chore: update quality badges

- Coverage: 84%
- Core coverage: 95%

[skip ci]

AGENTS.md

@@ -8,10 +8,10 @@ broad permissions inside a sandbox, so a misbehaving agent cannot reach the
 host. A Python CLI (entry point `cli.py`, package `bot_bottle/`) orchestrates
 the runtime lifecycle and the copying of skills and env vars into it.
 The default backend on compatible macOS hosts is macos-container:
-agents and sidecar bundles run through Apple's `container` CLI without
+agents and gateways run through Apple's `container` CLI without
 requiring Docker. On KVM-capable Linux hosts the default is firecracker:
 agents run in a Firecracker microVM reached over SSH on a point-to-point
-TAP, while the sidecar bundle still uses Docker. The legacy Docker
+TAP, while the gateway still uses Docker. The legacy Docker
 backend remains available with `BOT_BOTTLE_BACKEND=docker` or
 `--backend=docker`.
 
@@ -59,7 +59,7 @@ backend remains available with `BOT_BOTTLE_BACKEND=docker` or
   in a PRD, research note, or decision record.
 - Low dependencies by default. The project is Python, stdlib-first (no
   runtime pip dependencies in the package itself; the only language
-  runtime is the Python 3.13 used by the CLI + sidecars). Ask before
+  runtime is the Python 3.13 used by the CLI + companion containers). Ask before
   adding new tools, runtimes, or package managers.
 - Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/):
   `<type>[(scope)][!]: <description>`, where `<type>` is one of `feat`, `fix`,

Dockerfile.gateway

@@ -1,8 +1,15 @@
-# Per-bottle sidecar bundle image (PRD 0024).
+# Gateway data-plane image (PRD 0024 bundle shape; PRD 0070 gateway).
 #
-# Collapses the prior per-sidecar images (egress, git-gate,
+# The egress / git-gate / supervise *data plane* — one image, run by
+# the consolidated per-host gateway (PRD 0070). It is NOT the
+# orchestrator control plane: that is the separate, lean
+# `bot-bottle-orchestrator` image (Dockerfile.orchestrator, #384), which
+# ships only python + the stdlib-only `bot_bottle` package and none of
+# this image's mitmproxy / git / gitleaks payload.
+#
+# Collapses the prior per-daemon images (egress, git-gate,
 # supervise) into one. A small stdlib-Python init supervisor at
-# /app/sidecar_init.py spawns all daemons, forwards SIGTERM, and
+# /app/gateway_init.py spawns all daemons, forwards SIGTERM, and
 # propagates per-daemon stdout/stderr to the container log with a
 # `[name]` prefix. See PRD 0024 for the rationale.
 #
@@ -12,7 +19,7 @@
 #   /app/egress_addon.py + siblings      mitmproxy addon (egress)
 #   /app/egress-entrypoint.sh            mitmdump launcher
 #   /app/supervise_server.py + .py       supervise MCP server
-#   /app/sidecar_init.py                 PID 1 supervisor
+#   /app/gateway_init.py                 PID 1 supervisor
 #   /etc/egress/routes.yaml              bind-mounted at run time
 #   /etc/git-gate/pre-receive            docker-cp'd at start time
 #   /git-gate-entrypoint.sh              docker-cp'd at start time
@@ -64,8 +71,10 @@ COPY --from=gitleaks-src /usr/bin/gitleaks /usr/bin/gitleaks
 COPY bot_bottle/egress_addon_core.py /app/egress_addon_core.py
 COPY bot_bottle/egress_dlp_config.py /app/egress_dlp_config.py
 COPY bot_bottle/egress_addon.py      /app/egress_addon.py
+COPY bot_bottle/policy_resolver.py   /app/policy_resolver.py
 COPY bot_bottle/dlp_detectors.py     /app/dlp_detectors.py
 COPY bot_bottle/yaml_subset.py       /app/yaml_subset.py
+COPY bot_bottle/paths.py             /app/paths.py
 COPY bot_bottle/migrations.py        /app/migrations.py
 COPY bot_bottle/db_store.py          /app/db_store.py
 COPY bot_bottle/supervise_types.py   /app/supervise_types.py
@@ -74,7 +83,7 @@ COPY bot_bottle/audit_store.py       /app/audit_store.py
 COPY bot_bottle/store_manager.py     /app/store_manager.py
 COPY bot_bottle/supervise.py         /app/supervise.py
 COPY bot_bottle/supervise_server.py  /app/supervise_server.py
-COPY bot_bottle/sidecar_init.py      /app/sidecar_init.py
+COPY bot_bottle/gateway_init.py      /app/gateway_init.py
 COPY bot_bottle/git_http_backend.py  /app/git_http_backend.py
 COPY bot_bottle/egress_entrypoint.sh /app/egress-entrypoint.sh
 RUN chmod +x /app/egress-entrypoint.sh
@@ -100,4 +109,4 @@ WORKDIR /app
 
 # PID 1 is the supervisor. It owns signal handling and exit-code
 # propagation; no `exec` chain in the entrypoint itself.
-ENTRYPOINT ["python3", "/app/sidecar_init.py"]
+ENTRYPOINT ["python3", "/app/gateway_init.py"]

Dockerfile.orchestrator

@@ -0,0 +1,27 @@
+# Orchestrator control-plane image (PRD 0070, #384).
+#
+# The per-host orchestrator runs `python3 -m bot_bottle.orchestrator`.
+# The `bot_bottle` package is **stdlib-only** by design, so the control
+# plane needs nothing but a Python runtime — none of the gateway's
+# mitmproxy / git / gitleaks payload (that is the separate
+# `bot-bottle-gateway` image, Dockerfile.gateway). Splitting them keeps
+# the secret-dense control plane (it concentrates every bottle's egress
+# tokens — see PRD 0070's "secret concentration") on a minimal
+# dependency surface.
+#
+# The repo is bind-mounted read-only into the container at run time (see
+# `orchestrator/lifecycle.py`), so the source is NOT copied in here: the
+# image is just the runtime. `ensure_running` recreates the container
+# only when the bind-mounted source hash changes (#381), which is why
+# the code stays a mount rather than a baked layer.
+
+FROM python:3.12-slim
+
+# No third-party deps to install — stdlib only. Kept as an explicit,
+# self-documenting stage so a future confinement step (baking the
+# package, dropping the bind mount) has an obvious home.
+WORKDIR /app
+
+# Documentation only; lifecycle.py overrides the entrypoint to
+# `python3 -m bot_bottle.orchestrator` with the runtime flags.
+ENTRYPOINT ["python3", "-m", "bot_bottle.orchestrator"]

README.md

@@ -5,7 +5,7 @@
 # bot-bottle
 
 [![test](https://gitea.dideric.is/didericis/bot-bottle/actions/workflows/test.yml/badge.svg?branch=main)](https://gitea.dideric.is/didericis/bot-bottle/actions?workflow=test.yml)
-[![coverage](https://img.shields.io/badge/coverage-82%25-brightgreen)](https://coverage.readthedocs.io/)
+[![coverage](https://img.shields.io/badge/coverage-84%25-brightgreen)](https://coverage.readthedocs.io/)
 [![core coverage](https://img.shields.io/badge/core%20coverage-95%25-brightgreen)](https://gitea.dideric.is/didericis/bot-bottle/src/branch/main/docs/decisions/0004-coverage-policy.md)
 
 **Problem:** Developer wants to run a coding agent without supervision, but they don't want a prompt injected or misbehaving agent wrecking their environment or exfiltrating sensitive data.
@@ -16,7 +16,7 @@
 
 - **Per-bottle egress allowlist** — TLS-bumped HTTP/HTTPS chokepoint with a per-manifest host allowlist; per-route path/method/header `matches` filtering; outbound DLP scanning for known tokens and secrets, inbound DLP scanning for prompt-injection attempts; DoH and arbitrary hosts blocked by default.
 - **Per-route token-match policy** — each egress route picks what happens when the outbound DLP catches a token via `dlp.outbound_on_match`: `supervise` (default) holds the request and surfaces it in `./cli.py supervise` for approval (an approved value is remembered for the life of the proxy); `redact` scrubs the value and forwards; `block` is a hard `403`. Cuts false-positive friction without weakening default-deny.
-- **Tokens the agent never sees** — host secrets live in a sidecar; the agent dials `http://sidecar:9099/<path>` and the proxy strips inbound `Authorization` and injects the real token before forwarding. `printenv` in the agent shows proxy URLs only.
+- **Tokens the agent never sees** — host secrets live in a gateway; the agent dials `http://gateway:9099/<path>` and the proxy strips inbound `Authorization` and injects the real token before forwarding. `printenv` in the agent shows proxy URLs only.
 - **Gitleaks-scanned push (git-gate)** — `bottle.git` remotes route through a per-bottle `git daemon` that gitleaks-scans incoming refs pre-receive and forwards clean refs upstream over SSH. The agent never holds the upstream credential.
 - **Manifest-scoped skills + secrets** — each bottle declares its skills, env, git identity, remotes, and egress routes; unknown keys die at load.
 - **Trust boundary at `$HOME`** — bottles (credentials, egress, remotes) live only under `~/.bot-bottle/bottles/`. Repos may ship agents but not bottles, so a cloned repo can't redirect an env var to an attacker host.
@@ -24,17 +24,17 @@
 - **Parallel, isolated bottles** — each bottle runs in its own backend-owned isolation boundary; bottles don't share state or talk to each other.
 - **Provider templates (Claude, Codex)** — `Dockerfile.claude` / `Dockerfile.codex`, or a bottle-supplied Dockerfile. Claude auth via long-lived OAuth token; Codex via opt-in host device-auth forwarding.
 - **gVisor auto-detect** — on Linux hosts where `runsc` is registered with Docker, every bottle launches under it for a userspace syscall barrier; no manifest config required.
-- **Apple Container backend (macOS default when available)** — runs the agent and sidecar bundle with Apple's `container` CLI, using a host-only agent network plus a separate sidecar egress network.
+- **Apple Container backend (macOS default when available)** — runs the agent and gateway with Apple's `container` CLI, using a host-only agent network plus a separate gateway egress network.
-- **Firecracker backend (Linux default when available)** — runs the agent in a KVM Firecracker microVM reached over SSH on a point-to-point TAP, with the sidecar bundle in Docker. A dedicated, fail-closed `nftables` table isolates the guest, closing the raw DNS/IP exfiltration gap that exists in the legacy Docker backend. Requires KVM (`/dev/kvm`) and a one-time privileged network-pool setup.
+- **Firecracker backend (Linux default when available)** — runs the agent in a KVM Firecracker microVM reached over SSH on a point-to-point TAP, with the gateway in Docker. A dedicated, fail-closed `nftables` table isolates the guest, closing the raw DNS/IP exfiltration gap that exists in the legacy Docker backend. Requires KVM (`/dev/kvm`) and a one-time privileged network-pool setup.
 - **Legacy Docker backend** — still available for examples, CI, and hosts without Apple Container or KVM via `BOT_BOTTLE_BACKEND=docker` or `--backend=docker`.
 
 ## Architecture
 
-On the default macOS Apple Container backend, a bottle is an agent container on a host-only internal network plus a sidecar bundle attached to both that internal network and a NAT egress network. The agent gets HTTP(S)_PROXY and CA bundle env vars pointing at the sidecar's internal-network IP, so HTTP/HTTPS traffic flows through the sidecar instead of direct egress. `bottle.git` / git-gate is intentionally deferred on this backend until a safe Apple Container key-delivery path exists.
+On the default macOS Apple Container backend, a bottle is an agent container on a host-only internal network plus a gateway attached to both that internal network and a NAT egress network. The agent gets HTTP(S)_PROXY and CA bundle env vars pointing at the gateway's internal-network IP, so HTTP/HTTPS traffic flows through the gateway instead of direct egress. `bottle.git` / git-gate is intentionally deferred on this backend until a safe Apple Container key-delivery path exists.
 
-On the Firecracker backend, a bottle is an agent microVM plus a Docker sidecar bundle for egress, git-gate, and supervise. The VM reaches the sidecars over a per-bottle point-to-point TAP link; a dedicated fail-closed `nftables` table (`inet bot_bottle_fc`) confines the guest to that link, so nothing leaves the box except through the sidecars. The TAP pool and nft table are provisioned once (root); per-launch needs no privilege.
+On the Firecracker backend, a bottle is an agent microVM plus a Docker gateway for egress, git-gate, and supervise. The VM reaches the gateway over a per-bottle point-to-point TAP link; a dedicated fail-closed `nftables` table (`inet bot_bottle_fc`) confines the guest to that link, so nothing leaves the box except through the gateway. The TAP pool and nft table are provisioned once (root); per-launch needs no privilege.
 
-On the legacy Docker backend, the same logical bottle is two containers per agent: an `agent` container and a `sidecars` container. They share a per-agent Docker `--internal` network; the agent has no default route off-box.
+On the legacy Docker backend, the same logical bottle is two containers per agent: an `agent` container and a `companion containers` container. They share a per-agent Docker `--internal` network; the agent has no default route off-box.
 
 The Docker topology looks like this:
 
@@ -67,11 +67,11 @@ The Docker topology looks like this:
    └─────────────────────────────────────────────────────────────────────┘
 ```
 
-When the agent exits, `cli.py` tears down every sidecar and both networks; nothing about a bottle persists between runs.
+When the agent exits, `cli.py` tears down every gateway and both networks; nothing about a bottle persists between runs.
 
 ## Quickstart
 
-On compatible macOS hosts, the default backend requires Apple's `container` CLI and does not require Docker. The Firecracker backend (Linux) requires Docker on the host for the sidecar bundle plus the `firecracker` binary and KVM. The legacy Docker backend requires Docker. Claude bottles also need a long-lived Claude Code OAuth token (`claude setup-token`) exported as `BOT_BOTTLE_CLAUDE_OAUTH_TOKEN`.
+On compatible macOS hosts, the default backend requires Apple's `container` CLI and does not require Docker. The Firecracker backend (Linux) requires Docker on the host for the gateway plus the `firecracker` binary and KVM. The legacy Docker backend requires Docker. Claude bottles also need a long-lived Claude Code OAuth token (`claude setup-token`) exported as `BOT_BOTTLE_CLAUDE_OAUTH_TOKEN`.
 
 Use `BOT_BOTTLE_BACKEND=docker ./cli.py start <agent>` on hosts where neither Apple Container nor KVM is available and Docker is the desired backend.
 
@@ -81,7 +81,7 @@ On Linux, a KVM-capable host defaults to the Firecracker backend. It needs:
 
 - **`/dev/kvm`** present and accessible. Load `kvm-intel` or `kvm-amd` (and enable virtualization in BIOS/firmware). The invoking user must be in the `kvm` group: `sudo usermod -aG kvm "$USER"` then re-login. bot-bottle preflights this and reports exactly what's missing.
 - **`firecracker`** on `PATH`: grab a release from <https://github.com/firecracker-microvm/firecracker/releases>. Start flows print this pointer when the binary is missing.
-- **Docker** for the sidecar bundle and image build.
+- **Docker** for the gateway and image build.
 - **A one-time privileged network setup** — the per-bottle TAP pool plus the fail-closed `nftables` isolation table. Run `./cli.py backend setup --backend=firecracker` for the host-appropriate config (a NixOS module, a `sudo` script elsewhere); `./cli.py backend status --backend=firecracker` reports what's present, including whether the pool range collides with an existing route. The pool defaults to `10.243.0.0/16` (an obscure RFC-1918 block that dodges docker/libvirt/LAN and, deliberately, Tailscale's `100.64.0.0/10` CGNAT range); override with `BOT_BOTTLE_FC_IP_BASE` if it clashes on your host.
 
 ```sh

bot_bottle/agent_provider.py

@@ -204,9 +204,9 @@ class AgentProvider(ABC):
         bottle: "Bottle",
         supervise_url: str,
     ) -> None:
-        """Register the per-bottle supervise sidecar as an MCP server
+        """Register the per-bottle supervise daemon as an MCP server
         in the provider's in-guest config. Called by the backend after
-        the supervise sidecar is reachable. No-op when
+        the supervise daemon is reachable. No-op when
         `plan.supervise_plan is None`."""
 
     @abstractmethod

bot_bottle/audit_store.py

@@ -6,11 +6,13 @@ import sqlite3
 from pathlib import Path
 
 try:
-    from .supervise_types import AuditEntry, host_db_path
+    from .supervise_types import AuditEntry
+    from .paths import host_db_path
     from .db_store import DbStore
     from .migrations import TableMigrations
 except ImportError:
-    from supervise_types import AuditEntry, host_db_path  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+    from supervise_types import AuditEntry  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+    from paths import host_db_path  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
     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
 

bot_bottle/backend/__init__.py

@@ -199,7 +199,7 @@ class ActiveAgent:
     bottle is the container, the agent is what runs in it.)
 
     Fields are deliberately backend-neutral. `services` is the set
-    of sidecar daemons currently up for this bottle (`egress`,
+    of gateway daemons currently up for this bottle (`egress`,
     `git-gate`, `supervise`); the dashboard uses it to
     gate edit verbs. `backend_name` is the matching key in
     `_BACKENDS` (`docker` / `firecracker` / `macos-container`) — used by the active-
@@ -251,7 +251,7 @@ class Bottle(ABC):
         `user` (default `node`, matching the agent image's USER
         directive) and return the captured stdout/stderr/returncode.
         The bottle's environment (including HTTPS_PROXY pointing at
-        the egress sidecar) is inherited by the child. Non-zero
+        the egress daemon) is inherited by the child. Non-zero
         exit does not raise — callers inspect `returncode`
         themselves.
 
@@ -454,7 +454,7 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
         declarative provision-plan apply, supervise MCP registration)
         live on the `AgentProvider` plugin. The backend only owns the
         steps that are about backend infrastructure (CA, workspace,
-        git) and surfaces the supervise sidecar URL its launch step
+        git) and surfaces the supervise daemon URL its launch step
         knows about via `supervise_mcp_url`.
 
         PRD 0017: cred-proxy's agent-side dotfile rewrites (~/.npmrc,
@@ -502,7 +502,7 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
 
     def supervise_mcp_url(self, plan: PlanT) -> str:
         """Return the agent-side URL of the per-bottle supervise
-        sidecar, or "" when this bottle has no sidecar. The provider
+        gateway, or "" when this bottle has no gateway. The provider
         plugin's `provision_supervise_mcp` uses it to register the
         MCP entry inside the guest.
 
@@ -524,7 +524,7 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
     def enumerate_active(self) -> Sequence[ActiveAgent]:
         """Return every currently-running agent on this backend.
         Empty when none. Backend-specific: docker queries `docker
-        compose ls`; firecracker cross-references its running sidecar
+        compose ls`; firecracker cross-references its running gateway
         containers against per-bottle metadata."""
 
     @classmethod

bot_bottle/backend/docker/backend.py

@@ -106,11 +106,16 @@ class DockerBottleBackend(BottleBackend["DockerBottlePlan", "DockerBottleCleanup
             yield bottle
 
     def supervise_mcp_url(self, plan: DockerBottlePlan) -> str:
-        """Docker bottles reach the supervise sidecar via the
+        """Docker bottles reach the supervise daemon via the
         compose-network alias `supervise:9100`. No per-bottle URL
         plumbing needed; the alias resolves inside the bridge."""
         if plan.supervise_plan is None:
             return ""
+        # Consolidated: the supervise daemon lives on the shared gateway, so
+        # the agent registers the gateway address (NO_PROXY bypasses egress),
+        # not the per-bottle `supervise` alias.
+        if plan.agent_supervise_url:
+            return plan.agent_supervise_url
         return f"http://{SUPERVISE_HOSTNAME}:{SUPERVISE_PORT}/"
 
     def prepare_cleanup(self) -> DockerBottleCleanupPlan:

bot_bottle/backend/docker/bottle_plan.py

@@ -28,11 +28,30 @@ class DockerBottlePlan(BottlePlan):
     # accidental log of the plan dataclass.
     forwarded_env: dict[str, str] = field(repr=False)
     use_runsc: bool
+    # Consolidated mode (PRD 0070): the agent reaches git-gate over HTTP at the
+    # shared gateway's address (`http://<gateway_ip>:9420`), set at launch.
+    # Empty → single-tenant defaults (the `git-gate` alias over git://).
+    agent_git_gate_url: str = ""
+    # Likewise the supervise MCP endpoint at the gateway (`http://<gw>:9100/`);
+    # empty → the single-tenant `supervise` alias.
+    agent_supervise_url: str = ""
 
     @property
     def container_name(self) -> str:
         return self.agent_provision.instance_name
 
+    @property
+    def git_gate_insteadof_host(self) -> str:
+        if self.agent_git_gate_url.startswith("http://"):
+            return self.agent_git_gate_url.removeprefix("http://").rstrip("/")
+        return super().git_gate_insteadof_host
+
+    @property
+    def git_gate_insteadof_scheme(self) -> str:
+        if self.agent_git_gate_url.startswith("http://"):
+            return "http"
+        return super().git_gate_insteadof_scheme
+
     @property
     def image(self) -> str:
         return self.agent_provision.image

bot_bottle/backend/docker/cleanup.py

@@ -26,7 +26,7 @@ from __future__ import annotations
 import shutil
 import subprocess
 
-from ... import supervise as _supervise
+from ...paths import bot_bottle_root
 from ...log import info, warn
 from . import util as docker_mod
 from .bottle_cleanup_plan import DockerBottleCleanupPlan
@@ -94,7 +94,7 @@ def _list_orphan_state_dirs(
     ANY backend — used so this docker-side check doesn't reap a
     running non-docker bottle's state dir (the layout is shared
     across backends)."""
-    state_root = _supervise.bot_bottle_root() / "state"
+    state_root = bot_bottle_root() / "state"
     if not state_root.is_dir():
         return []
     orphans: list[str] = []

bot_bottle/backend/docker/compose.py

@@ -1,20 +1,10 @@
-"""Compose-spec rendering for a Docker bottle (PRD 0018, chunk 1).
+"""Docker compose lifecycle helpers (PRD 0018).
 
-`bottle_plan_to_compose(plan)` returns a Compose v2 spec dict
+Serialize a compose spec to disk, drive `docker compose up/down`,
-describing the per-bottle container topology — one project per
+dump the merged log on teardown, and enumerate `bot-bottle-*`
-bottle instance, services for the agent + every applicable sidecar,
+projects. The spec itself is built by `consolidated_compose.py`
-two networks, no named volumes.
+(the consolidated per-host gateway topology); this module owns the
-
+I/O side that persists and runs it.
-Pure function. No I/O, no subprocess. Expects every launch-time
-field (network names, CA host paths, etc.) on the plan's inner
-plans to be populated; chunks 2+3 own that ordering.
-
-Conditional services follow the plan content:
-
-  - agent + sidecars bundle: always.
-  - git-gate:  iff plan.git_gate_plan.upstreams.
-  - egress:    iff plan.egress_plan.routes.
-  - supervise: iff plan.supervise_plan is not None.
 """
 
 from __future__ import annotations
@@ -25,233 +15,7 @@ import sys
 from pathlib import Path
 from typing import Any
 
-from ...egress import (
-    EGRESS_HOSTNAME,
-    EGRESS_ROUTES_IN_CONTAINER,
-    egress_agent_env_entries,
-    egress_sidecar_env_entries,
-)
-from ...git_gate import GIT_GATE_HOSTNAME
 from ...log import die, warn
-from ...supervise import (
-    DB_PATH_IN_CONTAINER,
-    SUPERVISE_HOSTNAME,
-    SUPERVISE_PORT,
-)
-from ...util import expand_tilde
-from ..util import AGENT_CA_BUNDLE, AGENT_CA_PATH
-from .bottle_plan import DockerBottlePlan
-from .egress import (
-    EGRESS_CA_IN_CONTAINER,
-    EGRESS_PORT,
-)
-from .git_gate import (
-    GIT_GATE_ACCESS_HOOK_IN_CONTAINER,
-    GIT_GATE_CREDS_DIR_IN_CONTAINER,
-    GIT_GATE_ENTRYPOINT_IN_CONTAINER,
-    GIT_GATE_HOOK_IN_CONTAINER,
-)
-from . import network as network_mod
-from .sidecar_bundle import (
-    SIDECAR_BUNDLE_DOCKERFILE,
-    SIDECAR_BUNDLE_IMAGE,
-    sidecar_bundle_container_name,
-)
-
-
-# Repo root, used as the build context for the bundle Dockerfile.
-_REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)
-
-
-def bottle_plan_to_compose(plan: DockerBottlePlan) -> dict[str, Any]:
-    """Render a Compose v2 spec dict from a fully-resolved
-    DockerBottlePlan.
-
-    The plan must have its inner plans (`git_gate_plan`,
-    `egress_plan`, `supervise_plan`) populated with launch-time
-    fields — network names, CA host paths. The renderer doesn't
-    validate; callers feed it a fully-resolved plan or get an
-    incomplete compose spec back.
-    """
-    project = f"bot-bottle-{plan.slug}"
-    services: dict[str, Any] = {
-        "sidecars": _sidecar_bundle_service(plan),
-        "agent": _agent_service(plan),
-    }
-    return {
-        "name": project,
-        "services": services,
-        "networks": _networks(plan),
-    }
-
-
-def _networks(plan: DockerBottlePlan) -> dict[str, Any]:
-    """Compose-managed networks with explicit `name:` matching the
-    existing slug-suffixed convention. Compose creates them on `up`
-    and destroys them on `down`. The internal one is `--internal`
-    (no default gateway); the egress one is a normal user-defined
-    bridge."""
-    return {
-        "internal": {
-            "name": network_mod.network_name_for_slug(plan.slug),
-            "internal": True,
-        },
-        "egress": {
-            "name": network_mod.network_egress_name_for_slug(plan.slug),
-        },
-    }
-
-
-def _bind(host: str | Path, target: str, *, read_only: bool = True) -> dict[str, Any]:
-    """One bind-mount entry in the long-form `volumes:` shape.
-    Long form is preferred over `host:target:ro` strings because
-    it's easier to inspect in tests and survives whitespace in
-    host paths."""
-    return {
-        "type": "bind",
-        "source": str(host),
-        "target": target,
-        "read_only": read_only,
-    }
-
-
-def _sidecar_bundle_service(plan: DockerBottlePlan) -> dict[str, Any]:
-    """The `sidecars` service: one container per bottle, bundle
-    image, all daemons under a Python init supervisor.
-
-    Daemon subset narrows via `BOT_BOTTLE_SIDECAR_DAEMONS` env.
-    egress is always present; git-gate / supervise are conditional.
-    """
-    daemons: list[str] = ["egress"]
-    if plan.git_gate_plan.upstreams:
-        daemons.append("git-gate")
-    if plan.supervise_plan is not None:
-        daemons.append("supervise")
-
-    env: list[str] = [f"BOT_BOTTLE_SIDECAR_DAEMONS={','.join(daemons)}"]
-    volumes: list[dict[str, Any]] = []
-
-    # --- egress -------------------------------------------------------
-    ep = plan.egress_plan
-    volumes.append(_bind(ep.mitmproxy_ca_host_path, EGRESS_CA_IN_CONTAINER))
-    if ep.routes:
-        volumes.append(_bind(ep.routes_path.parent, str(Path(EGRESS_ROUTES_IN_CONTAINER).parent)))
-    env.extend(egress_sidecar_env_entries(ep))
-
-    # --- git-gate -----------------------------------------------------
-    gp = plan.git_gate_plan
-    if gp.upstreams:
-        volumes += [
-            _bind(gp.entrypoint_script, GIT_GATE_ENTRYPOINT_IN_CONTAINER),
-            _bind(gp.hook_script, GIT_GATE_HOOK_IN_CONTAINER),
-            _bind(gp.access_hook_script, GIT_GATE_ACCESS_HOOK_IN_CONTAINER),
-        ]
-        for u in gp.upstreams:
-            keypath = expand_tilde(u.identity_file)
-            volumes.append(_bind(
-                keypath,
-                f"{GIT_GATE_CREDS_DIR_IN_CONTAINER}/{u.name}-key",
-            ))
-            if u.known_hosts_file:
-                volumes.append(_bind(
-                    u.known_hosts_file,
-                    f"{GIT_GATE_CREDS_DIR_IN_CONTAINER}/{u.name}-known_hosts",
-                ))
-
-    # --- supervise ----------------------------------------------------
-    sp = plan.supervise_plan
-    if sp is not None:
-        env += [
-            f"SUPERVISE_BOTTLE_SLUG={plan.slug}",
-            f"SUPERVISE_DB_PATH={DB_PATH_IN_CONTAINER}",
-            f"SUPERVISE_PORT={SUPERVISE_PORT}",
-        ]
-        volumes.append({
-            "type": "bind",
-            "source": str(sp.db_path),
-            "target": DB_PATH_IN_CONTAINER,
-            "read_only": False,
-        })
-    internal_aliases = [EGRESS_HOSTNAME]
-    if gp.upstreams:
-        internal_aliases.append(GIT_GATE_HOSTNAME)
-    if sp is not None:
-        internal_aliases.append(SUPERVISE_HOSTNAME)
-
-    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},
-            "egress": None,
-        },
-        "environment": env,
-        "volumes": volumes,
-    }
-    return service
-
-
-def _agent_service(plan: DockerBottlePlan) -> dict[str, Any]:
-    """Agent container. Runs `sleep infinity`; claude is `docker
-    exec -it`'d into it later. HTTP_PROXY/HTTPS_PROXY point at the
-    egress sidecar."""
-    proxy_url = _agent_proxy_url(plan)
-    no_proxy = _agent_no_proxy(plan)
-    env: list[str] = [
-        f"HTTPS_PROXY={proxy_url}",
-        f"HTTP_PROXY={proxy_url}",
-        f"https_proxy={proxy_url}",
-        f"http_proxy={proxy_url}",
-        f"NO_PROXY={no_proxy}",
-        f"no_proxy={no_proxy}",
-        f"NODE_EXTRA_CA_CERTS={AGENT_CA_PATH}",
-        f"SSL_CERT_FILE={AGENT_CA_BUNDLE}",
-        f"REQUESTS_CA_BUNDLE={AGENT_CA_BUNDLE}",
-    ]
-    for name, value in sorted(plan.agent_provision.guest_env.items()):
-        env.append(f"{name}={value}")
-    # Forwarded vars (OAuth token, manifest host-interpolations):
-    # bare name → inherits from compose-up process env, value
-    # never lands on argv or in the compose file.
-    for name in sorted(plan.forwarded_env.keys()):
-        env.append(name)
-    env.extend(egress_agent_env_entries(plan.egress_plan))
-
-    service: dict[str, Any] = {
-        "image": plan.image,
-        "container_name": plan.container_name,
-        "command": ["sleep", "infinity"],
-        "networks": {"internal": None},
-        "environment": env,
-    }
-    if plan.use_runsc:
-        service["runtime"] = "runsc"
-
-    # The init supervisor inside the bundle owns intra-bundle
-    # daemon ordering, so the agent only waits for the bundle
-    # container itself.
-    service["depends_on"] = ["sidecars"]
-
-    return service
-
-
-def _agent_proxy_url(plan: DockerBottlePlan) -> str:
-    """Agent's HTTP_PROXY — always points at egress."""
-    return f"http://{EGRESS_HOSTNAME}:{EGRESS_PORT}"
-
-
-def _agent_no_proxy(plan: DockerBottlePlan) -> str:
-    """NO_PROXY for the agent: loopback always; supervise hostname
-    when the supervise sidecar is up (MCP long-poll must bypass
-    the egress proxy)."""
-    hosts = ["localhost", "127.0.0.1"]
-    if plan.supervise_plan is not None:
-        hosts.append(SUPERVISE_HOSTNAME)
-    return ",".join(hosts)
 
 
 # --- Lifecycle helpers (PRD 0018 chunk 3) ----------------------------------
@@ -442,7 +206,6 @@ __all__ = [
     "COMPOSE_FILE_NAME",
     "COMPOSE_LOG_NAME",
     "COMPOSE_PROJECT_PREFIX",
-    "bottle_plan_to_compose",
     "compose_down",
     "compose_dump_logs",
     "compose_file_path",

bot_bottle/backend/docker/consolidated_compose.py

@@ -0,0 +1,78 @@
+"""Agent-only compose for the consolidated docker backend (PRD 0070).
+
+The per-bottle model rendered a compose project with the agent *and* a
+gateway on two per-bottle networks. In the consolidated model the
+per-bottle companion containers are gone — one shared gateway serves every bottle — so this renders
+just the agent, attached to the **external shared gateway network** with the
+pinned source IP the orchestrator allocated, and pointed at the gateway's
+address for egress (and, around the proxy, for git-http / supervise).
+
+Pure: it takes the launch-time `LaunchContext` values (gateway address,
+source IP, network) and the prepared plan, and returns a compose dict — no
+docker, so it's testable in isolation.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...egress import egress_agent_env_entries
+from ..util import AGENT_CA_BUNDLE, AGENT_CA_PATH
+from .bottle_plan import DockerBottlePlan
+from .egress import EGRESS_PORT
+
+
+def consolidated_agent_compose(
+    plan: DockerBottlePlan,
+    *,
+    gateway_ip: str,
+    source_ip: str,
+    network: str,
+) -> dict[str, Any]:
+    """A compose spec with only the agent service, on the external gateway
+    network at `source_ip`, proxying egress through `gateway_ip`."""
+    proxy_url = f"http://{gateway_ip}:{EGRESS_PORT}"
+    # git-http + supervise live on the gateway too and must NOT go through the
+    # egress proxy — the agent reaches them directly by the gateway address.
+    no_proxy = f"localhost,127.0.0.1,{gateway_ip}"
+    env: list[str] = [
+        f"HTTPS_PROXY={proxy_url}",
+        f"HTTP_PROXY={proxy_url}",
+        f"https_proxy={proxy_url}",
+        f"http_proxy={proxy_url}",
+        f"NO_PROXY={no_proxy}",
+        f"no_proxy={no_proxy}",
+        f"NODE_EXTRA_CA_CERTS={AGENT_CA_PATH}",
+        f"SSL_CERT_FILE={AGENT_CA_BUNDLE}",
+        f"REQUESTS_CA_BUNDLE={AGENT_CA_BUNDLE}",
+    ]
+    for name, value in sorted(plan.agent_provision.guest_env.items()):
+        env.append(f"{name}={value}")
+    # Forwarded vars: bare name → inherits from the compose-up process env so
+    # the secret value never lands on argv or in the compose file.
+    for name in sorted(plan.forwarded_env.keys()):
+        env.append(name)
+    env.extend(egress_agent_env_entries(plan.egress_plan))
+
+    service: dict[str, Any] = {
+        "image": plan.image,
+        "container_name": plan.container_name,
+        "command": ["sleep", "infinity"],
+        # Pinned address on the shared gateway network — the orchestrator
+        # registered this IP, and the gateway attributes the bottle by it.
+        "networks": {network: {"ipv4_address": source_ip}},
+        "environment": env,
+    }
+    if plan.use_runsc:
+        service["runtime"] = "runsc"
+
+    return {
+        "name": f"bot-bottle-{plan.slug}",
+        "services": {"agent": service},
+        # The gateway network is created + owned by the orchestrator; compose
+        # attaches to it (external) and must not create or destroy it.
+        "networks": {network: {"external": True}},
+    }
+
+
+__all__ = ["consolidated_agent_compose"]

bot_bottle/backend/docker/consolidated_launch.py

@@ -0,0 +1,153 @@
+"""Consolidated bottle launch sequence for the docker backend (PRD 0070).
+
+Composes the orchestrator primitives into the register/teardown sequence that
+replaces the per-bottle gateway:
+
+  1. ensure the orchestrator control plane + shared gateway are up;
+  2. allocate the bottle a pinned source IP on the gateway network (the
+     attribution key), skipping the gateway's own address + live bottles;
+  3. register it (egress policy blob + slug metadata) → bottle id + identity
+     token;
+  4. provision its git-gate repos/creds into the running gateway.
+
+It returns a `LaunchContext` with everything the agent container needs to
+attach — network, pinned IP, the gateway's address (its proxy target), the
+orchestrator URL, and the identity token. The agent `docker run` itself is
+the backend's job (it owns provider provisioning); this owns the
+orchestrator-facing wiring so that sequence stays testable in isolation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...docker_cmd import run_docker
+from ...egress import EgressPlan
+from ...git_gate import GitGatePlan
+from ...orchestrator.client import OrchestratorClient
+from ...orchestrator.gateway import GATEWAY_NAME, GATEWAY_NETWORK
+from ...orchestrator.lifecycle import OrchestratorService
+from ...orchestrator.registration import registration_inputs
+from .gateway_net import next_free_ip
+from .gateway_provision import deprovision_git_gate, provision_git_gate
+
+
+class ConsolidatedLaunchError(RuntimeError):
+    """The consolidated register/provision sequence could not complete."""
+
+
+@dataclass(frozen=True)
+class LaunchContext:
+    """What the agent container needs to join the shared gateway."""
+
+    bottle_id: str
+    identity_token: str
+    source_ip: str          # the agent's pinned address (attribution key)
+    network: str            # the shared gateway network to attach to
+    gateway_ip: str         # the gateway's address — the agent's proxy target
+    orchestrator_url: str
+
+
+def _network_cidr(network: str) -> str:
+    """The gateway network's IPv4 subnet, or raise."""
+    proc = run_docker([
+        "docker", "network", "inspect",
+        "--format", "{{range .IPAM.Config}}{{.Subnet}}{{end}}", network,
+    ])
+    cidr = proc.stdout.strip()
+    if proc.returncode != 0 or not cidr:
+        raise ConsolidatedLaunchError(
+            f"gateway network {network} has no subnet: {proc.stderr.strip()}"
+        )
+    return cidr
+
+
+def _container_ip(name: str, network: str) -> str:
+    """A container's IPv4 address on `network`, or raise."""
+    proc = run_docker([
+        "docker", "inspect", "--format",
+        f'{{{{(index .NetworkSettings.Networks "{network}").IPAddress}}}}', name,
+    ])
+    ip = proc.stdout.strip()
+    if proc.returncode != 0 or not ip:
+        raise ConsolidatedLaunchError(
+            f"gateway {name} has no address on {network}: {proc.stderr.strip()}"
+        )
+    return ip
+
+
+def _network_container_ips(network: str) -> list[str]:
+    """Every address currently assigned on the gateway network — the ground
+    truth for "in use": the gateway + orchestrator infrastructure containers
+    and every live agent. Read from the network so a new bottle can't collide
+    with anything actually attached (a registry-only view would miss the
+    orchestrator/gateway containers)."""
+    proc = run_docker([
+        "docker", "network", "inspect", "--format",
+        "{{range .Containers}}{{.IPv4Address}} {{end}}", network,
+    ])
+    ips: list[str] = []
+    for entry in proc.stdout.split():
+        # entries look like "172.20.0.2/16" — keep the address.
+        ips.append(entry.split("/", 1)[0])
+    return ips
+
+
+def launch_consolidated(
+    egress_plan: EgressPlan,
+    git_gate_plan: GitGatePlan,
+    *,
+    image_ref: str = "",
+    tokens: dict[str, str] | None = None,
+    service: OrchestratorService | None = None,
+    gateway_name: str = GATEWAY_NAME,
+    network: str = GATEWAY_NETWORK,
+) -> LaunchContext:
+    """Ensure the orchestrator + gateway are up, allocate + register the
+    bottle, and provision its git-gate state. Returns the agent's attach
+    context. Raises `ConsolidatedLaunchError` (or the primitives' own errors)
+    if any step fails — the caller tears down on failure."""
+    service = service or OrchestratorService()
+    url = service.ensure_running()
+    client = OrchestratorClient(url)
+
+    cidr = _network_cidr(network)
+    gateway_ip = _container_ip(gateway_name, network)
+    source_ip = next_free_ip(cidr, _network_container_ips(network))
+
+    inputs = registration_inputs(egress_plan)
+    reg = client.register_bottle(
+        source_ip, image_ref=image_ref, policy=inputs.policy,
+        metadata=inputs.metadata, tokens=tokens,
+    )
+    try:
+        provision_git_gate(gateway_name, reg.bottle_id, git_gate_plan)
+    except Exception:
+        # Roll the registration back so a provisioning failure leaves no orphan.
+        client.teardown_bottle(reg.bottle_id)
+        raise
+    return LaunchContext(
+        bottle_id=reg.bottle_id,
+        identity_token=reg.identity_token,
+        source_ip=source_ip,
+        network=network,
+        gateway_ip=gateway_ip,
+        orchestrator_url=url,
+    )
+
+
+def teardown_consolidated(
+    bottle_id: str, *, orchestrator_url: str, gateway_name: str = GATEWAY_NAME,
+) -> None:
+    """Deregister the bottle and remove its git-gate state from the gateway.
+    Both steps are idempotent so this is safe from a cleanup trap."""
+    OrchestratorClient(orchestrator_url).teardown_bottle(bottle_id)
+    deprovision_git_gate(gateway_name, bottle_id)
+
+
+__all__ = [
+    "LaunchContext",
+    "launch_consolidated",
+    "teardown_consolidated",
+    "ConsolidatedLaunchError",
+]

bot_bottle/backend/docker/egress.py

@@ -4,7 +4,7 @@ prepare-time routes-yaml rendering itself lives on the
 platform-neutral `Egress` ABC — backends instantiate it directly.
 
 The per-container `.start()` / `.stop()` lifecycle was removed in
-PRD 0024 chunk 3; the sidecar bundle (PRD 0024) runs egress
+PRD 0024 chunk 3; the gateway (PRD 0024) runs egress
 under its python init supervisor."""
 
 from __future__ import annotations

bot_bottle/backend/docker/egress_apply.py

@@ -1,60 +1,29 @@
-"""Host-side helper for egress sidecar inspection and live updates.
+"""Host-side egress route-apply for the docker backend.
 
-The approve path uses this module to validate a proposed routes file,
+The per-bottle companion container this used to signal (`docker kill
-write it to the bottle's live egress state dir, and signal the sidecar
+--signal HUP <container>`) was removed in the companion-container removal (#385).
-bundle so the mitmproxy addon reloads it.
+In the consolidated model the shared gateway resolves egress policy
+per-request against the orchestrator rather than reloading a per-bottle
+routes file, so the live per-bottle reload is not supported here and
+fails closed until the gateway-side apply lands.
 """
 
 from __future__ import annotations
 
-import os
-import subprocess
-
-from ...egress import EGRESS_ROUTES_IN_CONTAINER
-from ...log import warn
 from ..egress_apply import EgressApplicator, EgressApplyError
-from .sidecar_bundle import sidecar_bundle_container_name
-
-
-def fetch_current_routes(slug: str) -> str:
-    container = sidecar_bundle_container_name(slug)
-    r = subprocess.run(
-        ["docker", "exec", container, "cat", EGRESS_ROUTES_IN_CONTAINER],
-        capture_output=True, text=True, check=False,
-    )
-    if r.returncode != 0:
-        raise EgressApplyError(
-            f"could not read routes.yaml from {container}: "
-            f"{(r.stderr or '').strip() or 'container not running?'}"
-        )
-    return r.stdout
 
 
 class DockerEgressApplicator(EgressApplicator):
     def _signal_bundle_reload(self, slug: str) -> None:
-        container = sidecar_bundle_container_name(slug)
+        del slug
-        result = subprocess.run(
+        raise EgressApplyError(
-            ["docker", "kill", "--signal", "HUP", container],
+            "live egress route-apply was removed with the per-bottle "
-            capture_output=True, text=True, check=False, env=os.environ,
+            "companion container (#385); route changes will flow through "
+            "the consolidated gateway in a follow-up."
         )
-        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 'docker kill failed'}"
-            )
-            raise EgressApplyError(
-                f"could not reload egress bundle {container}: "
-                f"{last_error or 'docker kill failed'}"
-            )
 
 
 applicator = DockerEgressApplicator()
 
 
-__all__ = [
+__all__ = ["DockerEgressApplicator", "EgressApplyError", "applicator"]
-    "DockerEgressApplicator",
-    "EgressApplyError",
-    "applicator",
-    "fetch_current_routes",
-]

bot_bottle/backend/docker/gateway_net.py

@@ -0,0 +1,47 @@
+"""Shared-gateway source-IP allocation for the consolidated docker backend
+(PRD 0070).
+
+In the consolidated model one gateway container serves every bottle over a
+single shared docker network, and each agent bottle attaches with a pinned,
+deterministic address that the gateway uses as its **attribution key**. This
+allocates those addresses from the network's subnet, skipping the reserved
+ones — the network address and broadcast (excluded by `hosts()`), docker's
+router `.1`, and everything already in use (`taken`: the gateway container
+plus every live bottle, which the caller reads from the registry).
+
+Pure `ipaddress` logic — the docker-specific bits (the subnet CIDR, the
+gateway container's own address) are gathered by the caller and passed in, so
+this stays testable without docker.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from collections.abc import Iterable
+
+
+class NoFreeAddressError(RuntimeError):
+    """The shared gateway network's subnet is exhausted — every host address
+    is reserved or already assigned to a bottle."""
+
+
+def next_free_ip(cidr: str, taken: Iterable[str]) -> str:
+    """The lowest host address in `cidr` not in `taken` and not docker's
+    router (`.1`). `taken` must include the gateway container's own address
+    and every live bottle's. Raises `NoFreeAddressError` if the subnet is
+    full."""
+    net = ipaddress.ip_network(cidr, strict=False)
+    reserved = {str(a) for a in taken}
+    # Docker assigns the network's first host (.1) to the bridge router; a
+    # bottle must never be handed that address.
+    reserved.add(str(net.network_address + 1))
+    for host in net.hosts():  # hosts() already excludes network + broadcast
+        candidate = str(host)
+        if candidate not in reserved:
+            return candidate
+    raise NoFreeAddressError(
+        f"no free address in {cidr} ({len(reserved)} reserved/assigned)"
+    )
+
+
+__all__ = ["next_free_ip", "NoFreeAddressError"]

bot_bottle/backend/docker/gateway_provision.py

@@ -0,0 +1,100 @@
+"""Provision one bottle's git-gate state into the running shared gateway
+(PRD 0070, docker slice).
+
+The consolidated gateway serves every bottle's repos under `/git/<bottle_id>/`
+with per-repo credentials under `/git-gate/creds/<bottle_id>/`. When a bottle
+is registered the launcher must place *its* deploy keys + known_hosts into
+that per-bottle creds dir and init its bare repos there — so this copies the
+credential files into the live gateway container and runs the (namespaced,
+init-only) provisioning script produced by `git_gate_render_provision`.
+
+Isolating each bottle's creds dir + repo root by id is what keeps one
+bottle's push credentials out of another's repos on the shared gateway.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ...docker_cmd import run_docker
+from ...git_gate import GitGatePlan, git_gate_render_provision
+
+# bottle ids index the gateway's per-bottle repo + creds dirs; they land in
+# `docker cp`/`rm` path arguments, so validate before any path is built (a
+# traversal id like "../etc" must never reach the container). Registry ids are
+# token_hex — this is defense in depth at the docker boundary.
+_SAFE_BOTTLE_ID = re.compile(r"[A-Za-z0-9_-]+")
+
+
+class GatewayProvisionError(RuntimeError):
+    """A git-gate provisioning step against the running gateway failed."""
+
+
+def _require_safe(bottle_id: str) -> None:
+    if not _SAFE_BOTTLE_ID.fullmatch(bottle_id):
+        raise GatewayProvisionError(f"unsafe bottle id {bottle_id!r}")
+
+
+def _creds_dir(bottle_id: str) -> str:
+    return f"/git-gate/creds/{bottle_id}"
+
+
+def _exec(gateway: str, argv: list[str]) -> None:
+    """`docker exec` a command in the gateway, raising on non-zero exit."""
+    proc = run_docker(["docker", "exec", gateway, *argv])
+    if proc.returncode != 0:
+        raise GatewayProvisionError(
+            f"gateway exec {argv!r} failed: {proc.stderr.strip()}"
+        )
+
+
+def _cp_into(gateway: str, src: str, dest: str) -> None:
+    """`docker cp` a host file into the gateway, raising on non-zero exit."""
+    proc = run_docker(["docker", "cp", src, f"{gateway}:{dest}"])
+    if proc.returncode != 0:
+        raise GatewayProvisionError(
+            f"gateway cp {src} -> {dest} failed: {proc.stderr.strip()}"
+        )
+
+
+def provision_git_gate(gateway: str, bottle_id: str, plan: GitGatePlan) -> None:
+    """Place `bottle_id`'s git-gate credentials into the running `gateway`
+    container and init its bare repos under `/git/<bottle_id>/`.
+
+    Copies each upstream's identity key (and known_hosts, when present) into
+    `/git-gate/creds/<bottle_id>/`, then runs the namespaced provisioning
+    script. No-op for a bottle with no git upstreams."""
+    _require_safe(bottle_id)
+    if not plan.upstreams:
+        return
+    # The pre-receive + access hooks are bottle-agnostic and shared by every
+    # bottle's repos; install them into the gateway (idempotent — same content
+    # each time). The per-bottle model cp'd these into each bundle at start.
+    _exec(gateway, ["mkdir", "-p", "/etc/git-gate"])
+    _cp_into(gateway, str(plan.hook_script), "/etc/git-gate/pre-receive")
+    _cp_into(gateway, str(plan.access_hook_script), "/etc/git-gate/access-hook")
+    creds = _creds_dir(bottle_id)
+    _exec(gateway, ["mkdir", "-p", creds])
+    for u in plan.upstreams:
+        if u.identity_file:
+            _cp_into(gateway, u.identity_file, f"{creds}/{u.name}-key")
+        known_hosts = str(u.known_hosts_file)
+        if known_hosts and known_hosts != ".":
+            _cp_into(gateway, known_hosts, f"{creds}/{u.name}-known_hosts")
+    # Init the bare repos + per-repo credential config for this namespace.
+    script = git_gate_render_provision(bottle_id, plan.upstreams)
+    _exec(gateway, ["sh", "-c", script])
+
+
+def deprovision_git_gate(gateway: str, bottle_id: str) -> None:
+    """Remove a bottle's repos + creds from the gateway on teardown. Idempotent
+    — an already-absent namespace is a clean no-op (best effort; a stray dir
+    can't leak, since attribution is by source IP and the bottle is gone)."""
+    _require_safe(bottle_id)
+    run_docker([
+        "docker", "exec", gateway, "rm", "-rf",
+        f"/git/{bottle_id}", _creds_dir(bottle_id),
+    ])
+
+
+__all__ = ["provision_git_gate", "deprovision_git_gate", "GatewayProvisionError"]

bot_bottle/backend/docker/git_gate.py

@@ -2,7 +2,7 @@
 bind-mounts target + the listening port. The prepare-time entrypoint
 / hook render lives on the platform-neutral `GitGate` ABC — backends
 instantiate it directly. The git-gate daemon's container lifecycle
-is owned by the sidecar bundle (PRD 0024)."""
+is owned by the gateway (PRD 0024)."""
 
 from __future__ import annotations
 

bot_bottle/backend/docker/launch.py

@@ -5,7 +5,7 @@ PRD 0018 chunk 3: each instance is one `docker compose` project.
 The flow is:
 
   1. Build the agent image from the provider Dockerfile (compose
-     builds the sidecar images via the `build:` directive on first up).
+     builds the gateway image on first up).
   2. Mint the per-bottle egress CA (chunk 2 writes it under
      state/<slug>/egress/).
   3. Populate the inner plans with launch-time fields so the
@@ -42,7 +42,6 @@ from ...git_gate import (
     revoke_git_gate_provisioned_keys,
 )
 from ...log import info, warn
-from . import network as network_mod
 from . import util as docker_mod
 from .bottle import DockerBottle
 from .bottle_plan import DockerBottlePlan
@@ -53,7 +52,6 @@ from ...bottle_state import (
     read_committed_image,
 )
 from .compose import (
-    bottle_plan_to_compose,
     compose_down,
     compose_dump_logs,
     compose_file_path,
@@ -62,7 +60,9 @@ from .compose import (
     compose_up,
     write_compose_file,
 )
-from .egress import egress_tls_init
+from .consolidated_compose import consolidated_agent_compose
+from .consolidated_launch import launch_consolidated, teardown_consolidated
+from ...orchestrator.gateway import DockerGateway
 
 
 # Where the repo root lives, for `docker build` context. Computed once.
@@ -97,8 +97,7 @@ 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
+        # Dockerfile. (The gateway image is built by the orchestrator.)
-        # 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}")
@@ -112,82 +111,82 @@ def launch(
                 dockerfile=plan.dockerfile_path,
             )
 
-        internal_network = network_mod.network_name_for_slug(plan.slug)
+        # Step 2: mint the git-gate dynamic (gitea) deploy keys, if any, before
-        egress_network = network_mod.network_egress_name_for_slug(plan.slug)
+        # provisioning the bottle's repos into the shared gateway.
-
-        egress_ca_host, egress_ca_cert_only = egress_tls_init(
-            egress_state_dir(plan.slug),
-        )
-
         git_gate_plan = plan.git_gate_plan
         if git_gate_plan.upstreams:
             git_gate_plan = provision_git_gate_dynamic_keys(
-                plan.manifest.bottle,
+                plan.manifest.bottle, git_gate_plan, git_gate_state_dir(plan.slug),
-                git_gate_plan,
-                git_gate_state_dir(plan.slug),
-            )
-            git_gate_plan = dataclasses.replace(
-                git_gate_plan,
-                internal_network=internal_network,
-                egress_network=egress_network,
             )
+
+        # Step 3: register on the orchestrator + provision this bottle's
+        # git-gate state into the shared gateway; get the agent's attach
+        # context (pinned source IP, gateway address, shared network). The
+        # per-bottle egress auth tokens are resolved from the host env now and
+        # handed to the orchestrator (in memory) for the gateway to inject —
+        # the agent never sees them.
+        effective_env = {**os.environ, **plan.agent_provision.provisioned_env}
+        token_values = egress_resolve_token_values(
+            plan.egress_plan.token_env_map, effective_env,
+        )
+        ctx = launch_consolidated(
+            plan.egress_plan, git_gate_plan, image_ref=plan.image, tokens=token_values,
+        )
+        stack.callback(
+            teardown_consolidated, ctx.bottle_id, orchestrator_url=ctx.orchestrator_url,
+        )
+
+        # Step 4: install the SHARED gateway CA into the agent (replaces the
+        # per-bottle CA) — read it out of the running gateway.
+        ca_dir = egress_state_dir(plan.slug) / "gateway-ca"
+        ca_dir.mkdir(parents=True, exist_ok=True)
+        ca_file = ca_dir / "gateway-ca.pem"
+        ca_file.write_text(DockerGateway(network=ctx.network).ca_cert_pem())
         egress_plan = dataclasses.replace(
             plan.egress_plan,
-            internal_network=internal_network,
+            mitmproxy_ca_host_path=ca_file,
-            egress_network=egress_network,
+            mitmproxy_ca_cert_only_host_path=ca_file,
-            mitmproxy_ca_host_path=egress_ca_host,
+        )
-            mitmproxy_ca_cert_only_host_path=egress_ca_cert_only,
+        # Point the agent's git-gate insteadOf rewrites at the shared gateway's
+        # HTTP git endpoint (9420) instead of the dead per-bottle `git-gate`
+        # alias. git-http + supervise on the gateway bypass the egress proxy
+        # (NO_PROXY includes the gateway address).
+        git_gate_url = (
+            f"http://{ctx.gateway_ip}:9420" if git_gate_plan.upstreams else ""
+        )
+        supervise_url = (
+            f"http://{ctx.gateway_ip}:9100/" if plan.supervise_plan is not None else ""
         )
-        supervise_plan = plan.supervise_plan
-        if supervise_plan is not None:
-            supervise_plan = dataclasses.replace(
-                supervise_plan,
-                internal_network=internal_network,
-            )
         plan = dataclasses.replace(
             plan,
             git_gate_plan=git_gate_plan,
             egress_plan=egress_plan,
-            supervise_plan=supervise_plan,
+            agent_git_gate_url=git_gate_url,
+            agent_supervise_url=supervise_url,
         )
 
-        # Step 6: render + write the compose file. metadata.json
+        # Step 5: render + up the agent-only compose, pinned on the shared
-        # was written at prepare time and already carries
+        # gateway network and proxied through the gateway's address.
-        # compose_project; nothing to update here.
         state_dir = bottle_state_dir(plan.slug)
-        spec = bottle_plan_to_compose(plan)
+        spec = consolidated_agent_compose(
+            plan, gateway_ip=ctx.gateway_ip, source_ip=ctx.source_ip, network=ctx.network,
+        )
         compose_file = write_compose_file(spec, compose_file_path(state_dir))
         project = compose_project_name(plan.slug)
-
+        # Forwarded vars (OAuth token, host interpolations) flow through the
-        # Step 7: compose up. Token values + the OAuth placeholder
+        # subprocess env as bare names so values never land in the file.
-        # flow through subprocess env; the compose file holds only
+        compose_env: dict[str, str] = {**os.environ, **plan.forwarded_env}
-        # bare names for the secret-carrying entries.
-        effective_env = {**dict(os.environ), **plan.agent_provision.provisioned_env}
-        token_values = egress_resolve_token_values(
-            plan.egress_plan.token_env_map, effective_env,
-        )
-        compose_env: dict[str, str] = {
-            **os.environ,
-            **plan.forwarded_env,
-            **token_values,
-        }
         info(
-            f"docker compose up -d  (project {project}, "
+            f"docker compose up -d  (project {project}, agent on shared "
-            f"{len(spec['services'])} services)"
+            f"gateway {ctx.gateway_ip}, ip {ctx.source_ip})"
         )
         compose_up(project, compose_file, env=compose_env)
-
-        # Register teardown in reverse order: log dump first, then
-        # `compose down`. Networks come down last via callbacks
-        # registered in step 2.
         stack.callback(compose_down, project, compose_file)
         stack.callback(
             compose_dump_logs, project, compose_file, compose_log_path(state_dir),
         )
 
-        # Step 8: provision. Create the bottle first so provisioners
+        # Step 6: provision (CA install now uses the gateway CA) + yield.
-        # can use bottle.exec / bottle.cp_in; set the prompt path
-        # returned by provision_prompt after the fact.
         bottle = DockerBottle(
             plan.container_name,
             teardown,
@@ -200,10 +199,6 @@ def launch(
             agent_workdir=plan.workspace_plan.workdir,
         )
         bottle.prompt_path = provision(plan, bottle)
-
-        # Step 9: yield. exec_agent continues to use `docker exec -it`
-        # — the agent runs `sleep infinity` per the renderer's
-        # service spec.
         yield bottle
     finally:
         teardown()

bot_bottle/backend/docker/network.py

@@ -76,7 +76,7 @@ def network_create_internal(slug: str) -> str:
 
 def network_create_egress(slug: str) -> str:
     """Create a per-agent user-defined bridge (NOT the legacy `bridge`)
-    so the egress sidecar has working DNS for upstream hostnames."""
+    so the egress daemon has working DNS for upstream hostnames."""
     return _network_create_with_prefix(network_egress_name_for_slug(slug), internal=False)
 
 

bot_bottle/backend/docker/setup.py

@@ -1,7 +1,7 @@
 """Host setup + status for the Docker backend.
 
 Unlike Firecracker, the Docker backend needs no privileged one-time
-host provisioning (no TAP pool / nft table) — networks and the sidecar
+host provisioning (no TAP pool / nft table) — networks and the gateway
 bundle are created per-launch. So `setup()` is mostly an install/daemon
 pointer, and `status()` reports whether docker is usable.
 
@@ -45,7 +45,7 @@ def setup() -> int:
         return 1
     sys.stderr.write(
         "Docker backend: no privileged host setup required — networks and "
-        "the sidecar bundle are created per-launch.\n"
+        "the gateway are created per-launch.\n"
     )
     if not _daemon_reachable():
         sys.stderr.write(
@@ -64,7 +64,7 @@ def setup() -> int:
 def teardown() -> int:
     sys.stderr.write(
         "Docker backend: nothing to undo — it provisions no privileged host "
-        "state (networks and the sidecar bundle are per-launch and are "
+        "state (networks and the gateway are per-launch and are "
         "removed by `./cli.py cleanup`). Docker itself is left installed.\n"
     )
     return 0

bot_bottle/backend/docker/sidecar_bundle.py

@@ -1,30 +0,0 @@
-"""Sidecar bundle constants + helpers for the Docker backend
-(PRD 0024).
-
-The bundle image (built by Dockerfile.sidecars, PRD 0024 chunk 1)
-runs egress + git-gate + supervise as one container per bottle
-under a small Python init supervisor. As of chunk 5 the bundle
-is the only shape — the legacy four-sidecar topology and its
-`BOT_BOTTLE_SIDECAR_BUNDLE` feature flag are gone."""
-
-from __future__ import annotations
-
-import os
-
-
-# Bundle image. Defaults to a built-locally tag (built from the
-# repo's Dockerfile.sidecars via compose `build:`). Operators
-# pinning to a published digest can override via env.
-SIDECAR_BUNDLE_IMAGE = os.environ.get(
-    "BOT_BOTTLE_SIDECAR_IMAGE",
-    "bot-bottle-sidecars:latest",
-)
-
-SIDECAR_BUNDLE_DOCKERFILE = "Dockerfile.sidecars"
-
-
-def sidecar_bundle_container_name(slug: str) -> str:
-    """`bot-bottle-sidecars-<slug>`. Same prefix scheme as the
-    per-sidecar containers it replaces, so the dashboard's
-    discovery-by-prefix logic keeps working."""
-    return f"bot-bottle-sidecars-{slug}"

bot_bottle/backend/firecracker/bottle.py

@@ -7,7 +7,7 @@ session. `ssh -t` forwards the host terminal's SIGWINCH to the remote
 PTY natively, so no separate resize bridge is needed.
 
 Commands run as the image's `node` user via `runuser`, with HOME/USER/
-PATH and the bottle env (HTTPS_PROXY at the sidecar, CA paths, …) set
+PATH and the bottle env (HTTPS_PROXY at the gateway, CA paths, …) set
 per-invocation through `env` (the VM itself just runs the init; it has
 no baked-in process env like a `docker run` container would).
 """

bot_bottle/backend/firecracker/bottle_cleanup_plan.py

@@ -10,10 +10,9 @@ from .. import BottleCleanupPlan
 
 @dataclass(frozen=True)
 class FirecrackerBottleCleanupPlan(BottleCleanupPlan):
-    # PIDs of orphaned firecracker VMM processes and the sidecar
+    # PIDs of orphaned firecracker VMM processes and the per-bottle run
-    # containers left behind by previous bottles.
+    # dirs left behind by previous bottles.
     vm_pids: tuple[int, ...] = ()
-    containers: tuple[str, ...] = ()
     run_dirs: tuple[str, ...] = ()
 
     def print(self) -> None:
@@ -22,11 +21,9 @@ class FirecrackerBottleCleanupPlan(BottleCleanupPlan):
             return
         for pid in self.vm_pids:
             info(f"firecracker VM process: pid {pid}")
-        for name in self.containers:
-            info(f"firecracker sidecar container: {name}")
         for path in self.run_dirs:
             info(f"firecracker run dir: {path}")
 
     @property
     def empty(self) -> bool:
-        return not (self.vm_pids or self.containers or self.run_dirs)
+        return not (self.vm_pids or self.run_dirs)

bot_bottle/backend/firecracker/bottle_plan.py

@@ -13,7 +13,7 @@ from .. import BottlePlan
 class FirecrackerBottlePlan(BottlePlan):
     slug: str
     forwarded_env: dict[str, str] = field(repr=False)
-    # Stamped by launch once the sidecar is up and its ports are
+    # Stamped by launch once the gateway is up and its ports are
     # published on the host-side TAP IP (empty at prepare time).
     agent_proxy_url: str = ""
     agent_git_gate_url: str = ""
@@ -21,7 +21,7 @@ class FirecrackerBottlePlan(BottlePlan):
 
     @property
     def container_name(self) -> str:
-        """Instance name, reused for the sidecar container + VM run dir.
+        """Instance name, reused for the gateway container + VM run dir.
         Matches the `bot-bottle-<slug>` convention the other backends
         use so cleanup/enumerate discovery-by-prefix keeps working."""
         return self.agent_provision.instance_name

bot_bottle/backend/firecracker/cleanup.py

@@ -1,9 +1,8 @@
 """Cleanup for the Firecracker backend.
 
 Orphans are: firecracker VMM processes whose config lives under our run
-dir, the `bot-bottle-sidecars-*` containers, and the per-bottle run
+dir, and the per-bottle run dirs. TAP slots free themselves (the flock
-dirs. TAP slots free themselves (the flock drops when the launcher
+drops when the launcher exits), so there is nothing to reclaim there.
-exits), so there is nothing to reclaim there.
 """
 
 from __future__ import annotations
@@ -18,8 +17,6 @@ from ...log import info
 from . import util
 from .bottle_cleanup_plan import FirecrackerBottleCleanupPlan
 
-_SIDECAR_PREFIX = "bot-bottle-sidecars-"
-
 
 def _run_root() -> Path:
     return util.cache_dir() / "run"
@@ -46,17 +43,6 @@ def _orphan_vm_pids() -> list[int]:
     return pids
 
 
-def _sidecar_containers() -> list[str]:
-    result = subprocess.run(
-        ["docker", "ps", "-a", "--format", "{{.Names}}",
-         "--filter", f"name={_SIDECAR_PREFIX}"],
-        capture_output=True, text=True, check=False,
-    )
-    if result.returncode != 0:
-        return []
-    return sorted(n.strip() for n in result.stdout.splitlines() if n.strip())
-
-
 def _run_dirs() -> list[str]:
     run_root = _run_root()
     if not run_root.is_dir():
@@ -67,7 +53,6 @@ def _run_dirs() -> list[str]:
 def prepare_cleanup() -> FirecrackerBottleCleanupPlan:
     return FirecrackerBottleCleanupPlan(
         vm_pids=tuple(_orphan_vm_pids()),
-        containers=tuple(_sidecar_containers()),
         run_dirs=tuple(_run_dirs()),
     )
 
@@ -79,12 +64,6 @@ def cleanup(plan: FirecrackerBottleCleanupPlan) -> None:
             os.kill(pid, signal.SIGTERM)
         except ProcessLookupError:
             pass
-    for name in plan.containers:
-        info(f"docker rm -f {name}")
-        subprocess.run(
-            ["docker", "rm", "-f", name],
-            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
-        )
     for path in plan.run_dirs:
         info(f"rm -rf {path}")
         shutil.rmtree(path, ignore_errors=True)

bot_bottle/backend/firecracker/enumerate.py

@@ -1,43 +1,14 @@
 """Active-agent enumeration for the Firecracker backend.
 
-The agent runs in a VM (no container to list), so a live bottle is
+The backend is disabled during the companion-container removal (#385) — it can't
-identified by its running sidecar container `bot-bottle-sidecars-<slug>`
+launch bottles, so there are none to enumerate. Real enumeration returns
-— the same discovery-by-prefix the other backends use.
+with the backend's consolidated relaunch (#354).
 """
 
 from __future__ import annotations
 
-import subprocess
-
-from ...bottle_state import read_metadata
 from .. import ActiveAgent
 
-_SIDECAR_PREFIX = "bot-bottle-sidecars-"
-
 
 def enumerate_active() -> list[ActiveAgent]:
-    result = subprocess.run(
+    return []
-        ["docker", "ps", "--format", "{{.Names}}",
-         "--filter", f"name={_SIDECAR_PREFIX}"],
-        capture_output=True, text=True, check=False,
-    )
-    if result.returncode != 0:
-        return []
-    out: list[ActiveAgent] = []
-    for name in sorted(n.strip() for n in result.stdout.splitlines() if n.strip()):
-        slug = name[len(_SIDECAR_PREFIX):]
-        metadata = read_metadata(slug)
-        if metadata is None or metadata.backend != "firecracker":
-            # Skip sidecars owned by another backend (docker shares the
-            # container-name prefix).
-            continue
-        out.append(ActiveAgent(
-            backend_name="firecracker",
-            slug=slug,
-            agent_name=metadata.agent_name,
-            started_at=metadata.started_at,
-            services=(),
-            label=metadata.label,
-            color=metadata.color,
-        ))
-    return out

bot_bottle/backend/firecracker/launch.py

@@ -1,404 +1,39 @@
-"""Launch flow for the Firecracker backend.
+"""Launch flow for the Firecracker backend — temporarily disabled (#385).
 
-Per bottle:
+The firecracker backend launched a per-bottle companion container (the
-  1. mint the egress CA, build the agent image (docker), export it to a
+egress / git-gate / supervise data plane) alongside each microVM. That
-     cached ext4 rootfs;
+per-bottle-companion architecture was removed in the companion-container removal;
-  2. claim a free TAP pool slot (rootless flock);
+firecracker's replacement — the consolidated per-host gateway — lands in
-  3. bring up the Docker sidecar bundle, publishing egress / git-gate /
+its own cutover (#354).
-     supervise on the slot's host-side TAP IP at fixed ports;
-  4. boot the microVM on that TAP; wait for SSH;
-  5. provision (CA, prompt, skills, workspace, git, supervise) over SSH.
 
-Isolation is enforced by the operator-provisioned nft table (checked
+Until that lands, launching a firecracker bottle fails closed rather than
-fail-closed in preflight): a VM reaches only its sidecar (DNAT'd from
+silently running the removed path. `prepare` / `status` / cleanup still
-the host TAP IP) and nothing else. The agent's HTTPS_PROXY therefore
+work, so `backend status --backend=firecracker` and orphan cleanup are
-points at `http://<host_tap_ip>:9099`, its only route to the world.
+unaffected.
 """
 
 from __future__ import annotations
 
-import dataclasses
+from contextlib import contextmanager
-import os
-import subprocess
-from contextlib import ExitStack, contextmanager
-from pathlib import Path
 from typing import Callable, Generator
 
-from ...bottle_state import (
+from ...log import die
-    egress_state_dir,
-    git_gate_state_dir,
-    read_committed_image,
-)
-from ...egress import (
-    EGRESS_ROUTES_IN_CONTAINER,
-    egress_agent_env_entries,
-    egress_resolve_token_values,
-    egress_sidecar_env_entries,
-)
-from ...git_gate import (
-    provision_git_gate_dynamic_keys,
-    revoke_git_gate_provisioned_keys,
-)
-from ...log import die, info, warn
-from ...supervise import DB_PATH_IN_CONTAINER, SUPERVISE_PORT
-from ...util import expand_tilde
-from ..docker.egress import (
-    EGRESS_CA_IN_CONTAINER,
-    EGRESS_PORT,
-    egress_tls_init,
-)
-from ..docker.git_gate import (
-    GIT_GATE_ACCESS_HOOK_IN_CONTAINER,
-    GIT_GATE_CREDS_DIR_IN_CONTAINER,
-    GIT_GATE_ENTRYPOINT_IN_CONTAINER,
-    GIT_GATE_HOOK_IN_CONTAINER,
-)
-from ..docker.sidecar_bundle import (
-    SIDECAR_BUNDLE_DOCKERFILE,
-    SIDECAR_BUNDLE_IMAGE,
-)
-from ..util import AGENT_CA_BUNDLE, AGENT_CA_PATH
-from . import firecracker_vm, isolation_probe, netpool, util
 from .bottle import FirecrackerBottle
 from .bottle_plan import FirecrackerBottlePlan
 
 
-_REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)
-_GIT_HTTP_PORT = 9420
-_GIT_GATE_READY_FILE = "/run/git-gate/ready"
-
-
-def sidecar_container_name(slug: str) -> str:
-    return f"bot-bottle-sidecars-{slug}"
-
-
 @contextmanager
 def launch(
     plan: FirecrackerBottlePlan,
     *,
     provision: Callable[[FirecrackerBottlePlan, "FirecrackerBottle"], str | None],
 ) -> Generator[FirecrackerBottle, None, None]:
-    stack = ExitStack()
+    """Fail closed: the firecracker backend is disabled while its
-    bottle_for_revoke = plan.manifest.bottle
+    consolidated (gateway-backed) launch is built in #354."""
-    git_gate_dir_for_revoke = git_gate_state_dir(plan.slug)
+    del plan, provision
-
+    die(
-    def teardown() -> None:
+        "the firecracker backend is temporarily disabled during the "
-        teardown_exc: BaseException | None = None
+        "companion-container removal (#385); its consolidated relaunch "
-        try:
+        "lands in #354. Use --backend=docker for now."
-            stack.close()
-        except BaseException as exc:  # noqa: W0718 - teardown must continue
-            teardown_exc = exc
-            warn(f"firecracker teardown failed: {exc!r}")
-        revoke_git_gate_provisioned_keys(bottle_for_revoke, git_gate_dir_for_revoke)
-        if teardown_exc is not None:
-            raise teardown_exc
-
-    try:
-        plan = _mint_certs(plan)
-        plan = _build_agent_image(plan)
-
-        # Claim a TAP slot; the flock is held until teardown closes it.
-        slot, lock = netpool.allocate(plan.slug)
-        stack.callback(lock.close)
-        info(f"firecracker slot {slot.iface}: host={slot.host_ip} "
-             f"guest={slot.guest_ip}")
-
-        plan = _provision_git_gate_keys(plan)
-
-        sidecar_name = sidecar_container_name(plan.slug)
-        _force_remove_container(sidecar_name)
-        _start_sidecar_bundle(plan, sidecar_name, slot.host_ip)
-        stack.callback(_force_remove_container, sidecar_name)
-        _stage_git_gate(plan, sidecar_name)
-
-        plan = _stamp_agent_urls(plan, slot.host_ip)
-
-        # Build the per-bottle rootfs + SSH key, then boot.
-        base_dir = util.build_base_rootfs_dir(plan.image)
-        run_dir = util.cache_dir() / "run" / plan.slug
-        run_dir.mkdir(parents=True, exist_ok=True)
-        rootfs = run_dir / "rootfs.ext4"
-        util.build_rootfs_ext4(base_dir, rootfs)
-        private_key, pubkey = util.generate_keypair(run_dir)
-
-        vm = firecracker_vm.boot(
-            name=plan.container_name,
-            rootfs=rootfs,
-            tap=slot.iface,
-            guest_ip=slot.guest_ip,
-            host_ip=slot.host_ip,
-            pubkey=pubkey,
-            run_dir=run_dir,
-        )
-        stack.callback(vm.terminate)
-        firecracker_vm.wait_for_ssh(vm, private_key)
-
-        # Authoritative fail-closed egress-boundary check, before the
-        # agent runs: prove the VM cannot reach the host directly.
-        isolation_probe.verify_isolation(private_key, slot.guest_ip)
-
-        bottle = FirecrackerBottle(
-            plan.container_name,
-            private_key=private_key,
-            guest_ip=slot.guest_ip,
-            guest_env=_agent_guest_env(plan, slot.host_ip),
-            agent_command=plan.agent_command,
-            agent_prompt_mode=plan.agent_prompt_mode,
-            agent_provider_template=plan.agent_provider_template,
-            terminal_title=(
-                f"{plan.spec.label} ({plan.spec.agent_name})"
-                if plan.spec.label else plan.spec.agent_name
-            ),
-            terminal_color=plan.spec.color,
-            agent_workdir=plan.workspace_plan.workdir,
-        )
-        bottle.prompt_path = provision(plan, bottle)
-
-        yield bottle
-    finally:
-        teardown()
-
-
-def _mint_certs(plan: FirecrackerBottlePlan) -> FirecrackerBottlePlan:
-    egress_ca_host, egress_ca_cert_only = egress_tls_init(egress_state_dir(plan.slug))
-    egress_plan = dataclasses.replace(
-        plan.egress_plan,
-        mitmproxy_ca_host_path=egress_ca_host,
-        mitmproxy_ca_cert_only_host_path=egress_ca_cert_only,
     )
-    return dataclasses.replace(plan, egress_plan=egress_plan)
+    yield  # unreachable — `die` raises; keeps this a generator/contextmanager
-
-
-def _build_agent_image(plan: FirecrackerBottlePlan) -> FirecrackerBottlePlan:
-    _docker_build(SIDECAR_BUNDLE_IMAGE, _REPO_DIR, dockerfile=SIDECAR_BUNDLE_DOCKERFILE)
-    committed = read_committed_image(plan.slug)
-    if committed and _image_exists(committed):
-        info(f"using committed image {committed!r}")
-        return dataclasses.replace(
-            plan,
-            agent_provision=dataclasses.replace(plan.agent_provision, image=committed),
-        )
-    _docker_build(plan.image, _REPO_DIR, dockerfile=plan.dockerfile_path)
-    return plan
-
-
-def _provision_git_gate_keys(plan: FirecrackerBottlePlan) -> FirecrackerBottlePlan:
-    if not plan.git_gate_plan.upstreams:
-        return plan
-    git_gate_plan = provision_git_gate_dynamic_keys(
-        plan.manifest.bottle, plan.git_gate_plan, git_gate_state_dir(plan.slug),
-    )
-    return dataclasses.replace(plan, git_gate_plan=git_gate_plan)
-
-
-def _stamp_agent_urls(
-    plan: FirecrackerBottlePlan, host_ip: str,
-) -> FirecrackerBottlePlan:
-    proxy_url = f"http://{host_ip}:{EGRESS_PORT}"
-    supervise_url = (
-        f"http://{host_ip}:{SUPERVISE_PORT}/" if plan.supervise_plan is not None else ""
-    )
-    git_gate_url = (
-        f"http://{host_ip}:{_GIT_HTTP_PORT}" if plan.git_gate_plan.upstreams else ""
-    )
-    return dataclasses.replace(
-        plan,
-        agent_proxy_url=proxy_url,
-        agent_git_gate_url=git_gate_url,
-        agent_supervise_url=supervise_url,
-    )
-
-
-# --- sidecar bundle (Docker) ----------------------------------------
-
-def _start_sidecar_bundle(
-    plan: FirecrackerBottlePlan, sidecar_name: str, host_ip: str,
-) -> None:
-    argv = ["docker", "run", "--name", sidecar_name, "--detach", "--rm",
-            "-e", f"BOT_BOTTLE_SIDECAR_DAEMONS={','.join(_sidecar_daemons(plan))}"]
-    for entry in _sidecar_env_entries(plan):
-        argv += ["-e", entry]
-    for host_path, container_path, read_only in _sidecar_mounts(plan):
-        argv += ["-v", f"{host_path}:{container_path}{':ro' if read_only else ''}"]
-    # Publish on the slot's host TAP IP at fixed ports — each bottle
-    # has a distinct host_ip, so fixed ports never collide, and the VM
-    # reaches them at a stable, well-known address (its only route out).
-    for port in _sidecar_ports(plan):
-        argv += ["-p", f"{host_ip}:{port}:{port}"]
-    argv.append(SIDECAR_BUNDLE_IMAGE)
-
-    effective_env = {**dict(os.environ), **plan.agent_provision.provisioned_env}
-    token_values = egress_resolve_token_values(
-        plan.egress_plan.token_env_map, effective_env,
-    )
-    env = {**os.environ, **token_values}
-    info(f"docker run sidecar bundle {sidecar_name} (published on {host_ip})")
-    result = subprocess.run(argv, capture_output=True, text=True, env=env, check=False)
-    if result.returncode != 0:
-        die(f"docker run for sidecar bundle {sidecar_name} failed: "
-            f"{(result.stderr or '').strip() or '<no stderr>'}")
-
-
-def _sidecar_daemons(plan: FirecrackerBottlePlan) -> tuple[str, ...]:
-    daemons = ["egress"]
-    if plan.git_gate_plan.upstreams:
-        daemons += ["git-gate", "git-http"]
-    if plan.supervise_plan is not None:
-        daemons.append("supervise")
-    return tuple(daemons)
-
-
-def _sidecar_ports(plan: FirecrackerBottlePlan) -> tuple[int, ...]:
-    ports = [EGRESS_PORT]
-    if plan.git_gate_plan.upstreams:
-        ports.append(_GIT_HTTP_PORT)
-    if plan.supervise_plan is not None:
-        ports.append(SUPERVISE_PORT)
-    return tuple(ports)
-
-
-def _sidecar_env_entries(plan: FirecrackerBottlePlan) -> tuple[str, ...]:
-    env: list[str] = list(egress_sidecar_env_entries(plan.egress_plan))
-    if plan.git_gate_plan.upstreams:
-        env.append(f"BOT_BOTTLE_GIT_GATE_READY_FILE={_GIT_GATE_READY_FILE}")
-    if plan.supervise_plan is not None:
-        env += [
-            f"SUPERVISE_BOTTLE_SLUG={plan.slug}",
-            f"SUPERVISE_DB_PATH={DB_PATH_IN_CONTAINER}",
-            f"SUPERVISE_PORT={SUPERVISE_PORT}",
-        ]
-    return tuple(env)
-
-
-def _sidecar_mounts(
-    plan: FirecrackerBottlePlan,
-) -> tuple[tuple[str, str, bool], ...]:
-    mounts: list[tuple[str, str, bool]] = []
-    ep = plan.egress_plan
-    mounts.append((str(ep.mitmproxy_ca_host_path.parent),
-                   str(Path(EGRESS_CA_IN_CONTAINER).parent), False))
-    if ep.routes:
-        mounts.append((str(ep.routes_path.parent),
-                       str(Path(EGRESS_ROUTES_IN_CONTAINER).parent), True))
-    sp = plan.supervise_plan
-    if sp is not None:
-        mounts.append((str(sp.db_path.parent),
-                       str(Path(DB_PATH_IN_CONTAINER).parent), False))
-    return tuple(mounts)
-
-
-def _stage_git_gate(plan: FirecrackerBottlePlan, sidecar_name: str) -> None:
-    gp = plan.git_gate_plan
-    if not gp.upstreams:
-        return
-    _docker_exec(sidecar_name, [
-        "mkdir", "-p",
-        str(Path(GIT_GATE_HOOK_IN_CONTAINER).parent),
-        GIT_GATE_CREDS_DIR_IN_CONTAINER, "/git",
-        str(Path(_GIT_GATE_READY_FILE).parent),
-    ])
-    for host_path, container_path in _git_gate_files(plan):
-        _docker_cp(host_path, f"{sidecar_name}:{container_path}")
-    _docker_exec(sidecar_name, [
-        "sh", "-c",
-        f"chmod 755 {GIT_GATE_ENTRYPOINT_IN_CONTAINER} "
-        f"{GIT_GATE_HOOK_IN_CONTAINER} {GIT_GATE_ACCESS_HOOK_IN_CONTAINER} && "
-        f"chmod 600 {GIT_GATE_CREDS_DIR_IN_CONTAINER}/* && "
-        f"touch {_GIT_GATE_READY_FILE}",
-    ])
-
-
-def _git_gate_files(plan: FirecrackerBottlePlan) -> tuple[tuple[str, str], ...]:
-    gp = plan.git_gate_plan
-    files: list[tuple[str, str]] = [
-        (str(gp.entrypoint_script), GIT_GATE_ENTRYPOINT_IN_CONTAINER),
-        (str(gp.hook_script), GIT_GATE_HOOK_IN_CONTAINER),
-        (str(gp.access_hook_script), GIT_GATE_ACCESS_HOOK_IN_CONTAINER),
-    ]
-    for upstream in gp.upstreams:
-        files.append((expand_tilde(upstream.identity_file),
-                      f"{GIT_GATE_CREDS_DIR_IN_CONTAINER}/{upstream.name}-key"))
-        if upstream.known_hosts_file:
-            files.append((str(upstream.known_hosts_file),
-                          f"{GIT_GATE_CREDS_DIR_IN_CONTAINER}/{upstream.name}-known_hosts"))
-    return tuple(files)
-
-
-# --- agent guest env -------------------------------------------------
-
-def _agent_guest_env(plan: FirecrackerBottlePlan, host_ip: str) -> dict[str, str]:
-    """Env injected into every agent/exec call over SSH. The VM has no
-    baked process env (it just runs init), so the proxy/CA/git/supervise
-    wiring is applied per-invocation."""
-    proxy_url = f"http://{host_ip}:{EGRESS_PORT}"
-    no_proxy = f"localhost,127.0.0.1,{host_ip}"
-    env: dict[str, str] = {
-        "HTTPS_PROXY": proxy_url, "HTTP_PROXY": proxy_url,
-        "https_proxy": proxy_url, "http_proxy": proxy_url,
-        "NO_PROXY": no_proxy, "no_proxy": no_proxy,
-        "NODE_EXTRA_CA_CERTS": AGENT_CA_PATH,
-        "SSL_CERT_FILE": AGENT_CA_BUNDLE,
-        "REQUESTS_CA_BUNDLE": AGENT_CA_BUNDLE,
-    }
-    if plan.agent_git_gate_url:
-        env["GIT_GATE_URL"] = plan.agent_git_gate_url
-    if plan.agent_supervise_url:
-        env["MCP_SUPERVISE_URL"] = plan.agent_supervise_url
-    for entry in egress_agent_env_entries(plan.egress_plan):
-        key, _, value = entry.partition("=")
-        env[key] = value
-    env.update(plan.agent_provision.guest_env)
-    # Forwarded (bare-name) env: resolve host values now, since the VM
-    # can't inherit them from a `docker run --env NAME`.
-    for name in plan.forwarded_env:
-        value = os.environ.get(name)
-        if value is not None:
-            env[name] = value
-    return env
-
-
-# --- docker helpers --------------------------------------------------
-
-def _docker_build(ref: str, context: str, *, dockerfile: str = "") -> None:
-    info(f"docker build {ref}")
-    args = ["docker", "build", "-t", ref]
-    if dockerfile:
-        if not os.path.isabs(dockerfile):
-            dockerfile = os.path.join(context, dockerfile)
-        args += ["-f", dockerfile]
-    args.append(context)
-    result = subprocess.run(args, check=False)
-    if result.returncode != 0:
-        die(f"docker build for {ref!r} failed")
-
-
-def _image_exists(ref: str) -> bool:
-    return subprocess.run(
-        ["docker", "image", "inspect", ref],
-        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
-    ).returncode == 0
-
-
-def _force_remove_container(name: str) -> None:
-    subprocess.run(
-        ["docker", "rm", "-f", name],
-        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
-    )
-
-
-def _docker_exec(name: str, argv: list[str]) -> None:
-    result = subprocess.run(
-        ["docker", "exec", name, *argv], capture_output=True, text=True, check=False,
-    )
-    if result.returncode != 0:
-        die(f"docker exec in {name} failed: "
-            f"{(result.stderr or '').strip() or '<no stderr>'}")
-
-
-def _docker_cp(host_path: str, dest: str) -> None:
-    result = subprocess.run(
-        ["docker", "cp", host_path, dest], capture_output=True, text=True, check=False,
-    )
-    if result.returncode != 0:
-        die(f"docker cp {host_path} -> {dest} failed: "
-            f"{(result.stderr or '').strip() or '<no stderr>'}")

bot_bottle/backend/firecracker/netpool.py

@@ -18,7 +18,7 @@ Topology (per slot i):
   * a /31 host<->guest link: host = base + 2i (the gateway the VM
     routes through), guest = base + 2i + 1 (the VM's address).
   * isolation via ``table inet bot_bottle_fc``: a VM reaches only its
-    own sidecar (DNAT'd from the host TAP IP) and nothing else.
+    own gateway (DNAT'd from the host TAP IP) and nothing else.
 
 The default IP block is ``10.243.0.0/16`` — an intentionally obscure
 corner of RFC-1918 private space. RFC-1918 is the range *designated*
@@ -88,10 +88,10 @@ def ip_base() -> str:
     return _cfg("BOT_BOTTLE_FC_IP_BASE")
 
 
-# Sidecar ports the VM reaches at its host-side TAP IP. Kept in sync
+# Gateway ports the VM reaches at its host-side TAP IP. Kept in sync
 # with the backend constants (egress 9099, supervise 9100, git-http
 # 9420); rendered into the setup output for operator visibility.
-SIDECAR_PORTS = (9099, 9100, 9420)
+GATEWAY_PORTS = (9099, 9100, 9420)
 
 
 @dataclass(frozen=True)

bot_bottle/backend/macos_container/__init__.py

@@ -2,7 +2,7 @@
 
 Selectable via `BOT_BOTTLE_BACKEND=macos-container`. This package owns
 the Apple `container` CLI integration; launch remains gated until the
-sidecar network enforcement shape is implemented.
+gateway network enforcement shape is implemented.
 """
 
 from .backend import MacosContainerBottleBackend

bot_bottle/backend/macos_container/cleanup.py

@@ -9,7 +9,6 @@ from . import util as container_mod
 from .bottle_cleanup_plan import MacosContainerBottleCleanupPlan
 
 _PREFIX = "bot-bottle-"
-_BUNDLE_PREFIX = "bot-bottle-sidecars-"
 
 
 def _list_prefixed_containers() -> list[str]:
@@ -24,7 +23,7 @@ def _list_prefixed_containers() -> list[str]:
         return []
     return sorted(
         name for name in (line.strip() for line in result.stdout.splitlines())
-        if name.startswith(_PREFIX) or name.startswith(_BUNDLE_PREFIX)
+        if name.startswith(_PREFIX)
     )
 
 

bot_bottle/backend/macos_container/egress_apply.py

@@ -1,36 +1,24 @@
-"""Host-side egress apply for the macos-container backend.
+"""Host-side egress route-apply for the macos-container backend.
 
-Uses `container kill --signal HUP` (Apple Container framework) instead
+The per-bottle companion container this used to signal (`container kill
-of `docker kill` to signal the sidecar bundle.
+--signal HUP <container>`) was removed in the companion-container removal (#385),
+along with the disabled macOS launch path. Fails closed until the macOS
+backend grows the consolidated gateway.
 """
 
 from __future__ import annotations
 
-import os
-import subprocess
-
-from ...log import warn
 from ..egress_apply import EgressApplicator, EgressApplyError
-from .launch import sidecar_container_name
 
 
 class MacOSContainerEgressApplicator(EgressApplicator):
     def _signal_bundle_reload(self, slug: str) -> None:
-        container = sidecar_container_name(slug)
+        del slug
-        result = subprocess.run(
+        raise EgressApplyError(
-            ["container", "kill", "--signal", "HUP", container],
+            "live egress route-apply was removed with the per-bottle "
-            capture_output=True, text=True, check=False, env=os.environ,
+            "companion container (#385); the macos-container backend is "
+            "disabled until it uses the consolidated gateway."
         )
-        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 'container kill failed'}"
-            )
-            raise EgressApplyError(
-                f"could not reload egress bundle {container}: "
-                f"{last_error or 'container kill failed'}"
-            )
 
 
 applicator = MacOSContainerEgressApplicator()

bot_bottle/backend/macos_container/enumerate.py

@@ -1,40 +1,14 @@
-"""Active-agent enumeration for the macOS Apple Container backend."""
+"""Active-agent enumeration for the macOS Apple Container backend.
+
+The backend is disabled during the companion-container removal (#385) — it can't
+launch bottles, so there are none to enumerate. Enumeration returns when
+the backend grows the consolidated gateway.
+"""
 
 from __future__ import annotations
 
-import subprocess
-
-from ...bottle_state import read_metadata
 from .. import ActiveAgent
 
-_PREFIX = "bot-bottle-"
-_SIDECAR_PREFIX = "bot-bottle-sidecars-"
-
 
 def enumerate_active() -> list[ActiveAgent]:
-    result = subprocess.run(
+    return []
-        ["container", "list", "--quiet"],
-        capture_output=True,
-        text=True,
-        check=False,
-    )
-    if result.returncode != 0:
-        return []
-    out: list[ActiveAgent] = []
-    for name in sorted(line.strip() for line in result.stdout.splitlines()):
-        if not name.startswith(_PREFIX):
-            continue
-        if name.startswith(_SIDECAR_PREFIX):
-            continue
-        slug = name[len(_PREFIX):]
-        metadata = read_metadata(slug)
-        out.append(ActiveAgent(
-            backend_name="macos-container",
-            slug=slug,
-            agent_name=metadata.agent_name if metadata else "?",
-            started_at=metadata.started_at if metadata else "",
-            services=(),
-            label=metadata.label if metadata else "",
-            color=metadata.color if metadata else "",
-        ))
-    return out

bot_bottle/backend/macos_container/launch.py

@@ -1,458 +1,39 @@
-"""Launch flow for the macOS Apple Container backend.
+"""Launch flow for the macOS Apple Container backend — disabled (#385).
 
-This backend keeps the explicit proxy-env enforcement model for v1:
+This backend launched a per-bottle companion container (the egress /
-the agent container is attached only to a host-only Apple Container
+git-gate / supervise data plane) alongside the agent container, with the
-network, while the sidecar bundle is attached to a NAT network first
+agent's proxy env pointed at the companion's host-only IP. That
-and the host-only network second. The sidecar's host-only IP is
+per-bottle-companion architecture was removed in the companion-container removal;
-discovered from `container inspect` and stamped into the agent's
+the macOS backend will be re-enabled once it grows the consolidated
-HTTP_PROXY / HTTPS_PROXY env vars.
+per-host gateway the docker backend already uses.
+
+Until then, launching a macOS bottle fails closed. `prepare` / `status`
+/ cleanup still work.
 """
 
 from __future__ import annotations
 
-import dataclasses
+from contextlib import contextmanager
-import os
-import subprocess
-from contextlib import ExitStack, contextmanager
-from pathlib import Path
 from typing import Callable, Generator
 
-from ...bottle_state import (
+from ...log import die
-    egress_state_dir,
-    git_gate_state_dir,
-    read_committed_image,
-)
-from ...egress import (
-    EGRESS_ROUTES_IN_CONTAINER,
-    egress_agent_env_entries,
-    egress_resolve_token_values,
-    egress_sidecar_env_entries,
-)
-from ...git_gate import (
-    provision_git_gate_dynamic_keys,
-    revoke_git_gate_provisioned_keys,
-)
-from ...log import die, info, warn
-from ...supervise import DB_PATH_IN_CONTAINER, SUPERVISE_PORT
-from ...util import expand_tilde
-from ..docker.egress import EGRESS_CA_IN_CONTAINER, EGRESS_PORT
-from ..docker.git_gate import (
-    GIT_GATE_ACCESS_HOOK_IN_CONTAINER,
-    GIT_GATE_CREDS_DIR_IN_CONTAINER,
-    GIT_GATE_ENTRYPOINT_IN_CONTAINER,
-    GIT_GATE_HOOK_IN_CONTAINER,
-)
-from ..docker.sidecar_bundle import (
-    SIDECAR_BUNDLE_DOCKERFILE,
-    SIDECAR_BUNDLE_IMAGE,
-)
-from ..docker.egress import egress_tls_init
-from ..util import AGENT_CA_BUNDLE, AGENT_CA_PATH
-from . import util as container_mod
 from .bottle import MacosContainerBottle
 from .bottle_plan import MacosContainerBottlePlan
 
 
-_REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)
-_AGENT_SLEEP_SECONDS = "2147483647"
-_GIT_HTTP_PORT = 9420
-_GIT_GATE_READY_FILE = "/run/git-gate/ready"
-
-
-def internal_network_name(slug: str) -> str:
-    return f"bot-bottle-net-{slug}"
-
-
-def egress_network_name(slug: str) -> str:
-    return f"bot-bottle-egress-{slug}"
-
-
-def sidecar_container_name(slug: str) -> str:
-    return f"bot-bottle-sidecars-{slug}"
-
-
 @contextmanager
 def launch(
     plan: MacosContainerBottlePlan,
     *,
     provision: Callable[[MacosContainerBottlePlan, "MacosContainerBottle"], str | None],
 ) -> Generator[MacosContainerBottle, None, None]:
-    """Build, run, provision, and yield an Apple Container bottle."""
+    """Fail closed: the macOS backend is disabled until it grows the
-    stack = ExitStack()
+    consolidated per-host gateway (the companion-container path it used
-    bottle_for_revoke = plan.manifest.bottle
+    was removed in #385)."""
-    git_gate_dir_for_revoke = git_gate_state_dir(plan.slug)
+    del plan, provision
-
+    die(
-    def teardown() -> None:
+        "the macos-container backend is temporarily disabled during the "
-        teardown_exc: BaseException | None = None
+        "companion-container removal (#385); it will return once it uses "
-        try:
+        "the consolidated gateway. Use --backend=docker for now."
-            stack.close()
-        except BaseException as exc:  # noqa: W0718 - teardown must continue
-            teardown_exc = exc
-            warn(f"macos-container teardown failed: {exc!r}")
-        revoke_git_gate_provisioned_keys(bottle_for_revoke, git_gate_dir_for_revoke)
-        if teardown_exc is not None:
-            raise teardown_exc
-
-    try:
-        plan = _mint_certs(plan)
-        plan = _build_images(plan)
-
-        internal_network = internal_network_name(plan.slug)
-        egress_network = egress_network_name(plan.slug)
-        _create_networks(internal_network, egress_network, stack)
-
-        plan = _provision_git_gate_keys(plan)
-
-        sidecar_name = sidecar_container_name(plan.slug)
-        container_mod.force_remove_container(sidecar_name)
-        _start_sidecar_bundle(plan, sidecar_name, internal_network, egress_network)
-        stack.callback(container_mod.force_remove_container, sidecar_name)
-        _stage_git_gate(plan, sidecar_name)
-
-        sidecar_ip = container_mod.container_ipv4_on_network(
-            sidecar_name, internal_network,
-        )
-        plan = _stamp_agent_urls(plan, sidecar_ip)
-
-        container_mod.force_remove_container(plan.container_name)
-        _start_agent(plan, internal_network, sidecar_ip)
-        stack.callback(container_mod.force_remove_container, plan.container_name)
-
-        bottle = MacosContainerBottle(
-            plan.container_name,
-            teardown,
-            None,
-            agent_command=plan.agent_command,
-            agent_prompt_mode=plan.agent_prompt_mode,
-            agent_provider_template=plan.agent_provider_template,
-            terminal_title=f"{plan.spec.label} ({plan.spec.agent_name})" if plan.spec.label else plan.spec.agent_name,
-            terminal_color=plan.spec.color,
-            agent_workdir=plan.workspace_plan.workdir,
-        )
-        bottle.prompt_path = provision(plan, bottle)
-
-        yield bottle
-    finally:
-        teardown()
-
-
-def _mint_certs(plan: MacosContainerBottlePlan) -> MacosContainerBottlePlan:
-    egress_ca_host, egress_ca_cert_only = egress_tls_init(
-        egress_state_dir(plan.slug),
     )
-    egress_plan = dataclasses.replace(
+    yield  # unreachable — `die` raises; keeps this a generator/contextmanager
-        plan.egress_plan,
-        mitmproxy_ca_host_path=egress_ca_host,
-        mitmproxy_ca_cert_only_host_path=egress_ca_cert_only,
-    )
-    return dataclasses.replace(plan, egress_plan=egress_plan)
-
-
-def _build_images(plan: MacosContainerBottlePlan) -> MacosContainerBottlePlan:
-    container_mod.build_image(
-        SIDECAR_BUNDLE_IMAGE,
-        _REPO_DIR,
-        dockerfile=SIDECAR_BUNDLE_DOCKERFILE,
-    )
-    committed = read_committed_image(plan.slug)
-    if committed and container_mod.image_exists(committed):
-        info(f"using committed image {committed!r}")
-        return dataclasses.replace(
-            plan,
-            agent_provision=dataclasses.replace(
-                plan.agent_provision,
-                image=committed,
-            ),
-        )
-    container_mod.build_image(
-        plan.image,
-        _REPO_DIR,
-        dockerfile=plan.dockerfile_path,
-    )
-    return plan
-
-
-def _create_networks(
-    internal_network: str,
-    egress_network: str,
-    stack: ExitStack,
-) -> None:
-    container_mod.create_network(internal_network, internal=True)
-    stack.callback(container_mod.remove_network, internal_network)
-    container_mod.create_network(egress_network)
-    stack.callback(container_mod.remove_network, egress_network)
-
-
-def _start_sidecar_bundle(
-    plan: MacosContainerBottlePlan,
-    sidecar_name: str,
-    internal_network: str,
-    egress_network: str,
-) -> None:
-    argv = _sidecar_run_argv(plan, sidecar_name, internal_network, egress_network)
-    effective_env = {**dict(os.environ), **plan.agent_provision.provisioned_env}
-    token_values = egress_resolve_token_values(
-        plan.egress_plan.token_env_map, effective_env,
-    )
-    env = {**os.environ, **token_values}
-    info(f"container run sidecar bundle {sidecar_name}")
-    result = subprocess.run(
-        argv, capture_output=True, text=True, env=env, check=False,
-    )
-    if result.returncode != 0:
-        die(
-            f"container run for sidecar bundle {sidecar_name} failed: "
-            f"{(result.stderr or '').strip() or '<no stderr>'}"
-        )
-
-
-def _start_agent(
-    plan: MacosContainerBottlePlan,
-    internal_network: str,
-    sidecar_ip: str,
-) -> None:
-    argv = _agent_run_argv(plan, internal_network, sidecar_ip)
-    env = {
-        **os.environ,
-        **plan.forwarded_env,
-    }
-    info(f"container run agent {plan.container_name}")
-    result = subprocess.run(
-        argv, capture_output=True, text=True, env=env, check=False,
-    )
-    if result.returncode != 0:
-        die(
-            f"container run for agent {plan.container_name} failed: "
-            f"{(result.stderr or '').strip() or '<no stderr>'}"
-        )
-
-
-def _stamp_agent_urls(
-    plan: MacosContainerBottlePlan,
-    sidecar_ip: str,
-) -> MacosContainerBottlePlan:
-    proxy_url = f"http://{sidecar_ip}:{EGRESS_PORT}"
-    supervise_url = ""
-    if plan.supervise_plan is not None:
-        supervise_url = f"http://{sidecar_ip}:{SUPERVISE_PORT}/"
-    git_gate_url = ""
-    if plan.git_gate_plan.upstreams:
-        git_gate_url = f"http://{sidecar_ip}:{_GIT_HTTP_PORT}"
-    return dataclasses.replace(
-        plan,
-        agent_proxy_url=proxy_url,
-        agent_git_gate_url=git_gate_url,
-        agent_supervise_url=supervise_url,
-    )
-
-
-def _provision_git_gate_keys(
-    plan: MacosContainerBottlePlan,
-) -> MacosContainerBottlePlan:
-    if not plan.git_gate_plan.upstreams:
-        return plan
-    git_gate_plan = provision_git_gate_dynamic_keys(
-        plan.manifest.bottle,
-        plan.git_gate_plan,
-        git_gate_state_dir(plan.slug),
-    )
-    return dataclasses.replace(plan, git_gate_plan=git_gate_plan)
-
-
-def _stage_git_gate(plan: MacosContainerBottlePlan, sidecar_name: str) -> None:
-    gp = plan.git_gate_plan
-    if not gp.upstreams:
-        return
-
-    container_mod.exec_container(
-        sidecar_name,
-        [
-            "mkdir",
-            "-p",
-            str(Path(GIT_GATE_HOOK_IN_CONTAINER).parent),
-            GIT_GATE_CREDS_DIR_IN_CONTAINER,
-            "/git",
-            str(Path(_GIT_GATE_READY_FILE).parent),
-        ],
-    )
-
-    for host_path, container_path in _git_gate_files(plan):
-        container_mod.copy_into_container(
-            sidecar_name, host_path, container_path,
-        )
-
-    container_mod.exec_container(
-        sidecar_name,
-        [
-            "sh",
-            "-c",
-            "chmod 755 "
-            f"{GIT_GATE_ENTRYPOINT_IN_CONTAINER} "
-            f"{GIT_GATE_HOOK_IN_CONTAINER} "
-            f"{GIT_GATE_ACCESS_HOOK_IN_CONTAINER} && "
-            f"chmod 600 {GIT_GATE_CREDS_DIR_IN_CONTAINER}/* && "
-            f"touch {_GIT_GATE_READY_FILE}",
-        ],
-    )
-
-
-def _git_gate_files(
-    plan: MacosContainerBottlePlan,
-) -> tuple[tuple[str, str], ...]:
-    gp = plan.git_gate_plan
-    files: list[tuple[str, str]] = [
-        (str(gp.entrypoint_script), GIT_GATE_ENTRYPOINT_IN_CONTAINER),
-        (str(gp.hook_script), GIT_GATE_HOOK_IN_CONTAINER),
-        (str(gp.access_hook_script), GIT_GATE_ACCESS_HOOK_IN_CONTAINER),
-    ]
-    for upstream in gp.upstreams:
-        files.append((
-            expand_tilde(upstream.identity_file),
-            f"{GIT_GATE_CREDS_DIR_IN_CONTAINER}/{upstream.name}-key",
-        ))
-        if upstream.known_hosts_file:
-            files.append((
-                str(upstream.known_hosts_file),
-                f"{GIT_GATE_CREDS_DIR_IN_CONTAINER}/{upstream.name}-known_hosts",
-            ))
-    return tuple(files)
-
-
-def _sidecar_run_argv(
-    plan: MacosContainerBottlePlan,
-    sidecar_name: str,
-    internal_network: str,
-    egress_network: str,
-) -> list[str]:
-    argv = [
-        "container", "run",
-        "--name", sidecar_name,
-        "--detach",
-        "--rm",
-        "--network", egress_network,
-        "--network", internal_network,
-        "--dns", _sidecar_dns(),
-        "--env", f"BOT_BOTTLE_SIDECAR_DAEMONS={','.join(_sidecar_daemons(plan))}",
-    ]
-    for entry in _sidecar_env_entries(plan):
-        argv += ["--env", entry]
-    for host_path, container_path, read_only in _sidecar_mounts(plan):
-        argv += ["--mount", _mount_spec(host_path, container_path, read_only)]
-    argv.append(SIDECAR_BUNDLE_IMAGE)
-    return argv
-
-
-def _agent_run_argv(
-    plan: MacosContainerBottlePlan,
-    internal_network: str,
-    sidecar_ip: str,
-) -> list[str]:
-    argv = [
-        "container", "run",
-        "--name", plan.container_name,
-        "--detach",
-        "--network", internal_network,
-    ]
-    for entry in _agent_env_entries(plan, sidecar_ip):
-        argv += ["--env", entry]
-    argv += [plan.image, "sleep", _AGENT_SLEEP_SECONDS]
-    return argv
-
-
-def _sidecar_dns() -> str:
-    return container_mod.dns_server()
-
-
-def _sidecar_daemons(plan: MacosContainerBottlePlan) -> tuple[str, ...]:
-    daemons = ["egress"]
-    if plan.git_gate_plan.upstreams:
-        daemons += ["git-gate", "git-http"]
-    if plan.supervise_plan is not None:
-        daemons.append("supervise")
-    return tuple(daemons)
-
-
-def _sidecar_env_entries(plan: MacosContainerBottlePlan) -> tuple[str, ...]:
-    env: list[str] = list(egress_sidecar_env_entries(plan.egress_plan))
-    if plan.git_gate_plan.upstreams:
-        env.append(f"BOT_BOTTLE_GIT_GATE_READY_FILE={_GIT_GATE_READY_FILE}")
-    if plan.supervise_plan is not None:
-        env += [
-            f"SUPERVISE_BOTTLE_SLUG={plan.slug}",
-            f"SUPERVISE_DB_PATH={DB_PATH_IN_CONTAINER}",
-            f"SUPERVISE_PORT={SUPERVISE_PORT}",
-        ]
-    return tuple(env)
-
-
-def _sidecar_mounts(
-    plan: MacosContainerBottlePlan,
-) -> tuple[tuple[str, str, bool], ...]:
-    mounts: list[tuple[str, str, bool]] = []
-
-    ep = plan.egress_plan
-    mounts.append((
-        str(ep.mitmproxy_ca_host_path.parent),
-        str(Path(EGRESS_CA_IN_CONTAINER).parent),
-        False,
-    ))
-    if ep.routes:
-        mounts.append((
-            str(ep.routes_path.parent),
-            str(Path(EGRESS_ROUTES_IN_CONTAINER).parent),
-            True,
-        ))
-
-    sp = plan.supervise_plan
-    if sp is not None:
-        # `container run --mount type=bind` only accepts directory
-        # sources (a file source fails with "is not a directory") —
-        # mount db_path's dedicated parent dir instead of the file
-        # itself, same as the CA/routes mounts above.
-        mounts.append((
-            str(sp.db_path.parent),
-            str(Path(DB_PATH_IN_CONTAINER).parent),
-            False,
-        ))
-
-    return tuple(mounts)
-
-def _mount_spec(host_path: str, container_path: str, read_only: bool) -> str:
-    spec = f"type=bind,source={host_path},target={container_path}"
-    if read_only:
-        spec += ",readonly"
-    return spec
-
-
-def _agent_env_entries(
-    plan: MacosContainerBottlePlan,
-    sidecar_ip: str,
-) -> tuple[str, ...]:
-    proxy_url = f"http://{sidecar_ip}:{EGRESS_PORT}"
-    no_proxy = _agent_no_proxy(plan, sidecar_ip)
-    env = [
-        f"HTTPS_PROXY={proxy_url}",
-        f"HTTP_PROXY={proxy_url}",
-        f"https_proxy={proxy_url}",
-        f"http_proxy={proxy_url}",
-        f"NO_PROXY={no_proxy}",
-        f"no_proxy={no_proxy}",
-        f"NODE_EXTRA_CA_CERTS={AGENT_CA_PATH}",
-        f"SSL_CERT_FILE={AGENT_CA_BUNDLE}",
-        f"REQUESTS_CA_BUNDLE={AGENT_CA_BUNDLE}",
-    ]
-    if plan.agent_git_gate_url:
-        env.append(f"GIT_GATE_URL={plan.agent_git_gate_url}")
-    if plan.agent_supervise_url:
-        env.append(f"MCP_SUPERVISE_URL={plan.agent_supervise_url}")
-    for name, value in sorted(plan.agent_provision.guest_env.items()):
-        env.append(f"{name}={value}")
-    for name in sorted(plan.forwarded_env.keys()):
-        env.append(name)
-    env.extend(egress_agent_env_entries(plan.egress_plan))
-    return tuple(env)
-
-
-def _agent_no_proxy(plan: MacosContainerBottlePlan, sidecar_ip: str) -> str:
-    hosts = ["localhost", "127.0.0.1", sidecar_ip]
-    return ",".join(hosts)

bot_bottle/backend/resolve_common.py

@@ -94,7 +94,7 @@ def prepare_egress(
 
 
 def prepare_supervise(bottle: ManifestBottle, slug: str) -> SupervisePlan | None:
-    """Prepare the supervise sidecar state dir. Returns None when
+    """Prepare the supervise daemon state dir. Returns None when
     bottle.supervise is falsy."""
     if not bottle.supervise:
         return None

bot_bottle/bottle_state.py

@@ -36,7 +36,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import cast
 
-from . import supervise as _supervise
+from .paths import bot_bottle_root
 
 
 # Directory layout: ~/.bot-bottle/state/<identity>/...
@@ -44,16 +44,16 @@ _STATE_SUBDIR = "state"
 _PER_BOTTLE_DOCKERFILE_NAME = "Dockerfile"
 _COMMITTED_IMAGE_NAME = "committed-image"
 _TRANSCRIPT_SUBDIR = "transcript"
-# Per-sidecar scratch subdirs. PRD 0018 chunk 2: bind-mount sources
+# Per-daemon scratch subdirs. PRD 0018 chunk 2: bind-mount sources
 # live here so chunk 3's `docker compose up` can find them at stable
-# paths. Each sidecar's `prepare()` writes config + CAs into its own
+# paths. Each daemon's `prepare()` writes config + CAs into its own
 # subdir; the launch step is unchanged today (still `docker cp`).
 _EGRESS_SUBDIR = "egress"
 _GIT_GATE_SUBDIR = "git-gate"
 _SUPERVISE_SUBDIR = "supervise"
 _AGENT_SUBDIR = "agent"
 _METADATA_NAME = "metadata.json"
-# Live-config dir bind-mounted into the supervise sidecar (read-only).
+# Live-config dir bind-mounted into the supervise daemon (read-only).
 # Host's apply paths keep these files fresh so supervise's
 # `list-egress-routes` MCP tool returns the current state —
 # not a snapshot from launch time.
@@ -163,7 +163,7 @@ def read_metadata(identity: str) -> BottleMetadata | None:
 def bottle_state_dir(identity: str) -> Path:
     """Per-bottle state directory on the host. Created lazily by the
     write helpers; readers tolerate its absence."""
-    return _supervise.bot_bottle_root() / _STATE_SUBDIR / identity
+    return bot_bottle_root() / _STATE_SUBDIR / identity
 
 
 def per_bottle_dockerfile_path(identity: str) -> Path:
@@ -222,7 +222,7 @@ def per_bottle_image_tag(identity: str) -> str:
 
 def live_config_dir(identity: str) -> Path:
     """Per-bottle live-config dir. Bind-mounted read-only into the
-    supervise sidecar; the host's apply paths refresh the files on
+    supervise daemon; the host's apply paths refresh the files on
     every operator approval so the agent's `list-*` MCP tools always
     return current state."""
     return bottle_state_dir(identity) / _LIVE_CONFIG_SUBDIR
@@ -260,9 +260,9 @@ def transcript_snapshot_dir(identity: str) -> Path:
     return bottle_state_dir(identity) / _TRANSCRIPT_SUBDIR
 
 
-# --- Per-sidecar scratch subdirs (PRD 0018 chunk 2) ------------------------
+# --- Per-daemon scratch subdirs (PRD 0018 chunk 2) ------------------------
 #
-# Each sidecar gets its own subdir under the bottle's state dir for
+# Each daemon gets its own subdir under the bottle's state dir for
 # bind-mount sources (config, CAs, hooks, etc.). Prepare-time writes
 # land here; the state dir's normal cleanup (`cleanup_state`) reaps
 # them along with everything else when the bottle session ends and
@@ -270,20 +270,20 @@ def transcript_snapshot_dir(identity: str) -> Path:
 
 
 def egress_state_dir(identity: str) -> Path:
-    """State subdir for the egress sidecar: routes.yaml + the
+    """State subdir for the egress daemon: routes.yaml + the
     per-bottle mitmproxy CA. Bind-mount source from chunk 3 onward."""
     return bottle_state_dir(identity) / _EGRESS_SUBDIR
 
 
 def git_gate_state_dir(identity: str) -> Path:
-    """State subdir for the git-gate sidecar: entrypoint + hooks +
+    """State subdir for the git-gate daemon: entrypoint + hooks +
     per-upstream known_hosts. Bind-mount source from chunk 3
     onward."""
     return bottle_state_dir(identity) / _GIT_GATE_SUBDIR
 
 
 def supervise_state_dir(identity: str) -> Path:
-    """State subdir reserved for supervise sidecar bind-mount sources.
+    """State subdir reserved for supervise daemon bind-mount sources.
     Runtime queue/audit rows live in the host-level bot-bottle SQLite
     database, so they survive state-dir cleanup."""
     return bottle_state_dir(identity) / _SUPERVISE_SUBDIR

bot_bottle/cli/cleanup.py

@@ -2,8 +2,8 @@
 
 Walks every registered backend (docker, firecracker, macos-container)
 so a single `./cli.py cleanup` reaps every backend's leftovers — a
-firecracker bottle's sidecars won't survive a docker-only cleanup pass
+firecracker bottle's VM processes and run dirs won't survive a
-(issue addressed alongside #77).
+docker-only cleanup pass (issue addressed alongside #77).
 
 Each backend's `prepare_cleanup` enumerates its own resources;
 docker's `_list_orphan_state_dirs` consults

bot_bottle/cli/supervise.py

@@ -19,7 +19,7 @@ from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 
-from .. import supervise as _supervise
+from ..paths import bot_bottle_root
 from ..bottle_state import read_metadata
 from ..backend.docker.egress_apply import (
     EgressApplyError,
@@ -276,7 +276,7 @@ def _write_crash_log(exc: BaseException) -> Path:
     )
     entry = f"=== supervise crash {stamp} ===\n{body}\n"
     try:
-        log_dir = _supervise.bot_bottle_root() / "logs"
+        log_dir = bot_bottle_root() / "logs"
         log_dir.mkdir(parents=True, exist_ok=True)
         path = log_dir / "supervise-crash.log"
         with path.open("a", encoding="utf-8") as fh:

bot_bottle/contrib/claude/agent_provider.py

@@ -4,7 +4,7 @@ The Claude-specific behavior previously inlined under
 `agent_provider.agent_provision_plan` (claude.json trust marker,
 api.anthropic.com egress route, OAuth-token placeholder), plus
 the `claude mcp add` invocation that registers the supervise
-sidecar in claude-code's user config (PRD 0013)."""
+gateway in claude-code's user config (PRD 0013)."""
 
 from __future__ import annotations
 
@@ -293,7 +293,7 @@ class ClaudeAgentProvider(AgentProvider):
         supervise_url: str,
     ) -> None:
         """Run `claude mcp add` inside the agent guest to register the
-        supervise sidecar in claude-code's user config (~/.claude.json).
+        supervise daemon in claude-code's user config (~/.claude.json).
 
         Failure is logged but not fatal — the bottle still works without
         the entry; the operator can register it manually."""

bot_bottle/contrib/codex/agent_provider.py

@@ -4,7 +4,7 @@ The Codex-specific behavior previously inlined under
 `agent_provider.agent_provision_plan` (config.toml trust marker,
 chatgpt.com / api.openai.com egress routes, optional host-credential
 forwarding with dummy-auth.json + verify), plus the `codex mcp add`
-invocation that registers the supervise sidecar in Codex's
+invocation that registers the supervise daemon in Codex's
 ~/.codex/config.toml (PRD 0050)."""
 
 from __future__ import annotations
@@ -266,7 +266,7 @@ class CodexAgentProvider(AgentProvider):
         supervise_url: str,
     ) -> None:
         """Run `codex mcp add` inside the agent guest to register the
-        supervise sidecar in Codex's user config (~/.codex/config.toml).
+        supervise daemon in Codex's user config (~/.codex/config.toml).
 
         Mirrors the Claude provider's `claude mcp add` flow — failure
         is logged but not fatal."""

bot_bottle/dlp_detectors.py

@@ -3,7 +3,7 @@
 Pure Python, no mitmproxy dependency. Each detector is a module-level
 function returning `ScanResult | None`.
 
-Ships flat into the sidecar bundle image alongside
+Ships flat into the gateway image alongside
 `egress_addon_core.py` — both this file and the package source use
 the same try/except import shim pattern.
 """

bot_bottle/docker_cmd.py

@@ -0,0 +1,27 @@
+"""Lean, framework-free `docker` subprocess primitive.
+
+Deliberately a top-level module with a single stdlib import so it can be
+reused from anywhere without cost. It is intentionally *not* placed in
+`backend.docker.util`: importing that module runs `backend/__init__.py`,
+which eagerly loads all three bottle backends (docker + firecracker +
+macos) plus the manifest/egress/git-gate/supervise framework — ~76 modules
+— which would drag the whole backend layer into the deliberately-lean
+orchestrator. This primitive stays free of that so both the orchestrator's
+docker components and (in time) `backend.docker.util` can share it."""
+
+from __future__ import annotations
+
+import subprocess
+
+
+def run_docker(argv: list[str]) -> subprocess.CompletedProcess[str]:
+    """Run a `docker` command, capturing stdout/stderr as text. Never raises
+    on a non-zero exit — callers inspect `returncode` / `stderr` so they can
+    stay fail-closed or tolerate idempotent no-ops (e.g. removing an
+    already-absent container)."""
+    return subprocess.run(
+        argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, check=False,
+    )
+
+
+__all__ = ["run_docker"]

bot_bottle/egress.py

@@ -2,7 +2,7 @@
 
 This module defines the abstract proxy (`Egress`), its plan
 dataclass (`EgressPlan`), and the resolved per-route shape
-(`EgressRoute`). The sidecar's start/stop lifecycle is backend-
+(`EgressRoute`). The gateway's start/stop lifecycle is backend-
 specific and lives on concrete subclasses (see
 `bot_bottle/backend/docker/egress.py`).
 """
@@ -63,8 +63,8 @@ def _random_canary_env() -> str:
     return f"{first}_{second}_SECRET"
 
 
-def egress_sidecar_env_entries(plan: "EgressPlan") -> tuple[str, ...]:
+def egress_gateway_env_entries(plan: "EgressPlan") -> tuple[str, ...]:
-    """Return sidecar env entries needed by egress across all backends."""
+    """Return gateway env entries needed by egress across all backends."""
     env: list[str] = []
     if plan.routes:
         env.extend(sorted(plan.token_env_map.keys()))
@@ -87,7 +87,7 @@ class EgressRoute(Route):
 
     Inherits `host`, `matches`, `auth_scheme`, and `token_env`
     from `egress_addon_core.Route` — those are the fields that cross the
-    YAML wire into the sidecar. The fields below are host-only and
+    YAML wire into the gateway. The fields below are host-only and
     are never serialised to the addon.
 
     `token_ref` is the host env var the CLI reads at launch and forwards
@@ -386,7 +386,7 @@ class Egress(ABC):
         routes_path.write_text(egress_render_routes(routes, log=log))
         routes_path.chmod(0o600)
         # Generate a per-session fake secret under a plausible random env name.
-        # The sidecar marks that exact env name as sensitive for known-secret
+        # The gateway marks that exact env name as sensitive for known-secret
         # scanning; the agent receives the same name/value as exfil bait.
         canary = secrets.token_urlsafe(32)
         return EgressPlan(
@@ -412,6 +412,6 @@ __all__ = [
     "egress_resolve_token_values",
     "egress_routes_for_bottle",
     "egress_agent_env_entries",
-    "egress_sidecar_env_entries",
+    "egress_gateway_env_entries",
     "egress_token_env_map",
 ]

bot_bottle/egress_addon.py

@@ -1,4 +1,4 @@
-"""mitmproxy addon entrypoint for the egress sidecar (PRD 0017, PRD 0053).
+"""mitmproxy addon entrypoint for the egress gateway (PRD 0017, PRD 0053).
 
 Loaded by `mitmdump -s /app/egress_addon.py` inside the
 egress container."""
@@ -10,6 +10,7 @@ import json
 import os
 import signal
 import sys
+import typing
 from pathlib import Path
 
 from mitmproxy import http  # type: ignore[import-not-found]  # pylint: disable=import-error
@@ -32,6 +33,7 @@ from egress_addon_core import (  # type: ignore[import-not-found]  # pylint: dis
     is_git_push_request,
     load_config,
     match_route,
+    resolve_client_context,
     outbound_scan_headers,
     route_to_yaml_dict,
     scan_inbound,
@@ -51,11 +53,26 @@ try:
 except ImportError:  # pragma: no cover - host-side path
     from bot_bottle import supervise as _sv  # type: ignore[import-not-found]
 
+try:
+    from policy_resolver import PolicyResolver  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover - host-side path
+    from bot_bottle.policy_resolver import PolicyResolver
+
 
 DEFAULT_ROUTES_PATH = "/etc/egress/routes.yaml"
 
 INTROSPECT_HOST = "_egress.local"
 
+# Consolidated (multi-tenant) mode: when this points at the per-host
+# orchestrator's control plane, the addon resolves each client's Config by
+# source IP per request instead of using a single static routes file. Unset
+# → legacy per-bottle single-tenant mode (unchanged).
+ORCHESTRATOR_URL_ENV = "BOT_BOTTLE_ORCHESTRATOR_URL"
+
+# App-layer identity token (defense-in-depth over the source-IP invariant);
+# the agent injects it, the addon strips it so it never leaks upstream.
+IDENTITY_HEADER = "x-bot-bottle-identity"
+
 # Seconds the egress proxy holds a token-blocked request open waiting for the
 # operator's supervisor decision (PRD 0062), overridable via env.
 DEFAULT_TOKEN_ALLOW_TIMEOUT_SECONDS = 300.0
@@ -72,20 +89,40 @@ _TOKEN_ALLOW_JUSTIFICATION = (
 
 
 class EgressAddon:
+    # Class default so addons built via __new__ (e.g. in tests) default to
+    # single-tenant; __init__ sets the instance attribute for real runs.
+    _resolver: "PolicyResolver | None" = None
+
     def __init__(self) -> None:
         self.routes_path = os.environ.get("EGRESS_ROUTES", DEFAULT_ROUTES_PATH)
         self.config: Config = Config(routes=())
-        # Tokens the operator has approved this session (PRD 0062). In-memory
+        # Consolidated mode: resolve per-client Config from the orchestrator.
-        # only — a restart re-prompts. Mutated only from the asyncio loop that
+        # Absent → single-tenant (static routes file); behaviour unchanged.
-        # runs the addon hooks, so no lock is needed.
+        orch_url = os.environ.get(ORCHESTRATOR_URL_ENV, "").strip()
-        self.safe_tokens: set[str] = set()
+        self._resolver = PolicyResolver(orch_url) if orch_url else None
+        # Tokens the operator has approved this session (PRD 0062), keyed by
+        # bottle so the shared gateway keeps each bottle's safelist separate —
+        # a global set would let bottle A's approved secret pass bottle B's DLP
+        # scan. In-memory only (a restart re-prompts); mutated only from the
+        # asyncio loop that runs the addon hooks, so no lock is needed.
+        self._safe_tokens: dict[str, set[str]] = {}
         self._supervise_slug = os.environ.get("SUPERVISE_BOTTLE_SLUG", "").strip()
         self._token_allow_timeout = _token_allow_timeout_from_env(os.environ)
         self._reload(initial=True)
         self._install_sighup()
 
-    def _supervise_available(self) -> bool:
+    @staticmethod
-        return bool(self._supervise_slug)
+    def _supervise_available(slug: str) -> bool:
+        """Supervise is reachable for this request iff we resolved a bottle to
+        attribute its proposals to (single-tenant env slug, or a source-IP
+        -attributed bottle id). Empty → fail closed (no queue to write to)."""
+        return bool(slug)
+
+    def _safe_tokens_for(self, slug: str) -> set[str]:
+        """This bottle's operator-approved DLP safelist (PRD 0062), created on
+        first use. Keyed by bottle so the shared gateway never leaks one
+        bottle's approved token into another's scan."""
+        return self._safe_tokens.setdefault(slug, set())
 
     def _reload(self, *, initial: bool = False) -> None:
         try:
@@ -194,6 +231,28 @@ class EgressAddon:
             + "\n"
         )
 
+    def _resolve_flow(
+        self, flow: http.HTTPFlow,
+    ) -> "tuple[Config, str, typing.Mapping[str, str]]":
+        """The `(Config, supervise slug, env)` to apply to this request.
+        Single-tenant → the static `self.config`, the env slug, and the process
+        env. Consolidated → the calling bottle's Config + bottle id + auth
+        tokens, resolved by source IP in one round-trip (fail-closed to deny-all
+        + empty slug if unattributed); `env` is the process env overlaid with
+        the bottle's tokens, so upstream-auth injection (and DLP) use *this*
+        bottle's credentials — exactly what the per-bottle gateway daemon's env did.
+        The identity token, if the agent injected one, is read then stripped so
+        it never leaks upstream."""
+        if self._resolver is None:
+            return self.config, self._supervise_slug, os.environ
+        conn = flow.client_conn
+        client_ip = conn.peername[0] if conn and conn.peername else ""
+        token = flow.request.headers.get(IDENTITY_HEADER, "")
+        flow.request.headers.pop(IDENTITY_HEADER, None)
+        config, slug, tokens = resolve_client_context(self._resolver, client_ip, token)
+        env = {**os.environ, **tokens} if tokens else os.environ
+        return config, slug, env
+
     async def request(self, flow: http.HTTPFlow) -> None:
         request_path, _, query = flow.request.path.partition("?")
 
@@ -201,12 +260,14 @@ class EgressAddon:
             self._serve_introspection(flow, request_path)
             return
 
+        config, slug, env = self._resolve_flow(flow)
+
         # DLP outbound scan BEFORE stripping auth — catches tokens the
         # agent tried to smuggle in any header, path, query param, or body.
         # Hostname is included to catch DNS-tunnelling exfiltration attempts.
-        route = match_route(self.config.routes, flow.request.pretty_host)
+        route = match_route(config.routes, flow.request.pretty_host)
         if route is not None:
-            if not await self._handle_outbound_dlp(flow, route):
+            if not await self._handle_outbound_dlp(flow, route, slug, env):
                 return
             # The redact policy may have rewritten the request line; recompute
             # the path/query the git checks below rely on.
@@ -224,7 +285,7 @@ class EgressAddon:
 
         if is_git_fetch_request(request_path, query):
             git_decision = decide_git_fetch(
-                self.config.routes, flow.request.pretty_host,
+                config.routes, flow.request.pretty_host,
             )
             if git_decision.action == "block":
                 self._block(
@@ -235,17 +296,17 @@ class EgressAddon:
                 return
 
         # Strip agent-set Authorization after DLP scan so smuggled tokens
-        # are caught above; the route may inject sidecar-owned auth below.
+        # are caught above; the route may inject gateway-owned auth below.
         flow.request.headers.pop("authorization", None)
 
         # Build headers mapping for match evaluation
         req_headers = {k.lower(): v for k, v in flow.request.headers.items()}
 
         decision = decide(
-            self.config.routes,
+            config.routes,
             flow.request.pretty_host,
             request_path,
-            os.environ,
+            env,
             request_method=flow.request.method,
             request_headers=req_headers,
         )
@@ -257,7 +318,7 @@ class EgressAddon:
         if decision.inject_authorization is not None:
             flow.request.headers["authorization"] = decision.inject_authorization
 
-        if self.config.log >= LOG_FULL:
+        if config.log >= LOG_FULL:
             self._log_request(flow)
 
     def _block_dlp(self, flow: http.HTTPFlow, result: ScanResult) -> None:
@@ -270,10 +331,13 @@ class EgressAddon:
         self,
         flow: http.HTTPFlow,
         route: Route,
+        slug: str,
+        env: "typing.Mapping[str, str]",
     ) -> bool:
         """Scan the outbound request and apply the route's on-match policy
-        (PRD 0062). Returns True if the request may be forwarded, False if a
+        (PRD 0062). `env` is the per-bottle env overlay (process env + this
-        403 response has been written to `flow`.
+        bottle's tokens) used for DLP detection. Returns True if the request may
+        be forwarded, False if a 403 response has been written to `flow`.
 
         Loops so the supervise policy can re-scan after each approval — a
         second, un-approved token in the same request is still caught."""
@@ -290,8 +354,8 @@ class EgressAddon:
                 flow.request.pretty_host, request_path, query, headers, "",
             )
             result = scan_outbound(
-                route, scan_text, os.environ,
+                route, scan_text, env,
-                safe_tokens=self.safe_tokens, crlf_text=crlf_text,
+                safe_tokens=self._safe_tokens_for(slug), crlf_text=crlf_text,
             )
             if result is None or result.severity != "block":
                 return True
@@ -301,7 +365,7 @@ class EgressAddon:
             # redact scrubs every detection (tokens and structural CRLF) and
             # forwards; it fails closed only if a match survives the scrub.
             if policy == ON_MATCH_REDACT:
-                if self._redact_outbound(flow, route):
+                if self._redact_outbound(flow, route, env):
                     if self.config.log >= LOG_BLOCKS:
                         sys.stderr.write(json.dumps({
                             "event": "egress_redacted",
@@ -326,32 +390,34 @@ class EgressAddon:
 
             # supervise (default): hold the request for operator approval.
             # Fall back to a hard 403 when supervise isn't wired for the bottle.
-            if not self._supervise_available():
+            if not self._supervise_available(slug):
                 self._block_dlp(flow, result)
                 return False
-            approved = await self._supervise_token_block(flow, request_path, result)
+            approved = await self._supervise_token_block(flow, request_path, result, slug, env)
             if not approved:
                 return False  # _supervise_token_block wrote the 403 response
             # loop: the approved value is now in safe_tokens; re-scan.
 
-    def _redact_outbound(self, flow: http.HTTPFlow, route: Route) -> bool:
+    def _redact_outbound(
+        self, flow: http.HTTPFlow, route: Route, env: "typing.Mapping[str, str]",
+    ) -> bool:
         """Scrub detected tokens (and CRLF injection sequences) from the mutable
-        request surfaces (body, headers, path/query) and re-scan. Returns True
+        request surfaces (body, headers, path/query) and re-scan. `env` is the
-        if the request is now clean; False if a block-severity match remains on
+        per-bottle env overlay. Returns True if the request is now clean; False
-        a surface redaction cannot rewrite (the hostname) so the caller fails
+        if a block-severity match remains on a surface redaction cannot rewrite
-        closed."""
+        (the hostname) so the caller fails closed."""
         body = flow.request.get_text(strict=False)
         if body:
-            redacted_body = redact_tokens(body, env=os.environ)
+            redacted_body = redact_tokens(body, env=env)
             if redacted_body != body:
                 flow.request.text = redacted_body
         for name, value in list(flow.request.headers.items()):
             if name.lower() == "host":
                 continue  # routing-critical; never a legitimate token
-            redacted = strip_crlf(redact_tokens(value, env=os.environ))
+            redacted = strip_crlf(redact_tokens(value, env=env))
             if redacted != value:
                 flow.request.headers[name] = redacted
-        redacted_path = strip_crlf(redact_tokens(flow.request.path, env=os.environ))
+        redacted_path = strip_crlf(redact_tokens(flow.request.path, env=env))
         if redacted_path != flow.request.path:
             flow.request.path = redacted_path
 
@@ -364,7 +430,7 @@ class EgressAddon:
         crlf_text = build_outbound_scan_text(
             flow.request.pretty_host, request_path, query, headers, "",
         )
-        result = scan_outbound(route, scan_text, os.environ, crlf_text=crlf_text)
+        result = scan_outbound(route, scan_text, env, crlf_text=crlf_text)
         return result is None or result.severity != "block"
 
     async def _supervise_token_block(
@@ -372,21 +438,27 @@ class EgressAddon:
         flow: http.HTTPFlow,
         request_path: str,
         result: ScanResult,
+        slug: str,
+        env: "typing.Mapping[str, str]",
     ) -> bool:
         """Route a token DLP block to the operator's supervisor queue and wait.
 
-        Returns True if the operator approved (the matched value is added to
+        `slug` attributes the proposal to the calling bottle (its own queue +
-        `self.safe_tokens` and the caller re-scans); False if the request must
+        safelist) — in the shared gateway this is what keeps one bottle's
-        be blocked (a 403 response has been written to `flow`)."""
+        approval from unblocking another's request. `env` is the per-bottle env
+        overlay used to redact secrets from the proposal text. Returns True if
+        the operator approved (the matched value is added to that bottle's
+        safelist and the caller re-scans); False if the request must be blocked
+        (a 403 response has been written to `flow`)."""
         host = flow.request.pretty_host
         payload = build_token_allow_payload(
-            redact_tokens(host, env=os.environ),
+            redact_tokens(host, env=env),
             flow.request.method,
-            redact_tokens(request_path, env=os.environ),
+            redact_tokens(request_path, env=env),
             result,
         )
         proposal = _sv.Proposal.new(
-            bottle_slug=self._supervise_slug,
+            bottle_slug=slug,
             tool=_sv.TOOL_EGRESS_TOKEN_ALLOW,
             proposed_file=payload,
             justification=_TOKEN_ALLOW_JUSTIFICATION,
@@ -409,13 +481,13 @@ class EgressAddon:
             **self._req_ctx(flow),
         }) + "\n")
 
-        response = await self._await_token_response(proposal.id)
+        response = await self._await_token_response(proposal.id, slug)
-        _sv.archive_proposal(self._supervise_slug, proposal.id)
+        _sv.archive_proposal(slug, proposal.id)
 
         if response is not None and response.status in (
             _sv.STATUS_APPROVED, _sv.STATUS_MODIFIED,
         ):
-            self.safe_tokens.add(result.matched)
+            self._safe_tokens_for(slug).add(result.matched)
             if self.config.log >= LOG_BLOCKS:
                 sys.stderr.write(json.dumps({
                     "event": "egress_token_allowed",
@@ -438,6 +510,7 @@ class EgressAddon:
     async def _await_token_response(
         self,
         proposal_id: str,
+        slug: str,
     ) -> "_sv.Response | None":
         """Poll the DB for the operator's response without blocking the
         proxy event loop. Returns the Response, or None on timeout."""
@@ -445,7 +518,7 @@ class EgressAddon:
         deadline = loop.time() + self._token_allow_timeout
         while True:
             try:
-                return _sv.read_response(self._supervise_slug, proposal_id)
+                return _sv.read_response(slug, proposal_id)
             except (OSError, ValueError, KeyError):
                 # Not written yet, or a partial/malformed write — retry until
                 # the deadline, then fail closed.
@@ -499,6 +572,9 @@ class EgressAddon:
         """
         if flow.websocket is None:  # type: ignore[union-attr]
             return
+        # WebSocket DLP runs against the static config only (single-tenant); in
+        # the consolidated gateway self.config has no routes, so this is inert
+        # until websocket routing is made source-IP-aware (a separate slice).
         route = match_route(self.config.routes, flow.request.pretty_host)
         if route is None:
             return
@@ -509,7 +585,7 @@ class EgressAddon:
             # not an injection vector here — scan only for credential leakage.
             result = scan_outbound(
                 route, content, os.environ,
-                safe_tokens=self.safe_tokens, crlf_text="",
+                safe_tokens=self._safe_tokens_for(self._supervise_slug), crlf_text="",
             )
             if result is not None and result.severity == "block":
                 sys.stderr.write(f"egress DLP: {result.reason}\n")

bot_bottle/egress_addon_core.py

@@ -3,12 +3,12 @@
 Split out of `egress_addon.py` so the host's unit tests can
 exercise the parse + decision functions without depending on the
 `mitmproxy` package. The companion module wraps these with the
-`mitmproxy.http.HTTPFlow` API and is loaded inside the sidecar
+`mitmproxy.http.HTTPFlow` API and is loaded inside the gateway
 container.
 
 Imports: stdlib + `yaml_subset` (which is itself stdlib-only and
-ships flat into the sidecar bundle image alongside this file —
+ships flat into the gateway image alongside this file —
-see `Dockerfile.sidecars`)."""
+see `Dockerfile.gateway`)."""
 
 from __future__ import annotations
 
@@ -22,7 +22,7 @@ except ImportError:  # pragma: no cover - host-side path
     from .yaml_subset import YamlSubsetError, parse_yaml_subset
 
 # DLP detector-config parsing lives in a sibling module (also flat-bundled
-# into the sidecar — see Dockerfile.sidecars). Re-exported below so existing
+# into the gateway — see Dockerfile.gateway). Re-exported below so existing
 # `from egress_addon_core import ON_MATCH_*` callers keep working.
 try:
     from egress_dlp_config import (  # type: ignore[import-not-found]
@@ -120,7 +120,7 @@ class ScanResult:
     reason: str
     location: str = ""  # where the match was found, e.g. "body", "authorization header"
     context: str = ""   # surrounding text with the match replaced by REDACT
-    # Raw substring the detector matched. Used inside the sidecar to key the
+    # Raw substring the detector matched. Used inside the gateway to key the
     # supervisor-approved "safe tokens" set (PRD 0062); never logged or written
     # to a proposal file. Empty for structural detectors (CRLF) that carry no
     # safelist-able value.
@@ -413,6 +413,70 @@ def load_config(text: str) -> "Config":
     return parse_config(payload)
 
 
+class PolicyResolverLike(typing.Protocol):
+    """The bit of `policy_resolver.PolicyResolver` this module needs — kept a
+    Protocol so egress_addon_core stays free of that import."""
+
+    def resolve(self, source_ip: str, identity_token: str = ...) -> "str | None":
+        ...
+
+
+def _config_from_policy(policy: "str | None") -> "Config":
+    """Parse a resolved policy blob into a Config, fail-closed: None / empty /
+    unparseable all become a deny-all Config (no routes → every request
+    blocked)."""
+    if not policy:
+        return Config(routes=())  # unattributed or empty → deny-all
+    try:
+        return load_config(policy)
+    except ValueError:
+        return Config(routes=())  # unparseable policy → deny
+
+
+def resolve_client_config(
+    resolver: PolicyResolverLike, client_ip: str, identity_token: str = ""
+) -> "Config":
+    """The calling client's egress Config, resolved from the orchestrator via
+    `resolver` and parsed — **fail-closed**. An unattributed client (None), a
+    resolver error, or an unparseable policy all yield a deny-all Config (no
+    routes → every request blocked). A compromised, absent, or confused
+    orchestrator must never *widen* a bottle's egress."""
+    try:
+        policy = resolver.resolve(client_ip, identity_token)
+    except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
+        return Config(routes=())  # orchestrator unreachable/errored → deny
+    return _config_from_policy(policy)
+
+
+class ContextResolverLike(typing.Protocol):
+    """The bit of `policy_resolver.PolicyResolver` `resolve_client_context`
+    needs — one round-trip returning policy, bottle id, and auth tokens."""
+
+    def resolve_policy_and_bottle_id(
+        self, source_ip: str, identity_token: str = ...,
+    ) -> "tuple[str | None, str | None, dict[str, str]]":
+        ...
+
+
+def resolve_client_context(
+    resolver: ContextResolverLike, client_ip: str, identity_token: str = "",
+) -> "tuple[Config, str, dict[str, str]]":
+    """The calling client's `(Config, bottle_id, tokens)` in one round-trip —
+    **fail-closed**. The Config follows `resolve_client_config`'s deny-all
+    rules; the bottle id is `""` whenever unattributed or the orchestrator
+    errored (caller treats as "supervise unavailable", never another bottle's
+    queue); `tokens` are the per-bottle upstream auth values the addon injects.
+    One `/resolve` keys the egress policy, the supervise queue + safelist, and
+    auth injection."""
+    try:
+        policy, bottle_id, tokens = resolver.resolve_policy_and_bottle_id(
+            client_ip, identity_token,
+        )
+    except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
+        return Config(routes=()), "", {}  # orchestrator unreachable/errored → deny
+    return _config_from_policy(policy), (bottle_id or ""), tokens
+
+
 # ---------------------------------------------------------------------------
 # Match evaluation
 # ---------------------------------------------------------------------------
@@ -613,7 +677,7 @@ def outbound_scan_headers(
 ) -> dict[str, str]:
     """Return request headers that should be included in outbound DLP.
 
-    Routes that inject sidecar-owned auth always strip the agent's
+    Routes that inject gateway-owned auth always strip the agent's
     Authorization header before forwarding. Scanning that header first
     creates false positives for provider clients that insist on sending
     their own bearer-shaped placeholder, while still not changing what
@@ -664,7 +728,7 @@ def scan_outbound(
     crlf_text: str | None = None,
 ) -> ScanResult | None:
     # Lazy import to avoid circular deps and keep dlp_detectors optional
-    # at import time (the sidecar copies it flat alongside this file).
+    # at import time (the gateway copies it flat alongside this file).
     try:
         from dlp_detectors import (  # type: ignore[import-not-found]
             scan_crlf_injection,
@@ -804,6 +868,10 @@ __all__ = [
     "is_git_push_request",
     "is_git_fetch_request",
     "load_config",
+    "resolve_client_config",
+    "resolve_client_context",
+    "PolicyResolverLike",
+    "ContextResolverLike",
     "match_route",
     "outbound_scan_headers",
     "parse_config",

bot_bottle/egress_dlp_config.py

@@ -6,8 +6,8 @@ and what the proxy does when an outbound detector matches a token
 kept apart from the request-time scan/decision flow in `egress_addon_core`
 so each half reads top-to-bottom without scrolling past the other.
 
-Stdlib-only; ships flat into the sidecar bundle image alongside
+Stdlib-only; ships flat into the gateway image alongside
-`egress_addon_core.py` — see `Dockerfile.sidecars`."""
+`egress_addon_core.py` — see `Dockerfile.gateway`."""
 
 from __future__ import annotations
 

bot_bottle/egress_entrypoint.sh

@@ -1,8 +1,8 @@
 #!/bin/sh
-# Egress daemon entrypoint inside the sidecar bundle (PRD 0024).
+# Egress daemon entrypoint inside the gateway (PRD 0024).
 #
 # Extracted verbatim from Dockerfile.egress's prior inline `sh -c`
-# ENTRYPOINT so the supervisor in bot_bottle/sidecar_init.py can
+# ENTRYPOINT so the supervisor in bot_bottle/gateway_init.py can
 # call it as a normal child. Behavior is unchanged:
 #
 #   * Upstream proxy: when EGRESS_UPSTREAM_PROXY is set, switch
@@ -22,7 +22,7 @@ set -e
 
 # Pin mitmproxy's config dir to the bind-mount location of its CA
 # regardless of which user mitmdump runs as. In the legacy
-# four-sidecar setup (Dockerfile.egress, USER mitmproxy) this
+# four-daemon setup (Dockerfile.egress, USER mitmproxy) this
 # resolved naturally to `~mitmproxy/.mitmproxy`. In the PRD 0024
 # bundle (USER root) `~root/.mitmproxy` is empty, so without this
 # flag mitmdump would generate a fresh CA on the wrong path and

bot_bottle/gateway_init.py

@@ -1,26 +1,26 @@
-"""Per-bottle sidecar supervisor (PRD 0024 chunk 1).
+"""Gateway data-plane supervisor (PRD 0070; PRD 0024 bundle shape).
 
-PID 1 inside the `bot-bottle-sidecars` bundle image. Spawns
+PID 1 inside the `bot-bottle-gateway` data-plane image. Spawns
 the configured daemons (egress, git-gate, supervise),
 forwards SIGTERM/SIGINT to each child, and propagates per-daemon
 stdout+stderr to the container log with a `[name] ` prefix.
 
 Failure policy (interim): when a child dies unexpectedly, the
 supervisor logs the death and leaves the surviving children
-running. The bundle stays up; whatever the dead daemon served
+running. The gateway stays up; whatever the dead daemon served
 will start failing, surfacing in the agent's own error path.
-The supervisor itself exits only when (a) the operator/compose
+The supervisor itself exits only when (a) the operator sends
-sends SIGTERM/SIGINT, or (b) every child has died.
+SIGTERM/SIGINT, or (b) every child has died.
 
 Failure policy (eventual): on unexpected death, the supervisor
 restarts the daemon and emits a notification to the supervise
-sidecar so the operator sees the event. That lands in a later
+daemon so the operator sees the event. That lands in a later
-PR; the interim policy is "don't take the bundle down for one
+PR; the interim policy is "don't take the gateway down for one
 sick daemon."
 
-Daemon subset is env-driven. The compose renderer narrows it via
+Daemon subset is env-driven via `BOT_BOTTLE_GATEWAY_DAEMONS=egress`
-`BOT_BOTTLE_SIDECAR_DAEMONS=egress` for bottles that
+for callers that don't use git-gate or supervise. Default: all
-don't use git-gate or supervise. Default: all daemons.
+daemons.
 
 Stdlib-only by design — adding supervisord/s6/runit for four
 daemons is heavier than this script.
@@ -103,8 +103,8 @@ def _selected_daemons(
     env: dict[str, str],
     all_daemons: Sequence[_DaemonSpec] | None = None,
 ) -> tuple[_DaemonSpec, ...]:
-    """Filter the daemon set by the BOT_BOTTLE_SIDECAR_DAEMONS env
+    """Filter the daemon set by the BOT_BOTTLE_GATEWAY_DAEMONS env
-    var. Unknown names in the list are ignored — the renderer is the
+    var. Unknown names in the list are ignored — the caller is the
     source of truth for which daemons are wired.
 
     `all_daemons` defaults to `_DAEMONS` resolved at call time (not
@@ -112,7 +112,7 @@ def _selected_daemons(
     `_DAEMONS` and have the new value take effect."""
     if all_daemons is None:
         all_daemons = _DAEMONS
-    raw = env.get("BOT_BOTTLE_SIDECAR_DAEMONS", "").strip()
+    raw = env.get("BOT_BOTTLE_GATEWAY_DAEMONS", "").strip()
     if not raw:
         return tuple(all_daemons)
     wanted = {n.strip() for n in raw.split(",") if n.strip()}
@@ -120,7 +120,7 @@ def _selected_daemons(
 
 
 def _log(msg: str) -> None:
-    sys.stdout.write(f"sidecar-init: {msg}\n")
+    sys.stdout.write(f"gateway-init: {msg}\n")
     sys.stdout.flush()
 
 

bot_bottle/git_gate.py

@@ -1,6 +1,6 @@
 """Per-agent git-gate (PRD 0008).
 
-A third per-agent sidecar that fronts the bottle's declared git
+A third per-agent daemon that fronts the bottle's declared git
 upstreams as a transparent mirror. Each `bottle.git` entry maps to
 a bare repo on the gate; `git daemon` serves the bare repos over
 `git://<gate>/<name>.git`. Two hooks make the mirror bidirectional:
@@ -15,7 +15,7 @@ a bare repo on the gate; `git daemon` serves the bare repos over
 
 The agent never sees the upstream credential under either path.
 
-Why a separate sidecar (not folded into egress or ssh-gate): the
+Why a separate daemon (not folded into egress or ssh-gate): the
 gate is the only one of the three that holds upstream push
 credentials. Mixing it with egress would put push creds in the
 same blast radius as internet-facing TLS interception; mixing it
@@ -23,7 +23,7 @@ with ssh-gate would force ssh-gate above L4 and into git-protocol
 land. See `docs/prds/0008-git-gate.md`.
 
 This module defines the abstract gate (`GitGate`) and its plan
-dataclass (`GitGatePlan`). The sidecar's start/stop lifecycle is
+dataclass (`GitGatePlan`). The gateway's start/stop lifecycle is
 backend-specific and lives on concrete subclasses (see
 `bot_bottle/backend/docker/git_gate.py`)."""
 
@@ -46,6 +46,7 @@ from .git_gate_render import (
     git_gate_known_hosts_line,
     git_gate_render_access_hook,
     git_gate_render_entrypoint,
+    git_gate_render_provision,
     git_gate_render_gitconfig,
     git_gate_render_hook,
     git_gate_upstreams_for_bottle,
@@ -85,7 +86,7 @@ class GitGatePlan:
 
 class GitGate(ABC):
     """The per-agent git-gate. Encapsulates the host-side prepare
-    (upstream lift + entrypoint/hook render); the sidecar's
+    (upstream lift + entrypoint/hook render); the gateway's
     start/stop lifecycle is backend-specific and lives on concrete
     subclasses."""
 
@@ -155,6 +156,7 @@ __all__ = [
     "git_gate_render_gitconfig",
     "git_gate_known_hosts_line",
     "git_gate_render_entrypoint",
+    "git_gate_render_provision",
     "git_gate_render_hook",
     "git_gate_render_access_hook",
     "provision_git_gate_dynamic_keys",

bot_bottle/git_gate_render.py

@@ -1,7 +1,7 @@
 """Pure host-side rendering for the per-agent git-gate (PRD 0008).
 
 Builds the agent's `.gitconfig` insteadOf rewrites, the known_hosts
-line, and the entrypoint / pre-receive / access-hook scripts the sidecar
+line, and the entrypoint / pre-receive / access-hook scripts the gateway
 runs. No docker or forge calls — exposed for tests and reuse across
 backends. Split out of `git_gate.py` so the control surface (`GitGate`)
 and the deploy-key lifecycle (`git_gate_provision`) each read on their
@@ -9,13 +9,14 @@ own; `git_gate` re-exports these names for API stability."""
 
 from __future__ import annotations
 
+import re
 import shlex
 from dataclasses import dataclass
 from pathlib import Path
 
 from .manifest import ManifestBottle, ManifestGitEntry
 
-# Short network alias for git-gate inside the sidecar bundle. The
+# Short network alias for git-gate inside the gateway. The
 # agent's `.gitconfig` insteadOf rewrites resolve through this name.
 GIT_GATE_HOSTNAME = "git-gate"
 # Shared timeout (seconds) for all git-gate subprocess and CGI calls:
@@ -37,7 +38,7 @@ class GitGateUpstream:
     KnownHostKey string from the manifest; the gate's start step
     materialises it into a known_hosts file if non-empty.
 
-    the gate credential paths inside the running sidecar."""
+    the gate credential paths inside the running gateway."""
 
     name: str
     upstream_url: str
@@ -125,22 +126,18 @@ def git_gate_known_hosts_line(host: str, port: str, key: str) -> str:
     return f"{target} {key}\n"
 
 
-def git_gate_render_entrypoint(upstreams: tuple[GitGateUpstream, ...]) -> str:
+def _git_gate_init_repo_fn(repo_root: str, creds_dir: str) -> list[str]:
-    """Posix-sh entrypoint. One `init_repo` call per upstream, then
+    """The `init_repo` shell function, parameterized by the bare-repo root
-    `exec git daemon`. The function reads
+    and the per-bottle creds dir. Single source of the credential-wiring
-    `/git-gate/creds/<name>-{key,known_hosts}` (bind-mounted into
+    logic, shared by the single-tenant daemon entrypoint (`/git`,
-    the bundle by the renderer) and wires them into each bare repo's
+    `/git-gate/creds`) and the consolidated per-bottle provisioning
-    config; the access-hook + pre-receive hook pick those paths up
+    (`/git/<bottle_id>`, `/git-gate/creds/<bottle_id>`)."""
-    at fetch / push time."""
+    return [
-    lines = [
-        "#!/bin/sh",
-        "set -eu",
-        "",
         "init_repo() {",
         "  name=$1",
         "  upstream_url=$2",
-        "  keyfile=/git-gate/creds/${name}-key",
+        f"  keyfile={creds_dir}/${{name}}-key",
-        "  hostsfile=/git-gate/creds/${name}-known_hosts",
+        f"  hostsfile={creds_dir}/${{name}}-known_hosts",
         "",
         # `|| true`: PRD 0018 chunk 3+ bind-mounts these RO from the
         # host, so chmod-syscalls fail with EROFS. The files already
@@ -153,14 +150,14 @@ def git_gate_render_entrypoint(upstreams: tuple[GitGateUpstream, ...]) -> str:
         "    chmod 600 \"$hostsfile\" 2>/dev/null || true",
         "  fi",
         "",
-        "  repo=/git/${name}.git",
+        f"  repo={repo_root}/${{name}}.git",
         "  if [ ! -d \"$repo\" ]; then",
         "    git init --bare \"$repo\" >/dev/null",
-        # --mirror=fetch sets remote.origin.fetch = +refs/*:refs/* so",
+        # --mirror=fetch sets remote.origin.fetch = +refs/*:refs/* so a later
-        # a later `git fetch origin` mirrors the upstream's full ref",
+        # `git fetch origin` mirrors the upstream's full ref graph (heads,
-        # graph (heads, tags, notes) into the bare repo at canonical",
+        # tags, notes) into the bare repo at canonical paths. It does NOT set
-        # paths. It does NOT set remote.origin.mirror=true, so an",
+        # remote.origin.mirror=true, so an explicit `git push origin
-        # explicit `git push origin <ref>:<ref>` still pushes one ref.",
+        # <ref>:<ref>` still pushes one ref.
         "    git -C \"$repo\" remote add --mirror=fetch origin \"$upstream_url\"",
         "  fi",
         "  git -C \"$repo\" config git-gate.identityFile \"$keyfile\"",
@@ -170,9 +167,19 @@ def git_gate_render_entrypoint(upstreams: tuple[GitGateUpstream, ...]) -> str:
         "  git -C \"$repo\" config http.receivepack true",
         "  install -m 755 /etc/git-gate/pre-receive \"$repo/hooks/pre-receive\"",
         "}",
-        "",
-        "mkdir -p /git",
     ]
+
+
+def git_gate_render_entrypoint(upstreams: tuple[GitGateUpstream, ...]) -> str:
+    """Posix-sh entrypoint. One `init_repo` call per upstream, then
+    `exec git daemon`. The function reads
+    `/git-gate/creds/<name>-{key,known_hosts}` (bind-mounted into
+    the bundle by the renderer) and wires them into each bare repo's
+    config; the access-hook + pre-receive hook pick those paths up
+    at fetch / push time."""
+    lines = ["#!/bin/sh", "set -eu", ""]
+    lines += _git_gate_init_repo_fn("/git", "/git-gate/creds")
+    lines += ["", "mkdir -p /git"]
     for u in upstreams:
         lines.append(f"init_repo {shlex.quote(u.name)} {shlex.quote(u.upstream_url)}")
     lines.extend([
@@ -190,6 +197,35 @@ def git_gate_render_entrypoint(upstreams: tuple[GitGateUpstream, ...]) -> str:
     return "\n".join(lines) + "\n"
 
 
+# A bottle id namespaces the consolidated gateway's repo + creds dirs; it is
+# embedded unquoted in the provisioning script, so restrict it to a shell- and
+# path-safe alphabet (registry ids are token_hex — this is defense in depth).
+_SAFE_BOTTLE_ID = re.compile(r"[A-Za-z0-9_-]+")
+
+
+def git_gate_render_provision(
+    bottle_id: str, upstreams: tuple[GitGateUpstream, ...],
+) -> str:
+    """Posix-sh script that provisions ONE bottle's bare repos into the
+    consolidated gateway (PRD 0070), under `/git/<bottle_id>/` with creds
+    read from `/git-gate/creds/<bottle_id>/`. Init-only — no `git daemon`,
+    since the shared gateway already serves every bottle; run inside the
+    running gateway when the bottle is registered.
+
+    Isolating each bottle's repo root and creds dir by id is what keeps one
+    bottle's push credentials out of another's repos on the shared gateway."""
+    if not _SAFE_BOTTLE_ID.fullmatch(bottle_id):
+        raise ValueError(f"git-gate: unsafe bottle id {bottle_id!r}")
+    repo_root = f"/git/{bottle_id}"
+    creds_dir = f"/git-gate/creds/{bottle_id}"
+    lines = ["#!/bin/sh", "set -eu", ""]
+    lines += _git_gate_init_repo_fn(repo_root, creds_dir)
+    lines += ["", f"mkdir -p {shlex.quote(repo_root)}"]
+    for u in upstreams:
+        lines.append(f"init_repo {shlex.quote(u.name)} {shlex.quote(u.upstream_url)}")
+    return "\n".join(lines) + "\n"
+
+
 def git_gate_render_hook() -> str:
     """The shared pre-receive hook: gitleaks-scan all incoming refs,
     then forward each accepted ref to the real upstream (`origin`)

bot_bottle/git_http_backend.py

@@ -2,10 +2,19 @@
 
 Used where `git://` push traffic over a host-published Docker port can
 hang before receive-pack reaches hooks (e.g. the firecracker backend,
-where the guest reaches the sidecar over the point-to-point TAP). The
+where the guest reaches the gateway over the point-to-point TAP). The
 wrapper serves the same `/git/*.git` bare repos through
 `git http-backend`, so pre-receive and upstream forwarding remain the
 git-gate enforcement point.
+
+Consolidated (PRD 0070): when `BOT_BOTTLE_ORCHESTRATOR_URL` is set, one
+shared gateway serves every bottle, and each request is served from the
+calling bottle's repo namespace (`<root>/<bottle_id>`), attributed from
+the unspoofable source IP via the orchestrator. Per-repo credentials +
+hooks scope by repo directory, so isolating the *root* per bottle isolates
+its creds too. Unattributed clients fail closed (404). Unset → the legacy
+per-bottle single-tenant flat root, unchanged — a transitional path that
+gets stripped out once every backend runs the consolidated gateway.
 """
 
 from __future__ import annotations
@@ -13,16 +22,89 @@ from __future__ import annotations
 import os
 import subprocess
 import sys
+import typing
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
 from urllib.parse import urlsplit
 
+# policy_resolver ships flat alongside this file in the gateway
+# image (see Dockerfile.gateway); the bot_bottle.* fallback is the
+# host-side / test path. Mirrors egress_addon's import shape.
+try:
+    from policy_resolver import (  # type: ignore[import-not-found]
+        PolicyResolveError,
+        PolicyResolver,
+    )
+except ImportError:  # pragma: no cover - host-side path
+    from bot_bottle.policy_resolver import PolicyResolveError, PolicyResolver
+
 
 DEFAULT_PORT = 9420
 
+# Consolidated (multi-tenant) mode: when this points at the per-host
+# orchestrator's control plane, the backend serves each request from the
+# *calling* bottle's repo namespace, selected by source IP, instead of a
+# single flat repo root. Unset → legacy per-bottle single-tenant mode
+# (unchanged). Same env the egress addon reads, so one orchestrator setting
+# flips the whole shared gateway multi-tenant.
+ORCHESTRATOR_URL_ENV = "BOT_BOTTLE_ORCHESTRATOR_URL"
+
+# App-layer identity token (defense-in-depth over the source-IP invariant);
+# the agent injects it, the backend reads it for attribution and never
+# forwards it to `git http-backend`. Mirrors egress_addon.IDENTITY_HEADER
+# (duplicated, not imported: egress_addon pulls in mitmproxy).
+IDENTITY_HEADER = "x-bot-bottle-identity"
+
+# Default flat repo root (single-tenant, and the base under which
+# consolidated mode nests each sandbox's namespace).
+DEFAULT_REPO_ROOT = "/git"
+
+
+class ResolverLike(typing.Protocol):
+    """Structural type for the resolver `resolve_sandbox_root` needs — just
+    `resolve_bottle_id`. A Protocol so tests can pass a fake without
+    importing PolicyResolver (mirrors egress_addon_core.PolicyResolverLike)."""
+
+    def resolve_bottle_id(
+        self, source_ip: str, identity_token: str = ...,
+    ) -> "str | None": ...
+
+
+def resolve_sandbox_root(
+    resolver: "ResolverLike | None",
+    base_root: Path,
+    source_ip: str,
+    identity_token: str = "",
+) -> Path | None:
+    """The per-sandbox repo root to serve this request from, or None to
+    deny (404).
+
+    Single-tenant (`resolver is None`): the flat `base_root`, unchanged.
+    NOTE: this legacy per-bottle single-tenant path is transitional — it
+    will be stripped out once every backend runs the consolidated gateway
+    (PRD 0070), leaving only the source-IP-attributed path below.
+
+    Consolidated: `base_root/<bottle_id>`, where the sandbox is attributed
+    from the source IP via the orchestrator. Fail-closed — an unattributed
+    client, a resolver error, or a namespace that would escape `base_root`
+    all deny, so one sandbox can never reach another's repos."""
+    if resolver is None:
+        return base_root
+    try:
+        bottle_id = resolver.resolve_bottle_id(source_ip, identity_token)
+    except PolicyResolveError:
+        return None  # orchestrator unreachable/errored → deny
+    if not bottle_id:
+        return None  # unattributed → deny
+    base = base_root.resolve()
+    namespace = (base / bottle_id).resolve()
+    if base not in namespace.parents:
+        return None  # bottle_id tried to escape the root → deny
+    return namespace
+
 # Mirrors git_gate_render.GIT_GATE_TIMEOUT_SECS. Duplicated rather than
-# imported: this module ships as a flat top-level sibling in the sidecar
+# imported: this module ships as a flat top-level sibling in the gateway
-# bundle image (see Dockerfile.sidecars), not as part of the bot_bottle
+# bundle image (see Dockerfile.gateway), not as part of the bot_bottle
 # package, so `bot_bottle.git_gate` and its dependency chain aren't
 # available at runtime.
 GIT_GATE_TIMEOUT_SECS = 15
@@ -40,10 +122,25 @@ class GitHttpHandler(BaseHTTPRequestHandler):
     def do_POST(self) -> None:
         self._run_backend()
 
+    def _sandbox_root(self) -> Path | None:
+        """This request's per-sandbox repo root, or None to deny. Single-tenant
+        unless the server was started with a resolver (consolidated mode), in
+        which case the root is the calling sandbox's source-IP-selected
+        namespace. `GIT_PROJECT_ROOT` keeps git's own env-var name."""
+        base = Path(os.environ.get("GIT_PROJECT_ROOT", DEFAULT_REPO_ROOT))
+        resolver = getattr(self.server, "policy_resolver", None)
+        token = self.headers.get(IDENTITY_HEADER, "")
+        return resolve_sandbox_root(resolver, base, self.client_address[0], token)
+
     def _run_backend(self) -> None:
+        sandbox_root = self._sandbox_root()
+        if sandbox_root is None:
+            # Unattributed / resolver error: deny before touching any repo.
+            self.send_error(404)
+            return
         parsed = urlsplit(self.path)
         if self._is_upload_pack(parsed.path, parsed.query):
-            repo_dir = self._repo_dir(parsed.path)
+            repo_dir = self._repo_dir(sandbox_root, parsed.path)
             if repo_dir is None:
                 self.send_error(404)
                 return
@@ -77,7 +174,7 @@ class GitHttpHandler(BaseHTTPRequestHandler):
                 return
         env = os.environ.copy()
         env.update({
-            "GIT_PROJECT_ROOT": os.environ.get("GIT_PROJECT_ROOT", "/git"),
+            "GIT_PROJECT_ROOT": str(sandbox_root),
             "GIT_HTTP_EXPORT_ALL": "1",
             "REQUEST_METHOD": self.command,
             "PATH_INFO": parsed.path,
@@ -91,6 +188,14 @@ class GitHttpHandler(BaseHTTPRequestHandler):
             "SERVER_PORT": str(self.server.server_port),  # type: ignore
             "SERVER_PROTOCOL": self.request_version,
         })
+        # Consolidated mode: attribute the gitleaks-allow supervise proposal
+        # (written by receive-pack's pre-receive hook, a child of the CGI we
+        # spawn below) to the calling bottle. The namespaced root is
+        # `<base>/<bottle_id>`, so its final component is the bottle id — the
+        # same per-bottle key egress uses. Single-tenant leaves the hook's
+        # container-stamped SUPERVISE_BOTTLE_SLUG untouched.
+        if getattr(self.server, "policy_resolver", None) is not None:
+            env["SUPERVISE_BOTTLE_SLUG"] = sandbox_root.name
         for header, variable in (
             ("accept", "HTTP_ACCEPT"),
             ("content-encoding", "HTTP_CONTENT_ENCODING"),
@@ -123,8 +228,8 @@ class GitHttpHandler(BaseHTTPRequestHandler):
         )
         self._write_cgi_response(proc.stdout)
 
-    def _repo_dir(self, path: str) -> Path | None:
+    def _repo_dir(self, sandbox_root: Path, path: str) -> Path | None:
-        root = Path(os.environ.get("GIT_PROJECT_ROOT", "/git")).resolve()
+        root = sandbox_root.resolve()
         relative = path.lstrip("/").split(".git", 1)[0] + ".git"
         candidate = (root / relative).resolve()
         if root not in (candidate, *candidate.parents):
@@ -181,7 +286,13 @@ class GitHttpHandler(BaseHTTPRequestHandler):
 def main() -> int:
     port = int(os.environ.get("GIT_HTTP_PORT", str(DEFAULT_PORT)))
     server = ThreadingHTTPServer(("0.0.0.0", port), GitHttpHandler)
-    sys.stdout.write(f"git-http listening on 0.0.0.0:{port}\n")
+    orch_url = os.environ.get(ORCHESTRATOR_URL_ENV, "").strip()
+    # Consolidated mode: resolve each request's sandbox namespace by source
+    # IP. Absent → single-tenant (flat repo root); behaviour unchanged.
+    resolver = PolicyResolver(orch_url) if orch_url else None
+    server.policy_resolver = resolver  # type: ignore[attr-defined]
+    mode = "multi-tenant" if orch_url else "single-tenant"
+    sys.stdout.write(f"git-http listening on 0.0.0.0:{port} ({mode})\n")
     sys.stdout.flush()
     server.serve_forever()
     return 0

bot_bottle/manifest_agent.py

@@ -17,7 +17,7 @@ class ManifestAgentProvider:
 
     `template` selects a built-in launch/runtime contract. `dockerfile`
     optionally points at a custom agent-image Dockerfile while leaving
-    bot-bottle's sidecar infrastructure intact.
+    bot-bottle's gateway infrastructure intact.
 
     `auth_token` names the host env var that holds the provider's OAuth
     token (Claude only). The provisioner injects a provider-owned egress
@@ -26,7 +26,7 @@ class ManifestAgentProvider:
     so the Claude Code CLI starts.
 
     `forward_host_credentials` forwards the host Codex auth token into
-    the egress sidecar (Codex only).
+    the egress daemon (Codex only).
     """
 
     template: str = "claude"

bot_bottle/manifest_bottle.py

@@ -39,10 +39,10 @@ class ManifestBottle:
     # identity without any git-gate.repos upstreams, and vice versa.
     git_user: ManifestGitUser = field(default_factory=ManifestGitUser)
     egress: ManifestEgressConfig = field(default_factory=ManifestEgressConfig)
-    # Per-bottle stuck-recovery sidecar (PRD 0013). When true (the
+    # Per-bottle stuck-recovery daemon (PRD 0013). When true (the
     # default, issue #249), the launch step brings up a supervise
-    # sidecar that exposes egress MCP tools to the agent. Set
+    # daemon that exposes egress MCP tools to the agent. Set
-    # `supervise: false` to skip the sidecar.
+    # `supervise: false` to skip the gateway.
     supervise: bool = True
 
     @classmethod
@@ -61,7 +61,7 @@ class ManifestBottle:
             raise ManifestError(
                 f"bottle '{name}' has an 'ssh' field, which has been removed "
                 f"(PRD 0009). Declare upstreams under 'git-gate.repos' with "
-                f"url + identity + host_key; the git-gate sidecar (PRD 0008) "
+                f"url + identity + host_key; the git-gate daemon (PRD 0008) "
                 f"holds the credential and gitleaks-scans pushes."
             )
 

bot_bottle/orchestrator/__init__.py

@@ -0,0 +1,64 @@
+"""Per-host orchestrator service (PRD 0070).
+
+A single persistent per-host service that will run the gateway functions
+(egress / git-gate / supervise), coordinate with the console, and broker
+agent launches. This package is being built bottom-up, starting with the
+backend-neutral "consolidation core" that needs no VM packaging:
+
+  * `registry`      — the SQLite runtime-state store + fail-closed
+                      attribution (source IP + per-bottle identity token).
+  * `broker`        — the signed, structured launch-request contract + a
+                      `LaunchBroker` (stub for the harness) that verifies
+                      provenance before acting.
+  * `gateway`       — the consolidated per-host gateway: a `Gateway`
+                      lifecycle contract (idempotent singleton) + a
+                      `DockerGateway` impl. One gateway shared by all
+                      bottles instead of one per bottle.
+  * `service`       — the `Orchestrator`: owns the registry, brokers the
+                      launch lifecycle (launch/teardown), manages the
+                      shared gateway, attributes.
+  * `control_plane` — the HTTP control-plane RPC (launch / teardown /
+                      list / attribute / gateway / health).
+
+The actual backend-native launch (a real docker/firecracker broker) and
+the egress/git/supervise data plane land in later slices once this core is
+proven (see the PRD sequencing: plain-process dev-harness -> docker
+orchestrator -> firecracker).
+"""
+
+from __future__ import annotations
+
+from .registry import BottleRecord, RegistryStore, new_identity_token
+from .broker import (
+    BrokerAuthError,
+    LaunchBroker,
+    LaunchRequest,
+    StubBroker,
+    sign_request,
+    verify_request,
+)
+from .docker_broker import DockerBroker, DockerBrokerError
+from .gateway import DockerGateway, Gateway, GatewayError
+from .service import Orchestrator
+from .control_plane import ControlPlaneServer, dispatch, make_server
+
+__all__ = [
+    "BottleRecord",
+    "RegistryStore",
+    "new_identity_token",
+    "BrokerAuthError",
+    "LaunchBroker",
+    "LaunchRequest",
+    "StubBroker",
+    "DockerBroker",
+    "DockerBrokerError",
+    "Gateway",
+    "DockerGateway",
+    "GatewayError",
+    "sign_request",
+    "verify_request",
+    "Orchestrator",
+    "ControlPlaneServer",
+    "dispatch",
+    "make_server",
+]

bot_bottle/orchestrator/__main__.py

@@ -0,0 +1,85 @@
+"""Run the orchestrator control plane as a plain process (PRD 0070 dev-harness).
+
+    python -m bot_bottle.orchestrator [--host H] [--port P] [--db PATH]
+
+The PRD sequences the orchestrator as a plain-process dev-harness first, so
+the consolidation core (registry + attribution + HTTP control plane + live
+reload) can be exercised with fast iteration, decoupled from any VM /
+container packaging. Wrapping this exact service in a backend-native unit
+(docker container, then Firecracker VM) comes later.
+"""
+
+from __future__ import annotations
+
+import argparse
+import secrets
+from pathlib import Path
+
+from .. import log
+from .broker import LaunchBroker, StubBroker
+from .control_plane import make_server
+from .docker_broker import DockerBroker
+from .registry import RegistryStore, default_db_path
+from .service import Orchestrator
+from .gateway import DockerGateway, Gateway
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Parse args, migrate the registry, and serve the control plane."""
+    parser = argparse.ArgumentParser(prog="bot_bottle.orchestrator")
+    parser.add_argument("--host", default="127.0.0.1", help="bind address")
+    parser.add_argument("--port", type=int, default=8080, help="bind port (0 = ephemeral)")
+    parser.add_argument(
+        "--db", type=Path, default=None,
+        help=f"registry DB path (default: {default_db_path()})",
+    )
+    parser.add_argument(
+        "--broker", choices=("stub", "docker"), default="stub",
+        help="launch broker: 'stub' records requests; 'docker' runs containers",
+    )
+    parser.add_argument(
+        "--gateway", action="store_true",
+        help="run one consolidated per-host gateway (build-if-missing)",
+    )
+    args = parser.parse_args(argv)
+
+    registry = RegistryStore(args.db)
+    registry.migrate()
+
+    # An ephemeral signing secret ties the orchestrator (signer) to its
+    # broker (verifier). 'stub' records launches instead of starting
+    # anything; 'docker' runs real containers (firecracker drops in later).
+    secret = secrets.token_bytes(32)
+    broker: LaunchBroker = DockerBroker(secret) if args.broker == "docker" else StubBroker(secret)
+    # Standalone `--gateway` (not the consolidated flow, where the host
+    # lifecycle runs the gateway). The gateway resolves against this same
+    # process; the URL is only reachable when they share a docker network.
+    gateway: Gateway | None = (
+        DockerGateway(orchestrator_url=f"http://{args.host}:{args.port}")
+        if args.gateway else None
+    )
+    orchestrator = Orchestrator(registry, broker, secret, gateway)
+
+    # One persistent per-host gateway, shared by every bottle: build the
+    # bundle image if missing, then bring the singleton up (idempotent).
+    if gateway is not None:
+        orchestrator.ensure_gateway()
+        log.info("consolidated gateway ensured", context={"name": gateway.name})
+
+    server = make_server(orchestrator, host=args.host, port=args.port)
+    bound_host, bound_port = server.server_address[0], server.server_address[1]
+    log.info(
+        "orchestrator control plane listening",
+        context={"host": bound_host, "port": bound_port, "db": str(registry.db_path)},
+    )
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        log.info("orchestrator shutting down")
+    finally:
+        server.server_close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bot_bottle/orchestrator/broker.py

@@ -0,0 +1,176 @@
+"""Launch broker contract (PRD 0070).
+
+A VM/container can't spawn its own host-network siblings, so the
+orchestrator brokers agent launches through a small privileged component.
+The request it sends is:
+
+  * **structured** — static flags + ids only (bottle id, pool slot, a
+    content-addressed image ref), never a free-form path or argv, so a
+    request can't be coerced into launching an arbitrary payload; and
+  * **signed** — wrapped as a compact JWS/JWT the broker verifies before
+    acting, so a *compromised co-located component* (an agent-facing
+    gateway, say) can't forge a launch. This is the concrete form of the
+    "structured requests only" rule in the PRD security review.
+
+Signing is **HS256** over a secret shared by the orchestrator (signer) and
+the broker (verifier) — appropriate here because both are trusted host
+components provisioned together; the secret is exactly what an
+agent-facing component does not have. (Stdlib only — the project takes no
+runtime deps; a cross-host deployment could swap in an asymmetric alg.)
+"""
+
+from __future__ import annotations
+
+import abc
+import base64
+import hashlib
+import hmac
+import json
+import secrets
+import time
+from dataclasses import dataclass
+
+_JWT_HEADER = {"alg": "HS256", "typ": "JWT"}
+_ALLOWED_OPS = ("launch", "teardown")
+
+
+class BrokerAuthError(Exception):
+    """A broker request failed provenance or schema verification —
+    bad/absent signature, malformed token, or a payload that doesn't match
+    the fixed launch-request shape. Fail-closed: the broker must not act."""
+
+
+@dataclass(frozen=True)
+class LaunchRequest:
+    """The structured, un-coercible launch/teardown request. Ids + flags
+    only — `image_ref` is a content-addressed id, never a path/argv."""
+
+    op: str  # one of _ALLOWED_OPS
+    bottle_id: str
+    source_ip: str = ""
+    image_ref: str = ""
+    slot: int | None = None
+
+
+# --- minimal JWS/JWT (HS256), stdlib only ----------------------------------
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _b64url_decode(text: str) -> bytes:
+    return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+
+
+def _mac(signing_input: str, secret: bytes) -> str:
+    digest = hmac.new(secret, signing_input.encode("ascii"), hashlib.sha256).digest()
+    return _b64url(digest)
+
+
+def sign_request(req: LaunchRequest, secret: bytes) -> str:
+    """Serialize `req` to signed-JWT form. Adds a per-signature `jti`
+    (replay id) and `iat` (issued-at)."""
+    claims: dict[str, object] = {
+        "op": req.op,
+        "bottle_id": req.bottle_id,
+        "source_ip": req.source_ip,
+        "image_ref": req.image_ref,
+        "slot": req.slot,
+        "jti": secrets.token_hex(8),
+        "iat": int(time.time()),
+    }
+    header = _b64url(json.dumps(_JWT_HEADER, sort_keys=True, separators=(",", ":")).encode())
+    payload = _b64url(json.dumps(claims, sort_keys=True, separators=(",", ":")).encode())
+    signing_input = f"{header}.{payload}"
+    return f"{signing_input}.{_mac(signing_input, secret)}"
+
+
+def verify_request(token: str, secret: bytes) -> LaunchRequest:
+    """Verify the signature and the request shape; return the parsed
+    request. Raises `BrokerAuthError` on any failure (fail-closed)."""
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise BrokerAuthError("malformed token")
+    header_b, payload_b, sig = parts
+    if not hmac.compare_digest(_mac(f"{header_b}.{payload_b}", secret), sig):
+        raise BrokerAuthError("bad signature")
+    try:
+        header = json.loads(_b64url_decode(header_b))
+        claims = json.loads(_b64url_decode(payload_b))
+    except (ValueError, json.JSONDecodeError) as e:
+        raise BrokerAuthError("malformed token payload") from e
+    if not isinstance(header, dict) or header.get("alg") != "HS256":
+        raise BrokerAuthError("unexpected header/alg")
+    if not isinstance(claims, dict):
+        raise BrokerAuthError("claims are not an object")
+
+    op = claims.get("op")
+    bottle_id = claims.get("bottle_id")
+    source_ip = claims.get("source_ip", "")
+    image_ref = claims.get("image_ref", "")
+    slot = claims.get("slot")
+    if (
+        not isinstance(op, str) or op not in _ALLOWED_OPS
+        or not isinstance(bottle_id, str) or not bottle_id
+        or not isinstance(source_ip, str) or not isinstance(image_ref, str)
+        or not (slot is None or isinstance(slot, int))
+    ):
+        raise BrokerAuthError("request does not match the launch-request schema")
+    return LaunchRequest(
+        op=op, bottle_id=bottle_id, source_ip=source_ip, image_ref=image_ref, slot=slot
+    )
+
+
+# --- the broker itself ------------------------------------------------------
+
+class LaunchBroker(abc.ABC):
+    """Verifies a signed request came from the orchestrator, then performs
+    the backend-native launch/teardown. Subclasses implement `_launch` /
+    `_teardown`; verification is shared and fail-closed."""
+
+    def __init__(self, secret: bytes) -> None:
+        self._secret = secret
+
+    def submit(self, token: str) -> LaunchRequest:
+        """Verify `token` and perform its op. Returns the verified request;
+        raises `BrokerAuthError` if provenance/shape fails."""
+        req = verify_request(token, self._secret)
+        if req.op == "launch":
+            self._launch(req)
+        else:
+            self._teardown(req)
+        return req
+
+    @abc.abstractmethod
+    def _launch(self, req: LaunchRequest) -> None:
+        ...
+
+    @abc.abstractmethod
+    def _teardown(self, req: LaunchRequest) -> None:
+        ...
+
+
+class StubBroker(LaunchBroker):
+    """Dev-harness broker: records verified requests without launching
+    anything. Exercises the full sign -> verify -> act contract in-process."""
+
+    def __init__(self, secret: bytes) -> None:
+        super().__init__(secret)
+        self.launched: list[LaunchRequest] = []
+        self.torn_down: list[LaunchRequest] = []
+
+    def _launch(self, req: LaunchRequest) -> None:
+        self.launched.append(req)
+
+    def _teardown(self, req: LaunchRequest) -> None:
+        self.torn_down.append(req)
+
+
+__all__ = [
+    "BrokerAuthError",
+    "LaunchRequest",
+    "LaunchBroker",
+    "StubBroker",
+    "sign_request",
+    "verify_request",
+]

bot_bottle/orchestrator/client.py

@@ -0,0 +1,144 @@
+"""Host-side control-plane client (PRD 0070).
+
+The launch path talks to the orchestrator over its HTTP control plane to
+register, re-policy, and tear down bottles — the counterpart to the
+gateway-side `PolicyResolver` (which only reads `/resolve`). Where
+`PolicyResolver` is fail-closed and lives in the untrusted data plane, this
+is the trusted control-plane caller: a non-success response is an error the
+launch path must surface, not silently swallow.
+
+Stdlib-only, so the CLI can drive the orchestrator without any dependency.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+DEFAULT_TIMEOUT_SECONDS = 5.0
+
+
+class OrchestratorClientError(RuntimeError):
+    """A control-plane call failed (unreachable, or an unexpected status)."""
+
+
+@dataclass(frozen=True)
+class RegisteredBottle:
+    """What `POST /bottles` returns: the minted bottle id and the per-bottle
+    identity token the agent presents for app-layer attribution."""
+
+    bottle_id: str
+    identity_token: str
+
+
+class OrchestratorClient:
+    """Trusted host-side client for the orchestrator control plane."""
+
+    def __init__(self, base_url: str, *, timeout: float = DEFAULT_TIMEOUT_SECONDS) -> None:
+        self._base = base_url.rstrip("/")
+        self._timeout = timeout
+
+    def _request(
+        self, method: str, path: str, body: dict[str, object] | None = None,
+    ) -> tuple[int, dict[str, object]]:
+        """Send one request; return `(status, payload)`. Raises
+        `OrchestratorClientError` only when the orchestrator can't be reached
+        or returns malformed data — HTTP *status* codes are returned so
+        callers can treat 404 as a meaningful "no such bottle"."""
+        data = json.dumps(body).encode() if body is not None else None
+        headers = {"Content-Type": "application/json"} if data is not None else {}
+        req = urllib.request.Request(
+            f"{self._base}{path}", data=data, method=method, headers=headers,
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                raw = resp.read()
+                payload = json.loads(raw) if raw else {}
+                return resp.status, payload if isinstance(payload, dict) else {}
+        except urllib.error.HTTPError as e:
+            # A structured error response still carries a usable status.
+            try:
+                payload = json.loads(e.read() or b"{}")
+            except (ValueError, OSError):
+                payload = {}
+            return e.code, payload if isinstance(payload, dict) else {}
+        except (urllib.error.URLError, TimeoutError, OSError, ValueError) as e:
+            raise OrchestratorClientError(f"{method} {path}: {e}") from e
+
+    def _ok(self, method: str, path: str, body: dict[str, object] | None = None) -> dict[str, object]:
+        """`_request` that requires a 2xx, raising otherwise."""
+        status, payload = self._request(method, path, body)
+        if not 200 <= status < 300:
+            detail = payload.get("error", "")
+            raise OrchestratorClientError(f"{method} {path}: HTTP {status} {detail}".rstrip())
+        return payload
+
+    def health(self) -> bool:
+        """True iff the control plane answers `GET /health` with 200."""
+        try:
+            status, _ = self._request("GET", "/health")
+        except OrchestratorClientError:
+            return False
+        return status == 200
+
+    def register_bottle(
+        self,
+        source_ip: str,
+        *,
+        image_ref: str = "",
+        metadata: str = "",
+        policy: str = "",
+        tokens: dict[str, str] | None = None,
+    ) -> RegisteredBottle:
+        """Register a bottle and broker its launch (`POST /bottles`). `tokens`
+        are the per-bottle egress auth values (env_name -> value) the
+        orchestrator holds in memory for the gateway to inject. Returns the
+        minted id + identity token."""
+        payload = self._ok("POST", "/bottles", {
+            "source_ip": source_ip,
+            "image_ref": image_ref,
+            "metadata": metadata,
+            "policy": policy,
+            "tokens": tokens or {},
+        })
+        bottle_id = payload.get("bottle_id")
+        token = payload.get("identity_token")
+        if not isinstance(bottle_id, str) or not isinstance(token, str):
+            raise OrchestratorClientError("register: response missing bottle_id/identity_token")
+        return RegisteredBottle(bottle_id=bottle_id, identity_token=token)
+
+    def teardown_bottle(self, bottle_id: str) -> bool:
+        """Tear a bottle down (`DELETE /bottles/<id>`). False if the
+        orchestrator didn't know it (404) — idempotent for cleanup paths."""
+        status, _ = self._request("DELETE", f"/bottles/{bottle_id}")
+        if status == 404:
+            return False
+        if not 200 <= status < 300:
+            raise OrchestratorClientError(f"teardown {bottle_id}: HTTP {status}")
+        return True
+
+    def set_policy(self, bottle_id: str, policy: str) -> bool:
+        """Live-reload a bottle's policy (`PUT /bottles/<id>/policy`). False on
+        404 (unknown bottle)."""
+        status, _ = self._request("PUT", f"/bottles/{bottle_id}/policy", {"policy": policy})
+        if status == 404:
+            return False
+        if not 200 <= status < 300:
+            raise OrchestratorClientError(f"set_policy {bottle_id}: HTTP {status}")
+        return True
+
+    def list_bottles(self) -> list[dict[str, object]]:
+        """Every registered bottle's redacted record (`GET /bottles`)."""
+        payload = self._ok("GET", "/bottles")
+        bottles = payload.get("bottles")
+        return bottles if isinstance(bottles, list) else []
+
+
+__all__ = [
+    "OrchestratorClient",
+    "OrchestratorClientError",
+    "RegisteredBottle",
+    "DEFAULT_TIMEOUT_SECONDS",
+]

bot_bottle/orchestrator/control_plane.py

@@ -0,0 +1,219 @@
+"""Orchestrator HTTP control plane (PRD 0070).
+
+The backend-agnostic control-plane RPC (CLI / console -> orchestrator) over
+**HTTP** — the universal transport chosen in 0070 (works on every host; no
+vsock / unix-socket portability caveats):
+
+    GET    /health                    -> 200 {"status": "ok"}
+    GET    /gateway                   -> 200 {"configured", ["name","running"]}
+    GET    /bottles                   -> 200 {"bottles": [ <redacted record>, ...]}
+    POST   /bottles                   -> 201 {"bottle_id","identity_token"}  (launch)
+                                         body: {"source_ip", ["image_ref"],
+                                                ["metadata"], ["policy"]}
+    PUT    /bottles/<bottle_id>/policy -> 200 {"updated": true} | 404  (live reload)
+                                         body: {"policy"}
+    DELETE /bottles/<bottle_id>        -> 200 {"torn_down": true} | 404  (teardown)
+    POST   /attribute                 -> 200 {"bottle_id"} | 403
+    POST   /resolve                   -> 200 {"bottle_id","policy"} | 403
+                                         body: {"source_ip","identity_token"}
+
+`POST /bottles` / `DELETE` drive the full launch lifecycle: they mint (or
+tear down) the bottle in the registry AND broker the backend-native launch
+via the orchestrator. Register/deregister without a launch are internal to
+`Orchestrator`, not exposed here.
+
+Routing/handling is the pure function `dispatch()` so it is unit-testable
+without a socket; `Handler` / `ControlPlaneServer` / `make_server` are a
+thin stdlib adapter around it. Listing redacts identity tokens — they are
+returned only once, to the caller that launches the bottle.
+"""
+
+from __future__ import annotations
+
+import http.server
+import json
+import os
+import socketserver
+import sys
+import typing
+from urllib.parse import urlsplit
+
+from .service import Orchestrator
+
+# JSON body payload type (parsed request / rendered response).
+Json = dict[str, object]
+
+
+def _parse_json_object(body: bytes) -> Json:
+    """Parse a JSON object body. Raises ValueError for non-objects / bad JSON."""
+    if not body:
+        return {}
+    obj = json.loads(body)  # raises json.JSONDecodeError (a ValueError)
+    if not isinstance(obj, dict):
+        raise ValueError("request body must be a JSON object")
+    return obj
+
+
+def dispatch(  # pylint: disable=too-many-return-statements,too-many-branches
+    orch: Orchestrator, method: str, path: str, body: bytes
+) -> tuple[int, Json]:
+    """Route one control-plane request to a (status, payload) pair. Pure —
+    no I/O beyond the orchestrator — so it is fully testable without a socket."""
+    route = urlsplit(path).path.rstrip("/") or "/"
+
+    if method == "GET" and route == "/health":
+        return 200, {"status": "ok"}
+
+    if method == "GET" and route == "/gateway":
+        return 200, orch.gateway_status()
+
+    if method == "GET" and route == "/bottles":
+        return 200, {"bottles": [r.redacted() for r in orch.registry.all()]}
+
+    if method == "POST" and route == "/bottles":
+        try:
+            data = _parse_json_object(body)
+        except ValueError as e:
+            return 400, {"error": f"invalid JSON: {e}"}
+        source_ip = data.get("source_ip")
+        if not isinstance(source_ip, str) or not source_ip:
+            return 400, {"error": "source_ip (string) is required"}
+        image_ref = data.get("image_ref")
+        metadata = data.get("metadata")
+        policy = data.get("policy")
+        raw_tokens = data.get("tokens")
+        tokens = {
+            k: v for k, v in raw_tokens.items() if isinstance(k, str) and isinstance(v, str)
+        } if isinstance(raw_tokens, dict) else {}
+        rec = orch.launch_bottle(
+            source_ip,
+            image_ref=image_ref if isinstance(image_ref, str) else "",
+            metadata=metadata if isinstance(metadata, str) else "",
+            policy=policy if isinstance(policy, str) else "",
+            tokens=tokens,
+        )
+        return 201, {"bottle_id": rec.bottle_id, "identity_token": rec.identity_token}
+
+    if method == "PUT" and route.startswith("/bottles/") and route.endswith("/policy"):
+        bottle_id = route[len("/bottles/"):-len("/policy")]
+        try:
+            data = _parse_json_object(body)
+        except ValueError as e:
+            return 400, {"error": f"invalid JSON: {e}"}
+        policy = data.get("policy")
+        if not isinstance(policy, str):
+            return 400, {"error": "policy (string) is required"}
+        if orch.set_policy(bottle_id, policy):
+            return 200, {"updated": True}
+        return 404, {"error": "no such bottle"}
+
+    if method == "DELETE" and route.startswith("/bottles/"):
+        bottle_id = route[len("/bottles/"):]
+        if orch.teardown_bottle(bottle_id):
+            return 200, {"torn_down": True}
+        return 404, {"error": "no such bottle"}
+
+    if method == "POST" and route == "/attribute":
+        try:
+            data = _parse_json_object(body)
+        except ValueError as e:
+            return 400, {"error": f"invalid JSON: {e}"}
+        source_ip = data.get("source_ip")
+        token = data.get("identity_token")
+        if not isinstance(source_ip, str) or not isinstance(token, str):
+            return 400, {"error": "source_ip and identity_token (strings) required"}
+        rec = orch.attribute(source_ip, token)
+        if rec is None:
+            return 403, {"error": "unattributed"}
+        return 200, {"bottle_id": rec.bottle_id}
+
+    if method == "POST" and route == "/resolve":
+        # The per-request lookup the multi-tenant gateway makes: returns the
+        # bottle's policy. identity_token is OPTIONAL — absent means resolve
+        # by source IP alone (network-layer attribution).
+        try:
+            data = _parse_json_object(body)
+        except ValueError as e:
+            return 400, {"error": f"invalid JSON: {e}"}
+        source_ip = data.get("source_ip")
+        token = data.get("identity_token")
+        if not isinstance(source_ip, str) or not source_ip:
+            return 400, {"error": "source_ip (string) is required"}
+        rec = orch.resolve(source_ip, token if isinstance(token, str) else "")
+        if rec is None:
+            return 403, {"error": "unattributed"}
+        # tokens are the in-memory per-bottle egress auth values the gateway
+        # injects; served here, never persisted.
+        return 200, {
+            "bottle_id": rec.bottle_id,
+            "policy": rec.policy,
+            "tokens": orch.tokens_for(rec.bottle_id),
+        }
+
+    return 404, {"error": "not found"}
+
+
+class Handler(http.server.BaseHTTPRequestHandler):
+    """Thin stdlib adapter: read the body, call `dispatch`, write JSON."""
+
+    # Quiet by default (the orchestrator has its own logging); opt back into
+    # stdlib access logging with BOT_BOTTLE_ORCHESTRATOR_DEBUG.
+    def log_message(self, format: str, *args: typing.Any) -> None:  # noqa: A002
+        if os.environ.get("BOT_BOTTLE_ORCHESTRATOR_DEBUG"):
+            super().log_message(format, *args)
+
+    def _serve(self, method: str) -> None:
+        """Read the request body, dispatch it, and write the JSON reply. A
+        dispatch failure (e.g. a broker error) returns a 500 rather than
+        crashing the connection, so one bad request can't take the control
+        plane down for the caller."""
+        server = self.server
+        assert isinstance(server, ControlPlaneServer)
+        length = int(self.headers.get("Content-Length") or 0)
+        body = self.rfile.read(length) if length > 0 else b""
+        try:
+            status, payload = dispatch(server.orchestrator, method, self.path, body)
+        except Exception as e:  # noqa: BLE001 — the control plane must stay up
+            sys.stderr.write(f"orchestrator: {method} {self.path} failed: {e!r}\n")
+            sys.stderr.flush()
+            status, payload = 500, {"error": f"internal error: {e}"}
+        data = json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def do_GET(self) -> None:
+        self._serve("GET")
+
+    def do_POST(self) -> None:
+        self._serve("POST")
+
+    def do_PUT(self) -> None:
+        self._serve("PUT")
+
+    def do_DELETE(self) -> None:
+        self._serve("DELETE")
+
+
+class ControlPlaneServer(socketserver.ThreadingMixIn, http.server.HTTPServer):
+    """Threading HTTP server that carries the orchestrator for its handlers."""
+
+    daemon_threads = True
+    allow_reuse_address = True
+
+    def __init__(self, address: tuple[str, int], orchestrator: Orchestrator) -> None:
+        self.orchestrator = orchestrator
+        super().__init__(address, Handler)
+
+
+def make_server(
+    orchestrator: Orchestrator, host: str = "127.0.0.1", port: int = 0
+) -> ControlPlaneServer:
+    """Build (but do not start) a control-plane server. `port=0` binds an
+    ephemeral port — read `server.server_address` for the actual one."""
+    return ControlPlaneServer((host, port), orchestrator)
+
+
+__all__ = ["dispatch", "Handler", "ControlPlaneServer", "make_server", "Json"]

bot_bottle/orchestrator/docker_broker.py

@@ -0,0 +1,83 @@
+"""Docker launch broker (PRD 0070) — the first *real* LaunchBroker.
+
+On a verified launch request it starts a Docker container; on teardown it
+removes it. This proves the orchestrator -> backend seam on the cheapest
+backend (the gateway is already containers). Only the request's
+static ids/flags reach `docker`, so nothing free-form crosses the boundary.
+
+Slice 3 launches a single container from the request's `image_ref`, named
+after the bottle id and labelled for cleanup. Wiring the full agent +
+gateway (networks, mounts, the consolidated gateway) is a later
+slice — this is the seam, not the finished launcher.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+from ..docker_cmd import run_docker
+from .broker import LaunchBroker, LaunchRequest
+
+CONTAINER_PREFIX = "bot-bottle-orch-"
+BOTTLE_ID_LABEL = "bot-bottle-bottle-id"
+
+
+class DockerBrokerError(Exception):
+    """A brokered docker launch/teardown failed (non-zero `docker` exit)."""
+
+
+def container_name(bottle_id: str) -> str:
+    """Deterministic container name for a bottle."""
+    return f"{CONTAINER_PREFIX}{bottle_id}"
+
+
+def run_argv(req: LaunchRequest) -> list[str]:
+    """`docker run` argv for a launch request — built only from its static
+    fields, so it can't be coerced into an arbitrary command."""
+    return [
+        "docker", "run", "--detach",
+        "--name", container_name(req.bottle_id),
+        "--label", f"{BOTTLE_ID_LABEL}={req.bottle_id}",
+        req.image_ref,
+    ]
+
+
+def rm_argv(req: LaunchRequest) -> list[str]:
+    """`docker rm --force` argv to tear a bottle's container down."""
+    return ["docker", "rm", "--force", container_name(req.bottle_id)]
+
+
+class DockerBroker(LaunchBroker):
+    """A `LaunchBroker` that runs / removes a Docker container per bottle.
+    Provenance + schema verification are inherited from `LaunchBroker`."""
+
+    def _docker(self, argv: list[str]) -> subprocess.CompletedProcess[str]:
+        return run_docker(argv)
+
+    def _launch(self, req: LaunchRequest) -> None:
+        if not req.image_ref:
+            raise DockerBrokerError(f"launch request for {req.bottle_id} has no image_ref")
+        proc = self._docker(run_argv(req))
+        if proc.returncode != 0:
+            raise DockerBrokerError(
+                f"docker run failed for {req.bottle_id}: {proc.stderr.strip()}"
+            )
+
+    def _teardown(self, req: LaunchRequest) -> None:
+        proc = self._docker(rm_argv(req))
+        # Idempotent: an already-absent container is a successful teardown.
+        if proc.returncode != 0 and "No such container" not in proc.stderr:
+            raise DockerBrokerError(
+                f"docker rm failed for {req.bottle_id}: {proc.stderr.strip()}"
+            )
+
+
+__all__ = [
+    "DockerBroker",
+    "DockerBrokerError",
+    "container_name",
+    "run_argv",
+    "rm_argv",
+    "CONTAINER_PREFIX",
+    "BOTTLE_ID_LABEL",
+]

bot_bottle/orchestrator/gateway.py

@@ -0,0 +1,228 @@
+"""The consolidated per-host gateway (PRD 0070).
+
+The core consolidation win: **one** persistent gateway per host, shared by
+every bottle, instead of a gateway per bottle. It's safe to share
+because the attribution invariant (source IP + identity token, see
+`registry`) lets the gateway attribute each request to the right bottle —
+so per-bottle policy lives in one long-lived process keyed on who's calling.
+
+`Gateway` is the backend-neutral lifecycle contract (mirrors `LaunchBroker`):
+ensure the single instance is up, report it, tear it down. `DockerGateway`
+is the docker implementation; a firecracker gateway VM slots in later.
+
+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 bottle
+launches never spawn N gateways.
+"""
+
+from __future__ import annotations
+
+import abc
+import os
+import time
+from pathlib import Path
+
+from ..docker_cmd import run_docker
+
+# The gateway's mitmproxy writes its CA a beat after the container starts, so
+# reads poll for it rather than assuming it's there on a fresh launch.
+_CA_POLL_SECONDS = 0.5
+DEFAULT_CA_TIMEOUT_SECONDS = 30.0
+
+GATEWAY_NAME = "bot-bottle-orch-gateway"
+GATEWAY_LABEL = "bot-bottle-orch-gateway=1"
+# The single user-defined network the gateway and every agent bottle share.
+# Agents attach here with a pinned IP and reach the gateway's egress /
+# git-http / supervise ports by its address — no host port publishing, and
+# the source IP the gateway attributes by is the address on this network.
+GATEWAY_NETWORK = "bot-bottle-gateway"
+
+# mitmproxy's CA dir in the bundle. A persistent named volume here keeps the
+# gateway's self-generated CA STABLE across container recreation — every agent
+# installs this one CA to trust the shared gateway's TLS interception, so it
+# must not rotate when the gateway restarts.
+MITMPROXY_HOME = "/home/mitmproxy/.mitmproxy"
+GATEWAY_CA_VOLUME = "bot-bottle-gateway-mitmproxy"
+GATEWAY_CA_CERT = f"{MITMPROXY_HOME}/mitmproxy-ca-cert.pem"
+
+# The gateway data-plane image + its Dockerfile. Kept as a local constant
+# rather than imported from the backend layer, 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_GATEWAY_IMAGE.
+GATEWAY_IMAGE = os.environ.get("BOT_BOTTLE_GATEWAY_IMAGE", "bot-bottle-gateway:latest")
+GATEWAY_DOCKERFILE = "Dockerfile.gateway"
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+class GatewayError(Exception):
+    """The shared gateway failed to build/start/stop (non-zero `docker` exit)."""
+
+
+class Gateway(abc.ABC):
+    """Lifecycle of the single per-host gateway. Backend-neutral."""
+
+    name: str
+
+    def ensure_built(self) -> None:
+        """Ensure the gateway'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 gateway if it isn't already up. Idempotent: a no-op
+        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:
+        """True iff the gateway instance is currently up."""
+
+    @abc.abstractmethod
+    def stop(self) -> None:
+        """Remove the gateway. Idempotent — absent is success."""
+
+
+class DockerGateway(Gateway):
+    """The consolidated gateway as a single, fixed-name Docker container.
+
+    `image_ref` defaults to the gateway data-plane image; `ensure_built`
+    builds it from `Dockerfile.gateway` 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 = GATEWAY_IMAGE,
+        *,
+        name: str = GATEWAY_NAME,
+        network: str = GATEWAY_NETWORK,
+        orchestrator_url: str = "",
+        build_context: Path | None = None,
+        dockerfile: str | None = GATEWAY_DOCKERFILE,
+    ) -> None:
+        self.image_ref = image_ref
+        self.name = name
+        self.network = network
+        # The control-plane URL the gateway's data plane resolves per bottle
+        # against — reached by container name over docker DNS on the shared
+        # network (container↔container, no host firewall). Empty → single-tenant.
+        self._orchestrator_url = orchestrator_url
+        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, **cache-aware** — cheap
+        (a cache check) when nothing changed, a real rebuild when the flat
+        sources (egress addon / git-http / policy_resolver / supervise) moved.
+
+        This deliberately builds every time rather than build-if-missing: the
+        per-bottle model kept the image fresh via compose's `build:` on up, and
+        a stale image silently runs the OLD single-tenant daemons. No-op only
+        when no dockerfile is configured (a pre-pulled image). BOT_BOTTLE_NO_CACHE
+        forces a full rebuild (parity with `start --no-cache`)."""
+        if self._dockerfile is None:
+            return
+        argv = ["docker", "build", "-t", self.image_ref,
+                "-f", str(self._build_context / self._dockerfile),
+                str(self._build_context)]
+        if os.environ.get("BOT_BOTTLE_NO_CACHE"):
+            argv.insert(2, "--no-cache")
+        proc = run_docker(argv)
+        if proc.returncode != 0:
+            raise GatewayError(f"gateway image build failed: {proc.stderr.strip()}")
+
+    def is_running(self) -> bool:
+        proc = run_docker([
+            "docker", "ps",
+            "--filter", f"name=^{self.name}$",
+            "--filter", "status=running",
+            "--format", "{{.Names}}",
+        ])
+        return self.name in proc.stdout.split()
+
+    def _running_image_is_current(self) -> bool:
+        """True iff the running gateway was created from the *current*
+        `image_ref`. When `ensure_built` rebuilds the image (a source change),
+        the running container is still the OLD image running the OLD flat
+        daemons — so this is how a rebuild actually takes effect: a mismatch
+        means recreate."""
+        running = run_docker(["docker", "inspect", "--format", "{{.Image}}", self.name])
+        current = run_docker(["docker", "image", "inspect", "--format", "{{.Id}}", self.image_ref])
+        if running.returncode != 0 or current.returncode != 0:
+            return True  # can't compare → don't churn a working container
+        return running.stdout.strip() == current.stdout.strip()
+
+    def _ensure_network(self) -> None:
+        """Create the shared gateway network if it doesn't exist. Idempotent —
+        a concurrent create loses harmlessly (the loser sees 'already exists').
+        Docker picks the subnet; the launcher reads it back to allocate IPs."""
+        if run_docker(["docker", "network", "inspect", self.network]).returncode == 0:
+            return
+        proc = run_docker(["docker", "network", "create", self.network])
+        if proc.returncode != 0 and "already exists" not in proc.stderr:
+            raise GatewayError(
+                f"gateway network {self.network} failed to create: {proc.stderr.strip()}"
+            )
+
+    def ensure_running(self) -> None:
+        # Recreate when the running container's image is stale (a rebuild),
+        # so source changes to the gateway's flat daemons take effect — not
+        # just when the container is absent.
+        if self.is_running() and self._running_image_is_current():
+            return
+        self._ensure_network()
+        # Clear any stale (stopped OR outdated-image) container holding the
+        # fixed name, then start fresh. `rm --force` on an absent name is a
+        # tolerated no-op.
+        run_docker(["docker", "rm", "--force", self.name])
+        argv = [
+            "docker", "run", "--detach",
+            "--name", self.name,
+            "--label", GATEWAY_LABEL,
+            "--network", self.network,
+            # Persist the self-generated CA so it survives restarts (agents
+            # trust it) — see GATEWAY_CA_VOLUME.
+            "--volume", f"{GATEWAY_CA_VOLUME}:{MITMPROXY_HOME}",
+        ]
+        if self._orchestrator_url:
+            # Makes the gateway's egress / git / supervise daemons multi-tenant:
+            # each request resolves source-IP -> policy against the control plane.
+            argv += ["--env", f"BOT_BOTTLE_ORCHESTRATOR_URL={self._orchestrator_url}"]
+        argv.append(self.image_ref)
+        proc = run_docker(argv)
+        if proc.returncode != 0:
+            raise GatewayError(f"gateway failed to start: {proc.stderr.strip()}")
+
+    def ca_cert_pem(self, *, timeout: float = DEFAULT_CA_TIMEOUT_SECONDS) -> str:
+        """The gateway's CA certificate (PEM) that agents install to trust its
+        TLS interception. mitmproxy generates it a moment after the container
+        starts, so this **polls** for it (up to `timeout`) rather than assuming
+        it's already there on a fresh gateway — raising only if it never
+        appears."""
+        deadline = time.monotonic() + timeout
+        while True:
+            proc = run_docker(["docker", "exec", self.name, "cat", GATEWAY_CA_CERT])
+            if proc.returncode == 0 and proc.stdout.strip():
+                return proc.stdout
+            if time.monotonic() >= deadline:
+                raise GatewayError(
+                    f"gateway CA cert not available after {timeout:g}s: "
+                    f"{proc.stderr.strip() or 'empty'}"
+                )
+            time.sleep(_CA_POLL_SECONDS)
+
+    def stop(self) -> None:
+        proc = run_docker(["docker", "rm", "--force", self.name])
+        if proc.returncode != 0 and "No such container" not in proc.stderr:
+            raise GatewayError(f"gateway failed to stop: {proc.stderr.strip()}")
+
+
+__all__ = [
+    "Gateway", "DockerGateway", "GatewayError",
+    "GATEWAY_NAME", "GATEWAY_LABEL", "GATEWAY_IMAGE", "GATEWAY_NETWORK",
+    "GATEWAY_CA_VOLUME", "GATEWAY_CA_CERT",
+]

bot_bottle/orchestrator/lifecycle.py

@@ -0,0 +1,248 @@
+"""Orchestrator + gateway lifecycle (PRD 0070, docker slice).
+
+Runs the orchestrator control plane **as a container** on the shared gateway
+network, alongside the gateway container. This is the PRD's "virtualize the
+orchestrator": container↔container between the gateway and the orchestrator
+avoids the host firewall (which drops container→host traffic), and the gateway
+reaches the control plane by container name over docker DNS. The host CLI
+reaches it via a published loopback port.
+
+The orchestrator runs with the **register-only broker** — the *backend*
+launches agent containers (compose), so the orchestrator needs no docker
+socket. That keeps this control-plane container unprivileged; the host manages
+both containers. `ensure_running` is an idempotent singleton (fixed container
+names + the published port).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from .. import log
+from ..docker_cmd import run_docker
+from ..paths import bot_bottle_root
+from .gateway import GATEWAY_IMAGE, GATEWAY_NETWORK, DockerGateway, GatewayError
+
+DEFAULT_PORT = 8099
+ORCHESTRATOR_NAME = "bot-bottle-orchestrator"
+ORCHESTRATOR_LABEL = "bot-bottle-orchestrator=1"
+# The control-plane's own runtime image — lean (python + the stdlib-only
+# `bot_bottle` package, bind-mounted at run time), distinct from the heavy
+# gateway data-plane image it used to borrow (#384). Env override for
+# operators pinning a published build.
+ORCHESTRATOR_IMAGE = os.environ.get(
+    "BOT_BOTTLE_ORCHESTRATOR_IMAGE", "bot-bottle-orchestrator:latest"
+)
+ORCHESTRATOR_DOCKERFILE = "Dockerfile.orchestrator"
+# Baked onto the container as a label so `ensure_running` can tell whether the
+# running process is executing the *current* bind-mounted source — see
+# `_source_hash`.
+ORCHESTRATOR_SOURCE_HASH_LABEL = "bot-bottle-orchestrator-source-hash"
+
+# The repo root is bind-mounted into the control-plane container so
+# `python -m bot_bottle.orchestrator` resolves the package (the orchestrator
+# is stdlib-only, so the lean orchestrator image's python is enough).
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+_APP_DIR = "/app"
+_ROOT_IN_CONTAINER = "/bot-bottle-root"
+
+_HEALTH_POLL_SECONDS = 0.25
+DEFAULT_STARTUP_TIMEOUT_SECONDS = 45.0
+_HEALTH_REQUEST_TIMEOUT_SECONDS = 1.0
+
+
+class OrchestratorStartError(RuntimeError):
+    """The orchestrator container did not become healthy within the timeout."""
+
+
+def _source_hash(repo_root: Path) -> str:
+    """Content hash of the orchestrator's bind-mounted Python source (the
+    `bot_bottle` package the control-plane process imports). This only
+    changes when the code that would actually run inside the container
+    changes — `ensure_running` recreates the container on a mismatch and
+    otherwise leaves a healthy one alone, so a bottle launch that isn't
+    accompanied by a code change doesn't restart the process and drop every
+    *other* active bottle's in-memory egress tokens (`Orchestrator._tokens`
+    in `service.py`, never persisted to disk by design)."""
+    h = hashlib.sha256()
+    for path in sorted((repo_root / "bot_bottle").rglob("*.py")):
+        h.update(str(path.relative_to(repo_root)).encode())
+        h.update(path.read_bytes())
+    return h.hexdigest()
+
+
+class OrchestratorService:
+    """Manages the orchestrator control-plane container + the shared gateway.
+    Callers only need `ensure_running()` + `url`."""
+
+    def __init__(
+        self,
+        *,
+        port: int = DEFAULT_PORT,
+        network: str = GATEWAY_NETWORK,
+        image: str = ORCHESTRATOR_IMAGE,
+        gateway_image: str = GATEWAY_IMAGE,
+        repo_root: Path = _REPO_ROOT,
+        host_root: Path | None = None,
+    ) -> None:
+        self.port = port
+        self.network = network
+        # Two distinct images (#384): `image` is the lean control-plane
+        # runtime this container runs; `_gateway_image` is the heavy egress /
+        # git-gate / supervise data plane the gateway container runs. They
+        # were one conflated image before the split.
+        self.image = image
+        self._gateway_image = gateway_image
+        self._repo_root = repo_root
+        self._host_root = host_root or bot_bottle_root()
+
+    @property
+    def url(self) -> str:
+        """Host-side control-plane URL (published loopback port)."""
+        return f"http://127.0.0.1:{self.port}"
+
+    @property
+    def internal_url(self) -> str:
+        """Control-plane URL as the gateway container reaches it — by name over
+        docker DNS on the shared network. This is the gateway's
+        BOT_BOTTLE_ORCHESTRATOR_URL."""
+        return f"http://{ORCHESTRATOR_NAME}:{self.port}"
+
+    def is_healthy(self, *, timeout: float = _HEALTH_REQUEST_TIMEOUT_SECONDS) -> bool:
+        try:
+            with urllib.request.urlopen(f"{self.url}/health", timeout=timeout) as resp:
+                return resp.status == 200
+        except (urllib.error.URLError, TimeoutError, OSError):
+            return False
+
+    def _container_running(self, name: str) -> bool:
+        proc = run_docker(["docker", "ps", "--filter", f"name=^/{name}$", "--format", "{{.Names}}"])
+        return name in proc.stdout.split()
+
+    def _run_orchestrator_container(self, source_hash: str) -> None:
+        """Start the control-plane container (idempotent: clears a stale
+        fixed-name container first). Register-only broker → no docker socket.
+        Labels the container with `source_hash` so a later `ensure_running`
+        can detect a real code change (see `_source_hash`)."""
+        run_docker(["docker", "rm", "--force", ORCHESTRATOR_NAME])
+        proc = run_docker([
+            "docker", "run", "--detach",
+            "--name", ORCHESTRATOR_NAME,
+            "--label", ORCHESTRATOR_LABEL,
+            "--label", f"{ORCHESTRATOR_SOURCE_HASH_LABEL}={source_hash}",
+            "--network", self.network,
+            # Host CLI reaches the control plane here; bound to loopback so it
+            # is not exposed on the host's external interfaces.
+            "--publish", f"127.0.0.1:{self.port}:{self.port}",
+            "--volume", f"{self._repo_root}:{_APP_DIR}:ro",
+            "--workdir", _APP_DIR,
+            # Persist the registry DB on the host (sole-owner: only the
+            # orchestrator opens bot-bottle.db).
+            "--volume", f"{self._host_root}:{_ROOT_IN_CONTAINER}",
+            "--env", f"BOT_BOTTLE_ROOT={_ROOT_IN_CONTAINER}",
+            "--entrypoint", "python3",
+            self.image,
+            "-m", "bot_bottle.orchestrator",
+            "--host", "0.0.0.0", "--port", str(self.port), "--broker", "stub",
+        ])
+        if proc.returncode != 0:
+            raise OrchestratorStartError(
+                f"orchestrator container failed to start: {proc.stderr.strip()}"
+            )
+
+    def _gateway(self) -> DockerGateway:
+        return DockerGateway(
+            self._gateway_image, network=self.network, orchestrator_url=self.internal_url
+        )
+
+    def _ensure_orchestrator_image(self) -> None:
+        """Build the lean control-plane image from `Dockerfile.orchestrator`
+        when it's missing (#384). Cheap — a `FROM python:*-slim` base with no
+        deps to install, so the layer cache makes rebuilds a no-op. Unlike the
+        gateway image this is build-if-missing, not build-every-time: the
+        control plane bind-mounts its source, so a code change is caught by the
+        source-hash recreate (below), not by an image rebuild."""
+        if run_docker(["docker", "image", "inspect", self.image]).returncode == 0:
+            return
+        argv = ["docker", "build", "-t", self.image,
+                "-f", str(self._repo_root / ORCHESTRATOR_DOCKERFILE),
+                str(self._repo_root)]
+        if os.environ.get("BOT_BOTTLE_NO_CACHE"):
+            argv.insert(2, "--no-cache")
+        proc = run_docker(argv)
+        if proc.returncode != 0:
+            raise GatewayError(
+                f"orchestrator image build failed: {proc.stderr.strip()}"
+            )
+
+    def _orchestrator_source_current(self, current_hash: str) -> bool:
+        """True iff the running orchestrator container was created from the
+        *current* bind-mounted source. Mirrors `DockerGateway`'s
+        image-staleness check, but by content hash rather than image id since
+        the orchestrator runs bind-mounted source, not a built image."""
+        if not self._container_running(ORCHESTRATOR_NAME):
+            return False
+        proc = run_docker([
+            "docker", "inspect", "--format",
+            "{{ index .Config.Labels \"" + ORCHESTRATOR_SOURCE_HASH_LABEL + "\" }}",
+            ORCHESTRATOR_NAME,
+        ])
+        if proc.returncode != 0:
+            return True  # can't compare -> don't churn a working container
+        return proc.stdout.strip() == current_hash
+
+    def ensure_running(
+        self, *, startup_timeout: float = DEFAULT_STARTUP_TIMEOUT_SECONDS,
+    ) -> str:
+        """Ensure the control plane + shared gateway are up; return the host
+        control-plane URL. Idempotent — a healthy control plane running
+        current code and a running gateway are left untouched. Raises
+        `OrchestratorStartError` on timeout."""
+        gateway = self._gateway()
+        gateway.ensure_built()  # rebuild the bundle image on a source change
+        gateway.ensure_running()  # creates the shared network + (re)starts gateway
+
+        # Recreate the orchestrator container only when its bind-mounted
+        # source has actually changed since it started — its Python process
+        # loaded that code at startup and won't reload, so a stale container
+        # would keep running OLD control-plane code. Recreating on *every*
+        # launch (the prior behaviour) would drop every other active
+        # bottle's in-memory egress tokens each time a new bottle starts,
+        # since the orchestrator process holds them only in memory (#381).
+        current_hash = _source_hash(self._repo_root)
+        if self.is_healthy() and self._orchestrator_source_current(current_hash):
+            return self.url
+
+        self._ensure_orchestrator_image()
+        log.info("starting orchestrator container", context={"name": ORCHESTRATOR_NAME})
+        self._run_orchestrator_container(current_hash)
+
+        deadline = time.monotonic() + startup_timeout
+        while time.monotonic() < deadline:
+            if self.is_healthy():
+                log.info("orchestrator healthy", context={"url": self.url})
+                return self.url
+            time.sleep(_HEALTH_POLL_SECONDS)
+        raise OrchestratorStartError(
+            f"orchestrator at {self.url} did not become healthy within {startup_timeout:g}s"
+        )
+
+    def stop(self) -> None:
+        """Remove the orchestrator + gateway containers (idempotent)."""
+        run_docker(["docker", "rm", "--force", ORCHESTRATOR_NAME])
+        self._gateway().stop()
+
+
+__all__ = [
+    "OrchestratorService",
+    "OrchestratorStartError",
+    "ORCHESTRATOR_NAME",
+    "ORCHESTRATOR_IMAGE",
+    "DEFAULT_PORT",
+    "DEFAULT_STARTUP_TIMEOUT_SECONDS",
+]

bot_bottle/orchestrator/registration.py

@@ -0,0 +1,57 @@
+"""Consolidated registration inputs (PRD 0070, docker slice).
+
+Bridges the existing per-bottle `prepare` output to the consolidated
+registry: turns a prepared bottle's egress plan into the backend-neutral
+inputs `Orchestrator.launch_bottle` takes — the egress **policy** blob and
+launch **metadata**.
+
+The policy blob is the exact routes YAML the per-bottle egress daemon used
+to read from a file; in the consolidated model the multi-tenant gateway's
+`PolicyResolver` fetches it from the registry per request (keyed by source
+IP) instead. Same render, so consolidated and single-tenant egress apply
+byte-identical policy — a bottle's allow-list doesn't change when it moves
+onto the shared gateway.
+
+Host-side glue (imports `bot_bottle.egress`), used by the launch path — not
+by the lean orchestrator control-plane process itself.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from ..egress import EgressPlan, egress_render_routes
+
+
+@dataclass(frozen=True)
+class RegistrationInputs:
+    """What `Orchestrator.launch_bottle` needs to register a bottle, derived
+    from its prepared plan. `policy` is served verbatim by the gateway's
+    `/resolve`; `metadata` is opaque forward-compat state — it carries the
+    human slug so the console / supervise can show a name, not just the
+    minted bottle id."""
+
+    policy: str
+    metadata: str
+
+
+def egress_policy(plan: EgressPlan) -> str:
+    """The bottle's egress policy blob: the routes YAML the gateway serves
+    and the addon parses with `load_config`. Identical to the per-bottle
+    `routes.yaml` render, so the consolidated path applies the same
+    allow-list."""
+    return egress_render_routes(plan.routes, log=plan.log)
+
+
+def registration_inputs(plan: EgressPlan) -> RegistrationInputs:
+    """Assemble the orchestrator registration inputs from a prepared egress
+    plan. `metadata` records the slug so the shared registry can map a minted
+    bottle id back to its human name."""
+    return RegistrationInputs(
+        policy=egress_policy(plan),
+        metadata=json.dumps({"slug": plan.slug}),
+    )
+
+
+__all__ = ["RegistrationInputs", "egress_policy", "registration_inputs"]

bot_bottle/orchestrator/registry.py

@@ -0,0 +1,265 @@
+"""Orchestrator bottle registry — the per-host runtime-state store (PRD 0070).
+
+SQLite-backed registry mapping each live bottle to its source IP and
+per-bottle identity token, plus the **fail-closed attribution** the data
+plane relies on: a request is attributed to a bottle only when its source
+IP *and* its identity token both match a single active record.
+
+The registry co-tenants the shared host `bot-bottle.db` (the `DbStore`
+framework namespaces each store by `schema_key`), so all bot-bottle
+runtime state lives in one queryable file — one place to back up, inspect,
+and integrate a console against.
+
+This is the "runtime state" tier of PRD 0070 (leases / approvals /
+registry) — deliberately NOT config (which stays declarative under
+`~/.bot-bottle/`) and NOT the build-time constants (a flat file). It is the
+source of truth the orchestrator sweeps on restart to re-adopt running
+bottles, so it lives in a durable store rather than process memory.
+
+Attribution combines two independent signals, and needs both:
+
+  * source IP  — the network-layer invariant (on Firecracker the `/31` TAP
+    + nft make it unspoofable by construction; weaker on other backends).
+  * identity token — an application-layer per-bottle secret, defence in
+    depth that doesn't lean on network anti-spoof. A bottle can only ever
+    prove it is *itself* (it can't learn another bottle's token), so a
+    hostile agent gains nothing by presenting it.
+"""
+
+from __future__ import annotations
+
+import hmac
+import secrets
+import sqlite3
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..db_store import DbStore
+from ..migrations import TableMigrations
+from ..paths import host_db_path
+
+# 256 bits of urandom, URL-safe — unguessable per-bottle identity token.
+IDENTITY_TOKEN_BYTES = 32
+
+
+def new_identity_token() -> str:
+    """A fresh per-bottle identity token (PRD 0070 attribution defence)."""
+    return secrets.token_urlsafe(IDENTITY_TOKEN_BYTES)
+
+
+def default_db_path() -> Path:
+    """The shared host state DB (`bot-bottle.db`) — all bot-bottle runtime
+    state in one file, co-tenanted via schema_key. Host-resident so it
+    survives orchestrator restarts (re-adoption sweeps it)."""
+    return host_db_path()
+
+
+@dataclass(frozen=True)
+class BottleRecord:
+    """One live bottle in the registry."""
+
+    bottle_id: str
+    source_ip: str
+    identity_token: str
+    state: str = "active"
+    created_at: float = 0.0
+    # Opaque JSON blob for forward-compat (pool slot, ...) — the registry
+    # doesn't interpret it, so new fields need no migration.
+    metadata: str = ""
+    # The bottle's gateway policy (opaque JSON — egress allowlist / routes /
+    # git config). The registry stores and serves it verbatim, keyed by
+    # source IP; the multi-tenant gateway interprets it.
+    policy: str = ""
+
+    def redacted(self) -> dict[str, object]:
+        """Public view for listing — never exposes the identity token."""
+        return {
+            "bottle_id": self.bottle_id,
+            "source_ip": self.source_ip,
+            "state": self.state,
+            "created_at": self.created_at,
+            "metadata": self.metadata,
+            "policy": self.policy,
+        }
+
+
+_MIGRATIONS = TableMigrations(
+    "orchestrator_registry",
+    [
+        # v1 — the live bottle registry.
+        """
+        CREATE TABLE IF NOT EXISTS orchestrator_bottles (
+            bottle_id      TEXT PRIMARY KEY,
+            source_ip      TEXT NOT NULL,
+            identity_token TEXT NOT NULL,
+            state          TEXT NOT NULL DEFAULT 'active',
+            created_at     REAL NOT NULL,
+            metadata       TEXT NOT NULL DEFAULT ''
+        )
+        """,
+        # source_ip is the data-plane attribution key — index it, and make
+        # the "one active bottle per source IP" check cheap.
+        "CREATE INDEX IF NOT EXISTS idx_orchestrator_bottles_source_ip "
+        "ON orchestrator_bottles (source_ip)",
+        # v3 — per-bottle policy (opaque JSON the gateway interprets): the
+        # egress allowlist / routes / git config selected by source IP. The
+        # multi-tenant gateway resolves it per request via `attribute`.
+        "ALTER TABLE orchestrator_bottles ADD COLUMN policy TEXT NOT NULL DEFAULT ''",
+    ],
+)
+
+
+def _row_to_record(row: sqlite3.Row) -> BottleRecord:
+    """Build a BottleRecord from a registry row."""
+    return BottleRecord(
+        bottle_id=row["bottle_id"],
+        source_ip=row["source_ip"],
+        identity_token=row["identity_token"],
+        state=row["state"],
+        created_at=row["created_at"],
+        metadata=row["metadata"],
+        policy=row["policy"],
+    )
+
+
+class RegistryStore(DbStore):
+    """SQLite-backed registry of live bottles + fail-closed attribution."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        super().__init__(db_path or default_db_path(), _MIGRATIONS)
+
+    def _connect(self) -> sqlite3.Connection:
+        """Open a connection with a busy timeout for the shared DB."""
+        conn = super()._connect()
+        # The registry co-tenants the shared bot-bottle.db, so a busy_timeout
+        # rides out brief lock contention with the other stores. WAL for the
+        # shared DB is a deliberate future change (it affects supervise/audit
+        # and is finicky over guest shares) — not flipped here.
+        conn.execute("PRAGMA busy_timeout=5000")
+        return conn
+
+    def register(
+        self,
+        source_ip: str,
+        *,
+        bottle_id: str | None = None,
+        identity_token: str | None = None,
+        metadata: str = "",
+        policy: str = "",
+    ) -> BottleRecord:
+        """Register (or replace) a bottle. Mints a bottle_id / identity token
+        when not supplied. Live — this is the control-plane reload path.
+
+        Supersedes any *other* active bottle at the same source IP first:
+        `by_source_ip` fail-closes on ambiguity (>1 active row → None), so a
+        leftover row at a reused IP — from an untorn-down bottle, crash
+        recovery, or a persisted DB — would otherwise *brick* the new bottle's
+        attribution. The new registration is authoritative for its IP; the
+        stale rows go. INSERT OR REPLACE handles a same-`bottle_id` reload in
+        place (its own row is exempt from the sweep)."""
+        rec = BottleRecord(
+            bottle_id=bottle_id or secrets.token_hex(8),
+            source_ip=source_ip,
+            identity_token=identity_token or new_identity_token(),
+            state="active",
+            created_at=time.time(),
+            metadata=metadata,
+            policy=policy,
+        )
+        with self._connect() as conn:
+            conn.execute(
+                "DELETE FROM orchestrator_bottles "
+                "WHERE source_ip = ? AND state = 'active' AND bottle_id != ?",
+                (rec.source_ip, rec.bottle_id),
+            )
+            conn.execute(
+                "INSERT OR REPLACE INTO orchestrator_bottles "
+                "(bottle_id, source_ip, identity_token, state, created_at, metadata, policy) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (
+                    rec.bottle_id,
+                    rec.source_ip,
+                    rec.identity_token,
+                    rec.state,
+                    rec.created_at,
+                    rec.metadata,
+                    rec.policy,
+                ),
+            )
+        self._chmod()
+        return rec
+
+    def set_policy(self, bottle_id: str, policy: str) -> bool:
+        """Update a bottle's policy in place (live reload). Returns True if
+        the bottle exists."""
+        with self._connect() as conn:
+            cur = conn.execute(
+                "UPDATE orchestrator_bottles SET policy = ? WHERE bottle_id = ?",
+                (policy, bottle_id),
+            )
+        self._chmod()
+        return cur.rowcount > 0
+
+    def deregister(self, bottle_id: str) -> bool:
+        """Remove a bottle. Returns True if a row was deleted."""
+        with self._connect() as conn:
+            cur = conn.execute(
+                "DELETE FROM orchestrator_bottles WHERE bottle_id = ?", (bottle_id,)
+            )
+            return cur.rowcount > 0
+
+    def get(self, bottle_id: str) -> BottleRecord | None:
+        """Return the bottle by id, or None if absent."""
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT * FROM orchestrator_bottles WHERE bottle_id = ?", (bottle_id,)
+            ).fetchone()
+        return _row_to_record(row) if row else None
+
+    def all(self) -> list[BottleRecord]:
+        """Every registered bottle, oldest first."""
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT * FROM orchestrator_bottles ORDER BY created_at"
+            ).fetchall()
+        return [_row_to_record(r) for r in rows]
+
+    def by_source_ip(self, source_ip: str) -> BottleRecord | None:
+        """Network-layer attribution: the single active bottle at this source
+        IP, or None if unknown or ambiguous (more than one — a
+        misconfiguration). Safe as the *sole* attributor only where the
+        source IP is unspoofable (Firecracker `/31` + nft) and the control
+        plane is reachable only by the trusted gateway; pair with the
+        identity token (`attribute`) elsewhere."""
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT * FROM orchestrator_bottles "
+                "WHERE source_ip = ? AND state = 'active'",
+                (source_ip,),
+            ).fetchall()
+        if len(rows) != 1:
+            return None
+        return _row_to_record(rows[0])
+
+    def attribute(self, source_ip: str, identity_token: str) -> BottleRecord | None:
+        """Fail-closed attribution: `by_source_ip` AND a matching identity
+        token (constant-time). Either signal alone is insufficient here — an
+        unknown/ambiguous IP, an empty token, or a token mismatch all deny."""
+        if not identity_token:
+            return None
+        rec = self.by_source_ip(source_ip)
+        if rec is None:
+            return None
+        if not hmac.compare_digest(rec.identity_token, identity_token):
+            return None
+        return rec
+
+
+__all__ = [
+    "BottleRecord",
+    "RegistryStore",
+    "new_identity_token",
+    "default_db_path",
+    "IDENTITY_TOKEN_BYTES",
+]

bot_bottle/orchestrator/service.py

@@ -0,0 +1,138 @@
+"""The per-host orchestrator core (PRD 0070).
+
+`Orchestrator` is the single backend-neutral object the control plane talks
+to: it owns the registry (runtime state) and brokers agent launches. It
+never branches on backend — the `LaunchBroker` abstracts the backend-native
+launch, so this same object drives docker / firecracker / apple once a real
+broker is wired in.
+
+Launch lifecycle:
+
+  * `launch_bottle` mints the bottle (registry: source IP + identity
+    token), sends a *signed, structured* launch request through the broker,
+    and returns the record. If the broker rejects/fails, the registry entry
+    is rolled back so a failed launch leaves no orphan.
+  * `teardown_bottle` sends a signed teardown request, then deregisters.
+"""
+
+from __future__ import annotations
+
+from .broker import LaunchBroker, LaunchRequest, sign_request
+from .registry import BottleRecord, RegistryStore
+from .gateway import Gateway
+
+
+class Orchestrator:
+    """Owns the registry + brokers launches, and manages the single
+    consolidated per-host gateway. Backend-neutral (broker and gateway
+    abstract the backend-native pieces)."""
+
+    def __init__(
+        self,
+        registry: RegistryStore,
+        broker: LaunchBroker,
+        sign_secret: bytes,
+        gateway: Gateway | None = None,
+    ) -> None:
+        self.registry = registry
+        self._broker = broker
+        self._secret = sign_secret
+        self._gateway = gateway
+        # Per-bottle egress auth tokens (env_name -> value), keyed by bottle_id.
+        # Held **in memory only** — never written to the registry DB — so the
+        # gateway can inject each bottle's upstream credential without secrets
+        # at rest. Lost on restart (re-launch re-registers them); the future
+        # SecretProvider (#355) replaces this with per-request minting.
+        self._tokens: dict[str, dict[str, str]] = {}
+
+    def launch_bottle(
+        self,
+        source_ip: str,
+        *,
+        image_ref: str = "",
+        slot: int | None = None,
+        metadata: str = "",
+        policy: str = "",
+        tokens: dict[str, str] | None = None,
+    ) -> BottleRecord:
+        """Register a bottle (with its gateway policy + in-memory egress auth
+        tokens) and broker its launch. Rolls the registry entry back if the
+        launch doesn't take, so a failure leaves no orphan."""
+        rec = self.registry.register(source_ip, metadata=metadata, policy=policy)
+        if tokens:
+            self._tokens[rec.bottle_id] = dict(tokens)
+        req = LaunchRequest(
+            op="launch",
+            bottle_id=rec.bottle_id,
+            source_ip=source_ip,
+            image_ref=image_ref,
+            slot=slot,
+        )
+        launched = False
+        try:
+            self._broker.submit(sign_request(req, self._secret))
+            launched = True
+        finally:
+            if not launched:
+                self.registry.deregister(rec.bottle_id)
+                self._tokens.pop(rec.bottle_id, None)
+        return rec
+
+    def teardown_bottle(self, bottle_id: str) -> bool:
+        """Broker teardown then deregister. False if the bottle is unknown."""
+        rec = self.registry.get(bottle_id)
+        if rec is None:
+            return False
+        req = LaunchRequest(op="teardown", bottle_id=bottle_id, source_ip=rec.source_ip)
+        self._broker.submit(sign_request(req, self._secret))
+        self.registry.deregister(bottle_id)
+        self._tokens.pop(bottle_id, None)
+        return True
+
+    def tokens_for(self, bottle_id: str) -> dict[str, str]:
+        """The bottle's in-memory egress auth tokens (env_name -> value), or
+        empty. The gateway injects these per request; they are never
+        persisted."""
+        return dict(self._tokens.get(bottle_id, {}))
+
+    def attribute(self, source_ip: str, identity_token: str) -> BottleRecord | None:
+        """Fail-closed attribution (delegates to the registry)."""
+        return self.registry.attribute(source_ip, identity_token)
+
+    def resolve(self, source_ip: str, identity_token: str = "") -> BottleRecord | None:
+        """Resolve the bottle behind a request — the source-IP-keyed lookup
+        the multi-tenant gateway makes per request; the returned record
+        carries its `policy`. With a token, full attribution (source IP +
+        token); without, network-layer attribution by source IP alone
+        (valid where the IP is unspoofable and the control plane is
+        gateway-only)."""
+        if identity_token:
+            return self.registry.attribute(source_ip, identity_token)
+        return self.registry.by_source_ip(source_ip)
+
+    def set_policy(self, bottle_id: str, policy: str) -> bool:
+        """Update a bottle's gateway policy in place (live reload). False if
+        the bottle is unknown."""
+        return self.registry.set_policy(bottle_id, policy)
+
+    # --- consolidated gateway ----------------------------------------------
+
+    def ensure_gateway(self) -> None:
+        """Ensure the single per-host gateway is built and up (idempotent).
+        No-op when no gateway is configured."""
+        if self._gateway is not None:
+            self._gateway.ensure_built()
+            self._gateway.ensure_running()
+
+    def gateway_status(self) -> dict[str, object]:
+        """Report the shared gateway for the control plane / console."""
+        if self._gateway is None:
+            return {"configured": False}
+        return {
+            "configured": True,
+            "name": self._gateway.name,
+            "running": self._gateway.is_running(),
+        }
+
+
+__all__ = ["Orchestrator"]

bot_bottle/paths.py

@@ -0,0 +1,43 @@
+"""Foundational filesystem paths for bot-bottle.
+
+`bot_bottle_root()` is the app data root — state, queue, audit logs,
+git-gate keys, and the shared DB all live under it. It defaults to
+`~/.bot-bottle` and is overridable with the **`BOT_BOTTLE_ROOT`** env var.
+
+The env override is the single knob for redirecting the root: the test
+suite points it at a throwaway dir instead of monkey-patching the function
+(every module and every flat/package copy reads the same env var, so one
+override covers them all), and operators can relocate the root if needed.
+
+This module has no bot-bottle imports, so it is safe to import from any
+layer (and to COPY flat into the gateway).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# The single shared host state DB. All bot-bottle SQLite stores (supervise
+# queue, audit, the orchestrator registry) co-tenant this one file — the
+# TableMigrations schema_key namespaces each store's tables.
+HOST_DB_FILENAME = "bot-bottle.db"
+
+
+def bot_bottle_root() -> Path:
+    """The app data root — `$BOT_BOTTLE_ROOT` if set, else `~/.bot-bottle`."""
+    override = os.environ.get("BOT_BOTTLE_ROOT")
+    return Path(override) if override else Path.home() / ".bot-bottle"
+
+
+def host_db_path() -> Path:
+    """Path to the shared host state DB, `<root>/db/bot-bottle.db`.
+
+    Kept in its own `db/` subdirectory (not directly under the root) so a
+    backend that can only bind-mount *directories* can share this one file
+    with a gateway without exposing the root's other contents (git-gate
+    keys, per-bottle state, ...)."""
+    return bot_bottle_root() / "db" / HOST_DB_FILENAME
+
+
+__all__ = ["HOST_DB_FILENAME", "bot_bottle_root", "host_db_path"]

bot_bottle/policy_resolver.py

@@ -0,0 +1,128 @@
+"""Gateway-side per-client policy resolver (PRD 0070).
+
+The consolidated gateway serves every bottle from one process, so for each
+request it must apply the *calling* bottle's policy, selected by the source
+IP the attribution invariant makes unspoofable. This resolves that policy
+from the orchestrator's control plane (`POST /resolve`), keyed on the
+`(source_ip, identity_token)` pair.
+
+**Always fresh — no cache.** The resolver is called rarely enough that a
+round-trip doesn't matter, and correctness matters more than speed: every
+resolve reflects the orchestrator's *current* view, so a revocation, a
+policy change, or a bottle teardown the orchestrator knows about is honored
+immediately rather than lingering for a cache TTL. (If this ever becomes a
+hot path, add caching with orchestrator-driven invalidation — not a blind
+TTL.)
+
+**Fail-closed:** an unattributed client (the orchestrator answers `403`)
+resolves to `None`, and the caller (the egress addon, git-gate) must then
+deny — exactly as an unknown bottle should be treated. Orchestrator
+*errors* (unreachable / unexpected status) raise, so the caller can fail
+closed too rather than silently serving stale or empty policy.
+
+The resolved value is the policy blob the orchestrator stores verbatim; the
+consumer parses it (e.g. the egress addon's `load_config`). This module is
+stdlib-only and free of bot-bottle imports so it can be COPYed flat into
+the gateway.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+
+DEFAULT_TIMEOUT_SECONDS = 2.0
+
+
+class PolicyResolveError(RuntimeError):
+    """The orchestrator was unreachable or returned an unexpected status —
+    distinct from a clean `403` (unattributed), which returns None."""
+
+
+class PolicyResolver:
+    """Resolves each client's policy from the orchestrator, fresh per call."""
+
+    def __init__(self, base_url: str, *, timeout: float = DEFAULT_TIMEOUT_SECONDS) -> None:
+        self._base = base_url.rstrip("/")
+        self._timeout = timeout
+
+    def _post_resolve(self, source_ip: str, identity_token: str) -> dict[str, object] | None:
+        """The orchestrator's `/resolve` payload for this client, or None if
+        unattributed (a clean `403`). Raises `PolicyResolveError` on an
+        unreachable / unexpected-status / malformed response so every caller
+        can fail closed. Shared by `resolve` and `resolve_bottle_id`."""
+        body = json.dumps(
+            {"source_ip": source_ip, "identity_token": identity_token}
+        ).encode()
+        req = urllib.request.Request(
+            f"{self._base}/resolve", data=body, method="POST",
+            headers={"Content-Type": "application/json"},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                payload = json.loads(resp.read())
+        except urllib.error.HTTPError as e:
+            if e.code == 403:
+                return None  # unattributed → fail closed (caller denies)
+            raise PolicyResolveError(f"/resolve returned HTTP {e.code}") from e
+        except (urllib.error.URLError, TimeoutError, OSError, ValueError) as e:
+            raise PolicyResolveError(f"/resolve unreachable or malformed: {e}") from e
+        return payload if isinstance(payload, dict) else {}
+
+    def resolve(self, source_ip: str, identity_token: str = "") -> str | None:
+        """The calling bottle's policy blob, or None if unattributed. Always
+        fetches from the orchestrator so revocations / changes / teardowns
+        are honored immediately.
+
+        `identity_token` is optional *transitionally* — omitting it resolves
+        by source IP alone (the network-layer attribution, sound by
+        construction on Firecracker's `/31`+nft, weaker elsewhere). The
+        consolidated end state makes the token mandatory so the app-layer
+        defense is always enforced, not silently degraded; that flips at the
+        `/resolve` boundary once identity-token *delivery* lands (a PRD 0070
+        open question — we can't require what the agent can't yet present).
+        Raises `PolicyResolveError` if the orchestrator can't be reached."""
+        payload = self._post_resolve(source_ip, identity_token)
+        if payload is None:
+            return None
+        policy = payload.get("policy")
+        return policy if isinstance(policy, str) else ""
+
+    def resolve_bottle_id(self, source_ip: str, identity_token: str = "") -> str | None:
+        """The calling bottle's id, or None if unattributed. This is the
+        source-IP-keyed identity the git-gate uses to select the bottle's
+        repo namespace (there is no per-bottle policy blob to parse — the
+        bottle *is* the namespace). Same fail-closed contract as `resolve`."""
+        payload = self._post_resolve(source_ip, identity_token)
+        if payload is None:
+            return None
+        bottle_id = payload.get("bottle_id")
+        return bottle_id if isinstance(bottle_id, str) and bottle_id else None
+
+    def resolve_policy_and_bottle_id(
+        self, source_ip: str, identity_token: str = "",
+    ) -> tuple[str | None, str | None, dict[str, str]]:
+        """The policy blob, bottle id, **and per-bottle egress auth tokens** in
+        a single `/resolve` — so the egress addon gets everything it needs
+        (policy for routing, bottle id for the supervise queue/safelist, tokens
+        to inject upstream auth) in one round-trip. Returns `(None, None, {})`
+        when unattributed (a clean `403`). Raises `PolicyResolveError` if the
+        orchestrator can't be reached, so the caller still fails closed."""
+        payload = self._post_resolve(source_ip, identity_token)
+        if payload is None:
+            return None, None, {}
+        policy = payload.get("policy")
+        bottle_id = payload.get("bottle_id")
+        raw = payload.get("tokens")
+        tokens = {
+            k: v for k, v in raw.items() if isinstance(k, str) and isinstance(v, str)
+        } if isinstance(raw, dict) else {}
+        return (
+            policy if isinstance(policy, str) else "",
+            bottle_id if isinstance(bottle_id, str) and bottle_id else None,
+            tokens,
+        )
+
+
+__all__ = ["PolicyResolver", "PolicyResolveError"]

bot_bottle/queue_store.py

@@ -7,11 +7,13 @@ import sqlite3
 from pathlib import Path
 
 try:
-    from .supervise_types import Proposal, Response, host_db_path
+    from .supervise_types import Proposal, Response
+    from .paths import host_db_path
     from .db_store import DbStore
     from .migrations import TableMigrations
 except ImportError:
-    from supervise_types import Proposal, Response, host_db_path  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+    from supervise_types import Proposal, Response  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+    from paths import host_db_path  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
     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
 
@@ -24,7 +26,7 @@ class QueueStore(DbStore):
         if db_path is not None:
             resolved = db_path
         else:
-            # In the sidecar container SUPERVISE_DB_PATH points at the
+            # In the gateway container SUPERVISE_DB_PATH points at the
             # bind-mounted host DB. On the host this env var is never set,
             # so we always fall through to host_db_path().
             env_path = os.environ.get("SUPERVISE_DB_PATH", "").strip()

bot_bottle/store_manager.py

@@ -23,13 +23,10 @@ class StoreManager:
 
     def __init__(self, db_path: Path | None = None) -> None:
         if db_path is None:
-            # Lazy import to avoid a circular dependency: supervise imports
-            # StoreManager at module level; StoreManager must not import
-            # supervise at module level in return.
             try:
-                from .supervise import host_db_path
+                from .paths import host_db_path
             except ImportError:
-                from supervise import host_db_path  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+                from paths import host_db_path  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
             db_path = host_db_path()
         self.db_path = db_path
 

bot_bottle/supervise.py

@@ -1,25 +1,25 @@
 """Per-bottle supervise plane (PRD 0013).
 
-The supervise plane is the per-bottle MCP sidecar plus its host-side
+The supervise plane is the per-bottle MCP daemon plus its host-side
-queue/audit support. The sidecar (bot_bottle.supervise_server)
+queue/audit support. The daemon (bot_bottle.supervise_server)
 sits on the bottle's internal network and exposes MCP tools the agent
 calls when it needs an operator-reviewed egress change:
 
   * egress-block / allow — agent proposes a new routes.yaml
 
 Each tool call: the agent passes the full proposed file plus a
-justification text. The sidecar validates the proposal syntactically,
+justification text. The gateway validates the proposal syntactically,
 writes it to the host SQLite queue table, and holds the tool-call
 connection open. The operator's supervise TUI
 (bot_bottle.cli.supervise) sees the proposal, accepts
-approve / modify / reject, and writes a response row. The sidecar sees
+approve / modify / reject, and writes a response row. The gateway sees
 the response and returns `{status, notes}` to the agent.
 
 This module defines the host-side library: dataclasses for the queue
 record shapes, queue read/write helpers, the audit log writer, and the
-diff renderer. The in-container sidecar lives in
+diff renderer. The in-gateway daemon lives in
 bot_bottle/supervise_server.py; the supervise daemon's container
-lifecycle is owned by the sidecar bundle (PRD 0024).
+lifecycle is owned by the gateway (PRD 0024).
 
 For 0013 the supervisor's approval handlers are deliberately no-ops:
 on approval the audit log is written and the response file is
@@ -41,7 +41,6 @@ try:
     from .supervise_types import (
         ACTION_OPERATOR_EDIT,
         AuditEntry,
-        HOST_DB_FILENAME,
         Proposal,
         Response,
         STATUSES,
@@ -54,13 +53,11 @@ try:
         TOOL_EGRESS_TOKEN_ALLOW,
         TOOL_GITLEAKS_ALLOW,
         TOOL_LIST_EGRESS_ROUTES,
-        bot_bottle_root,
     )
 except ImportError:
     from supervise_types import (  # type: ignore[import-not-found,no-redef]  # pylint: disable=import-error,no-name-in-module
         ACTION_OPERATOR_EDIT,
         AuditEntry,
-        HOST_DB_FILENAME,
         Proposal,
         Response,
         STATUSES,
@@ -73,18 +70,23 @@ except ImportError:
         TOOL_EGRESS_TOKEN_ALLOW,
         TOOL_GITLEAKS_ALLOW,
         TOOL_LIST_EGRESS_ROUTES,
-        bot_bottle_root,
     )
 
 
+try:
+    from .paths import bot_bottle_root
+except ImportError:  # flat imports inside the gateway
+    from paths import bot_bottle_root  # type: ignore[import-not-found,no-redef]  # pylint: disable=import-error,no-name-in-module
+
+
 SUPERVISE_HOSTNAME = "supervise"
 SUPERVISE_PORT = 9100
 
-# The supervise sidecar uses these to query egress's
+# The supervise daemon uses these to query egress's
 # introspection endpoint for the `list-egress-routes` MCP
 # tool. The hostname + port match egress's docker network
 # listen port (see backend.docker.egress.EGRESS_PORT). The supervise
-# daemon runs inside the sidecar bundle alongside egress, so loopback
+# daemon runs inside the gateway alongside egress, so loopback
 # is the stable address across docker, firecracker, and Apple
 # Container backends.
 EGRESS_FORWARD_PROXY = "http://127.0.0.1:9099"
@@ -106,16 +108,6 @@ def audit_dir() -> Path:
     return bot_bottle_root() / "audit"
 
 
-def host_db_path() -> Path:
-    # Calls bot_bottle_root() through this module's globals so that patches
-    # on supervise.bot_bottle_root propagate to callers going through
-    # supervise.host_db_path().
-    #
-    # Kept in its own "db" subdirectory (see supervise_types.host_db_path
-    # for why) — must stay in sync with that copy.
-    return bot_bottle_root() / "db" / HOST_DB_FILENAME
-
-
 def audit_log_path(component: str, slug: str) -> Path:
     return audit_dir() / f"{component}-{slug}.log"
 
@@ -125,7 +117,7 @@ try:
     from .audit_store import AuditStore
     from .store_manager import StoreManager
 except ImportError:
-    # Sidecar bundle: files are flat-copied under /app, not a package.
+    # Gateway: files are flat-copied under /app, not a package.
     from queue_store import QueueStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
     from audit_store import AuditStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
     from store_manager import StoreManager  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
@@ -230,14 +222,14 @@ def sha256_hex(content: str) -> str:
     return hashlib.sha256(content.encode("utf-8")).hexdigest()
 
 
-# --- Sidecar plan + abstract lifecycle -------------------------------------
+# --- Gateway plan + abstract lifecycle -------------------------------------
 
 
 @dataclass(frozen=True)
 class SupervisePlan:
     """Output of Supervise.prepare; consumed by .start.
 
-    `db_path` is the host database bind-mounted into the sidecar at
+    `db_path` is the host database bind-mounted into the gateway at
     /run/supervise/bot-bottle.db. `internal_network` is empty at
     prepare time; the backend's launch step fills it via
     dataclasses.replace before calling .start."""
@@ -248,8 +240,8 @@ class SupervisePlan:
 
 
 class Supervise(ABC):
-    """Per-bottle supervise sidecar. Encapsulates host-side database
+    """Per-bottle supervise daemon. Encapsulates host-side database
-    staging; the sidecar's start/stop lifecycle is backend-specific."""
+    staging; the gateway's start/stop lifecycle is backend-specific."""
 
     def prepare(
         self,
@@ -297,8 +289,6 @@ __all__ = [
     "archive_proposal",
     "audit_dir",
     "audit_log_path",
-    "bot_bottle_root",
-    "host_db_path",
     "list_pending_proposals",
     "list_all_pending_proposals",
     "read_audit_entries",

bot_bottle/supervise_server.py

@@ -1,4 +1,4 @@
-"""Supervise sidecar HTTP server (PRD 0013).
+"""Supervise daemon HTTP server (PRD 0013).
 
 Per-bottle MCP server exposing tools the agent calls to propose egress
 config changes when stuck. The tools are `egress-allow`,
@@ -15,6 +15,12 @@ The bottle slug arrives via SUPERVISE_BOTTLE_SLUG env (stamped at
 container creation by the backend's start step). SUPERVISE_DB_PATH
 points at the bind-mounted host database.
 
+Consolidated (PRD 0070): when BOT_BOTTLE_ORCHESTRATOR_URL is set, one
+shared server fronts every bottle and attributes each proposal to the
+calling bottle by source IP (resolved from the orchestrator) instead of a
+fixed slug — an unattributed source fails closed. Unset → the legacy
+per-bottle single-tenant server, unchanged.
+
 Speaks MCP over HTTP+JSON-RPC. Methods handled:
 
   * `initialize`           — handshake; returns server info + caps.
@@ -40,16 +46,18 @@ import time
 import typing
 import urllib.error
 import urllib.request
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 
 try:
     # Same-directory imports inside the bundle container; these files are
-    # COPYed flat under /app by Dockerfile.sidecars.
+    # COPYed flat under /app by Dockerfile.gateway.
     from egress_addon_core import LOG_OFF, load_config
+    from policy_resolver import PolicyResolveError, PolicyResolver
     import supervise as _sv
 except ModuleNotFoundError:
     # Package imports for host-side tests and tooling.
     from .egress_addon_core import LOG_OFF, load_config
+    from .policy_resolver import PolicyResolveError, PolicyResolver
     from . import supervise as _sv
 
 
@@ -73,6 +81,12 @@ DEFAULT_RESPONSE_TIMEOUT_SECONDS = 30.0
 MIN_RESPONSE_POLL_INTERVAL_SECONDS = 0.05
 EGRESS_LIST_TIMEOUT_SECONDS = 5.0
 
+# Consolidated (multi-tenant) mode: when set, one shared supervise server
+# fronts every bottle and attributes each proposal to the calling bottle by
+# source IP (resolved from the orchestrator), instead of a single
+# SUPERVISE_BOTTLE_SLUG env. Unset → legacy per-bottle single-tenant.
+ORCHESTRATOR_URL_ENV = "BOT_BOTTLE_ORCHESTRATOR_URL"
+
 
 @dataclass(frozen=True)
 class JsonRpcRequest:
@@ -511,9 +525,30 @@ class MCPHandler(http.server.BaseHTTPRequestHandler):
         if method == "tools/list":
             return handle_tools_list(req.params)
         if method == "tools/call":
-            return handle_tools_call(req.params, config)
+            # Attribute the proposal to the calling bottle. Single-tenant → the
+            # env slug on `config`; consolidated → the source-IP-resolved
+            # bottle id, so one shared server queues each bottle's proposal
+            # under its own slug.
+            return handle_tools_call(req.params, self._attributed_config(config))
         raise _RpcClientError(ERR_METHOD_NOT_FOUND, f"method not found: {method}")
 
+    def _attributed_config(self, config: ServerConfig) -> ServerConfig:
+        """The ServerConfig with `bottle_slug` bound to *this request's* bottle.
+        Single-tenant (no resolver): unchanged. Consolidated: the bottle id
+        attributed from the source IP — **fail-closed**, an unattributed or
+        unreachable source raises so no proposal is queued under the wrong (or
+        empty) slug."""
+        resolver = getattr(self.server, "policy_resolver", None)
+        if resolver is None:
+            return config
+        try:
+            bottle_id = resolver.resolve_bottle_id(self.client_address[0])
+        except PolicyResolveError as e:
+            raise _RpcInternalError(f"orchestrator unreachable, cannot attribute: {e}") from e
+        if not bottle_id:
+            raise _RpcInternalError("request source is not attributed to a bottle")
+        return replace(config, bottle_slug=bottle_id)
+
     def _write_jsonrpc(self, body: bytes) -> None:
         self.send_response(200)
         self.send_header("Content-Type", "application/json")
@@ -537,6 +572,9 @@ class MCPServer(socketserver.ThreadingMixIn, http.server.HTTPServer):
     allow_reuse_address = True
     daemon_threads = True
     config: ServerConfig = ServerConfig(bottle_slug="")
+    # None → single-tenant (proposals use config.bottle_slug); set → consolidated
+    # (each proposal attributed to the source-IP-resolved bottle).
+    policy_resolver: "PolicyResolver | None" = None
 
 
 # --- Entry point -----------------------------------------------------------
@@ -548,15 +586,17 @@ def serve(
     port: int = _sv.SUPERVISE_PORT,
     bind: str = "0.0.0.0",
     response_timeout_seconds: float = DEFAULT_RESPONSE_TIMEOUT_SECONDS,
+    resolver: "PolicyResolver | None" = None,
 ) -> typing.NoReturn:
     server = MCPServer((bind, port), MCPHandler)
     server.config = ServerConfig(
         bottle_slug=bottle_slug,
         response_timeout_seconds=response_timeout_seconds,
     )
+    server.policy_resolver = resolver
+    mode = "multi-tenant" if resolver else f"slug={bottle_slug!r}"
     sys.stderr.write(
-        f"supervise listening on {bind}:{port}; "
+        f"supervise listening on {bind}:{port}; {mode}; "
-        f"slug={bottle_slug!r}; "
         f"tools: {', '.join(t['name'] for t in TOOL_DEFINITIONS)}\n"  # type: ignore[arg-type]
     )
     sys.stderr.flush()
@@ -571,8 +611,12 @@ def serve(
 
 def main(argv: list[str]) -> int:
     del argv  # config is env-only, no CLI flags
+    orch_url = os.environ.get(ORCHESTRATOR_URL_ENV, "").strip()
+    resolver = PolicyResolver(orch_url) if orch_url else None
     bottle_slug = os.environ.get("SUPERVISE_BOTTLE_SLUG", "")
-    if not bottle_slug:
+    # Consolidated mode resolves the slug per request, so the env slug is
+    # optional there; single-tenant still requires it.
+    if not bottle_slug and resolver is None:
         sys.stderr.write("supervise: SUPERVISE_BOTTLE_SLUG env is unset\n")
         return 2
     port = int(os.environ.get("SUPERVISE_PORT", str(_sv.SUPERVISE_PORT)))
@@ -587,6 +631,7 @@ def main(argv: list[str]) -> int:
         port=port,
         bind=bind,
         response_timeout_seconds=response_timeout_seconds,
+        resolver=resolver,
     )
     return 0  # serve() does not return
 

bot_bottle/supervise_types.py

@@ -1,26 +1,19 @@
-"""Shared types and path helpers for supervise stores (PRD 0013).
+"""Shared types for supervise stores (PRD 0013).
 
 Extracted from supervise.py so queue_store and audit_store can import
-Proposal, Response, AuditEntry, and host_db_path without creating a
+Proposal, Response, and AuditEntry without creating a circular import
-circular import (supervise imports from queue_store/audit_store and
+(supervise imports from queue_store/audit_store and vice-versa).
-vice-versa).
 
-Patching bot_bottle_root on this module propagates through host_db_path
+The path helpers (`bot_bottle_root`, `host_db_path`, `HOST_DB_FILENAME`)
-because host_db_path looks up bot_bottle_root via sys.modules[__name__]
+live in `paths` — import them from there.
-at call time rather than capturing it at import time.
 """
 
 from __future__ import annotations
 
 import dataclasses
-import sys
 import uuid
 from dataclasses import dataclass
 from datetime import datetime, timezone
-from pathlib import Path
-
-
-HOST_DB_FILENAME = "bot-bottle.db"
 
 TOOL_EGRESS_BLOCK = "egress-block"
 TOOL_EGRESS_ALLOW = "egress-allow"
@@ -43,23 +36,6 @@ STATUSES: tuple[str, ...] = (STATUS_APPROVED, STATUS_MODIFIED, STATUS_REJECTED)
 ACTION_OPERATOR_EDIT = "operator-edit"
 
 
-def bot_bottle_root() -> Path:
-    return Path.home() / ".bot-bottle"
-
-
-def host_db_path() -> Path:
-    # Look up bot_bottle_root through this module's live namespace so that
-    # monkey-patches on supervise_types.bot_bottle_root take effect.
-    #
-    # Lives in its own "db" subdirectory, not directly under
-    # bot_bottle_root(), so backends that can only bind-mount
-    # directories (macos_container's `container run --mount`, which
-    # rejects file sources with "is not a directory") can share this
-    # one file with a sidecar without also exposing bot_bottle_root()'s
-    # other contents (git-gate keys, per-bottle state, etc.).
-    return sys.modules[__name__].bot_bottle_root() / "db" / HOST_DB_FILENAME
-
-
 def _require_str(raw: dict[str, object], key: str) -> str:
     value = raw.get(key)
     if not isinstance(value, str):
@@ -171,7 +147,6 @@ class AuditEntry:
 __all__ = [
     "ACTION_OPERATOR_EDIT",
     "AuditEntry",
-    "HOST_DB_FILENAME",
     "Proposal",
     "Response",
     "STATUSES",
@@ -184,6 +159,4 @@ __all__ = [
     "TOOL_EGRESS_TOKEN_ALLOW",
     "TOOL_GITLEAKS_ALLOW",
     "TOOL_LIST_EGRESS_ROUTES",
-    "bot_bottle_root",
-    "host_db_path",
 ]

bot_bottle/yaml_subset.py

@@ -71,7 +71,7 @@ class YamlSubsetError(ValueError):
     that want fatal-exit semantics (manifest loader, egress-apply,
     etc.) catch this at their own boundary and forward to `die`;
     callers running outside the bot-bottle CLI process (the
-    egress sidecar's addon) handle it as a normal exception."""
+    egress daemon's addon) handle it as a normal exception."""
 
 
 

docs/ci.md

@@ -22,8 +22,7 @@ mounted in. That topology breaks two assumptions those tests make:
   `http://127.0.0.1:<host_port>` from inside the job time out.
 
 The affected tests (`test_orphan_cleanup.test_create_and_remove`,
-`test_sidecar_bundle_image.TestSidecarBundleImage`,
+`test_gateway_image.TestGatewayImage`) still run
-`test_sidecar_bundle_compose.TestSidecarBundleCompose`) still run
 locally where the test process and Docker daemon share a host.
 Making them work in CI is a follow-up: either re-write them to
 discover container IPs via `docker inspect`, or reconfigure the

docs/demo.tape

@@ -38,7 +38,7 @@ Type "y"
 Enter
 
 # Wait for the bottle to launch: networks created, pipelock + git-gate
-# sidecars started, agent container started, claude boots.
+# companion containers started, agent container started, claude boots.
 Sleep 22s
 
 # Probe 1 — warm-up. A reply at all proves api.anthropic.com is
@@ -72,7 +72,7 @@ Type "init /tmp/r, commit AKIAQRJHK7N5ZPM2VXTL to leak.txt, push to ssh://git@up
 Enter
 Sleep 30s
 
-# Leave claude. The launcher tears down the container, sidecars, and
+# Leave claude. The launcher tears down the container, companion containers, and
 # networks on session end.
 Ctrl+D
 Sleep 4s

docs/prds/0069-firecracker-native-docker-free.md

@@ -1,10 +1,16 @@
 # PRD 0069: Firecracker-native, Docker-free backend
 
-- **Status:** Draft
+- **Status:** Draft (partially superseded)
 - **Author:** Claude
 - **Created:** 2026-07-12
 - **Issue:** #348
 
+> **Superseded in part by [PRD 0070](0070-per-host-orchestrator.md) (#351):**
+> the sidecar-consolidation framing here (Stage 1, per-host sidecar; Stage 4,
+> sidecar-as-VM) is taken over by 0070's per-host orchestrator. This PRD still
+> owns the docker-free **image-building** work — Stage 2 (nix-built fixed
+> images, a dependency of 0070) and Stage 3 (in-VM Dockerfile builder).
+
 ## Summary
 
 Make the Firecracker backend depend on **firecracker + KVM only**, removing

docs/prds/0070-per-host-orchestrator.md

@@ -0,0 +1,401 @@
+# PRD 0070: Per-host orchestrator service
+
+- **Status:** Draft
+- **Author:** Claude
+- **Created:** 2026-07-12
+- **Issue:** #351
+- **Supersedes:** the Stage-1 / Stage-4 sidecar-consolidation framing of
+  PRD 0069 (#348). Depends on 0069's nix-built fixed images (Stage 2) for
+  bootstrapping; 0069 still owns the docker-free image-building work.
+
+## Summary
+
+Replace the **per-bottle gateway bundle** with a single **persistent,
+per-host orchestrator**: one long-lived service that runs the gateway
+functions (egress / git-gate / supervise), coordinates with the console,
+and brokers agent launches and teardown. It is **virtualized from the
+start** using each backend's native isolation primitive — a Firecracker
+microVM on the Firecracker backend, an Apple container on macOS, a Docker
+container on the legacy backend — and is fronted by a single
+**backend-agnostic contract**. Per-backend variation lives on
+`BottleBackend`, not in the orchestrator.
+
+## Motivation
+
+Today each bottle spins up its own gateway bundle (egress mitmproxy +
+git-gate + supervise). That costs:
+
+- **Resources.** N bottles → N heavy bundles booting and idling.
+- **Operational churn.** Per-launch container/VM lifecycle for the
+  gateways, a control path baked at launch and torn down at exit.
+- **A blurry contract.** "How a bottle talks to its gateway" is
+  re-implemented per backend instead of being one agreed interface.
+
+A per-host orchestrator collapses the first two and forces the third to
+be made explicit. It's also the component that will own per-host runtime
+**state** (slot leases, the approval queue, the bottle registry) — today
+that's ad-hoc `fcntl`-locked files.
+
+## Security review (read this first)
+
+Consolidation is a real change to the trust model. The goal is to **not
+significantly weaken** the posture; some properties strengthen, some
+weaken, and the weakened ones must be mitigated by design, not hand-waved.
+
+### What gets stronger
+
+- **Build/host isolation of untrusted inputs** (with 0069 Stage 3): user
+  Dockerfiles build in a disposable VM instead of on the host.
+- **One audited privileged surface.** Today the launcher runs as the full
+  host user and needs the Docker socket (root-equivalent). The orchestrator
+  model replaces that with a **thin launch broker** (below) — a small,
+  structured, auditable privileged core instead of a fat socket.
+- **Attribution is enforced, not assumed.** Making source-IP identity a
+  first-class contract invariant (below) means each backend must *prove*
+  it, rather than the gateway implicitly trusting network position.
+
+### What gets weaker, and the mitigation
+
+1. **Secret concentration.** Per-bottle gateways isolate secrets at the
+   process boundary — each holds only its bottle's tokens/keys. A host
+   orchestrator concentrates **every bottle's** egress tokens, git deploy
+   keys, and the console credential in one long-lived process. A single
+   attribution bug leaks bottle A's token into bottle B's request — a class
+   of bug that *cannot exist* per-bottle.
+   - *Mitigation:* lean on the enforced source-IP invariant for
+     attribution; keep the most secret-dense, least-shareable service
+     (**git-gate**, per-repo deploy keys, no natural source-IP scoping)
+     **per-bottle** unless there's a compelling reason; scope each secret
+     to the bottle in the state DB so a lookup can't return the wrong
+     bottle's secret by construction (key every secret access by the
+     verified source identity, never by ambient state).
+
+2. **Shared fate.** Orchestrator down = no new launches, and running
+   agents lose egress / git / supervise. Compromise = the whole host's
+   fleet, plus launch authority, plus the console token.
+   - *Mitigation:* the orchestrator is itself confined (its own VM/container
+     with its own fail-closed egress); make it **restartable without killing
+     running agent VMs** (agents keep running; they briefly lose gateway
+     connectivity until it's back); persist state to a host volume so a
+     restart re-adopts live bottles rather than losing them.
+
+3. **The launch broker is the new privileged core.** We don't eliminate
+   host privilege — we shrink and relocate it. If the broker accepts
+   arbitrary paths/commands, the orchestrator VM can escape through it.
+   - *Mitigation:* the broker takes **structured requests only** — "launch
+     bottle from *this* content-addressed, nix-built rootfs on TAP slot
+     *k*", never "run this argv". It validates against a fixed image set,
+     not caller-supplied paths. It is small enough to audit line-by-line.
+
+4. **The egress proxy now parses every bottle's traffic in one process.**
+   Higher blast radius for a mitmproxy/TLS-bump bug.
+   - *Mitigation:* this is the argument for virtualizing the orchestrator
+     from the start (Stage B, not a host daemon) — the code that TLS-bumps
+     and parses agent traffic and holds every token runs **inside its own
+     confined VM**, not as a host process. If egress sharing's blast radius
+     feels too high, egress can stay per-bottle while supervise (near-zero
+     secrets) goes host-level first.
+
+### The attribution invariant
+
+Source-IP attribution is what makes a shared orchestrator safe: one
+process serves every bottle and tells them apart by source address. The
+*mechanism* is identical everywhere (read source IP → look up bottle); the
+**guarantee that the address can't be forged is a per-backend
+responsibility** and part of the contract:
+
+> **Invariant:** a packet's source address, as seen by the orchestrator,
+> *provably* identifies the originating bottle.
+
+- **Firecracker** — enforced by the `/31` point-to-point TAP + the
+  `bot_bottle_fc` nft table (strongest; already built).
+- **Docker** — the per-bottle `--internal` network + anti-spoof; weaker,
+  must be made explicit.
+- **Apple** — the host-only network.
+
+If a backend can't honor the invariant, source-IP consolidation is not
+safe there and that backend keeps per-bottle gateways. The invariant is a
+hard precondition, not an aspiration.
+
+**Defense-in-depth — a per-bottle identity token.** On top of the
+network-layer invariant, inject a per-bottle secret token into every
+request the agent makes to the orchestrator (the agent already egresses
+through the gateway proxy, so this is cheap to add). It gives an
+**application-layer** proof of identity independent of the network layer:
+
+- On **Firecracker** the `/31` + nft already make source IP unspoofable
+  *by construction*, so the token is belt-and-suspenders there — but cheap
+  insurance against a misconfigured invariant.
+- On **weaker backends** (Docker) it is load-bearing, providing attribution
+  that doesn't lean on network anti-spoof.
+
+Requirements: the token is **per-bottle, unguessable, and
+non-cross-leakable** — a bottle can only ever prove it is *itself* (it
+can't learn another bottle's token, given bottle isolation), so a hostile
+agent gains nothing by presenting it. The orchestrator provisions the
+token at launch and the gateway requires it to attribute + authorize.
+Note this hardens *attribution*, not *secret exposure*: it's app-layer, so
+a compromised orchestrator still sees every token (that's the
+concentration problem, addressed separately under Secret handling).
+
+### Secret handling — a FUTURE pattern (not v1)
+
+> **Status: future / not required for the initial orchestrator.** The
+> initial cut can inject secrets as today; this section records the
+> direction so v1 doesn't paint itself into a corner. Tracked as its own
+> work in **#355** (generic `SecretProvider`).
+
+The residual weakness after all of the above is **long-lived credential
+concentration** — the data-plane proxies must hold every bottle's upstream
+tokens because the agent must never see them. You can't policy-gate the
+component whose job is to *use* all the secrets, so a full RCE of a proxy
+drains its authorized set regardless. Two moves bound this without
+pretending to prevent it:
+
+1. **Vault as a separate trust domain.** The long-lived *roots* live in a
+   distinct process (ideally its own VM) that the byte-parsing data plane
+   never shares memory with. The proxies request secrets from it; the
+   crown jewels are not in the process an agent-facing parser can pop.
+2. **Derive short-lived, scoped creds where the upstream allows it.** The
+   vault holds the root and mints expiring, narrowly-scoped credentials
+   per bottle-start (or per request) — GitHub App installation tokens,
+   OAuth/STS token exchange, forge deploy tokens. A compromise then leaks
+   short-lived material, not permanent keys. For upstreams stuck on static
+   keys the vault passes the value through (only the at-rest / audit /
+   revocation benefits apply, not lifetime reduction) — this residue is
+   accepted and documented, not solved.
+
+Even a plain per-request fetch (no derivation) still buys **at-rest**
+reduction (process memory holds only in-flight secrets), a **detection /
+rate-limit / revocation chokepoint**, and clean **cross-component
+scoping** (an egress RCE can't request git-gate's creds). It does *not*
+prevent abuse of currently-authorized access during the compromise window.
+
+**Mechanism (see #355):** generalize the existing `DeployKeyProvisioner`
+(PRD 0048) into a user-extensible **`SecretProvider`** droppable into the
+manifest anywhere a raw token value is accepted, discovered from
+`~/.bot-bottle/contrib/<name>/secret_provider.py` exactly as user
+`AgentProvider`s are — because maintaining every forge/cloud/OAuth
+provider in-tree is untenable. The orchestrator's vault mints via these
+providers; but the abstraction is shippable independently and today's
+per-bottle gateways can use it too.
+
+## Design
+
+### The contract (backend-agnostic)
+
+Three surfaces; only one is per-backend.
+
+1. **Control plane (CLI / console → orchestrator)** — an RPC:
+   `launch_bottle`, `teardown_bottle`, `register_policy`,
+   `deregister_bottle`, `supervise_queue`. Fully backend-agnostic. Both the
+   local `cli.py` and the remote console funnel through it, so policy is
+   uniform and `cli.py` becomes a thin client rather than a parallel
+   launcher. **Transport: HTTP** — the most universal/reliable choice on
+   every host (no vsock/unix-socket portability caveats); a local unix
+   socket is a fine optimization, but HTTP is the wire contract.
+2. **Data plane (agent → orchestrator)** — the egress / git / supervise
+   endpoints. Already agnostic today (agents dial `http://gateway:9099`);
+   only the *address* and *how packets get there* are per-backend.
+3. **Launch / wire (orchestrator → backend)** — the irreducibly
+   backend-specific part; lives on `BottleBackend`.
+
+### One `Orchestrator`, no subclass tree
+
+The orchestrator is a **single concrete class** holding all the
+backend-neutral logic — egress addon, git-gate, supervise, source-IP
+attribution, live-reload control plane, console client. It never branches
+on backend; it *composes* a `BottleBackend`. That composition is what makes
+the contract agnostic: there is nothing backend-specific left in the
+orchestrator to leak.
+
+Rejected alternative: an `Orchestrator` ABC with per-backend
+implementations. The interesting logic (proxies, attribution, control
+plane) is backend-neutral, so three subclasses would triplicate the hard
+part; and a second hierarchy paralleling `BottleBackend` reintroduces the
+same hand-maintained lockstep coupling we just removed from the netpool
+constants (PR #350). Composition over a parallel tree.
+
+### `BottleBackend` absorbs the per-backend variation
+
+A small, cohesive surface — reused for launching agent bottles *and* the
+orchestrator's own unit (the orchestrator is just another native unit):
+
+```
+launch_unit(spec) -> Handle      # agent bottle OR the orchestrator itself
+                                 # (fc microVM / apple ctr / docker ctr)
+wire(unit, endpoint) -> None     # DNAT+forward (fc) | attach shared net (docker/apple)
+endpoint_of(unit) -> Endpoint    # address resolution
+health(unit) -> Status
+```
+
+Plus the **launch broker** — the answer to "a VM/container can't spawn its
+own host-network siblings." The orchestrator can't directly open host
+`/dev/kvm` + a host TAP fd (Firecracker), and a container can't spawn
+siblings without a root-equivalent socket (Docker). So every backend
+exposes a broker the orchestrator calls to launch an agent:
+
+- **Firecracker** — a thin, structured host shim (see security #3). This
+  replaces today's implicit "launcher runs as host user."
+- **Docker** — the socket today (fat, root-equivalent — the thing 0069's
+  Stage 3 removes); a narrower broker later.
+- **Apple** — the `container` CLI/daemon.
+
+**Broker request schema:** human-readable JSON of **static flags + ids
+only** (never free-form paths/argv — that's what keeps it un-coercible
+into arbitrary launches), wrapped as a **signed JWT** so the broker
+verifies *provenance*: the request came from the real orchestrator, not a
+forged one from a compromised co-located component. The orchestrator signs;
+the broker verifies with the orchestrator's public key (provisioned at
+broker install). This is the concrete form of security #3's "structured
+requests only." Same JSON-with-ids + JWT shape for all
+orchestrator↔broker/gateway communication; cases that don't fit get
+handled as they arise, with this as the default.
+
+If `BottleBackend` bloats, the pressure valve is composition one level
+down: vend a `backend.network()` / `Wiring` collaborator rather than
+piling methods on — the same discipline, recursed.
+
+### State: one SQLite DB, owned by the orchestrator
+
+The orchestrator is the natural owner of per-host **runtime state**:
+
+- pool **slot leases** (which bottle holds slot *i*) — replaces today's
+  `fcntl`-locked files with SQLite transactions;
+- the **supervise approval queue** + remembered approvals;
+- the **live bottle registry** (source IP → bottle → policy/secrets refs),
+  the lookup table the attribution invariant reads.
+
+This is deliberately **not** a "single source of truth for all config."
+Config splits into three tiers with different homes:
+
+| Tier | Example | Home |
+|---|---|---|
+| Build-time constants | pool size, IP base, nft table | flat `.env` (PR #350) — must be readable by Nix eval + root bash, zero runtime |
+| User-authored config | bottle manifests, egress routes, secret refs | declarative files under `~/.bot-bottle/` — trust boundary at `$HOME`, git-trackable, "unknown keys die at load" |
+| Runtime state | slot leases, approvals, registry | one shared **`bot-bottle.db`**, solely owned by the orchestrator |
+
+SQLite is right for the runtime tier (mutable, concurrent, queried) and
+wrong for the other two (Nix can't read it at eval time; it fights the
+declarative manifest trust model). Keep the tiers separate.
+
+**One shared `bot-bottle.db` for all runtime state** (decided in review).
+The registry co-tenants the existing host `bot-bottle.db` — the `DbStore`
+framework already namespaces each store by `schema_key`, so slot
+leases / approvals / registry share one file. One place to query, back up,
+and integrate a console against.
+
+- **Host-resident, for durability.** Re-adoption sweeps the registry after
+  an orchestrator restart, so state *must* outlive the orchestrator
+  instance. The file lives on the host (`bot_bottle_root()/db/bot-bottle.db`);
+  the orchestrator unit reaches it, it doesn't carry it.
+- **Integrity by sole ownership, not mount permissions.** Agents can't
+  touch the DB directly wherever it lives (network-isolated in their
+  bottles). The risk is a *compromised agent-facing data-plane service*
+  (egress/git-gate, which parse hostile bytes) writing the registry and
+  forging attribution. Because it's now one shared file, coarse `ro`/`rw`
+  mount-splitting no longer isolates the registry — so the rule is stronger
+  and simpler: **only the orchestrator (control plane) opens `bot-bottle.db`;
+  the data plane and the console reach state through the control-plane RPC,
+  never a direct file handle.** No agent-facing component gets the file, so
+  none can forge attribution. (This supersedes the earlier `ro`-mount idea.)
+  - *Transitional caveat:* today the per-bottle **supervise gateway
+    rw-bind-mounts `bot-bottle.db`** to write proposals — exactly the
+    pattern the orchestrator removes (supervise consolidates into the
+    orchestrator; gateway writes become RPC calls). Until that lands, don't
+    put the attribution registry behind a data-plane-writable mount.
+
+Implementation note for the VM slices: SQLite **WAL** over a guest share
+(virtiofs/9p) is finicky (the `-shm`/`-wal` files need real mmap/locking),
+which is a second reason the DB wants a **host-side owner** the orchestrator
+reaches over the RPC rather than a shared mount into the VM. WAL on the
+shared DB is therefore a deliberate, tested future change — not enabled ad
+hoc. `sqlite3` itself is stdlib, so "the host needs SQLite" is a non-cost.
+
+## Sequencing
+
+Jump straight to the **virtualized** end state (not a host-daemon stepping
+stone): a host daemon's agent→`localhost` transport is throwaway once the
+orchestrator becomes a VM. Decouple the two risks instead:
+
+- **Consolidation risk** (one process, all secrets, attribution, reload)
+  and **packaging/transport risk** (VM-to-VM wiring, the shim) are
+  independent. Develop the orchestrator **service as a plain process
+  dev-harness** first, so the consolidation logic (attribution, reload,
+  secret handling) is proven with fast iteration — *then* wrap that exact
+  service in the VM and solve wiring separately.
+
+Backend order (cheapest proof → hardest → last):
+
+1. **Docker orchestrator** — nearly free (the gateway bundle is already
+   containers; collapse N bundles into one persistent container). Proves
+   consolidation + the `BottleBackend` seam with the least moving parts.
+2. **Firecracker orchestrator** — the real work: the shim + VM-to-VM
+   routing (host forwards `bbfcN` → orchestrator TAP; the nft table grows
+   forward rules where today it drops all non-DNAT egress). Built against
+   the dev-harness so the app logic is already proven.
+3. **macOS (Apple container)** — last (container-to-container networking).
+
+Keep the gateway **service one shared thing** throughout.
+
+## Non-goals
+
+- Removing OCI/Dockerfile support for agent images (0069's concern).
+- A single database for *all* config (see the three-tier table).
+- Changing the per-bottle isolation of agent workloads — only the gateway
+  is consolidated; agents stay one-VM/container-each.
+
+## Relationship to other work
+
+- **PRD 0069 (#348):** 0070 subsumes its Stage 1 (per-host sidecar) and
+  Stage 4 (sidecar-as-VM). 0069 retains Stage 2 (nix-built fixed images —
+  a **dependency** here: the orchestrator and agent base must be
+  nix-built so the broker launches from a fixed image set and bootstrapping
+  has no chicken-and-egg) and Stage 3 (in-VM Dockerfile builder).
+- **Minimal CI runner (paused):** the Firecracker broker + no host Docker
+  is what lets a dedicated `gitea` runner user drop the root-equivalent
+  `docker` group — it only needs broker-socket access + `kvm`/pool group
+  membership. This work unblocks it.
+- **Generic `SecretProvider` (#355):** the future secret-handling
+  mechanism (see "Secret handling") — generalizes PRD 0048's
+  `DeployKeyProvisioner` into a user-extensible provider that mints
+  short-lived creds. Shippable independently; the orchestrator's vault
+  mints through it.
+- **PR #350 (netpool single-source):** the same "one source per fact,
+  composition over parallel hierarchies" discipline the contract follows.
+
+## Decisions (review 2026-07-13)
+
+- **Egress sharing:** **consolidate egress** (worth it). Treat it as a
+  minimal, hardened attack surface for a malicious agent rather than
+  keeping it per-bottle; pair it with the identity token above and the
+  short-lived-vault-token mitigations (Secret handling / #355).
+- **Control-plane transport:** **HTTP** — most universal/reliable on every
+  host; unix socket is an optional local optimization (see the contract).
+- **Broker request schema:** **signed-JWT JSON, static flags + ids only**
+  (see the launch broker) — provenance + un-coercible by construction.
+- **State re-adoption:** the restart procedure is:
+  1. **Singleton:** a new orchestrator launch requires no pre-existing
+     orchestrator; any found (healthy or not) is fully shut down first.
+  2. Re-adoption **waits for the new orchestrator to be healthy**.
+  3. Once healthy, it discovers all agents needing adoption via **both the
+     SQLite registry and live process/VM inspection** *before serving any
+     other request*. The two-source sweep is what closes the *in-flight
+     launch* race — a launch that started (VM booting / slot claimed) but
+     hadn't committed to SQLite when the old orchestrator died would be
+     invisible to a SQLite-only sweep; process inspection catches it.
+     Launches should also write an **intent record ahead of committing
+     resources** so the sweep can reconcile intent vs. actual.
+
+## Open questions
+
+- **VM-to-VM routing:** per-backend, and in the design it *is*
+  `BottleBackend.wire()` (DNAT+forward for fc, shared-net for
+  docker/apple), not orchestrator logic. **Not a blocker** — resolvable at
+  implementation time (may require a bit of host modification, as the pool
+  setup already does on NixOS); an earlier "gateways in VMs" spike showed
+  it's feasible.
+- **Live-reload protocol** for per-bottle policy over the HTTP control
+  plane (add/remove routes/keys/proposals without a restart).
+- **Identity-token delivery:** exactly how the per-bottle token is placed
+  where the agent can present it but not swap in another bottle's.

docs/research/agent-credential-proxy-landscape.md

@@ -15,6 +15,25 @@ the biggest credential risk).
 
 ## Summary
 
+> **Status — implemented (2026-07-14).** This note's recommendation
+> shipped, so the "today" / "in-flight" tenses below are now historical
+> (kept as the reasoning that led here). Current reality: bot-bottle no
+> longer injects raw provider tokens into the agent. The agent's environ
+> carries only a **placeholder** (e.g.
+> `CLAUDE_CODE_OAUTH_TOKEN=egress-placeholder`); the real token is held
+> in the egress sidecar and injected as the upstream `Authorization`
+> header. Rather than adding a *separate* in-container reverse proxy (as
+> proposed below), credential injection was folded into the **existing
+> pipelock/mitmproxy egress firewall**: an `EgressRoute` carries
+> `auth_scheme` + `token_ref`, the host token is forwarded into the
+> sidecar addon under an `EGRESS_TOKEN_N` slot, and the addon rewrites
+> `Authorization` on matching routes — **one MITM, not two** (this
+> resolves the Infisical-doubling concern noted later). The same
+> mechanism now covers Codex and Pi provider tokens and git-host PATs.
+> A `printenv` inside the bottle yields the placeholder, not the secret.
+> For current wiring see `bot_bottle/egress.py` and
+> `bot_bottle/contrib/*/agent_provider.py`.
+
 Today every bot-bottle agent gets `CLAUDE_CODE_OAUTH_TOKEN` (and
 any `bottle.env` secrets like a Gitea PAT) injected as env vars,
 which means the agent process can read them with `printenv` or
@@ -36,6 +55,24 @@ small bot-bottle-specific reverse proxy modeled on the
 phantom-token shape is probably the right call. For Gitea / GitHub /
 GitLab, the same proxy generalizes by config.
 
+**Updated 2026-07-14:** OneCLI ([onecli.sh](https://onecli.sh/)) —
+already listed below — has matured into a GA, YC-backed Rust
+credential gateway ("The Identity Gateway for AI Agents", ~2.5k⭐,
+300k+ downloads) that implements the **same phantom-token pattern**
+this note recommends: the agent holds a placeholder token, the
+gateway swaps it for the real (AES-256-GCM-encrypted) credential at
+request time. It's now the most mature open-source realization of the
+exact design proposed here — a production-ready alternative to
+alpha-stage nono — at the cost of being a broader product (built-in
+vault + management dashboard + hosted cloud tier + 50+ app
+integrations) rather than a minimal proxy. Its managed/cloud tier and
+per-agent dashboard also overlap bot-bottle's own planned paid control
+plane (bot-bottle-console, issue #327), so it's worth tracking as both
+a build-vs-adopt option *and* a product-level competitor. The
+build-first recommendation still stands (see synthesis below), but
+adopting OneCLI's OSS core is now a credible alternative where nono was
+too green.
+
 ## The shared problem
 
 Linux has no per-env-var ACL. Once a var is in a process's
@@ -77,7 +114,9 @@ The remaining credible designs reduce to three:
 
 ### Anthropic / Claude Code
 
-**Today's wiring** (`bot_bottle/cli/start.py`): the host's
+**Original wiring** (pre-gateway; **superseded 2026-07-14** — see the
+Status note in the Summary; the token now lives in the egress sidecar
+and the agent gets a placeholder): the host's
 `BOT_BOTTLE_CLAUDE_OAUTH_TOKEN` is forwarded into the bottle as
 `CLAUDE_CODE_OAUTH_TOKEN` via `docker run -e CLAUDE_CODE_OAUTH_TOKEN`
 (no `=value`, so the value never lands on argv — good). Inside the
@@ -223,7 +262,7 @@ Two categories:
 | **Infisical Agent Vault** | B | MIT (EE carve-out) | In-process HTTPS_PROXY forward proxy | TLS MITM, dummy-to-real swap | No — HTTPS_PROXY model | Service-level | Active; v0.19.0 May 2026, ~1k⭐ |
 | **nono** | B | Apache-2.0 | In-process reverse proxy | Phantom token, explicit URL routing | **Yes** — `BASE_URL=http://127.0.0.1:PORT/…` | Host + endpoint | Early alpha; v0.53.0 May 2026, 2.4k⭐ |
 | **Aegis** | B | Apache-2.0 | In-process reverse proxy | Path routing (`localhost:3100/{svc}/…`) | Configurable, undocumented for Anthropic | Method/path/rate/time | Very new, 10⭐ |
-| **OneCLI** | B | Apache-2.0 | Reverse proxy + management UI | Host/path matching, Bitwarden integration | Configurable | Per-agent scoping | Active; v1.23.0 May 2026, 2.1k⭐ |
+| **OneCLI** | B | Apache-2.0 | Reverse proxy + built-in vault + dashboard | **Phantom token** (placeholder→real swap at request time), AES-256-GCM vault | Yes (host match) | Per-agent + endpoint/method + rate limits | GA; Rust; YC-backed; ~2.5k⭐, 300k+ downloads (Jul 2026) |
 | **Aembit** | B | Proprietary | Sidecar + cloud control plane | TLS intercept, SPIFFE, JIT creds | No — intercepts by destination | Policy-based | GA (Apr 2026) |
 | **LiteLLM Proxy** | A | MIT | Reverse proxy | Virtual key → upstream key | Yes — set base URL to LiteLLM | Route-level | 45k⭐; **CVE-2026-42208 exploited Apr 2026**, patch v1.83.7 |
 | **Portkey Gateway** | A | MIT (OSS core) | Reverse proxy | Virtual key vault (cloud or Enterprise self-host) | Yes — documented for Claude Code | Config-based | Production; virtual-key vault needs Enterprise for self-host |
@@ -242,6 +281,18 @@ Two categories:
   `ANTHROPIC_BASE_URL`. **Blocker:** nono is explicitly
   "early alpha, not security audited."
 
+  **Update (2026-07-14):** OneCLI ([onecli.sh](https://onecli.sh/))
+  ships the same phantom-token shape but is GA and YC-backed (Rust,
+  ~2.5k⭐, 300k+ downloads) — the maturity nono lacks. Trade-offs: it's
+  a full identity-gateway *product* (encrypted vault, management
+  dashboard, 50+ one-click app integrations, hosted cloud tier), much
+  heavier than the ~100-line proxy proposed below, and its hosted tier
+  is a third-party credential custodian — precisely the trust
+  dependency bot-bottle's isolation model exists to avoid. So: its
+  Apache-2.0 OSS core is a credible *adopt* candidate for the
+  phantom-token slice; its managed offering is a *competitor*, not a
+  dependency to lean on.
+
 - **TLS-MITM forward proxies** (Infisical Agent Vault, Cloudflare
   Sandbox Auth, Aembit, the existing pipelock) all double up on
   the CA-trust machinery PRD 0006 already built for pipelock.
@@ -273,6 +324,15 @@ routing matches the design recommended here exactly; zero TLS
 work. But "not security audited" + "early alpha" means adopting it
 is a bet on the project rather than a buy-vs-build win.
 
+**Mature phantom-token option (added 2026-07-14):** OneCLI — same
+architecture as nono, but GA, Rust, and YC-backed. Its Apache-2.0 OSS
+core is now the strongest *adopt* candidate for the phantom-token slice
+if building is undesirable; the caveats are product surface you don't
+need (bundled vault + dashboard) and that its hosted tier is a
+competitor rather than a dependency. Doesn't change the build-first
+recommendation for the narrow Anthropic-token slice, but it does mean
+"is there a mature drop-in?" now has a real answer.
+
 **Most mature OSS purpose-built:** Infisical Agent Vault. MIT,
 v0.19.0 active, v0.17.0 added a containerized agent mode that
 maps directly to bot-bottle. Friction is the TLS-MITM topology
@@ -293,6 +353,12 @@ exposed.
 
 ## Recommended path forward
 
+> **Mostly implemented (2026-07-14).** Steps 1–3 shipped — the token
+> injection moved into the egress sidecar (folded into pipelock rather
+> than a standalone reverse proxy) and generalized to Codex/Pi/git-host
+> tokens. Steps 4–5 (issuance-side scope narrowing, per-route allowlists)
+> remain good hygiene. See the Status note in the Summary.
+
 In priority order:
 
 1. **In-container reverse proxy holding `CLAUDE_CODE_OAUTH_TOKEN`.**
@@ -376,6 +442,9 @@ already gives us for upstream push credentials.
 - [nono — phantom token blog](https://nono.sh/blog/blog-credential-injection)
 - [Aegis — GitHub](https://github.com/getaegis/aegis)
 - [OneCLI — GitHub](https://github.com/onecli/onecli)
+- [OneCLI — homepage](https://onecli.sh/)
+- [OneCLI — Y Combinator company page](https://www.ycombinator.com/companies/onecli)
+- [Show HN: OneCLI – Vault for AI Agents in Rust](https://news.ycombinator.com/item?id=47353558)
 - [Sandbox0 — GitHub](https://github.com/sandbox0-ai/sandbox0)
 - [Buildkite Cleanroom — GitHub](https://github.com/buildkite/cleanroom)
 - [Aembit IAM for Agentic AI — GA](https://aembit.io/blog/aembit-iam-for-agentic-ai-is-now-generally-available/)

docs/research/landscape-containerized-claude.md

@@ -71,6 +71,56 @@ manifest merge.
   network egress is logged by pipelock/mitmproxy, and per-run op-log/audit state
   is persisted to SQLite.
 
+- **OneCLI** ([onecli.sh](https://onecli.sh/)) — YC-backed, GA, open-source
+  (Apache-2.0, Rust) "identity gateway for AI agents": a credential/secret
+  broker that holds API keys and OAuth tokens out of the agent's reach and
+  injects them at the network layer (phantom-token — the agent sees a
+  placeholder, the gateway swaps in the real, AES-256-GCM-encrypted credential
+  at request time). Framework-agnostic and drop-in for any HTTP-calling agent,
+  50+ app integrations, plus a hosted cloud tier with a per-agent dashboard and
+  audit logs. Full technical breakdown in
+  [`agent-credential-proxy-landscape.md`](agent-credential-proxy-landscape.md).
+
+  **How close a competitor:** near-exact on the *single axis of agent secret
+  custody* — the exact thing bot-bottle sells as "the agent never sees real
+  credentials, even via `printenv`." OneCLI does that one job well, is mature
+  and funded, and is *more portable* (it sits in front of anything; bot-bottle
+  only helps agents launched through bot-bottle). Takeaway: bot-bottle should
+  stop treating secret custody as a *unique* differentiator. But OneCLI is
+  **not** a competitor to bot-bottle's actual product — it does no agent
+  sandboxing (containers/microVMs), no fleet/manifest layer, no named agents /
+  skills / per-agent system prompts, no multi-provider launching, no egress
+  firewall.
+
+  **Our edge:** (1) *Isolation is the product, not a proxy.* OneCLI keeps the
+  key out of reach at the network layer, but the agent itself still runs
+  unsandboxed — a hijacked agent behind OneCLI has full run of its host and can
+  exfil captured data through any allowed host. bot-bottle runs the agent inside
+  a kernel/VM-enforced sandbox, injects credentials across that same
+  out-of-process boundary, *and* clamps egress with pipelock — defense in depth
+  vs. a single network layer. (2) *Fleet + manifest model* with named agents,
+  skills, per-agent system prompts, multi-provider and multi-backend — OneCLI
+  has no equivalent. (3) *Trust posture:* OneCLI's managed tier reintroduces a
+  third-party credential custodian, whereas bot-bottle's OSS-runtime +
+  paid-control-plane split keeps custody inside the operator's own boundary —
+  the stronger story for the security-minded self-hoster. (4) *Runs inside your
+  network boundary — local/internal reach.* Because bot-bottle executes the
+  agent on your own host (homelab, corporate LAN, a Tailnet) and egress is a
+  manifest field, giving an agent *scoped* access to **internal** resources — a
+  private Gitea, a LAN database, a Tailscale node — is just another egress-route
+  line, not a networking project (the same move an operator already makes to
+  reach their Tailscale services). OneCLI's OSS core can self-host too, but it's
+  a credential *broker* for outbound API calls, not an agent runtime, and its
+  managed tier + 50+ integrations are oriented at public SaaS — it doesn't put
+  the agent behind your firewall for you. This is a reach advantage, distinct
+  from the isolation ones above, and it's a wedge cloud-first agent products
+  (Devin, Copilot Workspace, OneCLI Cloud) structurally can't match. **Tactical
+  read:**
+  adopt OneCLI's OSS core for the credential slice if building is undesirable
+  (it's mature now); don't build atop its managed tier (competitor, not
+  dependency); re-position bot-bottle on isolation + fleet + self-hosted custody
+  rather than "we hide your secrets."
+
 ## What no found project does
 
 None combine:

nix/firecracker-netpool.nix

@@ -2,7 +2,7 @@
 #
 # The one-time privileged setup the Firecracker backend needs: a pool of
 # user- (or group-) owned point-to-point TAP devices plus a fail-closed
-# nftables table that confines every microVM to its own sidecar.
+# nftables table that confines every microVM to its own gateway.
 #
 # NON-INVASIVE BY DESIGN. It does NOT flip `networking.nftables.enable`
 # (which would switch your whole host firewall backend) or
@@ -150,7 +150,7 @@ in
       }
     ];
 
-    # VM->sidecar traffic is DNAT'd and forwarded, so forwarding must be on.
+    # VM->gateway traffic is DNAT'd and forwarded, so forwarding must be on.
     boot.kernel.sysctl."net.ipv4.ip_forward" = 1;
 
     # One oneshot brings up the whole pool (TAPs + independent nft table)

scripts/firecracker-netpool.sh

@@ -4,7 +4,7 @@
 # Creates a pool of point-to-point TAP devices (owned by the invoking
 # user so the backend can open them without root at launch) and a
 # dedicated nftables table that isolates every VM: a bottle VM can
-# reach only its own sidecar (published on the host-side TAP IP) and
+# reach only its own gateway (published on the host-side TAP IP) and
 # nothing else on the host or network.
 #
 # Why a pool + one-time setup: creating a TAP and assigning it an IP
@@ -72,9 +72,9 @@ for _v in POOL_SIZE IP_BASE PREFIX TABLE; do
     [ -n "${!_v}" ] || { echo "error: $_v unresolved (set BOT_BOTTLE_FC_* or fix $_DEFAULTS)" >&2; exit 1; }
 done
 
-# Sidecar ports (must match the backend). egress=9099, supervise=9100,
+# Gateway ports (must match the backend). egress=9099, supervise=9100,
 # git-http=9420. Reached by the VM at its host-side TAP IP.
-SIDECAR_PORTS="9099,9100,9420"
+GATEWAY_PORTS="9099,9100,9420"
 
 # --- IP math ---------------------------------------------------------
 # Slot i occupies the /31 {base+2i, base+2i+1}: host = base+2i (the
@@ -107,7 +107,7 @@ cmd_up() {
     fi
     echo "firecracker net pool: $POOL_SIZE slots, base $IP_BASE, $own_desc"
 
-    # VM->sidecar traffic is DNAT'd to the sidecar container and
+    # VM->gateway traffic is DNAT'd to the gateway container and
     # forwarded, so forwarding must be enabled (Docker also sets this).
     sysctl -qw net.ipv4.ip_forward=1
 
@@ -135,11 +135,11 @@ _install_nft() {
     # tool's traffic is affected. Priority -10 runs before Docker's
     # filter hooks (priority 0); a drop here is terminal for the packet.
     #
-    #   forward: VM egress is DNAT'd to the sidecar (established via
+    #   forward: VM egress is DNAT'd to the gateway (established via
     #     `ct status dnat`); return traffic via `ct state established`.
     #     Anything else from a VM is dropped -> no route to the internet
-    #     or the rest of the host except through the sidecar proxy.
+    #     or the rest of the host except through the gateway proxy.
-    #   input: a VM never needs host-local delivery (its sidecar is
+    #   input: a VM never needs host-local delivery (its gateway is
     #     reached via DNAT->forward), so drop all direct input from VMs
     #     -> host services bound on 0.0.0.0 are unreachable from the VM.
     nft -f - <<EOF

tests/README.md

@@ -18,8 +18,7 @@ tests/
     test_manifest_runtime.py
     ...                             # many others; see unit/ directory
   integration/
-    test_sidecar_bundle_image.py
+    test_gateway_image.py
-    test_sidecar_bundle_compose.py
     test_dry_run_plan.py
     test_orphan_cleanup.py
     ...
@@ -48,12 +47,9 @@ Discovery is invoked with `-t .` (top-level dir = repo root) so the
   the bottle's runtime, and creates zero Docker resources.
 - `test_orphan_cleanup.py` — `network_remove` is idempotent against
   missing resources, so the EXIT trap can call it unconditionally.
-- `test_sidecar_bundle_image.py` — builds Dockerfile.sidecars and
+- `test_gateway_image.py` — builds Dockerfile.gateway and
   probes that gitleaks / mitmdump / supervise are all reachable
-  inside the bundle.
+  inside the gateway image.
-- `test_sidecar_bundle_compose.py` — end-to-end compose-up of an
-  agent + bundle pair; verifies the agent reaches the bundle via
-  the legacy network aliases.
 
 ## Canaries
 

tests/integration/test_firecracker_launch.py

@@ -1,142 +0,0 @@
-"""Integration: Firecracker microVM launch.
-
-End-to-end against a real Firecracker microVM: prepare + launch a bottle
-on the firecracker backend and verify the agent execs after provisioning
-and that the egress proxy env is wired to the sidecar.
-
-Gated on the `backend status` result for firecracker (0 == the privileged
-TAP pool + nft isolation table are provisioned). Skips cleanly with setup
-instructions otherwise, so the suite runs on hosts without the pool.
-"""
-
-from __future__ import annotations
-
-import contextlib
-import io
-import os
-import shutil
-import tempfile
-import unittest
-from pathlib import Path
-
-from bot_bottle.backend import BottleSpec, get_bottle_backend
-from bot_bottle.backend.firecracker import FirecrackerBottleBackend
-from bot_bottle.manifest import ManifestIndex
-
-
-def _firecracker_status_ok() -> bool:
-    """Gate on `./cli.py backend status --backend=firecracker`: a 0 exit
-    means the pool + nft table are ready. Output is captured so the
-    decorator stays quiet during collection; any error → not ready."""
-    buf = io.StringIO()
-    try:
-        with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(buf):
-            return FirecrackerBottleBackend.status() == 0
-    except Exception:
-        return False
-
-
-_SKIP_MSG = (
-    "firecracker backend not ready — provision the network pool with "
-    "`./cli.py backend setup --backend=firecracker`, then confirm with "
-    "`./cli.py backend status --backend=firecracker`"
-)
-
-
-def _minimal_agent_dockerfile(path: Path) -> None:
-    path.write_text(
-        "\n".join((
-            "FROM node:22-slim",
-            "RUN apt-get update \\",
-            "  && apt-get install -y --no-install-recommends \\",
-            "    ca-certificates curl git \\",
-            "  && rm -rf /var/lib/apt/lists/*",
-            "USER node",
-            "WORKDIR /home/node",
-            "CMD [\"sleep\", \"infinity\"]",
-            "",
-        )),
-        encoding="utf-8",
-    )
-
-
-def _minimal_manifest(dockerfile: Path) -> ManifestIndex:
-    return ManifestIndex.from_json_obj({
-        "bottles": {
-            "dev": {
-                "agent_provider": {
-                    "template": "pi",
-                    "dockerfile": str(dockerfile),
-                    "settings": {
-                        "provider": "example",
-                        "base_url": "https://example.com/v1",
-                        "models": ["smoke"],
-                    },
-                },
-                "egress": {"routes": [{"host": "example.com"}]},
-            },
-        },
-        "agents": {
-            "demo": {"skills": [], "prompt": "smoke", "bottle": "dev"},
-        },
-    })
-
-
-@unittest.skipIf(
-    os.environ.get("GITEA_ACTIONS") == "true",
-    "skipped under act_runner: cannot host Firecracker microVMs",
-)
-@unittest.skipUnless(_firecracker_status_ok(), _SKIP_MSG)
-class TestFirecrackerLaunch(unittest.TestCase):
-    """Launch once, reuse the bottle across probes."""
-
-    @classmethod
-    def setUpClass(cls) -> None:
-        cls.stage = Path(tempfile.mkdtemp(prefix="cb-firecracker-launch."))
-        cls._launch = None
-        cls.bottle = None
-        dockerfile = cls.stage / "Dockerfile.agent-smoke"
-        _minimal_agent_dockerfile(dockerfile)
-        os.environ["BOT_BOTTLE_BACKEND"] = "firecracker"
-        try:
-            backend = get_bottle_backend()
-            spec = BottleSpec(
-                manifest=_minimal_manifest(dockerfile),
-                agent_name="demo",
-                copy_cwd=False,
-                user_cwd=str(cls.stage),
-            )
-            cls.plan = backend.prepare(spec, stage_dir=cls.stage)
-            cls._launch = backend.launch(cls.plan)
-            cls.bottle = cls._launch.__enter__()
-        except BaseException:
-            if cls._launch is not None:
-                cls._launch.__exit__(None, None, None)
-            shutil.rmtree(cls.stage, ignore_errors=True)
-            os.environ.pop("BOT_BOTTLE_BACKEND", None)
-            raise
-
-    @classmethod
-    def tearDownClass(cls) -> None:
-        try:
-            if cls._launch is not None:
-                cls._launch.__exit__(None, None, None)
-        finally:
-            shutil.rmtree(cls.stage, ignore_errors=True)
-            os.environ.pop("BOT_BOTTLE_BACKEND", None)
-
-    def test_smoke_exec_echo(self) -> None:
-        r = self.bottle.exec("echo hello-from-firecracker")  # type: ignore[union-attr]
-        self.assertEqual(0, r.returncode, msg=r.stderr)
-        self.assertIn("hello-from-firecracker", r.stdout)
-
-    def test_proxy_env_points_at_sidecar(self) -> None:
-        r = self.bottle.exec(  # type: ignore[union-attr]
-            "printf '%s\\n' \"$HTTPS_PROXY\" \"$HTTP_PROXY\""
-        )
-        self.assertEqual(0, r.returncode, msg=r.stderr)
-        self.assertIn("http", r.stdout.lower())
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/integration/test_gateway_image.py

@@ -1,4 +1,4 @@
-"""Integration: PRD 0024 chunk 1 — the sidecar bundle image builds
+"""Integration: PRD 0024 chunk 1 — the gateway image builds
 and the daemon binaries are present + executable inside it.
 
 This test does NOT exercise the daemons running against real
@@ -6,11 +6,11 @@ config (routes.yaml, etc) — that lands in chunk 2 when the
 renderer wires the bundle into compose. What we verify here is
 the chunk-1 contract:
 
-  - Dockerfile.sidecars builds (multi-stage works, base layers
+  - Dockerfile.gateway builds (multi-stage works, base layers
     pull, COPYs resolve).
   - gitleaks, mitmdump are at the documented paths and answer
     `--version`.
-  - The Python init at /app/sidecar_init.py runs and prints the
+  - The Python init at /app/gateway_init.py runs and prints the
     expected "no daemons selected" line when the supervisor is
     pointed at an empty daemon set.
 
@@ -28,18 +28,18 @@ import unittest
 from tests._docker import skip_unless_docker
 
 
-_IMAGE = "bot-bottle-sidecars-test:chunk1"
+_IMAGE = "bot-bottle-gateway-test:chunk1"
-_DOCKERFILE = "Dockerfile.sidecars"
+_DOCKERFILE = "Dockerfile.gateway"
 
 
 @skip_unless_docker()
 @unittest.skipIf(
     os.environ.get("GITEA_ACTIONS") == "true",
     "skipped under act_runner: multi-stage build pulls a 200+MB "
-    "mitmproxy base + two upstream sidecar images; runner storage "
+    "mitmproxy base + two upstream gateway images; runner storage "
     "+ time budget make this an interactive-only test",
 )
-class TestSidecarBundleImage(unittest.TestCase):
+class TestGatewayImage(unittest.TestCase):
     """Builds the image once for the class, then runs a few
     `docker run` probes against it."""
 
@@ -103,7 +103,7 @@ class TestSidecarBundleImage(unittest.TestCase):
         # ENTRYPOINT wiring works.
         proc = subprocess.run(
             ["docker", "run", "--rm",
-             "-e", "BOT_BOTTLE_SIDECAR_DAEMONS=nothing",
+             "-e", "BOT_BOTTLE_GATEWAY_DAEMONS=nothing",
              _IMAGE],
             stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
             timeout=10.0,

tests/integration/test_macos_container_launch.py

@@ -1,239 +0,0 @@
-"""Integration: macOS Container launch topology.
-
-End-to-end against Apple's real `container` runtime. The smoke launches
-a bottle with the experimental macOS Container backend and verifies the
-properties that make the explicit-proxy launch acceptable:
-
-  - the agent can exec commands after provisioning;
-  - HTTP(S)_PROXY points at the sidecar's internal-network IP;
-  - allowlisted HTTPS reaches the egress sidecar;
-  - direct egress with proxy env removed fails from the internal-only
-    agent network;
-  - non-allowlisted proxy traffic is blocked.
-
-Skipped under Gitea Actions and on hosts without Apple's `container`.
-"""
-
-from __future__ import annotations
-
-import os
-import platform
-import shutil
-import subprocess
-import tempfile
-import unittest
-from pathlib import Path
-
-from bot_bottle.backend import BottleSpec, get_bottle_backend
-from bot_bottle.backend.macos_container.util import (
-    dns_server as _container_dns_server,
-    is_available as _container_available,
-)
-from bot_bottle.manifest import ManifestIndex
-
-
-_AGENT_PROMPT = "You are a launch smoke-test agent. Be brief."
-
-
-def _minimal_agent_dockerfile(path: Path) -> None:
-    path.write_text(
-        "\n".join((
-            "FROM node:22-slim",
-            "RUN apt-get update \\",
-            "  && apt-get install -y --no-install-recommends \\",
-            "    ca-certificates curl git \\",
-            "  && rm -rf /var/lib/apt/lists/*",
-            "USER node",
-            "WORKDIR /home/node",
-            "CMD [\"sleep\", \"infinity\"]",
-            "",
-        )),
-        encoding="utf-8",
-    )
-
-
-def _minimal_manifest(dockerfile: Path) -> ManifestIndex:
-    return ManifestIndex.from_json_obj({
-        "bottles": {
-            "dev": {
-                "agent_provider": {
-                    "template": "pi",
-                    "dockerfile": str(dockerfile),
-                    "settings": {
-                        "provider": "example",
-                        "base_url": "https://example.com/v1",
-                        "models": ["smoke"],
-                    },
-                },
-                "egress": {
-                    "routes": [
-                        {"host": "example.com"},
-                    ],
-                },
-            },
-        },
-        "agents": {
-            "demo": {
-                "skills": [],
-                "prompt": _AGENT_PROMPT,
-                "bottle": "dev",
-            },
-        },
-    })
-
-
-def _buildkit_dns_available() -> bool:
-    if platform.system() != "Darwin" or not _container_available():
-        return False
-    stage = Path(tempfile.mkdtemp(prefix="cb-container-buildkit-dns."))
-    image = "bot-bottle-buildkit-dns-check:latest"
-    try:
-        dockerfile = stage / "Dockerfile"
-        dockerfile.write_text(
-            "FROM debian:bookworm-slim\n"
-            "RUN getent hosts deb.debian.org\n",
-            encoding="utf-8",
-        )
-        result = subprocess.run(
-            [
-                "container", "build",
-                "--dns", _container_dns_server(),
-                "-t", image,
-                "-f", str(dockerfile),
-                str(stage),
-            ],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            check=False,
-        )
-        return result.returncode == 0
-    finally:
-        subprocess.run(
-            ["container", "image", "delete", image],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            check=False,
-        )
-        shutil.rmtree(stage, ignore_errors=True)
-
-
-@unittest.skipIf(
-    os.environ.get("GITEA_ACTIONS") == "true",
-    "skipped under act_runner: cannot host Apple Container VMs",
-)
-@unittest.skipUnless(
-    platform.system() == "Darwin",
-    "Apple Container is macOS-only",
-)
-@unittest.skipUnless(
-    _container_available(),
-    "Apple Container not on PATH; install from "
-    "https://github.com/apple/container/releases",
-)
-@unittest.skipUnless(
-    _buildkit_dns_available(),
-    "Apple Container BuildKit cannot resolve deb.debian.org on this host",
-)
-class TestMacosContainerLaunch(unittest.TestCase):
-    """Launch once and reuse the bottle across probes."""
-
-    @classmethod
-    def setUpClass(cls) -> None:
-        cls.stage = Path(tempfile.mkdtemp(prefix="cb-macos-container-launch."))
-        cls._launch = None
-        cls.bottle = None
-        dockerfile = cls.stage / "Dockerfile.agent-smoke"
-        _minimal_agent_dockerfile(dockerfile)
-        os.environ["BOT_BOTTLE_BACKEND"] = "macos-container"
-        try:
-            backend = get_bottle_backend()
-            spec = BottleSpec(
-                manifest=_minimal_manifest(dockerfile),
-                agent_name="demo",
-                copy_cwd=False,
-                user_cwd=str(cls.stage),
-            )
-            cls.plan = backend.prepare(spec, stage_dir=cls.stage)
-            cls._launch = backend.launch(cls.plan)
-            cls.bottle = cls._launch.__enter__()
-        except BaseException:
-            if cls._launch is not None:
-                cls._launch.__exit__(None, None, None)
-            shutil.rmtree(cls.stage, ignore_errors=True)
-            os.environ.pop("BOT_BOTTLE_BACKEND", None)
-            raise
-
-    @classmethod
-    def tearDownClass(cls) -> None:
-        try:
-            if cls._launch is not None:
-                cls._launch.__exit__(None, None, None)
-        finally:
-            shutil.rmtree(cls.stage, ignore_errors=True)
-            os.environ.pop("BOT_BOTTLE_BACKEND", None)
-
-    def test_smoke_exec_echo(self):
-        r = self.bottle.exec(  # type: ignore[union-attr]
-            "echo hello-from-macos-container"
-        )
-        self.assertEqual(0, r.returncode, msg=r.stderr)
-        self.assertIn("hello-from-macos-container", r.stdout)
-
-    def test_proxy_env_points_at_sidecar_internal_ip(self):
-        r = self.bottle.exec(  # type: ignore[union-attr]
-            "printf '%s\n' \"$HTTPS_PROXY\" \"$HTTP_PROXY\" "
-            "\"$NO_PROXY\" \"$NODE_EXTRA_CA_CERTS\""
-        )
-        self.assertEqual(0, r.returncode, msg=r.stderr)
-        values = [line.strip() for line in r.stdout.splitlines()]
-        self.assertEqual(4, len(values), values)
-        self.assertEqual(values[0], values[1], values)
-        self.assertRegex(values[0], r"^http://[0-9.]+:9099$")
-        self.assertNotIn("127.0.0.1", values[0])
-        sidecar_host = values[0].removeprefix("http://").removesuffix(":9099")
-        self.assertIn(sidecar_host, values[2])
-        self.assertEqual(
-            "/usr/local/share/ca-certificates/bot-bottle-mitm-ca.crt",
-            values[3],
-        )
-
-    def test_allowlisted_https_reaches_egress_proxy(self):
-        r = self.bottle.exec(  # type: ignore[union-attr]
-            "curl -fsS --max-time 20 https://example.com >/dev/null && echo OK"
-        )
-        self.assertEqual(0, r.returncode, msg=r.stderr + r.stdout)
-        self.assertIn("OK", r.stdout)
-
-    def test_direct_egress_bypass_without_proxy_fails(self):
-        r = self.bottle.exec(  # type: ignore[union-attr]
-            "env -u HTTPS_PROXY -u HTTP_PROXY -u https_proxy -u http_proxy "
-            "curl -s --show-error --max-time 5 https://example.com 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()
-            or "could not resolve" in r.stdout.lower()
-            or "connection reset" in r.stdout.lower(),
-            f"expected direct egress to fail; got: {r.stdout!r}",
-        )
-
-    def test_non_allowlisted_host_fails_through_proxy(self):
-        r = self.bottle.exec(  # type: ignore[union-attr]
-            "curl -s --show-error --max-time 10 https://iana.org 2>&1 || true"
-        )
-        self.assertTrue(
-            "403" in r.stdout
-            or "502" in r.stdout
-            or "blocked" in r.stdout.lower()
-            or "not allowed" in r.stdout.lower()
-            or "not in the bottle's egress.routes allowlist" in r.stdout.lower()
-            or "forbidden" in r.stdout.lower()
-            or "failed" in r.stdout.lower(),
-            f"expected non-allowlisted proxy request to fail; got: {r.stdout!r}",
-        )
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/integration/test_multitenant_isolation.py

@@ -0,0 +1,161 @@
+"""Integration: two bottles share one gateway; source-IP attribution keeps
+their egress tokens *and* allowlists isolated (PRD 0070 multi-tenancy).
+
+The whole premise of the consolidation is one shared gateway for every
+bottle, isolated only by the unspoofable source IP. A single-bottle test
+can't catch cross-bottle token bleed or an allowlist leak — this brings up
+the real orchestrator + gateway and drives two bottles through the one
+gateway to prove each gets exactly its own token and its own routes.
+
+Gated on a reachable Docker daemon and builds the bundle image, so it runs
+with the other docker integration tests, not in unit CI. Uses the real
+fixed gateway/orchestrator names (that's what it's testing), so it can't run
+concurrently with a live per-host gateway; it points the orchestrator at a
+throwaway BOT_BOTTLE_ROOT for a clean registry and tears everything down.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+from bot_bottle.backend.docker.consolidated_launch import (
+    _network_cidr,
+    _network_container_ips,
+)
+from bot_bottle.backend.docker.egress import EGRESS_PORT
+from bot_bottle.backend.docker.gateway_net import next_free_ip
+from bot_bottle.orchestrator.client import OrchestratorClient
+from bot_bottle.orchestrator.gateway import GATEWAY_IMAGE, GATEWAY_NAME, GATEWAY_NETWORK
+from bot_bottle.orchestrator.lifecycle import OrchestratorService
+from tests._docker import skip_unless_docker
+
+# One upstream reachable under two names; reflects the Authorization header so
+# the probe can see exactly what the gateway injected (or didn't).
+_ECHO_NAME = "bot-bottle-mtitest-echo"
+_ECHO_ALIASES = ("echo-shared", "echo-bonly")
+_ECHO_SRC = (
+    "from http.server import BaseHTTPRequestHandler, HTTPServer\n"
+    "class H(BaseHTTPRequestHandler):\n"
+    " def do_GET(s):\n"
+    "  a=s.headers.get('Authorization','NONE'); s.send_response(200); s.end_headers()\n"
+    "  s.wfile.write(('AUTH='+a).encode())\n"
+    " def log_message(s,*a): pass\n"
+    "HTTPServer(('0.0.0.0',80),H).serve_forever()\n"
+)
+
+# A: echo-shared only, authed.  B: echo-shared authed + echo-bonly open.
+_POLICY_A = (
+    'routes:\n'
+    '  - host: echo-shared\n'
+    '    auth_scheme: "Bearer"\n'
+    '    token_env: "EGRESS_TOKEN_0"\n'
+)
+_POLICY_B = _POLICY_A + '  - host: echo-bonly\n'
+_TOKEN_A = "sk-AAA-alice"
+_TOKEN_B = "sk-BBB-bob"
+
+# Client probe: open http://<host>/ through the gateway proxy from a container
+# pinned to the bottle's source IP, printing "<status> <body>". Uses only the
+# bundle image's python3 — no dependency on the agent image.
+_PROBE_SRC = (
+    "import sys,urllib.request,urllib.error\n"
+    "op=urllib.request.build_opener(urllib.request.ProxyHandler({'http':sys.argv[1]}))\n"
+    "try:\n"
+    " r=op.open('http://'+sys.argv[2]+'/',timeout=8)\n"
+    " sys.stdout.write(str(r.status)+' '+r.read().decode())\n"
+    "except urllib.error.HTTPError as e:\n"
+    " sys.stdout.write(str(e.code)+' '+e.read().decode())\n"
+)
+
+
+@skip_unless_docker()
+@unittest.skipIf(
+    os.environ.get("GITEA_ACTIONS") == "true",
+    "skipped under act_runner: the orchestrator container bind-mounts the repo "
+    "path into a container on the socket-shared host daemon, which can't see the "
+    "runner's /workspace — same host-bind-mount constraint as the other "
+    "bottle-bringup integration tests",
+)
+class TestMultitenantIsolation(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmp.cleanup)
+        # Throwaway root → a clean registry DB, independent of the host's.
+        self.svc = OrchestratorService(host_root=Path(self._tmp.name))
+        self.addCleanup(self._teardown_docker)
+        # ensure_running builds the bundle image (slow on a cold cache) and
+        # brings up the shared network + gateway + orchestrator.
+        url = self.svc.ensure_running(startup_timeout=300)
+        self.client = OrchestratorClient(url)
+        self.gw_ip = self._container_ip(GATEWAY_NAME)
+        self._run_echo()
+
+    def _teardown_docker(self) -> None:
+        subprocess.run(["docker", "rm", "--force", _ECHO_NAME],
+                       stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False)
+        self.svc.stop()
+        subprocess.run(["docker", "network", "rm", GATEWAY_NETWORK],
+                       stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False)
+        # The orchestrator container wrote the registry DB as root into the
+        # throwaway root; chown it back so the (non-root) tempdir cleanup can
+        # remove it.
+        subprocess.run(
+            ["docker", "run", "--rm", "-v", f"{self._tmp.name}:/r",
+             "--entrypoint", "chown", GATEWAY_IMAGE, "-R",
+             f"{os.getuid()}:{os.getgid()}", "/r"],
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False)
+
+    @staticmethod
+    def _container_ip(name: str) -> str:
+        proc = subprocess.run(
+            ["docker", "inspect", "-f",
+             '{{(index .NetworkSettings.Networks "' + GATEWAY_NETWORK + '").IPAddress}}', name],
+            stdout=subprocess.PIPE, text=True, check=True,
+        )
+        return proc.stdout.strip()
+
+    def _run_echo(self) -> None:
+        argv = ["docker", "run", "--detach", "--name", _ECHO_NAME,
+                "--network", GATEWAY_NETWORK]
+        for alias in _ECHO_ALIASES:
+            argv += ["--network-alias", alias]
+        argv += ["--entrypoint", "python3", GATEWAY_IMAGE, "-c", _ECHO_SRC]
+        proc = subprocess.run(argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                              text=True, check=False)
+        self.assertEqual(0, proc.returncode, f"echo upstream failed: {proc.stderr}")
+
+    def _free_ip(self, extra_taken: list[str]) -> str:
+        taken = _network_container_ips(GATEWAY_NETWORK) + extra_taken
+        return next_free_ip(_network_cidr(GATEWAY_NETWORK), taken)
+
+    def _probe(self, source_ip: str, host: str) -> str:
+        proc = subprocess.run(
+            ["docker", "run", "--rm", "--network", GATEWAY_NETWORK, "--ip", source_ip,
+             "--entrypoint", "python3", GATEWAY_IMAGE, "-c", _PROBE_SRC,
+             f"http://{self.gw_ip}:{EGRESS_PORT}", host],
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, check=False, timeout=90,
+        )
+        return proc.stdout.strip()
+
+    def test_two_bottles_share_gateway_with_isolated_tokens_and_allowlists(self) -> None:
+        ip_a = self._free_ip([])
+        ip_b = self._free_ip([ip_a])
+        self.client.register_bottle(ip_a, policy=_POLICY_A, tokens={"EGRESS_TOKEN_0": _TOKEN_A})
+        self.client.register_bottle(ip_b, policy=_POLICY_B, tokens={"EGRESS_TOKEN_0": _TOKEN_B})
+
+        # Each bottle gets its OWN token injected on the shared route — no bleed.
+        self.assertEqual(f"200 AUTH=Bearer {_TOKEN_A}", self._probe(ip_a, "echo-shared"))
+        self.assertEqual(f"200 AUTH=Bearer {_TOKEN_B}", self._probe(ip_b, "echo-shared"))
+
+        # Allowlist is per-bottle: echo-bonly is only in B's policy.
+        self.assertTrue(self._probe(ip_a, "echo-bonly").startswith("403"),  # fail-closed for A
+                        "A reached a host outside its allowlist")
+        self.assertEqual("200 AUTH=NONE", self._probe(ip_b, "echo-bonly"))  # allowed, unauthed for B
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/integration/test_orchestrator_docker_broker.py

@@ -0,0 +1,56 @@
+"""Integration: the Docker launch broker starts and removes a real container.
+
+Gated on a reachable Docker daemon (skips cleanly otherwise). Uses a tiny
+image; the container may exit immediately — we only assert it exists after
+launch and is gone after teardown.
+"""
+
+from __future__ import annotations
+
+import secrets
+import subprocess
+import unittest
+
+from bot_bottle.orchestrator.broker import LaunchRequest, sign_request
+from bot_bottle.orchestrator.docker_broker import DockerBroker, container_name
+from tests._docker import skip_unless_docker
+
+IMAGE = "busybox"
+
+
+@skip_unless_docker()
+class TestDockerBrokerIntegration(unittest.TestCase):
+    def setUp(self) -> None:
+        self.secret = secrets.token_bytes(16)
+        self.broker = DockerBroker(self.secret)
+        self.bottle_id = "itest" + secrets.token_hex(4)
+        self.name = container_name(self.bottle_id)
+        self.addCleanup(
+            lambda: subprocess.run(
+                ["docker", "rm", "--force", self.name],
+                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
+            )
+        )
+
+    def _exists(self) -> bool:
+        proc = subprocess.run(
+            ["docker", "ps", "-a", "--filter", f"name=^{self.name}$",
+             "--format", "{{.Names}}"],
+            stdout=subprocess.PIPE, text=True, check=False,
+        )
+        return self.name in proc.stdout.split()
+
+    def _submit(self, req: LaunchRequest) -> None:
+        self.broker.submit(sign_request(req, self.secret))
+
+    def test_launch_creates_then_teardown_removes(self) -> None:
+        self._submit(
+            LaunchRequest(op="launch", bottle_id=self.bottle_id, image_ref=IMAGE)
+        )
+        self.assertTrue(self._exists(), "container should exist after launch")
+        self._submit(LaunchRequest(op="teardown", bottle_id=self.bottle_id))
+        self.assertFalse(self._exists(), "container should be gone after teardown")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/integration/test_orchestrator_docker_gateway.py

@@ -0,0 +1,45 @@
+"""Integration: the consolidated Docker gateway is an idempotent singleton.
+
+Gated on a reachable Docker daemon. Uses a unique name so it never
+collides with a real per-host gateway or a leftover from another run.
+"""
+
+from __future__ import annotations
+
+import secrets
+import subprocess
+import unittest
+
+from bot_bottle.orchestrator.gateway import DockerGateway
+from tests._docker import skip_unless_docker
+
+IMAGE = "busybox"
+
+
+@skip_unless_docker()
+class TestDockerGatewayIntegration(unittest.TestCase):
+    def setUp(self) -> None:
+        self.name = "bot-bottle-orch-gateway-itest-" + secrets.token_hex(4)
+        self.sc = DockerGateway(IMAGE, name=self.name)
+        self.addCleanup(self.sc.stop)
+
+    def _count(self) -> int:
+        proc = subprocess.run(
+            ["docker", "ps", "-a", "--filter", f"name=^{self.name}$",
+             "--format", "{{.Names}}"],
+            stdout=subprocess.PIPE, text=True, check=False,
+        )
+        return sum(1 for n in proc.stdout.split() if n == self.name)
+
+    def test_ensure_is_idempotent_singleton(self) -> None:
+        self.sc.ensure_running()
+        self.assertEqual(1, self._count())
+        # A second ensure must not spawn a second container — one per host.
+        self.sc.ensure_running()
+        self.assertEqual(1, self._count())
+        self.sc.stop()
+        self.assertEqual(0, self._count())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/integration/test_orchestrator_docker_gateway_build.py

@@ -0,0 +1,36 @@
+"""Integration: DockerGateway.image_exists reflects real docker state.
+
+Gated on a reachable Docker daemon. Deliberately does NOT build the full
+gateway (a heavy, slow image build) — it exercises the `image_exists`
+primitive that `ensure_built` gates on, against a tiny pulled image and a
+name that can't exist.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import unittest
+
+from bot_bottle.orchestrator.gateway import DockerGateway
+from tests._docker import skip_unless_docker
+
+IMAGE = "busybox"
+
+
+@skip_unless_docker()
+class TestDockerGatewayImageExists(unittest.TestCase):
+    def test_image_exists_true_for_present_false_for_absent(self) -> None:
+        # Ensure the tiny image is present (build_if_missing is disabled here
+        # so this never triggers a Dockerfile.gateway build).
+        subprocess.run(
+            ["docker", "pull", IMAGE],
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
+        )
+        self.assertTrue(DockerGateway(IMAGE, dockerfile=None).image_exists())
+        self.assertFalse(
+            DockerGateway("bot-bottle-nonexistent:doesnotexist", dockerfile=None).image_exists()
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/integration/test_orphan_cleanup.py

@@ -6,7 +6,7 @@ resources.
 
 The PipelockProxy.stop idempotency case that used to live here was
 removed in PRD 0024 chunk 3 when the per-container .stop method
-went away — sidecar teardown is now compose's responsibility, and
+went away — gateway teardown is now compose's responsibility, and
 `compose down` already no-ops on missing containers."""
 
 import os

tests/integration/test_sandbox_escape.py

@@ -72,7 +72,7 @@ _DUMMY_HOST_KEY = (
     os.environ.get("GITEA_ACTIONS") == "true",
     "skipped under act_runner: egress_tls_init uses a host bind mount "
     "the runner container can't see, and the network topology hides "
-    "sibling-sidecar visibility — same constraint as the other "
+    "sibling-gateway visibility — same constraint as the other "
     "bottle-bringup integration tests",
 )
 class TestSandboxEscape(unittest.TestCase):
@@ -90,8 +90,8 @@ class TestSandboxEscape(unittest.TestCase):
 
     @classmethod
     def setUpClass(cls) -> None:
-        # Docker is always required (the agent + sidecars run under it,
+        # Docker is always required (the agent + companion containers run under it,
-        # and VM backends still use it for the sidecar bundle); the
+        # and VM backends still use it for the gateway); the
         # class-level @skip_unless_docker already covers that. Pin
         # Docker when BOT_BOTTLE_BACKEND is unset to preserve the
         # Docker-backed CI path.
@@ -121,7 +121,7 @@ class TestSandboxEscape(unittest.TestCase):
                     "egress": {
                         "routes": [{"host": "api.anthropic.com"}],
                     },
-                    # git-gate sidecar so attack 5 can push. Upstream
+                    # git-gate daemon so attack 5 can push. Upstream
                     # is intentionally unreachable — the pre-receive
                     # gitleaks hook must reject BEFORE git-gate
                     # attempts the upstream push. A preset `host_key`
@@ -275,7 +275,7 @@ class TestSandboxEscape(unittest.TestCase):
 
     def _assert_sandbox_block(self, label: str, r: object) -> None:  # type: ignore
         """A real sandbox block produces an HTTP 403 with a
-        recognizable sandbox sidecar marker in the body. ANY
+        recognizable sandbox gateway marker in the body. ANY
         other outcome (200 from upstream, 401/404 from upstream,
         non-marker 5xx) means the request escaped — the secret
         reached the network."""

tests/integration/test_sidecar_bundle_compose.py

@@ -1,106 +0,0 @@
-"""Integration: end-to-end smoke for the PRD 0024 bundle shape.
-
-Verifies that flipping `BOT_BOTTLE_SIDECAR_BUNDLE=1` produces a
-working bottle: `docker compose up` brings the agent + bundle pair
-online, the daemons inside the bundle bind their ports, and the
-agent can reach egress + supervise via the bundle's network
-aliases (no agent-side config changes between flag positions).
-
-Skipped under GITEA_ACTIONS — the bundle image is a multi-stage
-build pulling 200+MB of base layers, and the bind-mounts won't
-share filesystem with the runner container. Same constraint as
-the chunk-1 image-probe test.
-"""
-
-from __future__ import annotations
-
-import os
-import shutil
-import tempfile
-import unittest
-from pathlib import Path
-from unittest.mock import patch
-
-from bot_bottle.backend import BottleSpec, get_bottle_backend
-from bot_bottle.manifest import ManifestIndex
-from tests._docker import skip_unless_docker
-
-
-def _manifest() -> ManifestIndex:
-    """Bottle with supervise on so the bundle exercises egress +
-    supervise. Git is off because a meaningful git-gate test needs
-    a real upstream and SSH keys — out of scope for a bundle smoke."""
-    return ManifestIndex.from_json_obj({
-        "bottles": {
-            "dev": {
-                "supervise": True,
-            },
-        },
-        "agents": {
-            "demo": {"skills": [], "prompt": "", "bottle": "dev"},
-        },
-    })
-
-
-@skip_unless_docker()
-@unittest.skipIf(
-    os.environ.get("GITEA_ACTIONS") == "true",
-    "skipped under act_runner: multi-stage bundle build pulls 200+MB "
-    "of base layers and bind-mounts don't share fs with the runner",
-)
-class TestSidecarBundleCompose(unittest.TestCase):
-    """One end-to-end pass with the bundle flag on. Skipping under
-    act_runner; the local docker daemon does the work."""
-
-    def test_bottle_up_with_bundle_flag_on(self):
-        stage_dir = Path(tempfile.mkdtemp(prefix="cb-bundle-smoke."))
-        try:
-            with patch.dict(os.environ, {"BOT_BOTTLE_SIDECAR_BUNDLE": "1"}):
-                backend = get_bottle_backend("docker")
-                spec = BottleSpec(
-                    manifest=_manifest(),
-                    agent_name="demo",
-                    copy_cwd=False,
-                    user_cwd=str(stage_dir),
-                )
-                plan = backend.prepare(spec, stage_dir=stage_dir)
-                with backend.launch(plan) as bottle:
-                    # The agent's HTTPS_PROXY URL (resolved at
-                    # renderer-time) should reach egress inside
-                    # the bundle. A bare CONNECT with no upstream
-                    # URL gets rejected with 400 or 405 but proves
-                    # the listener is alive at the alias.
-                    probe = bottle.exec(
-                        "set -eu\n"
-                        "echo HTTPS_PROXY=$HTTPS_PROXY\n"
-                        "PORT=$(echo \"$HTTPS_PROXY\" | sed -E 's|.*:([0-9]+).*|\\1|')\n"
-                        "HOST=$(echo \"$HTTPS_PROXY\" | sed -E 's|http://([^:]+):.*|\\1|')\n"
-                        "echo HOST=$HOST PORT=$PORT\n"
-                        "curl -sS --max-time 5 -o /dev/null -w 'http=%{http_code}\\n' "
-                        "  \"http://$HOST:$PORT/\" || true\n"
-                    )
-                    # The supervise URL resolves to the same bundle
-                    # via its supervise alias, on a different port.
-                    supervise_probe = bottle.exec(
-                        "set -eu\n"
-                        "curl -sS --max-time 5 -o /dev/null "
-                        "  -w 'http=%{http_code}\\n' "
-                        "  \"http://supervise:9100/health\" || true\n"
-                    )
-        finally:
-            shutil.rmtree(stage_dir, ignore_errors=True)
-
-        self.assertEqual(0, probe.returncode, msg=probe.stderr)
-        # egress answered SOMETHING — any 4xx is fine, just proves
-        # the egress daemon is listening at the proxy address.
-        self.assertIn("http=", probe.stdout,
-                      f"no HTTP response from egress: {probe.stdout!r}")
-        # supervise's /health endpoint exists (PRD 0013); it should
-        # answer 200 or similar — anything non-empty proves the
-        # third daemon's alias resolves to the same bundle.
-        self.assertEqual(0, supervise_probe.returncode, msg=supervise_probe.stderr)
-        self.assertIn("http=", supervise_probe.stdout)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/__init__.py

@@ -2,16 +2,20 @@
 
 Isolates ``HOME`` to a throwaway directory for the entire unit suite so
 no test ever reads or writes the real ``~/.bot-bottle`` (state, queue,
-and audit dirs all derive from ``supervise.bot_bottle_root()`` →
+and audit dirs all derive from ``paths.bot_bottle_root()`` →
 ``Path.home()``). Without this, a test that takes a ``flock`` on the
 real audit log can **block indefinitely** when a live bottle's supervise
-sidecar holds that lock — observed as a hung ``coverage run`` at 0% CPU —
+gateway holds that lock — observed as a hung ``coverage run`` at 0% CPU —
 and unisolated tests otherwise pollute the developer's home dir.
 
 Individual tests that need their own ``HOME`` still override
 ``os.environ['HOME']`` and restore it; they now restore to this isolated
-dir rather than the real one, so isolation holds either way. Tests that
+dir rather than the real one, so isolation holds either way.
-patch ``supervise.bot_bottle_root`` directly are unaffected.
+
+Tests that need their own app-data root call ``use_bottle_root`` (below),
+which sets ``BOT_BOTTLE_ROOT`` — the supported override read by
+``paths.bot_bottle_root`` — instead of monkey-patching. One env setting
+covers every module and every flat/package copy of the helper.
 """
 
 from __future__ import annotations
@@ -20,6 +24,9 @@ import atexit
 import os
 import shutil
 import tempfile
+from collections.abc import Callable
+from pathlib import Path
+from unittest import mock
 
 _real_home = os.environ.get("HOME")
 _tmp_home = tempfile.mkdtemp(prefix="bot-bottle-unit-home.")
@@ -35,3 +42,15 @@ def _restore_home() -> None:
 
 
 atexit.register(_restore_home)
+
+
+def use_bottle_root(root: Path) -> Callable[[], None]:
+    """Redirect ``paths.bot_bottle_root()`` to ``root`` by setting
+    ``BOT_BOTTLE_ROOT`` — the supported override. Returns a callable that
+    undoes it (store it as the test's restore hook, or pass to addCleanup).
+
+    Replaces monkey-patching ``paths.bot_bottle_root``; one env var covers
+    every module and the flat/package copies alike (they all read it)."""
+    patcher = mock.patch.dict(os.environ, {"BOT_BOTTLE_ROOT": str(root)})
+    patcher.start()
+    return patcher.stop

tests/unit/_docker_bottle_plan.py

@@ -0,0 +1,160 @@
+"""Shared in-memory `DockerBottlePlan` fixture for docker-backend tests.
+
+A fully-resolved plan with toggles for the conditional-service matrix
+(git-gate / egress / supervise / canary). Consumed by the consolidated
+compose tests; kept here (rather than in a test module) so it survives
+independent of any one test file.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from bot_bottle.agent_provider import AgentProvisionPlan
+from bot_bottle.backend import BottleSpec
+from bot_bottle.backend.docker.bottle_plan import DockerBottlePlan
+from bot_bottle.egress import EgressPlan, EgressRoute
+from bot_bottle.git_gate import GitGatePlan, GitGateUpstream
+from bot_bottle.manifest import ManifestIndex
+from bot_bottle.supervise import SupervisePlan
+
+
+SLUG = "demo-abc12"
+STAGE = Path("/tmp/cb-stage")
+STATE = Path("/tmp/cb-state")
+
+# Exported to consumers (e.g. test_consolidated_compose); named with a
+# leading underscore for the historical fixture convention.
+__all__ = ["_plan"]
+
+
+def _manifest(*, supervise: bool, with_git: bool, with_egress: bool) -> ManifestIndex:
+    """Minimal manifest with the toggles the matrix needs. The renderer
+    only reads from the plan, not the manifest, so this is just here to
+    back BottleSpec."""
+    bottle: dict[str, object] = {}
+    if supervise:
+        bottle["supervise"] = True
+    if with_git:
+        bottle["git-gate"] = {"repos": {
+            "upstream": {
+                "url": "ssh://git@example.com:22/x/y.git",
+                "key": {"provider": "static", "path": "/etc/hostname"},
+            },
+        }}
+    if with_egress:
+        bottle["egress"] = {
+            "routes": [{
+                "host": "api.example",
+                "auth": {"scheme": "Bearer", "token_ref": "TOK"},
+            }],
+        }
+    return ManifestIndex.from_json_obj({
+        "bottles": {"dev": bottle},
+        "agents": {"demo": {"skills": [], "prompt": "", "bottle": "dev"}},
+    })
+
+
+def _git_gate_plan(upstreams: tuple[GitGateUpstream, ...] = ()) -> GitGatePlan:
+    return GitGatePlan(
+        slug=SLUG,
+        entrypoint_script=STATE / "git-gate" / "entrypoint.sh",
+        hook_script=STATE / "git-gate" / "pre-receive",
+        access_hook_script=STATE / "git-gate" / "access-hook",
+        upstreams=upstreams,
+        internal_network=f"bot-bottle-net-{SLUG}",
+        egress_network=f"bot-bottle-egress-{SLUG}",
+    )
+
+
+def _egress_plan(
+    routes: tuple[EgressRoute, ...] = (),
+    *,
+    canary: bool = False,
+) -> EgressPlan:
+    token_env_map = {
+        r.token_env: r.token_ref
+        for r in routes
+        if r.token_env
+    }
+    return EgressPlan(
+        slug=SLUG,
+        routes_path=STATE / "egress" / "routes.yaml",
+        routes=routes,
+        token_env_map=token_env_map,
+        internal_network=f"bot-bottle-net-{SLUG}",
+        egress_network=f"bot-bottle-egress-{SLUG}",
+        mitmproxy_ca_host_path=STATE / "egress-ca" / "mitmproxy-ca.pem",
+        mitmproxy_ca_cert_only_host_path=STATE / "egress-ca" / "ca.pem",
+        canary="fake-canary-value" if canary else "",
+        canary_env="CANON_ALPHA_SECRET" if canary else "",
+    )
+
+
+def _supervise_plan() -> SupervisePlan:
+    return SupervisePlan(
+        slug=SLUG,
+        db_path=STATE / "bot-bottle.db",
+        internal_network=f"bot-bottle-net-{SLUG}",
+    )
+
+
+def _plan(
+    *,
+    with_git: bool = False,
+    with_egress: bool = False,
+    supervise: bool = False,
+    canary: bool = False,
+) -> DockerBottlePlan:
+    """Build a fully-resolved DockerBottlePlan. Toggles cover the
+    matrix the renderer's conditional-service logic branches on."""
+    upstreams: tuple[GitGateUpstream, ...] = ()
+    if with_git:
+        upstreams = (GitGateUpstream(
+            name="upstream",
+            upstream_url="ssh://git@example.com:22/x/y.git",
+            upstream_host="example.com",
+            upstream_port="22",
+            identity_file="/etc/hostname",
+            known_host_key="",
+            known_hosts_file=STATE / "git-gate" / "upstream-known_hosts",
+        ),)
+    routes: tuple[EgressRoute, ...] = ()
+    if with_egress:
+        routes = (EgressRoute(
+            host="api.example",
+            auth_scheme="Bearer",
+            token_env="EGRESS_TOKEN_0",
+            token_ref="TOK",
+            roles=(),
+        ),)
+
+    index = _manifest(supervise=supervise, with_git=with_git, with_egress=with_egress)
+    spec = BottleSpec(
+        manifest=index,
+        agent_name="demo",
+        copy_cwd=False,
+        user_cwd="/tmp/x",
+    )
+    return DockerBottlePlan(
+        spec=spec,
+        manifest=index.load_for_agent("demo"),
+        stage_dir=STAGE,
+        slug=SLUG,
+        forwarded_env={"CLAUDE_CODE_OAUTH_TOKEN": "x"},
+        git_gate_plan=_git_gate_plan(upstreams),
+        egress_plan=_egress_plan(routes, canary=canary),
+        supervise_plan=_supervise_plan() if supervise else None,
+        use_runsc=False,
+        agent_provision=AgentProvisionPlan(
+            template="claude",
+            command="claude",
+            prompt_mode="append_file",
+            image="bot-bottle-claude:latest",
+            dockerfile="",
+            guest_home="/home/node",
+            instance_name=f"bot-bottle-{SLUG}",
+            prompt_file=STAGE / "prompt",
+            guest_env={},
+        ),
+    )

tests/unit/test_backend_freezer.py

@@ -7,7 +7,8 @@ import unittest
 from pathlib import Path
 from unittest.mock import patch
 
-from bot_bottle import supervise, bottle_state
+from bot_bottle import bottle_state
+from tests.unit import use_bottle_root
 from bot_bottle.backend import ActiveAgent
 from bot_bottle.backend.freeze import get_freezer
 from bot_bottle.backend.docker.freezer import DockerFreezer
@@ -18,13 +19,7 @@ from bot_bottle.backend.firecracker.freezer import FirecrackerFreezer
 class _FakeHomeMixin:
     def _setup_fake_home(self):
         self._tmp = tempfile.TemporaryDirectory(prefix="freezer-test.")
-        original = supervise.bot_bottle_root
+        self._restore = use_bottle_root(Path(self._tmp.name) / ".bot-bottle")
-
-        def fake_root() -> Path:
-            return Path(self._tmp.name) / ".bot-bottle"
-
-        supervise.bot_bottle_root = fake_root  # type: ignore[assignment]
-        self._restore = lambda: setattr(supervise, "bot_bottle_root", original)
 
     def _teardown_fake_home(self):
         self._restore()

tests/unit/test_backend_prepare.py

@@ -13,7 +13,7 @@ from pathlib import Path
 from unittest.mock import patch
 
 from bot_bottle import bottle_state
-from bot_bottle import supervise
+from tests.unit import use_bottle_root
 from bot_bottle.backend import BottleSpec
 from bot_bottle.backend.docker import DockerBottleBackend
 from bot_bottle.backend.resolve_common import mint_slug
@@ -55,11 +55,10 @@ class _FakeStateMixin:
     def setUp(self) -> None:
         self.tmp = tempfile.TemporaryDirectory(prefix="backend-prepare.")
         self.root = Path(self.tmp.name) / ".bot-bottle"
-        self.original_root = supervise.bot_bottle_root
+        self._restore = use_bottle_root(self.root)
-        supervise.bot_bottle_root = lambda: self.root  # type: ignore[assignment]
 
     def tearDown(self) -> None:
-        supervise.bot_bottle_root = self.original_root  # type: ignore[assignment]
+        self._restore()
         self.tmp.cleanup()
 
 

tests/unit/test_backend_workspace.py

@@ -13,7 +13,7 @@ from pathlib import Path
 from unittest.mock import MagicMock, call, patch
 
 from bot_bottle import bottle_state
-from bot_bottle import supervise
+from tests.unit import use_bottle_root
 from bot_bottle.backend import Bottle, BottleSpec, ExecResult
 from bot_bottle.backend.docker import DockerBottleBackend
 from bot_bottle.backend.firecracker import FirecrackerBottleBackend
@@ -55,11 +55,10 @@ class _FakeStateMixin:
         self.tmp_dir = tempfile.TemporaryDirectory(prefix="backend-workspace.")
         self.tmp = Path(self.tmp_dir.name)
         self.root = self.tmp / ".bot-bottle"
-        self.original_root = supervise.bot_bottle_root
+        self._restore = use_bottle_root(self.root)
-        supervise.bot_bottle_root = lambda: self.root  # type: ignore[assignment]
 
     def tearDown(self) -> None:
-        supervise.bot_bottle_root = self.original_root  # type: ignore[assignment]
+        self._restore()
         self.tmp_dir.cleanup()
 
 

tests/unit/test_bottle_state.py

@@ -6,7 +6,7 @@ import tempfile
 import unittest
 from pathlib import Path
 
-from bot_bottle import supervise
+from tests.unit import use_bottle_root
 from bot_bottle import bottle_state
 from bot_bottle.bottle_state import (
     BottleMetadata,
@@ -18,13 +18,7 @@ from bot_bottle.bottle_state import (
 class _FakeHomeMixin:
     def _setup_fake_home(self):
         self._tmp = tempfile.TemporaryDirectory(prefix="bottle-state-test.")
-        original = supervise.bot_bottle_root
+        self._restore = use_bottle_root(Path(self._tmp.name) / ".bot-bottle")
-
-        def fake_root() -> Path:
-            return Path(self._tmp.name) / ".bot-bottle"
-
-        supervise.bot_bottle_root = fake_root  # type: ignore[assignment]
-        self._restore = lambda: setattr(supervise, "bot_bottle_root", original)
 
     def _teardown_fake_home(self):
         self._restore()

tests/unit/test_cli_commit.py

@@ -8,7 +8,7 @@ from pathlib import Path
 from unittest.mock import MagicMock, patch
 
 from bot_bottle.cli.commit import cmd_commit
-from bot_bottle import supervise
+from tests.unit import use_bottle_root
 from bot_bottle import bottle_state
 from bot_bottle.backend.freeze import CommitCancelled
 
@@ -16,13 +16,7 @@ from bot_bottle.backend.freeze import CommitCancelled
 class _FakeHomeMixin:
     def _setup_fake_home(self):
         self._tmp = tempfile.TemporaryDirectory(prefix="cli-commit-test.")
-        original = supervise.bot_bottle_root
+        self._restore = use_bottle_root(Path(self._tmp.name) / ".bot-bottle")
-
-        def fake_root() -> Path:
-            return Path(self._tmp.name) / ".bot-bottle"
-
-        supervise.bot_bottle_root = fake_root  # type: ignore[assignment]
-        self._restore = lambda: setattr(supervise, "bot_bottle_root", original)
 
     def _teardown_fake_home(self):
         self._restore()

tests/unit/test_cli_start_settle.py

@@ -8,7 +8,7 @@ import tempfile
 import unittest
 from pathlib import Path
 
-from bot_bottle import supervise
+from tests.unit import use_bottle_root
 from bot_bottle import bottle_state
 from bot_bottle.cli import start as start_mod
 
@@ -16,15 +16,10 @@ from bot_bottle.cli import start as start_mod
 class _FakeHomeMixin:
     def _setup_fake_home(self):
         self._tmp = tempfile.TemporaryDirectory(prefix="cli-start-settle.")
-        self._original = supervise.bot_bottle_root
+        self._restore = use_bottle_root(Path(self._tmp.name) / ".bot-bottle")
-
-        def fake_root() -> Path:
-            return Path(self._tmp.name) / ".bot-bottle"
-
-        supervise.bot_bottle_root = fake_root  # type: ignore[assignment]
 
     def _teardown_fake_home(self):
-        supervise.bot_bottle_root = self._original  # type: ignore[assignment]
+        self._restore()
         self._tmp.cleanup()
 
 

tests/unit/test_compose.py

@@ -1,434 +1,23 @@
-"""Unit: compose-spec renderer (PRD 0018 chunk 1).
+"""Unit: docker compose lifecycle helpers (PRD 0018).
 
-Pure-function tests for `bottle_plan_to_compose`. Fixtures build a
+The compose *spec* is built by `consolidated_compose.py`; these
-fully-resolved DockerBottlePlan in memory; the renderer just
+tests cover the I/O-side helpers in `compose.py` — the slug ↔
-translates it to the compose dict. Conditional-service matrix is
+project mapping and `docker compose ls` enumeration.
-covered via parameterized cases (git on/off × egress on/off ×
-supervise on/off).
 """
 
 from __future__ import annotations
 
 import subprocess
 import unittest
-from pathlib import Path
-from typing import Any
 from unittest import mock
 
-from bot_bottle.agent_provider import AgentProvisionPlan
-from bot_bottle.backend import BottleSpec
-from bot_bottle.backend.docker.bottle_plan import DockerBottlePlan
 from bot_bottle.backend.docker.compose import (
     COMPOSE_PROJECT_PREFIX,
-    bottle_plan_to_compose,
     compose_project_name,
     list_active_slugs,
     list_compose_projects,
     slug_from_compose_project,
 )
-from bot_bottle.egress import (
-    EgressPlan,
-    EgressRoute,
-)
-from bot_bottle.git_gate import GitGatePlan, GitGateUpstream
-from bot_bottle.manifest import ManifestIndex
-from bot_bottle.supervise import SupervisePlan
-
-
-SLUG = "demo-abc12"
-STAGE = Path("/tmp/cb-stage")
-STATE = Path("/tmp/cb-state")
-
-
-def _manifest(*, supervise: bool, with_git: bool, with_egress: bool) -> ManifestIndex:
-    """Minimal manifest with the toggles the chunk-1 matrix needs.
-    The renderer only reads from the plan, not the manifest, so this
-    is just here to back BottleSpec."""
-    bottle: dict[str, object] = {}
-    if supervise:
-        bottle["supervise"] = True
-    if with_git:
-        bottle["git-gate"] = {"repos": {
-            "upstream": {
-                "url": "ssh://git@example.com:22/x/y.git",
-                "key": {"provider": "static", "path": "/etc/hostname"},
-            },
-        }}
-    if with_egress:
-        bottle["egress"] = {
-            "routes": [{
-                "host": "api.example",
-                "auth": {"scheme": "Bearer", "token_ref": "TOK"},
-            }],
-        }
-    return ManifestIndex.from_json_obj({
-        "bottles": {"dev": bottle},
-        "agents": {"demo": {"skills": [], "prompt": "", "bottle": "dev"}},
-    })
-
-
-
-def _git_gate_plan(upstreams: tuple[GitGateUpstream, ...] = ()) -> GitGatePlan:
-    return GitGatePlan(
-        slug=SLUG,
-        entrypoint_script=STATE / "git-gate" / "entrypoint.sh",
-        hook_script=STATE / "git-gate" / "pre-receive",
-        access_hook_script=STATE / "git-gate" / "access-hook",
-        upstreams=upstreams,
-        internal_network=f"bot-bottle-net-{SLUG}",
-        egress_network=f"bot-bottle-egress-{SLUG}",
-    )
-
-
-def _egress_plan(
-    routes: tuple[EgressRoute, ...] = (),
-    *,
-    canary: bool = False,
-) -> EgressPlan:
-    token_env_map = {
-        r.token_env: r.token_ref
-        for r in routes
-        if r.token_env
-    }
-    return EgressPlan(
-        slug=SLUG,
-        routes_path=STATE / "egress" / "routes.yaml",
-        routes=routes,
-        token_env_map=token_env_map,
-        internal_network=f"bot-bottle-net-{SLUG}",
-        egress_network=f"bot-bottle-egress-{SLUG}",
-        mitmproxy_ca_host_path=STATE / "egress-ca" / "mitmproxy-ca.pem",
-        mitmproxy_ca_cert_only_host_path=STATE / "egress-ca" / "ca.pem",
-        canary="fake-canary-value" if canary else "",
-        canary_env="CANON_ALPHA_SECRET" if canary else "",
-    )
-
-
-def _supervise_plan() -> SupervisePlan:
-    return SupervisePlan(
-        slug=SLUG,
-        db_path=STATE / "bot-bottle.db",
-        internal_network=f"bot-bottle-net-{SLUG}",
-    )
-
-
-def _plan(
-    *,
-    with_git: bool = False,
-    with_egress: bool = False,
-    supervise: bool = False,
-    canary: bool = False,
-) -> DockerBottlePlan:
-    """Build a fully-resolved DockerBottlePlan. Toggles cover the
-    matrix the renderer's conditional-service logic branches on."""
-    upstreams: tuple[GitGateUpstream, ...] = ()
-    if with_git:
-        upstreams = (GitGateUpstream(
-            name="upstream",
-            upstream_url="ssh://git@example.com:22/x/y.git",
-            upstream_host="example.com",
-            upstream_port="22",
-            identity_file="/etc/hostname",
-            known_host_key="",
-            known_hosts_file=STATE / "git-gate" / "upstream-known_hosts",
-        ),)
-    routes: tuple[EgressRoute, ...] = ()
-    if with_egress:
-        routes = (EgressRoute(
-            host="api.example",
-            auth_scheme="Bearer",
-            token_env="EGRESS_TOKEN_0",
-            token_ref="TOK",
-            roles=(),
-        ),)
-
-    index = _manifest(supervise=supervise, with_git=with_git, with_egress=with_egress)
-    spec = BottleSpec(
-        manifest=index,
-        agent_name="demo",
-        copy_cwd=False,
-        user_cwd="/tmp/x",
-    )
-    return DockerBottlePlan(
-        spec=spec,
-        manifest=index.load_for_agent("demo"),
-        stage_dir=STAGE,
-        slug=SLUG,
-        forwarded_env={"CLAUDE_CODE_OAUTH_TOKEN": "x"},
-        git_gate_plan=_git_gate_plan(upstreams),
-        egress_plan=_egress_plan(routes, canary=canary),
-        supervise_plan=_supervise_plan() if supervise else None,
-        use_runsc=False,
-        agent_provision=AgentProvisionPlan(
-            template="claude",
-            command="claude",
-            prompt_mode="append_file",
-            image="bot-bottle-claude:latest",
-            dockerfile="",
-            guest_home="/home/node",
-            instance_name=f"bot-bottle-{SLUG}",
-            prompt_file=STAGE / "prompt",
-            guest_env={},
-        ),
-    )
-
-
-class TestProjectAndNetworks(unittest.TestCase):
-    def test_project_name(self):
-        spec = bottle_plan_to_compose(_plan())
-        self.assertEqual(f"bot-bottle-{SLUG}", spec["name"])
-
-    def test_internal_network_is_internal(self):
-        spec = bottle_plan_to_compose(_plan())
-        net = spec["networks"]["internal"]
-        self.assertEqual(f"bot-bottle-net-{SLUG}", net["name"])
-        self.assertTrue(net["internal"])
-
-    def test_egress_network_is_external_bridge(self):
-        spec = bottle_plan_to_compose(_plan())
-        net = spec["networks"]["egress"]
-        self.assertEqual(f"bot-bottle-egress-{SLUG}", net["name"])
-        # No `internal:` key on the egress network — defaults to a
-        # normal user-defined bridge.
-        self.assertNotIn("internal", net)
-
-
-class TestAgentAlwaysPresent(unittest.TestCase):
-    def test_agent_in_services(self):
-        s = bottle_plan_to_compose(_plan())["services"]
-        self.assertIn("agent", s)
-
-    def test_agent_command(self):
-        s = bottle_plan_to_compose(_plan())["services"]["agent"]
-        self.assertEqual(["sleep", "infinity"], s["command"])
-
-    def test_agent_image_uses_runtime_image(self):
-        plan = _plan()
-        s = bottle_plan_to_compose(plan)["services"]["agent"]
-        self.assertEqual(plan.image, s["image"])
-
-    def test_agent_only_on_internal_network(self):
-        s = bottle_plan_to_compose(_plan())["services"]["agent"]
-        self.assertEqual({"internal"}, set(s["networks"].keys()))
-
-    def test_agent_proxy_always_via_egress(self):
-        for with_egress in (False, True):
-            with self.subTest(with_egress=with_egress):
-                s = bottle_plan_to_compose(
-                    _plan(with_egress=with_egress)
-                )["services"]["agent"]
-                proxy_lines = [e for e in s["environment"] if e.startswith("HTTPS_PROXY=")]
-                self.assertEqual(1, len(proxy_lines))
-                self.assertEqual("HTTPS_PROXY=http://egress:9099", proxy_lines[0])
-
-    def test_agent_proxy_via_egress_when_egress_present(self):
-        s = bottle_plan_to_compose(_plan(with_egress=True))["services"]["agent"]
-        proxy = [e for e in s["environment"] if e.startswith("HTTPS_PROXY=")][0]
-        self.assertEqual("HTTPS_PROXY=http://egress:9099", proxy)
-
-    def test_agent_no_proxy_adds_supervise_when_enabled(self):
-        s = bottle_plan_to_compose(
-            _plan(supervise=True)
-        )["services"]["agent"]
-        no_proxy = [e for e in s["environment"] if e.startswith("NO_PROXY=")][0]
-        self.assertIn("supervise", no_proxy)
-
-    def test_agent_forwarded_env_uses_bare_names(self):
-        # Bare NAME → compose inherits value from the up-process env,
-        # so secret token values stay out of the file.
-        s = bottle_plan_to_compose(_plan())["services"]["agent"]
-        self.assertIn("CLAUDE_CODE_OAUTH_TOKEN", s["environment"])
-
-    def test_agent_provider_env_uses_literal_values(self):
-        plan = _plan()
-        provision = AgentProvisionPlan(
-            template="codex",
-            command="codex",
-            prompt_mode="read_prompt_file",
-            image="bot-bottle-codex:latest",
-            dockerfile="",
-            guest_home="/home/node",
-            instance_name=f"bot-bottle-{SLUG}",
-            prompt_file=STAGE / "prompt",
-            guest_env={"CODEX_HOME": "/home/node/.codex"},
-        )
-        plan = type(plan)(**{**vars(plan), "agent_provision": provision})  # type: ignore
-        s = bottle_plan_to_compose(plan)["services"]["agent"]
-        self.assertIn("CODEX_HOME=/home/node/.codex", s["environment"])
-
-    def test_agent_runsc_runtime(self):
-        plan = _plan()
-        plan = type(plan)(**{**vars(plan), "use_runsc": True})  # type: ignore
-        s = bottle_plan_to_compose(plan)["services"]["agent"]
-        self.assertEqual("runsc", s["runtime"])
-
-    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.
-        for kwargs in [{}, {"with_git": True, "with_egress": True, "supervise": True}]:
-            with self.subTest(**kwargs):
-                s = bottle_plan_to_compose(_plan(**kwargs))["services"]["agent"]
-                self.assertEqual(["sidecars"], s["depends_on"])
-
-    def test_agent_has_no_current_config_mount_with_supervise(self):
-        with_sv = bottle_plan_to_compose(_plan(supervise=True))["services"]["agent"]
-        self.assertNotIn("volumes", with_sv)
-        without_sv = bottle_plan_to_compose(_plan(supervise=False))["services"]["agent"]
-        self.assertNotIn("volumes", without_sv)
-
-
-class TestSidecarBundleShape(unittest.TestCase):
-    """The compose renderer emits exactly one `sidecars` service in
-    place of the daemons it owns (egress + git-gate + supervise).
-    PRD 0024 chunk 5 dropped the legacy four-sidecar shape entirely,
-    so the bundle is the only thing exercised here."""
-
-    def _render(self, **plan_kwargs: object) -> Any:  # type: ignore
-        return bottle_plan_to_compose(_plan(**plan_kwargs))  # type: ignore
-
-    def test_emits_two_services_minimal(self):
-        spec = self._render()
-        self.assertEqual({"sidecars", "agent"}, set(spec["services"].keys()))
-
-    def test_emits_two_services_full_matrix(self):
-        spec = self._render(with_git=True, with_egress=True, supervise=True)
-        # Still two services — the bundle absorbs git-gate/egress/supervise.
-        self.assertEqual({"sidecars", "agent"}, set(spec["services"].keys()))
-
-    def test_bundle_uses_bundle_image_and_dockerfile(self):
-        sc = self._render()["services"]["sidecars"]
-        self.assertEqual("bot-bottle-sidecars:latest", sc["image"])
-        self.assertEqual("Dockerfile.sidecars", sc["build"]["dockerfile"])
-
-    def test_bundle_container_name_uses_sidecars_prefix(self):
-        sc = self._render()["services"]["sidecars"]
-        self.assertEqual(f"bot-bottle-sidecars-{SLUG}", sc["container_name"])
-
-    def test_bundle_joins_both_networks(self):
-        sc = self._render()["services"]["sidecars"]
-        self.assertEqual({"internal", "egress"}, set(sc["networks"].keys()))
-
-    def test_internal_aliases_include_egress_shortname(self):
-        sc = self._render()["services"]["sidecars"]
-        aliases = set(sc["networks"]["internal"]["aliases"])
-        self.assertIn("egress", aliases)
-
-    def test_internal_aliases_omit_inactive_sidecars(self):
-        # With no git-gate / supervise, those names are NOT aliased
-        # — keeps the alias list honest about what's actually
-        # listening inside the bundle.
-        sc = self._render()["services"]["sidecars"]
-        aliases = set(sc["networks"]["internal"]["aliases"])
-        self.assertNotIn("git-gate", aliases)
-        self.assertNotIn("supervise", aliases)
-
-    def test_internal_aliases_include_active_sidecars(self):
-        sc = self._render(with_git=True, supervise=True)["services"]["sidecars"]
-        aliases = set(sc["networks"]["internal"]["aliases"])
-        self.assertIn("git-gate", aliases)
-        self.assertIn("supervise", aliases)
-
-    def test_daemons_csv_lists_only_active(self):
-        sc = self._render()["services"]["sidecars"]
-        daemons = {
-            line.split("=", 1)[1]
-            for line in sc["environment"]
-            if line.startswith("BOT_BOTTLE_SIDECAR_DAEMONS=")
-        }
-        self.assertEqual({"egress"}, daemons)
-
-    def test_daemons_csv_expands_with_optional_sidecars(self):
-        sc = self._render(with_git=True, supervise=True)["services"]["sidecars"]
-        for line in sc["environment"]:
-            if line.startswith("BOT_BOTTLE_SIDECAR_DAEMONS="):
-                csv = line.split("=", 1)[1]
-                break
-        else:
-            self.fail("BOT_BOTTLE_SIDECAR_DAEMONS not in env")
-        self.assertEqual(
-            ["egress", "git-gate", "supervise"],
-            csv.split(","),
-        )
-
-    def test_bundle_env_does_not_set_https_proxy(self):
-        # HTTPS_PROXY at the container level would route git-gate's
-        # git fetches through the proxy. Scoping it to mitmdump is
-        # the job of egress_entrypoint.sh; the bundle env must not
-        # leak it.
-        sc = self._render(with_egress=True)["services"]["sidecars"]
-        for line in sc["environment"]:
-            self.assertFalse(
-                line.startswith("HTTPS_PROXY=")
-                or line.startswith("HTTP_PROXY=")
-                or line.startswith("NO_PROXY="),
-                f"bundle env must not set {line!r}",
-            )
-
-    def test_egress_token_env_present_when_routes_declared(self):
-        sc = self._render(with_egress=True)["services"]["sidecars"]
-        env_strings = sc["environment"]
-        self.assertIn("EGRESS_TOKEN_0", env_strings)
-
-    def test_egress_token_env_omitted_when_no_routes(self):
-        sc = self._render()["services"]["sidecars"]
-        env_strings = sc["environment"]
-        self.assertNotIn("EGRESS_TOKEN_0", env_strings)
-
-    def test_canary_env_registered_as_sensitive_in_sidecar(self):
-        sc = self._render(canary=True)["services"]["sidecars"]
-        env_strings = sc["environment"]
-        self.assertIn("CANON_ALPHA_SECRET=fake-canary-value", env_strings)
-        self.assertIn(
-            "BOT_BOTTLE_SENSITIVE_PREFIXES=CANON_ALPHA_SECRET",
-            env_strings,
-        )
-
-    def test_canary_env_visible_to_agent(self):
-        agent = self._render(canary=True)["services"]["agent"]
-        env_strings = agent["environment"]
-        self.assertIn("CANON_ALPHA_SECRET=fake-canary-value", env_strings)
-
-    def test_supervise_env_present_when_active(self):
-        sc = self._render(supervise=True)["services"]["sidecars"]
-        env_strings = sc["environment"]
-        self.assertIn(f"SUPERVISE_BOTTLE_SLUG={SLUG}", env_strings)
-        self.assertIn("SUPERVISE_DB_PATH=/run/supervise/bot-bottle.db", env_strings)
-        self.assertTrue(any(e.startswith("SUPERVISE_PORT=") for e in env_strings))
-
-    def test_volumes_always_includes_egress_ca(self):
-        sc = self._render()["services"]["sidecars"]
-        targets = {v["target"] for v in sc["volumes"]}
-        self.assertIn("/home/mitmproxy/.mitmproxy/mitmproxy-ca.pem", targets)
-
-    def test_volumes_union_full_matrix(self):
-        sc = self._render(with_git=True, with_egress=True, supervise=True)[
-            "services"]["sidecars"]
-        targets = {v["target"] for v in sc["volumes"]}
-        self.assertIn("/home/mitmproxy/.mitmproxy/mitmproxy-ca.pem", targets)
-        self.assertIn("/etc/egress", targets)
-        self.assertIn("/git-gate-entrypoint.sh", targets)
-        self.assertIn("/git-gate/creds/upstream-known_hosts", targets)
-        self.assertIn("/run/supervise/bot-bottle.db", targets)
-
-    def test_extra_hosts_omitted_for_git_upstreams(self):
-        sc = self._render(with_git=True)["services"]["sidecars"]
-        self.assertNotIn("extra_hosts", sc)
-
-    def test_agent_depends_on_bundle_only(self):
-        sc = self._render(with_git=True, with_egress=True, supervise=True)[
-            "services"]["agent"]
-        self.assertEqual(["sidecars"], sc["depends_on"])
-
-    def test_agent_proxy_url_resolves_via_bundle_alias(self):
-        # With egress active, the agent's HTTPS_PROXY points at
-        # `egress` shortname; bundle aliases `egress` to itself so
-        # the URL keeps working without an agent-side change.
-        spec = self._render(with_egress=True)
-        sc = spec["services"]["agent"]
-        proxy = next(e for e in sc["environment"] if e.startswith("HTTPS_PROXY="))
-        self.assertIn("egress", proxy)
-        self.assertIn("egress",
-                      spec["services"]["sidecars"]["networks"]["internal"]["aliases"])
 
 
 class TestProjectNaming(unittest.TestCase):