feat(orchestrator+egress): slice 8 — multi-tenant egress via the resolver (#352)

The egress addon now selects each request's Config by the calling bottle's
source IP, so one shared sidecar serves every bottle. Opt-in and fail-closed;
single-tenant behaviour is unchanged.

Orchestrator side (source-IP-primary attribution, per the PRD invariant):
  * registry: `by_source_ip` (the single active bottle at a source IP —
    network-layer attribution); `attribute` now composes it + the token.
  * service: `resolve(source_ip, token="")` — with a token, strict
    attribution; without, source IP alone.
  * control_plane: `POST /resolve`'s identity_token is now OPTIONAL (absent
    → source-IP-only); split cleanly from the token-required `/attribute`.
  * policy_resolver: `resolve` token now optional.

Egress side:
  * egress_addon_core: `resolve_client_config(resolver, client_ip, token)` —
    fetches + parses the client's Config, **fail-closed**: unattributed, a
    resolver error, or an unparseable policy all yield deny-all (no routes).
    Host-testable; `PolicyResolverLike` Protocol keeps it import-free.
  * egress_addon: consolidated mode when `BOT_BOTTLE_ORCHESTRATOR_URL` is
    set → `_active_config(flow)` resolves per client IP (reads + strips the
    `x-bot-bottle-identity` header); `request()` uses it. Unset → the static
    routes file, exactly as before. `PolicyResolver` added to the bundle.

Security note: source-IP-only resolution is safe where the IP is unspoofable
(Firecracker /31 + nft) AND the control plane is reachable only by the
trusted sidecar; the identity token, when the agent injects it, strengthens
it on weaker backends.

Scope note: the egress data plane is now multi-tenant. Remaining to be fully
live: the network topology routing every bottle's proxy to the one shared
sidecar, git-gate multitenancy, and agent-side identity-token injection.

Tests: registry by_source_ip; orchestrator resolve (with/without token);
control-plane /resolve token-optional; resolver token-optional;
resolve_client_config fail-closed matrix. All 182 egress tests still pass
(single-tenant unchanged). Full suite green.

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

.coveragerc

@@ -1,10 +1,6 @@
 [run]
 branch = True
 source = .
-# Store paths relative to the project root so .coverage.* files produced on
-# different runners (ubuntu-latest vs self-hosted KVM) can be combined by the
-# coverage job without a [paths] remapping section.
-relative_files = True
 
 [report]
 # Coverage policy: see docs/decisions/0004-coverage-policy.md.
@@ -20,9 +16,3 @@ omit =
     bot_bottle/cli/tui.py
     bot_bottle/cli/init.py
     tests/*
-    # Build-time only: setuptools invokes it out-of-process to build the
-    # wheel/sdist (it's never imported by the running app), so in-process
-    # coverage can't reach it. Its one job — bundling the root resources into
-    # bot_bottle/_resources/ — is exercised end-to-end by test_wheel_install,
-    # which builds and installs a real wheel and checks the result.
-    setup.py

.gitea/workflows/canaries.yml

@@ -2,7 +2,7 @@
 # digest, etc.) without coupling every dev push to upstream registry
 # availability.
 #
-# Opt-in via BOT_BOTTLE_RUN_CANARIES=1 so the same files can be run
+# Opt-in via CLAUDE_BOTTLE_RUN_CANARIES=1 so the same files can be run
 # locally with the same gating.
 
 name: canaries
@@ -17,15 +17,15 @@ jobs:
   canaries:
     runs-on: ubuntu-latest
     env:
-      BOT_BOTTLE_RUN_CANARIES: "1"
+      CLAUDE_BOTTLE_RUN_CANARIES: "1"
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      # No actions/setup-python: canaries are stdlib unittest on the image's
-      # system Python 3.12 (older act_runner mishandles setup-python's PATH).
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
       - name: Run canaries
-        run: |
-          python3 -m scripts.unittest_gate \
-            -t . -s tests/canaries -v \
-            --minimum-executed 1 --fail-on-skip
+        run: python3 -m unittest discover -t . -s tests/canaries -v

.gitea/workflows/lint.yml

@@ -13,30 +13,20 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      # No actions/setup-python: the runner image already ships Python 3.12,
-      # and older act_runner engines mishandle setup-python's PATH. Install
-      # into the ephemeral job container's system Python — the pylint/pyright
-      # console scripts land on /usr/local/bin (on PATH) so the steps below
-      # still resolve. --break-system-packages is safe: the container is
-      # disposable.
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+
       - name: Install dev dependencies
-        run: python3 -m pip install --break-system-packages -r requirements-dev.txt
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.txt
 
       - name: Run pylint
         run: |
-          # Pylint's normal exit code is nonzero for any emitted finding,
-          # regardless of --fail-under. Preserve the full report but enforce
-          # the aggregate score this workflow promises.
-          set +e
-          find . -name '*.py' -not -path './.venv/*' -not -path './.git/*' \
-            | xargs pylint --fail-under=8.0 \
-            | tee /tmp/pylint-output.txt
-          set -e
-          SCORE=$(sed -n \
-            's/^Your code has been rated at \([-0-9.]*\)\/10.*/\1/p' \
-            /tmp/pylint-output.txt | tail -1)
-          test -n "$SCORE"
-          awk -v score="$SCORE" 'BEGIN { exit !(score >= 8.0) }'
+          # Run pylint on all Python files in the repo
+          find . -name '*.py' -not -path './.venv/*' -not -path './.git/*' | xargs pylint --fail-under=8.0
 
       - name: Run pyright
         run: |

.gitea/workflows/prd-number-check.yml

@@ -1,27 +0,0 @@
-name: prd-number-check
-
-on:
-  pull_request:
-    types: [opened, reopened, synchronize]
-    branches: [main]
-
-jobs:
-  require-numbered-prds:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Reject unnumbered PRDs
-        run: |
-          unnumbered=$(find docs/prds -maxdepth 1 -type f \
-            -name 'prd-new-*.md' -print | sort)
-
-          if [ -n "$unnumbered" ]; then
-            echo "::error::Assign every new PRD its final sequential number before merge."
-            echo "Unnumbered PRDs:"
-            echo "$unnumbered"
-            exit 1
-          fi
-
-          echo "All PRDs have final numbers."

.gitea/workflows/prd-number.yml

@@ -0,0 +1,125 @@
+# Assign sequential numbers to prd-new-*.md files on merge to main.
+#
+# When a PR merges to main and includes prd-new-*.md files this workflow:
+#   1. Finds the next available NNNN number by scanning existing PRDs.
+#   2. Renames each prd-new-*.md to NNNN-<slug>.md.
+#   3. Updates the title header (# PRD prd-new: → # PRD NNNN:).
+#   4. Flips Status: Draft → Active when the push touched files outside
+#      docs/prds/ anywhere in its commit range (i.e. the implementation
+#      shipped together with the PRD).
+#   5. Commits the renaming back to main.
+#
+# No-op if the working tree contains no prd-new-*.md files.
+#
+# NOTE: The workflow scans the working tree (not just HEAD~1..HEAD) because
+# PRs land as multi-commit pushes and the prd-new file is often added in an
+# earlier commit on the branch, not in the final squash/merge commit.
+
+name: prd-number
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/prds/prd-new-*.md'
+
+jobs:
+  assign-numbers:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Assign PRD numbers
+        run: |
+          python3 - <<'EOF'
+          import os
+          import re
+          import subprocess
+          import sys
+          from pathlib import Path
+
+          prds_dir = Path("docs/prds")
+
+          # Scan the working tree — prd-new files may have landed in any
+          # commit of a multi-commit push, not just HEAD.
+          new_prds = sorted(prds_dir.glob("prd-new-*.md"))
+
+          if not new_prds:
+              print("No prd-new-*.md files found — nothing to do.")
+              sys.exit(0)
+
+          # Determine whether non-PRD files were also changed anywhere in
+          # the push range (BEFORE_SHA → HEAD).  Falls back to HEAD~1 when
+          # the env var isn't set (e.g. local act runs).
+          before_sha = os.environ.get("GITHUB_EVENT_BEFORE", "HEAD~1")
+          all_changed = subprocess.run(
+              ["git", "diff", "--name-only", before_sha, "HEAD"],
+              capture_output=True, text=True, check=True,
+          ).stdout.splitlines()
+          non_prd_changed = any(
+              not f.startswith("docs/prds/") for f in all_changed
+          )
+
+          # Find next available number.
+          existing = sorted(
+              int(m.group(1))
+              for p in prds_dir.glob("*.md")
+              if (m := re.match(r"^(\d{4})-", p.name))
+          )
+          next_num = (max(existing) + 1) if existing else 1
+
+          for prd_path in sorted(new_prds):
+              slug = re.sub(r"^prd-new-", "", prd_path.stem)
+              new_name = f"{next_num:04d}-{slug}.md"
+              new_path = prds_dir / new_name
+              print(f"  {prd_path.name}  →  {new_name}")
+
+              content = prd_path.read_text()
+
+              # Update title header.
+              content = re.sub(
+                  r"^(#\s+PRD\s+)prd-new(:)",
+                  rf"\g<1>{next_num:04d}\2",
+                  content,
+                  count=1,
+                  flags=re.MULTILINE,
+              )
+
+              # Conditionally flip Status.
+              if non_prd_changed:
+                  content = re.sub(
+                      r"(\*\*Status:\*\*\s*)Draft",
+                      r"\g<1>Active",
+                      content,
+                      count=1,
+                  )
+
+              new_path.write_text(content)
+              subprocess.run(["git", "rm", str(prd_path)], check=True)
+              subprocess.run(["git", "add", str(new_path)], check=True)
+              next_num += 1
+
+          subprocess.run(
+              ["git", "commit", "-m", "ci(prd): assign sequential numbers to new PRDs"],
+              check=True,
+          )
+          subprocess.run(["git", "push"], check=True)
+          EOF

.gitea/workflows/pre-release-test.yml

@@ -1,363 +0,0 @@
-# Run the complete backend test suite before a release. This workflow is
-# intentionally manual because Firecracker and macOS use privileged,
-# self-hosted runners.
-#
-# The suite uses stdlib `unittest` discovery — no external Python
-# dependencies are required to execute it. Tests are split by directory:
-#
-#   tests/unit/         — pure unit tests; always run
-#   tests/integration/  — need a reachable backend; skip cleanly when
-#                         the backend isn't available on the runner
-#   tests/canaries/     — upstream regression canaries; run on a separate
-#                         schedule (see canaries.yml), not here
-#
-# Unit, Docker, and Firecracker run once under coverage and upload a small
-# .coverage.* artifact for the combined coverage job. macOS reports coverage
-# in place because it is an advisory host-mode runner.
-
-name: pre-release-test
-
-on:
-  workflow_dispatch:
-
-jobs:
-  unit:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      # No actions/setup-python: the runner image already ships Python 3.12,
-      # and older act_runner engines mishandle setup-python's PATH (coverage
-      # lands in one interpreter, `python3` resolves to another). Install
-      # straight into the ephemeral job container's system Python —
-      # --break-system-packages is safe because the container is disposable.
-      - name: Install dev requirements
-        run: python3 -m pip install --break-system-packages -r requirements-dev.txt
-
-      - name: Run unit tests with coverage
-        env:
-          COVERAGE_FILE: ${{ github.workspace }}/.coverage.unit
-        run: python3 -m coverage run -m unittest discover -t . -s tests/unit -v
-
-      - name: Report unit coverage
-        env:
-          COVERAGE_FILE: ${{ github.workspace }}/.coverage.unit
-        run: python3 -m coverage report -m
-
-      # upload-artifact@v3's glob skips dotfiles, so a bare `.coverage.unit`
-      # silently uploads nothing ("No files were found"). Stage it under a
-      # non-dot name; the coverage job renames it back before `coverage
-      # combine`. `cp` also fails loudly if coverage never wrote the file.
-      - name: Stage unit coverage for upload
-        run: cp .coverage.unit coverage-unit.dat
-
-      - name: Upload unit coverage artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: coverage-unit
-          path: coverage-unit.dat
-
-  integration-docker:
-    runs-on: ubuntu-latest
-    concurrency:
-      group: integration-docker-infra
-      cancel-in-progress: false
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      # No actions/setup-python (see the note in the `unit` job); the
-      # container's system Python 3.12 runs the stdlib test suite directly.
-      - name: Install coverage
-        run: python3 -m pip install --break-system-packages coverage
-
-      # Fail loudly if the backend this job promises isn't actually usable,
-      # rather than letting every test silently `unittest.skip` and the job
-      # go green on zero coverage. `backend status` prints a clear per-check
-      # summary (docker on PATH, daemon reachable) and exits non-zero when a
-      # prerequisite is missing — the same readiness check the skip guards
-      # gate on via `has_backend`.
-      - name: Preflight — Docker backend is ready
-        run: |
-          python3 --version
-          python3 cli.py backend status --backend=docker
-
-      - name: Run integration tests (docker) with coverage
-        env:
-          BOT_BOTTLE_BACKEND: docker
-          COVERAGE_FILE: ${{ github.workspace }}/.coverage.docker
-        run: |
-          set -euo pipefail
-          DOCKER_CLIENT_NETWORK=$(
-            docker inspect "$(hostname)" |
-              python3 -c 'import json,sys; n=json.load(sys.stdin)[0]["NetworkSettings"]["Networks"]; print(next(iter(n)))'
-          )
-          test -n "$DOCKER_CLIENT_NETWORK"
-          RUN_KEY="${GITHUB_RUN_ID:-${GITHUB_RUN_NUMBER:-0}}"
-          export NO_PROXY="*"
-          export no_proxy="*"
-          export BOT_BOTTLE_DOCKER_CLIENT_NETWORK="$DOCKER_CLIENT_NETWORK"
-          export BOT_BOTTLE_DOCKER_ROOT_MOUNT="bot-bottle-ci-root-$RUN_KEY"
-          export BOT_BOTTLE_DOCKER_CA_MOUNT="bot-bottle-ci-ca-$RUN_KEY"
-          python3 -m coverage run -m scripts.unittest_gate \
-            -t . -s tests/integration -v \
-            --minimum-executed 22 --fail-on-skip
-
-      - name: Clean Docker integration volumes
-        if: always()
-        run: |
-          RUN_KEY="${GITHUB_RUN_ID:-${GITHUB_RUN_NUMBER:-0}}"
-          docker volume rm --force \
-            "bot-bottle-ci-root-$RUN_KEY" \
-            "bot-bottle-ci-ca-$RUN_KEY" 2>/dev/null || true
-
-      # Non-dot name so upload-artifact's dotfile-skipping glob picks it up.
-      - name: Stage docker coverage for upload
-        run: cp .coverage.docker coverage-docker.dat
-
-      - name: Upload docker coverage artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: coverage-docker
-          path: coverage-docker.dat
-
-  # Integration tests against the Firecracker backend. Runs on a self-hosted
-  # KVM runner (label `kvm`) where /dev/kvm and the TAP/nft pool are available.
-  #
-  # Manual only: the privileged KVM runner does not execute proposed changes
-  # unattended.
-  #
-  # Runner prerequisites (provision once; see README "Firecracker on Linux"):
-  # `firecracker` on PATH, `/dev/kvm` accessible, cached kernel +
-  # static dropbear at /var/cache/bot-bottle-fc/dropbear, and the pool as a
-  # persistent systemd unit.
-  #
-  # The infra candidate is built here directly (no artifact download) to
-  # eliminate the ~70 s ubuntu-latest upload + ~83 s combined download that
-  # the old build-infra → integration-firecracker + coverage chain incurred.
-  integration-firecracker:
-    runs-on: [self-hosted, kvm]
-    if: github.event_name == 'workflow_dispatch'
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Preflight — Firecracker host is ready
-        run: |
-          command -v firecracker >/dev/null || {
-            echo "firecracker not on PATH — provision the runner (README: Firecracker on Linux)"; exit 1; }
-          test -e /dev/kvm || { echo "/dev/kvm missing — KVM not available on this runner"; exit 1; }
-          # `backend status` exits non-zero unless the TAP pool is up + no
-          # range overlap; it prints the exact `backend setup` fix.
-          python3 cli.py backend status --backend=firecracker
-
-      - name: Build infra candidate from this checkout
-        env:
-          BOT_BOTTLE_FC_DROPBEAR: /var/cache/bot-bottle-fc/dropbear
-        run: python3 -m bot_bottle.backend.firecracker.publish_infra --output infra-candidate --reuse-published
-
-      - name: Replace the persistent infra VM with the candidate
-        run: python3 -c 'from bot_bottle.backend.firecracker import infra_vm; infra_vm.stop()'
-
-      # No dev-requirements install: `coverage` is already provided by the
-      # self-hosted runner's Nix python env, and that env has no `pip`
-      # module to install into anyway.
-      - name: Run integration tests (firecracker) with coverage
-        env:
-          BOT_BOTTLE_BACKEND: firecracker
-          BOT_BOTTLE_INFRA_ARTIFACT_DIR: ${{ github.workspace }}/infra-candidate
-          COVERAGE_FILE: ${{ github.workspace }}/.coverage.firecracker
-        run: python3 -m coverage run -m unittest discover -t . -s tests/integration -v
-
-      - name: Stage firecracker coverage for upload
-        run: cp .coverage.firecracker coverage-firecracker.dat
-
-      - name: Upload firecracker coverage artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: coverage-firecracker
-          path: coverage-firecracker.dat
-
-      - name: Upload tested rootfs
-        uses: actions/upload-artifact@v3
-        with:
-          name: infra-candidate
-          path: infra-candidate/
-
-      - name: Upload dropbear for publish verification
-        uses: actions/upload-artifact@v3
-        with:
-          name: firecracker-inputs
-          path: /var/cache/bot-bottle-fc/dropbear
-
-  # Integration tests against the macOS Apple Container backend. Runs on a
-  # self-hosted macOS runner (label `macos`) registered in HOST mode — Apple
-  # Container needs the host `container` CLI + virtualization framework and
-  # cannot run inside a Linux container, so this cannot reuse the KVM runner.
-  #
-  # Advisory only: workflow_dispatch (manual) exclusively — never push or
-  # pull_request. A single non-redundant laptop that sleeps/roams must not run
-  # unattended on every push to main, let alone block a PR merge, so this job is
-  # deliberately NOT in the `coverage` job's `needs` and its coverage never
-  # feeds the diff-coverage gate. Dispatch-only also means no fork PR (or any
-  # push) ever executes on the host-mode runner.
-  #
-  # The infra container is a singleton (`bot-bottle-mac-infra`); the
-  # `concurrency` group serializes runs so two never collide on it (#425), and
-  # the always-run teardown removes it so a crashed run can't wedge the next.
-  #
-  # Runner prerequisites (provision once; see README "macOS Apple Container"):
-  # the `container` CLI on PATH with `container system status` running, and a
-  # Python >=3.11 with `coverage` importable on the launchd service PATH.
-  integration-macos:
-    runs-on: [self-hosted, macos]
-    if: github.event_name == 'workflow_dispatch'
-    concurrency:
-      group: integration-macos-infra
-      cancel-in-progress: false
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      # Fail loudly if the backend this job promises isn't actually usable,
-      # rather than letting every test silently `unittest.skip` and the job go
-      # green on zero coverage. `backend status` exits non-zero (and prints the
-      # per-check summary) when the `container` CLI or its system service is
-      # missing — the same readiness check the skip guards gate on.
-      - name: Preflight — Apple Container backend is ready
-        run: |
-          command -v container >/dev/null || {
-            echo "container CLI not on PATH — provision the runner (README: macOS Apple Container)"; exit 1; }
-          container system status || {
-            echo "container system service not running — run 'container system start'"; exit 1; }
-          python3 cli.py backend status --backend=macos-container
-
-      # `coverage` comes from the runner's provisioned Python (no pip install
-      # into the host interpreter). Advisory job: report coverage in-line for
-      # visibility but don't upload — it never feeds the combined gate.
-      - name: Run integration tests (macos-container) with coverage
-        env:
-          BOT_BOTTLE_BACKEND: macos-container
-          COVERAGE_FILE: ${{ github.workspace }}/.coverage.macos
-        run: python3 -m coverage run -m unittest discover -t . -s tests/integration -v
-
-      - name: Report macos coverage
-        env:
-          COVERAGE_FILE: ${{ github.workspace }}/.coverage.macos
-        run: python3 -m coverage report -m
-
-      # On failure, capture the infra containers' state and logs BEFORE the
-      # teardown below removes them — otherwise a control-plane crash is
-      # undiagnosable from CI, since `stop()` deletes the orchestrator (and its
-      # logs) on every run. Best-effort: never let the diagnostics themselves
-      # fail the job, and keep going if a container is already gone.
-      - name: Dump infra diagnostics (on failure)
-        if: failure()
-        run: |
-          set +e
-          echo "=== containers ==="
-          container ls -a | grep bot-bottle-mac || echo "(no bot-bottle-mac containers)"
-          echo "=== networks ==="
-          container network ls | grep bot-bottle-mac || echo "(no bot-bottle-mac networks)"
-          for c in bot-bottle-mac-orchestrator bot-bottle-mac-infra; do
-            echo "=== inspect $c ==="
-            container inspect "$c" || echo "($c not found)"
-            echo "=== logs $c ==="
-            container logs "$c" || echo "($c logs unavailable)"
-          done
-          exit 0
-
-      # Remove the singleton infra container so a crashed or cancelled run
-      # cannot leave `bot-bottle-mac-infra` wedged for the next job.
-      - name: Teardown infra singleton
-        if: always()
-        run: python3 -c 'from bot_bottle.backend.macos_container.infra import MacosInfraService; MacosInfraService().stop()'
-
-  # Combined coverage gate: aggregates .coverage.* artifacts uploaded by each
-  # test job, then runs the diff-coverage gate (new/changed lines >= 90%).
-  #
-  # Runs on ubuntu-latest — no KVM needed, no test reruns. Coverage files use
-  # relative_files = True (.coveragerc) so they combine cleanly across runners.
-  # Each test job sets COVERAGE_FILE to an absolute path so coverage.py writes
-  # to a known location that upload-artifact can find regardless of runner env.
-  #
-  coverage:
-    needs: [unit, integration-docker, integration-firecracker]
-    timeout-minutes: 15
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Install coverage
-        run: python3 -m pip install --break-system-packages coverage
-
-      - name: Download unit coverage artifact
-        uses: actions/download-artifact@v3
-        with:
-          name: coverage-unit
-          path: ${{ github.workspace }}
-
-      - name: Download docker coverage artifact
-        uses: actions/download-artifact@v3
-        with:
-          name: coverage-docker
-          path: ${{ github.workspace }}
-
-      - name: Download firecracker coverage artifact
-        uses: actions/download-artifact@v3
-        with:
-          name: coverage-firecracker
-          path: ${{ github.workspace }}
-
-      # Rename the non-dot upload names back to the .coverage.* files that
-      # `coverage combine` discovers (see the staging steps in each test job).
-      - name: Reassemble coverage data files
-        run: |
-          mv coverage-unit.dat .coverage.unit
-          mv coverage-docker.dat .coverage.docker
-          mv coverage-firecracker.dat .coverage.firecracker
-
-      - name: Combined coverage (unit + integration, incl. firecracker)
-        run: PYTHON=python3 bash scripts/coverage.sh aggregate critical
-
-      - name: Diff-coverage gate (changed lines >= 90%)
-        run: |
-          git fetch --no-tags origin main:refs/remotes/origin/main
-          python3 scripts/diff_coverage.py --base origin/main --min 90
-
-  publish-infra:
-    needs:
-      - unit
-      - integration-docker
-      - integration-firecracker
-      - integration-macos
-      - coverage
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout the tested revision
-        uses: actions/checkout@v4
-
-      - name: Download the tested rootfs
-        uses: actions/download-artifact@v3
-        with:
-          name: infra-candidate
-          path: infra-candidate
-
-      # publish_infra re-derives the version from the checkout to confirm the
-      # bundle matches before uploading, and the version hashes the dropbear
-      # bytes. Download the same dropbear integration-firecracker used.
-      - name: Download the staged dropbear
-        uses: actions/download-artifact@v3
-        with:
-          name: firecracker-inputs
-          path: firecracker-inputs
-
-      - name: Publish the tested candidate
-        env:
-          BOT_BOTTLE_INFRA_ARTIFACT_TOKEN: ${{ secrets.BOT_BOTTLE_INFRA_ARTIFACT_TOKEN }}
-          BOT_BOTTLE_FC_DROPBEAR: ${{ github.workspace }}/firecracker-inputs/dropbear
-        run: python3 -m bot_bottle.backend.firecracker.publish_infra --publish-dir infra-candidate

.gitea/workflows/test.yml

@@ -1,6 +1,19 @@
-# Run the automated test gate when package or runtime inputs change on a PR
-# or on push to main. Privileged self-hosted backends live in the manually
-# dispatched pre-release-test workflow.
+# Run the project's test suite on every PR push and on push to main.
+#
+# The suite uses stdlib `unittest` discovery — no external Python
+# dependencies are required to execute it. Tests are split by directory:
+#
+#   tests/unit/         — pure unit tests; always run
+#   tests/integration/  — need a reachable Docker daemon; skip cleanly
+#                         (via tests/_docker.py:skip_unless_docker) when
+#                         Docker isn't available on the runner
+#   tests/canaries/     — upstream regression canaries; run on a separate
+#                         schedule (see canaries.yml), not here
+#
+# This workflow assumes the Gitea Actions runner exposes the host Docker
+# socket to the job container so `docker` commands inside the job can
+# reach the daemon. If that's not yet configured on the runner the
+# integration tests will skip rather than fail.
 
 name: test
 
@@ -9,46 +22,10 @@ on:
     branches:
       - main
     paths:
-      - 'bot_bottle/**'
-      - 'tests/**/*.py'
-      - 'cli.py'
-      - 'install.sh'
-      - 'setup.py'
-      - 'MANIFEST.in'
-      - 'flake.nix'
-      - 'nix/firecracker-netpool.nix'
-      - 'scripts/coverage.sh'
-      - 'scripts/critical-modules.txt'
-      - 'scripts/**/*.py'
-      - 'scripts/firecracker-netpool.sh'
-      - 'Dockerfile*'
-      - 'pyproject.toml'
-      - 'requirements-dev.txt'
-      - '.coveragerc'
-      - '.dockerignore'
-      - '.gitea/workflows/test.yml'
-      - '.gitea/workflows/pre-release-test.yml'
+      - '**.py'
   pull_request:
     paths:
-      - 'bot_bottle/**'
-      - 'tests/**/*.py'
-      - 'cli.py'
-      - 'install.sh'
-      - 'setup.py'
-      - 'MANIFEST.in'
-      - 'flake.nix'
-      - 'nix/firecracker-netpool.nix'
-      - 'scripts/coverage.sh'
-      - 'scripts/critical-modules.txt'
-      - 'scripts/**/*.py'
-      - 'scripts/firecracker-netpool.sh'
-      - 'Dockerfile*'
-      - 'pyproject.toml'
-      - 'requirements-dev.txt'
-      - '.coveragerc'
-      - '.dockerignore'
-      - '.gitea/workflows/test.yml'
-      - '.gitea/workflows/pre-release-test.yml'
+      - '**.py'
 
 jobs:
   unit:
@@ -57,89 +34,53 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Install dev requirements
-        run: python3 -m pip install --break-system-packages -r requirements-dev.txt
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
 
-      - name: Run unit tests with coverage
-        env:
-          COVERAGE_FILE: ${{ github.workspace }}/.coverage.unit
+      - name: Install dev requirements
+        run: python3 -m pip install -r requirements-dev.txt
+
+      - name: Run unit tests
         run: python3 -m coverage run -m unittest discover -t . -s tests/unit -v
 
       - name: Report unit coverage
-        env:
-          COVERAGE_FILE: ${{ github.workspace }}/.coverage.unit
         run: python3 -m coverage report -m
 
-      - name: Stage unit coverage for upload
-        run: cp .coverage.unit coverage-unit.dat
-
-      - name: Upload unit coverage artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: coverage-unit
-          path: coverage-unit.dat
-
-  integration-docker:
+  integration:
     runs-on: ubuntu-latest
-    concurrency:
-      group: integration-docker-infra
-      cancel-in-progress: false
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Install coverage
-        run: python3 -m pip install --break-system-packages coverage
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
 
-      - name: Preflight — Docker backend is ready
+      - name: Show environment
         run: |
           python3 --version
-          python3 cli.py backend status --backend=docker
+          if command -v docker >/dev/null 2>&1; then
+            docker version || true
+          else
+            echo "docker not on PATH — integration tests will skip"
+          fi
 
-      - name: Run integration tests (docker) with coverage
-        env:
-          BOT_BOTTLE_BACKEND: docker
-          COVERAGE_FILE: ${{ github.workspace }}/.coverage.docker
-        run: |
-          set -euo pipefail
-          # act_runner executes this job in a container while sharing the host
-          # Docker socket. Attach control-plane siblings to the job's network,
-          # and use named volumes for state the host daemon must mount.
-          DOCKER_CLIENT_NETWORK=$(
-            docker inspect "$(hostname)" |
-              python3 -c 'import json,sys; n=json.load(sys.stdin)[0]["NetworkSettings"]["Networks"]; print(next(iter(n)))'
-          )
-          test -n "$DOCKER_CLIENT_NETWORK"
-          RUN_KEY="${GITHUB_RUN_ID:-${GITHUB_RUN_NUMBER:-0}}"
-          export NO_PROXY="*"
-          export no_proxy="*"
-          export BOT_BOTTLE_DOCKER_CLIENT_NETWORK="$DOCKER_CLIENT_NETWORK"
-          export BOT_BOTTLE_DOCKER_ROOT_MOUNT="bot-bottle-ci-root-$RUN_KEY"
-          export BOT_BOTTLE_DOCKER_CA_MOUNT="bot-bottle-ci-ca-$RUN_KEY"
-          python3 -m coverage run -m scripts.unittest_gate \
-            -t . -s tests/integration -v \
-            --minimum-executed 22 --fail-on-skip
-
-      - name: Clean Docker integration volumes
-        if: always()
-        run: |
-          RUN_KEY="${GITHUB_RUN_ID:-${GITHUB_RUN_NUMBER:-0}}"
-          docker volume rm --force \
-            "bot-bottle-ci-root-$RUN_KEY" \
-            "bot-bottle-ci-ca-$RUN_KEY" 2>/dev/null || true
-
-      - name: Stage docker coverage for upload
-        run: cp .coverage.docker coverage-docker.dat
-
-      - name: Upload docker coverage artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: coverage-docker
-          path: coverage-docker.dat
+      - name: Run integration tests
+        run: python3 -m unittest discover -t . -s tests/integration -v
 
+  # Combined unit+integration coverage report (informational). See
+  # docs/decisions/0004-coverage-policy.md.
+  #
+  # The hard diff-coverage gate (changed lines >= 90%) is DEFERRED: the
+  # Firecracker backend's VM/SSH orchestration is covered by the integration
+  # suite, which needs /dev/kvm + the provisioned TAP/nft pool — a
+  # container-based runner skips it and those lines read uncovered, so the
+  # gate can't pass here. Re-enabling it on a self-hosted KVM runner is
+  # tracked separately (see PRD 0069 / #348 and the ci-runner branch).
   coverage:
-    needs: [unit, integration-docker]
-    timeout-minutes: 15
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -147,30 +88,13 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Install coverage
-        run: python3 -m pip install --break-system-packages coverage
-
-      - name: Download unit coverage artifact
-        uses: actions/download-artifact@v3
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
-          name: coverage-unit
-          path: ${{ github.workspace }}
+          python-version: "3.12"
 
-      - name: Download docker coverage artifact
-        uses: actions/download-artifact@v3
-        with:
-          name: coverage-docker
-          path: ${{ github.workspace }}
+      - name: Install dev requirements
+        run: python3 -m pip install -r requirements-dev.txt
 
-      - name: Reassemble coverage data files
-        run: |
-          mv coverage-unit.dat .coverage.unit
-          mv coverage-docker.dat .coverage.docker
-
-      - name: Combined coverage (unit + docker integration)
-        run: PYTHON=python3 bash scripts/coverage.sh aggregate critical
-
-      - name: Diff-coverage gate (changed lines >= 90%)
-        run: |
-          git fetch --no-tags origin main:refs/remotes/origin/main
-          python3 scripts/diff_coverage.py --base origin/main --min 90
+      - name: Combined coverage report (unit + integration)
+        run: PYTHON=python3 bash scripts/coverage.sh critical

.gitea/workflows/tracker-policy-issues.yml

@@ -1,17 +0,0 @@
-name: tracker-policy-issues
-
-on:
-  issues:
-    types: [opened, unlabeled]
-
-jobs:
-  label-issue:
-    runs-on: ubuntu-latest
-    permissions:
-      issues: write
-    steps:
-      - uses: actions/checkout@v4
-      - name: Ensure the issue has a label
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: python3 scripts/tracker_policy.py label-issue

.gitea/workflows/tracker-policy-pr.yml

@@ -1,18 +0,0 @@
-name: tracker-policy-pr
-
-on:
-  pull_request:
-    types: [opened, edited, reopened, synchronize, labeled, unlabeled]
-
-jobs:
-  check-pr:
-    runs-on: ubuntu-latest
-    permissions:
-      issues: read
-      pull-requests: read
-    steps:
-      - uses: actions/checkout@v4
-      - name: Require an unlabeled PR linked to an issue
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: python3 scripts/tracker_policy.py check-pr

.gitea/workflows/update-badges.yml

@@ -14,47 +14,38 @@ on:
 jobs:
   update-badges:
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
-
     steps:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 0
-          token: ${{ secrets.BADGE_PUSH_TOKEN }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
 
-      # No actions/setup-python: the runner image ships Python 3.12 and older
-      # act_runner engines mishandle setup-python's PATH. Install into the
-      # ephemeral job container's system Python (--break-system-packages is
-      # safe because the container is disposable).
       - name: Install dev dependencies
-        run: python3 -m pip install --break-system-packages -r requirements-dev.txt
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.txt
 
       - name: Run coverage and extract percentage
         id: coverage
         run: |
-          set -euo pipefail
-          # Never publish a badge from a failed or partial test run.
-          python3 -m coverage run -m unittest discover -t . -s tests/unit
-          REPORT=$(python3 -m coverage report)
-          printf '%s\n' "$REPORT"
-          PERCENT=$(printf '%s\n' "$REPORT" | awk '$1 == "TOTAL" {gsub("%", "", $NF); print $NF}')
-          test -n "$PERCENT"
+          python -m coverage run -m unittest discover -t . -s tests/unit > /dev/null 2>&1 || true
+          PERCENT=$(python -m coverage report 2>/dev/null | grep '^TOTAL' | grep -oP '\d+(?=%)' | tail -1)
           echo "percent=$PERCENT" >> $GITHUB_OUTPUT
           echo "Coverage: $PERCENT%"
 
       - name: Extract core (critical-module) coverage percentage
         id: core_coverage
         run: |
-          set -euo pipefail
           # Reuses the .coverage data from the previous step. The core list is
-          # validated single source of truth. Fail if a listed path disappeared
-          # or if the measured core falls below ADR 0004's 90% minimum.
-          INCLUDE=$(python3 scripts/critical_modules.py)
-          REPORT=$(python3 -m coverage report --include="$INCLUDE" --fail-under=90)
-          printf '%s\n' "$REPORT"
-          PERCENT=$(printf '%s\n' "$REPORT" | awk '$1 == "TOTAL" {gsub("%", "", $NF); print $NF}')
-          test -n "$PERCENT"
+          # the single source of truth in scripts/critical-modules.txt; every
+          # core module is unit-tested, so the unit-only run is accurate for it.
+          INCLUDE=$(grep -vE '^[[:space:]]*(#|$)' scripts/critical-modules.txt | paste -sd, -)
+          PERCENT=$(python -m coverage report --include="$INCLUDE" 2>/dev/null | grep '^TOTAL' | grep -oP '\d+(?=%)' | tail -1)
           echo "percent=$PERCENT" >> $GITHUB_OUTPUT
           echo "Core coverage: $PERCENT%"
 

.gitignore

@@ -17,9 +17,6 @@ __pycache__/
 *.py[cod]
 *$py.class
 *.egg-info/
-# setuptools/build_meta output (wheels, sdists, build tree)
-/build/
-/dist/
 .venv/
 venv/
 .pytest_cache/

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 gateways run through Apple's `container` CLI without
+agents and sidecar bundles 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 gateway still uses Docker. The legacy Docker
+TAP, while the sidecar bundle still uses Docker. The legacy Docker
 backend remains available with `BOT_BOTTLE_BACKEND=docker` or
 `--backend=docker`.
 
@@ -35,7 +35,6 @@ backend remains available with `BOT_BOTTLE_BACKEND=docker` or
 - `.bot-bottle/` — per-repo agent and bottle manifests (YAML markdown format).
 - `examples/` — example bottles and agents showing the manifest format.
 - `docs/README.md` — docs overview; when to write which document.
-- `docs/glossary.md` — canonical term definitions (Agent Provider, Bottle, Sealed Bottle, etc.).
 - `docs/prds/` — product requirement docs (see `docs/prds/README.md` for format).
 - `docs/research/` — research notes (see `docs/research/README.md`).
 - `docs/decisions/` — decision records (ADR-lite).
@@ -44,10 +43,10 @@ backend remains available with `BOT_BOTTLE_BACKEND=docker` or
 
 - Three kinds of doc, each with its own conventions in-folder; see
   `docs/README.md` for when to write which:
-  - **PRDs** (`docs/prds/`) — one feature per file. A draft may initially
-    use `prd-new-<kebab>.md`, but its author must assign the next
-    sequential number before merge; CI rejects unnumbered PRDs. A
-    `Status:` line tracks lifecycle: Draft → Active (shipped to `main`) →
+  - **PRDs** (`docs/prds/`) — one feature per file. While a PR is open
+    the file is named `prd-new-<kebab>.md`; CI assigns a sequential
+    number on merge to `main` and renames it. A `Status:` line tracks
+    lifecycle: Draft → Active (shipped to `main`) →
     Superseded/Retargeted. Format in `docs/prds/README.md`.
   - **Research notes** (`docs/research/`) — opinionated investigations;
     unnumbered kebab-case, freeform and verdict-first. See
@@ -60,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 + companion containers). Ask before
+  runtime is the Python 3.13 used by the CLI + sidecars). 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,123 +0,0 @@
-# Gateway data-plane image (PRD 0024 bundle shape; PRD 0070 gateway).
-#
-# 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
-# (`bot_bottle.gateway.bootstrap`) 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.
-#
-# Layout:
-#
-#   /usr/bin/gitleaks                    gitleaks binary
-#   /app/egress_addon.py                 mitmproxy addon entry point
-#   /app/egress-entrypoint.sh            mitmdump launcher
-#   /usr/local/lib/python*/bot_bottle/   installed package (all daemons + shared modules)
-#   /app/egress_addon.py                 one-line shim: re-exports addons from package
-#                                        (mitmdump -s requires a file path, not a module)
-#   /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
-#   /git-gate/creds/*                    docker-cp'd at start time
-#   /git/*                               bare repos, populated at runtime
-#   /home/mitmproxy/.mitmproxy/          mitmproxy CA dir
-# (No bot-bottle.db mount: the data plane reaches the supervise queue over the
-#  control-plane RPC and never opens the DB — PRD 0070 / issue #469.)
-#
-# Exposed ports inside the container:
-#   9099  egress (mitmproxy, agent-facing HTTPS proxy)
-#   9418  git-gate (git-daemon)
-#   9420  git-gate smart HTTP (VM-backend agent-facing transport)
-#   9100  supervise (MCP HTTP)
-
-# Based on `python:3.12-slim` (Debian trixie) rather than the
-# `mitmproxy/mitmproxy` image (Debian bookworm), matching the trixie base the
-# orchestrator image needs for buildah (Dockerfile.orchestrator.fc). mitmproxy
-# is pip-installed to the same effect as the upstream image.
-FROM python:3.12-slim
-
-# Runtime system deps:
-#   git supplies the `git daemon` subcommand (no separate package)
-#     plus the core `git` binary the pre-receive hook invokes.
-#   openssh-client supplies the upstream SSH transport the
-#     pre-receive hook uses to forward accepted refs.
-#   ca-certificates is needed for mitmdump upstream TLS.
-RUN apt-get update \
- && apt-get install -y --no-install-recommends \
-      git openssh-client ca-certificates \
- && rm -rf /var/lib/apt/lists/*
-
-# mitmdump (the egress data plane). The upstream mitmproxy image baked
-# this in; on the plain python base we pip-install the same pinned
-# version. Its CA dir is set explicitly via `--set confdir=` in
-# egress-entrypoint.sh, so it doesn't depend on a `mitmproxy` home user.
-RUN pip install --no-cache-dir mitmproxy==11.1.3
-
-# gitleaks (the pre-receive hook's secret scanner). Installed from its
-# official release, pinned by version + SHA256 and verified — rather than
-# using a third-party image as a build stage (supply-chain surface, and it
-# would pin us to that image's cadence). python (already present) does the
-# download so we add no curl/wget. trixie apt also ships gitleaks, but an
-# older 8.16; the pinned download keeps the verified 8.30.1.
-#
-# Arch-aware: the asset + SHA are picked from the build's target
-# architecture so an arm64 host (Apple Silicon) gets the arm64 binary
-# rather than an x86_64 one that dies with "Exec format error" the first
-# time the pre-receive hook runs it. TARGETARCH is auto-populated by
-# BuildKit; the dpkg fallback keeps it correct under a legacy builder.
-ARG GITLEAKS_VERSION=8.30.1
-ARG GITLEAKS_SHA256_AMD64=551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb
-ARG GITLEAKS_SHA256_ARM64=e4a487ee7ccd7d3a7f7ec08657610aa3606637dab924210b3aee62570fb4b080
-ARG TARGETARCH
-RUN arch="${TARGETARCH:-$(dpkg --print-architecture)}" \
- && case "$arch" in \
-      amd64) asset="linux_x64";   sha="${GITLEAKS_SHA256_AMD64}" ;; \
-      arm64) asset="linux_arm64"; sha="${GITLEAKS_SHA256_ARM64}" ;; \
-      *) echo "unsupported gitleaks target arch: $arch" >&2; exit 1 ;; \
-    esac \
- && url="https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_${asset}.tar.gz" \
- && python3 -c "import sys,urllib.request; urllib.request.urlretrieve(sys.argv[1], '/tmp/gitleaks.tar.gz')" "$url" \
- && echo "${sha}  /tmp/gitleaks.tar.gz" | sha256sum -c - \
- && tar -xzf /tmp/gitleaks.tar.gz -C /usr/bin gitleaks \
- && rm /tmp/gitleaks.tar.gz
-
-# Install bot_bottle as a proper package so entry-point scripts can use
-# `from bot_bottle.X import Y` absolute imports. A rename or a missing
-# module is caught at pip-install time — not at container runtime.
-COPY pyproject.toml /src/
-COPY bot_bottle/    /src/bot_bottle/
-RUN pip install --no-cache-dir /src/
-
-# mitmdump -s requires a file path, not a module. Write a one-line shim that
-# re-exports `addons` from the installed package; mitmdump finds it there.
-# WORKDIR here also creates /app so the shim + COPYs below can write into it
-# (nothing created /app before this point).
-WORKDIR /app
-RUN printf 'from bot_bottle.gateway.egress.addon import addons\n' > /app/egress_addon.py
-COPY bot_bottle/gateway/egress/entrypoint.sh /app/egress-entrypoint.sh
-RUN chmod +x /app/egress-entrypoint.sh
-
-# Pre-create runtime directories the compose renderer + start
-# step expect to exist. `docker cp` does not create intermediate
-# dirs, and bind mounts won't either if the parent is missing.
-RUN mkdir -p \
-      /etc/egress \
-      /etc/git-gate \
-      /git-gate/creds \
-      /git \
-      /run/supervise \
-      /home/mitmproxy/.mitmproxy
-
-# Documentation only — the compose renderer publishes whichever
-# subset the bottle uses.
-EXPOSE 8888 9099 9418 9420 9100
-
-# PID 1 is the supervisor. It owns signal handling and exit-code
-# propagation; no `exec` chain in the entrypoint itself.
-ENTRYPOINT ["python3", "-m", "bot_bottle.gateway.bootstrap"]

Dockerfile.orchestrator

@@ -1,34 +0,0 @@
-# Orchestrator control-plane image (PRD 0070, #384).
-#
-# This is the **single definition of the orchestrator's content** — the
-# `bot_bottle` package baked onto a Python runtime — referenced by BOTH:
-#   * the docker backend, which runs this image directly as the lean
-#     control-plane container; and
-#   * the firecracker orchestrator VM image (Dockerfile.orchestrator.fc),
-#     which is `FROM` this image and adds buildah for in-VM agent builds.
-#     Keeping the content in one place means future orchestrator deps (e.g.
-#     iroh) are added here once, not duplicated per backend.
-#
-# It stays deliberately lean: the control plane is **stdlib-only** today, so
-# no third-party payload — none of the gateway's mitmproxy/git/gitleaks
-# (that's Dockerfile.gateway) and no buildah (that's the firecracker
-# builder, and lives only in Dockerfile.orchestrator.fc). Keeping the
-# secret-dense control plane on a minimal dependency surface is the point
-# (PRD 0070's "secret concentration").
-#
-# Shares the trixie `python:3.12-slim` base with the gateway image.
-
-FROM python:3.12-slim
-
-WORKDIR /app
-
-# The orchestrator content. Baked so the image is self-contained (runs from
-# a built image, no runtime bind-mount); the docker backend may still
-# bind-mount /app for dev live-reload, which simply overlays this copy.
-# `.dockerignore` keeps .git/docs/*.md out of the context. (Future deps like
-# iroh go here too — a shared requirements installed on this same base.)
-COPY bot_bottle /app/bot_bottle
-
-# Documentation only; lifecycle.py overrides the entrypoint to
-# `python3 -m bot_bottle.orchestrator` with the runtime flags.
-ENTRYPOINT ["python3", "-m", "bot_bottle.orchestrator"]

Dockerfile.orchestrator.fc

@@ -1,23 +0,0 @@
-# Firecracker orchestrator-VM image (PRD 0070).
-#
-# The control-plane rootfs the orchestrator microVM boots: the lean orchestrator
-# image + the in-VM agent-image builder. The Firecracker backend builds users'
-# agent Dockerfiles *inside this VM* with buildah (rootless, daemonless) instead
-# of on the host — no host Docker daemon, no root-equivalent `docker` group. The
-# gateway VM boots a *separate*, slimmer rootfs (bot-bottle-gateway:latest) that
-# carries none of this build tooling — the exposed data plane stays minimal.
-#
-# `crun` is the OCI runtime; `netavark` + `aardvark-dns` are the network backend
-# for `FROM` pulls + `RUN` egress. `vfs` + `chroot`: buildah works as root in the
-# bare microVM (no fuse-overlayfs / overlay module / subuid maps). The trixie
-# base (from Dockerfile.orchestrator's python:3.12-slim) carries buildah 1.39,
-# which parses the Dockerfile heredocs agent images use (bookworm's 1.28 can't).
-# Matches image_builder.
-FROM bot-bottle-orchestrator:latest
-
-RUN apt-get update \
- && apt-get install -y --no-install-recommends \
-      buildah crun netavark aardvark-dns \
- && rm -rf /var/lib/apt/lists/*
-ENV STORAGE_DRIVER=vfs \
-    BUILDAH_ISOLATION=chroot

Dockerfile.sidecars

@@ -0,0 +1,105 @@
+# Per-bottle sidecar bundle image (PRD 0024).
+#
+# Collapses the prior per-sidecar images (egress, git-gate,
+# supervise) into one. A small stdlib-Python init supervisor at
+# /app/sidecar_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.
+#
+# Layout:
+#
+#   /usr/bin/gitleaks                    gitleaks binary
+#   /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
+#   /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
+#   /git-gate/creds/*                    docker-cp'd at start time
+#   /git/*                               bare repos, populated at runtime
+#   /run/supervise/bot-bottle.db         bind-mounted at run time
+#   /home/mitmproxy/.mitmproxy/          mitmproxy CA dir
+#
+# Exposed ports inside the container:
+#   9099  egress (mitmproxy, agent-facing HTTPS proxy)
+#   9418  git-gate (git-daemon)
+#   9420  git-gate smart HTTP (VM-backend agent-facing transport)
+#   9100  supervise (MCP HTTP)
+
+# Stage 1: gitleaks binary. The upstream gitleaks image is alpine
+# with the binary at /usr/bin/gitleaks. Pinned by digest in lockstep
+# with Dockerfile.git-gate's prior base (now deleted at chunk 3).
+FROM zricethezav/gitleaks@sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9ab65d25e6bc8abbb7f AS gitleaks-src
+
+# Stage 2: assembly. mitmproxy/mitmproxy is debian-slim-based with
+# Python + mitmdump pre-installed — heavier than the others, so
+# this stage starts there and pulls the standalone binaries in.
+FROM mitmproxy/mitmproxy:11.1.3
+
+# Run as root inside the bundle. The bundle is the isolation
+# boundary; per-daemon user separation inside it is not load-bearing
+# and complicates the supervisor's spawn path.
+USER root
+
+# Runtime system deps:
+#   git supplies the `git daemon` subcommand (no separate package)
+#     plus the core `git` binary the pre-receive hook invokes.
+#   openssh-client supplies the upstream SSH transport the
+#     pre-receive hook uses to forward accepted refs.
+#   ca-certificates is needed for mitmdump upstream TLS (the
+#     base image already has it; listed for explicitness).
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      git openssh-client ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+
+# Pull the standalone binaries into the final image.
+COPY --from=gitleaks-src /usr/bin/gitleaks /usr/bin/gitleaks
+
+# Project Python: addon + server modules + the init supervisor.
+# Kept flat under /app/ so mitmdump's loader resolves them as
+# top-level siblings (absolute imports), matching the prior
+# Dockerfile.egress / Dockerfile.supervise layout.
+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
+COPY bot_bottle/queue_store.py       /app/queue_store.py
+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/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
+
+# Pre-create runtime directories the compose renderer + start
+# step expect to exist. `docker cp` does not create intermediate
+# dirs, and bind mounts won't either if the parent is missing.
+RUN mkdir -p \
+      /etc/egress \
+      /etc/git-gate \
+      /git-gate/creds \
+      /git \
+      /run/supervise \
+      /home/mitmproxy/.mitmproxy
+
+# Documentation only — the compose renderer publishes whichever
+# subset the bottle uses.
+EXPOSE 8888 9099 9418 9420 9100
+
+# WORKDIR matches Dockerfile.supervise's prior layout so the
+# in-app same-dir import in supervise_server.py stays deterministic.
+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"]

MANIFEST.in

@@ -1,8 +0,0 @@
-# Root-level build resources copied into bot_bottle/_resources/ at build time
-# (see setup.py). Included in the sdist so `pip install` from an sdist can
-# still bundle them into the wheel.
-include Dockerfile.gateway
-include Dockerfile.orchestrator
-include Dockerfile.orchestrator.fc
-include nix/firecracker-netpool.nix
-include scripts/firecracker-netpool.sh

README.md

@@ -5,8 +5,8 @@
 # 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-84%25-brightgreen)](https://coverage.readthedocs.io/)
-[![core coverage](https://img.shields.io/badge/core%20coverage-94%25-brightgreen)](https://gitea.dideric.is/didericis/bot-bottle/src/branch/main/docs/decisions/0004-coverage-policy.md)
+[![coverage](https://img.shields.io/badge/coverage-82%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 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.
+- **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.
 - **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 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 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.
+- **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.
+- **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.
 - **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 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. git-gate runs over the gateway's consolidated `git-http` daemon (the legacy per-bottle `git://` daemon is not used on this backend); keys are provisioned dynamically at launch and revoked on teardown.
+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 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 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 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.
+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.
 
 The Docker topology looks like this:
 
@@ -67,105 +67,21 @@ The Docker topology looks like this:
    └─────────────────────────────────────────────────────────────────────┘
 ```
 
-When the agent exits, `cli.py` tears down every gateway and both networks; nothing about a bottle persists between runs.
+When the agent exits, `cli.py` tears down every sidecar 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 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`.
+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`.
 
 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.
 
-> **CI (macOS Apple Container):** the advisory `integration-macos` job in `.gitea/workflows/pre-release-test.yml` runs only on manual dispatch. It targets a self-hosted host-mode runner labelled `macos`; Apple Container cannot run inside the Linux pull-request runner. Provision an Apple Silicon host with the `container` CLI running and Python ≥ 3.11 plus `coverage` on the launchd service's explicit `PATH`. The infra container is a singleton (`bot-bottle-mac-infra`), so keep runner concurrency at 1. Its coverage is reported separately and never feeds the required pull-request gate.
-
-### Containers inside a bottle
-
-A bottle may set `nested_containers: true`. On the macOS backend this starts a
-guest-local, rootless **podman** service after the bottle is registered and
-exposes its Docker-compatible API socket, so the agent still runs `docker` and
-`docker compose`. Nothing is mounted from the host: Docker Desktop's socket
-stays out of the bottle and the guest gains no outer VM capabilities. Backends
-that cannot do this (`docker`, `firecracker`) reject the flag rather than
-silently ignore it.
-
-Rootless Docker was tried first and does not work here at all: Apple
-Container's capability bounding set omits `CAP_SYS_ADMIN`, which the kernel
-requires to write a multi-range `uid_map`. See
-[`docs/research/rootless-docker-in-apple-container-spike.md`](docs/research/rootless-docker-in-apple-container-spike.md).
-
-The tradeoff to understand before enabling it: podman avoids that requirement
-by falling back to a single-UID mapping, so nested containers provide **no
-isolation from the agent itself** — `root` inside a nested container is the
-agent user outside it. Nested containers are a build/test convenience, not a
-security boundary. The bottle remains the boundary.
-
-Pulling images goes through the bottle's egress proxy like every other
-request, so each registry needs a route — **and so does the CDN it redirects
-layer blobs to**, which is a different host. Without the CDN route the pull
-authenticates, fetches the manifest, then 403s partway through.
-
-Docker Hub and GHCR additionally need `preserve_auth: true`: their token dance
-uses a client-fetched per-scope bearer token that the proxy would otherwise
-strip. Turn DLP off on every registry and CDN route — the bodies are
-compressed layer blobs that no detector can read, and buffering them is what
-triggers the shared-proxy OOM in #455.
-
-```yaml
-nested_containers: true
-egress:
-  routes:
-    # Docker Hub: registry, token endpoint, blob CDN.
-    - host: registry-1.docker.io
-      preserve_auth: true
-      dlp: { outbound_detectors: false, inbound_detectors: false }
-    - host: auth.docker.io
-      preserve_auth: true
-      dlp: { outbound_detectors: false, inbound_detectors: false }
-    - host: production.cloudfront.docker.com
-      dlp: { outbound_detectors: false, inbound_detectors: false }
-    # GHCR: registry + blob CDN.
-    - host: ghcr.io
-      preserve_auth: true
-      dlp: { outbound_detectors: false, inbound_detectors: false }
-    - host: pkg-containers.githubusercontent.com
-      dlp: { outbound_detectors: false, inbound_detectors: false }
-    # quay.io: registry + blob CDNs. No preserve_auth needed for public pulls.
-    - host: quay.io
-      dlp: { outbound_detectors: false, inbound_detectors: false }
-    - host: cdn01.quay.io
-      dlp: { outbound_detectors: false, inbound_detectors: false }
-    - host: cdn02.quay.io
-      dlp: { outbound_detectors: false, inbound_detectors: false }
-    - host: cdn03.quay.io
-      dlp: { outbound_detectors: false, inbound_detectors: false }
-```
-
-`mcr.microsoft.com` and `registry.k8s.io` follow the same shape and also
-redirect blobs elsewhere (`*.data.mcr.microsoft.com` and
-`us-*-docker.pkg.dev` respectively); route whichever host the 403 names.
-
-Inside a nested container the same allowlist applies: an allowlisted host
-returns 200 and anything else gets a 403 straight from the proxy. The
-gateway's CA bundle and proxy settings are wired in automatically, so
-`docker run … curl https://…` works with no extra flags — no `--add-host`,
-`-e`, or `-v`.
-
-Two things worth knowing when testing that:
-
-- Public DNS inside a nested container fails **by design**. Everything
-  egresses through the proxy, so `nslookup` failing is expected and is not
-  evidence of a problem.
-- Alpine's BusyBox `wget` drops the connection after the proxy's TLS
-  interception and reports `error getting response`, even though the proxy
-  logs the decrypted request and returns a response. Use `curl` to test
-  egress; BusyBox `wget` will lie to you.
-
 ### Firecracker on Linux
 
 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 gateway and image build.
+- **Docker** for the sidecar bundle 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
@@ -174,8 +90,6 @@ BOT_BOTTLE_BACKEND=firecracker ./cli.py start <agent>
 
 > **NixOS:** enable `virtualisation.docker`, ensure the KVM module is loaded (`boot.kernelModules = [ "kvm-intel" ];` or `kvm-amd`), and add your user to the `kvm` and `docker` groups. For the network pool, consume the flake module — `imports = [ inputs.bot-bottle.nixosModules.firecracker-netpool ]; services.bot-bottle-firecracker = { enable = true; owner = "you"; };` — then `nixos-rebuild switch` (imperative nft/TAP rules don't survive a rebuild; channel users can `imports = [ <bot-bottle>/nix/firecracker-netpool.nix ]`). `firecracker` isn't in nixpkgs by default as a user binary — install the release binary (pin the version) and put it on `PATH`.
 
-> **CI:** Firecracker integration runs in the manually dispatched `.gitea/workflows/pre-release-test.yml` on a self-hosted runner labelled `kvm`; privileged KVM hosts never execute unreviewed PR code automatically. Provision it like a normal Firecracker host: `firecracker` on `PATH`, `/dev/kvm`, the cached guest kernel and static dropbear, and the persistent TAP/nft pool. The required pull-request workflow runs unit plus the complete Docker integration suite on `ubuntu-latest`; see `docs/ci.md`.
-
 ```sh
 ./cli.py start <agent>   # builds the image on first run, drops you into claude
 ```
@@ -207,14 +121,14 @@ git:
 egress:
   routes:
     - host: gitea.dideric.is
-      inspect:
-        auth:
-          scheme: token        # Bearer | token
-          token_ref: BOT_BOTTLE_GITEA_TOKEN
-        matches:               # optional — restrict to specific paths/methods/headers
-          - paths:
-              - {type: prefix, value: /api/v1/}
-            methods: [GET, POST, PATCH, DELETE]
+      auth:
+        scheme: token        # Bearer | token
+        token_ref: BOT_BOTTLE_GITEA_TOKEN
+      matches:               # optional — restrict to specific paths/methods/headers
+        - paths:
+            - {type: prefix, value: /api/v1/}
+          methods: [GET, POST, PATCH, DELETE]
+      dlp:                   # optional — per-route detector overrides (default: all on)
         outbound_detectors: [token_patterns, known_secrets]
         inbound_detectors: false   # disable response scanning for this host
 ---
@@ -257,15 +171,6 @@ When an outbound DLP detector matches a token, the route's `dlp.outbound_on_matc
 
 More examples in `examples/`. Full design lives under `docs/prds/`; the trust-boundary rationale is in `docs/prds/0011-per-file-md-manifest.md`.
 
-## Tracker policy
-
-Issues are the canonical work items and own all tracker labels; every issue
-must have at least one. Pull requests stay unlabeled and deliberately reference
-an issue with `Closes #…`, `Part of #…`, or another form defined in
-[`ADR 0005`](docs/decisions/0005-issues-own-tracker-metadata.md). Gitea Actions
-enforces the convention for new work from 2026-07-18 onward. Earlier closed
-PRs are grandfathered rather than given artificial retrospective issues.
-
 ## Trademarks
 
 bot-bottle is an independent project and is not affiliated with, endorsed by, or sponsored by Anthropic, PBC. "Claude" and "Claude Code" are trademarks of Anthropic, PBC; the project name uses "claude" descriptively to indicate that the tool runs Claude Code inside a sandbox.

bot_bottle/agent_provider.py

@@ -45,10 +45,6 @@ PROVIDER_TEMPLATES = frozenset({PROVIDER_CLAUDE, PROVIDER_CODEX, PROVIDER_PI})
 # forward_host_credentials is enabled. Pipelock must pass these through
 # (no TLS MITM) or its header DLP blocks the injected JWT.
 CODEX_HOST_CREDENTIAL_HOSTS = ("api.openai.com", "chatgpt.com")
-
-# Host that egress injects the host Claude bearer on when Claude
-# forward_host_credentials is enabled.
-CLAUDE_HOST_CREDENTIAL_HOSTS = ("api.anthropic.com",)
 PromptMode = Literal[
     "append_file",
     "read_prompt_file",
@@ -65,13 +61,6 @@ class AgentProviderRuntime:
     prompt_mode: PromptMode
     bypass_args: tuple[str, ...]
     resume_args: tuple[str, ...]
-    # argv run inside a throwaway container of a freshly built agent
-    # image, right after `build_image()`, to catch a build that
-    # exited 0 but produced a broken CLI (e.g. an npm
-    # optionalDependencies fetch for a platform-native binary that
-    # silently no-ops on a transient failure). Empty tuple skips the
-    # check — not every provider has opted in yet.
-    smoke_test: tuple[str, ...] = ()
 
 
 @dataclass(frozen=True)
@@ -215,9 +204,9 @@ class AgentProvider(ABC):
         bottle: "Bottle",
         supervise_url: str,
     ) -> None:
-        """Register the per-bottle supervise daemon as an MCP server
+        """Register the per-bottle supervise sidecar as an MCP server
         in the provider's in-guest config. Called by the backend after
-        the supervise daemon is reachable. No-op when
+        the supervise sidecar is reachable. No-op when
         `plan.supervise_plan is None`."""
 
     @abstractmethod
@@ -261,28 +250,7 @@ class AgentProvider(ABC):
         Default: Debian/node — writes the git-gate insteadOf gitconfig
         and sets user.name/email as node. Workspace copy runs through
         BottleBackend.provision_workspace against the running bottle."""
-        from .log import die, info
-
-        # Firecracker exports image rootfs files through an unprivileged host
-        # tar extraction, so image-time ownership of XDG directories is not
-        # preserved.  Git consults ~/.config/git even when the actual config
-        # is ~/.gitconfig; an unreadable directory there can prevent the
-        # git-gate insteadOf rules below from taking effect.  Repair this at
-        # runtime, after every backend's copy/export path has completed.
-        git_xdg_dir = f"{plan.guest_home}/.config/git"
-        repair = bottle.exec(
-            f"chown node:node {shlex.quote(plan.guest_home)} && "
-            f"chmod 755 {shlex.quote(plan.guest_home)} && "
-            f"mkdir -p {shlex.quote(git_xdg_dir)} && "
-            f"chown -R node:node {shlex.quote(f'{plan.guest_home}/.config')} && "
-            f"chmod -R u+rwX,go+rX {shlex.quote(f'{plan.guest_home}/.config')}",
-            user="root",
-        )
-        if repair.returncode != 0:
-            die(
-                "git provisioning: could not make the runtime Git config "
-                f"directory readable: {(repair.stderr or repair.stdout).strip()}"
-            )
+        from .log import info
 
         manifest_bottle = plan.manifest.bottle
         if manifest_bottle.git:
@@ -291,7 +259,6 @@ class AgentProvider(ABC):
             gate_scheme = getattr(plan, "git_gate_insteadof_scheme", "git")
             content = git_gate_render_gitconfig(
                 manifest_bottle.git, gate_host, scheme=gate_scheme,
-                identity_token=getattr(plan, "identity_token", ""),
             )
             guest_gitconfig = f"{plan.guest_home}/.gitconfig"
             with tempfile.NamedTemporaryFile(
@@ -305,27 +272,11 @@ class AgentProvider(ABC):
                 f"{len(manifest_bottle.git)} insteadOf rule(s)"
             )
             bottle.cp_in(str(config_file), guest_gitconfig)
-            permissions = bottle.exec(
+            bottle.exec(
                 f"chown node:node {shlex.quote(guest_gitconfig)} && "
                 f"chmod 644 {shlex.quote(guest_gitconfig)}",
                 user="root",
             )
-            if permissions.returncode != 0:
-                die(
-                    "git provisioning: could not set ownership on "
-                    f"{guest_gitconfig}: "
-                    f"{(permissions.stderr or permissions.stdout).strip()}"
-                )
-            configured = bottle.exec(
-                "git config --global --get-regexp '^url\\..*\\.insteadof$'",
-                user="node",
-            )
-            if configured.returncode != 0:
-                die(
-                    "git provisioning: the runtime user cannot read the "
-                    f"git-gate insteadOf rules from {guest_gitconfig}: "
-                    f"{(configured.stderr or configured.stdout).strip()}"
-                )
 
         gu = manifest_bottle.git_user
         if not gu.is_empty():

bot_bottle/audit_store.py

@@ -5,10 +5,16 @@ from __future__ import annotations
 import sqlite3
 from pathlib import Path
 
-from ..supervisor.types import AuditEntry
-from ..paths import host_db_path
-from .db_store import DbStore
-from .migrations import TableMigrations
+try:
+    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  # 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
 
 
 class AuditStore(DbStore):
@@ -36,7 +42,7 @@ class AuditStore(DbStore):
         super().__init__(db_path or host_db_path(), migrations)
 
     def write_audit_entry(self, entry: AuditEntry) -> Path:
-        with self._connection() as conn:
+        with self._connect() as conn:
             conn.execute(
                 """
                 INSERT INTO supervise_audit_entries (
@@ -60,7 +66,7 @@ class AuditStore(DbStore):
     def read_audit_entries(self, component: str, slug: str) -> list[AuditEntry]:
         if not self.db_path.is_file():
             return []
-        with self._connection() as conn:
+        with self._connect() as conn:
             rows = conn.execute(
                 """
                 SELECT * FROM supervise_audit_entries

bot_bottle/backend/__init__.py

@@ -1,115 +1,689 @@
-"""The bottle-backend package: abstract contract + backend selection.
+"""Per-backend bottle factories.
 
-Thin by design — nothing framework-heavy is imported at package init, so
-importing any `backend.*` submodule (e.g. `backend.docker.util`) doesn't drag
-the manifest / egress / git-gate framework into memory. The public names are
-re-exported lazily:
+A bottle is a running, isolated environment with claude inside. Each
+backend exposes five methods:
 
-  * the abstract contract (`BottleBackend`, `BottleSpec`, `Bottle`, …) lives in
-    `backend.base`;
-  * backend selection / enumeration (`get_bottle_backend`,
-    `enumerate_active_agents`, …) in `backend.selection`;
-  * the concrete backends and the freeze helpers in their own submodules.
+  prepare(spec, stage_dir=...) -> BottlePlan
+      Resolves names, validates host-side prerequisites, and writes
+      scratch files. No remote/runtime resources are created yet.
+      Safe to call before the y/N preflight.
 
-`from bot_bottle.backend import X` resolves X on first access via `__getattr__`
-and caches it at package level, so existing call-sites (and
-`patch.object(backend_mod, X, …)`) keep working.
+  launch(plan) -> ContextManager[Bottle]
+      Brings up the container (or VM, or remote machine), provisions
+      it, yields a Bottle handle, and tears everything down on exit.
+
+  prepare_cleanup() -> BottleCleanupPlan
+      Enumerates orphaned resources left behind by previous bottles
+      (containers, networks, ...). Idempotent; no side effects.
+
+  cleanup(plan) -> None
+      Actually removes everything described by the cleanup plan.
+
+  enumerate_active() -> Sequence[ActiveAgent]
+      Return every currently-running bottle on this backend, with
+      enough metadata for callers (CLI `list active`, dashboard
+      agents pane) to render a row.
+
+Selection is driven by `--backend` on `start` or BOT_BOTTLE_BACKEND
+(env var). When neither is set, compatible macOS hosts default to
+`macos-container`; Linux hosts with KVM default to `firecracker`;
+otherwise `docker`. Per PRD 0003 the manifest does not carry a
+backend field; the host picks.
 """
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+import os
+import shlex
+import sys
+from abc import ABC, abstractmethod
+from contextlib import AbstractContextManager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Generic, Sequence, TypeVar
 
-if TYPE_CHECKING:
-    from .base import (
-        ActiveAgent,
-        BackendStatus,
-        Bottle,
-        BottleBackend,
-        BottleCleanupPlan,
-        BottleImages,
-        BottlePlan,
-        BottleSpec,
-        ExecResult,
-    )
-    from .selection import (
-        enumerate_active_agents,
-        get_bottle_backend,
-        has_backend,
-        is_backend_available,
-        is_backend_ready,
-        known_backend_names,
-    )
-    from .docker import DockerBottleBackend
-    from .firecracker import FirecrackerBottleBackend
-    from .macos_container import MacosContainerBottleBackend
-    from .freeze import CommitCancelled, Freezer, get_freezer
+from ..agent_provider import AgentProvisionPlan, get_provider, build_agent_provision_plan
+from ..egress import EgressPlan
+from ..git_gate import GitGatePlan
+from ..log import die, info
+from ..manifest import Manifest, ManifestIndex
+from ..supervise import SupervisePlan
+from ..util import expand_tilde
+from ..env import resolve_env, ResolvedEnv
+from ..workspace import WorkspacePlan, workspace_plan
+from .print_util import print_multi, visible_agent_env_names
+from .util import host_skill_dir
 
 
-# Public name -> submodule that defines it. Contract types resolve from `base`,
-# selection/enumeration from `selection`, the concrete backends + freeze helpers
-# from their own subpackages.
-_LAZY_MODULES: dict[str, str] = {
-    "BottleSpec": "base",
-    "BottlePlan": "base",
-    "BottleCleanupPlan": "base",
-    "ExecResult": "base",
-    "ActiveAgent": "base",
-    "Bottle": "base",
-    "BottleImages": "base",
-    "BottleBackend": "base",
-    "BackendStatus": "base",
-    "get_bottle_backend": "selection",
-    "known_backend_names": "selection",
-    "has_backend": "selection",
-    "is_backend_available": "selection",
-    "is_backend_ready": "selection",
-    "enumerate_active_agents": "selection",
-    "_print_vm_install_instructions": "selection",
-    "DockerBottleBackend": "docker",
-    "FirecrackerBottleBackend": "firecracker",
-    "MacosContainerBottleBackend": "macos_container",
-    "CommitCancelled": "freeze",
-    "Freezer": "freeze",
-    "get_freezer": "freeze",
+@dataclass(frozen=True)
+class BottleSpec:
+    """CLI-supplied intent. Backend-agnostic — each backend's prepare
+    step consumes it and produces its own backend-specific plan.
+    Resolved values (image names, container name, scratch paths, runsc
+    availability) live on the plan, not the spec."""
+
+    manifest: ManifestIndex
+    agent_name: str
+    copy_cwd: bool
+    user_cwd: str
+    # PRD 0016 follow-up: when set, the backend's prepare step uses
+    # this identity instead of minting a fresh one — the resume path
+    # (`cli.py resume <identity>`) sets this to continue an existing
+    # bottle's state. Empty string for a fresh `start`.
+    identity: str = ""
+    label: str = ""
+    color: str = ""
+    # Ordered bottle names selected at launch (issue #269). When non-empty
+    # they are merged in order and replace the agent's `bottle:` field.
+    bottle_names: tuple[str, ...] = ()
+    # True when launched via --headless (no TTY, no interactive prompts).
+    # The git-gate host-key preflight uses this to error rather than prompt.
+    headless: bool = False
+
+
+@dataclass(frozen=True)
+class BottlePlan(ABC):
+    """Base output of a backend's prepare step. Concrete subclasses
+    (e.g. DockerBottlePlan) add backend-specific resolved fields."""
+
+    spec: BottleSpec
+    manifest: Manifest
+    stage_dir: Path
+    git_gate_plan: GitGatePlan
+
+    @property
+    def guest_home(self) -> str:
+        return self.agent_provision.guest_home
+
+    @property
+    def git_gate_insteadof_host(self) -> str:
+        """Host (and optional port) used in git-gate insteadOf URLs.
+        Docker uses the compose-network DNS alias; VM backends may
+        override with an IP:port when the guest has no DNS."""
+        return "git-gate"
+
+    @property
+    def git_gate_insteadof_scheme(self) -> str:
+        """URL scheme for git-gate insteadOf rewrites. 'git' for
+        Docker (git daemon); VM backends may override (e.g. 'http'
+        over a published host port)."""
+        return "git"
+    egress_plan: EgressPlan
+    supervise_plan: SupervisePlan | None
+    agent_provision: AgentProvisionPlan
+
+    @property
+    def workspace_plan(self) -> WorkspacePlan:
+        return workspace_plan(self.spec, guest_home=self.guest_home)
+
+    def print(self) -> None:
+        """Render the y/N preflight summary to stderr."""
+        spec = self.spec
+        manifest = self.manifest
+        agent = manifest.agent
+        bottle = manifest.bottle
+
+        env_names = visible_agent_env_names(
+            sorted(
+                set(bottle.env.keys())
+                | set(self.agent_provision.guest_env.keys())
+            ),
+            hidden_env_names=self.agent_provision.hidden_env_names,
+        )
+
+        print(file=sys.stderr)
+        info(f"agent           : {spec.agent_name}")
+        info(f"provider        : {self.agent_provision.template}")
+        print_multi("env             ", env_names)
+        print_multi("skills          ", list(agent.skills))
+        effective_bottles = (
+            list(spec.bottle_names) if spec.bottle_names
+            else ([agent.bottle] if agent.bottle else [])
+        )
+        print_multi("bottle          ", effective_bottles)
+
+        identity = manifest.git_identity_summary()
+        if identity:
+            info(f"  git identity  : {identity}")
+
+        git_lines = [
+            f"{u.name} → {u.upstream_host}:{u.upstream_port}"
+            for u in self.git_gate_plan.upstreams
+        ]
+        if git_lines:
+            print_multi("  git gate      ", git_lines)
+
+        if self.egress_plan.routes:
+            egress_lines = []
+            for r in self.egress_plan.routes:
+                auth = f" [auth:{r.auth_scheme}]" if r.auth_scheme else ""
+                egress_lines.append(f"{r.host}{auth}")
+            print_multi("  egress        ", egress_lines)
+        print(file=sys.stderr)
+
+
+@dataclass(frozen=True)
+class BottleCleanupPlan(ABC):
+    """Base output of a backend's prepare_cleanup step. Concrete
+    subclasses (e.g. DockerBottleCleanupPlan) carry backend-specific
+    lists of resources to be removed and implement `print` + `empty`."""
+
+    @abstractmethod
+    def print(self) -> None:
+        """Render the cleanup y/N summary to stderr."""
+
+    @property
+    @abstractmethod
+    def empty(self) -> bool:
+        """True iff there is nothing to clean up; the CLI uses this to
+        short-circuit before showing the y/N."""
+
+
+@dataclass(frozen=True)
+class ExecResult:
+    """Captured result of `Bottle.exec`. Backend-neutral: the Docker
+    impl populates it from a `subprocess.CompletedProcess`, but a
+    VM backend could populate it from any source that produces a
+    returncode + captured streams."""
+
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+@dataclass(frozen=True)
+class ActiveAgent:
+    """One currently-running agent, as the CLI `list active` and
+    dashboard agents pane render it. ("Agent" is the project's
+    consistent name for the thing running inside a bottle — the
+    bottle is the container, the agent is what runs in it.)
+
+    Fields are deliberately backend-neutral. `services` is the set
+    of sidecar daemons currently up for this bottle (`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-
+    list rendering to disambiguate and by the dashboard's
+    re-attach path."""
+
+    backend_name: str
+    slug: str
+    agent_name: str       # from metadata.json; "?" if missing
+    started_at: str       # ISO 8601 from metadata.json; "" if missing
+    services: tuple[str, ...]  # alphabetical
+    label: str = ""
+    color: str = ""
+
+
+class Bottle(ABC):
+    """Handle to a running bottle. Yielded by a backend's launch step.
+
+    `exec_agent` runs the selected agent CLI inside the bottle and
+    blocks until the session ends. `exec` runs a POSIX shell script inside the bottle
+    and returns the captured result. `cp_in` copies a host path into
+    the bottle. `close` is an idempotent alias for context-manager
+    teardown.
+    """
+
+    name: str
+
+    @abstractmethod
+    def agent_argv(
+        self, argv: list[str], *, tty: bool = True,
+    ) -> list[str]:
+        """Return the host-side argv that runs the selected agent
+        inside the bottle. Used by `exec_agent` for foreground
+        handoffs and by the dashboard's tmux `respawn-pane` flow,
+        which needs the argv up front (it spawns claude in a tmux
+        pane rather than as a child of the current process).
+
+        Implementations transparently inject
+        `--append-system-prompt-file` when the bottle was launched
+        with a provisioned prompt path."""
+        ...
+
+    @abstractmethod
+    def exec_agent(self, argv: list[str], *, tty: bool = True) -> int: ...
+
+    @abstractmethod
+    def exec(self, script: str, *, user: str = "node") -> ExecResult:
+        """Run `script` as a POSIX shell script inside the bottle as
+        `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
+        exit does not raise — callers inspect `returncode`
+        themselves.
+
+        Pass `user="root"` for shell-outs that need privileged file
+        writes / package install — provisioning calls that need root
+        bypass `Bottle.exec` and use the backend-specific raw
+        machine-exec helper, but the tests have a legitimate use
+        case for arbitrary-user runs."""
+
+    @abstractmethod
+    def cp_in(self, host_path: str, container_path: str) -> None: ...
+
+    @abstractmethod
+    def close(self) -> None: ...
+
+
+
+
+PlanT = TypeVar("PlanT", bound=BottlePlan)
+CleanupT = TypeVar("CleanupT", bound=BottleCleanupPlan)
+
+
+class BottleBackend(ABC, Generic[PlanT, CleanupT]):
+    """Abstract base for selectable bottle backends. Concrete subclasses
+    (e.g. DockerBottleBackend) own their own prepare/launch impls.
+    Parameterized over the backend's concrete plan + cleanup-plan types
+    so subclass methods get the narrow type without isinstance
+    boilerplate."""
+
+    name: str
+
+    def prepare(self, spec: BottleSpec, stage_dir: Path) -> PlanT:
+        """Template method: run cross-backend host-side validation, then
+        delegate to the subclass's `_resolve_plan` for the
+        backend-specific resolution (names, scratch files, etc.). The
+        validation step is enforced here so a future backend cannot
+        accidentally skip it. No remote/runtime resources are created."""
+        from .resolve_common import (
+            merge_provision_env_vars,
+            mint_slug,
+            prepare_agent_state_dir,
+            prepare_egress,
+            prepare_git_gate,
+            prepare_supervise,
+            resolve_manifest_dockerfile,
+            write_launch_metadata,
+        )
+
+        manifest = self._validate(spec)
+
+        self._preflight()
+
+        from ..git_gate_host_key import preflight_host_keys
+        manifest = preflight_host_keys(
+            manifest,
+            headless=spec.headless,
+            home_md=spec.manifest.home_md,
+        )
+
+        manifest_bottle = manifest.bottle
+        manifest_agent_provider = manifest_bottle.agent_provider
+        agent_provider = get_provider(manifest_agent_provider.template)
+        resolved_env = resolve_env(manifest)
+        workspace = workspace_plan(spec, guest_home=agent_provider.guest_home)
+
+        slug = mint_slug(spec)
+        write_launch_metadata(slug, spec, compose_project="", backend=self.name)
+
+        # Manifest may override the Dockerfile per-bottle; otherwise fall
+        # back to the provider plugin's bundled Dockerfile (next to its
+        # agent_provider.py module).
+        if manifest_agent_provider.dockerfile:
+            agent_dockerfile_path = resolve_manifest_dockerfile(
+                manifest_agent_provider.dockerfile, spec,
+            )
+        else:
+            agent_dockerfile_path = str(agent_provider.dockerfile)
+
+        agent_dir, prompt_file = prepare_agent_state_dir(slug, manifest)
+
+        agent_provision_plan = build_agent_provision_plan(
+            template=manifest_agent_provider.template,
+            dockerfile=agent_dockerfile_path,
+            state_dir=agent_dir,
+            instance_name=f"bot-bottle-{slug}",
+            prompt_file=prompt_file,
+            guest_env=self._build_guest_env(resolved_env),
+            forward_host_credentials=manifest_agent_provider.forward_host_credentials,
+            auth_token=manifest_agent_provider.auth_token,
+            host_env=dict(os.environ),
+            trusted_project_path=workspace.workdir,
+            label=spec.label,
+            color=spec.color,
+            provider_settings=manifest_agent_provider.settings,
+        )
+        agent_provision_plan = merge_provision_env_vars(agent_provision_plan)
+        egress_plan = prepare_egress(manifest_bottle, slug, agent_provision_plan)
+        supervise_plan = prepare_supervise(manifest_bottle, slug)
+        git_gate_plan = prepare_git_gate(manifest_bottle, slug)
+
+        return self._resolve_plan(
+            spec,
+            manifest=manifest,
+            slug=slug,
+            resolved_env=resolved_env,
+            agent_provision_plan=agent_provision_plan,
+            egress_plan=egress_plan,
+            supervise_plan=supervise_plan,
+            git_gate_plan=git_gate_plan,
+            stage_dir=stage_dir,
+        )
+
+    def _build_guest_env(self, resolved_env: ResolvedEnv) -> dict[str, str]:
+        return {}
+
+    def _preflight(self) -> None:
+        """
+        tasks to do before resolving a plan
+        """
+        pass
+
+    def _validate(self, spec: BottleSpec) -> Manifest:
+        """Cross-backend pre-launch checks. Parses the selected agent and
+        its bottle (raising ManifestError on invalid content), confirms
+        skills are present on the host, and every git IdentityFile resolves.
+
+        Returns the loaded Manifest for the selected agent. Subclasses with
+        additional preconditions should override and call
+        `super()._validate(spec)` first."""
+        manifest = spec.manifest.load_for_agent(spec.agent_name, spec.bottle_names)
+        self._validate_skills(manifest.agent.skills)
+        self._validate_agent_provider_dockerfile(spec, manifest)
+        return manifest
+
+    def _validate_skills(self, skills: Sequence[str]) -> None:
+        """Each named skill must be a directory under the host's
+        `~/.claude/skills/`. The check is purely host-side, so the
+        default impl covers every backend."""
+        for name in skills:
+            path = host_skill_dir(name)
+            if not os.path.isdir(path):
+                die(
+                    f"skill '{name}' not found on host at {path}. "
+                    f"Create it under ~/.claude/skills/, then re-run."
+                )
+
+    def _validate_agent_provider_dockerfile(self, spec: BottleSpec, manifest: Manifest) -> None:
+        bottle = manifest.bottle
+        dockerfile = bottle.agent_provider.dockerfile
+        if not dockerfile:
+            return
+        path = Path(expand_tilde(dockerfile))
+        if not path.is_absolute():
+            path = Path(spec.user_cwd) / path
+        if not path.is_file():
+            effective = (
+                ", ".join(spec.bottle_names) if spec.bottle_names else manifest.agent.bottle
+            )
+            die(
+                f"agent_provider.dockerfile for bottle "
+                f"'{effective}' not found: {path}"
+            )
+
+    @abstractmethod
+    def _resolve_plan(self,
+                      spec: BottleSpec,
+                      *,
+                      manifest: Manifest,
+                      slug: str,
+                      resolved_env: ResolvedEnv,
+                      agent_provision_plan: AgentProvisionPlan,
+                      egress_plan: EgressPlan,
+                      git_gate_plan: GitGatePlan,
+                      supervise_plan: SupervisePlan | None,
+                      stage_dir: Path) -> PlanT:
+        """Backend-specific plan resolution: image/container names,
+        env-file, prompt-file, proxy plan, runtime detection. Called by
+        `prepare` after `_validate` succeeds. Instance name, image,
+        prompt file, Dockerfile path, and guest home all live on
+        `agent_provision_plan` — the source of truth."""
+
+    @abstractmethod
+    def launch(self, plan: PlanT) -> AbstractContextManager[Bottle]:
+        """Build/run the bottle and yield a handle; tear down on exit."""
+
+    def provision(self, plan: PlanT, bottle: "Bottle") -> str | None:
+        """Copy host-side files (CA cert, prompt, skills, .git) into
+        the running bottle. Called from `launch` after the container
+        / machine is up. Returns the in-container prompt path if a
+        prompt was provisioned, else None — the Bottle handle uses it
+        to decide whether to add provider-specific prompt args to the
+        agent's argv.
+
+        Default orchestration: ca → prompt → provider apply → skills
+        → workspace → git → supervise-mcp. CA install runs first so
+        the agent's trust store is rebuilt before anything inside the
+        agent makes a TLS call.
+
+        Per PRD 0050 the per-provider steps (prompt, skills,
+        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
+        knows about via `supervise_mcp_url`.
+
+        PRD 0017: cred-proxy's agent-side dotfile rewrites (~/.npmrc,
+        ~/.gitconfig insteadOf, tea config) are gone. Egress-proxy is
+        on the agent's HTTP_PROXY path so every tool that respects
+        HTTPS_PROXY (claude-code, git over HTTPS, npm, curl) is
+        intercepted without per-tool reconfiguration."""
+        provider = get_provider(plan.agent_provision.template)
+        provider.provision_ca(bottle, plan)
+        prompt_path = provider.provision_prompt(plan, bottle)
+        provider.provision(plan, bottle)
+        provider.provision_skills(plan, bottle)
+        self.provision_workspace(plan, bottle)
+        provider.provision_git(bottle, plan)
+        provider.provision_supervise_mcp(
+            plan, bottle, self.supervise_mcp_url(plan),
+        )
+        return prompt_path
+
+    def provision_workspace(self, plan: PlanT, bottle: "Bottle") -> None:
+        """Copy the operator workspace into the running bottle.
+
+        This is the only supported workspace-provisioning path: Docker
+        does not build a derived image containing the current
+        workspace."""
+        workspace = plan.workspace_plan
+        if not (workspace.enabled and workspace.copy_contents):
+            return
+
+        guest_parent = workspace.guest_path.rsplit("/", 1)[0] or "/"
+        guest_path = shlex.quote(workspace.guest_path)
+        guest_parent = shlex.quote(guest_parent)
+        owner = shlex.quote(workspace.owner)
+        mode = shlex.quote(workspace.mode)
+        info(f"copying {workspace.host_path} -> {bottle.name}:{workspace.guest_path}")
+        bottle.exec(
+            f"rm -rf {guest_path} && mkdir -p {guest_parent}",
+            user="root",
+        )
+        bottle.cp_in(str(workspace.host_path), workspace.guest_path)
+        bottle.exec(
+            f"chown -R {owner} {guest_path} && chmod {mode} {guest_path}",
+            user="root",
+        )
+
+    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
+        plugin's `provision_supervise_mcp` uses it to register the
+        MCP entry inside the guest.
+
+        Default returns "" so backends without supervise support
+        don't have to implement it. Docker and firecracker override."""
+        del plan
+        return ""
+
+    @abstractmethod
+    def prepare_cleanup(self) -> CleanupT:
+        """Enumerate orphaned resources from previous bottles. No side
+        effects; safe to call before the y/N."""
+
+    @abstractmethod
+    def cleanup(self, plan: CleanupT) -> None:
+        """Remove everything described by the cleanup plan."""
+
+    @abstractmethod
+    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
+        containers against per-bottle metadata."""
+
+    @classmethod
+    @abstractmethod
+    def is_available(cls) -> bool:
+        """Whether this backend's runtime prerequisites are satisfied
+        on the current host. Docker → `docker` on PATH; firecracker →
+        Linux + KVM. Used by the cross-backend
+        `enumerate_active_agents` / `cmd_cleanup` to skip backends
+        the operator hasn't installed, so a docker-only host
+        doesn't fail when `cli.py list active` walks past
+        firecracker."""
+
+    @classmethod
+    @abstractmethod
+    def setup(cls) -> int:
+        """Emit this backend's one-time host setup — privileged network
+        pool, daemon bring-up, install pointers, etc. — as
+        host-appropriate config or commands. Prints to stdout/stderr and
+        returns a shell exit code (0 = nothing to report / success). A
+        backend that needs no host setup prints a short note and returns
+        0. Invoked generically by `./cli.py backend setup [--backend=…]`
+        so operators can provision any backend without a
+        backend-specific command. Classmethod (like `is_available`) —
+        it's a host query, not per-bottle state."""
+
+    @classmethod
+    @abstractmethod
+    def status(cls) -> int:
+        """Report whether this backend's prerequisites are satisfied on
+        the host — binaries, daemon reachability, network pool, range
+        conflicts, etc. Prints a human-readable summary; returns 0 when
+        the backend is ready to launch and non-zero when something is
+        missing. Invoked by `./cli.py backend status [--backend=…]`."""
+
+    @classmethod
+    @abstractmethod
+    def teardown(cls) -> int:
+        """Undo `setup()` — the inverse operation, surfaced as
+        `./cli.py backend teardown [--backend=…]` (uninstall). Symmetric
+        with setup: where setup is advisory (prints the privileged
+        commands / declarative config to apply), teardown prints the
+        commands / config change to remove the host prerequisites. A
+        backend with no host setup prints a short note and returns 0.
+        Not called by the launch path or the test suite."""
+
+
+# Import concrete backend classes AFTER the base types are defined, so
+# each backend module can pull BottleSpec / BottlePlan / BottleBackend
+# via `from . import ...` without hitting a partially-initialized module.
+from .docker import DockerBottleBackend  # noqa: E402  # pylint: disable=wrong-import-position
+from .firecracker import FirecrackerBottleBackend  # noqa: E402  # pylint: disable=wrong-import-position
+from .macos_container import MacosContainerBottleBackend  # noqa: E402  # pylint: disable=wrong-import-position
+
+# Freezer is imported after the backend classes for the same reason:
+# Freezer.commit_slug constructs ActiveAgent, which must be fully
+# defined first.
+from .freeze import CommitCancelled, Freezer, get_freezer  # noqa: E402  # pylint: disable=wrong-import-position
+
+
+# The dict is heterogeneous: each value is a BottleBackend specialized
+# over its own plan type. Concrete plan types are erased here because
+# the registry is selected at runtime and the CLI only needs the
+# unparameterized methods (prepare → plan → launch(plan), cleanup, etc.).
+_BACKENDS: dict[str, BottleBackend[Any, Any]] = {
+    "docker": DockerBottleBackend(),
+    "firecracker": FirecrackerBottleBackend(),
+    "macos-container": MacosContainerBottleBackend(),
 }
 
 
-def __getattr__(name: str) -> Any:
-    """Lazily surface the package's public names from their submodules and
-    cache them at package level — so `from bot_bottle.backend import X` and
-    `patch.object(backend_mod, X, …)` keep working without importing the
-    framework (or every backend) at package-init time."""
-    mod = _LAZY_MODULES.get(name)
-    if mod is None:
-        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-    from importlib import import_module
+def get_bottle_backend(
+    name: str | None = None,
+) -> BottleBackend[Any, Any]:
+    """Resolve the bottle backend.
 
-    value = getattr(import_module(f"{__name__}.{mod}"), name)
-    globals()[name] = value
-    return value
+    `name` precedence:
+      1. explicit arg (CLI `--backend=<name>` passes through here)
+      2. BOT_BOTTLE_BACKEND env var
+      3. `macos-container` on compatible macOS hosts
+      4. `firecracker` on KVM-capable Linux hosts
+      5. default `docker`
+
+    Dies with a pointer at the known backends if the chosen name
+    isn't implemented."""
+    resolved = name or os.environ.get("BOT_BOTTLE_BACKEND") or _default_backend_name()
+    if resolved not in _BACKENDS:
+        known = ", ".join(sorted(_BACKENDS))
+        die(f"unknown backend {resolved!r}; known backends: {known}")
+    return _BACKENDS[resolved]
+
+
+def _default_backend_name() -> str:
+    if has_backend("macos-container"):
+        return "macos-container"
+    # A KVM-capable Linux host defaults to firecracker even when the
+    # `firecracker` binary isn't installed yet: selecting it here routes
+    # start through firecracker's preflight, which prints an install
+    # pointer, instead of silently falling back to docker.
+    if FirecrackerBottleBackend.is_host_capable():
+        return "firecracker"
+    return "docker"
+
+
+def known_backend_names() -> tuple[str, ...]:
+    """Sorted tuple of all backend keys in `_BACKENDS`. Used by
+    argparse (`--backend` choices) and the dashboard's backend
+    picker."""
+    return tuple(sorted(_BACKENDS))
+
+
+def has_backend(name: str) -> bool:
+    """Whether the named backend's runtime prerequisites are
+    available on the current host. Cross-backend callers (list,
+    cleanup) skip unavailable backends so a docker-only host
+    doesn't fail when the firecracker backend isn't usable,
+    and vice versa.
+
+    Returns False for unknown names so callers can pass
+    arbitrary input without separate validation."""
+    if name not in _BACKENDS:
+        return False
+    return _BACKENDS[name].is_available()
+
+
+def enumerate_active_agents() -> list[ActiveAgent]:
+    """All currently-running agents, across every available
+    backend. Used by CLI `list active` and the dashboard's agents
+    pane so neither has to know which backends exist. Skips
+    backends whose `is_available()` reports False.
+
+    Sorted by `(started_at, slug)` so the list is stable across
+    dashboard refresh ticks — agents don't shift position while
+    the operator navigates with arrow keys. ISO 8601 timestamps
+    sort lexicographically in chronological order; `slug` is the
+    deterministic tiebreaker. Agents with missing metadata
+    (`started_at == ""`) sort first."""
+    out: list[ActiveAgent] = []
+    for name in known_backend_names():
+        if not has_backend(name):
+            continue
+        out.extend(_BACKENDS[name].enumerate_active())
+    out.sort(key=lambda a: (a.started_at, a.slug))
+    return out
 
 
 __all__ = [
     "ActiveAgent",
-    "BackendStatus",
     "Bottle",
     "BottleBackend",
     "BottleCleanupPlan",
-    "BottleImages",
     "BottlePlan",
     "BottleSpec",
-    "ExecResult",
     "CommitCancelled",
+    "ExecResult",
     "Freezer",
-    "get_freezer",
-    "DockerBottleBackend",
-    "FirecrackerBottleBackend",
-    "MacosContainerBottleBackend",
     "enumerate_active_agents",
     "get_bottle_backend",
+    "get_freezer",
     "has_backend",
-    "is_backend_available",
-    "is_backend_ready",
     "known_backend_names",
 ]

bot_bottle/backend/base.py

@@ -1,555 +0,0 @@
-"""The abstract backend contract (PRD 0018 / 0070).
-
-The backend-neutral types every bottle backend implements: the launch
-`BottleSpec`, the `BottlePlan` / `BottleCleanupPlan` ABCs, the running-`Bottle`
-+ `ExecResult` shapes, `BottleImages`, and the `BottleBackend` ABC itself.
-
-This carries the framework imports (manifest, egress, git-gate, env, workspace,
-agent-provider) the contract's signatures and helpers need — which is why it
-lives here rather than in `backend/__init__.py`: touching an unrelated
-`backend.*` module then doesn't drag the whole framework into memory. The
-thin package `__init__` re-exports these names lazily.
-"""
-
-from __future__ import annotations
-
-import enum
-import os
-import shlex
-import sys
-from abc import ABC, abstractmethod
-from contextlib import AbstractContextManager, contextmanager
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Generator, Generic, Sequence, TypeVar
-
-from ..agent_provider import AgentProvisionPlan, get_provider
-from ..egress import EgressPlan
-from ..git_gate import GitGatePlan
-from ..log import die, info
-from ..util import expand_tilde
-from ..manifest import Manifest, ManifestIndex
-from ..supervisor.plan import SupervisePlan
-from ..env import ResolvedEnv
-from ..workspace import WorkspacePlan, workspace_plan
-from .print_util import print_multi, visible_agent_env_names
-from .util import host_skill_dir
-
-
-class BackendStatus(enum.IntEnum):
-    """Return codes for BottleBackend.status(). READY == 0 so callsites
-    can compare against 0 or the named constant interchangeably."""
-    READY = 0
-
-
-@dataclass(frozen=True)
-class BottleSpec:
-    """CLI-supplied intent. Backend-agnostic — each backend's prepare
-    step consumes it and produces its own backend-specific plan.
-    Resolved values (image names, container name, scratch paths, runsc
-    availability) live on the plan, not the spec."""
-
-    manifest: ManifestIndex
-    agent_name: str
-    copy_cwd: bool
-    user_cwd: str
-    # PRD 0016 follow-up: when set, the backend's prepare step uses
-    # this identity instead of minting a fresh one — the resume path
-    # (`cli.py resume <identity>`) sets this to continue an existing
-    # bottle's state. Empty string for a fresh `start`.
-    identity: str = ""
-    label: str = ""
-    color: str = ""
-    # Ordered bottle names selected at launch (issue #269). When non-empty
-    # they are merged in order and replace the agent's `bottle:` field.
-    bottle_names: tuple[str, ...] = ()
-    # True when launched via --headless (no TTY, no interactive prompts).
-    # The git-gate host-key preflight uses this to error rather than prompt.
-    headless: bool = False
-    # Image startup policy. "fresh" preserves the normal build path;
-    # "cached" reuses the current local image/artifact without rebuilding.
-    image_policy: str = "fresh"
-
-
-@dataclass(frozen=True)
-class BottlePlan(ABC):
-    """Base output of a backend's prepare step. Concrete subclasses
-    (e.g. DockerBottlePlan) add backend-specific resolved fields."""
-
-    spec: BottleSpec
-    manifest: Manifest
-    stage_dir: Path
-    git_gate_plan: GitGatePlan
-
-    @property
-    def guest_home(self) -> str:
-        return self.agent_provision.guest_home
-
-    @property
-    def git_gate_insteadof_host(self) -> str:
-        """Host (and optional port) used in git-gate insteadOf URLs.
-        Docker uses the compose-network DNS alias; VM backends may
-        override with an IP:port when the guest has no DNS."""
-        return "git-gate"
-
-    @property
-    def git_gate_insteadof_scheme(self) -> str:
-        """URL scheme for git-gate insteadOf rewrites. 'git' for
-        Docker (git daemon); VM backends may override (e.g. 'http'
-        over a published host port)."""
-        return "git"
-    egress_plan: EgressPlan
-    supervise_plan: SupervisePlan | None
-    agent_provision: AgentProvisionPlan
-
-    @property
-    def workspace_plan(self) -> WorkspacePlan:
-        return workspace_plan(self.spec, guest_home=self.guest_home)
-
-    def print(self) -> None:
-        """Render the y/N preflight summary to stderr."""
-        spec = self.spec
-        manifest = self.manifest
-        agent = manifest.agent
-        bottle = manifest.bottle
-
-        env_names = visible_agent_env_names(
-            sorted(
-                set(bottle.env.keys())
-                | set(self.agent_provision.guest_env.keys())
-            ),
-            hidden_env_names=self.agent_provision.hidden_env_names,
-        )
-
-        print(file=sys.stderr)
-        info(f"agent           : {spec.agent_name}")
-        info(f"provider        : {self.agent_provision.template}")
-        print_multi("env             ", env_names)
-        print_multi("skills          ", list(agent.skills))
-        effective_bottles = (
-            list(spec.bottle_names) if spec.bottle_names
-            else ([agent.bottle] if agent.bottle else [])
-        )
-        print_multi("bottle          ", effective_bottles)
-
-        identity = manifest.git_identity_summary()
-        if identity:
-            info(f"  git identity  : {identity}")
-
-        git_lines = [
-            f"{u.name} → {u.upstream_host}:{u.upstream_port}"
-            for u in self.git_gate_plan.upstreams
-        ]
-        if git_lines:
-            print_multi("  git gate      ", git_lines)
-
-        if self.egress_plan.routes:
-            egress_lines = []
-            for r in self.egress_plan.routes:
-                auth = f" [auth:{r.auth_scheme}]" if r.auth_scheme else ""
-                egress_lines.append(f"{r.host}{auth}")
-            print_multi("  egress        ", egress_lines)
-        print(file=sys.stderr)
-
-
-@dataclass(frozen=True)
-class BottleCleanupPlan(ABC):
-    """Base output of a backend's prepare_cleanup step. Concrete
-    subclasses (e.g. DockerBottleCleanupPlan) carry backend-specific
-    lists of resources to be removed and implement `print` + `empty`."""
-
-    @abstractmethod
-    def print(self) -> None:
-        """Render the cleanup y/N summary to stderr."""
-
-    @property
-    @abstractmethod
-    def empty(self) -> bool:
-        """True iff there is nothing to clean up; the CLI uses this to
-        short-circuit before showing the y/N."""
-
-
-@dataclass(frozen=True)
-class ExecResult:
-    """Captured result of `Bottle.exec`. Backend-neutral: the Docker
-    impl populates it from a `subprocess.CompletedProcess`, but a
-    VM backend could populate it from any source that produces a
-    returncode + captured streams."""
-
-    returncode: int
-    stdout: str
-    stderr: str
-
-
-@dataclass(frozen=True)
-class ActiveAgent:
-    """One currently-running agent, as the CLI `active` and
-    dashboard agents pane render it. ("Agent" is the project's
-    consistent name for the thing running inside a bottle — the
-    bottle is the container, the agent is what runs in it.)
-
-    Fields are deliberately backend-neutral. `services` is the set
-    of 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-
-    list rendering to disambiguate and by the dashboard's
-    re-attach path."""
-
-    backend_name: str
-    slug: str
-    agent_name: str       # from metadata.json; "?" if missing
-    started_at: str       # ISO 8601 from metadata.json; "" if missing
-    services: tuple[str, ...]  # alphabetical
-    label: str = ""
-    color: str = ""
-
-
-class Bottle(ABC):
-    """Handle to a running bottle. Yielded by a backend's launch step.
-
-    `exec_agent` runs the selected agent CLI inside the bottle and
-    blocks until the session ends. `exec` runs a POSIX shell script inside the bottle
-    and returns the captured result. `cp_in` copies a host path into
-    the bottle. `close` is an idempotent alias for context-manager
-    teardown.
-    """
-
-    name: str
-
-    @abstractmethod
-    def agent_argv(
-        self, argv: list[str], *, tty: bool = True,
-    ) -> list[str]:
-        """Return the host-side argv that runs the selected agent
-        inside the bottle. Used by `exec_agent` for foreground
-        handoffs and by the dashboard's tmux `respawn-pane` flow,
-        which needs the argv up front (it spawns claude in a tmux
-        pane rather than as a child of the current process).
-
-        Implementations transparently inject
-        `--append-system-prompt-file` when the bottle was launched
-        with a provisioned prompt path."""
-        ...
-
-    @abstractmethod
-    def exec_agent(self, argv: list[str], *, tty: bool = True) -> int: ...
-
-    @abstractmethod
-    def exec(self, script: str, *, user: str = "node") -> ExecResult:
-        """Run `script` as a POSIX shell script inside the bottle as
-        `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 daemon) is inherited by the child. Non-zero
-        exit does not raise — callers inspect `returncode`
-        themselves.
-
-        Pass `user="root"` for shell-outs that need privileged file
-        writes / package install — provisioning calls that need root
-        bypass `Bottle.exec` and use the backend-specific raw
-        machine-exec helper, but the tests have a legitimate use
-        case for arbitrary-user runs."""
-
-    @abstractmethod
-    def cp_in(self, host_path: str, container_path: str) -> None: ...
-
-    @abstractmethod
-    def close(self) -> None: ...
-
-
-
-
-PlanT = TypeVar("PlanT", bound=BottlePlan)
-CleanupT = TypeVar("CleanupT", bound=BottleCleanupPlan)
-
-
-@dataclass(frozen=True)
-class BottleImages:
-    """Resolved image references (or artifact paths) for a bottle launch.
-
-    For Docker/macOS-container backends, `agent` and `sidecar` are string
-    image refs. For the smolmachines backend they are Path objects pointing
-    to pre-built `.smolmachine` artifacts."""
-
-    agent: str | Path
-    sidecar: str | Path = ""
-
-
-class BottleBackend(ABC, Generic[PlanT, CleanupT]):
-    """Abstract base for selectable bottle backends. Concrete subclasses
-    (e.g. DockerBottleBackend) own their own prepare/launch impls.
-    Parameterized over the backend's concrete plan + cleanup-plan types
-    so subclass methods get the narrow type without isinstance
-    boilerplate."""
-
-    name: str
-
-    # Whether this backend can run a container engine *inside* the bottle.
-    # Backends that cannot must reject `nested_containers: true` rather than
-    # reach for a host daemon socket (issue #392).
-    supports_nested_containers: bool = False
-
-    def prepare(self, spec: BottleSpec, stage_dir: Path) -> PlanT:
-        """Template method: run cross-backend host-side validation, then
-        delegate to the subclass's `_resolve_plan` for the
-        backend-specific resolution (names, scratch files, etc.). The
-        validation step is enforced here so a future backend cannot
-        accidentally skip it. No remote/runtime resources are created."""
-        from .preparation import BottlePreparationPlanner
-        prepared = BottlePreparationPlanner(self).prepare(spec)
-
-        return self._resolve_plan(
-            spec,
-            manifest=prepared.manifest,
-            slug=prepared.slug,
-            resolved_env=prepared.resolved_env,
-            agent_provision_plan=prepared.agent_provision_plan,
-            egress_plan=prepared.egress_plan,
-            supervise_plan=prepared.supervise_plan,
-            git_gate_plan=prepared.git_gate_plan,
-            stage_dir=stage_dir,
-        )
-
-    def _build_guest_env(self, resolved_env: ResolvedEnv) -> dict[str, str]:
-        return {}
-
-    def _preflight(self) -> None:
-        """
-        tasks to do before resolving a plan
-        """
-        pass
-
-    def _validate(self, spec: BottleSpec) -> Manifest:
-        """Cross-backend pre-launch checks. Parses the selected agent and
-        its bottle (raising ManifestError on invalid content), confirms
-        skills are present on the host, and every git IdentityFile resolves.
-
-        Returns the loaded Manifest for the selected agent. Subclasses with
-        additional preconditions should override and call
-        `super()._validate(spec)` first."""
-        manifest = spec.manifest.load_for_agent(spec.agent_name, spec.bottle_names)
-        self._validate_skills(manifest.agent.skills)
-        self._validate_agent_provider_dockerfile(spec, manifest)
-        return manifest
-
-    def _validate_skills(self, skills: Sequence[str]) -> None:
-        """Each named skill must be a directory under the host's
-        `~/.claude/skills/`. The check is purely host-side, so the
-        default impl covers every backend."""
-        for name in skills:
-            path = host_skill_dir(name)
-            if not os.path.isdir(path):
-                die(
-                    f"skill '{name}' not found on host at {path}. "
-                    f"Create it under ~/.claude/skills/, then re-run."
-                )
-
-    def _validate_agent_provider_dockerfile(self, spec: BottleSpec, manifest: Manifest) -> None:
-        bottle = manifest.bottle
-        dockerfile = bottle.agent_provider.dockerfile
-        if not dockerfile:
-            return
-        path = Path(expand_tilde(dockerfile))
-        if not path.is_absolute():
-            path = Path(spec.user_cwd) / path
-        if not path.is_file():
-            effective = (
-                ", ".join(spec.bottle_names) if spec.bottle_names else manifest.agent.bottle
-            )
-            die(
-                f"agent_provider.dockerfile for bottle "
-                f"'{effective}' not found: {path}"
-            )
-
-    @abstractmethod
-    def _resolve_plan(self,
-                      spec: BottleSpec,
-                      *,
-                      manifest: Manifest,
-                      slug: str,
-                      resolved_env: ResolvedEnv,
-                      agent_provision_plan: AgentProvisionPlan,
-                      egress_plan: EgressPlan,
-                      git_gate_plan: GitGatePlan,
-                      supervise_plan: SupervisePlan | None,
-                      stage_dir: Path) -> PlanT:
-        """Backend-specific plan resolution: image/container names,
-        env-file, prompt-file, proxy plan, runtime detection. Called by
-        `prepare` after `_validate` succeeds. Instance name, image,
-        prompt file, Dockerfile path, and guest home all live on
-        `agent_provision_plan` — the source of truth."""
-
-    def prelaunch_checks(self, plan: PlanT) -> None:
-        """Raise StaleImageError if any cached image used by this plan is stale.
-        No-op default; backends override to call the shared check_stale*
-        helpers on their image/artifact timestamps. Called by the CLI before
-        launch so the operator can be prompted outside the launch context."""
-
-    @contextmanager
-    def launch(self, plan: PlanT) -> Generator[Bottle, None, None]:
-        """Template: build or load images, then delegate to _launch_impl."""
-        images = self._build_or_load_images(plan)
-        with self._launch_impl(plan, images) as bottle:
-            yield bottle
-
-    @abstractmethod
-    def _build_or_load_images(self, plan: PlanT) -> BottleImages:
-        """Return the agent and sidecar image references (or artifact paths)
-        for this plan, building fresh images when the policy requires it."""
-
-    @abstractmethod
-    def _launch_impl(self, plan: PlanT, images: BottleImages) -> AbstractContextManager[Bottle]:
-        """Bring up the bottle using pre-resolved images; yield a handle; tear down on exit."""
-
-    def provision(self, plan: PlanT, bottle: "Bottle") -> str | None:
-        """Copy host-side files (CA cert, prompt, skills, .git) into
-        the running bottle. Called from `launch` after the container
-        / machine is up. Returns the in-container prompt path if a
-        prompt was provisioned, else None — the Bottle handle uses it
-        to decide whether to add provider-specific prompt args to the
-        agent's argv.
-
-        Default orchestration: ca → prompt → provider apply → skills
-        → workspace → git → supervise-mcp. CA install runs first so
-        the agent's trust store is rebuilt before anything inside the
-        agent makes a TLS call.
-
-        Per PRD 0050 the per-provider steps (prompt, skills,
-        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 daemon URL its launch step
-        knows about via `supervise_mcp_url`.
-
-        PRD 0017: cred-proxy's agent-side dotfile rewrites (~/.npmrc,
-        ~/.gitconfig insteadOf, tea config) are gone. Egress-proxy is
-        on the agent's HTTP_PROXY path so every tool that respects
-        HTTPS_PROXY (claude-code, git over HTTPS, npm, curl) is
-        intercepted without per-tool reconfiguration."""
-        provider = get_provider(plan.agent_provision.template)
-        provider.provision_ca(bottle, plan)
-        prompt_path = provider.provision_prompt(plan, bottle)
-        provider.provision(plan, bottle)
-        provider.provision_skills(plan, bottle)
-        self.provision_workspace(plan, bottle)
-        provider.provision_git(bottle, plan)
-        provider.provision_supervise_mcp(
-            plan, bottle, self.supervise_mcp_url(plan),
-        )
-        return prompt_path
-
-    def provision_workspace(self, plan: PlanT, bottle: "Bottle") -> None:
-        """Copy the operator workspace into the running bottle.
-
-        This is the only supported workspace-provisioning path: Docker
-        does not build a derived image containing the current
-        workspace."""
-        workspace = plan.workspace_plan
-        if not (workspace.enabled and workspace.copy_contents):
-            return
-
-        guest_parent = workspace.guest_path.rsplit("/", 1)[0] or "/"
-        guest_path = shlex.quote(workspace.guest_path)
-        guest_parent = shlex.quote(guest_parent)
-        owner = shlex.quote(workspace.owner)
-        mode = shlex.quote(workspace.mode)
-        info(f"copying {workspace.host_path} -> {bottle.name}:{workspace.guest_path}")
-        bottle.exec(
-            f"rm -rf {guest_path} && mkdir -p {guest_parent}",
-            user="root",
-        )
-        bottle.cp_in(str(workspace.host_path), workspace.guest_path)
-        bottle.exec(
-            f"chown -R {owner} {guest_path} && chmod {mode} {guest_path}",
-            user="root",
-        )
-
-    def supervise_mcp_url(self, plan: PlanT) -> str:
-        """Return the agent-side URL of the per-bottle supervise
-        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.
-
-        Default returns "" so backends without supervise support
-        don't have to implement it. Docker and firecracker override."""
-        del plan
-        return ""
-
-    def ensure_orchestrator(self) -> str:
-        """Bring up this backend's per-host orchestrator + shared gateway
-        (idempotent) and return the host-reachable control-plane URL.
-
-        This is the backend-agnostic bring-up entry point: `launch` calls
-        it as part of starting a bottle, and operator tools (`supervise`)
-        call it to start the control plane on demand when none is running
-        yet. Docker starts the orchestrator + gateway containers;
-        firecracker boots the infra VM. Backends with no orchestrator
-        (macos-container) die with a pointer — the default here."""
-        die(f"backend {self.name!r} has no orchestrator control plane")
-
-    @abstractmethod
-    def prepare_cleanup(self) -> CleanupT:
-        """Enumerate orphaned resources from previous bottles. No side
-        effects; safe to call before the y/N."""
-
-    @abstractmethod
-    def cleanup(self, plan: CleanupT) -> None:
-        """Remove everything described by the cleanup plan."""
-
-    @abstractmethod
-    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 gateway
-        containers against per-bottle metadata."""
-
-    @classmethod
-    @abstractmethod
-    def is_available(cls) -> bool:
-        """Whether this backend's runtime prerequisites are satisfied
-        on the current host. Docker → `docker` on PATH; firecracker →
-        Linux + KVM. Used by the cross-backend
-        `enumerate_active_agents` / `cmd_cleanup` to skip backends
-        the operator hasn't installed, so a docker-only host
-        doesn't fail when `cli.py active` walks past
-        firecracker."""
-
-    @classmethod
-    @abstractmethod
-    def setup(cls) -> int:
-        """Emit this backend's one-time host setup — privileged network
-        pool, daemon bring-up, install pointers, etc. — as
-        host-appropriate config or commands. Prints to stdout/stderr and
-        returns a shell exit code (0 = nothing to report / success). A
-        backend that needs no host setup prints a short note and returns
-        0. Invoked generically by `./cli.py backend setup [--backend=…]`
-        so operators can provision any backend without a
-        backend-specific command. Classmethod (like `is_available`) —
-        it's a host query, not per-bottle state."""
-
-    @classmethod
-    @abstractmethod
-    def status(cls, *, quiet: bool = False) -> int:
-        """Report whether this backend's prerequisites are satisfied on
-        the host — binaries, daemon reachability, network pool, range
-        conflicts, etc. Returns BackendStatus.READY (0) when the backend
-        is ready to launch and non-zero when something is missing.
-
-        When quiet=False (default) prints a human-readable summary to
-        stderr. When quiet=True returns the status code silently —
-        useful for cheap programmatic checks.
-
-        Invoked by `./cli.py backend status [--backend=…]` (quiet=False)
-        and by is_backend_ready() (caller-controlled)."""
-
-    @classmethod
-    @abstractmethod
-    def teardown(cls) -> int:
-        """Undo `setup()` — the inverse operation, surfaced as
-        `./cli.py backend teardown [--backend=…]` (uninstall). Symmetric
-        with setup: where setup is advisory (prints the privileged
-        commands / declarative config to apply), teardown prints the
-        commands / config change to remove the host prerequisites. A
-        backend with no host setup prints a short note and returns 0.
-        Not called by the launch path or the test suite."""

bot_bottle/backend/docker/__init__.py

@@ -11,42 +11,18 @@ The bulk of the implementation lives in sibling modules:
   - launch:               bring-up + teardown context manager
   - cleanup:              orphan enumeration, removal, active listing
   - backend:              DockerBottleBackend façade wiring the above
-  - infra:                DockerInfraService (the per-host orchestrator + gateway pair)
 
-Thin by design: the public names are re-exported lazily via `__getattr__`, so
-importing a leaf like `backend.docker.util` doesn't drag `DockerBottleBackend`
-(and the whole framework it pulls) into memory.
+This file only re-exports the public names so
+`from bot_bottle.backend.docker import DockerBottleBackend` keeps
+working.
 """
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from .backend import DockerBottleBackend
-    from .bottle import DockerBottle
-    from .bottle_cleanup_plan import DockerBottleCleanupPlan
-    from .bottle_plan import DockerBottlePlan
-
-
-_LAZY_MODULES: dict[str, str] = {
-    "DockerBottleBackend": "backend",
-    "DockerBottle": "bottle",
-    "DockerBottleCleanupPlan": "bottle_cleanup_plan",
-    "DockerBottlePlan": "bottle_plan",
-}
-
-
-def __getattr__(name: str) -> Any:
-    mod = _LAZY_MODULES.get(name)
-    if mod is None:
-        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-    from importlib import import_module
-
-    value = getattr(import_module(f"{__name__}.{mod}"), name)
-    globals()[name] = value
-    return value
-
+from .backend import DockerBottleBackend
+from .bottle import DockerBottle
+from .bottle_cleanup_plan import DockerBottleCleanupPlan
+from .bottle_plan import DockerBottlePlan
 
 __all__ = [
     "DockerBottle",

bot_bottle/backend/docker/backend.py

@@ -20,19 +20,18 @@ infrastructure: CA install and git copy-in.
 from __future__ import annotations
 
 import shutil
-import io
-from contextlib import contextmanager, redirect_stderr
+from contextlib import contextmanager
 from pathlib import Path
 from typing import Generator, Sequence
 
-from ...supervisor.types import SUPERVISE_HOSTNAME, SUPERVISE_PORT
+from ...supervise import SUPERVISE_HOSTNAME, SUPERVISE_PORT
 from ...agent_provider import AgentProvisionPlan
 from ...egress import EgressPlan
 from ...env import ResolvedEnv
 from ...git_gate import GitGatePlan
-from ...supervisor.plan import SupervisePlan
+from ...supervise import SupervisePlan
 from ...manifest import Manifest
-from .. import ActiveAgent, BottleBackend, BottleImages, BottleSpec
+from .. import ActiveAgent, BottleBackend, BottleSpec
 from . import cleanup as _cleanup
 from . import enumerate as _enumerate
 from . import launch as _launch
@@ -61,11 +60,8 @@ class DockerBottleBackend(BottleBackend["DockerBottlePlan", "DockerBottleCleanup
         return _setup.setup()
 
     @classmethod
-    def status(cls, *, quiet: bool = False) -> int:
+    def status(cls) -> int:
         from . import setup as _setup
-        if quiet:
-            with redirect_stderr(io.StringIO()):
-                return _setup.status()
         return _setup.status()
 
     @classmethod
@@ -104,32 +100,17 @@ class DockerBottleBackend(BottleBackend["DockerBottlePlan", "DockerBottleCleanup
             stage_dir=stage_dir,
         )
 
-    def prelaunch_checks(self, plan: DockerBottlePlan) -> None:
-        _launch.stale_checks(plan)
-
-    def _build_or_load_images(self, plan: DockerBottlePlan) -> BottleImages:
-        return _launch.build_or_load_images(plan)
-
     @contextmanager
-    def _launch_impl(self, plan: DockerBottlePlan, images: BottleImages) -> Generator[DockerBottle, None, None]:
-        with _launch.launch(plan, images, provision=self.provision) as bottle:
+    def launch(self, plan: DockerBottlePlan) -> Generator[DockerBottle, None, None]:
+        with _launch.launch(plan, provision=self.provision) as bottle:
             yield bottle
 
-    def ensure_orchestrator(self) -> str:
-        from .infra import DockerInfraService
-        return DockerInfraService().ensure_running()
-
     def supervise_mcp_url(self, plan: DockerBottlePlan) -> str:
-        """Docker bottles reach the supervise daemon via the
+        """Docker bottles reach the supervise sidecar 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,38 +28,11 @@ 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 = ""
-    # Per-bottle identity token the agent presents on every attributed request
-    # (egress proxy credentials, git-gate/supervise headers); set by launch
-    # from the orchestrator registration. Empty pre-registration.
-    identity_token: str = ""
-    # Encryption key for the agent's stored egress secrets; injected into the
-    # agent container as ENV_VAR_SECRET via the compose subprocess env (bare
-    # name — value never written to the compose file). Empty pre-registration.
-    env_var_secret: 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/compose.py

@@ -1,10 +1,20 @@
-"""Docker compose lifecycle helpers (PRD 0018).
+"""Compose-spec rendering for a Docker bottle (PRD 0018, chunk 1).
 
-Serialize a compose spec to disk, drive `docker compose up/down`,
-dump the merged log on teardown, and enumerate `bot-bottle-*`
-projects. The spec itself is built by `consolidated_compose.py`
-(the consolidated per-host gateway topology); this module owns the
-I/O side that persists and runs it.
+`bottle_plan_to_compose(plan)` returns a Compose v2 spec dict
+describing the per-bottle container topology — one project per
+bottle instance, services for the agent + every applicable sidecar,
+two networks, no named volumes.
+
+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
@@ -15,7 +25,233 @@ 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) ----------------------------------
@@ -206,6 +442,7 @@ __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

@@ -1,89 +0,0 @@
-"""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
-from ...orchestrator.store.secret_store import ENV_VAR_SECRET_NAME
-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`."""
-    # Deliver the identity token as egress proxy credentials — the gateway
-    # reads Proxy-Authorization, validates the (source_ip, token) pair, and
-    # strips it before upstream. git-http/supervise get it via their own
-    # headers (git config extraHeader / MCP header).
-    token = getattr(plan, "identity_token", "")
-    cred = f"bottle:{token}@" if token else ""
-    proxy_url = f"http://{cred}{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_VAR_SECRET: bare name so the value comes from the compose subprocess
-    # env (set in launch.py) and is never written to the compose file on disk.
-    if getattr(plan, "env_var_secret", ""):
-        env.append(ENV_VAR_SECRET_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

@@ -1,185 +0,0 @@
-"""Consolidated bottle launch sequence for the docker backend (PRD 0070).
-
-Composes the orchestrator primitives into the register/teardown sequence:
-
-  1. ensure the per-host pair (orchestrator + gateway containers) is up;
-  2. allocate the bottle a pinned source IP on the gateway network;
-  3. register it and provision its git-gate repos/creds into the gateway.
-
-Returns a `LaunchContext` with everything the agent container needs to
-attach. The agent `docker run` itself is the backend's job; this owns the
-orchestrator-facing wiring so that sequence stays testable in isolation.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from ... import log
-from .util import run_docker
-from ...egress import EgressPlan
-from ...git_gate import GitGatePlan
-from ...orchestrator.client import OrchestratorClient
-from ...gateway import GATEWAY_NETWORK
-from .infra import INFRA_NAME, DockerInfraService
-from ...orchestrator.store.secret_store import ENV_VAR_SECRET_NAME
-from ...orchestrator.reprovision import reprovision_bottles
-from ..provision_bottle import deprovision_bottle, provision_bottle
-from .gateway_transport import DockerGatewayTransport
-from .gateway_net import next_free_ip
-
-
-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
-    env_var_secret: str = ""  # encryption key injected into the agent's env
-
-
-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 _network_container_ips(network: str) -> list[str]:
-    """Every address currently assigned on the gateway network — the ground
-    truth for "in use": the gateway container and every live agent. Read from
-    the network so a new bottle can't collide with anything actually attached."""
-    proc = run_docker([
-        "docker", "network", "inspect", "--format",
-        "{{range .Containers}}{{.IPv4Address}} {{end}}", network,
-    ])
-    ips: list[str] = []
-    for entry in proc.stdout.split():
-        ips.append(entry.split("/", 1)[0])
-    return ips
-
-
-def _reprovision_running_bottles(
-    orchestrator_url: str,
-    network: str = GATEWAY_NETWORK,
-    infra_name: str = INFRA_NAME,
-) -> None:
-    """Re-inject egress tokens for any registered bottles that lost their
-    in-memory tokens (e.g., after an orchestrator restart).
-
-    For each registered bottle whose source IP maps to a live container on the
-    gateway network, reads ENV_VAR_SECRET via ``docker exec … printenv`` and
-    calls ``POST /bottles/<id>/reprovision_gateway``. Idempotent — a no-op
-    when the orchestrator already has all tokens loaded. Best-effort: a single
-    container exec failure never blocks a new bottle launch."""
-    client = OrchestratorClient(orchestrator_url)
-    # Build {source_ip: container_name} from live containers on the gateway
-    # network, excluding the gateway container itself.
-    try:
-        proc = run_docker([
-            "docker", "network", "inspect",
-            "--format", "{{range .Containers}}{{.Name}} {{.IPv4Address}}\n{{end}}",
-            network,
-        ])
-    except OSError as exc:
-        log.info(f"egress token reprovision skipped: {exc}")
-        return
-    ip_to_container: dict[str, str] = {}
-    for line in proc.stdout.splitlines():
-        parts = line.strip().split()
-        if len(parts) >= 2 and parts[0] != infra_name:
-            ip = parts[1].split("/", 1)[0]
-            if ip:
-                ip_to_container[ip] = parts[0]
-
-    secrets_by_ip: dict[str, str] = {}
-    for source_ip, container_name in ip_to_container.items():
-        proc = run_docker(
-            ["docker", "exec", container_name, "printenv", ENV_VAR_SECRET_NAME]
-        )
-        if proc.returncode == 0 and proc.stdout.strip():
-            secrets_by_ip[source_ip] = proc.stdout.strip()
-
-    reprovisioned = reprovision_bottles(client, secrets_by_ip)
-    if reprovisioned:
-        log.info(
-            "reprovisioned egress tokens",
-            context={"count": reprovisioned},
-        )
-
-
-def launch_consolidated(
-    egress_plan: EgressPlan,
-    git_gate_plan: GitGatePlan,
-    *,
-    image_ref: str = "",
-    tokens: dict[str, str] | None = None,
-    service: DockerInfraService | None = None,
-    infra_name: str = INFRA_NAME,
-    network: str = GATEWAY_NETWORK,
-) -> LaunchContext:
-    """Ensure the orchestrator + gateway pair is up, allocate + register the bottle, and
-    provision its git-gate state. Returns the agent's attach context.
-
-    Also reprovisiones egress tokens for any already-running bottles that lost
-    their in-memory credentials (e.g. after an orchestrator restart), so
-    they regain egress access before the new bottle is registered."""
-    service = service or DockerInfraService()
-    url = service.ensure_running()
-    # Agents attribute against the *gateway* container (data plane), not the
-    # orchestrator — the two planes are now separate containers. Read its
-    # agent-facing address + provisioning transport off the Gateway service.
-    gateway = service.gateway()
-    _reprovision_running_bottles(url, network=network, infra_name=gateway.name)
-    client = OrchestratorClient(url)
-
-    cidr = _network_cidr(network)
-    gateway_ip = gateway.address()
-    source_ip = next_free_ip(cidr, _network_container_ips(network))
-
-    transport = gateway.provisioning_transport()
-    reg = provision_bottle(
-        client, source_ip, egress_plan, git_gate_plan, transport,
-        image_ref=image_ref, tokens=tokens,
-    )
-    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,
-        env_var_secret=reg.env_var_secret,
-    )
-
-
-def deprovision_consolidated(
-    bottle_id: str, *, orchestrator_url: str, infra_name: str = INFRA_NAME,
-    timeout: float | None = None,
-) -> None:
-    """Deregister the bottle and remove its git-gate state. Idempotent."""
-    deprovision_bottle(bottle_id, DockerGatewayTransport(infra_name),
-                   orchestrator_url=orchestrator_url, timeout=timeout)
-
-
-__all__ = [
-    "LaunchContext",
-    "launch_consolidated",
-    "deprovision_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 gateway (PRD 0024) runs egress
+PRD 0024 chunk 3; the sidecar bundle (PRD 0024) runs egress
 under its python init supervisor."""
 
 from __future__ import annotations

bot_bottle/backend/docker/egress_apply.py

@@ -1,29 +1,60 @@
-"""Host-side egress route-apply for the docker backend.
+"""Host-side helper for egress sidecar inspection and live updates.
 
-The per-bottle companion container this used to signal (`docker kill
---signal HUP <container>`) was removed in the companion-container removal (#385).
-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.
+The approve path uses this module to validate a proposed routes file,
+write it to the bottle's live egress state dir, and signal the sidecar
+bundle so the mitmproxy addon reloads it.
 """
 
 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:
-        del slug
-        raise EgressApplyError(
-            "live egress route-apply was removed with the per-bottle "
-            "companion container (#385); route changes will flow through "
-            "the consolidated gateway in a follow-up."
+        container = sidecar_bundle_container_name(slug)
+        result = subprocess.run(
+            ["docker", "kill", "--signal", "HUP", container],
+            capture_output=True, text=True, check=False, env=os.environ,
         )
+        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__ = ["DockerEgressApplicator", "EgressApplyError", "applicator"]
+__all__ = [
+    "DockerEgressApplicator",
+    "EgressApplyError",
+    "applicator",
+    "fetch_current_routes",
+]

bot_bottle/backend/docker/enumerate.py

@@ -1,6 +1,6 @@
 """Active-agent enumeration for the docker backend.
 
-Returns `ActiveAgent` records the CLI `active` command and the
+Returns `ActiveAgent` records the CLI `list active` command and the
 dashboard agents pane consume. Empty when docker isn't reachable
 — gated by `has_backend('docker')` at the cross-backend caller
 so this module trusts that docker is available when called.
@@ -60,7 +60,7 @@ def _parse_services_by_project(stdout: str) -> dict[str, set[str]]:
 
 def _query_services_by_project() -> dict[str, set[str]]:
     """One `docker ps` call → `{project: {service, ...}}`. Used
-    by the CLI's `active` and the dashboard's agents pane —
+    by the CLI's `list active` and the dashboard's agents pane —
     one subprocess per refresh tick, not one per bottle."""
     try:
         r = subprocess.run(

bot_bottle/backend/docker/gateway.py

@@ -1,295 +0,0 @@
-from __future__ import annotations
-
-import os
-import time
-from pathlib import Path
-
-from .util import run_docker
-from .gateway_transport import DockerGatewayTransport
-from ...paths import (
-    ORCHESTRATOR_AUTH_JWT_ENV,
-    host_gateway_ca_dir,
-)
-from ... import resources
-from ...gateway import (
-  Gateway, GatewayTransport, GATEWAY_IMAGE, GATEWAY_NAME, GATEWAY_NETWORK,
-  GATEWAY_DOCKERFILE, GATEWAY_LABEL, MITMPROXY_HOME,
-  DEFAULT_CA_TIMEOUT_SECONDS, CA_POLL_SECONDS, GATEWAY_CA_CERT, GatewayError
-)
-
-DEFAULT_GATEWAY_SUBNET = "10.242.255.0/24"
-_GATEWAY_SUBNET_LABEL = "bot-bottle.gateway-subnet"
-
-
-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,
-        control_network: str = "",
-        build_context: Path | None = None,
-        dockerfile: str | None = GATEWAY_DOCKERFILE,
-        host_port_bindings: tuple[int, ...] = (),
-        ca_mount_source: str | Path | None = None,
-        subnet: str | None = None,
-    ) -> None:
-        self.image_ref = image_ref
-        self.name = name
-        self.network = network
-        # When set, the gateway is dual-homed: it also joins this `--internal`
-        # control network (shared only with the orchestrator) so it can resolve
-        # `orchestrator_url` by container name over docker DNS. Agents are never
-        # on it, so they get no route to the control plane (PRD 0070).
-        self._control_network = control_network
-        # The orchestrator binding — set by `connect_to_orchestrator` (the
-        # control-plane URL the data plane resolves against, and the pre-minted
-        # `gateway` token it presents; the gateway never mints, so it never
-        # holds the signing key — #469). Empty until connected; `ca_cert_pem` /
-        # `address` / `stop` work on an already-running gateway without it.
-        self._orchestrator_url = ""
-        self._gateway_token = ""
-        # Resolved lazily in ensure_built() so merely constructing a gateway to
-        # read its CA never stages a build root from an installed wheel.
-        self._build_context = build_context
-        self._dockerfile = dockerfile
-        # Ports published on the host (0.0.0.0). Used by the Firecracker
-        # backend's dev-harness gateway so VMs can reach it via their TAP link;
-        # Docker's DNAT + the nft `ct status dnat accept` rule handle the rest.
-        self._host_port_bindings = host_port_bindings
-        self._subnet = (
-            subnet
-            or os.environ.get("BOT_BOTTLE_DOCKER_GATEWAY_SUBNET", "").strip()
-            or DEFAULT_GATEWAY_SUBNET
-        )
-        configured_ca = os.environ.get("BOT_BOTTLE_DOCKER_CA_MOUNT", "").strip()
-        self._ca_mount_source = str(
-            ca_mount_source or configured_ca or host_gateway_ca_dir()
-        )
-
-    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
-        context = self._build_context or resources.build_root()
-        argv = ["docker", "build", "-t", self.image_ref,
-                "-f", str(context / self._dockerfile),
-                str(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').
-        The explicit subnet is required because bottle attribution pins source
-        IPs; Docker rejects static endpoint addresses on an auto-IPAM network."""
-        inspected = run_docker([
-            "docker", "network", "inspect",
-            "--format", f'{{{{index .Labels "{_GATEWAY_SUBNET_LABEL}"}}}}',
-            self.network,
-        ])
-        if inspected.returncode == 0:
-            marker = inspected.stdout.strip()
-            if marker in {"", self._subnet}:
-                return
-        if inspected.returncode == 0:
-            # Migrate the stale auto-IPAM network created by older releases.
-            # Removing the fixed gateway is safe here: this launch recreates it.
-            run_docker(["docker", "rm", "--force", self.name])
-            removed = run_docker(["docker", "network", "rm", self.network])
-            if removed.returncode != 0:
-                raise GatewayError(
-                    f"gateway network {self.network} needs explicit subnet "
-                    f"{self._subnet} but could not be replaced: "
-                    f"{removed.stderr.strip()}"
-                )
-        proc = run_docker([
-            "docker", "network", "create",
-            "--subnet", self._subnet,
-            "--label", f"{_GATEWAY_SUBNET_LABEL}={self._subnet}",
-            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 connect_to_orchestrator(self, orchestrator_url: str, gateway_token: str) -> None:
-        # Bind to this orchestrator (PRD 0070): stash the URL its daemons resolve
-        # policy against + the pre-minted `gateway` token they present, then bring
-        # the container up. The gateway never mints, so it holds no signing key —
-        # only this token (#469).
-        self._orchestrator_url = orchestrator_url
-        self._gateway_token = gateway_token
-        # Fail closed on a missing policy source. The data-plane daemons are
-        # resolver-only now (PRD 0070) — without an orchestrator URL egress
-        # raises, git-http exits 1, and supervise exits 2 — so launching a
-        # gateway without one would only crash-loop its daemons. Refuse here so
-        # the misconfiguration surfaces as a clear error, not a broken container.
-        if not self._orchestrator_url:
-            raise GatewayError(
-                "gateway requires an orchestrator URL to run "
-                "(resolver-only data plane; no single-tenant fallback)"
-            )
-        if not self._gateway_token:
-            raise GatewayError(
-                "gateway requires a pre-minted `gateway` token to run "
-                "(the orchestrator mints it; the gateway never holds the key)"
-            )
-        # 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.
-        self._ensure_network()
-        if self.is_running() and self._running_image_is_current():
-            return
-        # 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 on the host so it survives both
-            # container recreation AND docker volume pruning (agents trust it)
-            # — see host_gateway_ca_dir / issue #450.
-            "--volume", f"{self._ca_mount_source}:{MITMPROXY_HOME}",
-            # No DB mount: the data plane (egress / supervise / git-gate) reaches
-            # the supervise queue over the control-plane RPC and never opens
-            # bot-bottle.db, so the gateway container gets no file handle on it
-            # (PRD 0070 / issue #469).
-        ]
-        for port in self._host_port_bindings:
-            argv += ["--publish", f"0.0.0.0:{port}:{port}"]
-        run_env = dict(os.environ)
-        # The gateway's egress / git / supervise daemons resolve source-IP ->
-        # policy against the control plane per request (guaranteed non-empty by
-        # the check above).
-        argv += ["--env", f"BOT_BOTTLE_ORCHESTRATOR_URL={self._orchestrator_url}"]
-        # ...presenting a role-scoped `gateway` token (a signed JWT minted from
-        # the host signing key) on those calls. The gateway never receives the
-        # signing key — only this pre-minted token, which it cannot rewrite into
-        # a `cli` token, so a compromised data-plane process can't drive the
-        # operator routes (issue #469 review). Bare `--env NAME` keeps the value
-        # off argv / `docker inspect`; only the gateway (not the agent) is given it.
-        argv += ["--env", ORCHESTRATOR_AUTH_JWT_ENV]
-        run_env[ORCHESTRATOR_AUTH_JWT_ENV] = self._gateway_token
-        argv.append(self.image_ref)
-        proc = run_docker(argv, env=run_env)
-        if proc.returncode != 0:
-            raise GatewayError(f"gateway failed to start: {proc.stderr.strip()}")
-        # Dual-home onto the control network so the daemons resolve the
-        # orchestrator by name. Docker attaches only one network at `run`, so
-        # the second is a `network connect` — the daemons tolerate the brief
-        # pre-connect window (they retry /resolve per request).
-        if self._control_network:
-            self._connect_control_network()
-
-    def _connect_control_network(self) -> None:
-        """Ensure the `--internal` control network exists and attach the gateway
-        to it (idempotent — an already-connected container is a tolerated
-        no-op)."""
-        if run_docker(["docker", "network", "inspect", self._control_network]).returncode != 0:
-            proc = run_docker(["docker", "network", "create", "--internal", self._control_network])
-            if proc.returncode != 0 and "already exists" not in proc.stderr:
-                raise GatewayError(
-                    f"control network {self._control_network} failed to create: "
-                    f"{proc.stderr.strip()}"
-                )
-        proc = run_docker(["docker", "network", "connect", self._control_network, self.name])
-        if proc.returncode != 0 and "already exists" not in proc.stderr:
-            raise GatewayError(
-                f"gateway failed to join control network {self._control_network}: "
-                f"{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()}")
-
-    def address(self) -> str:
-        """The gateway's IPv4 on the agent-facing network (`self.network`) — the
-        proxy target agents dial for egress / git-http / supervise. This is
-        *not* the control network: agents share only this network with the
-        gateway, so its address here is also the source IP the gateway
-        attributes each request by."""
-        proc = run_docker([
-            "docker", "inspect", "--format",
-            f'{{{{(index .NetworkSettings.Networks "{self.network}").IPAddress}}}}',
-            self.name,
-        ])
-        ip = proc.stdout.strip()
-        if proc.returncode != 0 or not ip:
-            raise GatewayError(
-                f"gateway {self.name} has no address on {self.network}: "
-                f"{proc.stderr.strip()}"
-            )
-        return ip
-
-    def provisioning_transport(self) -> GatewayTransport:
-        """The exec/cp transport git-gate provisioning stages per-bottle repos +
-        deploy keys through (over the docker socket)."""
-        return DockerGatewayTransport(self.name)

bot_bottle/backend/docker/gateway_net.py

@@ -1,47 +0,0 @@
-"""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_transport.py

@@ -1,35 +0,0 @@
-"""The `GatewayTransport` for the docker gateway container (PRD 0070).
-
-How the launcher stages files + runs commands in the running gateway container:
-`docker exec` / `docker cp` over the docker socket. The backend-neutral
-provisioning logic that drives it lives in `backend.provision_gateway`.
-"""
-
-from __future__ import annotations
-
-from .util import run_docker
-from ...gateway import GatewayProvisionError
-
-
-class DockerGatewayTransport:
-    """`GatewayTransport` for the docker gateway container (exec/cp)."""
-
-    def __init__(self, gateway: str) -> None:
-        self.gateway = gateway
-
-    def exec(self, argv: list[str]) -> None:
-        proc = run_docker(["docker", "exec", self.gateway, *argv])
-        if proc.returncode != 0:
-            raise GatewayProvisionError(
-                f"gateway exec {argv!r} failed: {proc.stderr.strip()}"
-            )
-
-    def cp_into(self, src: str, dest: str) -> None:
-        proc = run_docker(["docker", "cp", src, f"{self.gateway}:{dest}"])
-        if proc.returncode != 0:
-            raise GatewayProvisionError(
-                f"gateway cp {src} -> {dest} failed: {proc.stderr.strip()}"
-            )
-
-
-__all__ = ["DockerGatewayTransport"]

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 gateway (PRD 0024)."""
+is owned by the sidecar bundle (PRD 0024)."""
 
 from __future__ import annotations
 

bot_bottle/backend/docker/infra.py

@@ -1,160 +0,0 @@
-"""The per-host control plane + gateway for the docker backend (PRD 0070).
-
-Runs the orchestrator (control plane) and the gateway (data plane) as **two
-separate containers**, split now that #469 got the DB off the data plane:
-
-  * `bot-bottle-orchestrator` — the lean control-plane container
-    (`DockerOrchestrator`). Joins the `bot-bottle-orchestrator` **control
-    network** (`--internal`) only, plus a host-loopback publish for the CLI.
-    Sole opener of `bot-bottle.db`; holds the signing key.
-  * `bot-bottle-gateway` — the data-plane container (`DockerGateway`).
-    **Dual-homed** on the agent-facing `bot-bottle-gateway` network *and* the
-    control network, so it reaches the orchestrator by name over docker DNS
-    (`http://bot-bottle-orchestrator:8099`) while agents — which are never on
-    the control network — cannot reach the control plane at all (the L3 block
-    Firecracker's nft already has). Holds the `gateway` JWT + the mitmproxy CA.
-
-`DockerInfraService` composes the two services (`orchestrator()` + `gateway()`)
-and brings them up as an idempotent per-host pair. Callers use `ensure_running()`
-(returns the host control-plane URL) + `gateway_name` (the container the launch
-flow attributes agents against).
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from .util import run_docker
-from .gateway import DockerGateway
-from .orchestrator import (
-    DockerOrchestrator,
-    ORCHESTRATOR_IMAGE,
-    ORCHESTRATOR_LABEL,
-    ORCHESTRATOR_NAME,
-    ORCHESTRATOR_NETWORK,
-)
-from ... import resources
-from ...gateway import (
-    GATEWAY_IMAGE,
-    GATEWAY_NAME,
-    GATEWAY_NETWORK,
-)
-from ..infra_service import InfraService
-from ...orchestrator.lifecycle import (
-    DEFAULT_PORT,
-    DEFAULT_STARTUP_TIMEOUT_SECONDS,
-)
-
-# Back-compat aliases: the split retired the combined `bot-bottle-infra`
-# container, but the fixed-name constants some callers/tests import still map to
-# the pair's public identity.
-INFRA_NAME = GATEWAY_NAME  # the container agents attribute against is the gateway
-
-
-class DockerInfraService(InfraService):
-    """Composes the per-host control plane + gateway as two containers.
-
-    `orchestrator_name` / `gateway_name` let callers run independent pairs on
-    one host without name collisions (e.g. isolated integration tests that
-    can't share the production singletons)."""
-
-    def __init__(
-        self,
-        *,
-        port: int = DEFAULT_PORT,
-        network: str = GATEWAY_NETWORK,
-        control_network: str = ORCHESTRATOR_NETWORK,
-        orchestrator_image: str = ORCHESTRATOR_IMAGE,
-        gateway_image: str = GATEWAY_IMAGE,
-        repo_root: Path | None = None,
-        host_root: Path | None = None,
-        root_mount_source: str | Path | None = None,
-        gateway_ca_mount_source: str | Path | None = None,
-        orchestrator_name: str = ORCHESTRATOR_NAME,
-        orchestrator_label: str = ORCHESTRATOR_LABEL,
-        gateway_name: str = GATEWAY_NAME,
-    ) -> None:
-        self.port = port
-        self.network = network
-        self.control_network = control_network
-        self.orchestrator_image = orchestrator_image
-        self.gateway_image = gateway_image
-        # Build context: the repo root in a checkout, a staged copy from the
-        # installed wheel otherwise (bot_bottle.resources).
-        self._repo_root = repo_root if repo_root is not None else resources.build_root()
-        if host_root is not None and root_mount_source is not None:
-            raise ValueError("pass host_root or root_mount_source, not both")
-        self._host_root = host_root
-        self._root_mount_source = root_mount_source
-        self._gateway_ca_mount_source = gateway_ca_mount_source
-        self._orchestrator_name = orchestrator_name
-        self._orchestrator_label = orchestrator_label
-        self._gateway_name = gateway_name
-
-    def orchestrator(self) -> DockerOrchestrator:
-        """The control-plane service. Cheap to reconstruct — `ensure_built`
-        builds its image, `ensure_running` brings it up, and the launch flow
-        reads its `url()` / `gateway_url()` / `mint_gateway_token()` off it."""
-        return DockerOrchestrator(
-            self.orchestrator_image,
-            name=self._orchestrator_name,
-            label=self._orchestrator_label,
-            port=self.port,
-            control_network=self.control_network,
-            repo_root=self._repo_root,
-            host_root=self._host_root,
-            root_mount_source=self._root_mount_source,
-        )
-
-    def gateway(self) -> DockerGateway:
-        """The data-plane gateway, dual-homed on the agent network + the control
-        network, resolving policy against the orchestrator by name. Cheap to
-        reconstruct — the launch flow reads its `address()` / provisioning
-        transport off it, and `ensure_running` connects it to the control
-        plane."""
-        return DockerGateway(
-            self.gateway_image,
-            name=self._gateway_name,
-            network=self.network,
-            control_network=self.control_network,
-            build_context=self._repo_root,
-            ca_mount_source=self._gateway_ca_mount_source,
-        )
-
-    def ensure_running(
-        self, *, startup_timeout: float = DEFAULT_STARTUP_TIMEOUT_SECONDS,
-    ) -> str:
-        """Ensure the orchestrator + gateway containers are up; return the host
-        control-plane URL. Idempotent — a healthy orchestrator on current source
-        (and a current-image gateway) is left untouched. Raises
-        `OrchestratorStartError` on control-plane startup timeout."""
-        orchestrator = self.orchestrator()
-        gateway = self.gateway()
-        # Build both images (cache-aware; a no-op when nothing changed) before
-        # bringing either plane up.
-        orchestrator.ensure_built()
-        gateway.ensure_built()
-
-        orchestrator.ensure_running(startup_timeout=startup_timeout)
-
-        # Bring up (or refresh) the gateway once the control plane it resolves
-        # against is healthy. The orchestrator (which holds the signing key)
-        # mints the role-scoped `gateway` JWT here and hands it to the gateway,
-        # which never sees the key (#469). `connect_to_orchestrator` is
-        # idempotent.
-        gateway.connect_to_orchestrator(
-            orchestrator.gateway_url(), orchestrator.mint_gateway_token(),
-        )
-        return orchestrator.url()
-
-    def stop(self) -> None:
-        """Remove both containers (idempotent)."""
-        run_docker(["docker", "rm", "--force", self._gateway_name])
-        run_docker(["docker", "rm", "--force", self._orchestrator_name])
-
-
-__all__ = [
-    "DockerInfraService",
-    "ORCHESTRATOR_NAME",
-    "INFRA_NAME",
-]

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 gateway image on first up).
+     builds the sidecar images via the `build:` directive 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
@@ -33,14 +33,16 @@ from __future__ import annotations
 import dataclasses
 import os
 from contextlib import ExitStack, contextmanager
+from pathlib import Path
 from typing import Callable, Generator
 
-from ...agent_provider import runtime_for
-from ...egress import Egress
-from ...git_gate import GitGate
-from ...image_cache import check_stale
-from ...log import die, info, warn
-from .. import BottleImages
+from ...egress import egress_resolve_token_values
+from ...git_gate import (
+    provision_git_gate_dynamic_keys,
+    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
@@ -51,6 +53,7 @@ from ...bottle_state import (
     read_committed_image,
 )
 from .compose import (
+    bottle_plan_to_compose,
     compose_down,
     compose_dump_logs,
     compose_file_path,
@@ -59,55 +62,23 @@ from .compose import (
     compose_up,
     write_compose_file,
 )
-from .consolidated_compose import consolidated_agent_compose
-from ...orchestrator.store.config_store import resolve_teardown_timeout
-from .consolidated_launch import launch_consolidated, deprovision_consolidated
-from .infra import INFRA_NAME
-from .gateway import DockerGateway
-from ... import resources
+from .egress import egress_tls_init
 
 
-def build_or_load_images(plan: DockerBottlePlan) -> BottleImages:
-    """Resolve the agent image ref for this plan.
-
-    Returns the committed snapshot if one exists, the cached image when the
-    policy is 'cached', or builds a fresh image and returns that."""
-    committed = read_committed_image(plan.slug)
-    if committed and docker_mod.image_exists(committed):
-        info(f"using committed image {committed!r}")
-        return BottleImages(agent=committed)
-    if plan.spec.image_policy == "cached":
-        if not docker_mod.image_exists(plan.image):
-            die(
-                f"cached agent image {plan.image!r} not found; "
-                "run without --cached-images to build it"
-            )
-        info(f"using cached agent image {plan.image!r}")
-        return BottleImages(agent=plan.image)
-    docker_mod.build_image(plan.image, str(resources.build_root()), dockerfile=plan.dockerfile_path)
-    docker_mod.verify_agent_image(
-        plan.image, runtime_for(plan.agent_provider_template).smoke_test,
-    )
-    return BottleImages(agent=plan.image)
+# Where the repo root lives, for `docker build` context. Computed once.
+_REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)
 
 
 @contextmanager
 def launch(
     plan: DockerBottlePlan,
-    images: BottleImages,
     *,
     provision: Callable[[DockerBottlePlan, "DockerBottle"], str | None],
 ) -> Generator[DockerBottle, None, None]:
-    """Launch and provision a Docker bottle via compose. Teardown on exit."""
+    """Build, launch, and provision a Docker bottle via compose.
+    Teardown on exit."""
     stack = ExitStack()
 
-    # Stamp the resolved agent image ref into the plan so compose rendering
-    # picks up the right image (may be a committed snapshot or cached ref).
-    plan = dataclasses.replace(
-        plan,
-        agent_provision=dataclasses.replace(plan.agent_provision, image=str(images.agent)),
-    )
-
     _bottle_for_revoke = plan.manifest.bottle
     _git_gate_dir_for_revoke = git_gate_state_dir(plan.slug)
 
@@ -119,99 +90,104 @@ def launch(
                 f"teardown failed for container {plan.container_name}"
                 f" (compose-down): {exc!r}"
             )
-        GitGate().revoke_provisioned_keys(
+        revoke_git_gate_provisioned_keys(
             _bottle_for_revoke, _git_gate_dir_for_revoke
         )
 
     try:
-        # Step 2: mint the git-gate dynamic (gitea) deploy keys, if any, before
-        # provisioning the bottle's repos into the shared gateway.
-        git_gate_plan = plan.git_gate_plan
-        if git_gate_plan.upstreams:
-            git_gate_plan = GitGate().provision_dynamic_keys(
-                plan.manifest.bottle, git_gate_plan, git_gate_state_dir(plan.slug),
+        # Step 1: agent image. Use a committed snapshot when one exists
+        # and is present in the local daemon; otherwise build from the
+        # Dockerfile. Sidecar images get built lazily by `docker compose
+        # up` via the renderer's `build:` directives.
+        committed = read_committed_image(plan.slug)
+        if committed and docker_mod.image_exists(committed):
+            info(f"using committed image {committed!r}")
+            plan = dataclasses.replace(
+                plan,
+                agent_provision=dataclasses.replace(plan.agent_provision, image=committed),
+            )
+        else:
+            docker_mod.build_image(
+                plan.image, _REPO_DIR,
+                dockerfile=plan.dockerfile_path,
             )
 
-        # 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,
-        )
-        teardown_timeout = resolve_teardown_timeout()
-        ctx = launch_consolidated(
-            plan.egress_plan, git_gate_plan, image_ref=plan.image, tokens=token_values,
-        )
-        stack.callback(
-            deprovision_consolidated, ctx.bottle_id,
-            orchestrator_url=ctx.orchestrator_url,
-            timeout=teardown_timeout,
+        internal_network = network_mod.network_name_for_slug(plan.slug)
+        egress_network = network_mod.network_egress_name_for_slug(plan.slug)
+
+        egress_ca_host, egress_ca_cert_only = egress_tls_init(
+            egress_state_dir(plan.slug),
         )
 
-        # Step 4: install the SHARED gateway CA into the agent (replaces the
-        # per-bottle CA) — read it out of the running gateway container
-        # (INFRA_NAME now aliases the gateway container name; the orchestrator,
-        # split into its own container, holds no CA).
-        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(name=INFRA_NAME).ca_cert_pem())
+        git_gate_plan = plan.git_gate_plan
+        if git_gate_plan.upstreams:
+            git_gate_plan = provision_git_gate_dynamic_keys(
+                plan.manifest.bottle,
+                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,
+            )
         egress_plan = dataclasses.replace(
             plan.egress_plan,
-            mitmproxy_ca_host_path=ca_file,
-            mitmproxy_ca_cert_only_host_path=ca_file,
-        )
-        # 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 ""
+            internal_network=internal_network,
+            egress_network=egress_network,
+            mitmproxy_ca_host_path=egress_ca_host,
+            mitmproxy_ca_cert_only_host_path=egress_ca_cert_only,
         )
+        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,
-            agent_git_gate_url=git_gate_url,
-            agent_supervise_url=supervise_url,
-            identity_token=ctx.identity_token,
-            env_var_secret=ctx.env_var_secret,
+            supervise_plan=supervise_plan,
         )
 
-        # Step 5: render + up the agent-only compose, pinned on the shared
-        # gateway network and proxied through the gateway's address.
+        # Step 6: render + write the compose file. metadata.json
+        # was written at prepare time and already carries
+        # compose_project; nothing to update here.
         state_dir = bottle_state_dir(plan.slug)
-        spec = consolidated_agent_compose(
-            plan, gateway_ip=ctx.gateway_ip, source_ip=ctx.source_ip, network=ctx.network,
-        )
+        spec = bottle_plan_to_compose(plan)
         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
-        # subprocess env as bare names so values never land in the file.
-        # ENV_VAR_SECRET follows the same pattern: bare name in the compose
-        # spec, value only in the subprocess env so it is never written to disk.
-        compose_env: dict[str, str] = {**os.environ, **plan.forwarded_env}
-        if plan.env_var_secret:
-            from ...orchestrator.store.secret_store import ENV_VAR_SECRET_NAME
-            compose_env[ENV_VAR_SECRET_NAME] = plan.env_var_secret
+
+        # Step 7: compose up. Token values + the OAuth placeholder
+        # flow through subprocess env; the compose file holds only
+        # 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}, agent on shared "
-            f"gateway {ctx.gateway_ip}, ip {ctx.source_ip})"
+            f"docker compose up -d  (project {project}, "
+            f"{len(spec['services'])} services)"
         )
         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 6: provision (CA install now uses the gateway CA) + yield.
+        # Step 8: provision. Create the bottle first so provisioners
+        # can use bottle.exec / bottle.cp_in; set the prompt path
+        # returned by provision_prompt after the fact.
         bottle = DockerBottle(
             plan.container_name,
             teardown,
@@ -224,24 +200,10 @@ 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()
-
-
-def stale_checks(plan: DockerBottlePlan) -> None:
-    """Raise StaleImageError if a cached image is older than the configured
-    threshold. Only runs when image_policy is 'cached'. Called by the backend
-    class's _image_stale_checks before _launch_impl starts any resources."""
-    if plan.spec.image_policy != "cached":
-        return
-    committed = read_committed_image(plan.slug)
-    if committed and docker_mod.image_exists(committed):
-        ts = docker_mod.image_created_at(committed)
-        if ts is not None:
-            check_stale(f"agent image {committed!r}", ts)
-        return
-    if docker_mod.image_exists(plan.image):
-        ts = docker_mod.image_created_at(plan.image)
-        if ts is not None:
-            check_stale(f"agent image {plan.image!r}", ts)

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 daemon has working DNS for upstream hostnames."""
+    so the egress sidecar has working DNS for upstream hostnames."""
     return _network_create_with_prefix(network_egress_name_for_slug(slug), internal=False)
 
 

bot_bottle/backend/docker/orchestrator.py

@@ -1,258 +0,0 @@
-"""The docker orchestrator (control plane) as a single, fixed-name container
-(PRD 0070).
-
-`DockerOrchestrator` is the docker implementation of the backend-neutral
-`Orchestrator` service. The lean control-plane container joins the `--internal`
-control network only (agents are never on it, so they have no L3 route to it)
-plus a host-loopback publish for the CLI. It is the sole opener of
-`bot-bottle.db` and the sole holder of the signing key (#469).
-"""
-
-from __future__ import annotations
-
-import os
-import time
-from pathlib import Path
-
-from ... import log
-from ... import resources
-from .util import run_docker
-from ...paths import (
-    ORCHESTRATOR_TOKEN_ENV,
-    bot_bottle_root,
-)
-from ...gateway import GatewayError
-from ...orchestrator.lifecycle import (
-    DEFAULT_PORT,
-    DEFAULT_STARTUP_TIMEOUT_SECONDS,
-    Orchestrator,
-    OrchestratorStartError,
-    source_hash,
-)
-
-# The control plane's own container + the dedicated `--internal` control network
-# the gateway reaches it over. The orchestrator + gateway join it, agents never
-# do, so agents have no route to the control plane (PRD 0070 "Separating the
-# planes"). Same name across docker + macOS.
-ORCHESTRATOR_NAME = "bot-bottle-orchestrator"
-ORCHESTRATOR_LABEL = "bot-bottle-orchestrator=1"
-ORCHESTRATOR_NETWORK = "bot-bottle-orchestrator"
-ORCHESTRATOR_IMAGE = os.environ.get(
-    "BOT_BOTTLE_ORCHESTRATOR_IMAGE", "bot-bottle-orchestrator:latest"
-)
-ORCHESTRATOR_DOCKERFILE = "Dockerfile.orchestrator"
-# Baked as a container label so `ensure_running` can detect whether the running
-# orchestrator image was built from the current source.
-ORCHESTRATOR_SOURCE_HASH_LABEL = "bot-bottle-orchestrator-source-hash"
-
-# Bot-bottle host-root bind-mount (DB + state) inside the orchestrator. The
-# control plane opens bot-bottle.db under here (via BOT_BOTTLE_ROOT ->
-# host_db_path()); it is the ONLY container with a handle on it (issue #469).
-_ROOT_IN_CONTAINER = "/bot-bottle-root"
-
-_HEALTH_POLL_SECONDS = 0.25
-
-
-class DockerOrchestrator(Orchestrator):
-    """The control plane as a single fixed-name container. `ensure_built` builds
-    it from `Dockerfile.orchestrator`; `ensure_running` starts it on the control
-    network + host loopback and blocks until `/health` answers."""
-
-    def __init__(
-        self,
-        image_ref: str = ORCHESTRATOR_IMAGE,
-        *,
-        name: str = ORCHESTRATOR_NAME,
-        label: str = ORCHESTRATOR_LABEL,
-        port: int = DEFAULT_PORT,
-        control_network: str = ORCHESTRATOR_NETWORK,
-        repo_root: Path | None = None,
-        host_root: Path | None = None,
-        root_mount_source: str | Path | None = None,
-        client_host: str | None = None,
-        client_network: str | None = None,
-        bind_host: str | None = None,
-        dockerfile: str | None = ORCHESTRATOR_DOCKERFILE,
-    ) -> None:
-        if host_root is not None and root_mount_source is not None:
-            raise ValueError("pass host_root or root_mount_source, not both")
-        self.image_ref = image_ref
-        self.name = name
-        self.label = label
-        self.port = port
-        self.control_network = control_network
-        # Build context: the repo root in a checkout, a staged copy from the
-        # installed wheel otherwise (bot_bottle.resources).
-        self._repo_root = repo_root if repo_root is not None else resources.build_root()
-        configured_root = os.environ.get("BOT_BOTTLE_DOCKER_ROOT_MOUNT", "").strip()
-        self._root_mount_source = str(
-            root_mount_source or configured_root or host_root or bot_bottle_root()
-        )
-        configured_network = os.environ.get(
-            "BOT_BOTTLE_DOCKER_CLIENT_NETWORK", ""
-        ).strip()
-        self._client_network = client_network or configured_network or None
-        configured_host = os.environ.get(
-            "BOT_BOTTLE_DOCKER_HOST_ADDRESS", ""
-        ).strip()
-        self._client_host = (
-            client_host or configured_host
-            or (self.name if self._client_network else "127.0.0.1")
-        )
-        # A socket-shared CI runner reaches published ports through its Docker
-        # network rather than its own loopback. Production stays bound to host
-        # loopback unless a caller explicitly selects another client.
-        self._bind_host = bind_host or (
-            "0.0.0.0"
-            if not self._client_network and self._client_host != "127.0.0.1"
-            else "127.0.0.1"
-        )
-        self._dockerfile = dockerfile
-
-    def url(self) -> str:
-        """Control-plane URL reachable by this Docker client."""
-        port = DEFAULT_PORT if self._client_network else self.port
-        return f"http://{self._client_host}:{port}"
-
-    def gateway_url(self) -> str:
-        """The URL the gateway's data plane resolves policy against — the
-        orchestrator container by name on the control network (docker DNS,
-        container↔container, no host firewall)."""
-        return f"http://{self.name}:{DEFAULT_PORT}"
-
-    def ensure_built(self) -> None:
-        """Build the control-plane image from its Dockerfile, cache-aware (a
-        no-op when nothing changed). No-op when no dockerfile is configured (a
-        pre-pulled image). BOT_BOTTLE_NO_CACHE forces a full rebuild."""
-        if self._dockerfile is None:
-            return
-        argv = ["docker", "build", "-t", self.image_ref,
-                "-f", str(self._repo_root / self._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"{self._dockerfile} build failed: {proc.stderr.strip()}")
-
-    def is_running(self) -> bool:
-        proc = run_docker([
-            "docker", "ps", "--filter", f"name=^/{self.name}$", "--format", "{{.Names}}",
-        ])
-        return self.name in proc.stdout.split()
-
-    def _source_current(self, current_hash: str) -> bool:
-        """True iff the running orchestrator image matches current source."""
-        if not self.is_running():
-            return False
-        proc = run_docker([
-            "docker", "inspect", "--format",
-            "{{ index .Config.Labels \"" + ORCHESTRATOR_SOURCE_HASH_LABEL + "\" }}",
-            self.name,
-        ])
-        if proc.returncode != 0:
-            return True  # can't compare → don't churn a working container
-        return proc.stdout.strip() == current_hash
-
-    def _ensure_control_network(self) -> None:
-        if run_docker(["docker", "network", "inspect", self.control_network]).returncode == 0:
-            return
-        proc = run_docker(["docker", "network", "create", "--internal", self.control_network])
-        if proc.returncode != 0 and "already exists" not in proc.stderr:
-            raise GatewayError(
-                f"control network {self.control_network} failed to create: "
-                f"{proc.stderr.strip()}"
-            )
-
-    def ensure_running(
-        self, *, startup_timeout: float = DEFAULT_STARTUP_TIMEOUT_SECONDS,
-    ) -> None:
-        """Ensure the control-plane container is up on current source; block
-        until healthy. Idempotent — a healthy orchestrator on current source is
-        left untouched (its in-memory egress tokens survive). Raises
-        `OrchestratorStartError` on startup timeout."""
-        current_hash = source_hash(self._repo_root)
-        if self.is_healthy() and self._source_current(current_hash):
-            return
-        log.info("starting orchestrator container", context={"name": self.name})
-        self._run_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
-            time.sleep(_HEALTH_POLL_SECONDS)
-        raise OrchestratorStartError(
-            f"orchestrator at {self.url()} did not become healthy "
-            f"within {startup_timeout:g}s"
-        )
-
-    def _run_container(self, current_hash: str) -> None:
-        """Start the lean control-plane container on the control network only,
-        published to host loopback for the CLI. Idempotent (clears a stale
-        fixed-name container first)."""
-        self._ensure_control_network()
-        run_docker(["docker", "rm", "--force", self.name])
-        # The signing key comes through the shared provisioning contract (#476),
-        # which fail-closes rather than yield an empty key that would run OPEN.
-        _signing_key = self.control_plane_key()
-        proc = run_docker([
-            "docker", "run", "--detach",
-            "--name", self.name,
-            "--label", self.label,
-            "--label", f"{ORCHESTRATOR_SOURCE_HASH_LABEL}={current_hash}",
-            # Control network only — agents are never on it, so they have no
-            # route to the control plane (the L3 block, not just the JWT).
-            "--network", self.control_network,
-            # Host CLI reaches the control plane here (loopback by default).
-            # Socket-shared CI joins the container directly to the job network;
-            # the host-side mapping remains loopback-only in that topology. The
-            # orchestrator listens on the fixed DEFAULT_PORT inside the
-            # container; self.port is the host-side published port.
-            "--publish", f"{self._bind_host}:{self.port}:{DEFAULT_PORT}",
-            # The image was rebuilt from `_repo_root` immediately before this
-            # launch. Running its baked package avoids a host-path bind mount,
-            # which is both more production-like and works with socket-shared
-            # CI where the daemon cannot see the job container's workspace.
-            # Orchestrator registry DB on the host (sole writer: control plane).
-            # `root_mount_source` may be a host path or a named Docker volume.
-            "--volume", f"{self._root_mount_source}:{_ROOT_IN_CONTAINER}",
-            "--env", f"BOT_BOTTLE_ROOT={_ROOT_IN_CONTAINER}",
-            # The signing key — held ONLY by the orchestrator (it verifies
-            # tokens); the gateway gets the pre-minted `gateway` JWT, never the
-            # key (issue #469). Bare `--env NAME` keeps the value off argv.
-            "--env", ORCHESTRATOR_TOKEN_ENV,
-            self.image_ref,
-            # Dockerfile.orchestrator ENTRYPOINT is `python3 -m bot_bottle.orchestrator`;
-            # these are its args.
-            "--host", "0.0.0.0", "--port", str(DEFAULT_PORT), "--broker", "stub",
-        ], env={**os.environ, ORCHESTRATOR_TOKEN_ENV: _signing_key})
-        if proc.returncode != 0:
-            raise OrchestratorStartError(
-                f"orchestrator container failed to start: {proc.stderr.strip()}"
-            )
-        if self._client_network:
-            proc = run_docker([
-                "docker", "network", "connect", self._client_network, self.name,
-            ])
-            if proc.returncode != 0:
-                raise OrchestratorStartError(
-                    f"orchestrator container failed to join client network "
-                    f"{self._client_network}: {proc.stderr.strip()}"
-                )
-
-    def stop(self) -> None:
-        """Remove the control-plane container (idempotent)."""
-        run_docker(["docker", "rm", "--force", self.name])
-
-
-__all__ = [
-    "DockerOrchestrator",
-    "ORCHESTRATOR_NAME",
-    "ORCHESTRATOR_LABEL",
-    "ORCHESTRATOR_NETWORK",
-    "ORCHESTRATOR_IMAGE",
-    "ORCHESTRATOR_DOCKERFILE",
-    "ORCHESTRATOR_SOURCE_HASH_LABEL",
-]

bot_bottle/backend/docker/provision/__init__.py

@@ -0,0 +1,12 @@
+"""Backend-infrastructure provisioners for the Docker backend.
+
+Per PRD 0050 the per-provider provisioning steps (prompt, skills,
+declarative provision-plan apply, supervise MCP registration) live on
+the `AgentProvider` plugin under `bot_bottle/contrib/`. CA and git
+provisioning also moved to the AgentProvider ABC (with Debian/node
+defaults); user plugins override them for non-standard images.
+
+No modules remain in this subpackage — the directory is kept so that
+existing imports of `from .provision import ...` don't need updating
+if new backend-specific provisioners are added later.
+"""

bot_bottle/backend/docker/resolve_plan.py

@@ -19,7 +19,7 @@ from ...env import ResolvedEnv
 from ...agent_provider import AgentProvisionPlan
 from ...egress import EgressPlan
 from ...manifest import Manifest
-from ...supervisor.plan import SupervisePlan
+from ...supervise import SupervisePlan
 from ...git_gate import GitGatePlan
 
 def preflight() -> None:

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 gateway
+host provisioning (no TAP pool / nft table) — networks and the sidecar
 bundle are created per-launch. So `setup()` is mostly an install/daemon
 pointer, and `status()` reports whether docker is usable.
 
@@ -27,14 +27,10 @@ def _docker_on_path() -> bool:
 def _daemon_reachable() -> bool:
     if not _docker_on_path():
         return False
-    try:
-        return subprocess.run(
-            ["docker", "info"],
-            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
-            check=False, timeout=5,
-        ).returncode == 0
-    except subprocess.TimeoutExpired:
-        return False
+    return subprocess.run(
+        ["docker", "info"],
+        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
+    ).returncode == 0
 
 
 def _print_install_pointer() -> None:
@@ -49,7 +45,7 @@ def setup() -> int:
         return 1
     sys.stderr.write(
         "Docker backend: no privileged host setup required — networks and "
-        "the gateway are created per-launch.\n"
+        "the sidecar bundle are created per-launch.\n"
     )
     if not _daemon_reachable():
         sys.stderr.write(
@@ -68,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 gateway are per-launch and are "
+        "state (networks and the sidecar bundle 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

@@ -0,0 +1,30 @@
+"""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/docker/util.py

@@ -1,39 +1,16 @@
-"""Docker host-side primitives used by DockerBottleBackend: the lean
-`run_docker` subprocess wrapper, probing for docker on PATH, slugifying agent
-names, checking image/container existence, and building images."""
+"""Docker host-side primitives used by DockerBottleBackend: probing
+for docker on PATH, slugifying agent names, checking image/container
+existence, and building images."""
 
 from __future__ import annotations
 
-import os
-from datetime import datetime, timezone
+import re
 import shutil
 import subprocess
-from typing import Iterator
+from typing import Iterable, Iterator
 
 from ...log import die, info
-from ...util import slugify as _slugify
-
-
-def slugify(name: str) -> str:
-    """Compatibility wrapper; new generic callers import ``bot_bottle.util``."""
-    return _slugify(name)
-
-
-def run_docker(
-    argv: list[str], *, env: dict[str, str] | None = None,
-) -> 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).
-
-    `env` sets the child process environment — used to hand a secret to a bare
-    `--env NAME` flag (docker inherits its value from this process) so the value
-    never lands on argv or in `docker inspect`'s recorded command line."""
-    return subprocess.run(
-        argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
-        check=False, env=env,
-    )
+# from ...workspace import WorkspacePlan
 
 
 # Cap on the suffix the container-name conflict logic will try before
@@ -53,7 +30,12 @@ def container_name_candidates(base: str) -> Iterator[str]:
 def runsc_available() -> bool:
     """Return True if the Docker daemon has the gVisor (`runsc`) runtime
     registered. Called once per prepare; the result lives on the plan."""
-    r = run_docker(["docker", "info", "--format", "{{json .Runtimes}}"])
+    r = subprocess.run(
+        ["docker", "info", "--format", "{{json .Runtimes}}"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
     return r.returncode == 0 and "runsc" in r.stdout
 
 
@@ -67,15 +49,20 @@ def require_docker() -> None:
 
 
 def image_exists(ref: str) -> bool:
-    return run_docker(["docker", "image", "inspect", ref]).returncode == 0
+    return _silent_run(["docker", "image", "inspect", ref]) == 0
 
 
 def container_exists(name: str) -> bool:
     """Returns True if a container (running or stopped) with the given
     name exists. Uses `docker ps -a -q -f name=^<name>$` so substring
     matches don't false-positive."""
-    result = run_docker(["docker", "ps", "-a", "-q", "-f", f"name=^{name}$"])
-    return result.returncode == 0 and bool(result.stdout.strip())
+    result = subprocess.run(
+        ["docker", "ps", "-a", "-q", "-f", f"name=^{name}$"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return bool(result.stdout.strip())
 
 
 def force_remove_container(name: str) -> None:
@@ -83,7 +70,12 @@ def force_remove_container(name: str) -> None:
     doesn't — and the rm itself is best-effort (errors swallowed) so
     this is safe to register as a teardown callback."""
     if container_exists(name):
-        run_docker(["docker", "rm", "-f", name])
+        subprocess.run(
+            ["docker", "rm", "-f", name],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+        )
 
 
 def docker_exec_root(container: str, argv: list[str]) -> None:
@@ -96,27 +88,17 @@ def docker_exec_root(container: str, argv: list[str]) -> None:
     )
 
 
-def docker_exec(container: str, argv: list[str], *, user: str = "") -> None:
-    """Run `docker exec` in the named container, dying with the
-    command's own stderr on failure. Pass `user=\"0\"` to run as root."""
-    cmd = ["docker", "exec"]
-    if user:
-        cmd += ["-u", user]
-    cmd += [container, *argv]
-    result = run_docker(cmd)
-    if result.returncode != 0:
-        die(
-            f"docker exec in {container} failed: "
-            f"{(result.stderr or '').strip() or '<no stderr>'}"
-        )
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
 
 
-def docker_cp(src: str, dest: str) -> None:
-    """Run `docker cp`, dying with the command's own stderr on failure."""
-    result = run_docker(["docker", "cp", src, dest])
-    if result.returncode != 0:
-        die(f"docker cp {src} -> {dest} failed: "
-            f"{(result.stderr or '').strip() or '<no stderr>'}")
+def slugify(name: str) -> str:
+    """Lowercase, non-alnum runs → '-', trimmed. Dies on empty result."""
+    if not name:
+        die("slugify: missing name")
+    slug = _SLUG_RE.sub("-", name.lower()).strip("-")
+    if not slug:
+        die(f"name '{name}' produced an empty slug; use alphanumeric characters")
+    return slug
 
 
 def build_image(ref: str, context: str, *, dockerfile: str = "") -> None:
@@ -126,40 +108,15 @@ def build_image(ref: str, context: str, *, dockerfile: str = "") -> None:
 
     `dockerfile` is an optional path (relative to `context`, or
     absolute) for callers that need to build from a non-default
-    Dockerfile in the same context — e.g. `Dockerfile.git-gate`.
-
-    Set `BOT_BOTTLE_NO_CACHE=1` (the `start --no-cache` flag) to force
-    `--no-cache`. The npm/curl installers some provider Dockerfiles
-    shell out to can silently no-op on a transient network failure —
-    e.g. an `optionalDependencies` fetch for a platform-native binary —
-    and Docker will then cache that broken layer indefinitely."""
+    Dockerfile in the same context — e.g. `Dockerfile.git-gate`."""
     info(f"building image {ref} from {context} (layer cache keeps repeat builds fast)")
     args = ["docker", "build", "-t", ref]
-    if os.environ.get("BOT_BOTTLE_NO_CACHE") == "1":
-        args.append("--no-cache")
     if dockerfile:
         args.extend(["-f", dockerfile])
     args.append(context)
     subprocess.run(args, check=True)
 
 
-def verify_agent_image(image: str, argv: tuple[str, ...]) -> None:
-    """Run `argv` inside a throwaway container of a freshly built agent
-    image and die loudly if it fails, instead of shipping an image
-    whose CLI only breaks at first real use. No-op when the provider
-    hasn't declared a smoke test (`AgentProviderRuntime.smoke_test`)."""
-    if not argv:
-        return
-    result = run_docker(["docker", "run", "--rm", "--entrypoint", argv[0], image, *argv[1:]])
-    if result.returncode != 0:
-        detail = (result.stderr or result.stdout or "").strip()
-        die(
-            f"agent image {image!r} failed its post-build smoke test "
-            f"({' '.join(argv)}): {detail}\n"
-            f"Try rebuilding from scratch: bot-bottle start --no-cache"
-        )
-
-
 # def build_image_with_cwd(
 #     derived: str,
 #     base: str,
@@ -198,7 +155,10 @@ def verify_agent_image(image: str, argv: tuple[str, ...]) -> None:
 def commit_container(container_name: str, image_tag: str) -> None:
     """Run `docker commit <container_name> <image_tag>` to snapshot the
     running container's filesystem state as a local Docker image."""
-    result = run_docker(["docker", "commit", container_name, image_tag])
+    result = subprocess.run(
+        ["docker", "commit", container_name, image_tag],
+        capture_output=True, text=True, check=False,
+    )
     if result.returncode != 0:
         die(
             f"docker commit {container_name!r} → {image_tag!r} failed: "
@@ -207,44 +167,10 @@ def commit_container(container_name: str, image_tag: str) -> None:
     info(f"committed {container_name!r} → {image_tag!r}")
 
 
-def image_created_at(ref: str) -> datetime | None:
-    """Return Docker's image Created timestamp as an aware UTC datetime, or
-    None when the field is absent or unparseable. Callers should skip the
-    stale check when None is returned."""
-    r = subprocess.run(
-        ["docker", "image", "inspect", "--format", "{{.Created}}", ref],
-        capture_output=True,
-        text=True,
+def _silent_run(cmd: Iterable[str]) -> int:
+    return subprocess.run(
+        list(cmd),
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
         check=False,
-    )
-    if r.returncode != 0:
-        die(
-            f"docker image inspect for {ref!r} failed: "
-            f"{(r.stderr or '').strip() or '<no stderr>'}"
-        )
-    raw = r.stdout.strip()
-    if not raw:
-        return None
-    try:
-        return _parse_docker_timestamp(raw)
-    except ValueError:
-        return None
-
-
-def _parse_docker_timestamp(raw: str) -> datetime:
-    text = raw.strip()
-    if text.endswith("Z"):
-        text = text[:-1] + "+00:00"
-    dot = text.find(".")
-    if dot != -1:
-        tz_plus = text.find("+", dot)
-        tz_minus = text.find("-", dot)
-        tz_candidates = [pos for pos in (tz_plus, tz_minus) if pos != -1]
-        if tz_candidates:
-            tz_pos = min(tz_candidates)
-            frac = text[dot + 1:tz_pos]
-            text = text[:dot + 1] + frac[:6].ljust(6, "0") + text[tz_pos:]
-    dt = datetime.fromisoformat(text)
-    if dt.tzinfo is None:
-        dt = dt.replace(tzinfo=timezone.utc)
-    return dt.astimezone(timezone.utc)
+    ).returncode

bot_bottle/backend/egress_apply.py

@@ -11,8 +11,7 @@ from pathlib import Path
 
 from ..bottle_state import egress_state_dir
 from ..egress import EGRESS_ROUTES_FILENAME
-from ..gateway.egress.schema import load_config
-from ..gateway.egress.types import LOG_OFF
+from ..egress_addon_core import LOG_OFF, load_config
 
 
 class EgressApplyError(RuntimeError):

bot_bottle/backend/firecracker/__init__.py

@@ -1,25 +1,7 @@
-"""Firecracker backend: Linux KVM microVM isolation (issue #342).
-
-Thin by design: `FirecrackerBottleBackend` is re-exported lazily via
-`__getattr__`, so importing a leaf module under this package doesn't drag the
-backend (and the framework it pulls) into memory.
-"""
+"""Firecracker backend: Linux KVM microVM isolation (issue #342)."""
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from .backend import FirecrackerBottleBackend
-
-
-def __getattr__(name: str) -> Any:
-    if name == "FirecrackerBottleBackend":
-        from .backend import FirecrackerBottleBackend
-
-        globals()[name] = FirecrackerBottleBackend
-        return FirecrackerBottleBackend
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-
+from .backend import FirecrackerBottleBackend
 
 __all__ = ["FirecrackerBottleBackend"]

bot_bottle/backend/firecracker/backend.py

@@ -8,8 +8,7 @@ fail-closed nftables egress boundary. Selected by
 
 from __future__ import annotations
 
-import io
-from contextlib import contextmanager, redirect_stderr
+from contextlib import contextmanager
 from pathlib import Path
 from typing import Generator, Sequence
 
@@ -18,8 +17,8 @@ from ...egress import EgressPlan
 from ...env import ResolvedEnv
 from ...git_gate import GitGatePlan
 from ...manifest import Manifest
-from ...supervisor.plan import SupervisePlan
-from .. import ActiveAgent, BottleBackend, BottleImages, BottleSpec
+from ...supervise import SupervisePlan
+from .. import ActiveAgent, BottleBackend, BottleSpec
 from . import cleanup as _cleanup
 from . import enumerate as _enumerate
 from . import launch as _launch
@@ -53,11 +52,8 @@ class FirecrackerBottleBackend(
         return _setup.setup()
 
     @classmethod
-    def status(cls, *, quiet: bool = False) -> int:
+    def status(cls) -> int:
         from . import setup as _setup
-        if quiet:
-            with redirect_stderr(io.StringIO()):
-                return _setup.status()
         return _setup.status()
 
     @classmethod
@@ -96,18 +92,11 @@ class FirecrackerBottleBackend(
             stage_dir=stage_dir,
         )
 
-    def _build_or_load_images(self, plan: FirecrackerBottlePlan) -> BottleImages:
-        return BottleImages(agent=_launch.build_or_load_agent_base(plan))
-
-    def prelaunch_checks(self, plan: FirecrackerBottlePlan) -> None:
-        _launch.stale_checks(plan)
-
     @contextmanager
-    def _launch_impl(
-        self, plan: FirecrackerBottlePlan, images: BottleImages,
+    def launch(
+        self, plan: FirecrackerBottlePlan
     ) -> Generator[FirecrackerBottle, None, None]:
-        assert isinstance(images.agent, Path)
-        with _launch.launch(plan, images.agent, provision=self.provision) as bottle:
+        with _launch.launch(plan, provision=self.provision) as bottle:
             yield bottle
 
     def prepare_cleanup(self) -> FirecrackerBottleCleanupPlan:
@@ -121,7 +110,3 @@ class FirecrackerBottleBackend(
 
     def supervise_mcp_url(self, plan: FirecrackerBottlePlan) -> str:
         return plan.agent_supervise_url
-
-    def ensure_orchestrator(self) -> str:
-        from .infra import FirecrackerInfraService
-        return FirecrackerInfraService().ensure_running()

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 gateway, CA paths, …) set
+PATH and the bottle env (HTTPS_PROXY at the sidecar, 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).
 """
@@ -105,9 +105,10 @@ class FirecrackerBottle(Bottle):
         # root-owned and unreadable by node, which breaks Node's
         # process.cwd(), the shell-snapshot machinery, and `/doctor`.
         # Use `env --chdir` rather than a `sh -c 'cd … && exec "$@"'`
-        # wrapper: it keeps the guest command a flat argv that `agent_argv`
-        # can quote token-by-token for the ssh→guest-shell round trip,
-        # avoiding a fragile nested-quoting `"$@"` script.
+        # wrapper: ssh space-joins everything after the host into one
+        # string for the guest shell, so a quoted script + $@ would be
+        # re-split and mangled (exec'ing the $0 placeholder). All-simple
+        # words survive that join.
         workdir = self.agent_workdir or _HOME_FOR["node"]
         remote = ["runuser", "-u", "node", "--",
                   "env", f"--chdir={workdir}",
@@ -116,15 +117,7 @@ class FirecrackerBottle(Bottle):
         return remote
 
     def agent_argv(self, argv: list[str], *, tty: bool = True) -> list[str]:
-        # ssh space-joins everything after the host into one line the guest
-        # shell re-parses, so pre-quote each remote token for that shell.
-        # Simple words are unchanged (existing behaviour); an arg containing
-        # spaces — e.g. codex's `read_prompt_file` positional "Read and follow
-        # the instructions in <path>." — is quoted so it survives as ONE
-        # argument instead of being re-split (which made codex parse "and" as
-        # a subcommand).
-        remote = self._agent_remote_argv(argv)
-        return [*self._ssh(tty=tty), "--", *(shlex.quote(t) for t in remote)]
+        return [*self._ssh(tty=tty), "--", *self._agent_remote_argv(argv)]
 
     def exec_agent(self, argv: list[str], *, tty: bool = True) -> int:
         agent_argv = self.agent_argv(argv, tty=tty)

bot_bottle/backend/firecracker/bottle_cleanup_plan.py

@@ -10,9 +10,10 @@ from .. import BottleCleanupPlan
 
 @dataclass(frozen=True)
 class FirecrackerBottleCleanupPlan(BottleCleanupPlan):
-    # PIDs of orphaned firecracker VMM processes and the per-bottle run
-    # dirs left behind by previous bottles.
+    # PIDs of orphaned firecracker VMM processes and the sidecar
+    # containers left behind by previous bottles.
     vm_pids: tuple[int, ...] = ()
+    containers: tuple[str, ...] = ()
     run_dirs: tuple[str, ...] = ()
 
     def print(self) -> None:
@@ -21,9 +22,11 @@ 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.run_dirs)
+        return not (self.vm_pids or self.containers or self.run_dirs)

bot_bottle/backend/firecracker/bottle_plan.py

@@ -13,22 +13,15 @@ from .. import BottlePlan
 class FirecrackerBottlePlan(BottlePlan):
     slug: str
     forwarded_env: dict[str, str] = field(repr=False)
-    # Stamped by launch once the gateway is up and its ports are
+    # Stamped by launch once the sidecar 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 = ""
     agent_supervise_url: str = ""
-    # Per-bottle identity token the agent presents on every attributed request
-    # (egress proxy credentials, git-gate/supervise headers); set by launch
-    # from the orchestrator registration. Empty pre-registration.
-    identity_token: str = ""
-    # Applied to every agent SSH exec and mirrored into /run inside the VM so
-    # the host can recover it after the infra VM restarts.
-    env_var_secret: str = ""
 
     @property
     def container_name(self) -> str:
-        """Instance name, reused for the gateway container + VM run dir.
+        """Instance name, reused for the sidecar 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,23 +1,9 @@
 """Cleanup for the Firecracker backend.
 
-Reaps *orphans* only — resources with no live VM behind them:
-
-  * orphan run dirs: a per-bottle run dir (holding the ~1G rootfs.ext4)
-    whose firecracker process has exited. These leak when a launch is
-    hard-killed before its teardown runs (host OOM/crash, a cancelled CI
-    job, `kill -9`); the clean-exit path already removes its own dir in
-    launch.py.
-  * orphan VM pids: a firecracker process whose run dir is already gone
-    — a VMM left lingering after its dir was removed.
-
-A run dir with a *live* firecracker process is a running bottle and is
-left strictly alone: it is neither killed nor removed. (The backend's
-`enumerate_active` registry is still a stub — #354 — so a live process
-is the only reliable "this bottle is in use" signal we have. Once the
-registry lands, registry-orphaned-but-running VMs can be reaped too.)
-
-TAP slots free themselves (the flock drops when the launcher exits), so
-there is nothing to reclaim there.
+Orphans are: firecracker VMM processes whose config lives under our run
+dir, the `bot-bottle-sidecars-*` containers, and the per-bottle run
+dirs. TAP slots free themselves (the flock drops when the launcher
+exits), so there is nothing to reclaim there.
 """
 
 from __future__ import annotations
@@ -32,84 +18,57 @@ 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"
 
 
-def _run_dir_of(cmd: str, run_root: Path) -> Path | None:
-    """The bottle run dir a firecracker cmdline belongs to, or None.
-
-    A bottle VM is launched with `--config-file <run_root>/<slug>/config.json`,
-    so the run dir is the config file's parent when it sits directly under
-    the run root. Anything else (a builder VM, the infra VM elsewhere) is
-    not ours to reap here.
-    """
-    toks = cmd.split()
-    for i, tok in enumerate(toks):
-        if tok == "--config-file" and i + 1 < len(toks):
-            parent = Path(toks[i + 1]).parent
-            if parent.parent == run_root:
-                return parent
-    return None
-
-
-def _scan_processes(run_root: Path) -> tuple[set[str], list[int]]:
-    """Inspect running firecracker VMs under ``run_root``.
-
-    Returns ``(live_run_dirs, orphan_pids)``:
-      * ``live_run_dirs`` — run dirs backed by a running VM (never reaped);
-      * ``orphan_pids`` — firecracker pids whose run dir no longer exists
-        (a lingering VMM to kill).
-    """
+def _orphan_vm_pids() -> list[int]:
+    """firecracker processes whose --config-file is under our run dir."""
+    run_root = str(_run_root())
     result = subprocess.run(
         ["pgrep", "-a", "firecracker"],
         capture_output=True, text=True, check=False,
     )
     if result.returncode != 0:
-        return set(), []
-    live: set[str] = set()
-    orphan_pids: list[int] = []
+        return []
+    pids: list[int] = []
     for line in result.stdout.splitlines():
         parts = line.split(None, 1)
-        if len(parts) != 2:
+        if len(parts) != 2 or run_root not in parts[1]:
             continue
         try:
-            pid = int(parts[0])
+            pids.append(int(parts[0]))
         except ValueError:
             continue
-        run_dir = _run_dir_of(parts[1], run_root)
-        if run_dir is None:
-            continue
-        if run_dir.is_dir():
-            live.add(str(run_dir))
-        else:
-            orphan_pids.append(pid)
-    return live, orphan_pids
+    return pids
 
 
-def live_run_dirs() -> tuple[Path, ...]:
-    """Run directories backed by currently running agent microVMs."""
-    live, _ = _scan_processes(_run_root())
-    return tuple(Path(path) for path in sorted(live))
+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 _orphan_run_dirs(run_root: Path, live: set[str]) -> list[str]:
-    """Run dirs with no live VM behind them — the leaked ones to remove."""
+def _run_dirs() -> list[str]:
+    run_root = _run_root()
     if not run_root.is_dir():
         return []
-    return sorted(
-        str(p) for p in run_root.iterdir()
-        if p.is_dir() and str(p) not in live
-    )
+    return sorted(str(p) for p in run_root.iterdir() if p.is_dir())
 
 
 def prepare_cleanup() -> FirecrackerBottleCleanupPlan:
-    run_root = _run_root()
-    live, orphan_pids = _scan_processes(run_root)
     return FirecrackerBottleCleanupPlan(
-        vm_pids=tuple(orphan_pids),
-        run_dirs=tuple(_orphan_run_dirs(run_root, live)),
+        vm_pids=tuple(_orphan_vm_pids()),
+        containers=tuple(_sidecar_containers()),
+        run_dirs=tuple(_run_dirs()),
     )
 
 
@@ -120,6 +79,12 @@ 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/consolidated_launch.py

@@ -1,167 +0,0 @@
-"""Consolidated bottle launch sequence for the Firecracker backend
-(PRD 0070, Stage B).
-
-The orchestrator control plane and the shared gateway run in **two** persistent
-per-host **infra VMs** (`infra_vm.py`), split per PRD 0070 — not Docker
-containers. Agent VMs reach the gateway's egress / supervise / git-http ports
-via a PREROUTING DNAT on their own host-side TAP IP that redirects to the
-**gateway** VM (see `scripts/firecracker-netpool.sh`) — never the orchestrator,
-so a breached agent has no L3 route to the control plane. The host CLI reaches
-the control plane over HTTP at the orchestrator VM's guest IP.
-
-Attribution is by the agent VM's guest IP, unspoofable by construction: the
-/31 point-to-point TAP + the `bot_bottle_fc` nft table ensure only the
-expected VM can source-IP that address.
-
-Sequence:
-  1. ensure the infra VMs (orchestrator control plane + gateway data plane)
-     are up (a singleton pair — a prior launcher may already have booted them);
-  2. register the bottle on the orchestrator by its guest IP (attribution key)
-     → bottle id + identity token;
-  3. provision its git-gate repos/creds into the gateway VM (over SSH);
-  4. fetch the shared gateway CA for the provisioner to install in the rootfs.
-
-The TAP slot allocation, rootfs build, and VM boot are the caller's job.
-"""
-
-from __future__ import annotations
-
-import json
-import subprocess
-from dataclasses import dataclass
-from pathlib import Path
-
-from ...egress import EgressPlan
-from ...git_gate import GitGatePlan
-from ...log import info
-from ...orchestrator.client import OrchestratorClient, OrchestratorClientError
-from ...orchestrator.lifecycle import (
-    OrchestratorStartError,  # re-exported so callers can catch it
-)
-from ...orchestrator.reprovision import reprovision_bottles
-from ...orchestrator.store.secret_store import ENV_VAR_SECRET_NAME
-from ..provision_bottle import deprovision_bottle, provision_bottle
-from . import cleanup, util
-from .gateway import FirecrackerGateway
-from .infra import FirecrackerInfraService
-
-_ENV_VAR_SECRET_PATH = "/run/bot-bottle/env-var-secret"
-
-
-class ConsolidatedLaunchError(RuntimeError):
-    """The consolidated register/provision sequence could not complete."""
-
-
-@dataclass(frozen=True)
-class LaunchContext:
-    """What the Firecracker launch needs from the consolidated sequence."""
-
-    bottle_id: str
-    identity_token: str
-    source_ip: str          # the VM's guest IP — the attribution key
-    gateway_ca_pem: str     # the shared gateway CA the provisioner installs
-    orchestrator_url: str
-    env_var_secret: str = ""  # encryption key injected into the agent's env
-
-
-def _guest_ip_from_config(config_path: Path) -> str:
-    """Read the kernel's configured guest IP from a Firecracker config."""
-    try:
-        config = json.loads(config_path.read_text())
-        args = config["boot-source"]["boot_args"]
-        ip_arg = next(part for part in args.split() if part.startswith("ip="))
-        return ip_arg.removeprefix("ip=").split(":", 1)[0]
-    except (OSError, ValueError, KeyError, TypeError, StopIteration):
-        return ""
-
-
-def persist_env_var_secret(private_key: Path, guest_ip: str, secret: str) -> None:
-    """Mirror the exec-time key into guest tmpfs for restart recovery."""
-    proc = subprocess.run(
-        util.ssh_base_argv(private_key, guest_ip)
-        + [f"umask 077; mkdir -p /run/bot-bottle; cat > {_ENV_VAR_SECRET_PATH}"],
-        input=secret, capture_output=True, text=True, check=False,
-    )
-    if proc.returncode != 0:
-        raise ConsolidatedLaunchError(
-            f"failed to persist {ENV_VAR_SECRET_NAME} in agent VM: "
-            f"{proc.stderr.strip() or '<no stderr>'}"
-        )
-
-
-def _reprovision_running_bottles(client: OrchestratorClient) -> None:
-    """Read keys from live agent VMs and restore the restarted gateway."""
-    try:
-        secrets_by_ip: dict[str, str] = {}
-        for run_dir in cleanup.live_run_dirs():
-            guest_ip = _guest_ip_from_config(run_dir / "config.json")
-            private_key = run_dir / "bottle_id_ed25519"
-            if not guest_ip or not private_key.is_file():
-                continue
-            proc = subprocess.run(
-                util.ssh_base_argv(private_key, guest_ip)
-                + [f"cat {_ENV_VAR_SECRET_PATH}"],
-                capture_output=True, text=True, check=False,
-            )
-            if proc.returncode == 0 and proc.stdout.strip():
-                secrets_by_ip[guest_ip] = proc.stdout.strip()
-        count = reprovision_bottles(client, secrets_by_ip)
-        if count:
-            info(f"reprovisioned egress tokens for {count} Firecracker bottle(s)")
-    except (OSError, OrchestratorClientError) as exc:
-        info(f"egress token reprovision skipped: {exc}")
-
-
-def launch_consolidated(
-    egress_plan: EgressPlan,
-    git_gate_plan: GitGatePlan,
-    *,
-    guest_ip: str,
-    image_ref: str = "",
-    tokens: dict[str, str] | None = None,
-) -> LaunchContext:
-    """Ensure the infra VM is up, register the bottle by its guest IP, and
-    provision its git-gate state into the gateway VM. Returns the context the
-    agent-VM launch needs. Raises on failure — the caller tears down."""
-    service = FirecrackerInfraService()
-    url = service.ensure_running()
-    client = OrchestratorClient(url)
-    _reprovision_running_bottles(client)
-
-    # Read the gateway's provisioning transport + CA off the Gateway service.
-    gateway = service.gateway()
-    transport = gateway.provisioning_transport()
-    reg = provision_bottle(
-        client, guest_ip, egress_plan, git_gate_plan, transport,
-        image_ref=image_ref, tokens=tokens,
-    )
-    # The shared gateway CA every agent on this host trusts for TLS
-    # interception — fetched from the gateway VM over SSH.
-    return LaunchContext(
-        bottle_id=reg.bottle_id,
-        identity_token=reg.identity_token,
-        source_ip=guest_ip,
-        gateway_ca_pem=gateway.ca_cert_pem(),
-        orchestrator_url=url,
-        env_var_secret=reg.env_var_secret,
-    )
-
-
-def deprovision_consolidated(
-    bottle_id: str, *, orchestrator_url: str, timeout: float | None = None,
-) -> None:
-    """Deregister the bottle and remove its git-gate state from the gateway
-    VM. Both steps are idempotent so this is safe from a cleanup trap. Does
-    NOT stop the infra VMs — they're persistent per-host singletons shared by
-    every bottle."""
-    deprovision_bottle(bottle_id, FirecrackerGateway().provisioning_transport(),
-                   orchestrator_url=orchestrator_url, timeout=timeout)
-
-
-__all__ = [
-    "LaunchContext",
-    "launch_consolidated",
-    "deprovision_consolidated",
-    "ConsolidatedLaunchError",
-    "OrchestratorStartError",
-]

bot_bottle/backend/firecracker/enumerate.py

@@ -1,14 +1,43 @@
 """Active-agent enumeration for the Firecracker backend.
 
-The backend is disabled during the companion-container removal (#385) — it can't
-launch bottles, so there are none to enumerate. Real enumeration returns
-with the backend's consolidated relaunch (#354).
+The agent runs in a VM (no container to list), so a live bottle is
+identified by its running sidecar container `bot-bottle-sidecars-<slug>`
+— the same discovery-by-prefix the other backends use.
 """
 
 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]:
-    return []
+    result = subprocess.run(
+        ["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/firecracker_vm.py

@@ -60,18 +60,12 @@ class VmHandle:
             self.process.wait(timeout=5)
 
 
-def _boot_args(
-    guest_ip: str, host_ip: str, pubkey: str, extra: str = "",
-) -> str:
+def _boot_args(guest_ip: str, host_ip: str, pubkey: str) -> str:
     # ip=<client>::<gw>:<netmask>::<dev>:off — /31 point-to-point link,
     # so netmask is 255.255.255.254 and the gateway is the host TAP IP.
     ip_arg = f"ip={guest_ip}::{host_ip}:255.255.255.254::eth0:off"
     pub_b64 = base64.b64encode(pubkey.encode()).decode()
-    args = f"{_BASE_BOOT_ARGS} {ip_arg} bb_pubkey={pub_b64}"
-    # `extra` carries caller-supplied cmdline params the guest init reads
-    # (e.g. the gateway VM's `bb_orch=<orchestrator guest IP>`). Agent VMs pass
-    # nothing.
-    return f"{args} {extra}".rstrip() if extra else args
+    return f"{_BASE_BOOT_ARGS} {ip_arg} bb_pubkey={pub_b64}"
 
 
 def _config(
@@ -84,33 +78,20 @@ def _config(
     vcpus: int,
     mem_mib: int,
     guest_mac: str,
-    data_drive: Path | None = None,
-    extra_boot_args: str = "",
 ) -> dict[str, object]:
-    drives: list[dict[str, object]] = [
-        {
-            "drive_id": "rootfs",
-            "path_on_host": str(rootfs),
-            "is_root_device": True,
-            "is_read_only": False,
-        }
-    ]
-    # A second virtio-block device (guest /dev/vdb) — the infra VM's
-    # persistent registry "volume", a host-side ext4 file that outlives the
-    # ephemeral rootfs across VM restarts.
-    if data_drive is not None:
-        drives.append({
-            "drive_id": "data",
-            "path_on_host": str(data_drive),
-            "is_root_device": False,
-            "is_read_only": False,
-        })
     return {
         "boot-source": {
             "kernel_image_path": str(util.kernel_path()),
-            "boot_args": _boot_args(guest_ip, host_ip, pubkey, extra_boot_args),
+            "boot_args": _boot_args(guest_ip, host_ip, pubkey),
         },
-        "drives": drives,
+        "drives": [
+            {
+                "drive_id": "rootfs",
+                "path_on_host": str(rootfs),
+                "is_root_device": True,
+                "is_read_only": False,
+            }
+        ],
         "network-interfaces": [
             {
                 "iface_id": "eth0",
@@ -137,17 +118,9 @@ def boot(
     vcpus: int = 2,
     mem_mib: int = 2048,
     guest_mac: str = "06:00:AC:10:00:02",
-    detached: bool = False,
-    data_drive: Path | None = None,
-    extra_boot_args: str = "",
 ) -> VmHandle:
     """Write the config and launch the VMM. Returns once the process is
-    spawned; callers wait for SSH readiness separately.
-
-    `detached` starts the VMM in its own session (`start_new_session`) so it
-    survives the launcher exiting — used for the persistent per-host infra
-    VM, which must outlive the short-lived `start` process (agent VMs stay
-    attached and are torn down with the launcher)."""
+    spawned; callers wait for SSH readiness separately."""
     run_dir.mkdir(parents=True, exist_ok=True)
     config_path = run_dir / "config.json"
     console_log = run_dir / "console.log"
@@ -155,7 +128,6 @@ def boot(
         _config(
             rootfs=rootfs, tap=tap, guest_ip=guest_ip, host_ip=host_ip,
             pubkey=pubkey, vcpus=vcpus, mem_mib=mem_mib, guest_mac=guest_mac,
-            data_drive=data_drive, extra_boot_args=extra_boot_args,
         ),
         indent=2,
     ))
@@ -165,7 +137,6 @@ def boot(
     process = subprocess.Popen(
         ["firecracker", "--no-api", "--config-file", str(config_path)],
         stdout=log_fh, stderr=subprocess.STDOUT, stdin=subprocess.DEVNULL,
-        start_new_session=detached,
     )
     return VmHandle(process=process, guest_ip=guest_ip, console_log=console_log)
 

bot_bottle/backend/firecracker/freezer.py

@@ -1,12 +1,9 @@
-"""FirecrackerFreezer — snapshot a running microVM to a rootfs tar.
+"""FirecrackerFreezer — snapshot a running microVM to a Docker image.
 
 The VM is live and can't be block-copied safely, so — like the macOS
 backend — we stream the guest root filesystem out over the control
-channel (SSH here). Unlike the other backends this needs no Docker: the
-tar *is* the resumable artifact. `resume` extracts it and rebuilds a
-fresh per-bottle ext4 with `mke2fs -d` (see `util.build_committed_rootfs_dir`
-and `launch.build_or_load_agent_base`). The bottle keeps running after the
-snapshot.
+channel (SSH here) and rebuild an image from it. The bottle keeps
+running after the snapshot.
 """
 
 from __future__ import annotations
@@ -14,9 +11,9 @@ from __future__ import annotations
 import json
 import os
 import subprocess
+import tempfile
 from pathlib import Path
 
-from ...bottle_state import committed_rootfs_path
 from ...log import die, info
 from .. import ActiveAgent
 from ..freeze import Freezer
@@ -33,13 +30,14 @@ class FirecrackerFreezer(Freezer):
         if not private_key.is_file() or not guest_ip:
             die(f"cannot freeze {agent.slug}: run dir {run_dir} is missing the "
                 f"SSH key or VM config (is the bottle still running?)")
-        tar_path = committed_rootfs_path(agent.slug)
-        _commit_rootfs_via_ssh(private_key, guest_ip, tar_path)
-        info(f"committed {agent.slug} -> {tar_path}")
-        return str(tar_path)
+        image_tag = f"bot-bottle-committed-{agent.slug}:latest"
+        _commit_via_ssh(private_key, guest_ip, image_tag)
+        info(f"committed {agent.slug} -> {image_tag!r}")
+        return image_tag
 
     def _export_hint(self, slug: str, image_ref: str) -> None:
-        info(f"to export for migration:      cp {image_ref} {slug}.tar")
+        info(f"to export for migration:      docker image save {image_ref} "
+             f"-o {slug}.tar")
 
 
 def _guest_ip_from_config(config_path: Path) -> str:
@@ -55,36 +53,24 @@ def _guest_ip_from_config(config_path: Path) -> str:
     return ""
 
 
-def _commit_rootfs_via_ssh(private_key: Path, guest_ip: str, tar_path: Path) -> None:
-    """Stream the guest rootfs out over SSH into `tar_path`. Excludes the
-    virtual/live mounts (proc/sys/dev/run) — resume recreates those empty
-    mount points. Written to a `.partial` sibling and renamed on success so
-    a failed freeze never leaves a truncated artifact in its place."""
-    tar_path.parent.mkdir(parents=True, exist_ok=True)
-    partial = tar_path.with_name(tar_path.name + ".partial")
-    ssh = util.ssh_base_argv(private_key, guest_ip)
-    # The snapshot can contain the bottle's private workspace, so keep it
-    # owner-only (0600) for the whole stream. The `os.open` mode only applies
-    # on *creation*, so unlink any leftover partial (a prior interrupted run
-    # could have left it world-readable, or something could swap in a symlink
-    # at this predictable name) and exclusively recreate it — O_EXCL|O_NOFOLLOW
-    # — then fchmod immediately so umask can't loosen it. Re-assert after the
-    # rename too (os.replace carries the source mode, but be explicit).
-    partial.unlink(missing_ok=True)
-    fd = os.open(
-        partial, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600
-    )
-    os.fchmod(fd, 0o600)
-    with os.fdopen(fd, "wb") as tar_out:
-        result = subprocess.run(
-            [*ssh, "--", "tar", "--create", "--one-file-system",
-             "--exclude=./proc", "--exclude=./sys", "--exclude=./dev",
-             "--exclude=./run", "--file=-", "--directory=/", "."],
-            stdout=tar_out, stderr=subprocess.PIPE, check=False,
+def _commit_via_ssh(private_key: Path, guest_ip: str, image_tag: str) -> None:
+    with tempfile.TemporaryDirectory(prefix="bot-bottle-fc-commit.") as tmp:
+        rootfs_tar = os.path.join(tmp, "rootfs.tar")
+        ssh = util.ssh_base_argv(private_key, guest_ip)
+        with open(rootfs_tar, "wb") as tar_out:
+            result = subprocess.run(
+                [*ssh, "--", "tar", "--create", "--one-file-system",
+                 "--exclude=./proc", "--exclude=./sys", "--exclude=./dev",
+                 "--exclude=./run", "--file=-", "--directory=/", "."],
+                stdout=tar_out, stderr=subprocess.PIPE, check=False,
+            )
+        if result.returncode != 0:
+            die(f"ssh tar for {guest_ip} failed: "
+                f"{(result.stderr or b'').decode().strip() or '<no stderr>'}")
+        with open(os.path.join(tmp, "Dockerfile"), "w", encoding="utf-8") as f:
+            f.write("FROM scratch\nADD rootfs.tar /\nUSER node\nWORKDIR /home/node\n")
+        build = subprocess.run(
+            ["docker", "build", "-t", image_tag, tmp], check=False,
         )
-    if result.returncode != 0:
-        partial.unlink(missing_ok=True)
-        die(f"ssh tar for {guest_ip} failed: "
-            f"{(result.stderr or b'').decode().strip() or '<no stderr>'}")
-    os.replace(partial, tar_path)
-    os.chmod(tar_path, 0o600)
+        if build.returncode != 0:
+            die(f"docker build for {image_tag!r} failed")

bot_bottle/backend/firecracker/gateway.py

@@ -1,156 +0,0 @@
-"""The Firecracker gateway data plane as a microVM (PRD 0070).
-
-`FirecrackerGateway` is the Firecracker implementation of the backend-neutral
-`Gateway` service, and owns the gateway's host-side logic directly: booting the
-gateway microVM on its NAT'd link, seeding the pre-minted `gateway` token,
-fetching the mitmproxy CA, and the SSH exec/cp provisioning transport. The
-gateway VM never opens `bot-bottle.db` (#469), so it holds no signing key —
-only the token the host hands it via `connect_to_orchestrator`.
-
-The plane-agnostic VM substrate the orchestrator VM also uses stays in
-`infra_vm` — booting a VM from a per-plane rootfs (`boot_vm`), the stable SSH
-keypair, the secret-push retry loop, the PID lifecycle, and the
-adoption/version helpers. The guest-side gateway daemon startup lives in the
-gateway rootfs's guest init (`_gateway_init` in `infra_vm`), so it can't live in
-a host-side method either. The pair coordinator (orchestrator-first, under a
-singleton flock) is `FirecrackerInfraService` (`infra.py`).
-"""
-
-from __future__ import annotations
-
-import subprocess
-from urllib.parse import urlparse
-
-from ...gateway import (
-    DEFAULT_CA_TIMEOUT_SECONDS,
-    Gateway,
-    GatewayError,
-    GatewayTransport,
-)
-from .. import util as backend_util
-from . import infra_vm, netpool, util
-from .gateway_transport import FirecrackerGatewayTransport
-
-# The gateway microVM's name (its run dir). Fixed per host — one gateway VM,
-# shared by every agent VM.
-GATEWAY_NAME = "bot-bottle-gateway"
-
-# The gateway VM's slim memory ceiling — the data plane carries no build
-# tooling (buildah lives only on the orchestrator rootfs) — PRD 0070
-# "Memory: fixed ceilings".
-_GW_MEM_MIB = 2048
-
-# The pre-minted `gateway` JWT path in the guest. The gateway init (in
-# `infra_vm`) waits for it before starting the data plane, so its canonical
-# definition lives with that init; imported here for the push so the
-# load-bearing path isn't duplicated.
-_GUEST_GATEWAY_JWT_PATH = infra_vm._GUEST_GATEWAY_JWT_PATH
-# mitmproxy writes its CA here a beat after start; agents install it to trust
-# the gateway's TLS interception. Host-side only (SSH cat), so it lives here.
-_GATEWAY_CA_PATH = "/home/mitmproxy/.mitmproxy/mitmproxy-ca-cert.pem"
-
-_CA_FETCH_TIMEOUT_SECONDS = 15.0
-
-
-class FirecrackerGateway(Gateway):
-    """The consolidated gateway as a Firecracker microVM on the gateway link.
-
-    The gateway rootfs is built/downloaded by `infra_vm.ensure_built` (the ABC's
-    `ensure_built` no-op here); `connect_to_orchestrator` boots the VM resolving
-    policy against the orchestrator and seeds the pre-minted `gateway` token."""
-
-    name = GATEWAY_NAME
-
-    def __init__(self, vm: infra_vm.InfraVm | None = None) -> None:
-        # The live VM handle when this process booted it; None when adapting an
-        # already-running gateway (CA fetch / provisioning go through the stable
-        # key + fixed link, so no live handle is needed).
-        self._vm = vm
-        self._orchestrator_url = ""
-        self._gateway_token = ""
-
-    def connect_to_orchestrator(self, orchestrator_url: str, gateway_token: str) -> None:
-        """Boot the gateway VM on its link resolving policy against
-        `orchestrator_url`, then seed `gateway_token` over SSH. The orchestrator's
-        guest IP is parsed from the URL and passed on the cmdline (`bb_orch=`), so
-        the baked init stays IP-independent. Boot the orchestrator first — the
-        gateway daemons reach it at startup. The gateway never mints, so it holds
-        no signing key, only this token (#469)."""
-        self._orchestrator_url = orchestrator_url
-        self._gateway_token = gateway_token
-        if not self._orchestrator_url:
-            raise GatewayError(
-                "gateway requires an orchestrator URL to run "
-                "(resolver-only data plane; no single-tenant fallback)"
-            )
-        if not self._gateway_token:
-            raise GatewayError(
-                "gateway requires a pre-minted `gateway` token to run "
-                "(the orchestrator mints it; the gateway never holds the key)"
-            )
-        orchestrator_guest_ip = urlparse(self._orchestrator_url).hostname or ""
-        if not orchestrator_guest_ip:
-            raise GatewayError(
-                f"cannot resolve orchestrator guest IP from {self._orchestrator_url!r}"
-            )
-        # Boot on the gateway link from the gateway rootfs, then push the token
-        # the init waits for before starting the data plane.
-        vm = infra_vm.boot_vm(
-            name=GATEWAY_NAME, slot=netpool.gw_slot(), run_dir=infra_vm._gw_dir(),
-            role="gateway", mem_mib=_GW_MEM_MIB,
-            extra_boot_args=f"bb_orch={orchestrator_guest_ip}",
-        )
-        infra_vm.push_secret(
-            vm, self._gateway_token, _GUEST_GATEWAY_JWT_PATH,
-            "the gateway JWT to the gateway VM (its data plane will not start)",
-        )
-        self._vm = vm
-
-    def is_running(self) -> bool:
-        return infra_vm._pidfile_alive(infra_vm._gw_dir())
-
-    def stop(self) -> None:
-        """Stop only the gateway VM (idempotent — absent is success). A dead
-        gateway already fails `infra_vm.adoptable`, so no version marker to
-        clear here."""
-        infra_vm._kill_pidfile(infra_vm._gw_dir())
-        infra_vm._pid_file(infra_vm._gw_dir()).unlink(missing_ok=True)
-
-    def address(self) -> str:
-        """The gateway VM's guest IP — the agent-facing target agent VMs'
-        gateway-port traffic is DNAT'd to."""
-        return netpool.gw_slot().guest_ip
-
-    def ca_cert_pem(self, *, timeout: float = DEFAULT_CA_TIMEOUT_SECONDS) -> str:
-        """The gateway's mitmproxy CA (PEM) agents install to trust its TLS
-        interception. Fetched from the gateway VM over SSH; polls because
-        mitmproxy writes it a beat after boot. Works from any later launcher —
-        falls back to the stable key + fixed link when this process didn't boot
-        the VM."""
-        key = self._vm.private_key if self._vm else infra_vm._infra_dir() / "id_ed25519"
-        ip = self._vm.guest_ip if self._vm else netpool.gw_slot().guest_ip
-
-        def _fetch() -> str | None:
-            proc = subprocess.run(
-                util.ssh_base_argv(key, ip) + [f"cat {_GATEWAY_CA_PATH}"],
-                capture_output=True, text=True,
-                timeout=_CA_FETCH_TIMEOUT_SECONDS, check=False,
-            )
-            ok = proc.returncode == 0 and "BEGIN CERTIFICATE" in proc.stdout
-            return proc.stdout if ok else None
-
-        try:
-            return backend_util.poll_ca_cert(_fetch, timeout=timeout)
-        except TimeoutError as exc:
-            raise GatewayError(str(exc)) from exc
-
-    def provisioning_transport(self) -> GatewayTransport:
-        """The exec/cp transport git-gate provisioning stages per-bottle repos +
-        deploy keys through (over SSH to the gateway VM). Needs no live handle —
-        built from the stable key + the gateway link's guest IP, so teardown can
-        use it too."""
-        return FirecrackerGatewayTransport(
-            infra_vm._infra_dir() / "id_ed25519", netpool.gw_slot().guest_ip)
-
-
-__all__ = ["FirecrackerGateway", "FirecrackerGatewayTransport", "GATEWAY_NAME"]

bot_bottle/backend/firecracker/gateway_transport.py

@@ -1,56 +0,0 @@
-"""The `GatewayTransport` for the gateway running in the gateway microVM
-(PRD 0070).
-
-How the launcher stages files + runs commands in the running gateway: the
-docker exec/cp equivalents over SSH (dropbear + the stable infra key). The
-backend-neutral provisioning logic that drives it lives in
-`backend.provision_gateway`.
-"""
-
-from __future__ import annotations
-
-import os
-import shlex
-import stat
-import subprocess
-from pathlib import Path
-
-from ...gateway import GatewayProvisionError
-from . import util
-
-
-class FirecrackerGatewayTransport:
-    """`GatewayTransport` for the gateway running in the gateway VM — the docker
-    exec/cp equivalents over SSH (dropbear + the stable infra key)."""
-
-    def __init__(self, private_key: Path, guest_ip: str) -> None:
-        self._key = private_key
-        self._ip = guest_ip
-
-    def exec(self, argv: list[str]) -> None:
-        proc = subprocess.run(
-            util.ssh_base_argv(self._key, self._ip) + [shlex.join(argv)],
-            capture_output=True, text=True, timeout=60, check=False,
-        )
-        if proc.returncode != 0:
-            raise GatewayProvisionError(
-                f"infra gateway exec {argv!r} failed: {proc.stderr.strip()}")
-
-    def cp_into(self, src: str, dest: str) -> None:
-        # Preserve the source mode (docker cp does): the access-hook is staged
-        # 0700 and git-http execs it directly — a plain `cat >` would land it
-        # 0644 and the exec fails with EACCES; keys stay 0600.
-        mode = stat.S_IMODE(os.stat(src).st_mode)
-        q = shlex.quote(dest)
-        proc = subprocess.run(
-            util.ssh_base_argv(self._key, self._ip)
-            + [f"cat > {q} && chmod {mode:o} {q}"],
-            input=Path(src).read_bytes(), capture_output=True, timeout=30, check=False,
-        )
-        if proc.returncode != 0:
-            raise GatewayProvisionError(
-                f"infra gateway cp {src} -> {dest} failed: "
-                f"{proc.stderr.decode(errors='replace').strip()}")
-
-
-__all__ = ["FirecrackerGatewayTransport"]

bot_bottle/backend/firecracker/image_builder.py

@@ -1,247 +0,0 @@
-"""Docker-free agent-image builds for the Firecracker backend (PRD 0069 Stage 3).
-
-Agent Dockerfiles build **inside the persistent per-host orchestrator VM**
-(`infra_vm.py`), which carries buildah (rootless, daemonless): no host Docker
-daemon, no root-equivalent `docker` group. The build runs over SSH against the
-orchestrator VM and its rootfs streams back to the host, where the existing
-`mke2fs -d` path (`util.build_rootfs_ext4`) turns it into a bootable ext4.
-
-Builds run on the control-plane (orchestrator) side — not the data-plane
-gateway — per PRD 0070 v1 ("builds stay in the orchestrator"): it owns
-launches and already carries buildah. Tradeoff: an untrusted Dockerfile's
-`RUN` steps share the VM with the control plane (buildah `--isolation chroot`
-isn't a hard boundary) — the accepted blast-radius tradeoff, re-splittable
-into a disposable builder (booted from this same image on its own TAP) later.
-"""
-
-from __future__ import annotations
-
-import fcntl
-import hashlib
-import os
-import shutil
-import subprocess
-from contextlib import contextmanager
-from pathlib import Path
-from typing import Generator
-
-from ...log import die, info
-from . import util
-from .infra import FirecrackerInfraService
-
-# vfs + chroot: buildah works as root in the microVM (no fuse-overlayfs /
-# overlay module / subuid maps). `--isolation` is a build/run-only flag;
-# `from`/`mount` take just the store.
-_BUILD_FLAGS = "--isolation chroot --storage-driver vfs"
-_STORE_FLAG = "--storage-driver vfs"
-
-_BUILD_TIMEOUT_SECONDS = 900.0
-
-
-def _dockerfile_hash(dockerfile: Path) -> str:
-    """The Dockerfile's content hash. The shipped agent Dockerfiles COPY
-    nothing from the build context (see .dockerignore), so their content fully
-    determines the built image; a Dockerfile that adds COPY will want the
-    context folded in here too."""
-    return hashlib.sha256(dockerfile.read_bytes()).hexdigest()[:16]
-
-
-def _rootfs_digest(dockerfile: Path) -> str:
-    """Cache key for the built AND boot-injected agent rootfs. Two inputs
-    determine the on-disk rootfs: the Dockerfile (the image) and the guest init
-    injected into it (`util._GUEST_INIT`). Folding the init in means a fix to
-    it — e.g. making /tmp world-writable — busts the cache instead of silently
-    reusing a stale rootfs built with the old init."""
-    h = hashlib.sha256()
-    h.update(_dockerfile_hash(dockerfile).encode())
-    h.update(b"\0")
-    h.update(util._GUEST_INIT.encode())
-    return h.hexdigest()[:16]
-
-
-def cached_agent_rootfs_dir(dockerfile: Path) -> Path | None:
-    """Return the ready cached rootfs for ``dockerfile``, if one exists."""
-    base = util.cache_dir() / "rootfs" / f"agent-{_rootfs_digest(dockerfile)}"
-    return base if (base / ".bb-ready").is_file() else None
-
-
-def build_agent_rootfs_dir(
-    dockerfile: Path, *, image_tag: str, smoke_test: tuple[str, ...] = (),
-) -> Path:
-    """Build `dockerfile` in the infra VM (buildah, no host docker), export its
-    rootfs, inject the guest boot bits, and return the cached base dir — the
-    same shape `util.build_rootfs_ext4` consumes. Cached by Dockerfile content
-    + injected guest init, so a repeat launch skips the rebuild but an init or
-    Dockerfile change rebuilds.
-
-    `smoke_test` (the provider's declared argv, e.g. `("claude","--version")`)
-    is run in the freshly built image before export, catching an npm
-    silent-failure image at build time rather than at first agent use."""
-    digest = _rootfs_digest(dockerfile)
-    base = util.cache_dir() / "rootfs" / f"agent-{digest}"
-    if cached_agent_rootfs_dir(dockerfile) is not None:
-        info(f"using cached agent rootfs {base.name}")
-        return base
-
-    # Serialize builds: the infra VM's buildah store + this cache dir are
-    # shared, so concurrent `start`s must not build into them at once. The
-    # lock covers the cache lookup + build + atomic publish; the ready
-    # fast-path above takes no lock.
-    with _build_lock():
-        if (base / ".bb-ready").is_file():  # another build finished while we waited
-            info(f"using cached agent rootfs {base.name}")
-            return base
-        # Build into a temp dir and publish by atomic rename, so a partial
-        # build is never visible as `agent-<digest>`.
-        staging = util.cache_dir() / "rootfs" / f".building-{digest}"
-        shutil.rmtree(staging, ignore_errors=True)
-        staging.mkdir(parents=True)
-        info(f"building agent image {image_tag!r} in the infra VM")
-        _build_in_infra(dockerfile, staging, smoke_test, digest)
-        util.inject_guest_boot(staging)
-        (staging / ".bb-ready").write_text("ok\n")
-        shutil.rmtree(base, ignore_errors=True)
-        os.rename(staging, base)
-    return base
-
-
-@contextmanager
-def _build_lock() -> Generator[None, None, None]:
-    """Host-level exclusive lock serializing agent-image builds (shared infra
-    buildah store + cache dir). flock auto-releases on a crash."""
-    lock_path = util.cache_dir() / "rootfs" / ".build.lock"
-    lock_path.parent.mkdir(parents=True, exist_ok=True)
-    handle = open(lock_path, "w", encoding="utf-8")
-    try:
-        fcntl.flock(handle, fcntl.LOCK_EX)
-        yield
-    finally:
-        handle.close()
-
-
-def _build_in_infra(
-    dockerfile: Path, base: Path, smoke_test: tuple[str, ...], digest: str,
-) -> None:
-    """Ensure the infra VMs are up, `buildah build` the Dockerfile in the
-    orchestrator VM (the build-capable control plane), smoke test the image,
-    and stream its rootfs into `base`. The infra VMs persist; only the
-    per-build container/image/context are cleaned up."""
-    service = FirecrackerInfraService()
-    service.ensure_running()
-    key, ip = service.orchestrator().ssh_target()
-    tag = f"bot-bottle-agent-build-{digest}"
-    ctx = f"/tmp/agent-build-{digest}"
-    smoke_ctr, export_ctr = f"{tag}-smoke", f"{tag}-export"
-
-    def _cleanup() -> None:
-        # Remove only THIS build's working containers/image/context — never
-        # `buildah rm -a`, which would nuke a concurrent build's container.
-        _ssh(key, ip,
-             f"buildah rm {smoke_ctr} {export_ctr} >/dev/null 2>&1; "
-             f"buildah rmi {_STORE_FLAG} {tag} >/dev/null 2>&1; rm -rf {ctx}",
-             timeout=60)
-
-    _cleanup()  # clear leftovers from a crashed prior build of this digest
-    try:
-        prep = _ssh(key, ip, f"mkdir -p {ctx}/ctx")
-        if prep.returncode != 0:
-            die(f"preparing build dir in the infra VM failed: {prep.stderr.strip()}")
-        _send_dockerfile(key, ip, dockerfile, ctx)
-        _buildah_build(key, ip, ctx, tag)
-        _smoke_test(key, ip, tag, smoke_ctr, smoke_test)
-        _stream_rootfs(key, ip, tag, export_ctr, base)
-    finally:
-        _cleanup()
-
-
-def _ssh(private_key: Path, guest_ip: str, script: str,
-         *, timeout: float = 60.0) -> subprocess.CompletedProcess[str]:
-    return subprocess.run(
-        util.ssh_base_argv(private_key, guest_ip) + [script],
-        capture_output=True, text=True, timeout=timeout, check=False,
-    )
-
-
-def _ssh_streamed(private_key: Path, guest_ip: str, script: str,
-                  *, timeout: float) -> int:
-    """Run an SSH command letting the remote's stdout/stderr flow straight to
-    ours (no capture), for long chatty steps where live progress beats a
-    silent wait. Returns the exit code."""
-    proc = subprocess.run(
-        util.ssh_base_argv(private_key, guest_ip) + [script],
-        timeout=timeout, check=False,
-    )
-    return proc.returncode
-
-
-def _send_dockerfile(private_key: Path, guest_ip: str, dockerfile: Path, ctx: str) -> None:
-    proc = subprocess.run(
-        util.ssh_base_argv(private_key, guest_ip) + [f"cat > {ctx}/Dockerfile"],
-        input=dockerfile.read_bytes(), capture_output=True, timeout=30, check=False,
-    )
-    if proc.returncode != 0:
-        die(f"sending Dockerfile to the infra VM failed: "
-            f"{proc.stderr.decode(errors='replace').strip()}")
-
-
-def _buildah_build(private_key: Path, guest_ip: str, ctx: str, tag: str) -> None:
-    # Stream buildah's step-by-step output straight to our stderr (like the
-    # docker backend's `docker build`), so a long first build (base pull +
-    # apt/npm installs) shows live progress instead of a silent wait. The
-    # remote stderr is where buildah writes its `STEP i/n` lines.
-    info(f"buildah build {tag} in the infra VM (streaming output)")
-    rc = _ssh_streamed(
-        private_key, guest_ip,
-        f"buildah build {_BUILD_FLAGS} -t {tag} -f {ctx}/Dockerfile {ctx}/ctx",
-        timeout=_BUILD_TIMEOUT_SECONDS,
-    )
-    if rc != 0:
-        die(f"buildah build in the infra VM failed (exit {rc}); "
-            "see the build output above.")
-
-
-def _smoke_test(private_key: Path, guest_ip: str, tag: str, ctr: str,
-                argv: tuple[str, ...]) -> None:
-    """Run the provider's smoke argv inside the freshly built image
-    (`buildah run`, which uses the image's own PATH), failing the build
-    loudly if the CLI is a broken stub. No-op without a declared test. Uses a
-    named working container (`ctr`) so cleanup is scoped to this build."""
-    if not argv:
-        return
-    cmd = (
-        f"set -e; buildah from {_STORE_FLAG} --name {ctr} {tag} >/dev/null; "
-        f"buildah run {_BUILD_FLAGS} {ctr} -- {' '.join(argv)}; rc=$?; "
-        f"buildah rm {ctr} >/dev/null 2>&1 || true; exit $rc"
-    )
-    result = _ssh(private_key, guest_ip, cmd, timeout=120)
-    if result.returncode != 0:
-        detail = (result.stdout + result.stderr).strip().splitlines()[-10:]
-        die(f"agent image failed its post-build smoke test "
-            f"({' '.join(argv)}):\n" + "\n".join(detail))
-
-
-def _stream_rootfs(private_key: Path, guest_ip: str, tag: str, ctr: str, base: Path) -> None:
-    """`buildah mount` the built image in the infra VM and pipe its rootfs tar
-    straight into `base` on the host (extracted as the non-root host user, so
-    uid 0 isn't preserved — the guest init restores /root ownership). Uses a
-    named working container so cleanup is scoped to this build."""
-    export = (
-        f"set -e; buildah from {_STORE_FLAG} --name {ctr} {tag} >/dev/null; "
-        f"mnt=$(buildah mount {_STORE_FLAG} {ctr}); "
-        f"tar -C \"$mnt\" -cf - ."
-    )
-    ssh_proc = subprocess.Popen(
-        util.ssh_base_argv(private_key, guest_ip) + [export],
-        stdout=subprocess.PIPE, stderr=subprocess.PIPE,
-    )
-    assert ssh_proc.stdout is not None
-    untar = subprocess.run(
-        ["tar", "-x", "-C", str(base)], stdin=ssh_proc.stdout, check=False,
-    )
-    ssh_proc.stdout.close()
-    ssh_err = (ssh_proc.stderr.read().decode(errors="replace")
-               if ssh_proc.stderr else "")
-    rc = ssh_proc.wait()
-    if rc != 0 or untar.returncode != 0:
-        die(f"exporting the built rootfs from the infra VM failed: "
-            f"{ssh_err.strip() or '<no stderr>'}")

bot_bottle/backend/firecracker/infra.py

@@ -1,80 +0,0 @@
-"""The per-host infra service for the Firecracker backend (PRD 0070).
-
-`FirecrackerInfraService` is the Firecracker `InfraService`: it composes the
-orchestrator + gateway microVMs as an idempotent per-host singleton pair over
-the shared `infra_vm` substrate (boot primitives, the singleton flock, the
-adopt/version machinery). Unlike the docker/macOS services it takes no
-per-instance config — the firecracker pair is a **hard** per-host singleton,
-pinned to the fixed netpool links (`orch_slot()` / `gw_slot()`), host cache
-paths, and a `booted-version` marker, so two pairs can't coexist on one host.
-"""
-
-from __future__ import annotations
-
-from ...log import info
-from ..infra_service import InfraService
-from ...orchestrator.lifecycle import DEFAULT_STARTUP_TIMEOUT_SECONDS
-from . import infra_vm
-from .gateway import FirecrackerGateway
-from .orchestrator import FirecrackerOrchestrator
-
-
-class FirecrackerInfraService(InfraService):
-    """Bring up the orchestrator + gateway microVM pair as a per-host singleton."""
-
-    def orchestrator(self) -> FirecrackerOrchestrator:
-        """The control-plane service (adopts the running orchestrator VM by its
-        fixed link; no live handle needed for URL / SSH / health)."""
-        return FirecrackerOrchestrator()
-
-    def gateway(self) -> FirecrackerGateway:
-        """The data-plane service (adopts the running gateway VM by its fixed
-        link; CA fetch / provisioning go through the stable key)."""
-        return FirecrackerGateway()
-
-    def ensure_running(
-        self, *, startup_timeout: float = DEFAULT_STARTUP_TIMEOUT_SECONDS,
-    ) -> str:
-        """Idempotent per-host singleton pair. Adopt the running VMs if the
-        orchestrator's control plane is healthy AND the gateway VM is alive AND
-        both booted the CURRENT code version (a prior launcher booted them — they
-        outlive short-lived `start` processes); otherwise clear any stale VMs and
-        boot a fresh pair (orchestrator first, then the gateway that resolves
-        policy against it). Returns the host control-plane URL.
-
-        Concurrency-safe: the cold stop/build/boot path is serialized by a host
-        flock, so two simultaneous first launches don't both boot on the same
-        links/PIDs. The healthy fast-path takes no lock."""
-        key = infra_vm._infra_dir() / "id_ed25519"
-        orchestrator = self.orchestrator()
-        url = orchestrator.url()
-        want = infra_vm.expected_version()
-        if infra_vm.adoptable(key, url, want):
-            info(f"adopting running infra VMs (orchestrator at {url})")
-            return url
-
-        with infra_vm.singleton_lock():
-            # Re-check under the lock: another launcher may have booted them while
-            # we waited (double-checked, so we adopt not re-boot).
-            if infra_vm.adoptable(key, url, want):
-                info(f"adopting running infra VMs (orchestrator at {url})")
-                return url
-            # Clear stale/hung/OUTDATED VMs holding either link before booting fresh.
-            infra_vm.stop()
-            infra_vm.ensure_built()
-            # Orchestrator first — the gateway daemons reach the control plane at
-            # startup. Each service owns its own boot; the orchestrator (which
-            # holds the signing key) mints the role-scoped `gateway` JWT for the
-            # gateway, which never sees the key (#469).
-            orchestrator.ensure_running(startup_timeout=startup_timeout)
-            self.gateway().connect_to_orchestrator(
-                orchestrator.gateway_url(), orchestrator.mint_gateway_token())
-            infra_vm.record_booted_version(want)
-            return url
-
-    def stop(self) -> None:
-        """Stop both infra VMs (idempotent) and drop the version marker."""
-        infra_vm.stop()
-
-
-__all__ = ["FirecrackerInfraService"]

bot_bottle/backend/firecracker/infra_artifact.py

@@ -1,256 +0,0 @@
-"""Prebuilt infra-VM rootfs images, pulled as artifacts (PRD 0069 Stage 2).
-
-The two Firecracker infra VMs each boot a fixed per-plane rootfs that does not
-vary per launch — the per-boot bits (authorized_keys, guest IP) ride the kernel
-cmdline, so one rootfs boots on any host:
-
-  * `orchestrator` — the control plane + buildah (in-VM agent-image builds);
-  * `gateway` — the slim data plane (no build tooling on the exposed VM).
-
-Instead of building them on the launch host with Docker, we build them
-**off-host** and publish each as a versioned, ready-to-boot ext4 (gzip-
-compressed) to a per-role Gitea **generic package**; the launch host downloads +
-verifies + boots them. No Docker, no image tooling on the launch host — just an
-HTTP fetch and gunzip.
-
-  publish (off-host, see publish_infra.py):
-    docker build -> rootfs dir -> mke2fs -> gzip -> PUT generic package
-  pull (this module, launch host):
-    GET .../rootfs.ext4.gz (+ .sha256) -> verify -> gunzip -> boot
-
-Each artifact **version** is a content hash of everything baked into that rootfs
-(the shipped bot_bottle package, the role's Dockerfiles, and the role init), so
-a launch host always pulls the artifact matching its code and a content change
-can't silently boot a stale rootfs. A checksum mismatch fails closed.
-
-Set `BOT_BOTTLE_INFRA_BUILD=local` to skip the pull and build the rootfs
-locally with Docker (dev iteration on the Dockerfiles) — see `infra_vm`.
-"""
-
-from __future__ import annotations
-
-import gzip
-import hashlib
-import os
-import shutil
-import urllib.error
-import urllib.request
-from pathlib import Path
-
-from ... import resources
-from ...log import die, info
-from . import util
-
-# Bump if the on-disk artifact *format* changes (compression, layout) so a new
-# scheme can't collide with a cached/published artifact of the old one.
-_ARTIFACT_FORMAT = "1"
-
-# The two per-plane infra VM roles. Each publishes/pulls its own rootfs artifact
-# from its own generic package; the Dockerfiles baked into each differ (only the
-# orchestrator rootfs carries buildah), so the versions are hashed separately.
-ROLES = ("orchestrator", "gateway")
-_DOCKERFILES = {
-    "orchestrator": ("Dockerfile.orchestrator", "Dockerfile.orchestrator.fc"),
-    "gateway": ("Dockerfile.gateway",),
-}
-
-_DEFAULT_BASE = "https://gitea.dideric.is"
-_DEFAULT_OWNER = "didericis"
-
-
-def _package(role: str) -> str:
-    return f"bot-bottle-firecracker-{role}"
-
-
-# Streaming copy chunk for the (hundreds-of-MB) download.
-_CHUNK = 1 << 20
-
-
-def local_build_requested() -> bool:
-    """True when the operator opted into the dev Docker-build path instead of
-    pulling the published artifact (`BOT_BOTTLE_INFRA_BUILD=local`)."""
-    return os.environ.get("BOT_BOTTLE_INFRA_BUILD", "").strip().lower() == "local"
-
-
-def infra_artifact_version(
-    init_script: str, role: str, *, repo_root: Path | None = None,
-) -> str:
-    """Content hash (16 hex) of everything baked into `role`'s infra rootfs: the
-    whole shipped `bot_bottle` package, that role's Dockerfiles, and its guest
-    init. Deterministic across the publish host and the launch host when both run
-    the same checkout, so the tag the launch host pulls is exactly the tag
-    publish produced.
-
-    The package is baked into both images wholesale (orchestrator `COPY`s it,
-    gateway `pip install`s it), so hash *every* regular file under it — not just
-    `*.py`. Non-Python inputs (e.g. `gateway/egress/entrypoint.sh`,
-    `netpool.defaults.env`) are baked in too, and a change to one must bump the
-    version or a launch host could boot a stale rootfs whose code differs from
-    its checkout. `__pycache__`/`.pyc` are the only exclusions — build artifacts,
-    never copied."""
-    if repo_root is None:
-        repo_root = resources.build_root()
-    h = hashlib.sha256()
-    h.update(f"format={_ARTIFACT_FORMAT}\nrole={role}\n".encode())
-    pkg = repo_root / "bot_bottle"
-    for path in sorted(pkg.rglob("*")):
-        if not path.is_file():
-            continue
-        if "__pycache__" in path.parts or path.suffix == ".pyc":
-            continue
-        h.update(str(path.relative_to(repo_root)).encode())
-        h.update(b"\0")
-        h.update(path.read_bytes())
-    for name in _DOCKERFILES[role]:
-        h.update(name.encode())
-        h.update(b"\0")
-        h.update((repo_root / name).read_bytes())
-    h.update(b"pyproject.toml\0")
-    h.update((repo_root / "pyproject.toml").read_bytes())
-    h.update(b"dropbear\0")
-    dropbear = util.dropbear_path()
-    h.update(dropbear.read_bytes() if dropbear.is_file() else b"<missing>")
-    h.update(b"init\0")
-    h.update(init_script.encode())
-    return h.hexdigest()[:16]
-
-
-def _config() -> tuple[str, str, str]:
-    """(base_url, owner, token) for the generic-package endpoint. Base + owner
-    are overridable for other deployments / mirrors; the token comes solely from
-    `BOT_BOTTLE_INFRA_ARTIFACT_TOKEN` (a dedicated package-scoped token, kept
-    separate from the general-purpose Gitea token) and is optional — a public
-    package needs none to pull."""
-    base = os.environ.get("BOT_BOTTLE_INFRA_ARTIFACT_BASE", _DEFAULT_BASE).rstrip("/")
-    owner = os.environ.get("BOT_BOTTLE_INFRA_ARTIFACT_OWNER", _DEFAULT_OWNER)
-    token = os.environ.get("BOT_BOTTLE_INFRA_ARTIFACT_TOKEN", "")
-    return base, owner, token
-
-
-def artifact_url(version: str, filename: str, *, role: str) -> str:
-    """The generic-package download URL for one file of `role`'s artifact at
-    `version` (`rootfs.ext4.gz` / `rootfs.ext4.gz.sha256`)."""
-    base, owner, _ = _config()
-    return f"{base}/api/packages/{owner}/generic/{_package(role)}/{version}/{filename}"
-
-
-_GZ_NAME = "rootfs.ext4.gz"
-_SHA_NAME = "rootfs.ext4.gz.sha256"
-_CANDIDATE_DIR_ENV = "BOT_BOTTLE_INFRA_ARTIFACT_DIR"
-
-
-def _cache_root(version: str, role: str) -> Path:
-    return util.cache_dir() / "infra-artifact" / role / version
-
-
-def _open(url: str) -> urllib.request.Request:
-    _, _, token = _config()
-    req = urllib.request.Request(url)
-    if token:
-        req.add_header("Authorization", f"token {token}")
-    return req
-
-
-def _download(url: str, dest: Path) -> None:
-    """Stream `url` to `dest` (atomic via a `.part` sibling)."""
-    tmp = dest.with_suffix(dest.suffix + ".part")
-    try:
-        with urllib.request.urlopen(_open(url)) as resp, open(tmp, "wb") as out:
-            shutil.copyfileobj(resp, out, _CHUNK)
-    except urllib.error.HTTPError as e:
-        tmp.unlink(missing_ok=True)
-        if e.code == 404:
-            die(
-                f"infra artifact not published for this code version.\n"
-                f"    missing: {url}\n"
-                f"    publish it from a build host (Docker):\n"
-                f"        python3 -m bot_bottle.backend.firecracker.publish_infra\n"
-                f"    or build the rootfs locally: BOT_BOTTLE_INFRA_BUILD=local"
-            )
-        die(f"downloading infra artifact failed (HTTP {e.code}): {url}")
-    except urllib.error.URLError as e:
-        tmp.unlink(missing_ok=True)
-        die(f"infra artifact registry unreachable: {url} ({e.reason})")
-    tmp.replace(dest)
-
-
-def _sha256_file(path: Path) -> str:
-    h = hashlib.sha256()
-    with open(path, "rb") as fh:
-        for chunk in iter(lambda: fh.read(_CHUNK), b""):
-            h.update(chunk)
-    return h.hexdigest()
-
-
-def ensure_artifact_gz(version: str, *, role: str) -> Path:
-    """The verified, cached `rootfs.ext4.gz` for `role` at `version` —
-    downloading it (and its `.sha256`) once, then reusing it. Fail-closed on a
-    checksum mismatch: the partial is removed and we die rather than boot an
-    unverified rootfs.
-
-    A pre-staged candidate bundle (`BOT_BOTTLE_INFRA_ARTIFACT_DIR`) holds each
-    role under its own `<dir>/<role>/` subdir."""
-    candidate_dir = os.environ.get(_CANDIDATE_DIR_ENV, "").strip()
-    if candidate_dir:
-        root = Path(candidate_dir) / role
-        version_file = root / "version.txt"
-        # Guard the read so a missing version.txt is a clean error, not a raw
-        # FileNotFoundError.
-        if not version_file.is_file():
-            die(f"infra candidate bundle is incomplete: {root}")
-        declared = version_file.read_text(encoding="utf-8").strip()
-        if declared != version:
-            die(
-                f"infra candidate version mismatch ({role}): expected {version}, "
-                f"bundle contains {declared or '<empty>'}"
-            )
-        gz = root / _GZ_NAME
-        sha = root / _SHA_NAME
-        if not gz.is_file() or not sha.is_file():
-            die(f"infra candidate bundle is incomplete: {root}")
-        expected = sha.read_text().split()[0].strip().lower()
-        actual = _sha256_file(gz)
-        if actual != expected:
-            die(
-                f"infra candidate checksum mismatch ({role}) for {version}:\n"
-                f"    expected {expected}\n    actual   {actual}"
-            )
-        return gz
-
-    root = _cache_root(version, role)
-    root.mkdir(parents=True, exist_ok=True)
-    gz = root / _GZ_NAME
-    ok = root / ".verified"
-    if gz.is_file() and ok.is_file():
-        return gz
-
-    info(f"pulling infra rootfs artifact {_package(role)}/{version}")
-    _download(artifact_url(version, _GZ_NAME, role=role), gz)
-    sha = root / _SHA_NAME
-    _download(artifact_url(version, _SHA_NAME, role=role), sha)
-
-    expected = sha.read_text().split()[0].strip().lower()
-    actual = _sha256_file(gz)
-    if actual != expected:
-        gz.unlink(missing_ok=True)
-        sha.unlink(missing_ok=True)
-        die(
-            f"infra artifact checksum mismatch ({role}) for {version}:\n"
-            f"    expected {expected}\n"
-            f"    actual   {actual}\n"
-            f"    refusing to boot an unverified rootfs."
-        )
-    ok.write_text("ok\n")
-    return gz
-
-
-def materialize_ext4(version: str, dest: Path, *, role: str) -> None:
-    """Ensure the verified `role` artifact is cached, then gunzip it to `dest` —
-    a fresh, writable per-boot rootfs (the VM mutates it; the cached `.gz` stays
-    pristine). Atomic via a `.part` sibling."""
-    gz = ensure_artifact_gz(version, role=role)
-    tmp = dest.with_suffix(dest.suffix + ".part")
-    info(f"expanding {role} infra rootfs -> {dest}")
-    with gzip.open(gz, "rb") as src, open(tmp, "wb") as out:
-        shutil.copyfileobj(src, out, _CHUNK)
-    tmp.replace(dest)

bot_bottle/backend/firecracker/infra_vm.py

@@ -1,497 +0,0 @@
-"""The per-host infra VMs for the Firecracker backend (PRD 0070).
-
-Two persistent microVMs, split now that #469 got the DB off the data plane
-(PRD 0070 "Separating the planes"):
-
-  * **orchestrator VM** — the control plane. Boots on the NAT'd orchestrator
-    link (`netpool.orch_slot()`); the host CLI reaches its `/health` +
-    operator routes over HTTP at the guest IP. Sole opener of `bot-bottle.db`
-    (on its persistent /dev/vdb registry volume); holds the host-canonical
-    signing key (pushed post-boot). Also carries buildah, so in-VM agent-image
-    builds run here (PRD 0070 v1: builds stay with the control plane).
-  * **gateway VM** — the data plane. Boots on its own NAT'd link
-    (`netpool.gw_slot()`); runs the egress / git-http / supervise daemons that
-    agent VMs reach (their gateway-port traffic is DNAT'd here — never to the
-    orchestrator, so a breached agent has no L3 route to the control plane).
-    Holds the mitmproxy CA + a pre-minted `gateway` JWT (never the signing
-    key); reaches the orchestrator's control plane at `orch_guest:8099` over
-    the one nft forward rule that link allows.
-
-Each VM boots its **own** per-plane rootfs — the orchestrator rootfs carries the
-control plane + buildah (in-VM agent builds), the gateway rootfs is the slim
-data plane with no build tooling on the exposed VM. Two artifacts, built/pulled
-per role (`infra_artifact`); each rootfs bakes only its own role init as PID 1.
-The gateway VM also runs a slimmer memory ceiling.
-
-SSH is left enabled for debugging + provisioning; the control plane is the
-load-bearing surface.
-"""
-
-from __future__ import annotations
-
-import fcntl
-import hashlib
-import os
-import signal
-import subprocess
-import time
-import urllib.error
-import urllib.request
-from contextlib import contextmanager
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Generator
-
-from ... import resources
-from ...log import die, info
-from ..docker import util as docker_mod
-from . import firecracker_vm, infra_artifact, netpool, util
-
-# The orchestrator VM's signing-key path on its persistent /dev/vdb volume
-# (mounted at BOT_BOTTLE_ROOT=/var/lib/bot-bottle). The launcher seeds this
-# file with the host-canonical key AFTER boot (over SSH), so the VM verifies
-# tokens with the same key the host CLI signs with — the host token file stays
-# the single source of truth, never clobbered per-backend (issue #469 review).
-_GUEST_SIGNING_KEY_PATH = "/var/lib/bot-bottle/orchestrator-token"
-# The gateway VM's pre-minted `gateway` JWT path (rootfs, not /dev/vdb — the
-# data plane has no registry volume and never opens the DB). Pushed post-boot;
-# the gateway daemons present it to the orchestrator, and never see the key.
-_GUEST_GATEWAY_JWT_PATH = "/var/lib/bot-bottle/gateway-jwt"
-
-# The two per-plane rootfs source images. The orchestrator VM boots a control
-# plane + buildah rootfs (Dockerfile.orchestrator.fc, FROM orchestrator); the
-# gateway VM boots the slim data-plane image directly (no build tooling on the
-# exposed VM). Built from source by default; the launch host pulls prebuilt
-# artifacts instead (`infra_artifact`).
-_GATEWAY_IMAGE = "bot-bottle-gateway:latest"
-_ORCHESTRATOR_IMAGE = "bot-bottle-orchestrator:latest"
-_ORCHESTRATOR_FC_IMAGE = "bot-bottle-orchestrator-fc:latest"
-
-# Per-role rootfs source image + the extra free space `mke2fs` leaves for the
-# guest to grow into. The orchestrator keeps buildah's large build slack; the
-# gateway carries no build tooling, so its rootfs is much smaller.
-_ROOTFS_IMAGE = {"orchestrator": _ORCHESTRATOR_FC_IMAGE, "gateway": _GATEWAY_IMAGE}
-_ROOTFS_SLACK_MIB = {"orchestrator": 8192, "gateway": 1024}
-
-ORCHESTRATOR_PORT = 8099
-
-# The infra VMs make direct upstream connections (gateway egress, and buildah
-# during builds), and the kernel `ip=` cmdline sets no resolver. Public for
-# now; routing DNS through a filtered path is a later refinement.
-_INFRA_RESOLVER = "1.1.1.1"
-
-# How long the launcher retries pushing a secret while the guest's SSH comes
-# up. Below the init's own wait window, so a failed push dies here first.
-_SECRET_PUSH_TIMEOUT_SECONDS = 30.0
-_SECRET_PUSH_POLL_SECONDS = 0.5
-
-
-@dataclass
-class InfraVm:
-    """A handle to one infra VM: its guest IP and the stable SSH key used to
-    seed secrets / fetch the CA / provision git-gate. `vm` is the live VMM
-    handle when this process booted it, and None when adopting a singleton a
-    prior launcher started (teardown then goes through the PID file)."""
-
-    guest_ip: str
-    private_key: Path
-    vm: firecracker_vm.VmHandle | None = None
-
-
-def role_init(role: str) -> str:
-    """The guest PID-1 init for `role` (each per-plane rootfs bakes only its
-    own — no `bb_role` branch, since the rootfs *is* the role)."""
-    return _orchestrator_init() if role == "orchestrator" else _gateway_init()
-
-
-def _role_version(role: str) -> str:
-    return infra_artifact.infra_artifact_version(role_init(role), role)
-
-
-def ensure_built() -> None:
-    """Ensure both infra rootfs artifacts are available before boot.
-
-    Default (docker-free, PRD 0069 Stage 2): download + verify the prebuilt
-    orchestrator + gateway rootfs artifacts matching this code version (see
-    `infra_artifact`); the launch host needs no Docker.
-    `BOT_BOTTLE_INFRA_BUILD=local` instead builds the images from source with
-    host Docker (the orchestrator-fc image is `FROM` the orchestrator image, so
-    it must exist first) — for iterating on the Dockerfiles."""
-    if infra_artifact.local_build_requested():
-        build_infra_images_with_docker()
-        return
-    for role in infra_artifact.ROLES:
-        infra_artifact.ensure_artifact_gz(_role_version(role), role=role)
-
-
-def build_infra_images_with_docker() -> None:
-    """Build the fixed images from source with host Docker: orchestrator,
-    gateway, then the orchestrator-fc image (Dockerfile.orchestrator.fc: FROM
-    orchestrator + buildah). The gateway VM boots the gateway image directly.
-    The launch host uses this only in `BOT_BOTTLE_INFRA_BUILD=local` mode;
-    `publish_infra` uses it off-host to produce the published artifacts."""
-    root = str(resources.build_root())
-    docker_mod.build_image(
-        _ORCHESTRATOR_IMAGE, root, dockerfile="Dockerfile.orchestrator")
-    docker_mod.build_image(
-        _GATEWAY_IMAGE, root, dockerfile="Dockerfile.gateway")
-    docker_mod.build_image(
-        _ORCHESTRATOR_FC_IMAGE, root, dockerfile="Dockerfile.orchestrator.fc")
-
-
-def build_rootfs_dir(role: str) -> Path:
-    """`role`'s base rootfs dir: its source image prepared with the role init as
-    PID 1. The init's content is folded into the cache key so an init change
-    rebuilds the rootfs (the base image digest alone wouldn't catch it)."""
-    init = role_init(role)
-    tag = hashlib.sha256(init.encode()).hexdigest()[:8]
-    return util.build_base_rootfs_dir(
-        _ROOTFS_IMAGE[role], variant=f"-{role}-{tag}", init_script=init,
-    )
-
-
-@contextmanager
-def singleton_lock() -> Generator[None, None, None]:
-    """Host-level exclusive lock serializing the infra pair's cold create path
-    (`stop`/`ensure_built`/`boot`). flock auto-releases if the launcher
-    crashes, so the lock is never leaked."""
-    lock_path = _infra_dir() / "singleton.lock"
-    handle = open(lock_path, "w", encoding="utf-8")
-    try:
-        fcntl.flock(handle, fcntl.LOCK_EX)
-        yield
-    finally:
-        handle.close()
-
-
-def stop() -> None:
-    """Stop BOTH infra VMs (idempotent — absent is success). Reaps the
-    recorded VMMs AND any orphaned firecracker still bound to either infra
-    config — the PID files drift after crashes / out-of-band kills, and a
-    survivor would hold a link's TAP so the next boot dies with "tap …
-    Resource busy". Also reaps a surviving *legacy* single combined-VM (the
-    pre-split layout booted from `<infra>/config.json` on the orchestrator
-    link): the two-VM `stop` otherwise wouldn't know about it, and it would
-    hold the orchestrator TAP so the first split boot fails — so the cutover
-    is self-healing, no manual host teardown. Drops the version marker so a
-    stopped pair is never treated as adoptable."""
-    _kill_pidfile(_orch_dir())
-    _kill_pidfile(_gw_dir())
-    _kill_pidfile(_infra_dir())  # legacy pre-split combined VM (migration)
-    _kill_infra_firecrackers()
-    _pid_file(_orch_dir()).unlink(missing_ok=True)
-    _pid_file(_gw_dir()).unlink(missing_ok=True)
-    _pid_file(_infra_dir()).unlink(missing_ok=True)  # legacy
-    _version_file().unlink(missing_ok=True)
-
-
-def boot_vm(
-    *,
-    name: str,
-    slot: netpool.Slot,
-    run_dir: Path,
-    role: str,
-    mem_mib: int,
-    data_drive: Path | None = None,
-    extra_boot_args: str = "",
-) -> InfraVm:
-    """Boot the `role` infra VM from its per-plane rootfs on `slot`'s link.
-    Records the PID."""
-    if not netpool.tap_present(slot.iface):
-        die(f"infra link {slot.iface} not present.\n"
-            f"    ./cli.py backend setup --backend=firecracker")
-
-    run_dir.mkdir(parents=True, exist_ok=True)
-    rootfs = run_dir / "rootfs.ext4"
-    if infra_artifact.local_build_requested():
-        util.build_rootfs_ext4(
-            build_rootfs_dir(role), rootfs, slack_mib=_ROOTFS_SLACK_MIB[role])
-    else:
-        # Prebuilt artifact already carries the role's build slack; expand it to
-        # a fresh writable rootfs for this boot.
-        infra_artifact.materialize_ext4(_role_version(role), rootfs, role=role)
-    private_key, pubkey = _stable_keypair()
-
-    info(f"booting {role} VM on {slot.iface} (guest {slot.guest_ip})")
-    boot_args = extra_boot_args
-    vm = firecracker_vm.boot(
-        name=name, rootfs=rootfs, tap=slot.iface,
-        guest_ip=slot.guest_ip, host_ip=slot.host_ip, pubkey=pubkey,
-        run_dir=run_dir, mem_mib=mem_mib, detached=True,
-        data_drive=data_drive, extra_boot_args=boot_args,
-    )
-    _pid_file(run_dir).write_text(str(vm.process.pid))
-    return InfraVm(guest_ip=slot.guest_ip, private_key=private_key, vm=vm)
-
-
-def _infra_dir() -> Path:
-    d = util.cache_dir() / "infra"
-    d.mkdir(parents=True, exist_ok=True)
-    return d
-
-
-def _orch_dir() -> Path:
-    d = _infra_dir() / "orchestrator"
-    d.mkdir(parents=True, exist_ok=True)
-    return d
-
-
-def _gw_dir() -> Path:
-    d = _infra_dir() / "gateway"
-    d.mkdir(parents=True, exist_ok=True)
-    return d
-
-
-def _pid_file(run_dir: Path) -> Path:
-    return run_dir / "vm.pid"
-
-
-def _version_file() -> Path:
-    """Records the infra-artifact version the *running* pair booted from, so a
-    later launcher can tell whether the singletons it found are the current
-    code. Without it, a healthy pair built from an older image gets adopted
-    forever and the new code never boots — every infra change would need an
-    out-of-band kill to dislodge the stale VMs (and races whatever launched
-    next). Both VMs boot the same artifact, so one marker covers the pair."""
-    return _infra_dir() / "booted-version"
-
-
-def expected_version() -> str:
-    """The combined marker for the running pair: both per-plane artifact
-    versions, so a change to either rootfs dislodges the adopted pair."""
-    return " ".join(f"{role}={_role_version(role)}" for role in infra_artifact.ROLES)
-
-
-def adoptable(key: Path, url: str, want: str) -> bool:
-    """Adopt the running pair only if it booted from the CURRENT version, the
-    orchestrator's control plane is healthy, and the gateway VM is still alive.
-    A missing/mismatched marker means a prior launcher booted an older infra
-    image; a dead gateway means the pair is half-down — reboot both rather than
-    reuse stale or partial state."""
-    if not key.exists():
-        return False
-    try:
-        booted = _version_file().read_text(encoding="utf-8").strip()
-    except OSError:
-        return False
-    if booted != want:
-        return False
-    if not _health_ok(url):
-        return False
-    return _pidfile_alive(_gw_dir())
-
-
-def record_booted_version(version: str) -> None:
-    _version_file().write_text(version + "\n", encoding="utf-8")
-
-
-def push_secret(infra: InfraVm, secret: str, dest: str, what: str) -> None:
-    """Pipe `secret` to an atomic write of `dest` in the guest over SSH,
-    retrying while the guest's SSH comes up; die (naming `what`) if it never
-    succeeds. Bare-pipe input keeps the value off argv."""
-    push = f"umask 077; cat > {dest}.tmp && mv {dest}.tmp {dest}"
-    deadline = time.monotonic() + _SECRET_PUSH_TIMEOUT_SECONDS
-    last = ""
-    while time.monotonic() < deadline:
-        proc = subprocess.run(
-            util.ssh_base_argv(infra.private_key, infra.guest_ip) + [push],
-            input=secret, capture_output=True, text=True, check=False,
-        )
-        if proc.returncode == 0:
-            return
-        last = proc.stderr.strip()
-        time.sleep(_SECRET_PUSH_POLL_SECONDS)
-    die(f"could not push {what}: {last or '<no stderr>'}")
-
-
-def _stable_keypair() -> tuple[Path, str]:
-    """The infra VMs' shared SSH keypair — generated once and reused, so any
-    later launcher can SSH in (seed secrets / fetch CA / provision) even though
-    a different process booted the VMs. Both VMs get the same pubkey re-injected
-    on every boot via the cmdline."""
-    d = _infra_dir()
-    key, pub = d / "id_ed25519", d / "id_ed25519.pub"
-    if key.exists() and pub.exists():
-        return key, pub.read_text().strip()
-    key.unlink(missing_ok=True)
-    pub.unlink(missing_ok=True)
-    subprocess.run(
-        ["ssh-keygen", "-t", "ed25519", "-N", "", "-q", "-f", str(key),
-         "-C", "bot-bottle-infra"],
-        check=True,
-    )
-    return key, pub.read_text().strip()
-
-
-def _pidfile_alive(run_dir: Path) -> bool:
-    """True iff `run_dir`'s recorded VMM is still a live firecracker (guards a
-    recycled PID by checking `comm`)."""
-    try:
-        pid = int(_pid_file(run_dir).read_text().strip())
-    except (OSError, ValueError):
-        return False
-    try:
-        return Path(f"/proc/{pid}/comm").read_text().strip() == "firecracker"
-    except OSError:
-        return False
-
-
-def _kill_pidfile(run_dir: Path) -> None:
-    """SIGTERM (then SIGKILL) the VMM recorded in `run_dir`, if it's still ours.
-    Guards against a recycled PID by checking the process is firecracker."""
-    try:
-        pid = int(_pid_file(run_dir).read_text().strip())
-    except (OSError, ValueError):
-        return
-    try:
-        comm = Path(f"/proc/{pid}/comm").read_text().strip()
-    except OSError:
-        return  # already gone
-    if comm != "firecracker":
-        return  # PID recycled by an unrelated process
-    try:
-        os.kill(pid, signal.SIGTERM)
-        for _ in range(50):
-            if not Path(f"/proc/{pid}").exists():
-                return
-            time.sleep(0.1)
-        os.kill(pid, signal.SIGKILL)
-    except OSError:
-        pass
-
-
-def _kill_infra_firecrackers(proc_root: Path = Path("/proc")) -> None:
-    """SIGKILL any firecracker VMM whose `--config-file` is one of this host's
-    infra configs (orchestrator or gateway), independent of the PID files —
-    reaps orphans it lost track of so both links' TAPs are free to rebind.
-    Also matches the *legacy* pre-split combined-VM config (`<infra>/config.json`)
-    so a surviving old singleton is cleared off the orchestrator link during the
-    cutover. Scoped to these infra config paths, so the pool's agent VMs (other
-    config paths) are untouched."""
-    cfgs = {
-        str(_orch_dir() / "config.json"),
-        str(_gw_dir() / "config.json"),
-        str(_infra_dir() / "config.json"),  # legacy pre-split combined VM
-    }
-    for entry in proc_root.iterdir():
-        if not entry.name.isdigit():
-            continue
-        try:
-            if (entry / "comm").read_text().strip() != "firecracker":
-                continue
-            args = (entry / "cmdline").read_bytes().split(b"\0")
-        except OSError:
-            continue  # process vanished / not ours
-        if any(a.decode("utf-8", "replace") in cfgs for a in args):
-            try:
-                os.kill(int(entry.name), signal.SIGKILL)
-            except (OSError, ValueError):
-                pass
-
-
-def _health_ok(url: str) -> bool:
-    try:
-        with urllib.request.urlopen(f"{url}/health", timeout=1.0) as resp:
-            return resp.status == 200
-    except (urllib.error.URLError, TimeoutError, OSError):
-        return False
-
-
-def _init_head() -> str:
-    """The shared PID-1 preamble both role inits open with: mount the pseudo-
-    filesystems, export a real PATH (a bare-init shell's built-in exec path
-    isn't in the *environment*, so backgrounded `python3 ...` children would
-    find no PATH), set the direct upstream resolver, install the per-boot SSH
-    pubkey from the cmdline, and start dropbear for debug/provisioning."""
-    return f"""#!/bin/sh
-# bot-bottle Firecracker infra VM init (PID 1).
-mount -t proc proc /proc 2>/dev/null
-mount -t sysfs sys /sys 2>/dev/null
-mount -t devtmpfs dev /dev 2>/dev/null
-mkdir -p /dev/pts && mount -t devpts devpts /dev/pts 2>/dev/null
-mount -o remount,rw / 2>/dev/null
-
-export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
-
-# Direct upstream resolver (control-plane / gateway egress + buildah).
-printf 'nameserver {_INFRA_RESOLVER}\\n' > /etc/resolv.conf 2>/dev/null
-
-# Debug SSH: install the per-boot pubkey from the kernel cmdline.
-KEY=$(sed -n 's/.*bb_pubkey=\\([^ ]*\\).*/\\1/p' /proc/cmdline | base64 -d 2>/dev/null)
-if [ -n "$KEY" ]; then
-    mkdir -p /root/.ssh
-    printf '%s\\n' "$KEY" > /root/.ssh/authorized_keys
-    chmod 700 /root/.ssh && chmod 600 /root/.ssh/authorized_keys
-fi
-chown -R 0:0 /root 2>/dev/null || true
-mkdir -p /etc/dropbear /run /var/lib/bot-bottle
-
-/bb-dropbear -R -E -p 22 &
-
-cd /app
-"""
-
-
-_INIT_TAIL = """
-# Reap as PID 1; children are backgrounded, so `wait` blocks.
-while : ; do wait ; done
-"""
-
-
-def _gateway_init() -> str:
-    """PID-1 init for the gateway (data-plane) VM. Waits for the host-seeded
-    `gateway` JWT, then starts ONLY the data-plane daemons, multi-tenant against
-    the orchestrator at the `bb_orch` cmdline address. The VM backend reaches git
-    over git-http (9420), so the git:// daemon (a per-bottle entrypoint the
-    consolidated model doesn't use) is left out. No SUPERVISE_DB_PATH: the data
-    plane reaches the supervise queue over the control-plane RPC and never opens
-    bot-bottle.db (PRD 0070 / #469). If the JWT never arrives, REFUSE to start
-    rather than run without auth."""
-    return _init_head() + f"""
-ORCH=$(sed -n 's/.*bb_orch=\\([^ ]*\\).*/\\1/p' /proc/cmdline)
-GW_JWT=""
-i=0
-while [ "$i" -lt 600 ]; do
-    GW_JWT=$(cat {_GUEST_GATEWAY_JWT_PATH} 2>/dev/null)
-    [ -n "$GW_JWT" ] && break
-    i=$((i + 1))
-    sleep 0.1
-done
-if [ -z "$GW_JWT" ]; then
-    echo "infra gateway: gateway JWT never arrived; refusing to start the data plane" >&2
-else
-    chmod 600 {_GUEST_GATEWAY_JWT_PATH} 2>/dev/null || true
-    BOT_BOTTLE_GATEWAY_DAEMONS=egress,git-http,supervise \\
-    BOT_BOTTLE_ORCHESTRATOR_URL=http://$ORCH:{ORCHESTRATOR_PORT} \\
-    BOT_BOTTLE_ORCHESTRATOR_AUTH_JWT="$GW_JWT" \\
-        python3 -m bot_bottle.gateway.bootstrap &
-fi
-""" + _INIT_TAIL
-
-
-def _orchestrator_init() -> str:
-    """PID-1 init for the orchestrator (control-plane) VM. Mounts the persistent
-    registry volume (/dev/vdb — bot-bottle.db survives a VM restart), waits for
-    the host-seeded signing key, then starts ONLY the control plane. If the key
-    never arrives, REFUSE to start rather than run OPEN — open mode would grant
-    every unauthenticated caller the `cli` role (#469)."""
-    return _init_head() + f"""
-# Persistent registry volume (second virtio-block device, /dev/vdb) mounted at
-# the DB dir, so bot-bottle.db survives orchestrator-VM restarts.
-mount -t ext4 /dev/vdb /var/lib/bot-bottle 2>/dev/null || true
-CP_KEY=""
-i=0
-while [ "$i" -lt 600 ]; do
-    CP_KEY=$(cat {_GUEST_SIGNING_KEY_PATH} 2>/dev/null)
-    [ -n "$CP_KEY" ] && break
-    i=$((i + 1))
-    sleep 0.1
-done
-if [ -z "$CP_KEY" ]; then
-    echo "infra: control-plane signing key never arrived; refusing to start the control plane (would run OPEN)" >&2
-else
-    chmod 600 {_GUEST_SIGNING_KEY_PATH} 2>/dev/null || true
-    BOT_BOTTLE_ROOT=/var/lib/bot-bottle BOT_BOTTLE_ORCHESTRATOR_TOKEN="$CP_KEY" python3 -m bot_bottle.orchestrator \\
-        --host 0.0.0.0 --port {ORCHESTRATOR_PORT} --broker stub &
-fi
-""" + _INIT_TAIL

bot_bottle/backend/firecracker/launch.py

@@ -1,75 +1,83 @@
-"""Launch flow for the Firecracker backend (PRD 0070, consolidated).
+"""Launch flow for the Firecracker backend.
 
 Per bottle:
-  1. build the agent rootfs in a builder VM (buildah, no host docker), or
-     resume a frozen bottle from its committed rootfs tar; cache the ext4;
-  2. ensure the per-host orchestrator + shared gateway are up;
-  3. claim a free TAP pool slot (rootless flock);
-  4. register the bottle on the orchestrator by the VM's guest IP (the
-     attribution key) and provision its git-gate state into the gateway;
-  5. boot the microVM on that TAP; wait for SSH;
-  6. provision (shared gateway CA, prompt, skills, workspace, git, supervise)
-     over SSH.
-
-The per-bottle Docker sidecar bundle is gone. The shared gateway (its own
-data-plane VM) handles egress / git-gate / supervise for every VM; the nft
-netpool's PREROUTING DNAT routes the VMs' gateway-port traffic to that gateway
-VM, and the nft table's `ct status dnat accept` rule in the forward chain lets
-it pass. The VM still sends to `host_tap_ip:PORT` — the address its world is,
-by nft design, limited to.
+  1. mint the egress CA, build the agent image (docker), export it to a
+     cached ext4 rootfs;
+  2. claim a free TAP pool slot (rootless flock);
+  3. bring up the Docker sidecar bundle, publishing egress / git-gate /
+     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
-fail-closed in preflight): a VM reaches only the gateway (DNAT'd from the host
-TAP IP) and nothing else — not even the orchestrator control plane.
+fail-closed in preflight): a VM reaches only its sidecar (DNAT'd from
+the host TAP IP) and nothing else. The agent's HTTPS_PROXY therefore
+points at `http://<host_tap_ip>:9099`, its only route to the world.
 """
 
 from __future__ import annotations
 
 import dataclasses
 import os
-import shutil
+import subprocess
 from contextlib import ExitStack, contextmanager
 from pathlib import Path
 from typing import Callable, Generator
 
-from ...agent_provider import runtime_for
 from ...bottle_state import (
-    committed_rootfs_path,
     egress_state_dir,
     git_gate_state_dir,
     read_committed_image,
 )
-from ...egress import Egress
-from ...git_gate import GitGate
-from ...image_cache import check_stale_path
+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 ...supervisor.types import SUPERVISE_PORT
-from ..docker.egress import EGRESS_PORT
+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, image_builder, isolation_probe, netpool, util
+from . import firecracker_vm, isolation_probe, netpool, util
 from .bottle import FirecrackerBottle
 from .bottle_plan import FirecrackerBottlePlan
-from ...orchestrator.store.config_store import resolve_teardown_timeout
-from ...orchestrator.store.secret_store import ENV_VAR_SECRET_NAME
-from .consolidated_launch import (
-    launch_consolidated,
-    persist_env_var_secret,
-    deprovision_consolidated,
-)
 
 
+_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,
-    agent_base: Path,
     *,
     provision: Callable[[FirecrackerBottlePlan, "FirecrackerBottle"], str | None],
 ) -> Generator[FirecrackerBottle, None, None]:
-    """Build, launch, and provision a Firecracker bottle via the consolidated
-    orchestrator. Teardown on exit."""
     stack = ExitStack()
     bottle_for_revoke = plan.manifest.bottle
     git_gate_dir_for_revoke = git_gate_state_dir(plan.slug)
@@ -81,97 +89,36 @@ def launch(
         except BaseException as exc:  # noqa: W0718 - teardown must continue
             teardown_exc = exc
             warn(f"firecracker teardown failed: {exc!r}")
-        GitGate().revoke_provisioned_keys(bottle_for_revoke, git_gate_dir_for_revoke)
+        revoke_git_gate_provisioned_keys(bottle_for_revoke, git_gate_dir_for_revoke)
         if teardown_exc is not None:
             raise teardown_exc
 
     try:
-        # Step 1 (rootfs resolution/build) runs in BottleBackend.launch before
-        # this context starts resources. ``agent_base`` is the selected cache,
-        # fresh build, or committed snapshot.
-        # Step 2: mint the git-gate dynamic (gitea) deploy keys, if any.
-        git_gate_plan = plan.git_gate_plan
-        if git_gate_plan.upstreams:
-            git_gate_plan = GitGate().provision_dynamic_keys(
-                plan.manifest.bottle, git_gate_plan, git_gate_state_dir(plan.slug),
-            )
+        plan = _mint_certs(plan)
+        plan = _build_agent_image(plan)
 
-        # Step 3: claim a TAP slot; the flock is held until teardown.
+        # 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}")
 
-        # Step 4: register on the orchestrator + provision this bottle's
-        # git-gate state into the shared gateway. The per-bottle egress 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.
-        # Attribution is by the VM's guest IP (unspoofable via /31 TAP + nft).
-        effective_env = {**os.environ, **plan.agent_provision.provisioned_env}
-        token_values = Egress().resolve_token_values(
-            plan.egress_plan.token_env_map, effective_env,
-        )
-        teardown_timeout = resolve_teardown_timeout()
-        ctx = launch_consolidated(
-            plan.egress_plan, git_gate_plan,
-            guest_ip=slot.guest_ip,
-            image_ref=plan.image,
-            tokens=token_values,
-        )
-        stack.callback(
-            deprovision_consolidated, ctx.bottle_id,
-            orchestrator_url=ctx.orchestrator_url,
-            timeout=teardown_timeout,
-        )
+        plan = _provision_git_gate_keys(plan)
 
-        # Step 5: install the SHARED gateway CA (replaces the per-bottle CA).
-        # Write it to a stable host path so the provisioner can copy it over SSH.
-        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(ctx.gateway_ca_pem)
-        egress_plan = dataclasses.replace(
-            plan.egress_plan,
-            mitmproxy_ca_host_path=ca_file,
-            mitmproxy_ca_cert_only_host_path=ca_file,
-        )
-        # Point the agent's git-gate insteadOf rewrites and supervise MCP URL
-        # at the shared gateway (reached at the slot's host TAP IP — the VM
-        # sends there and the nft netpool DNAT routes to the gateway VM).
-        git_gate_url = (
-            f"http://{slot.host_ip}:{_GIT_HTTP_PORT}" if git_gate_plan.upstreams else ""
-        )
-        supervise_url = (
-            f"http://{slot.host_ip}:{SUPERVISE_PORT}/"
-            if plan.supervise_plan is not None else ""
-        )
-        plan = dataclasses.replace(
-            plan,
-            git_gate_plan=git_gate_plan,
-            egress_plan=egress_plan,
-            identity_token=ctx.identity_token,
-            env_var_secret=ctx.env_var_secret,
-            # Deliver the identity token as egress proxy credentials — clients
-            # honor `HTTPS_PROXY=http://id:token@gw` without app changes; the
-            # gateway reads Proxy-Authorization, validates the (source_ip,
-            # token) pair, and strips it before upstream.
-            agent_proxy_url=(
-                f"http://bottle:{ctx.identity_token}"
-                f"@{slot.host_ip}:{EGRESS_PORT}"
-            ),
-            agent_git_gate_url=git_gate_url,
-            agent_supervise_url=supervise_url,
-        )
+        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)
 
-        # Step 6: build the per-bottle rootfs + SSH key, then boot.
+        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)
-        # Remove the run dir on teardown so the per-bottle rootfs.ext4 (~1G)
-        # doesn't leak. Registered before vm.terminate below so it runs *after*
-        # it (ExitStack is LIFO): the VM is gone before we rm its rootfs.
-        stack.callback(lambda: shutil.rmtree(run_dir, ignore_errors=True))
         rootfs = run_dir / "rootfs.ext4"
-        util.build_rootfs_ext4(agent_base, rootfs)
+        util.build_rootfs_ext4(base_dir, rootfs)
         private_key, pubkey = util.generate_keypair(run_dir)
 
         vm = firecracker_vm.boot(
@@ -185,10 +132,9 @@ def launch(
         )
         stack.callback(vm.terminate)
         firecracker_vm.wait_for_ssh(vm, private_key)
-        persist_env_var_secret(private_key, slot.guest_ip, ctx.env_var_secret)
 
-        # Authoritative fail-closed egress-boundary check, before the agent
-        # runs: prove the VM cannot reach the host directly.
+        # 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(
@@ -213,45 +159,169 @@ def launch(
         teardown()
 
 
-def build_or_load_agent_base(plan: FirecrackerBottlePlan) -> Path:
-    """Produce the agent's base rootfs dir. Primary path: build the Dockerfile
-    inside a Firecracker builder VM (buildah, no host docker), smoke-testing
-    the image before export. A committed snapshot (freeze/migrate) is resumed
-    directly from the rootfs tar the freezer wrote — no host docker either."""
+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)
+
+
+def _build_agent_image(plan: FirecrackerBottlePlan) -> FirecrackerBottlePlan:
+    _docker_build(SIDECAR_BUNDLE_IMAGE, _REPO_DIR, dockerfile=SIDECAR_BUNDLE_DOCKERFILE)
     committed = read_committed_image(plan.slug)
-    committed_tar = committed_rootfs_path(plan.slug)
-    if committed and committed_tar.is_file():
-        info(f"resuming from committed rootfs {committed_tar}")
-        return util.build_committed_rootfs_dir(committed_tar)
-    dockerfile = Path(plan.dockerfile_path)
-    if plan.spec.image_policy == "cached":
-        cached = image_builder.cached_agent_rootfs_dir(dockerfile)
-        if cached is None:
-            die(
-                f"cached agent rootfs for {plan.image!r} not found; "
-                "run without --cached-images to build it"
-            )
-        info(f"using cached agent rootfs {cached.name}")
-        return cached
-    return image_builder.build_agent_rootfs_dir(
-        dockerfile,
-        image_tag=plan.image,
-        smoke_test=runtime_for(plan.agent_provider_template).smoke_test,
+    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,
     )
 
 
-def stale_checks(plan: FirecrackerBottlePlan) -> None:
-    """Raise when the cached rootfs selected by this plan is stale."""
-    if plan.spec.image_policy != "cached":
+# --- 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
-    committed = read_committed_image(plan.slug)
-    committed_tar = committed_rootfs_path(plan.slug)
-    if committed and committed_tar.is_file():
-        check_stale_path(f"agent rootfs {committed_tar}", committed_tar)
-        return
-    cached = image_builder.cached_agent_rootfs_dir(Path(plan.dockerfile_path))
-    if cached is not None:
-        check_stale_path(f"agent rootfs {cached}", cached / ".bb-ready")
+    _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 -------------------------------------------------
@@ -260,18 +330,12 @@ 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."""
-    # Carries the identity token as proxy credentials (set in `launch`).
-    proxy_url = plan.agent_proxy_url or f"http://{host_ip}:{EGRESS_PORT}"
+    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,
-        # Rootfs export can leave Git's implicit XDG paths unreadable even
-        # after the runtime repair. Bypass that discovery and name the
-        # provisioned global config explicitly so insteadOf can never fall
-        # through to the credential-bearing upstream URL.
-        "GIT_CONFIG_GLOBAL": f"{plan.guest_home}/.gitconfig",
         "NODE_EXTRA_CA_CERTS": AGENT_CA_PATH,
         "SSL_CERT_FILE": AGENT_CA_BUNDLE,
         "REQUESTS_CA_BUNDLE": AGENT_CA_BUNDLE,
@@ -280,9 +344,7 @@ def _agent_guest_env(plan: FirecrackerBottlePlan, host_ip: str) -> dict[str, str
         env["GIT_GATE_URL"] = plan.agent_git_gate_url
     if plan.agent_supervise_url:
         env["MCP_SUPERVISE_URL"] = plan.agent_supervise_url
-    if plan.env_var_secret:
-        env[ENV_VAR_SECRET_NAME] = plan.env_var_secret
-    for entry in Egress().agent_env_entries(plan.egress_plan):
+    for entry in egress_agent_env_entries(plan.egress_plan):
         key, _, value = entry.partition("=")
         env[key] = value
     env.update(plan.agent_provision.guest_env)
@@ -293,3 +355,50 @@ def _agent_guest_env(plan: FirecrackerBottlePlan, host_ip: str) -> dict[str, str
         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.defaults.env

@@ -15,19 +15,3 @@ BOT_BOTTLE_FC_POOL_SIZE=8
 BOT_BOTTLE_FC_IP_BASE=10.243.0.0
 BOT_BOTTLE_FC_IFACE_PREFIX=bbfc
 BOT_BOTTLE_FC_NFT_TABLE=bot_bottle_fc
-# The orchestrator VM's own TAP — a dedicated link OUTSIDE the bbfc*
-# agent pool. Unlike agent VMs (which reach only their gateway), the
-# orchestrator is trusted infra that needs real NAT'd internet egress:
-# to FROM-pull + apt/npm during in-VM agent-image builds (buildah). Its
-# /31 is the top of the IP_BASE /16 (host x.y.255.0, guest x.y.255.1),
-# clear of the pool near the bottom of the block.
-BOT_BOTTLE_FC_ORCH_IFACE=bborch0
-# The gateway (data-plane) VM's own TAP — the second infra link, split
-# from the orchestrator now that #469 got the DB off the data plane (PRD
-# 0070 "Separating the planes"). It mirrors the orchestrator link: NAT'd
-# internet egress (the gateway forwards agent egress upstream) plus a
-# forward path to reach the orchestrator's control plane. Its /31 is the
-# next one above the orchestrator link (host x.y.255.2, guest x.y.255.3).
-# Agents DNAT their gateway-port traffic here (not to the orchestrator),
-# so a breached agent has no L3 route to the control plane.
-BOT_BOTTLE_FC_GW_IFACE=bbgw0

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 gateway (DNAT'd from the host TAP IP) and nothing else.
+    own sidecar (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*
@@ -79,19 +79,6 @@ def _cfg(key: str) -> str:
 IFACE_PREFIX = _cfg("BOT_BOTTLE_FC_IFACE_PREFIX")
 NFT_TABLE = _cfg("BOT_BOTTLE_FC_NFT_TABLE")
 
-# The orchestrator VM's dedicated TAP — outside the bbfc* agent pool
-# and, unlike it, NAT'd to the internet (see `orch_slot`). The
-# orchestrator is trusted infra: it builds agent images in-VM (buildah
-# needs to FROM-pull + apt/npm).
-ORCH_IFACE = _cfg("BOT_BOTTLE_FC_ORCH_IFACE")
-
-# The gateway (data-plane) VM's dedicated TAP — the second infra link
-# (see `gw_slot`), split from the orchestrator per PRD 0070. Like the
-# orchestrator link it is NAT'd to the internet (the gateway forwards
-# agent egress upstream); unlike it, agents DNAT here, never to the
-# orchestrator, so a breached agent has no L3 route to the control plane.
-GW_IFACE = _cfg("BOT_BOTTLE_FC_GW_IFACE")
-
 
 def pool_size() -> int:
     return int(_cfg("BOT_BOTTLE_FC_POOL_SIZE"))
@@ -101,10 +88,10 @@ def ip_base() -> str:
     return _cfg("BOT_BOTTLE_FC_IP_BASE")
 
 
-# Gateway ports the VM reaches at its host-side TAP IP. Kept in sync
+# Sidecar 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.
-GATEWAY_PORTS = (9099, 9100, 9420)
+SIDECAR_PORTS = (9099, 9100, 9420)
 
 
 @dataclass(frozen=True)
@@ -136,44 +123,6 @@ def all_slots() -> list[Slot]:
     return [slot(i) for i in range(pool_size())]
 
 
-def orch_slot() -> Slot:
-    """The orchestrator VM's dedicated link — its own TAP (`ORCH_IFACE`)
-    on a /31 at the TOP of the IP_BASE /16 (host x.y.255.0, guest
-    x.y.255.1), well clear of the agent pool near the bottom of the
-    block. Unlike a pool `Slot`, this link is NAT'd out to the internet
-    by the setup (the orchestrator is trusted infra), so it is
-    deliberately *not* one of the isolated `bbfc*` slots.
-
-    `index` is -1 (sentinel: not a pool index)."""
-    base16 = int(ipaddress.IPv4Address(ip_base())) & 0xFFFF0000
-    host = base16 + 0xFF00
-    return Slot(
-        index=-1,
-        iface=ORCH_IFACE,
-        host_ip=str(ipaddress.IPv4Address(host)),
-        guest_ip=str(ipaddress.IPv4Address(host + 1)),
-    )
-
-
-def gw_slot() -> Slot:
-    """The gateway (data-plane) VM's dedicated link — its own TAP
-    (`GW_IFACE`) on the /31 immediately above the orchestrator link (host
-    x.y.255.2, guest x.y.255.3), still clear of the agent pool at the
-    bottom of the block. Mirrors `orch_slot`: NAT'd to the internet (the
-    gateway forwards agent egress upstream), not one of the isolated
-    `bbfc*` slots. Agents DNAT their gateway-port traffic to this guest.
-
-    `index` is -2 (sentinel: not a pool index)."""
-    base16 = int(ipaddress.IPv4Address(ip_base())) & 0xFFFF0000
-    host = base16 + 0xFF02
-    return Slot(
-        index=-2,
-        iface=GW_IFACE,
-        host_ip=str(ipaddress.IPv4Address(host)),
-        guest_ip=str(ipaddress.IPv4Address(host + 1)),
-    )
-
-
 # --- fail-closed verification ---------------------------------------
 
 def _run_ok(argv: list[str]) -> bool:

bot_bottle/backend/firecracker/orchestrator.py

@@ -1,159 +0,0 @@
-"""The Firecracker orchestrator (control plane) as a microVM (PRD 0070).
-
-`FirecrackerOrchestrator` is the Firecracker implementation of the backend-neutral
-`Orchestrator` service, and owns the control plane's host-side logic directly:
-booting the orchestrator microVM on its NAT'd link with the persistent registry
-volume (/dev/vdb — the sole opener of `bot-bottle.db`), seeding the host-canonical
-signing key over SSH, and waiting for `/health`. The host CLI reaches it at its
-guest IP, and so does the gateway (`bb_orch` cmdline), so `url()` == `gateway_url()`.
-
-The plane-agnostic VM substrate the gateway VM also uses stays in `infra_vm` —
-booting a VM from a per-plane rootfs (`boot_vm`), the stable SSH keypair, the
-secret-push retry, the PID lifecycle, the adoption/version helpers, and the
-per-plane guest inits (`role_init`). The pair coordinator (adopt-or-boot-both
-under a singleton flock) is `FirecrackerInfraService` (`infra.py`).
-"""
-
-from __future__ import annotations
-
-import subprocess
-import time
-from pathlib import Path
-
-from ...log import die, info
-from ...orchestrator.lifecycle import (
-    DEFAULT_STARTUP_TIMEOUT_SECONDS,
-    Orchestrator,
-)
-from . import firecracker_vm, infra_vm, netpool
-from .infra_vm import ORCHESTRATOR_PORT
-
-# The orchestrator microVM's name (its run dir). Fixed per host — one
-# control-plane VM.
-ORCHESTRATOR_NAME = "bot-bottle-orchestrator"
-
-# Memory ceiling (fixed at boot, demand-paged). The orchestrator keeps the build
-# headroom (buildah's 2-4 GB working set during in-VM agent builds) — PRD 0070
-# "Memory: fixed ceilings".
-_ORCH_MEM_MIB = 4096
-
-_HEALTH_POLL_SECONDS = 0.5
-
-# The registry "volume": a host-side ext4 file attached to the orchestrator VM as
-# a second virtio-block device (guest /dev/vdb), mounted at the control plane's DB
-# dir. It outlives the ephemeral rootfs, so the bottle registry survives an
-# orchestrator-VM restart — the firecracker analogue of a docker volume. A plain
-# ext4 file: `sudo mount -o loop <path>` on the host (VM stopped) to inspect
-# bot-bottle.db. The gateway VM has no such volume — the data plane never opens
-# the DB (#469).
-_REGISTRY_SIZE = "512M"
-
-
-def registry_volume_path() -> Path:
-    return infra_vm._infra_dir() / "registry.ext4"
-
-
-class FirecrackerOrchestrator(Orchestrator):
-    """The control plane as a Firecracker microVM on the orchestrator link.
-
-    The orchestrator rootfs is built/downloaded by `infra_vm.ensure_built` (the
-    ABC's `ensure_built` no-op here); `ensure_running` boots the VM, seeds the
-    signing key, and blocks until `/health` answers."""
-
-    name = ORCHESTRATOR_NAME
-
-    def __init__(self, vm: infra_vm.InfraVm | None = None) -> None:
-        # The live VM handle when this process booted it; None when adapting an
-        # already-running orchestrator (health/URL go through the fixed link).
-        self._vm = vm
-
-    def url(self) -> str:
-        """The orchestrator VM's guest IP URL — where the host CLI reaches the
-        control plane."""
-        return f"http://{netpool.orch_slot().guest_ip}:{ORCHESTRATOR_PORT}"
-
-    def gateway_url(self) -> str:
-        """Same guest IP the host uses — the gateway resolves the orchestrator at
-        `bb_orch=<guest_ip>` off its cmdline."""
-        return self.url()
-
-    def ssh_target(self) -> tuple[Path, str]:
-        """(private key, guest IP) for SSHing into the orchestrator VM. In-VM
-        agent-image builds (buildah) run here — the build host drives them over
-        SSH with the stable infra key."""
-        return infra_vm._infra_dir() / "id_ed25519", netpool.orch_slot().guest_ip
-
-    def is_running(self) -> bool:
-        return infra_vm._pidfile_alive(infra_vm._orch_dir())
-
-    def stop(self) -> None:
-        """Stop only the orchestrator VM (idempotent). A dead orchestrator fails
-        `infra_vm.adoptable`'s health check, so no version marker to clear."""
-        infra_vm._kill_pidfile(infra_vm._orch_dir())
-        infra_vm._pid_file(infra_vm._orch_dir()).unlink(missing_ok=True)
-
-    def ensure_running(
-        self, *, startup_timeout: float = DEFAULT_STARTUP_TIMEOUT_SECONDS,
-    ) -> None:
-        """Boot the orchestrator VM on its link with the persistent registry
-        volume, seed the signing key over SSH, and block until `/health` answers.
-        Idempotent — a live, healthy control plane is left alone (the pair
-        coordinator otherwise `stop()`s it before calling, so this boots fresh)."""
-        if self.is_running() and self.is_healthy():
-            return
-        vm = infra_vm.boot_vm(
-            name=ORCHESTRATOR_NAME, slot=netpool.orch_slot(),
-            run_dir=infra_vm._orch_dir(), role="orchestrator", mem_mib=_ORCH_MEM_MIB,
-            data_drive=self._ensure_registry_volume(),
-        )
-        # Push the host-canonical signing key (the init waits for it before
-        # starting the control plane). It comes through the shared provisioning
-        # contract (#476) — the same host token file every backend uses, so a
-        # co-running docker/macOS control plane keeps working and the guest
-        # verifies tokens with the same key the CLI signs from; fail-closed, so
-        # the guest is never handed an empty key that would run it OPEN.
-        infra_vm.push_secret(
-            vm, self.control_plane_key(), infra_vm._GUEST_SIGNING_KEY_PATH,
-            "the control-plane signing key to the orchestrator VM "
-            "(its control plane will not start)",
-        )
-        self._vm = vm
-        self._wait_for_health(vm, timeout=startup_timeout)
-
-    def _wait_for_health(
-        self, vm: infra_vm.InfraVm, *, timeout: float,
-    ) -> None:
-        """Poll `/health` until it answers 200 or the deadline passes. Dies (with
-        the console tail) if the VMM exits early."""
-        url = f"{self.url()}/health"
-        deadline = time.monotonic() + timeout
-        while time.monotonic() < deadline:
-            if vm.vm is not None and not vm.vm.is_alive():
-                die(f"orchestrator VM exited during boot (rc={vm.vm.process.returncode}).\n"
-                    f"{firecracker_vm._console_tail(vm.vm.console_log)}")
-            if self.is_healthy():
-                info(f"orchestrator control plane healthy at {self.url()}")
-                return
-            time.sleep(_HEALTH_POLL_SECONDS)
-        tail = (firecracker_vm._console_tail(vm.vm.console_log)
-                if vm.vm is not None else "")
-        die(f"orchestrator control plane at {url} did not become healthy within "
-            f"{timeout:.0f}s.\n{tail}")
-
-    def _ensure_registry_volume(self) -> Path:
-        """Create the empty ext4 registry volume on first use; reuse it after."""
-        vol = registry_volume_path()
-        if vol.exists():
-            return vol
-        info(f"creating infra registry volume {vol} ({_REGISTRY_SIZE})")
-        proc = subprocess.run(
-            ["mke2fs", "-q", "-t", "ext4", "-F", str(vol), _REGISTRY_SIZE],
-            capture_output=True, text=True, check=False,
-        )
-        if proc.returncode != 0:
-            vol.unlink(missing_ok=True)
-            die(f"creating registry volume failed: {proc.stderr.strip()}")
-        return vol
-
-
-__all__ = ["FirecrackerOrchestrator", "ORCHESTRATOR_NAME", "registry_volume_path"]

bot_bottle/backend/firecracker/publish_infra.py

@@ -1,263 +0,0 @@
-"""Build the infra rootfs artifacts and publish them as Gitea generic packages.
-
-The off-host (build / CI) half of PRD 0069 Stage 2: this DOES use Docker, but
-never on the launch host. It runs the same pipeline the launch host used to run
-locally — `docker build` the fixed images, export each per-plane rootfs, inject
-the guest boot, `mke2fs` to an ext4 — then gzips each and PUTs it (plus a
-`.sha256`) to `…/api/packages/<owner>/generic/bot-bottle-firecracker-<role>/<version>/`.
-
-There are two artifacts, one per plane (`orchestrator`, `gateway`); the
-orchestrator rootfs carries buildah, the gateway rootfs is slim. Each
-`<version>` is `infra_artifact.infra_artifact_version(...)`, the content hash of
-that rootfs's inputs, so a launch host at the same code checkout resolves the
-exact artifacts this produced.
-
-  python3 -m bot_bottle.backend.firecracker.publish_infra --output DIR
-  python3 -m bot_bottle.backend.firecracker.publish_infra --publish-dir DIR
-
-A candidate bundle holds each role under its own `DIR/<role>/` subdir. Auth: a
-token with `write:package` on the target owner, from
-`BOT_BOTTLE_INFRA_ARTIFACT_TOKEN`.
-"""
-
-from __future__ import annotations
-
-import argparse
-import gzip
-import hashlib
-import shutil
-import sys
-import urllib.error
-import urllib.request
-from pathlib import Path
-
-from . import infra_artifact, infra_vm, util
-
-_CHUNK = 1 << 20
-
-_GZ_NAME = "rootfs.ext4.gz"
-_SHA_NAME = "rootfs.ext4.gz.sha256"
-
-# A human-readable description shipped alongside each artifact — generic packages
-# have no description field, so this file *is* the description on the package
-# page. Uploaded on every publish so it never goes stale.
-_ABOUT_NAME = "about.txt"
-
-
-def _about_text(role: str) -> str:
-    return (
-        f"bot-bottle firecracker {role} rootfs (PRD 0069 Stage 2 / PRD 0070): "
-        f"the per-host {role} infra VM. Prebuilt off-host, gzip ext4; the launch "
-        f"host downloads + sha256-verifies + boots it, no host Docker. The "
-        f"version tag is a content hash of the rootfs inputs. Files: "
-        f"{_GZ_NAME} + {_SHA_NAME}.\n"
-    )
-
-
-def _role_version(role: str) -> str:
-    return infra_artifact.infra_artifact_version(infra_vm.role_init(role), role)
-
-
-def _gzip(src: Path, dest: Path) -> None:
-    with open(src, "rb") as fh, gzip.open(dest, "wb") as out:
-        shutil.copyfileobj(fh, out, _CHUNK)
-
-
-def _sha256(path: Path) -> str:
-    h = hashlib.sha256()
-    with open(path, "rb") as fh:
-        for chunk in iter(lambda: fh.read(_CHUNK), b""):
-            h.update(chunk)
-    return h.hexdigest()
-
-
-def _put(url: str, body: "bytes | Path", token: str) -> None:
-    """PUT `body` (raw bytes, or a Path streamed from disk) to `url`. The rootfs
-    is hundreds of MB, so it is passed as a Path and streamed — `urlopen` reads
-    the open file in blocks rather than materializing it in memory (with an
-    explicit Content-Length, which Gitea requires and which also stops urllib
-    from `len()`-ing a non-bytes body)."""
-    handle = None
-    if isinstance(body, Path):
-        length = body.stat().st_size
-        handle = open(body, "rb")
-        data: object = handle
-    else:
-        length = len(body)
-        data = body
-    req = urllib.request.Request(url, data=data, method="PUT")  # type: ignore[arg-type]
-    req.add_header("Content-Length", str(length))
-    if token:
-        req.add_header("Authorization", f"token {token}")
-    req.add_header("Content-Type", "application/octet-stream")
-    try:
-        with urllib.request.urlopen(req) as resp:
-            print(f"  uploaded {url} (HTTP {resp.status})")
-    except urllib.error.HTTPError as e:
-        if e.code == 409:
-            raise SystemExit(
-                f"artifact already published at {url} (HTTP 409); "
-                f"bump the code version or pass --force to overwrite"
-            )
-        raise SystemExit(f"upload failed (HTTP {e.code}): {url}\n{e.read().decode(errors='replace')}")
-    except urllib.error.URLError as e:
-        raise SystemExit(f"registry unreachable: {url} ({e.reason})")
-    finally:
-        if handle is not None:
-            handle.close()
-
-
-def _delete(url: str, token: str) -> None:
-    req = urllib.request.Request(url, method="DELETE")
-    if token:
-        req.add_header("Authorization", f"token {token}")
-    try:
-        with urllib.request.urlopen(req):
-            pass
-    except urllib.error.HTTPError as e:
-        if e.code != 404:
-            raise SystemExit(f"could not overwrite existing artifact (HTTP {e.code}): {url}")
-    except urllib.error.URLError as e:
-        raise SystemExit(f"registry unreachable: {url} ({e.reason})")
-
-
-def build_role_artifact(role: str, role_dir: Path) -> str:
-    """Build `role`'s rootfs ext4, gzip it, and write the checksum + version into
-    `role_dir`. Returns the version. Assumes the docker images are already
-    built (`infra_vm.build_infra_images_with_docker`). Uses host Docker."""
-    version = _role_version(role)
-    print(f"building {role} rootfs artifact {version} (docker)")
-    base = infra_vm.build_rootfs_dir(role)
-
-    ext4 = role_dir / "rootfs.ext4"
-    util.build_rootfs_ext4(base, ext4, slack_mib=infra_vm._ROOTFS_SLACK_MIB[role])
-    gz = role_dir / _GZ_NAME
-    print(f"compressing {role} rootfs")
-    _gzip(ext4, gz)
-    ext4.unlink(missing_ok=True)
-
-    sha = role_dir / _SHA_NAME
-    digest = _sha256(gz)
-    sha.write_text(f"{digest}  {_GZ_NAME}\n")
-    (role_dir / "version.txt").write_text(version + "\n", encoding="utf-8")
-    print(f"  {role}/{gz.name}: {gz.stat().st_size / 1e6:.0f} MB  sha256={digest}")
-    return version
-
-
-def _try_download_published(role: str, role_dir: Path) -> str | None:
-    """If `role`'s artifact for this version is already in the registry, download
-    the gz + sha into `role_dir` and return the version. None when not yet
-    published."""
-    version = _role_version(role)
-    sha_url = infra_artifact.artifact_url(version, _SHA_NAME, role=role)
-    try:
-        with urllib.request.urlopen(infra_artifact._open(sha_url)):
-            pass
-    except urllib.error.HTTPError as e:
-        if e.code == 404:
-            return None
-        raise SystemExit(f"registry check failed (HTTP {e.code}): {sha_url}")
-    except urllib.error.URLError as e:
-        raise SystemExit(f"registry unreachable: {sha_url} ({e.reason})")
-    print(f"{role} rootfs {version} already published — downloading instead of building")
-    infra_artifact._download(
-        infra_artifact.artifact_url(version, _GZ_NAME, role=role), role_dir / _GZ_NAME)
-    infra_artifact._download(sha_url, role_dir / _SHA_NAME)
-    (role_dir / "version.txt").write_text(version + "\n", encoding="utf-8")
-    return version
-
-
-def _publish_bundle(role: str, role_dir: Path, token: str) -> str:
-    version_file = role_dir / "version.txt"
-    # Guard the read so a missing version.txt is a clean error, not a raw
-    # FileNotFoundError.
-    if not version_file.is_file():
-        raise SystemExit(f"incomplete {role} artifact bundle: {role_dir}")
-    version = version_file.read_text(encoding="utf-8").strip()
-    expected = _role_version(role)
-    if version != expected:
-        raise SystemExit(
-            f"{role} artifact bundle version {version!r} does not match checkout {expected!r}"
-        )
-    gz = role_dir / _GZ_NAME
-    sha = role_dir / _SHA_NAME
-    if not gz.is_file() or not sha.is_file():
-        raise SystemExit(f"incomplete {role} artifact bundle: {role_dir}")
-    expected_sha = sha.read_text().split()[0].strip().lower()
-    if _sha256(gz) != expected_sha:
-        raise SystemExit(f"{role} artifact bundle checksum mismatch")
-
-    gz_url = infra_artifact.artifact_url(version, _GZ_NAME, role=role)
-    sha_url = infra_artifact.artifact_url(version, _SHA_NAME, role=role)
-    about_url = infra_artifact.artifact_url(version, _ABOUT_NAME, role=role)
-
-    # Publishing is idempotent. If this exact complete artifact is already
-    # present, a re-publish is a no-op. Otherwise clear any partial upload left
-    # by an interrupted prior attempt and upload the complete set.
-    try:
-        with urllib.request.urlopen(infra_artifact._open(sha_url)) as resp:
-            remote_sha = resp.read().decode("utf-8").split()[0].strip().lower()
-    except urllib.error.HTTPError as e:
-        if e.code != 404:
-            raise SystemExit(f"checking existing {role} artifact failed (HTTP {e.code})")
-        remote_sha = ""
-    except urllib.error.URLError as e:
-        raise SystemExit(f"registry unreachable: {sha_url} ({e.reason})")
-    if remote_sha == expected_sha:
-        print(f"{role} rootfs {version} already published")
-        return version
-
-    for url in (gz_url, sha_url, about_url):
-        _delete(url, token)
-    _put(gz_url, gz, token)
-    _put(sha_url, sha.read_bytes(), token)
-    _put(about_url, _about_text(role).encode(), token)
-    return version
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        prog="publish_infra", description="Build + publish the infra rootfs artifacts.")
-    mode = parser.add_mutually_exclusive_group(required=True)
-    mode.add_argument("--output", type=Path,
-                      help="build candidate bundles in DIR/<role>/ without publishing")
-    mode.add_argument("--publish-dir", type=Path,
-                      help="publish already-built + tested candidate bundles under DIR")
-    parser.add_argument("--reuse-published", action="store_true",
-                        help="with --output: download from registry if already published instead of building")
-    args = parser.parse_args(argv)
-
-    _, _, token = infra_artifact._config()
-    if args.publish_dir is not None and not token:
-        raise SystemExit(
-            "no publish token: set BOT_BOTTLE_INFRA_ARTIFACT_TOKEN to a token "
-            "with write:package")
-
-    if args.output is not None:
-        # Build (or reuse) all roles. Images are built once, up front, only when
-        # something actually needs building.
-        pending = []
-        for role in infra_artifact.ROLES:
-            role_dir = args.output / role
-            role_dir.mkdir(parents=True, exist_ok=True)
-            if args.reuse_published and _try_download_published(role, role_dir):
-                print(f"reused published {role} rootfs candidate")
-                continue
-            pending.append(role)
-        if pending:
-            print("building infra images (docker)")
-            infra_vm.build_infra_images_with_docker()
-            for role in pending:
-                build_role_artifact(role, args.output / role)
-                print(f"built {role} rootfs candidate")
-        return 0
-
-    assert args.publish_dir is not None
-    for role in infra_artifact.ROLES:
-        version = _publish_bundle(role, args.publish_dir / role, token)
-        print(f"published {role} rootfs {version}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

bot_bottle/backend/firecracker/resolve_plan.py

@@ -9,7 +9,7 @@ from ...egress import EgressPlan
 from ...env import ResolvedEnv
 from ...git_gate import GitGatePlan
 from ...manifest import Manifest
-from ...supervisor.plan import SupervisePlan
+from ...supervise import SupervisePlan
 from .. import BottleSpec
 from . import util
 from .bottle_plan import FirecrackerBottlePlan

bot_bottle/backend/firecracker/setup.py

@@ -13,20 +13,15 @@ generic `./cli.py backend {setup,status}` command dispatches to.
 
 from __future__ import annotations
 
-import fcntl
 import os
 import shutil
 import subprocess
 import sys
 from pathlib import Path
 
-from ... import resources
 from . import netpool
 from . import util
 
-# KVM_GET_API_VERSION = _IO(KVMIO=0xAE, 0x00): cheapest proof of KVM access.
-_KVM_GET_API_VERSION = 0xAE00
-
 
 _FC_RELEASES = "https://github.com/firecracker-microvm/firecracker/releases"
 _UNIT_PATH = Path("/etc/systemd/system") / netpool.SYSTEMD_UNIT
@@ -43,13 +38,13 @@ def _has_systemd() -> bool:
 
 
 def _module_path() -> str:
-    """Absolute path to the importable NixOS module (checkout or wheel)."""
-    return str(resources.nix_netpool_module())
+    """Absolute path to the importable NixOS module in this checkout."""
+    return str(Path(__file__).resolve().parents[3] / "nix" / "firecracker-netpool.nix")
 
 
 def _script_path() -> str:
-    """Absolute path to the bundled bring-up script (checkout or wheel)."""
-    return str(resources.netpool_script())
+    """Absolute path to the bundled bring-up script in this checkout."""
+    return str(Path(__file__).resolve().parents[3] / "scripts" / "firecracker-netpool.sh")
 
 
 def _print_prereqs() -> None:
@@ -224,90 +219,14 @@ def teardown() -> int:
     return 0
 
 
-def _firecracker_binary_ok() -> bool:
-    """True iff the firecracker binary is on PATH and `--version` exits 0."""
-    if shutil.which("firecracker") is None:
-        return False
-    try:
-        return subprocess.run(
-            ["firecracker", "--version"],
-            capture_output=True, check=False, timeout=5,
-        ).returncode == 0
-    except (OSError, subprocess.TimeoutExpired):
-        return False
-
-
-def _kvm_accessible() -> bool:
-    """True iff /dev/kvm can be opened read-write and responds to KVM_GET_API_VERSION.
-
-    VM creation requires write access; opening read-only may satisfy the
-    ioctl but fails at boot time, so O_RDWR is the permission check."""
-    if not os.path.exists(util._KVM_DEVICE):
-        return False
-    try:
-        fd = os.open(util._KVM_DEVICE, os.O_RDWR | os.O_CLOEXEC)
-        try:
-            fcntl.ioctl(fd, _KVM_GET_API_VERSION)
-        finally:
-            os.close(fd)
-        return True
-    except OSError:
-        return False
-
-
 def status() -> int:
-    # Readiness == what the launch preflight hard-requires: the binary
-    # executable, /dev/kvm accessible, the TAP pool present, and no range
-    # overlap. Listing the nft table usually needs root, so — like the
-    # preflight — an unconfirmable table is reported but NOT treated as
-    # not-ready; the post-boot isolation probe is the authoritative check.
-    # This keeps an unprivileged `backend status` usable as a launch gate.
+    # Readiness == what the launch preflight hard-requires: the TAP pool
+    # present (unprivileged, authoritative) and no range overlap. Listing
+    # the nft table usually needs root, so — like the preflight — an
+    # unconfirmable table is reported but NOT treated as not-ready; the
+    # post-boot isolation probe is the authoritative check. This keeps an
+    # unprivileged `backend status` usable as a launch gate.
     ok = True
-    if _firecracker_binary_ok():
-        sys.stderr.write(f"firecracker binary: ok ({shutil.which('firecracker')})\n")
-    else:
-        fc_path = shutil.which("firecracker")
-        if fc_path is None:
-            sys.stderr.write("firecracker binary: NOT found on PATH\n")
-        else:
-            sys.stderr.write(
-                f"firecracker binary: found ({fc_path}) but `--version` failed\n"
-            )
-        ok = False
-    if _kvm_accessible():
-        sys.stderr.write(f"KVM: {util._KVM_DEVICE} accessible\n")
-    else:
-        if not os.path.exists(util._KVM_DEVICE):
-            sys.stderr.write(f"KVM: {util._KVM_DEVICE} not present\n")
-        else:
-            sys.stderr.write(
-                f"KVM: {util._KVM_DEVICE} not accessible (open/ioctl failed)\n"
-            )
-        ok = False
-    kernel = util.kernel_path()
-    if kernel.is_file():
-        sys.stderr.write(f"guest kernel: {kernel}\n")
-    else:
-        sys.stderr.write(
-            f"guest kernel: NOT found at {kernel} "
-            f"(set BOT_BOTTLE_FC_KERNEL or cache a vmlinux there)\n"
-        )
-        ok = False
-    dropbear = util.dropbear_path()
-    if dropbear.is_file():
-        sys.stderr.write(f"dropbear: {dropbear}\n")
-    else:
-        sys.stderr.write(
-            f"dropbear: NOT found at {dropbear} "
-            f"(set BOT_BOTTLE_FC_DROPBEAR or cache a static binary)\n"
-        )
-        ok = False
-    mke2fs = shutil.which("mke2fs")
-    if mke2fs is not None:
-        sys.stderr.write(f"mke2fs: {mke2fs}\n")
-    else:
-        sys.stderr.write("mke2fs: NOT found on PATH (install e2fsprogs)\n")
-        ok = False
     missing = netpool.missing_taps()
     total = netpool.pool_size()
     if missing:

bot_bottle/backend/firecracker/util.py

@@ -14,7 +14,6 @@ and `./cli.py backend setup --backend=firecracker`.
 
 from __future__ import annotations
 
-import hashlib
 import os
 import platform
 import shutil
@@ -88,7 +87,7 @@ def require_firecracker() -> None:
     booting a VM without it."""
     if not is_linux():
         die("firecracker backend is only supported on Linux (KVM). "
-            "On macOS use the macos-container backend.")
+            "On macOS use --backend=macos-container.")
     if shutil.which("firecracker") is None:
         info("Firecracker is required but was not found on PATH.")
         info("Install: https://github.com/firecracker-microvm/firecracker/releases")
@@ -160,22 +159,15 @@ def docker_image_id(ref: str) -> str:
     return result.stdout.strip().replace("sha256:", "")[:16]
 
 
-def build_base_rootfs_dir(
-    image_ref: str, *, variant: str = "", init_script: str | None = None,
-) -> Path:
-    """Export the image's filesystem and inject the guest init + static
-    dropbear. Cached by image digest — the per-bottle bits
+def build_base_rootfs_dir(image_ref: str) -> Path:
+    """Export the agent image's filesystem and inject the guest init +
+    static dropbear. Cached by image digest — the per-bottle bits
     (authorized_keys, IP) are passed at boot via the kernel cmdline, so
     this tree carries nothing bottle-specific and is safely shared.
 
-    `variant` suffixes the cache key so the same image can be prepared
-    with a different `init_script` (e.g. the infra VM boots the same
-    orchestrator image as the builder but runs the control plane as
-    PID 1, not the SSH-only agent init) without a cache collision.
-
     Returns the prepared directory (read as the `mke2fs -d` source)."""
     digest = docker_image_id(image_ref)
-    base = cache_dir() / "rootfs" / f"{digest}{variant}"
+    base = cache_dir() / "rootfs" / digest
     ready = base / ".bb-ready"
     if ready.is_file():
         return base
@@ -208,85 +200,18 @@ def build_base_rootfs_dir(
             stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
         )
 
-    inject_guest_boot(base, init_script=init_script)
+    _inject_guest_boot(base)
     ready.write_text("ok\n")
     return base
 
 
-def build_committed_rootfs_dir(tar_path: Path) -> Path:
-    """Prepare a base rootfs dir from a frozen-bottle snapshot tar (the
-    freeze/resume path — no Docker). Extracts the snapshot, recreates the
-    virtual mount points the freezer excluded, and injects the guest init +
-    static dropbear, mirroring `build_base_rootfs_dir` but sourced from a tar
-    we control rather than a Docker image.
-
-    Cached under the rootfs cache, keyed by the tar's size+mtime so a
-    re-freeze re-extracts but repeated resumes of the same snapshot don't.
-    Returns the prepared directory (read as the `mke2fs -d` source)."""
-    st = tar_path.stat()
-    fingerprint = hashlib.sha256(
-        f"{tar_path}:{st.st_size}:{st.st_mtime_ns}".encode()
-    ).hexdigest()[:16]
-    base = cache_dir() / "rootfs" / f"committed-{fingerprint}"
-    ready = base / ".bb-ready"
-    if ready.is_file():
-        return base
-
-    if base.exists():
-        shutil.rmtree(base, ignore_errors=True)
-    base.mkdir(parents=True)
-
-    info(f"extracting committed rootfs {tar_path} -> {base}")
-    result = subprocess.run(
-        ["tar", "-x", "-f", str(tar_path), "-C", str(base)],
-        capture_output=True, text=True, check=False,
-    )
-    if result.returncode != 0:
-        die(f"extracting committed rootfs {tar_path} failed: "
-            f"{result.stderr.strip() or '<no stderr>'}")
-
-    # The freezer excludes the live/virtual filesystems from the snapshot;
-    # recreate them as empty mount points so the guest init can mount
-    # proc/sys/dev and dropbear has a writable /run.
-    for mount_point in ("proc", "sys", "dev", "run"):
-        (base / mount_point).mkdir(mode=0o755, exist_ok=True)
-
-    inject_guest_boot(base)
-    ready.write_text("ok\n")
-    return base
-
-
-def inject_guest_boot(rootfs: Path, init_script: str | None = None) -> None:
-    """Drop the static dropbear and the PID-1 init into the rootfs.
-    `init_script` defaults to the SSH-only agent init; each infra VM
-    passes its own per-plane init (orchestrator or gateway).
-
-    A committed snapshot is guest-controlled, so `bb-dropbear`/`bb-init`
-    may already exist as symlinks aimed at a host file (e.g. bb-init ->
-    ~/.bashrc). Replace whatever is there and create the files with
-    O_EXCL|O_NOFOLLOW so the write always lands a fresh regular file in
-    the staging tree and never follows a planted symlink out of it."""
-    _write_staged_file(rootfs / "bb-dropbear", dropbear_path().read_bytes())
-    _write_staged_file(rootfs / "bb-init", (init_script or _GUEST_INIT).encode())
-
-
-def _write_staged_file(path: Path, data: bytes) -> None:
-    """Write `data` to `path` (mode 0755) as a fresh regular file inside a
-    staging rootfs, replacing any pre-existing entry without following a
-    symlink at `path`. Fails closed on anything unexpected there."""
-    if path.is_symlink() or path.exists():
-        if path.is_dir() and not path.is_symlink():
-            shutil.rmtree(path)
-        else:
-            path.unlink()
-    fd = os.open(
-        path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o755
-    )
-    try:
-        os.write(fd, data)
-    finally:
-        os.close(fd)
-    os.chmod(path, 0o755)
+def _inject_guest_boot(rootfs: Path) -> None:
+    """Drop the static dropbear and the PID-1 init into the rootfs."""
+    shutil.copy2(dropbear_path(), rootfs / "bb-dropbear")
+    os.chmod(rootfs / "bb-dropbear", 0o755)
+    init = rootfs / "bb-init"
+    init.write_text(_GUEST_INIT)
+    os.chmod(init, 0o755)
 
 
 def build_rootfs_ext4(base_dir: Path, out_path: Path, *, slack_mib: int = 1024) -> None:
@@ -368,17 +293,6 @@ mount -t devtmpfs dev /dev 2>/dev/null
 mkdir -p /dev/pts && mount -t devpts devpts /dev/pts 2>/dev/null
 mount -o remount,rw / 2>/dev/null
 
-# /tmp must be world-writable + sticky. The rootless rootfs build can land
-# it 0755/root-owned, leaving the agent (uid 1000 node) unable to create
-# scratch dirs there — git worktrees, build temp, `git init /tmp/...`, etc.
-mkdir -p /tmp && chmod 1777 /tmp
-
-# Rootfs export also maps the image's original owners to the unprivileged
-# host build uid. That uid is not guaranteed to be node's uid in the guest;
-# restore the home-directory boundary before any SSH provisioning runs.
-chown node:node /home/node 2>/dev/null || true
-chmod 755 /home/node 2>/dev/null || true
-
 # Install the per-bottle SSH pubkey from the kernel cmdline.
 KEY=$(sed -n 's/.*bb_pubkey=\([^ ]*\).*/\1/p' /proc/cmdline | base64 -d 2>/dev/null)
 if [ -n "$KEY" ]; then
@@ -399,9 +313,6 @@ fi
 chown -R 0:0 /root 2>/dev/null || true
 
 mkdir -p /etc/dropbear /run
-# Keep restart-recovery key material memory-backed, separate from both the
-# agent rootfs and the infra VM's persistent registry volume.
-mount -t tmpfs -o mode=0755 tmpfs /run 2>/dev/null || true
 # -R: generate host keys on demand. -E: log auth failures to stderr,
 # captured in the host-side console.log for debugging.
 /bb-dropbear -R -E -p 22 &

bot_bottle/backend/infra_service.py

@@ -1,58 +0,0 @@
-"""The per-host infra service contract (PRD 0070).
-
-`InfraService` is the backend-neutral composer of the per-host **pair**: the
-`Orchestrator` (control plane) + `Gateway` (data plane) services, brought up as
-an idempotent per-host singleton. One concrete impl per backend
-(`backend/*/infra.py`), mirroring how `Orchestrator` and `Gateway` each have a
-per-backend impl.
-
-The two backend-specific accessors (`orchestrator()` / `gateway()`) are the
-source of truth for how to reach each plane; the convenience `url()` /
-`is_healthy()` just delegate to the orchestrator.
-"""
-
-from __future__ import annotations
-
-import abc
-
-from ..gateway import Gateway
-from ..orchestrator.lifecycle import DEFAULT_STARTUP_TIMEOUT_SECONDS, Orchestrator
-
-
-class InfraService(abc.ABC):
-    """Compose + bring up the per-host orchestrator + gateway pair.
-
-    Backend-neutral: docker/macOS run the pair as two containers, firecracker as
-    two microVMs. Callers read reach-info off `orchestrator()` / `gateway()`."""
-
-    @abc.abstractmethod
-    def orchestrator(self) -> Orchestrator:
-        """The control-plane service. Cheap to reconstruct."""
-
-    @abc.abstractmethod
-    def gateway(self) -> Gateway:
-        """The data-plane service. Cheap to reconstruct."""
-
-    @abc.abstractmethod
-    def ensure_running(
-        self, *, startup_timeout: float = DEFAULT_STARTUP_TIMEOUT_SECONDS,
-    ) -> str:
-        """Bring the orchestrator + gateway pair up (idempotent per-host
-        singleton — a healthy, current pair is left running). Returns the host
-        control-plane URL. Raises `OrchestratorStartError` on control-plane
-        startup timeout."""
-
-    @abc.abstractmethod
-    def stop(self) -> None:
-        """Remove both the orchestrator and the gateway. Idempotent."""
-
-    def url(self) -> str:
-        """The host-facing control-plane URL the CLI reaches (the orchestrator's)."""
-        return self.orchestrator().url()
-
-    def is_healthy(self) -> bool:
-        """True iff the control plane answers `/health`."""
-        return self.orchestrator().is_healthy()
-
-
-__all__ = ["InfraService"]

bot_bottle/backend/macos_container/__init__.py

@@ -1,29 +1,10 @@
 """macOS Apple Container backend.
 
-Selectable via `BOT_BOTTLE_BACKEND=macos-container`. This package owns the Apple
-`container` CLI integration; launch remains gated until the gateway network
-enforcement shape is implemented.
-
-Thin by design: `MacosContainerBottleBackend` is re-exported lazily via
-`__getattr__`, so importing a leaf module under this package doesn't drag the
-backend (and the framework it pulls) into memory.
+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.
 """
 
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from .backend import MacosContainerBottleBackend
-
-
-def __getattr__(name: str) -> Any:
-    if name == "MacosContainerBottleBackend":
-        from .backend import MacosContainerBottleBackend
-
-        globals()[name] = MacosContainerBottleBackend
-        return MacosContainerBottleBackend
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-
+from .backend import MacosContainerBottleBackend
 
 __all__ = ["MacosContainerBottleBackend"]

bot_bottle/backend/macos_container/backend.py

@@ -2,8 +2,7 @@
 
 from __future__ import annotations
 
-import io
-from contextlib import contextmanager, redirect_stderr
+from contextlib import contextmanager
 from pathlib import Path
 from typing import Generator, Sequence
 
@@ -11,9 +10,9 @@ from ...agent_provider import AgentProvisionPlan
 from ...egress import EgressPlan
 from ...env import ResolvedEnv
 from ...git_gate import GitGatePlan
-from ...supervisor.plan import SupervisePlan
+from ...supervise import SupervisePlan
 from ...manifest import Manifest
-from .. import ActiveAgent, BottleBackend, BottleImages, BottleSpec
+from .. import ActiveAgent, BottleBackend, BottleSpec
 from . import cleanup as _cleanup
 from . import enumerate as _enumerate
 from . import launch as _launch
@@ -32,7 +31,6 @@ class MacosContainerBottleBackend(
     `--backend=macos-container`."""
 
     name = "macos-container"
-    supports_nested_containers = True
 
     @classmethod
     def is_available(cls) -> bool:
@@ -44,11 +42,8 @@ class MacosContainerBottleBackend(
         return _setup.setup()
 
     @classmethod
-    def status(cls, *, quiet: bool = False) -> int:
+    def status(cls) -> int:
         from . import setup as _setup
-        if quiet:
-            with redirect_stderr(io.StringIO()):
-                return _setup.status()
         return _setup.status()
 
     @classmethod
@@ -87,27 +82,13 @@ class MacosContainerBottleBackend(
             stage_dir=stage_dir,
         )
 
-    def prelaunch_checks(self, plan: MacosContainerBottlePlan) -> None:
-        _launch.stale_checks(plan)
-
-    def _build_or_load_images(self, plan: MacosContainerBottlePlan) -> BottleImages:
-        return _launch.build_or_load_images(plan)
-
     @contextmanager
-    def _launch_impl(
-        self, plan: MacosContainerBottlePlan, images: BottleImages
+    def launch(
+        self, plan: MacosContainerBottlePlan
     ) -> Generator[MacosContainerBottle, None, None]:
-        with _launch.launch(plan, images, provision=self.provision) as bottle:
+        with _launch.launch(plan, provision=self.provision) as bottle:
             yield bottle
 
-    def ensure_orchestrator(self) -> str:
-        """Bring up the per-host pair (orchestrator + gateway containers) and
-        return its control-plane URL — the on-demand entry point operator tools
-        (`supervise`) call when no control plane is running yet. Mirrors
-        firecracker's infra bring-up."""
-        from .infra import MacosInfraService
-        return MacosInfraService().ensure_running()
-
     def prepare_cleanup(self) -> MacosContainerBottleCleanupPlan:
         return _cleanup.prepare_cleanup()
 

bot_bottle/backend/macos_container/bottle.py

@@ -52,7 +52,6 @@ class MacosContainerBottle(Bottle):
         terminal_title: str = "",
         terminal_color: str = "",
         agent_workdir: str = "/home/node",
-        exec_env: dict[str, str] | None = None,
     ):
         self.name = container
         self._teardown = teardown
@@ -63,20 +62,6 @@ class MacosContainerBottle(Bottle):
         self.terminal_color = terminal_color
         self.agent_provider_template = agent_provider_template
         self.agent_workdir = agent_workdir
-        # Env applied to the agent process at `container exec` time, on top of
-        # what the container was run with. This is how the identity token
-        # reaches the agent (PRD 0070): registration mints it *after* the
-        # container exists — its source IP is the registration key and Apple
-        # Container assigns that by DHCP — so it cannot be in the run-time env
-        # the way docker's compose spec does it.
-        #
-        # `container exec --env` does NOT override a run-time value — it
-        # appends, leaving duplicate entries in the agent's `environ` whose
-        # resolution is runtime-specific (Node last-wins, Rust first-wins). So
-        # nothing here may rely on superseding: the proxy vars are supplied
-        # *only* at exec time and are deliberately absent from the run-time
-        # env. See `launch._agent_env_entries`.
-        self._exec_env = dict(exec_env or {})
         self._closed = False
 
     def agent_argv(self, argv: list[str], *, tty: bool = True) -> list[str]:
@@ -89,12 +74,6 @@ class MacosContainerBottle(Bottle):
             )
         )
         container_exec = ["container", "exec"]
-        # Bare env names, same rule as the terminal hints below: the value
-        # stays in the child env `exec_agent` builds and never reaches argv —
-        # the proxy URL here carries the identity token, which `ps` would
-        # otherwise expose to every process on the host.
-        for name in sorted(self._exec_env):
-            container_exec.extend(["--env", name])
         if tty:
             container_exec.extend(["--interactive", "--tty"])
             # Forward terminal capability hints so TUIs can enable modified-key
@@ -115,33 +94,21 @@ class MacosContainerBottle(Bottle):
 
     def exec_agent(self, argv: list[str], *, tty: bool = True) -> int:
         agent_argv = self.agent_argv(argv, tty=tty)
-        # The values behind the bare `--env` names in `agent_argv`. `sh -lc`
-        # below is in this process tree, so the child env reaches `container
-        # exec` either way.
-        env = {**os.environ, **self._exec_env} if self._exec_env else None
         script = (
             exec_shell_script(agent_argv, self.terminal_title, self.terminal_color)
             if tty else None
         )
         if script is None:
-            return subprocess.run(agent_argv, env=env, check=False).returncode
-        return subprocess.run(["sh", "-lc", script], env=env, check=False).returncode
+            return subprocess.run(agent_argv, check=False).returncode
+        return subprocess.run(["sh", "-lc", script], check=False).returncode
 
     def exec(self, script: str, *, user: str = "node") -> ExecResult:
-        # Carry the same exec env the agent gets: provisioning steps run
-        # through here, and a provider whose provision step fetches anything
-        # would egress without the identity token and be denied by /resolve.
-        # Bare `--env NAME` again, so the token stays off argv.
-        argv = ["container", "exec", "--user", user, "--interactive"]
-        for name in sorted(self._exec_env):
-            argv.extend(["--env", name])
-        argv.extend([self.name, "sh", "-s"])
         result = subprocess.run(
-            argv,
+            ["container", "exec", "--user", user, "--interactive",
+             self.name, "sh", "-s"],
             input=script,
             capture_output=True,
             text=True,
-            env={**os.environ, **self._exec_env} if self._exec_env else None,
             check=False,
         )
         return ExecResult(

bot_bottle/backend/macos_container/bottle_plan.py

@@ -13,19 +13,9 @@ from .. import BottlePlan
 class MacosContainerBottlePlan(BottlePlan):
     slug: str
     forwarded_env: dict[str, str] = field(repr=False)
+    agent_proxy_url: str = ""
     agent_git_gate_url: str = ""
     agent_supervise_url: str = ""
-    # Read by provision-time consumers (git extraHeader, supervise MCP header)
-    # via getattr(plan, "identity_token", ""); stamped in launch after the
-    # bottle is registered. See launch.py's stamp for why it lives here and not
-    # only in the exec-time proxy env.
-    identity_token: str = ""
-    # Guest-local container engine (issue #392). Gates the derived image, the
-    # device-mode relaxation, and the resident podman service.
-    nested_containers: bool = False
-    # Generated before `container run` so it becomes part of the container's
-    # configured environment and can be read back after an infra restart.
-    env_var_secret: str = ""
 
     @property
     def container_name(self) -> str:

bot_bottle/backend/macos_container/cleanup.py

@@ -9,6 +9,7 @@ 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]:
@@ -23,7 +24,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)
+        if name.startswith(_PREFIX) or name.startswith(_BUNDLE_PREFIX)
     )
 
 

bot_bottle/backend/macos_container/consolidated_launch.py

@@ -1,209 +0,0 @@
-"""Consolidated bottle launch sequence for the macOS backend (PRD 0070).
-
-The docker backend allocates a free address, pins the agent to it with
-`--ip`, registers it, *then* starts the agent — registration precedes launch
-because the pinned address is known up front.
-
-**Apple Container 1.0.0 has no `--ip`.** The `--network` flag takes only
-`<name>[,mac=…][,mtu=…]`; the address is assigned by vmnet's DHCP and is
-knowable only once the container is running. So the macOS order inverts:
-
-    ensure_gateway()  ->  caller starts the agent  ->  register_agent(source_ip)
-
-That is why this module exposes two functions where docker has one — the
-caller has to start the agent in between. `ensure_gateway` runs first because
-the agent's proxy env needs the gateway's address at `container run` time; the
-agent's *own* address (the attribution key) only exists afterwards.
-
-The control plane and the gateway are **separate containers** here (see
-`infra`): the orchestrator on the host-only control network, the gateway on the
-agent network — `gateway_ip` is the gateway container's agent-network address,
-distinct from the orchestrator's control-network host.
-
-The consequence for the identity token: it is minted by registration, i.e.
-*after* the agent container exists, so it cannot be baked into the run-time
-env the way docker's compose spec does. It is delivered at `container exec`
-time instead — see `bottle.MacosContainerBottle`.
-
-That delivery is load-bearing, not a nicety: `/resolve` requires a matching
-`(source_ip, identity_token)` pair and fail-closes with no source-IP-only
-fallback (#366). So egress that does not carry the token is denied — which is
-the safe direction, and is why the agent's init process is a bare `sleep` and
-every real command arrives through `container exec`.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from ...egress import EgressPlan
-from ...git_gate import GitGatePlan
-from ...log import info
-from ...orchestrator.client import OrchestratorClient, OrchestratorClientError
-from ...orchestrator.reprovision import reprovision_bottles
-from ...orchestrator.store.secret_store import ENV_VAR_SECRET_NAME
-from ..provision_bottle import deprovision_bottle, provision_bottle
-from . import util as container_mod
-from .enumerate import CONTAINER_NAME_PREFIX, EnumerationError, enumerate_active
-from .gateway import GATEWAY_NETWORK
-from .gateway_transport import MacosGatewayTransport
-from .infra import MacosInfraService, OrchestratorStartError
-
-
-class ConsolidatedLaunchError(RuntimeError):
-    """The consolidated register/provision sequence could not complete."""
-
-
-@dataclass(frozen=True)
-class GatewayEndpoint:
-    """What the agent `container run` needs to reach the shared gateway.
-    `gateway_ip` is the gateway container's agent-network address (the agent's
-    proxy target); `orchestrator_url` points at the separate control plane."""
-
-    orchestrator_url: str
-    gateway_ip: str         # the gateway's address — the agent's proxy target
-    gateway_ca_pem: str     # the shared CA the provisioner installs
-    network: str            # the shared host-only network to attach to
-
-
-@dataclass(frozen=True)
-class LaunchContext:
-    """What the running agent needs once it has been registered."""
-
-    bottle_id: str
-    identity_token: str
-    source_ip: str          # the agent's DHCP-assigned address (attribution key)
-    gateway_ip: str
-    network: str
-    orchestrator_url: str
-    env_var_secret: str = ""  # encryption key injected into the agent's env
-
-
-def ensure_gateway(
-    *, service: MacosInfraService | None = None,
-) -> GatewayEndpoint:
-    """Ensure the per-host pair (orchestrator + gateway containers) is up and
-    report how to reach the gateway. Idempotent — one singleton pair, so N bottle
-    launches share it. Call before starting the agent container: the agent's
-    proxy env needs `gateway_ip` at run time."""
-    service = service or MacosInfraService()
-    orchestrator_url = service.ensure_running()
-    endpoint = GatewayEndpoint(
-        orchestrator_url=orchestrator_url,
-        gateway_ip=service.gateway().address(),
-        gateway_ca_pem=service.ca_cert_pem(),
-        network=service.network,
-    )
-    _reprovision_running_bottles(endpoint)
-    return endpoint
-
-
-def _reprovision_running_bottles(endpoint: GatewayEndpoint) -> None:
-    """Recover keys from live Apple containers and restore gateway tokens."""
-    try:
-        secrets_by_ip: dict[str, str] = {}
-        for agent in enumerate_active():
-            name = f"{CONTAINER_NAME_PREFIX}{agent.slug}"
-            source_ip = container_mod.inspect_container_network_ip(name, endpoint.network)
-            if not source_ip:
-                continue
-            secret = container_mod.read_container_env(name, ENV_VAR_SECRET_NAME)
-            if secret:
-                secrets_by_ip[source_ip] = secret
-        count = reprovision_bottles(
-            OrchestratorClient(endpoint.orchestrator_url), secrets_by_ip,
-        )
-        if count:
-            info(f"reprovisioned egress tokens for {count} macOS bottle(s)")
-    except (OrchestratorClientError, EnumerationError, OSError) as exc:
-        info(f"egress token reprovision skipped: {exc}")
-
-
-def live_source_ips(network: str) -> list[str]:
-    """Every running agent container's address on `network`.
-
-    The reconciliation input: the orchestrator lives inside the infra
-    container and cannot enumerate the host's containers, so the host has to
-    tell it which bottles are actually up. Containers that have not been
-    assigned an address yet contribute nothing — the reap's grace window, not
-    this list, is what protects an in-flight launch.
-
-    Raises `EnumerationError` when the live set cannot be determined
-    authoritatively: either the container listing fails or any individual
-    inspect fails. Callers must skip reconciliation in that case to avoid
-    unregistering healthy bottles."""
-    ips: list[str] = []
-    for agent in enumerate_active():
-        name = f"{CONTAINER_NAME_PREFIX}{agent.slug}"
-        ip = container_mod.inspect_container_network_ip(name, network)
-        if ip is None:
-            raise EnumerationError(
-                f"container inspect {name!r} failed; live set is not authoritative"
-            )
-        if ip:
-            ips.append(ip)
-    return ips
-
-
-def register_agent(
-    egress_plan: EgressPlan,
-    git_gate_plan: GitGatePlan,
-    *,
-    source_ip: str,
-    endpoint: GatewayEndpoint,
-    image_ref: str = "",
-    tokens: dict[str, str] | None = None,
-    env_var_secret: str | None = None,
-) -> LaunchContext:
-    """Register the (already running) agent by its address and provision its
-    git-gate state into the gateway. `source_ip` must be read from the live
-    container — it is the attribution key the gateway resolves policy by.
-    Raises on failure; the caller tears down."""
-    client = OrchestratorClient(endpoint.orchestrator_url)
-    # Self-heal before registering: a launcher that died hard (SIGKILL, closed
-    # terminal, host sleep) never ran its teardown callback, leaving an active
-    # row with no container. vmnet recycles addresses, so such a row can
-    # collide with this bottle's — and `by_source_ip` fail-closes on ambiguity,
-    # which would resolve no policy at all and deny every host. Best-effort: a
-    # reconciliation failure must not block an otherwise-fine launch.
-    try:
-        client.reconcile(live_source_ips(endpoint.network))
-    except (OrchestratorClientError, EnumerationError) as e:
-        info(f"registry reconciliation skipped: {e}")
-    reg = provision_bottle(
-        client, source_ip, egress_plan, git_gate_plan, MacosGatewayTransport(),
-        image_ref=image_ref, tokens=tokens,
-        env_var_secret=env_var_secret,
-    )
-    return LaunchContext(
-        bottle_id=reg.bottle_id,
-        identity_token=reg.identity_token,
-        source_ip=source_ip,
-        gateway_ip=endpoint.gateway_ip,
-        network=endpoint.network,
-        orchestrator_url=endpoint.orchestrator_url,
-        env_var_secret=reg.env_var_secret,
-    )
-
-
-def deprovision_consolidated(
-    bottle_id: str, *, orchestrator_url: str, timeout: float | None = None,
-) -> 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. Does NOT
-    stop the gateway — it's a persistent per-host singleton."""
-    deprovision_bottle(bottle_id, MacosGatewayTransport(),
-                   orchestrator_url=orchestrator_url, timeout=timeout)
-
-
-__all__ = [
-    "GatewayEndpoint",
-    "LaunchContext",
-    "ensure_gateway",
-    "live_source_ips",
-    "register_agent",
-    "deprovision_consolidated",
-    "ConsolidatedLaunchError",
-    "OrchestratorStartError",
-    "GATEWAY_NETWORK",
-]

bot_bottle/backend/macos_container/egress_apply.py

@@ -1,26 +1,36 @@
-"""Host-side egress route-apply for the macos-container backend.
+"""Host-side egress apply for the macos-container backend.
 
-The per-bottle companion container this used to signal (`container kill
---signal HUP <container>`) was removed in the companion-container removal
-(#385). 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 — same posture as the docker backend.
+Uses `container kill --signal HUP` (Apple Container framework) instead
+of `docker kill` to signal the sidecar bundle.
 """
 
 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:
-        del slug
-        raise EgressApplyError(
-            "live egress route-apply was removed with the per-bottle "
-            "companion container (#385); route changes will flow through "
-            "the consolidated gateway in a follow-up."
+        container = sidecar_container_name(slug)
+        result = subprocess.run(
+            ["container", "kill", "--signal", "HUP", container],
+            capture_output=True, text=True, check=False, env=os.environ,
         )
+        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

@@ -6,22 +6,9 @@ import subprocess
 
 from ...bottle_state import read_metadata
 from .. import ActiveAgent
-from .infra import INFRA_NAME, ORCHESTRATOR_NAME
 
-# The name every agent container carries: `bot-bottle-<slug>`. Exported
-# because callers that act on a running bottle (gateway-host rewrites,
-# registry reconciliation) have to map an enumerated slug back to a
-# container name.
-CONTAINER_NAME_PREFIX = "bot-bottle-"
-# The two shared per-host infra containers (orchestrator + gateway) carry the
-# same `bot-bottle-` prefix as agent containers but are infrastructure, not
-# bottles — one pair serves every agent, so enumerating either as an agent would
-# invent a phantom bottle per host.
-_INFRA_NAMES = frozenset({INFRA_NAME, ORCHESTRATOR_NAME})
-
-
-class EnumerationError(RuntimeError):
-    """container list failed; the resulting live set is not authoritative."""
+_PREFIX = "bot-bottle-"
+_SIDECAR_PREFIX = "bot-bottle-sidecars-"
 
 
 def enumerate_active() -> list[ActiveAgent]:
@@ -32,15 +19,14 @@ def enumerate_active() -> list[ActiveAgent]:
         check=False,
     )
     if result.returncode != 0:
-        raise EnumerationError(
-            f"container list failed: "
-            f"{(result.stderr or '').strip() or '<no stderr>'}"
-        )
+        return []
     out: list[ActiveAgent] = []
     for name in sorted(line.strip() for line in result.stdout.splitlines()):
-        if not name.startswith(CONTAINER_NAME_PREFIX) or name in _INFRA_NAMES:
+        if not name.startswith(_PREFIX):
             continue
-        slug = name[len(CONTAINER_NAME_PREFIX):]
+        if name.startswith(_SIDECAR_PREFIX):
+            continue
+        slug = name[len(_PREFIX):]
         metadata = read_metadata(slug)
         out.append(ActiveAgent(
             backend_name="macos-container",

bot_bottle/backend/macos_container/gateway.py

@@ -1,213 +0,0 @@
-"""The macOS gateway data plane as an Apple container (PRD 0070).
-
-`MacosGateway` is the Apple-Container implementation of the backend-neutral
-`Gateway` service. It runs the gateway daemons (egress / git-http / supervise)
-in a single triple-homed container and never opens `bot-bottle.db` — it reaches
-the supervise queue over the control-plane RPC (#469), so it holds no signing
-key, only the pre-minted `gateway` token the orchestrator hands it via
-`connect_to_orchestrator`.
-
-This module also holds the pieces the infra service + launch/provision glue
-share: the network names, the gateway image, and the network-creation helper.
-"""
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-
-from ...gateway import (
-    DEFAULT_CA_TIMEOUT_SECONDS,
-    GATEWAY_CA_CERT,
-    MITMPROXY_HOME,
-    Gateway,
-    GatewayError,
-    GatewayTransport,
-)
-from ...paths import (
-    ORCHESTRATOR_AUTH_JWT_ENV,
-    host_gateway_ca_dir,
-)
-from ... import resources
-from .. import util as backend_util
-from . import util as container_mod
-
-# The shared host-only network the gateway container and every agent bottle sit
-# on. The agent's address here is the attribution key. Distinct from the docker
-# names so both backends can coexist on one host.
-GATEWAY_NETWORK = "bot-bottle-mac-gateway"
-# The NAT network that gives the gateway (and only it) a route out.
-GATEWAY_EGRESS_NETWORK = "bot-bottle-mac-egress"
-# The control network the gateway reaches the orchestrator over (host-only).
-# Only the orchestrator + gateway join it; agents never do, so agents have no
-# route to the control plane (PRD 0070 "Separating the planes").
-CONTROL_NETWORK = "bot-bottle-mac-control"
-
-# The gateway (data plane) container. The name predates the split — it was the
-# combined "infra" container — and is kept so callers importing it still resolve
-# the gateway (probe / reprovision attribute against it).
-GATEWAY_NAME = "bot-bottle-mac-infra"
-GATEWAY_LABEL = "bot-bottle-mac-infra=1"
-# The gateway subset the consolidated model runs (no per-bottle git:// daemon).
-GATEWAY_DAEMONS = "egress,git-http,supervise"
-
-GATEWAY_IMAGE = os.environ.get("BOT_BOTTLE_GATEWAY_IMAGE", "bot-bottle-gateway:latest")
-
-
-def ensure_networks(
-    network: str = GATEWAY_NETWORK,
-    egress_network: str = GATEWAY_EGRESS_NETWORK,
-    control_network: str = CONTROL_NETWORK,
-) -> None:
-    """Create the shared host-only agent network, the NAT egress network, and
-    the host-only control network. Idempotent — `create_network` tolerates
-    'already exists'."""
-    container_mod.create_network(egress_network)
-    container_mod.create_network(network, internal=True)
-    container_mod.create_network(control_network, internal=True)
-
-
-class MacosGateway(Gateway):
-    """The consolidated gateway as a single Apple container, triple-homed on the
-    NAT egress, host-only agent, and control networks.
-
-    `ensure_built` builds `Dockerfile.gateway`; the networks are ensured by the
-    composer. `connect_to_orchestrator` runs the container carrying the mitmproxy
-    CA + the pre-minted `gateway` token."""
-
-    def __init__(
-        self,
-        image_ref: str = GATEWAY_IMAGE,
-        *,
-        name: str = GATEWAY_NAME,
-        network: str = GATEWAY_NETWORK,
-        egress_network: str = GATEWAY_EGRESS_NETWORK,
-        control_network: str = CONTROL_NETWORK,
-        repo_root: Path | None = None,
-    ) -> None:
-        self.image_ref = image_ref
-        self.name = name
-        self.network = network
-        self.egress_network = egress_network
-        self.control_network = control_network
-        # Build context: the repo root in a checkout, a staged copy from the
-        # installed wheel otherwise (bot_bottle.resources).
-        self._repo_root = repo_root if repo_root is not None else resources.build_root()
-        # Set by `connect_to_orchestrator`: the URL the daemons resolve policy
-        # against + the pre-minted `gateway` token they present. The gateway
-        # never mints, so it never holds the signing key (#469).
-        self._orchestrator_url = ""
-        self._gateway_token = ""
-
-    def ensure_built(self) -> None:
-        """Build the data-plane image from `Dockerfile.gateway`."""
-        container_mod.build_image(
-            self.image_ref, str(self._repo_root), dockerfile="Dockerfile.gateway")
-
-    def connect_to_orchestrator(self, orchestrator_url: str, gateway_token: str) -> None:
-        """Bind the gateway to this orchestrator and (re)start it, dual-homed on
-        the agent + control networks, resolving policy against `orchestrator_url`
-        (the orchestrator's control-network address — Apple has no container
-        DNS) and presenting `gateway_token`."""
-        self._orchestrator_url = orchestrator_url
-        self._gateway_token = gateway_token
-        # Fail closed on a missing policy source or token: the resolver-only data
-        # plane (PRD 0070) would only crash-loop its daemons without an
-        # orchestrator URL, and it cannot mint the token it presents (#469).
-        if not self._orchestrator_url:
-            raise GatewayError(
-                "gateway requires an orchestrator URL to run "
-                "(resolver-only data plane; no single-tenant fallback)"
-            )
-        if not self._gateway_token:
-            raise GatewayError(
-                "gateway requires a pre-minted `gateway` token to run "
-                "(the orchestrator mints it; the gateway never holds the key)"
-            )
-        container_mod.force_remove_container(self.name)
-        argv = [
-            "container", "run", "--detach",
-            "--name", self.name,
-            "--label", "bot-bottle.backend=macos-container",
-            "--label", GATEWAY_LABEL,
-            # NAT egress FIRST (default route out); the host-only agent network
-            # is where agents reach the gateway; the control network reaches the
-            # orchestrator.
-            "--network", self.egress_network,
-            "--network", self.network,
-            "--network", self.control_network,
-            "--dns", container_mod.dns_server(),
-            # The mitmproxy CA on a host bind-mount (survives recreation +
-            # volume pruning — issue #450). No DB mount: the data plane never
-            # opens bot-bottle.db (#469).
-            "--mount",
-            container_mod.bind_mount_spec(str(host_gateway_ca_dir()), MITMPROXY_HOME),
-            "--env", f"BOT_BOTTLE_GATEWAY_DAEMONS={GATEWAY_DAEMONS}",
-            "--env", f"BOT_BOTTLE_ORCHESTRATOR_URL={self._orchestrator_url}",
-            # The pre-minted `gateway` JWT (never the signing key). Bare
-            # `--env NAME` inherits the value from run_env below.
-            "--env", ORCHESTRATOR_AUTH_JWT_ENV,
-            self.image_ref,
-        ]
-        run_env = {**os.environ, ORCHESTRATOR_AUTH_JWT_ENV: self._gateway_token}
-        result = container_mod.run_container_argv(argv, env=run_env)
-        if result.returncode != 0:
-            raise GatewayError(
-                f"gateway container failed to start: "
-                f"{(result.stderr or '').strip() or '<no stderr>'}"
-            )
-
-    def is_running(self) -> bool:
-        return container_mod.container_is_running(self.name)
-
-    def stop(self) -> None:
-        """Remove the gateway container (idempotent)."""
-        container_mod.force_remove_container(self.name)
-
-    def address(self) -> str:
-        """The gateway's agent-network address — the proxy / git-http / supervise
-        target agents dial (also the source IP the gateway attributes by)."""
-        ip = container_mod.try_container_ipv4_on_network(self.name, self.network)
-        if not ip:
-            raise GatewayError(
-                f"gateway {self.name} has no address on {self.network}"
-            )
-        return ip
-
-    def ca_cert_pem(self, *, timeout: float = DEFAULT_CA_TIMEOUT_SECONDS) -> str:
-        """The gateway's mitmproxy CA (PEM) agents install to trust its TLS
-        interception. Read from the gateway container; polls because mitmproxy
-        writes it a beat after start."""
-        def _fetch() -> str | None:
-            result = container_mod.run_container_argv(
-                ["container", "exec", self.name, "cat", GATEWAY_CA_CERT])
-            return result.stdout if result.returncode == 0 and result.stdout.strip() else None
-        try:
-            return backend_util.poll_ca_cert(_fetch, timeout=timeout)
-        except TimeoutError as exc:
-            raise GatewayError(
-                f"gateway CA not available in {self.name} after {timeout:g}s"
-            ) from exc
-
-    def provisioning_transport(self) -> GatewayTransport:
-        """The exec/cp transport git-gate provisioning stages per-bottle repos +
-        deploy keys through (over the `container` CLI)."""
-        # Local import: gateway_transport imports GATEWAY_NAME from this module,
-        # so importing MacosGatewayTransport at module scope would cycle.
-        from .gateway_transport import MacosGatewayTransport
-        return MacosGatewayTransport(self.name)
-
-
-__all__ = [
-    "GATEWAY_NETWORK",
-    "GATEWAY_EGRESS_NETWORK",
-    "CONTROL_NETWORK",
-    "GATEWAY_NAME",
-    "GATEWAY_LABEL",
-    "GATEWAY_DAEMONS",
-    "GATEWAY_IMAGE",
-    "GatewayError",
-    "DEFAULT_CA_TIMEOUT_SECONDS",
-    "ensure_networks",
-    "MacosGateway",
-]

bot_bottle/backend/macos_container/gateway_hosts.py

@@ -1,96 +0,0 @@
-"""Stable gateway name for macOS agents, via each bottle's `/etc/hosts`.
-
-The shared gateway's address is assigned by vmnet's DHCP and changes whenever
-the gateway container is recreated — a source-hash bump, an image upgrade, a
-crash. Every agent-facing URL (egress proxy, git-http, supervise) embeds that
-address, and the proxy URL reaches the agent as **process environment** at
-`container exec` time. A running process's `environ` cannot be rewritten from
-outside, so a moved gateway used to strand every running bottle permanently:
-not degraded, unreachable, until the bottle was relaunched and its session
-thrown away.
-
-So the agent never learns the address. It is given a stable *name*
-(`GATEWAY_HOSTNAME`) in every URL, resolved through its own `/etc/hosts`.
-Unlike `environ`, that is a file — it can be rewritten inside a container that
-is already running, so a gateway that comes back at a new address is picked up
-by live bottles instead of orphaning them.
-
-Apple Container 1.0 offers no container-name DNS on a user network (the only
-nameserver an agent sees is vmnet's, which does not know container names) and
-`container run` has no `--add-host`, so the entry is written by exec after the
-container starts.
-
-Writing it needs root, and the agent runs as `node`: the agent therefore
-cannot repoint its own gateway name, while the host (which drives `container
-exec --user root`) can. That asymmetry is deliberate — keep it.
-"""
-
-from __future__ import annotations
-
-from ...log import warn
-from . import util as container_mod
-from .enumerate import CONTAINER_NAME_PREFIX, enumerate_active
-
-# The name every agent-facing gateway URL uses. Must not collide with a real
-# DNS name the agent might resolve; it is bottle-local by construction.
-GATEWAY_HOSTNAME = "bot-bottle-gateway"
-
-# Marker so the rewrite is idempotent and only ever touches our own line —
-# the rest of /etc/hosts (localhost, the container's own name) is preserved.
-_MARKER = "# bot-bottle gateway"
-
-
-def _rewrite_script(gateway_ip: str) -> str:
-    """A shell one-liner that replaces our managed line in `/etc/hosts`.
-
-    Rewrites in place via a temp file + `cat` rather than `mv`, so the file
-    keeps its original inode, ownership, and mode — a bind-mounted or
-    pre-created `/etc/hosts` must not be replaced by a root-owned 0644 copy
-    that the runtime then refuses to update.
-    """
-    return (
-        "set -e; "
-        f"grep -v '{_MARKER}' /etc/hosts > /tmp/.bb-hosts || true; "
-        f"printf '%s %s %s\\n' '{gateway_ip}' '{GATEWAY_HOSTNAME}' "
-        f"'{_MARKER}' >> /tmp/.bb-hosts; "
-        "cat /tmp/.bb-hosts > /etc/hosts; "
-        "rm -f /tmp/.bb-hosts"
-    )
-
-
-def set_gateway_host(container_name: str, gateway_ip: str) -> None:
-    """Point `GATEWAY_HOSTNAME` at `gateway_ip` inside one running container.
-
-    Must run before the agent is exec'd: the agent's proxy URL names the
-    gateway, so the entry has to exist for its first connection. Idempotent —
-    re-running with the same address is a no-op in effect.
-    """
-    container_mod.exec_container_as_root(
-        container_name, ["sh", "-c", _rewrite_script(gateway_ip)],
-    )
-
-
-def refresh_gateway_host(gateway_ip: str) -> list[str]:
-    """Re-point every running bottle at the current gateway address.
-
-    Called once the shared gateway is known to be up, so a bottle stranded by
-    an earlier gateway restart re-attaches instead of needing a relaunch.
-    Returns the containers updated.
-
-    Best-effort per bottle: one container that refuses the write (already
-    exiting, say) must not stop the others from being repaired, and must not
-    fail the launch that triggered the sweep.
-    """
-    updated: list[str] = []
-    for agent in enumerate_active():
-        name = f"{CONTAINER_NAME_PREFIX}{agent.slug}"
-        try:
-            set_gateway_host(name, gateway_ip)
-            updated.append(name)
-        # One bad bottle must not stop the sweep, so this is deliberately broad.
-        except Exception as e:  # noqa: BLE001  # pylint: disable=broad-exception-caught
-            warn(f"could not re-point {name} at the gateway: {e}")
-    return updated
-
-
-__all__ = ["GATEWAY_HOSTNAME", "set_gateway_host", "refresh_gateway_host"]

bot_bottle/backend/macos_container/gateway_transport.py

@@ -1,43 +0,0 @@
-"""The `GatewayTransport` for the Apple gateway container (PRD 0070).
-
-How the launcher stages files + runs commands in the running gateway container:
-the `container` CLI's exec/cp equivalents. The backend-neutral provisioning
-logic that drives it lives in `backend.provision_gateway`; Docker uses
-`docker exec`/`docker cp` and Firecracker uses SSH.
-"""
-
-from __future__ import annotations
-
-from ...gateway import GatewayProvisionError
-from . import util as container_mod
-from .gateway import GATEWAY_NAME
-
-
-class MacosGatewayTransport:
-    """`GatewayTransport` for the gateway daemons in the Apple gateway container."""
-
-    def __init__(self, gateway: str = GATEWAY_NAME) -> None:
-        self.gateway = gateway
-
-    def exec(self, argv: list[str]) -> None:
-        result = container_mod.run_container_argv(
-            ["container", "exec", self.gateway, *argv]
-        )
-        if result.returncode != 0:
-            raise GatewayProvisionError(
-                f"gateway exec {argv!r} failed: "
-                f"{(result.stderr or '').strip() or '<no stderr>'}"
-            )
-
-    def cp_into(self, src: str, dest: str) -> None:
-        result = container_mod.run_container_argv(
-            ["container", "cp", src, f"{self.gateway}:{dest}"]
-        )
-        if result.returncode != 0:
-            raise GatewayProvisionError(
-                f"gateway cp {src} -> {dest} failed: "
-                f"{(result.stderr or '').strip() or '<no stderr>'}"
-            )
-
-
-__all__ = ["MacosGatewayTransport"]

bot_bottle/backend/macos_container/infra.py

@@ -1,162 +0,0 @@
-"""The per-host control plane + gateway for the macOS backend (PRD 0070).
-
-Two Apple containers — the orchestrator (control plane) and the gateway (data
-plane) — split now that #469 got the DB off the data plane. The single-container
-model existed only because two Apple-Container guests writing one `bot-bottle.db`
-over virtiofs would race incoherent `fcntl` locks; with the data plane no longer
-opening the DB at all, only the orchestrator does, so the split is safe.
-
-  * `bot-bottle-mac-orchestrator` — the lean control plane (`MacosOrchestrator`).
-    Joins the host-only **control network** (`bot-bottle-mac-control`) only. Sole
-    opener of the container-only DB volume; holds the signing key. The host CLI
-    reaches it at its control-network address; the gateway reaches it there too.
-  * `bot-bottle-mac-infra` — the gateway data plane (`MacosGateway`). Triple-homed:
-    the NAT egress network (route out), the host-only agent network (agents + CLI
-    reach the gateway), and the control network (reach the orchestrator by IP —
-    Apple has no container DNS). Holds the mitmproxy CA + the `gateway` JWT.
-
-`MacosInfraService` composes the two services and brings them up as an idempotent
-per-host pair. Agents sit on the agent network only, never the control network,
-so they have no route to the control plane (the L3 block, not just the JWT).
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from ... import resources
-from ...orchestrator.lifecycle import (
-    DEFAULT_PORT,
-    DEFAULT_STARTUP_TIMEOUT_SECONDS,
-    OrchestratorStartError,
-)
-from ..infra_service import InfraService
-from . import util as container_mod
-from .gateway import (
-    CONTROL_NETWORK,
-    DEFAULT_CA_TIMEOUT_SECONDS,
-    GATEWAY_EGRESS_NETWORK,
-    GATEWAY_IMAGE,
-    GATEWAY_NAME,
-    GATEWAY_NETWORK,
-    MacosGateway,
-    ensure_networks,
-)
-from .orchestrator import (
-    ORCHESTRATOR_DB_VOLUME,
-    ORCHESTRATOR_IMAGE,
-    ORCHESTRATOR_NAME,
-    MacosOrchestrator,
-    probe_orchestrator_url,
-)
-
-# `INFRA_NAME` is kept — now aliasing the gateway container — for callers that
-# still import it (probe / reprovision attribute against the gateway).
-INFRA_NAME = GATEWAY_NAME
-
-
-class MacosInfraService(InfraService):
-    """Composes the per-host orchestrator + gateway containers. Callers use
-    `ensure_running()` (returns the control-plane URL), the `orchestrator()` /
-    `gateway()` accessors, and `ca_cert_pem()`."""
-
-    def __init__(
-        self,
-        *,
-        port: int = DEFAULT_PORT,
-        network: str = GATEWAY_NETWORK,
-        egress_network: str = GATEWAY_EGRESS_NETWORK,
-        control_network: str = CONTROL_NETWORK,
-        gateway_image: str = GATEWAY_IMAGE,
-        orchestrator_image: str = ORCHESTRATOR_IMAGE,
-        repo_root: Path | None = None,
-        orchestrator_name: str = ORCHESTRATOR_NAME,
-        gateway_name: str = INFRA_NAME,
-        db_volume: str = ORCHESTRATOR_DB_VOLUME,
-    ) -> None:
-        self.port = port
-        self.network = network
-        self.egress_network = egress_network
-        self.control_network = control_network
-        self.gateway_image = gateway_image
-        self.orchestrator_image = orchestrator_image
-        # Build context / bind-mount source: the repo root in a checkout, a
-        # staged copy from the installed wheel otherwise (bot_bottle.resources).
-        self._repo_root = repo_root if repo_root is not None else resources.build_root()
-        self._orchestrator_name = orchestrator_name
-        self._gateway_name = gateway_name
-        self._db_volume = db_volume
-
-    def orchestrator(self) -> MacosOrchestrator:
-        """The control-plane service on the host-only control network. Cheap to
-        reconstruct — the launch flow reads its `url()` / `gateway_url()` /
-        `mint_gateway_token()` off it."""
-        return MacosOrchestrator(
-            self.orchestrator_image,
-            name=self._orchestrator_name,
-            port=self.port,
-            control_network=self.control_network,
-            repo_root=self._repo_root,
-            db_volume=self._db_volume,
-        )
-
-    def gateway(self) -> MacosGateway:
-        """The data-plane gateway service, triple-homed on the egress + agent +
-        control networks. Cheap to reconstruct — the launch flow reads its
-        `address()` / CA / provisioning transport off it, and `ensure_running`
-        connects it to the control plane."""
-        return MacosGateway(
-            self.gateway_image,
-            name=self._gateway_name,
-            network=self.network,
-            egress_network=self.egress_network,
-            control_network=self.control_network,
-            repo_root=self._repo_root,
-        )
-
-    def ensure_running(
-        self, *, startup_timeout: float = DEFAULT_STARTUP_TIMEOUT_SECONDS,
-    ) -> str:
-        """Ensure the orchestrator + gateway containers are up; return the host
-        control-plane URL. Idempotent per-host singleton — a healthy orchestrator
-        on current source is left untouched. Raises `OrchestratorStartError` on
-        control-plane startup timeout."""
-        # The networks (host-only agent + NAT egress + host-only control) are a
-        # shared concern — create them before either plane comes up.
-        ensure_networks(self.network, self.egress_network, self.control_network)
-
-        orchestrator = self.orchestrator()
-        gateway = self.gateway()
-        orchestrator.ensure_built()
-        gateway.ensure_built()
-
-        orchestrator.ensure_running(startup_timeout=startup_timeout)
-
-        # (Re)ensure the gateway once the control plane it resolves against is
-        # healthy — it needs the orchestrator's control-network address. The
-        # orchestrator (which holds the signing key) mints the role-scoped
-        # `gateway` JWT and hands it to the gateway, which never sees the key
-        # (#469).
-        url = orchestrator.url()
-        gateway.connect_to_orchestrator(url, orchestrator.mint_gateway_token())
-        return url
-
-    def ca_cert_pem(self, *, timeout: float = DEFAULT_CA_TIMEOUT_SECONDS) -> str:
-        """The gateway's mitmproxy CA (PEM) agents install to trust its TLS
-        interception — delegated to the gateway service (reads it out of the
-        gateway container, polling until mitmproxy writes it)."""
-        return self.gateway().ca_cert_pem(timeout=timeout)
-
-    def stop(self) -> None:
-        """Remove both containers (idempotent). The DB volume persists."""
-        container_mod.force_remove_container(self._gateway_name)
-        container_mod.force_remove_container(self._orchestrator_name)
-
-
-__all__ = [
-    "MacosInfraService",
-    "OrchestratorStartError",
-    "ORCHESTRATOR_NAME",
-    "INFRA_NAME",
-    "probe_orchestrator_url",
-]

bot_bottle/backend/macos_container/launch.py

@@ -1,33 +1,11 @@
-"""Launch flow for the macOS Apple Container backend (PRD 0070).
+"""Launch flow for the macOS Apple Container backend.
 
-The agent container attaches to the **shared host-only gateway network** and
-proxies egress through the one per-host gateway, replacing the per-bottle
-companion container removed in #385.
-
-The order differs from docker's, forced by Apple Container 1.0.0 having no
-`--ip` (see `consolidated_launch`): the agent is started *before* it is
-registered, because its DHCP-assigned address — the attribution key — does not
-exist until then.
-
-    gateway up -> run agent -> read its IP -> register it -> provision
-
-Two things follow from that inversion:
-
-- The **identity token** is minted by registration and so cannot be in the
-  agent's run-time env; it rides the proxy URL applied at `container exec`
-  time (`bottle.MacosContainerBottle`). `/resolve` requires it (#366), so
-  egress without it is denied — hence the bare `sleep` init: every real agent
-  command goes through exec and therefore carries the token.
-- The agent is run with `--cap-drop CAP_NET_RAW`. Apple Container grants
-  NET_RAW by default, which would let an agent open a raw socket and forge a
-  neighbour's source address on the shared segment. NET_ADMIN is already
-  absent (the agent cannot change its own address or route), so dropping
-  NET_RAW is what closes the source-address half of PRD 0070's invariant:
-  "a packet's source address, as seen by the orchestrator, provably identifies
-  the originating bottle." The identity token is the other half — an attacker
-  would need to forge the address *and* steal the token — but the invariant is
-  a stated precondition of consolidation, so it is enforced on its own terms
-  rather than left to the token.
+This backend keeps the explicit proxy-env enforcement model for v1:
+the agent container is attached only to a host-only Apple Container
+network, while the sidecar bundle is attached to a NAT network first
+and the host-only network second. The sidecar's host-only IP is
+discovered from `container inspect` and stamped into the agent's
+HTTP_PROXY / HTTPS_PROXY env vars.
 """
 
 from __future__ import annotations
@@ -36,6 +14,7 @@ import dataclasses
 import os
 import subprocess
 from contextlib import ExitStack, contextmanager
+from pathlib import Path
 from typing import Callable, Generator
 
 from ...bottle_state import (
@@ -43,100 +22,66 @@ from ...bottle_state import (
     git_gate_state_dir,
     read_committed_image,
 )
-from ...egress import Egress
-from ...git_gate import GitGate
-from ...gateway.git_gate.http_backend import DEFAULT_PORT as _GIT_HTTP_PORT
-from ...image_cache import check_stale
+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 ... import resources
-from .. import BottleImages
-from ...supervisor.types import SUPERVISE_PORT
-from ..docker.egress import EGRESS_PORT
+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 .gateway_hosts import (
-    GATEWAY_HOSTNAME,
-    refresh_gateway_host,
-    set_gateway_host,
-)
-from . import nested_containers as nested_containers_mod
 from .bottle_plan import MacosContainerBottlePlan
-from ...orchestrator.store.config_store import resolve_teardown_timeout
-from ...orchestrator.store.secret_store import ENV_VAR_SECRET_NAME, new_env_var_secret
-from .consolidated_launch import (
-    GatewayEndpoint,
-    ensure_gateway,
-    register_agent,
-    deprovision_consolidated,
-)
 
+
+_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 build_or_load_images(plan: MacosContainerBottlePlan) -> BottleImages:
-    """Resolve the agent image ref for this plan. The gateway's own image is
-    built by `ensure_gateway` — it belongs to the shared singleton."""
-    return BottleImages(agent=_layer_nested_containers(plan, _agent_image(plan)))
+def internal_network_name(slug: str) -> str:
+    return f"bot-bottle-net-{slug}"
 
 
-def _agent_image(plan: MacosContainerBottlePlan) -> str:
-    committed = read_committed_image(plan.slug)
-    if committed and container_mod.image_exists(committed):
-        info(f"using committed image {committed!r}")
-        return committed
-    if plan.spec.image_policy == "cached":
-        if not container_mod.image_exists(plan.image):
-            die(
-                f"cached agent image {plan.image!r} not found; "
-                "run without --cached-images to build it"
-            )
-        info(f"using cached agent image {plan.image!r}")
-        return plan.image
-    container_mod.build_image(plan.image, str(resources.build_root()), dockerfile=plan.dockerfile_path)
-    return plan.image
+def egress_network_name(slug: str) -> str:
+    return f"bot-bottle-egress-{slug}"
 
 
-def _layer_nested_containers(
-    plan: MacosContainerBottlePlan, agent_image: str,
-) -> str:
-    """Add the guest-local container tooling on top of the agent image.
-
-    A separate derived tag, not the provider Dockerfile, so bottles that never
-    ask for nested containers carry none of its weight.
-    """
-    if not plan.nested_containers:
-        return agent_image
-    derived = f"{agent_image}{nested_containers_mod.IMAGE_SUFFIX}"
-    if plan.spec.image_policy == "cached":
-        if not container_mod.image_exists(derived):
-            die(
-                f"cached nested-container image {derived!r} not found; "
-                "run without --cached-images to build it"
-            )
-        info(f"using cached nested-container image {derived!r}")
-        return derived
-    return nested_containers_mod.build_image(agent_image, container_mod.build_image)
+def sidecar_container_name(slug: str) -> str:
+    return f"bot-bottle-sidecars-{slug}"
 
 
 @contextmanager
 def launch(
     plan: MacosContainerBottlePlan,
-    images: BottleImages,
     *,
     provision: Callable[[MacosContainerBottlePlan, "MacosContainerBottle"], str | None],
 ) -> Generator[MacosContainerBottle, None, None]:
-    """Run, register, provision, and yield an Apple Container bottle on the
-    shared per-host gateway."""
+    """Build, run, provision, and yield an Apple Container bottle."""
     stack = ExitStack()
     bottle_for_revoke = plan.manifest.bottle
     git_gate_dir_for_revoke = git_gate_state_dir(plan.slug)
 
-    plan = dataclasses.replace(
-        plan,
-        agent_provision=dataclasses.replace(plan.agent_provision, image=str(images.agent)),
-    )
-
     def teardown() -> None:
         teardown_exc: BaseException | None = None
         try:
@@ -144,85 +89,35 @@ def launch(
         except BaseException as exc:  # noqa: W0718 - teardown must continue
             teardown_exc = exc
             warn(f"macos-container teardown failed: {exc!r}")
-        GitGate().revoke_provisioned_keys(bottle_for_revoke, git_gate_dir_for_revoke)
+        revoke_git_gate_provisioned_keys(bottle_for_revoke, git_gate_dir_for_revoke)
         if teardown_exc is not None:
             raise teardown_exc
 
     try:
-        # Step 1: the per-host singletons. Must precede the agent run — its
-        # proxy env needs the gateway's address at `container run` time.
-        endpoint = ensure_gateway()
-        # The gateway's address may have changed since these bottles launched
-        # (any infra recreate re-runs DHCP). They name the gateway rather than
-        # address it, so re-pointing /etc/hosts re-attaches them in place
-        # instead of leaving them stranded until relaunch.
-        refresh_gateway_host(endpoint.gateway_ip)
+        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)
 
-        # Step 2: mint this bottle's deploy keys, then point it at the SHARED
-        # gateway's CA + git-http/supervise ports.
         plan = _provision_git_gate_keys(plan)
-        plan = _install_gateway_ca(plan, endpoint)
-        plan = _stamp_agent_urls(plan, endpoint)
-        plan = dataclasses.replace(plan, env_var_secret=new_env_var_secret())
 
-        # Step 3: run the agent. It has no identity token yet — registration
-        # needs the address this run assigns.
+        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, endpoint)
+        _start_agent(plan, internal_network, sidecar_ip)
         stack.callback(container_mod.force_remove_container, plan.container_name)
 
-        # Step 4: read the assigned address and register by it. This is the
-        # attribution key; `--cap-drop CAP_NET_RAW` at run is what makes it
-        # unforgeable. Poll: `container run --detach` can return before vmnet's
-        # DHCP has assigned the address.
-        # Resolve the gateway name before anything execs: every agent-facing
-        # URL uses it, so the entry must exist for the first connection.
-        set_gateway_host(plan.container_name, endpoint.gateway_ip)
-        source_ip = container_mod.wait_container_ipv4_on_network(
-            plan.container_name, endpoint.network,
-        )
-        if not source_ip:
-            die(
-                f"agent {plan.container_name} never got an address on "
-                f"{endpoint.network}"
-            )
-        effective_env = {**os.environ, **plan.agent_provision.provisioned_env}
-        token_values = Egress().resolve_token_values(
-            plan.egress_plan.token_env_map, effective_env,
-        )
-        teardown_timeout = resolve_teardown_timeout()
-        ctx = register_agent(
-            plan.egress_plan,
-            plan.git_gate_plan,
-            source_ip=source_ip,
-            endpoint=endpoint,
-            image_ref=plan.image,
-            tokens=token_values,
-            env_var_secret=plan.env_var_secret,
-        )
-        stack.callback(
-            deprovision_consolidated, ctx.bottle_id,
-            orchestrator_url=ctx.orchestrator_url,
-            timeout=teardown_timeout,
-        )
-        info(
-            f"agent {plan.container_name} registered "
-            f"(gateway {endpoint.gateway_ip}, ip {source_ip})"
-        )
-
-        # Stamp the token onto the plan so provision-time consumers can read it,
-        # not only the exec-time egress proxy. git-gate's gitconfig extraHeader
-        # and the supervise MCP --header both reach the gateway on NO_PROXY (they
-        # bypass the egress proxy that carries the token), so without this the
-        # gateway's /resolve fail-closes and every git fetch/push and supervise
-        # call from the bottle is denied. Registration already produced the
-        # token above, so — unlike the run-time env — the plan CAN carry it.
-        plan = dataclasses.replace(plan, identity_token=ctx.identity_token)
-
-        exec_env = {
-            **_identity_proxy_env(endpoint, ctx.identity_token),
-            **nested_containers_mod.guest_env(plan.nested_containers),
-        }
         bottle = MacosContainerBottle(
             plan.container_name,
             teardown,
@@ -230,151 +125,97 @@ def launch(
             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_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,
-            exec_env=exec_env,
         )
         bottle.prompt_path = provision(plan, bottle)
 
-        if plan.nested_containers:
-            nested_containers_mod.prepare_guest_devices(
-                plan.container_name, container_mod.exec_container_as_root,
-            )
-            nested_containers_mod.start(bottle)
-
         yield bottle
     finally:
         teardown()
 
 
-
-def stale_checks(plan: MacosContainerBottlePlan) -> None:
-    """Raise StaleImageError if a cached image is older than the configured
-    threshold. Only runs when image_policy is 'cached'. Called by the backend
-    class's _image_stale_checks before _launch_impl starts any resources."""
-    if plan.spec.image_policy != "cached":
-        return
-    committed = read_committed_image(plan.slug)
-    if committed and container_mod.image_exists(committed):
-        ts = container_mod.image_created_at(committed)
-        if ts is not None:
-            check_stale(f"agent image {committed!r}", ts)
-        return
-    if container_mod.image_exists(plan.image):
-        ts = container_mod.image_created_at(plan.image)
-        if ts is not None:
-            check_stale(f"agent image {plan.image!r}", ts)
-
-
-def _provision_git_gate_keys(
-    plan: MacosContainerBottlePlan,
-) -> MacosContainerBottlePlan:
-    if not plan.git_gate_plan.upstreams:
-        return plan
-    git_gate_plan = GitGate().provision_dynamic_keys(
-        plan.manifest.bottle,
-        plan.git_gate_plan,
-        git_gate_state_dir(plan.slug),
+def _mint_certs(plan: MacosContainerBottlePlan) -> MacosContainerBottlePlan:
+    egress_ca_host, egress_ca_cert_only = egress_tls_init(
+        egress_state_dir(plan.slug),
     )
-    return dataclasses.replace(plan, git_gate_plan=git_gate_plan)
-
-
-def _install_gateway_ca(
-    plan: MacosContainerBottlePlan, endpoint: GatewayEndpoint,
-) -> MacosContainerBottlePlan:
-    """Stage the SHARED gateway's CA for the provisioner to install, replacing
-    the per-bottle CA the companion container used to mint. Every bottle on
-    this host trusts this one CA."""
-    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(endpoint.gateway_ca_pem)
     egress_plan = dataclasses.replace(
         plan.egress_plan,
-        mitmproxy_ca_host_path=ca_file,
-        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,
     )
     return dataclasses.replace(plan, egress_plan=egress_plan)
 
 
-def _stamp_agent_urls(
-    plan: MacosContainerBottlePlan, endpoint: GatewayEndpoint,
-) -> MacosContainerBottlePlan:
-    """Point the agent's git-gate insteadOf rewrites + supervise MCP at the
-    shared gateway's ports. Both bypass the egress proxy (NO_PROXY covers the
-    gateway name).
-
-    Addressed by `GATEWAY_HOSTNAME`, never by IP: these URLs are baked into
-    the agent's gitconfig and MCP config at provision time, so an address here
-    would strand the bottle the moment the gateway moved. The name is resolved
-    per connection through `/etc/hosts`, which stays rewritable while the
-    bottle runs."""
-    del endpoint  # addressed by name; the address reaches the bottle via /etc/hosts
-    git_gate_url = (
-        f"http://{GATEWAY_HOSTNAME}:{_GIT_HTTP_PORT}"
-        if plan.git_gate_plan.upstreams else ""
+def _build_images(plan: MacosContainerBottlePlan) -> MacosContainerBottlePlan:
+    container_mod.build_image(
+        SIDECAR_BUNDLE_IMAGE,
+        _REPO_DIR,
+        dockerfile=SIDECAR_BUNDLE_DOCKERFILE,
     )
-    supervise_url = (
-        f"http://{GATEWAY_HOSTNAME}:{SUPERVISE_PORT}/"
-        if plan.supervise_plan is not None else ""
+    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 dataclasses.replace(
-        plan,
-        agent_git_gate_url=git_gate_url,
-        agent_supervise_url=supervise_url,
+    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 _proxy_url(identity_token: str = "") -> str:
-    """The agent's egress proxy URL. The identity token rides as proxy
-    credentials — the gateway reads Proxy-Authorization, resolves the
-    (source_ip, token) pair against the control plane, and strips it before
-    upstream. Without a valid pair `/resolve` denies the request (#366).
-
-    Names the gateway rather than addressing it: this URL reaches the agent as
-    process environment, which cannot be rewritten once the agent is running,
-    so an address baked here is unfixable if the gateway moves."""
-    cred = f"bottle:{identity_token}@" if identity_token else ""
-    return f"http://{cred}{GATEWAY_HOSTNAME}:{EGRESS_PORT}"
-
-
-def _no_proxy() -> str:
-    # git-http + supervise live on the gateway and must NOT go through the
-    # egress proxy — the agent reaches them directly by name. Deliberately
-    # address-free: NO_PROXY is baked into the run-time env and is therefore
-    # just as unfixable as the proxy URL if the gateway moves.
-    return f"localhost,127.0.0.1,{GATEWAY_HOSTNAME}"
-
-
-def _identity_proxy_env(
-    endpoint: GatewayEndpoint, identity_token: str,
-) -> dict[str, str]:
-    """The token-bearing proxy env applied at `container exec` — the only way
-    to get the token in, since it does not exist until after the container
-    runs (registration keys on the DHCP-assigned address).
-
-    This is the *sole* source of `*_PROXY` for the agent. It deliberately does
-    not rely on overriding a run-time value: `container exec --env` appends
-    rather than replaces, so a run-time `HTTPS_PROXY` would survive alongside
-    this one and first-wins runtimes would read the wrong entry. See
-    `_agent_env_entries`."""
-    if not identity_token:
-        return {}
-    del endpoint  # the gateway is named, not addressed
-    url = _proxy_url(identity_token)
-    return {
-        "HTTPS_PROXY": url, "HTTP_PROXY": url,
-        "https_proxy": url, "http_proxy": url,
+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,
     }
-
-
-def _start_agent(plan: MacosContainerBottlePlan, endpoint: GatewayEndpoint) -> None:
-    argv = _agent_run_argv(plan, endpoint)
-    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,
@@ -386,49 +227,214 @@ def _start_agent(plan: MacosContainerBottlePlan, endpoint: GatewayEndpoint) -> N
         )
 
 
+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, endpoint: GatewayEndpoint,
+    plan: MacosContainerBottlePlan,
+    internal_network: str,
+    sidecar_ip: str,
 ) -> list[str]:
     argv = [
         "container", "run",
         "--name", plan.container_name,
         "--detach",
-        "--label", "bot-bottle.backend=macos-container",
-        "--network", endpoint.network,
-        # The attribution invariant: without NET_RAW the agent cannot open a
-        # raw socket, so it cannot source-IP-spoof its neighbours on the shared
-        # segment. NET_ADMIN is not granted by default, so its address and
-        # route are already fixed. See the module docstring.
-        "--cap-drop", "CAP_NET_RAW",
+        "--network", internal_network,
     ]
-    for entry in _agent_env_entries(plan, endpoint):
+    for entry in _agent_env_entries(plan, sidecar_ip):
         argv += ["--env", entry]
-    # The init process is a no-op: every agent command arrives via
-    # `container exec`, which is also how the identity token gets in.
     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, endpoint: GatewayEndpoint,
+    plan: MacosContainerBottlePlan,
+    sidecar_ip: str,
 ) -> tuple[str, ...]:
-    # No `*_PROXY` here on purpose. The token-bearing URL is applied at
-    # `container exec` (`_identity_proxy_env`), and Apple's `container exec
-    # --env` **appends** to the run-time environment rather than replacing it:
-    # setting a token-less value here leaves two `HTTPS_PROXY` entries in the
-    # agent's `environ`, token-less first. Which one a runtime reads is then
-    # pure luck — Node takes the last (and worked), Rust's `std::env::var`
-    # takes the first, so Codex proxied without its identity token and
-    # `/resolve` fail-closed on every request.
-    #
-    # A token-less proxy URL has no legitimate consumer anyway: the init
-    # process is `sleep` and everything that egresses arrives via exec. Its
-    # only value was a tidy 403 for unattributed callers, which is not worth
-    # silently dropping attribution for. Without it a process that egresses
-    # before the exec-time env still fails closed — the agent network is
-    # host-only, so there is no route off it except the gateway.
-    no_proxy = _no_proxy()
+    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}",
@@ -439,16 +445,14 @@ def _agent_env_entries(
         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}")
-    if getattr(plan, "env_var_secret", ""):
-        env.append(f"{ENV_VAR_SECRET_NAME}={plan.env_var_secret}")
     for name, value in sorted(plan.agent_provision.guest_env.items()):
         env.append(f"{name}={value}")
-    # Forwarded vars: bare name → inherits from the `container run` process env
-    # so the secret value never lands on argv.
     for name in sorted(plan.forwarded_env.keys()):
         env.append(name)
-    env.extend(Egress().agent_env_entries(plan.egress_plan))
+    env.extend(egress_agent_env_entries(plan.egress_plan))
     return tuple(env)
 
 
-__all__ = ["launch"]
+def _agent_no_proxy(plan: MacosContainerBottlePlan, sidecar_ip: str) -> str:
+    hosts = ["localhost", "127.0.0.1", sidecar_ip]
+    return ",".join(hosts)

bot_bottle/backend/macos_container/nested-containers-init.sh

@@ -1,210 +0,0 @@
-#!/bin/sh
-set -eu
-
-uid="$(id -u)"
-if [ "$uid" -eq 0 ]; then
-    echo "refusing to run the guest container engine as root" >&2
-    exit 1
-fi
-
-# Every piece of podman 5's networking stack is checked here, because each
-# one fails at a different and misleading layer if it is absent: no pasta and
-# nothing starts at all; no nft and netavark cannot build the bridge every
-# compose file expects; no aardvark-dns and DNS inside nested containers fails
-# while everything else looks healthy.
-for command in podman docker fuse-overlayfs pasta nft slirp4netns; do
-    command -v "$command" >/dev/null 2>&1 || {
-        echo "missing nested-container prerequisite: $command" >&2
-        exit 1
-    }
-done
-
-# The inverse of the rootless-Docker check, and the whole point of the podman
-# variant: a subordinate range would push podman onto newuidmap, which cannot
-# write a multi-range uid_map without CAP_SYS_ADMIN in this guest.  An empty
-# range keeps it on the single-UID self-mapping an unprivileged process may
-# write itself.
-if grep -q "^$(id -un):" /etc/subuid 2>/dev/null; then
-    echo "unexpected subordinate UID range for $(id -un): podman would" >&2
-    echo "require CAP_SYS_ADMIN via newuidmap in this guest" >&2
-    exit 1
-fi
-
-for device in /dev/fuse /dev/net/tun; do
-    [ -r "$device" ] && [ -w "$device" ] || {
-        echo "device $device is not readable/writable by $(id -un)" >&2
-        exit 1
-    }
-done
-
-# Short by necessity, not by accident: conmon's attach socket lives under
-# this directory and must fit in a 108-byte sun_path. See nested_containers.py.
-# Must stay in step with AGENT_CA_BUNDLE in bot_bottle/backend/util.py; a unit
-# test pins the two together.
-CA_BUNDLE="/etc/ssl/certs/ca-certificates.crt"
-[ -r "$CA_BUNDLE" ] || {
-    echo "gateway CA bundle $CA_BUNDLE is missing or unreadable" >&2
-    exit 1
-}
-
-# The proxy URL the agent inherits names `bot-bottle-gateway`, which resolves
-# only through this bottle's /etc/hosts. A nested container gets its own hosts
-# file, so it cannot resolve the name and dies at "Could not resolve proxy".
-#
-# podman's containers.conf `hosts_file` would fix that, except the
-# Docker-compatible API ignores it — it only takes effect for native
-# `podman run`, and the agent types `docker`. So the name is resolved *here*
-# and the address, not the name, goes into the proxy URL the nested container
-# receives. Verified on macOS 26 / podman 5.4.2: with the address in place,
-# https://quay.io returns 200 and a non-allowlisted host still gets 403, so
-# the egress boundary applies inside nested containers too.
-GATEWAY_NAME="bot-bottle-gateway"
-gateway_ip="$(
-    awk -v name="$GATEWAY_NAME" '$2 == name { print $1; exit }' /etc/hosts
-)"
-[ -n "$gateway_ip" ] || {
-    echo "no /etc/hosts entry for $GATEWAY_NAME; the gateway address is" >&2
-    echo "needed so nested containers can reach the egress proxy" >&2
-    exit 1
-}
-
-export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/tmp/bbp}"
-config="$HOME/.config/containers"
-mkdir -p "$XDG_RUNTIME_DIR" "$config"
-chmod 700 "$XDG_RUNTIME_DIR"
-
-# ignore_chown_errors is required, not incidental: with a single-UID mapping
-# there is no second UID for image layers to be chowned to, so layers that
-# record other owners would otherwise fail to extract.
-cat > "$config/storage.conf" <<'CONF'
-[storage]
-driver="overlay"
-[storage.options.overlay]
-mount_program="/usr/bin/fuse-overlayfs"
-ignore_chown_errors="true"
-CONF
-
-# No cgroup delegation reaches this guest, so asking podman to manage cgroups
-# fails; events_logger=file avoids the journald socket that is equally absent.
-#
-# The rest of this config is what lets a nested container reach the network:
-#
-#   hosts_file   only takes effect for native `podman run` — the
-#                Docker-compatible API ignores it, and the agent types
-#                `docker`. Kept anyway because it costs nothing and makes
-#                podman-native use behave; the compat path is covered by the
-#                address-bearing proxy URL below.
-#   volumes/env  the gateway TLS-intercepts, so a container that does not
-#                trust the bottle's CA bundle gets "unable to get local issuer
-#                certificate". Mounting the bundle read-only and pointing the
-#                usual env vars at it covers curl, wget, python, and node
-#                without distro-specific trust commands.
-#
-# The proxy URL carries the bottle's identity token. podman already forwards
-# that same URL into every nested container from the agent's own environment,
-# so writing it to a 0600 file inside this disposable VM hands it to nobody
-# new. It is never echoed.
-CA_BUNDLE="$CA_BUNDLE" GATEWAY_NAME="$GATEWAY_NAME" GATEWAY_IP="$gateway_ip" \
-CONTAINERS_CONF="$config/containers.conf" python3 - <<'PY'
-import os
-from pathlib import Path
-
-ca = os.environ["CA_BUNDLE"]
-name = os.environ["GATEWAY_NAME"]
-ip = os.environ["GATEWAY_IP"]
-
-entries = [
-    f"SSL_CERT_FILE={ca}",
-    f"CURL_CA_BUNDLE={ca}",
-    f"REQUESTS_CA_BUNDLE={ca}",
-    f"NODE_EXTRA_CA_CERTS={ca}",
-]
-# The gateway name resolves only through the bottle's /etc/hosts, which a
-# nested container does not inherit, so hand it the address instead.
-for var in ("HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"):
-    value = os.environ.get(var)
-    if value:
-        entries.append(f"{var}={value.replace(name, ip)}")
-# NO_PROXY keeps the name: it is matched against what a client asks for, and
-# code inside a nested container still says "bot-bottle-gateway".
-for var in ("NO_PROXY", "no_proxy"):
-    value = os.environ.get(var)
-    if value:
-        entries.append(f"{var}={value}")
-
-path = Path(os.environ["CONTAINERS_CONF"])
-path.write_text("\n".join([
-    "[containers]",
-    'cgroups="disabled"',
-    # podman copies the host's proxy vars into every container by default,
-    # and that copy *wins* over the env below — putting the unresolvable
-    # gateway name back. Turn it off so the address-bearing URLs stand.
-    "http_proxy=false",
-    'hosts_file="/etc/hosts"',
-    f'volumes=["{ca}:{ca}:ro"]',
-    "env=[",
-    *[f'  "{entry}",' for entry in entries],
-    "]",
-    "[engine]",
-    'cgroup_manager="cgroupfs"',
-    'events_logger="file"',
-    "",
-]), encoding="utf-8")
-path.chmod(0o600)
-PY
-
-# Registry pulls egress through the bottle's proxy like everything else. The
-# token-bearing proxy URL is already in the agent's environment; persisting it
-# inside this disposable VM does not broaden its authority.
-#
-# This file is also what the Docker CLI copies into every container it starts,
-# and being client-side it beats anything the podman service does — it is why
-# containers.conf `env`, `http_proxy=false`, and the service's own environment
-# all failed to change what a nested container saw. The address goes in here
-# for the same reason it goes everywhere else: `bot-bottle-gateway` resolves
-# in the bottle, never inside a nested container.
-GATEWAY_NAME="$GATEWAY_NAME" GATEWAY_IP="$gateway_ip" python3 - <<'PY'
-import json
-import os
-from pathlib import Path
-
-name = os.environ["GATEWAY_NAME"]
-ip = os.environ["GATEWAY_IP"]
-
-proxy = os.environ.get("HTTPS_PROXY") or os.environ.get("https_proxy", "")
-# NO_PROXY keeps the name: it is matched against what a client asks for, and
-# code inside a nested container still says "bot-bottle-gateway".
-no_proxy = os.environ.get("NO_PROXY") or os.environ.get("no_proxy", "")
-config = {"proxies": {"default": {
-    "httpProxy": proxy.replace(name, ip),
-    "httpsProxy": proxy.replace(name, ip),
-    "noProxy": no_proxy,
-}}}
-path = Path.home() / ".docker" / "config.json"
-path.parent.mkdir(parents=True, exist_ok=True)
-path.write_text(json.dumps(config), encoding="utf-8")
-path.chmod(0o600)
-PY
-
-if docker info >/dev/null 2>&1; then
-    exit 0
-fi
-
-# Belt to the ~/.docker/config.json braces above, which is what actually
-# decides this for `docker run`. The service environment is what podman falls
-# back to for anything the CLI does not stamp — its own registry pulls, and
-# containers created through the API by something other than the Docker CLI.
-# Cheap, and it keeps the address consistent across both paths.
-#
-# Assigned via parameter expansion, never echoed: these carry the bottle's
-# identity token.
-for var in HTTP_PROXY HTTPS_PROXY http_proxy https_proxy; do
-    eval "value=\${$var:-}"
-    [ -n "$value" ] || continue
-    eval "export $var=\"\${value%%$GATEWAY_NAME*}$gateway_ip\${value#*$GATEWAY_NAME}\""
-done
-
-log=/tmp/bot-bottle-nested-containers.log
-nohup podman system service --time=0 \
-    "unix://$XDG_RUNTIME_DIR/podman.sock" \
-    >"$log" 2>&1 </dev/null &

bot_bottle/backend/macos_container/nested_containers.py

@@ -1,161 +0,0 @@
-"""Guest-local container engine for Apple-container bottles (issue #392).
-
-The service and every nested container remain inside the existing per-bottle
-VM.  This module refuses to compensate for missing prerequisites with outer
-capabilities, a privileged container, or a host Docker socket.
-
-Podman is used rather than rootless Docker for one specific reason: Apple
-Container's capability bounding set omits `CAP_SYS_ADMIN`, which the kernel
-requires to write a multi-range `uid_map` via `newuidmap`.  Rootless Docker
-has no path that avoids that write.  Podman does — with no subordinate UID
-range configured it falls back to a single-UID self-mapping, which an
-unprivileged process may write itself.  See
-`docs/research/rootless-docker-in-apple-container-spike.md`.
-
-That fallback is why `build_image` *removes* the agent user's `/etc/subuid`
-and `/etc/subgid` entries instead of adding them: their presence is precisely
-what would send podman down the `newuidmap` path that cannot work here.
-
-The agent still talks to `docker` and `docker compose`; those speak to
-podman's Docker-compatible API socket, so nothing in the agent's habits
-changes.
-"""
-
-from __future__ import annotations
-
-import shlex
-import shutil
-import tempfile
-import time
-from pathlib import Path
-from typing import Callable
-
-from ...log import die, info
-
-_INIT = "/usr/local/libexec/bot-bottle/nested-containers-init"
-# Deliberately cryptic and short. podman derives conmon's attach socket as
-# `$XDG_RUNTIME_DIR/libpod/tmp/socket/<64-hex-id>/attach`, and a Unix socket
-# path may not exceed 108 bytes (`sun_path`). The descriptive
-# `/tmp/bot-bottle-podman-run` produced a 116-byte path — over the limit, so
-# attach would have broken as soon as anything got far enough to attach. Do
-# not lengthen this for readability; it buys 8 bytes of headroom.
-_RUNTIME_DIR = "/tmp/bbp"
-_SOCKET = f"{_RUNTIME_DIR}/podman.sock"
-_LOG = "/tmp/bot-bottle-nested-containers.log"
-IMAGE_SUFFIX = "-nested-containers"
-READY_RETRIES = 30
-
-# Apple Container creates both device nodes 0600 root:root, so the agent user
-# cannot open them: /dev/fuse blocks the fuse-overlayfs storage driver and
-# /dev/net/tun blocks slirp4netns, which rootless podman uses for the default
-# bridge network that stock compose files expect.  Relaxing the modes needs no
-# capability the bottle does not already hold — unlike CAP_SYS_ADMIN, which is
-# what killed the rootless-Docker approach.
-_GUEST_DEVICES = ("/dev/fuse", "/dev/net/tun")
-
-
-def build_image(
-    base_image: str,
-    build: Callable[..., None],
-) -> str:
-    """Layer the nested-container tooling onto an already-built agent image.
-
-    Podman and its networking stack live here rather than in the base agent
-    images so that bottles without the flag pay no image-size cost.
-
-    # TODO(#394): replace this hand-rolled Dockerfile with a docker-layer
-    # abstraction once that infrastructure exists.
-    """
-    image = f"{base_image}{IMAGE_SUFFIX}"
-    init_script = Path(__file__).with_name("nested-containers-init.sh")
-    with tempfile.TemporaryDirectory(prefix="bot-bottle-nested-containers.") as tmp:
-        context = Path(tmp)
-        shutil.copy2(init_script, context / "nested-containers-init.sh")
-        (context / "Dockerfile").write_text(
-            "FROM docker:28-cli AS docker_cli\n"
-            f"FROM {base_image}\n"
-            "USER root\n"
-            "COPY --from=docker_cli /usr/local/bin/docker /usr/local/bin/docker\n"
-            "COPY --from=docker_cli /usr/local/libexec/docker/cli-plugins/"
-            "docker-compose /usr/local/libexec/docker/cli-plugins/docker-compose\n"
-            "RUN apt-get update \\\n"
-            # podman 5's networking stack, installed explicitly because
-            # --no-install-recommends omits it and each missing piece fails
-            # at a different, misleading layer:
-            #   podman       -> moved here from the base agent images so that
-            #                   bottles without nested_containers pay no cost
-            #   passt        -> `pasta`, the default rootless netns helper
-            #                   (podman 4 used slirp4netns); without it
-            #                   nothing starts: "could not find pasta"
-            #   nftables     -> `nft`, which netavark shells out to for the
-            #                   bridge network every compose file expects
-            #   aardvark-dns -> name resolution *inside* nested containers;
-            #                   without it DNS fails while everything else
-            #                   looks healthy
-            # slirp4netns stays as the documented fallback for pasta.
-            " && apt-get install -y --no-install-recommends "
-            "aardvark-dns fuse-overlayfs netavark nftables passt podman "
-            "slirp4netns uidmap \\\n"
-            " && rm -rf /var/lib/apt/lists/* \\\n"
-            # Deliberate: an empty subordinate range keeps podman on the
-            # single-UID mapping that needs no CAP_SYS_ADMIN.  Adding ranges
-            # here would reintroduce the newuidmap failure this design exists
-            # to route around.
-            " && sed -i '/^node:/d' /etc/subuid /etc/subgid\n"
-            "COPY nested-containers-init.sh "
-            "/usr/local/libexec/bot-bottle/nested-containers-init\n"
-            "RUN chmod 0755 /usr/local/libexec/bot-bottle/nested-containers-init\n"
-            "USER node\n",
-            encoding="utf-8",
-        )
-        build(image, str(context), dockerfile=str(context / "Dockerfile"))
-    return image
-
-
-def guest_env(enabled: bool) -> dict[str, str]:
-    """Environment consumed by the Docker CLI inside an enabled bottle."""
-    if not enabled:
-        return {}
-    return {
-        "DOCKER_HOST": f"unix://{_SOCKET}",
-        "XDG_RUNTIME_DIR": _RUNTIME_DIR,
-    }
-
-
-def prepare_guest_devices(container_name: str, exec_as_root: Callable[..., None]) -> None:
-    """Make /dev/fuse and /dev/net/tun openable by the agent user.
-
-    Runs as root inside the bottle because the agent must not be able to
-    re-mode device nodes itself.  No outer capability is involved.
-    """
-    exec_as_root(
-        container_name,
-        ["sh", "-c", f"chmod 0666 {' '.join(_GUEST_DEVICES)}"],
-    )
-
-
-def start(bottle: object) -> None:
-    """Start and verify the unprivileged service through the bottle exec API."""
-    info("starting guest-local container engine")
-    result = bottle.exec(shlex.quote(_INIT))  # type: ignore[attr-defined]
-    if result.returncode != 0:
-        detail = (result.stderr or result.stdout or "").strip()
-        die(f"nested-container bootstrap failed: {detail or '<no output>'}")
-
-    for _ in range(READY_RETRIES):
-        result = bottle.exec("docker info >/dev/null 2>&1")  # type: ignore[attr-defined]
-        if result.returncode == 0:
-            info("guest-local container engine is ready")
-            return
-        time.sleep(0.2)
-
-    logs = bottle.exec(  # type: ignore[attr-defined]
-        f"tail -n 80 {_LOG} 2>/dev/null || true"
-    )
-    die(
-        "guest-local container engine did not become ready without additional "
-        f"outer privileges:\n{(logs.stdout or logs.stderr or '<no log>').strip()}"
-    )
-
-
-__all__ = ["build_image", "guest_env", "prepare_guest_devices", "start"]

bot_bottle/backend/macos_container/orchestrator.py

@@ -1,206 +0,0 @@
-"""The macOS orchestrator (control plane) as an Apple container (PRD 0070).
-
-`MacosOrchestrator` is the Apple-Container implementation of the backend-neutral
-`Orchestrator` service. The lean control-plane container joins the host-only
-control network only (agents are never on it), mounts a container-only DB volume
-(exactly one kernel writes `bot-bottle.db`), and holds the signing key (#469).
-The host CLI and the gateway both reach it at its control-network address —
-Apple has no container DNS, so there's a single resolved URL, not docker's
-loopback-vs-name split.
-"""
-
-from __future__ import annotations
-
-import os
-import time
-import urllib.error
-import urllib.request
-from pathlib import Path
-
-from ... import log
-from ... import resources
-from ...paths import ORCHESTRATOR_TOKEN_ENV
-from ...orchestrator.lifecycle import (
-    DEFAULT_HEALTH_TIMEOUT_SECONDS,
-    DEFAULT_PORT,
-    DEFAULT_STARTUP_TIMEOUT_SECONDS,
-    Orchestrator,
-    OrchestratorStartError,
-    source_hash,
-)
-from . import util as container_mod
-from .gateway import CONTROL_NETWORK
-
-ORCHESTRATOR_IMAGE = os.environ.get(
-    "BOT_BOTTLE_ORCHESTRATOR_IMAGE", "bot-bottle-orchestrator:latest"
-)
-ORCHESTRATOR_NAME = "bot-bottle-mac-orchestrator"
-ORCHESTRATOR_LABEL = "bot-bottle-mac-orchestrator=1"
-# Container-only volume holding bot-bottle.db, mounted ONLY into the
-# orchestrator. One kernel writes it (never host-shared or cross-guest).
-ORCHESTRATOR_DB_VOLUME = "bot-bottle-mac-db"
-
-# BOT_BOTTLE_ROOT inside the orchestrator; host_db_path() resolves the DB to
-# <root>/db/<filename>.
-_DB_ROOT_IN_CONTAINER = "/var/lib/bot-bottle"
-_SRC_IN_CONTAINER = "/bot-bottle-src"
-
-_HEALTH_POLL_SECONDS = 0.25
-
-
-class MacosOrchestrator(Orchestrator):
-    """The control plane as an Apple container on the host-only control network.
-    `ensure_built` builds `Dockerfile.orchestrator`; `ensure_running` starts it
-    and blocks until `/health` answers at its control-network address."""
-
-    def __init__(
-        self,
-        image_ref: str = ORCHESTRATOR_IMAGE,
-        *,
-        name: str = ORCHESTRATOR_NAME,
-        label: str = ORCHESTRATOR_LABEL,
-        port: int = DEFAULT_PORT,
-        control_network: str = CONTROL_NETWORK,
-        repo_root: Path | None = None,
-        db_volume: str = ORCHESTRATOR_DB_VOLUME,
-    ) -> None:
-        self.image_ref = image_ref
-        self.name = name
-        self.label = label
-        self.port = port
-        self.control_network = control_network
-        # Build context / bind-mount source: the repo root in a checkout, a
-        # staged copy from the installed wheel otherwise (bot_bottle.resources).
-        self._repo_root = repo_root if repo_root is not None else resources.build_root()
-        self._db_volume = db_volume
-
-    def url(self) -> str:
-        """The orchestrator's control-network address (host CLI + registration),
-        or "" while it has no address yet. Apple has no container DNS, so this is
-        also what the gateway resolves against (`gateway_url`)."""
-        ip = container_mod.try_container_ipv4_on_network(self.name, self.control_network)
-        return f"http://{ip}:{self.port}" if ip else ""
-
-    def gateway_url(self) -> str:
-        """Same address the host uses — the gateway reaches the orchestrator by
-        control-network IP (Apple has no container DNS)."""
-        return self.url()
-
-    def is_healthy(self, *, timeout: float = DEFAULT_HEALTH_TIMEOUT_SECONDS) -> bool:
-        url = self.url()
-        if not url:
-            return False
-        try:
-            with urllib.request.urlopen(f"{url}/health", timeout=timeout) as resp:
-                return resp.status == 200
-        except (urllib.error.URLError, TimeoutError, OSError):
-            return False
-
-    def is_running(self) -> bool:
-        return container_mod.container_is_running(self.name)
-
-    def _source_current(self, current_hash: str) -> bool:
-        """True iff the running orchestrator was created from the current
-        bind-mounted control-plane source (it loads that code at startup and
-        won't reload it)."""
-        if not self.is_running():
-            return False
-        env = container_mod.container_env(self.name)
-        if not env:
-            return True  # can't compare → don't churn a working container
-        return env.get("BOT_BOTTLE_SOURCE_HASH") == current_hash
-
-    def ensure_built(self) -> None:
-        """Build the control-plane image. The source is bind-mounted so a code
-        change takes effect without a rebuild; the image still carries the
-        package for its entrypoint."""
-        container_mod.build_image(
-            self.image_ref, str(self._repo_root), dockerfile="Dockerfile.orchestrator")
-
-    def ensure_running(
-        self, *, startup_timeout: float = DEFAULT_STARTUP_TIMEOUT_SECONDS,
-    ) -> None:
-        """Ensure the control-plane container is up on current source; block
-        until healthy. Idempotent — a healthy orchestrator on current source is
-        left untouched. Raises `OrchestratorStartError` on startup timeout.
-        The control network must already exist (the composer ensures it)."""
-        current_hash = source_hash(self._repo_root)
-        if self._source_current(current_hash) and self.is_healthy():
-            return
-        log.info("starting orchestrator container", context={"name": self.name})
-        self._run_container(current_hash)
-        self._wait_healthy(startup_timeout)
-
-    def _run_container(self, current_hash: str) -> None:
-        container_mod.force_remove_container(self.name)
-        # The signing key comes through the shared provisioning contract (#476),
-        # which fail-closes rather than yield an empty key that would run OPEN.
-        _signing_key = self.control_plane_key()
-        argv = [
-            "container", "run", "--detach",
-            "--name", self.name,
-            "--label", "bot-bottle.backend=macos-container",
-            "--label", self.label,
-            # Control network only — agents are never on it (L3-isolated).
-            "--network", self.control_network,
-            "--dns", container_mod.dns_server(),
-            # Container-only DB volume: exactly one kernel writes bot-bottle.db.
-            "--volume", f"{self._db_volume}:{_DB_ROOT_IN_CONTAINER}",
-            # Live control-plane source (a code change takes effect on relaunch).
-            "--mount",
-            container_mod.bind_mount_spec(
-                str(self._repo_root), _SRC_IN_CONTAINER, readonly=True),
-            "--env", f"PYTHONPATH={_SRC_IN_CONTAINER}",
-            "--env", f"BOT_BOTTLE_ROOT={_DB_ROOT_IN_CONTAINER}",
-            # Detect a real control-plane code change and recreate.
-            "--env", f"BOT_BOTTLE_SOURCE_HASH={current_hash}",
-            # The signing key — held ONLY by the orchestrator (issue #469). Bare
-            # `--env NAME` keeps the value off argv / `container inspect`.
-            "--env", ORCHESTRATOR_TOKEN_ENV,
-            self.image_ref,
-            # Dockerfile.orchestrator ENTRYPOINT is `-m bot_bottle.orchestrator`.
-            "--host", "0.0.0.0", "--port", str(self.port), "--broker", "stub",
-        ]
-        result = container_mod.run_container_argv(
-            argv, env={**os.environ, ORCHESTRATOR_TOKEN_ENV: _signing_key})
-        if result.returncode != 0:
-            raise OrchestratorStartError(
-                f"orchestrator container failed to start: "
-                f"{(result.stderr or '').strip() or '<no stderr>'}"
-            )
-
-    def _wait_healthy(self, startup_timeout: float) -> None:
-        deadline = time.monotonic() + startup_timeout
-        while True:
-            if self.is_healthy():
-                log.info("orchestrator healthy", context={"url": self.url()})
-                return
-            if time.monotonic() >= deadline:
-                raise OrchestratorStartError(
-                    f"orchestrator did not become healthy within "
-                    f"{startup_timeout:g}s"
-                )
-            time.sleep(_HEALTH_POLL_SECONDS)
-
-    def stop(self) -> None:
-        """Remove the control-plane container (idempotent). The DB volume
-        persists."""
-        container_mod.force_remove_container(self.name)
-
-
-def probe_orchestrator_url(port: int = DEFAULT_PORT) -> str:
-    """The running orchestrator's control-plane URL, or "" if it isn't up. Used
-    by host-side control-plane discovery; safe on any host (returns "" when the
-    container or the `container` CLI isn't present)."""
-    ip = container_mod.try_container_ipv4_on_network(ORCHESTRATOR_NAME, CONTROL_NETWORK)
-    return f"http://{ip}:{port}" if ip else ""
-
-
-__all__ = [
-    "MacosOrchestrator",
-    "ORCHESTRATOR_NAME",
-    "ORCHESTRATOR_LABEL",
-    "ORCHESTRATOR_IMAGE",
-    "ORCHESTRATOR_DB_VOLUME",
-    "probe_orchestrator_url",
-]

bot_bottle/backend/macos_container/resolve_plan.py

@@ -8,7 +8,7 @@ from ...agent_provider import AgentProvisionPlan
 from ...egress import EgressPlan
 from ...env import ResolvedEnv
 from ...git_gate import GitGatePlan
-from ...supervisor.plan import SupervisePlan
+from ...supervise import SupervisePlan
 from ...manifest import Manifest
 from .. import BottleSpec
 from . import util as container_mod
@@ -44,5 +44,4 @@ def resolve_plan(
         egress_plan=egress_plan,
         supervise_plan=supervise_plan,
         agent_provision=agent_provision_plan,
-        nested_containers=manifest.bottle.nested_containers,
     )

bot_bottle/backend/macos_container/util.py

@@ -10,7 +10,6 @@ import shutil
 import subprocess
 import tempfile
 import time
-from datetime import datetime, timezone
 from typing import Iterable
 
 from ...log import die, info
@@ -61,21 +60,13 @@ def dns_server() -> str:
 
 
 def build_image(ref: str, context: str, *, dockerfile: str = "") -> None:
-    """Build an OCI image with Apple's BuildKit-backed `container build`.
-
-    Set `BOT_BOTTLE_NO_CACHE=1` (the `start --no-cache` flag) to force
-    `--no-cache`. The npm/curl installers some provider Dockerfiles
-    shell out to can silently no-op on a transient network failure —
-    e.g. an `optionalDependencies` fetch for a platform-native binary —
-    and the builder will then cache that broken layer indefinitely."""
+    """Build an OCI image with Apple's BuildKit-backed `container build`."""
     info(
         f"building image {ref} from {context} with Apple Container "
         "(layer cache keeps repeat builds fast)"
     )
     _ensure_builder_dns()
     args = [_CONTAINER, "build", "-t", ref, "--dns", dns_server()]
-    if os.environ.get("BOT_BOTTLE_NO_CACHE") == "1":
-        args.append("--no-cache")
     if dockerfile:
         # `container build` resolves -f relative to the current working
         # directory, not the build context. Anchor a relative Dockerfile to
@@ -87,28 +78,6 @@ def build_image(ref: str, context: str, *, dockerfile: str = "") -> None:
     subprocess.run(args, check=True)
 
 
-def verify_agent_image(image: str, argv: tuple[str, ...]) -> None:
-    """Run `argv` inside a throwaway container of a freshly built agent
-    image and die loudly if it fails, instead of shipping an image
-    whose CLI only breaks at first real use. No-op when the provider
-    hasn't declared a smoke test (`AgentProviderRuntime.smoke_test`)."""
-    if not argv:
-        return
-    result = subprocess.run(
-        [_CONTAINER, "run", "--rm", "--entrypoint", argv[0], image, *argv[1:]],
-        capture_output=True,
-        text=True,
-        check=False,
-    )
-    if result.returncode != 0:
-        detail = (result.stderr or result.stdout or "").strip()
-        die(
-            f"agent image {image!r} failed its post-build smoke test "
-            f"({' '.join(argv)}): {detail}\n"
-            f"Try rebuilding from scratch: bot-bottle start --no-cache"
-        )
-
-
 def commit_container(container_name: str, image_tag: str) -> None:
     """Snapshot a running Apple Container as a local image.
 
@@ -361,27 +330,6 @@ def exec_container(name: str, argv: list[str]) -> None:
         )
 
 
-def read_container_env(name: str, env_name: str) -> str:
-    """Read one configured env value from a running container, or ``""``."""
-    result = _run_container_op([_CONTAINER, "exec", name, "printenv", env_name])
-    return result.stdout.strip() if result.returncode == 0 else ""
-
-
-def exec_container_as_root(name: str, argv: list[str]) -> None:
-    """`exec_container`, but as uid 0 inside the container.
-
-    For host-driven maintenance the agent itself must not be able to perform —
-    rewriting `/etc/hosts` to point the gateway name at an address. The agent
-    runs as `node`, so it cannot repoint its own gateway; the host can.
-    """
-    result = _run_container_op([_CONTAINER, "exec", "--user", "root", name, *argv])
-    if result.returncode != 0:
-        die(
-            f"container exec (root) in {name} failed: "
-            f"{(result.stderr or '').strip() or '<no stderr>'}"
-        )
-
-
 def _run_container_op(cmd: list[str]) -> subprocess.CompletedProcess[str]:
     result = subprocess.run(
         cmd,
@@ -459,180 +407,22 @@ def inspect_container(name: str) -> dict[str, object]:
 
 
 def container_ipv4_on_network(name: str, network: str) -> str:
-    """The container's IPv4 address on `network`. Fatal if absent — callers
-    that can tolerate "not yet" want `try_container_ipv4_on_network`."""
-    ip = try_container_ipv4_on_network(name, network)
-    if not ip:
-        die(f"container {name} has no IPv4 address on {network}")
-    return ip
-
-
-def run_container_argv(
-    argv: list[str], *, env: dict[str, str] | None = None,
-) -> subprocess.CompletedProcess[str]:
-    """Run a `container` command, returning the result for the caller to
-    interpret. Unlike the `die`-on-failure helpers above, this lets callers
-    that raise their own typed errors (the gateway / orchestrator lifecycle)
-    keep control of the failure path.
-
-    `env` sets the child process environment — used to hand a secret to a bare
-    `--env NAME` flag (Apple's "just key → inherit from host" form) so the
-    value is inherited from this process, never written onto argv or into
-    `container inspect`'s recorded command line."""
-    return subprocess.run(
-        argv, capture_output=True, text=True, check=False, env=env)
-
-
-def bind_mount_spec(source: str, target: str, *, readonly: bool = False) -> str:
-    """A `container run --mount` bind spec. One definition so the gateway and
-    orchestrator emit an identical string — a divergence here would silently
-    break one backend's mounts while the other kept working."""
-    spec = f"type=bind,source={source},target={target}"
-    if readonly:
-        spec += ",readonly"
-    return spec
-
-
-def _normalize_digest(value: str) -> str:
-    return value.split(":", 1)[1] if ":" in value else value
-
-
-def _inspect_first(argv: list[str]) -> dict[str, object]:
-    """Run an inspect command and return its first JSON object, or {} on any
-    failure (non-zero exit, malformed JSON, unexpected shape). {} is the shared
-    'don't know' signal all the non-fatal inspect readers below build on — a
-    caller comparing against it treats it as 'leave the working container
-    alone', never as a mismatch."""
-    result = run_container_argv(argv)
-    if result.returncode != 0:
-        return {}
-    try:
-        data = json.loads(result.stdout or "[]")
-    except json.JSONDecodeError:
-        return {}
-    if isinstance(data, list):
-        data = data[0] if data else {}
-    return data if isinstance(data, dict) else {}
-
-
-def _descriptor_digest(node: object) -> str:
-    """The normalized digest under a `{... "descriptor": {"digest": ...}}`
-    node, or "". Both the image and container inspect shapes nest the image's
-    identity this way, so the digest readers stay symmetric — a difference
-    between them is what would spuriously recreate a container."""
-    if not isinstance(node, dict):
-        return ""
-    descriptor = node.get("descriptor")
-    if isinstance(descriptor, dict) and descriptor.get("digest"):
-        return _normalize_digest(str(descriptor["digest"]))
-    return ""
-
-
-def image_digest(ref: str) -> str:
-    """The digest of image `ref`, or "" if it can't be read. Reads exactly the
-    field `container_image_digest` reads (`configuration.descriptor.digest`) so
-    the two are comparable; "" means 'don't know' → callers don't churn."""
-    data = _inspect_first([_CONTAINER, "image", "inspect", ref])
-    return _descriptor_digest(data.get("configuration"))
-
-
-def container_image_digest(name: str) -> str:
-    """The digest of the image container `name` was created from, or "" if it
-    can't be read. Compare with `image_digest(ref)` to tell whether a running
-    container predates an image rebuild."""
-    config = _inspect_first([_CONTAINER, "inspect", name]).get("configuration")
-    image = config.get("image") if isinstance(config, dict) else None
-    return _descriptor_digest(image)
-
-
-def container_env(name: str) -> dict[str, str]:
-    """The env container `name` was started with, or {} if unreadable. Lets a
-    caller tell whether a running container's baked-in configuration still
-    matches what it would pass today."""
-    config = _inspect_first([_CONTAINER, "inspect", name]).get("configuration")
-    init = config.get("initProcess") if isinstance(config, dict) else None
-    entries = init.get("environment") if isinstance(init, dict) else None
-    if not isinstance(entries, list):
-        return {}
-    env: dict[str, str] = {}
-    for entry in entries:
-        if isinstance(entry, str) and "=" in entry:
-            key, value = entry.split("=", 1)
-            env[key] = value
-    return env
-
-
-def try_container_ipv4_on_network(name: str, network: str) -> str:
-    """`container_ipv4_on_network` without the fatal exit: "" when the address
-    isn't readable yet. For pollers — a container is created before it has an
-    address, so "not yet" is an expected state there, not an error."""
-    status = _inspect_first([_CONTAINER, "inspect", name]).get("status")
-    networks = status.get("networks") if isinstance(status, dict) else None
-    if not isinstance(networks, list):
-        return ""
-    for entry in networks:
-        if not isinstance(entry, dict) or entry.get("network") != network:
-            continue
-        raw = entry.get("ipv4Address")
-        if isinstance(raw, str) and raw:
-            return raw.split("/", 1)[0]
-    return ""
-
-
-def inspect_container_network_ip(name: str, network: str) -> str | None:
-    """IP of `name` on `network`, distinguishing inspect failure from "not yet".
-
-    Returns:
-      - the IP string when the container has one on `network`
-      - "" when inspect succeeds but no address is assigned yet (in-flight DHCP)
-      - None when the inspect command itself fails (authoritative list impossible)
-    """
-    result = subprocess.run(
-        [_CONTAINER, "inspect", name],
-        capture_output=True, text=True, check=False,
-    )
-    if result.returncode != 0:
-        return None
-    try:
-        data = json.loads(result.stdout or "[]")
-    except json.JSONDecodeError:
-        return None
-    if isinstance(data, list):
-        data = data[0] if data else {}
-    if not isinstance(data, dict):
-        return None
+    data = inspect_container(name)
     status = data.get("status")
     networks = status.get("networks") if isinstance(status, dict) else None
     if not isinstance(networks, list):
-        return ""
+        die(f"container inspect {name} did not include status.networks")
     for entry in networks:
-        if not isinstance(entry, dict) or entry.get("network") != network:
+        if not isinstance(entry, dict):
+            continue
+        if entry.get("network") != network:
             continue
         raw = entry.get("ipv4Address")
-        if isinstance(raw, str) and raw:
-            return raw.split("/", 1)[0]
-    return ""
-
-
-def wait_container_ipv4_on_network(
-    name: str, network: str, *, timeout: float = 15.0, poll: float = 0.25,
-) -> str:
-    """Poll for the container's DHCP-assigned address on `network`, returning
-    it once available or "" on timeout.
-
-    Apple Container has no `--ip`: `container run --detach` can return before
-    vmnet's DHCP has populated `status.networks[].ipv4Address`, so a bare read
-    right after start races the assignment. Callers that need the address (the
-    attribution key, the gateway's proxy target) poll through here instead of
-    the fatal `container_ipv4_on_network`."""
-    deadline = time.monotonic() + timeout
-    while True:
-        ip = try_container_ipv4_on_network(name, network)
-        if ip:
-            return ip
-        if time.monotonic() >= deadline:
-            return ""
-        time.sleep(poll)
+        if not isinstance(raw, str) or not raw:
+            die(f"container {name} has no IPv4 address on {network}")
+        return raw.split("/", 1)[0]
+    die(f"container {name} is not attached to network {network}")
+    raise AssertionError("unreachable")
 
 
 def image_id(ref: str) -> str:
@@ -668,39 +458,6 @@ def image_id(ref: str) -> str:
     raise AssertionError("unreachable")
 
 
-def image_created_at(ref: str) -> datetime | None:
-    """Return the image creation timestamp as an aware UTC datetime, or None
-    when the field is absent or unparseable (e.g. FROM-scratch images, images
-    pulled from registries that omit the field). Callers should skip the stale
-    check when None is returned rather than treating it as an error."""
-    result = subprocess.run(
-        [_CONTAINER, "image", "inspect", ref],
-        capture_output=True,
-        text=True,
-        check=False,
-    )
-    if result.returncode != 0:
-        die(
-            f"container image inspect for {ref!r} failed: "
-            f"{(result.stderr or '').strip() or '<no stderr>'}"
-        )
-    try:
-        data = json.loads(result.stdout or "{}")
-    except json.JSONDecodeError as exc:
-        die(f"container image inspect for {ref!r} returned malformed JSON: {exc}")
-    if isinstance(data, list) and data:
-        data = data[0]
-    if isinstance(data, dict):
-        value = data.get("created") or data.get("Created")
-        if isinstance(value, str) and value:
-            try:
-                ts = value.rstrip("Z")
-                return datetime.fromisoformat(ts).replace(tzinfo=timezone.utc)
-            except ValueError:
-                pass
-    return None
-
-
 def save(ref: str, output: str) -> None:
     subprocess.run([_CONTAINER, "image", "save", ref, "-o", output], check=True)
 

bot_bottle/backend/preparation.py

@@ -1,124 +0,0 @@
-"""Backend-neutral preparation planner.
-
-This module owns the shared transformation from a CLI ``BottleSpec`` to the
-typed inputs consumed by a concrete backend's ``_resolve_plan``. Backend
-classes retain only their validation/preflight/env hooks and their
-backend-specific final resolution.
-"""
-
-from __future__ import annotations
-
-import os
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Protocol
-
-from ..agent_provider import AgentProvisionPlan, build_agent_provision_plan, get_provider
-from ..egress import EgressPlan
-from ..env import ResolvedEnv, resolve_env
-from ..git_gate import GitGate, GitGatePlan
-from ..manifest import Manifest
-from ..supervisor.plan import SupervisePlan
-from ..workspace import workspace_plan
-from .resolve_common import (
-    merge_provision_env_vars,
-    mint_slug,
-    prepare_agent_state_dir,
-    prepare_egress,
-    prepare_git_gate,
-    prepare_supervise,
-    reject_nested_containers,
-    resolve_manifest_dockerfile,
-    write_launch_metadata,
-)
-
-if TYPE_CHECKING:
-    from .base import BottleSpec
-
-
-class PreparationBackend(Protocol):
-    """Backend hooks needed by the shared planner."""
-
-    name: str
-    supports_nested_containers: bool
-
-    def _validate(self, spec: BottleSpec) -> Manifest: ...
-    def _preflight(self) -> None: ...
-    def _build_guest_env(self, resolved_env: ResolvedEnv) -> dict[str, str]: ...
-
-
-@dataclass(frozen=True)
-class PreparedBottle:
-    """Typed, backend-neutral result of shared launch preparation."""
-
-    manifest: Manifest
-    slug: str
-    resolved_env: ResolvedEnv
-    agent_provision_plan: AgentProvisionPlan
-    egress_plan: EgressPlan
-    git_gate_plan: GitGatePlan
-    supervise_plan: SupervisePlan | None
-
-
-class BottlePreparationPlanner:
-    """Run the common, side-effect-limited part of bottle preparation."""
-
-    def __init__(self, backend: PreparationBackend) -> None:
-        self._backend = backend
-
-    def prepare(self, spec: BottleSpec) -> PreparedBottle:
-        backend = self._backend
-        # These are deliberately protected backend hooks: only this shared
-        # planner orchestrates them, while concrete backends provide the
-        # implementation.
-        manifest = backend._validate(spec)  # pylint: disable=protected-access
-        if not backend.supports_nested_containers:
-            reject_nested_containers(backend.name, manifest)
-
-        backend._preflight()  # pylint: disable=protected-access
-        manifest = GitGate().preflight_host_keys(
-            manifest,
-            headless=spec.headless,
-            home_md=spec.manifest.home_md,
-        )
-
-        bottle = manifest.bottle
-        provider_config = bottle.agent_provider
-        provider = get_provider(provider_config.template)
-        resolved_env = resolve_env(manifest)
-        workspace = workspace_plan(spec, guest_home=provider.guest_home)
-        slug = mint_slug(spec)
-        write_launch_metadata(slug, spec, compose_project="", backend=backend.name)
-
-        dockerfile = (
-            resolve_manifest_dockerfile(provider_config.dockerfile, spec)
-            if provider_config.dockerfile
-            else str(provider.dockerfile)
-        )
-        agent_dir, prompt_file = prepare_agent_state_dir(slug, manifest)
-        provision = build_agent_provision_plan(
-            template=provider_config.template,
-            dockerfile=dockerfile,
-            state_dir=agent_dir,
-            instance_name=f"bot-bottle-{slug}",
-            prompt_file=prompt_file,
-            guest_env=backend._build_guest_env(  # pylint: disable=protected-access
-                resolved_env
-            ),
-            forward_host_credentials=provider_config.forward_host_credentials,
-            auth_token=provider_config.auth_token,
-            host_env=dict(os.environ),
-            trusted_project_path=workspace.workdir,
-            label=spec.label,
-            color=spec.color,
-            provider_settings=provider_config.settings,
-        )
-        provision = merge_provision_env_vars(provision)
-        return PreparedBottle(
-            manifest=manifest,
-            slug=slug,
-            resolved_env=resolved_env,
-            agent_provision_plan=provision,
-            egress_plan=prepare_egress(bottle, slug, provision),
-            git_gate_plan=prepare_git_gate(bottle, slug),
-            supervise_plan=prepare_supervise(bottle, slug),
-        )

bot_bottle/backend/provision_bottle.py

@@ -1,71 +0,0 @@
-"""Bottle-level provisioning for the consolidated launch sequence (PRD 0070).
-
-Register a bottle with the orchestrator and provision its git-gate state into
-the shared gateway (`provision_bottle`), and the inverse teardown
-(`deprovision_bottle`). Backend-neutral — each backend's consolidated_launch
-drives these through its own `GatewayTransport` rather than re-implementing
-them. The git-gate half of the work lives in `provision_gateway`.
-"""
-
-from __future__ import annotations
-
-import dataclasses
-
-from ..egress import EgressPlan
-from ..git_gate import GitGatePlan
-from ..orchestrator.client import OrchestratorClient, RegisteredBottle
-from ..orchestrator.registration import registration_inputs
-from ..orchestrator.store.secret_store import new_env_var_secret
-from .provision_gateway import GatewayTransport, deprovision_git_gate, provision_git_gate
-
-
-def provision_bottle(
-    client: OrchestratorClient,
-    source_ip: str,
-    egress_plan: EgressPlan,
-    git_gate_plan: GitGatePlan,
-    transport: GatewayTransport,
-    *,
-    image_ref: str = "",
-    tokens: dict[str, str] | None = None,
-    env_var_secret: str | None = None,
-) -> RegisteredBottle:
-    """Register the bottle and provision its git-gate state. Rolls back the
-    registration if provisioning fails so no orphan is left.
-
-    Generates a fresh ENV_VAR_SECRET, passes it to the orchestrator so it can
-    encrypt the token values at rest, and stamps the secret onto the returned
-    ``RegisteredBottle`` so callers can inject it into the agent container's
-    environment."""
-    inputs = registration_inputs(egress_plan)
-    env_var_secret = env_var_secret or new_env_var_secret()
-    reg = client.register_bottle(
-        source_ip, image_ref=image_ref, policy=inputs.policy,
-        metadata=inputs.metadata, tokens=tokens, env_var_secret=env_var_secret,
-    )
-    try:
-        provision_git_gate(transport, reg.bottle_id, git_gate_plan)
-    except Exception:
-        client.teardown_bottle(reg.bottle_id)
-        raise
-    return dataclasses.replace(reg, env_var_secret=env_var_secret)
-
-
-def deprovision_bottle(
-    bottle_id: str,
-    transport: GatewayTransport,
-    *,
-    orchestrator_url: str,
-    timeout: float | None = None,
-) -> None:
-    """Deregister the bottle and remove its git-gate state. Both steps are
-    idempotent so this is safe from a cleanup trap."""
-    from ..orchestrator.store.config_store import DEFAULT_TEARDOWN_TIMEOUT_SECONDS
-    OrchestratorClient(
-        orchestrator_url,
-        timeout=timeout if timeout is not None else DEFAULT_TEARDOWN_TIMEOUT_SECONDS,
-    ).teardown_bottle(bottle_id)
-    deprovision_git_gate(transport, bottle_id)
-
-
-__all__ = ["provision_bottle", "deprovision_bottle"]

bot_bottle/backend/provision_gateway.py

@@ -1,93 +0,0 @@
-"""Provision one bottle's git-gate state into the running shared gateway
-(PRD 0070). Backend-neutral: it drives any `GatewayTransport` (docker/apple
-exec+cp, firecracker SSH), and the guest-side paths it writes are identical
-inside every backend's gateway because they all run the same gateway image.
-
-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 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 ..git_gate import GitGatePlan, git_gate_render_provision
-from ..gateway import GatewayProvisionError, GatewayTransport
-
-# bottle ids index the gateway's per-bottle repo + creds dirs; they land in
-# exec/cp path arguments, so validate before any path is built (a traversal
-# id like "../etc" must never reach the gateway). Registry ids are token_hex —
-# this is defense in depth at the transport boundary.
-_SAFE_BOTTLE_ID = re.compile(r"[A-Za-z0-9_-]+")
-
-
-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 provision_git_gate(
-    transport: GatewayTransport, bottle_id: str, plan: GitGatePlan,
-) -> None:
-    """Place `bottle_id`'s git-gate credentials into the running gateway 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.
-    transport.exec(["mkdir", "-p", "/etc/git-gate"])
-    transport.cp_into(str(plan.hook_script), "/etc/git-gate/pre-receive")
-    transport.cp_into(str(plan.access_hook_script), "/etc/git-gate/access-hook")
-    # The access-hook is exec'd directly (not via `sh`), so it needs the x bit.
-    # Set it here rather than trusting the copy to carry the staged 0o700:
-    # `docker cp` preserves source mode, but the Apple `container cp` does not,
-    # landing the hook 0o644 → EACCES when the git-http handler tries to exec it.
-    # chmod on the gateway side is backend-neutral and fixes every transport.
-    transport.exec(["chmod", "+x", "/etc/git-gate/access-hook"])
-    creds = _creds_dir(bottle_id)
-    transport.exec(["mkdir", "-p", creds])
-    for u in plan.upstreams:
-        if u.identity_file:
-            transport.cp_into(u.identity_file, f"{creds}/{u.name}-key")
-        known_hosts = str(u.known_hosts_file)
-        if known_hosts and known_hosts != ".":
-            transport.cp_into(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)
-    transport.exec(["sh", "-c", script])
-
-
-def deprovision_git_gate(transport: GatewayTransport, 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)
-    try:
-        transport.exec([
-            "rm", "-rf", f"/git/{bottle_id}", _creds_dir(bottle_id),
-        ])
-    except GatewayProvisionError:
-        pass  # best-effort teardown; absent namespace is success
-
-
-__all__ = [
-    "provision_git_gate", "deprovision_git_gate",
-    "GatewayProvisionError", "GatewayTransport",
-]

bot_bottle/backend/resolve_common.py

@@ -26,11 +26,8 @@ from ..bottle_state import (
 )
 from ..egress import Egress, EgressPlan
 from ..git_gate import GitGate, GitGatePlan
-from ..log import die
 from ..manifest import Manifest, ManifestBottle
-from ..supervisor.plan import SupervisePlan
-from ..orchestrator.supervisor import Supervisor
-from ..util import slugify
+from ..supervise import Supervise, SupervisePlan
 from . import BottleSpec
 
 
@@ -45,7 +42,8 @@ def mint_slug(spec: BottleSpec) -> str:
     if spec.identity:
         return spec.identity
     if spec.label:
-        return slugify(spec.label)
+        from .docker import util as docker_mod
+        return docker_mod.slugify(spec.label)
     return bottle_identity(spec.agent_name)
 
 
@@ -96,13 +94,13 @@ def prepare_egress(
 
 
 def prepare_supervise(bottle: ManifestBottle, slug: str) -> SupervisePlan | None:
-    """Prepare the supervise daemon state dir. Returns None when
+    """Prepare the supervise sidecar state dir. Returns None when
     bottle.supervise is falsy."""
     if not bottle.supervise:
         return None
     supervise_dir = supervise_state_dir(slug)
     supervise_dir.mkdir(parents=True, exist_ok=True)
-    return Supervisor().prepare(slug, supervise_dir)
+    return Supervise().prepare(slug, supervise_dir)
 
 
 def merge_provision_env_vars(provision: AgentProvisionPlan) -> AgentProvisionPlan:
@@ -114,22 +112,6 @@ def merge_provision_env_vars(provision: AgentProvisionPlan) -> AgentProvisionPla
     return replace(provision, guest_env=merged)
 
 
-def reject_nested_containers(backend: str, manifest: Manifest) -> None:
-    """Fail loudly when a backend cannot honor `nested_containers: true`.
-
-    Silently ignoring it would hand the agent a bottle where `docker` is not
-    there — and the only sound alternatives on these backends (a host daemon
-    socket, a privileged container) are exactly what issue #392 rules out.
-    """
-    if not manifest.bottle.nested_containers:
-        return
-    die(
-        f"nested_containers is not supported on the {backend} backend. "
-        "Only macos-container runs a guest-local container engine today; "
-        "mounting the host Docker socket is not an option bot-bottle offers."
-    )
-
-
 def resolve_manifest_dockerfile(path_value: str, spec: BottleSpec) -> str:
     """Resolve a manifest-supplied dockerfile path relative to user_cwd."""
     path = Path(os.path.expanduser(path_value))
@@ -140,7 +122,6 @@ def resolve_manifest_dockerfile(path_value: str, spec: BottleSpec) -> str:
 
 __all__ = [
     "merge_provision_env_vars",
-    "reject_nested_containers",
     "mint_slug",
     "prepare_agent_state_dir",
     "prepare_egress",

bot_bottle/backend/selection.py

@@ -1,211 +0,0 @@
-"""Backend registry, selection, and active-agent enumeration.
-
-Resolves which bottle backend to use (explicit name / `BOT_BOTTLE_BACKEND` /
-auto-select), and enumerates running agents across every available backend. The
-three concrete backends are imported lazily inside `_get_backends` so this
-module — and anything that only needs to *select* a backend — stays cheap.
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-from typing import Any
-
-from ..log import die, info, warn
-from ..util import read_tty_line
-from .base import ActiveAgent, BackendStatus, BottleBackend
-
-
-# _backends is None until the first call to _get_backends(), at which
-# point all three concrete backend classes are imported and instantiated.
-# Keeping the imports out of module scope means that importing any
-# backend sub-module (e.g. `backend.docker.util`) no longer drags the
-# firecracker and macos-container implementations into memory.
-#
-# Tests may replace _backends with a {name: fake} dict via patch.object;
-# _get_backends() returns the current module-level value as-is when it
-# is not None, so test fakes take effect without triggering real imports.
-_backends: dict[str, BottleBackend[Any, Any]] | None = None
-
-
-def _get_backends() -> dict[str, BottleBackend[Any, Any]]:
-    """Return the registry of all backend instances, loading lazily on first call."""
-    global _backends  # pylint: disable=global-statement
-    if _backends is None:
-        from .docker import DockerBottleBackend
-        from .firecracker import FirecrackerBottleBackend
-        from .macos_container import MacosContainerBottleBackend
-        _backends = {
-            "docker": DockerBottleBackend(),
-            "firecracker": FirecrackerBottleBackend(),
-            "macos-container": MacosContainerBottleBackend(),
-        }
-    return _backends
-
-
-def get_bottle_backend(
-    name: str | None = None,
-    *,
-    prompt: bool = True,
-) -> BottleBackend[Any, Any]:
-    """Resolve the bottle backend.
-
-    `name` precedence:
-      1. explicit arg (e.g. resume passes the recorded backend name)
-      2. BOT_BOTTLE_BACKEND env var
-      3. auto-selection: VM backend first, docker fallback with prompt
-
-    `prompt` controls whether auto-selection may block on an interactive
-    [i/d/q] prompt when falling back to docker. Pass `prompt=False` in
-    non-interactive contexts (headless launches, CI) so the call dies
-    with an actionable message instead of hanging.
-
-    Dies with a pointer at the known backends if the chosen name
-    isn't implemented."""
-    resolved = name or os.environ.get("BOT_BOTTLE_BACKEND")
-    if resolved is None:
-        resolved = _auto_select_backend(prompt=prompt)
-    backends = _get_backends()
-    if resolved not in backends:
-        known = ", ".join(sorted(backends))
-        die(f"unknown backend {resolved!r}; known backends: {known}")
-    return backends[resolved]
-
-
-def _platform_vm_suggestion() -> str:
-    """Platform-appropriate VM backend name for install suggestions."""
-    return "macos-container" if sys.platform == "darwin" else "firecracker"
-
-
-def _print_vm_install_instructions() -> None:
-    """Print platform-appropriate VM backend install instructions to stderr."""
-    vm = _platform_vm_suggestion()
-    if vm == "macos-container":
-        info("Install Apple Container: https://github.com/apple/container/releases")
-        info("Then start the service:  container system start")
-    else:
-        info("Install Firecracker: https://github.com/firecracker-microvm/firecracker/releases")
-        info("Configure the host:  ./cli.py backend setup")
-
-
-def _auto_select_backend(prompt: bool = True) -> str:
-    """Tier-1 / tier-2 backend auto-selection.
-
-    Tier 1: VM backend — macos-container on macOS when Apple Container is
-    installed; firecracker on KVM-capable Linux even before the binary is
-    present (its preflight prints an install pointer).
-
-    Tier 2: docker, with a security warning and an interactive prompt.
-    When `prompt=False` (headless / CI), dies with an actionable message
-    instead of blocking on a TTY read. When docker is also absent, prints
-    VM install instructions and exits.
-    """
-    # --- Tier 1: VM backend -----------------------------------------
-    if has_backend("macos-container"):
-        return "macos-container"
-    # A KVM-capable Linux host defaults to firecracker even when the
-    # `firecracker` binary isn't installed yet: selecting it here routes
-    # start through firecracker's preflight, which prints an install
-    # pointer, instead of silently falling back to docker.
-    from .firecracker import FirecrackerBottleBackend
-    if FirecrackerBottleBackend.is_host_capable():
-        return "firecracker"
-
-    # --- Tier 2: docker fallback ------------------------------------
-    if not has_backend("docker"):
-        info("No backend available on this host.")
-        _print_vm_install_instructions()
-        die("no backend available; install a VM backend and re-run")
-
-    vm = _platform_vm_suggestion()
-    warn(
-        "docker is less secure than VM backends — "
-        "containers share the host kernel."
-    )
-    if not prompt:
-        die(
-            f"no VM backend available; set BOT_BOTTLE_BACKEND=docker to proceed "
-            f"with docker, or install the {vm!r} backend."
-        )
-    sys.stderr.write(
-        f"bot-bottle: For better isolation, install the {vm!r} backend.\n"
-        f"  [i] show {vm} install instructions and exit\n"
-        "  [d] use docker anyway\n"
-        "  [q] quit\n"
-        "bot-bottle: choice [i/d/q]: "
-    )
-    sys.stderr.flush()
-    reply = read_tty_line().strip().lower()
-    if reply == "d":
-        return "docker"
-    if reply == "i":
-        _print_vm_install_instructions()
-    die("not proceeding with docker; install a VM backend or set BOT_BOTTLE_BACKEND=docker")
-
-
-def known_backend_names() -> tuple[str, ...]:
-    """Sorted tuple of all backend keys in `_get_backends()`. Used by
-    argparse (`--backend` choices) and the dashboard's backend
-    picker."""
-    return tuple(sorted(_get_backends()))
-
-
-def has_backend(name: str) -> bool:
-    """Whether the named backend's runtime prerequisites are
-    available on the current host. Cross-backend callers (list,
-    cleanup) skip unavailable backends so a docker-only host
-    doesn't fail when the firecracker backend isn't usable,
-    and vice versa.
-
-    Returns False for unknown names so callers can pass
-    arbitrary input without separate validation."""
-    backends = _get_backends()
-    if name not in backends:
-        return False
-    return backends[name].is_available()
-
-
-def is_backend_available(name: str) -> bool:
-    """Cheap availability check: is the backend's binary on PATH?
-
-    Suitable for cleanup enumeration and auto-selection — does NOT probe
-    the daemon or network pool. Use is_backend_ready() for a full
-    readiness check before launching tests."""
-    return has_backend(name)
-
-
-def is_backend_ready(name: str, *, quiet: bool = False) -> bool:
-    """Full readiness check: passes all of the backend's status() checks.
-
-    When quiet=False the backend prints diagnostic output explaining what
-    is missing — intended for test-suite guards that run at discovery time
-    so the operator sees a concrete failure reason for each skip.
-
-    Returns False for unknown backend names."""
-    backends = _get_backends()
-    if name not in backends:
-        return False
-    return backends[name].status(quiet=quiet) == BackendStatus.READY
-
-
-def enumerate_active_agents() -> list[ActiveAgent]:
-    """All currently-running agents, across every available
-    backend. Used by CLI `active` and the dashboard's agents
-    pane so neither has to know which backends exist. Skips
-    backends whose `is_available()` reports False.
-
-    Sorted by `(started_at, slug)` so the list is stable across
-    dashboard refresh ticks — agents don't shift position while
-    the operator navigates with arrow keys. ISO 8601 timestamps
-    sort lexicographically in chronological order; `slug` is the
-    deterministic tiebreaker. Agents with missing metadata
-    (`started_at == ""`) sort first."""
-    out: list[ActiveAgent] = []
-    backends = _get_backends()
-    for name in sorted(backends):
-        if not backends[name].is_available():
-            continue
-        out.extend(backends[name].enumerate_active())
-    out.sort(key=lambda a: (a.started_at, a.slug))
-    return out

bot_bottle/backend/util.py

@@ -7,8 +7,6 @@ from __future__ import annotations
 import hashlib
 import os
 import ssl
-import time
-from collections.abc import Callable
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -17,24 +15,6 @@ from ..log import die, info
 if TYPE_CHECKING:
     from ..egress import EgressPlan
 
-_CA_POLL_INTERVAL = 0.5
-
-
-def poll_ca_cert(fetch: Callable[[], str | None], *, timeout: float) -> str:
-    """Poll `fetch` until it returns a non-empty PEM string or `timeout` expires.
-
-    `fetch` should return the PEM on success and `None` (or empty string) when
-    the cert is not yet available. Raises `TimeoutError` if the cert never
-    appears within `timeout` seconds."""
-    deadline = time.monotonic() + timeout
-    while True:
-        result = fetch()
-        if result:
-            return result
-        if time.monotonic() >= deadline:
-            raise TimeoutError(f"CA cert not available after {timeout:g}s")
-        time.sleep(_CA_POLL_INTERVAL)
-
 
 # Debian-family CA layout, shared by every backend (all guest images
 # are Debian-family). AGENT_CA_PATH is the source path that

bot_bottle/bottle_state.py

@@ -31,7 +31,6 @@ from __future__ import annotations
 import dataclasses
 import json
 import secrets
-import socket
 import string
 from dataclasses import dataclass
 from pathlib import Path
@@ -44,18 +43,17 @@ from .paths import bot_bottle_root
 _STATE_SUBDIR = "state"
 _PER_BOTTLE_DOCKERFILE_NAME = "Dockerfile"
 _COMMITTED_IMAGE_NAME = "committed-image"
-_COMMITTED_ROOTFS_NAME = "committed-rootfs.tar"
 _TRANSCRIPT_SUBDIR = "transcript"
-# Per-daemon scratch subdirs. PRD 0018 chunk 2: bind-mount sources
+# Per-sidecar 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 daemon's `prepare()` writes config + CAs into its own
+# paths. Each sidecar'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 daemon (read-only).
+# Live-config dir bind-mounted into the supervise sidecar (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.
@@ -89,14 +87,6 @@ def bottle_identity(agent_name: str) -> str:
     return f"{slug}-{suffix}"
 
 
-def globalize_slug(slug: str) -> str:
-    """Return a globally-unique slug qualified with the current hostname.
-
-    Assumes slug is a value returned from mint_slug. Use wherever a slug
-    must be unique across hosts (e.g. deploy-key titles)."""
-    return f"{socket.gethostname()}-{slug}"
-
-
 @dataclass(frozen=True)
 class BottleMetadata:
     """Persistent record of how a bottle was launched, written at
@@ -201,15 +191,6 @@ def committed_image_path(identity: str) -> Path:
     return bottle_state_dir(identity) / _COMMITTED_IMAGE_NAME
 
 
-def committed_rootfs_path(identity: str) -> Path:
-    """Where the Firecracker freezer stores a snapshot of the bottle's
-    guest rootfs (a plain tar). This is the resumable/migratable artifact
-    the Firecracker backend boots from — no Docker image involved. The
-    matching `committed-image` state file records that a snapshot exists
-    (and its path); `resume` boots from this tar when both are present."""
-    return bottle_state_dir(identity) / _COMMITTED_ROOTFS_NAME
-
-
 def write_committed_image(identity: str, image_tag: str) -> Path:
     """Persist the committed image tag for `identity`. The next
     `cli.py resume <identity>` will boot from this image instead of
@@ -241,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 daemon; the host's apply paths refresh the files on
+    supervise sidecar; 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
@@ -279,9 +260,9 @@ def transcript_snapshot_dir(identity: str) -> Path:
     return bottle_state_dir(identity) / _TRANSCRIPT_SUBDIR
 
 
-# --- Per-daemon scratch subdirs (PRD 0018 chunk 2) ------------------------
+# --- Per-sidecar scratch subdirs (PRD 0018 chunk 2) ------------------------
 #
-# Each daemon gets its own subdir under the bottle's state dir for
+# Each sidecar 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
@@ -289,20 +270,20 @@ def transcript_snapshot_dir(identity: str) -> Path:
 
 
 def egress_state_dir(identity: str) -> Path:
-    """State subdir for the egress daemon: routes.yaml + the
+    """State subdir for the egress sidecar: 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 daemon: entrypoint + hooks +
+    """State subdir for the git-gate sidecar: 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 daemon bind-mount sources.
+    """State subdir reserved for supervise sidecar 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
@@ -359,12 +340,10 @@ __all__ = [
     "BottleMetadata",
     "agent_state_dir",
     "bottle_identity",
-    "globalize_slug",
     "bottle_state_dir",
     "cleanup_state",
     "clear_preserve_marker",
     "committed_image_path",
-    "committed_rootfs_path",
     "egress_state_dir",
     "git_gate_state_dir",
     "is_preserved",

bot_bottle/cli/__init__.py

@@ -1,15 +1,110 @@
-"""bot-bottle CLI package.
+"""Main CLI dispatcher.
 
-The subcommand handlers live in `commands/` and are assembled into the
-COMMANDS registry by `commands/__init__.py`; the dispatcher `main()` lives
-in `__main__.py`. They are re-exported here so `bot_bottle.cli.main`,
-`bot_bottle.cli.COMMANDS`, and `bot_bottle.cli.NO_MIGRATION_COMMANDS` stay
-importable (the repo-root `cli.py` entry point and the tests use them).
+Commands: backend, cleanup, commit, edit, info, init, list, resume, start, supervise
 """
 
 from __future__ import annotations
 
-from .__main__ import main
-from .commands import COMMANDS, NO_MIGRATION_COMMANDS
+import sys
 
-__all__ = ["main", "COMMANDS", "NO_MIGRATION_COMMANDS"]
+from ..errors import MissingEnvVarError
+from ..log import Die, die, error
+from ..manifest import ManifestError
+from ..store_manager import StoreManager
+from ._common import PROG
+from . import list as _list_mod
+from .backend import cmd_backend
+from .cleanup import cmd_cleanup
+from .commit import cmd_commit
+from .edit import cmd_edit
+from .info import cmd_info
+from .init import cmd_init
+from .resume import cmd_resume
+from .start import cmd_start
+from .supervise import cmd_supervise
+
+cmd_list = _list_mod.cmd_list
+
+COMMANDS = {
+    "backend": cmd_backend,
+    "cleanup": cmd_cleanup,
+    "commit": cmd_commit,
+    "edit": cmd_edit,
+    "info": cmd_info,
+    "init": cmd_init,
+    "list": cmd_list,
+    "resume": cmd_resume,
+    "start": cmd_start,
+    "supervise": cmd_supervise,
+}
+
+
+def usage() -> None:
+    sys.stderr.write(f"usage: {PROG} <command> [args...]\n\n")
+    sys.stderr.write("Commands:\n")
+    sys.stderr.write("  backend   set up / check / undo a backend's host prerequisites (setup|status|teardown)\n")
+    sys.stderr.write("  cleanup   stop and remove all active bot-bottle containers\n")
+    sys.stderr.write("  commit    snapshot a running bottle's container state to a Docker image\n")
+    sys.stderr.write("  edit      open an agent in vim for editing\n")
+    sys.stderr.write("  info      print env, skills, and prompt details for a named agent\n")
+    sys.stderr.write("  init      interactively create a new agent and add it to bot-bottle.json\n")
+    sys.stderr.write("  list      list available agents or active containers\n")
+    sys.stderr.write(
+        "  resume    re-launch a bottle by its identity "
+        "(continues state from PRD 0016)\n"
+    )
+    sys.stderr.write(
+        "  start     boot a container for a named agent and "
+        "attach an interactive session\n"
+    )
+    sys.stderr.write(
+        "  supervise view + approve/modify/reject pending supervise "
+        "proposals (PRD 0013)\n\n"
+    )
+    sys.stderr.write(f"Run '{PROG} <command> --help' for command-specific usage.\n")
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    if not argv:
+        usage()
+        return 2
+    command = argv[0]
+    rest = argv[1:]
+    if command in ("-h", "--help"):
+        usage()
+        return 0
+    handler = COMMANDS.get(command)
+    if handler is None:
+        usage()
+        die(f"unknown command: {command}")
+    mgr = StoreManager.instance()
+    if not mgr.is_migrated():
+        sys.stderr.write("bot-bottle: database schema is out of date\n")
+        sys.stderr.write("Migrate now? [y/N] ")
+        sys.stderr.flush()
+        try:
+            answer = sys.stdin.readline().strip().lower()
+        except EOFError:
+            answer = ""
+        if answer != "y":
+            error("migration required — re-run and confirm to migrate")
+            return 1
+        mgr.migrate()
+    try:
+        return handler(rest) or 0
+    except MissingEnvVarError as e:
+        error(str(e))
+        return 1
+    except ManifestError as e:
+        error(str(e))
+        return 1
+    except Die as e:
+        return e.code if isinstance(e.code, int) else 1
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bot_bottle/cli/__main__.py

@@ -1,65 +0,0 @@
-"""Entry point + dispatcher for `python -m bot_bottle.cli`.
-
-Maps `bot-bottle <command>` to its handler in the COMMANDS registry
-(`bot_bottle.cli.commands`), enforces the schema-migration gate, and
-translates handler exceptions into process exit codes. The repo-root
-`cli.py` is the usual way in; this makes the package runnable too, so the
-CLI works from an installed copy where there is no `cli.py` on disk.
-"""
-
-from __future__ import annotations
-
-import sys
-
-from ..errors import MissingEnvVarError
-from ..log import Die, die, error
-from ..manifest import ManifestError
-from ..orchestrator.store.store_manager import StoreManager
-from .commands import COMMANDS, NO_MIGRATION_COMMANDS
-from .commands.help import cmd_help
-
-
-def main(argv: list[str] | None = None) -> int:
-    if argv is None:
-        argv = sys.argv[1:]
-    if not argv:
-        cmd_help()
-        return 2
-    command = argv[0]
-    rest = argv[1:]
-    if command in ("-h", "--help"):
-        cmd_help()
-        return 0
-    handler = COMMANDS.get(command)
-    if handler is None:
-        cmd_help()
-        die(f"unknown command: {command}")
-    mgr = StoreManager.instance()
-    if command not in NO_MIGRATION_COMMANDS and not mgr.is_migrated():
-        sys.stderr.write("bot-bottle: database schema is out of date\n")
-        sys.stderr.write("Migrate now? [y/N] ")
-        sys.stderr.flush()
-        try:
-            answer = sys.stdin.readline().strip().lower()
-        except EOFError:
-            answer = ""
-        if answer != "y":
-            error("migration required — re-run and confirm to migrate")
-            return 1
-        mgr.migrate()
-    try:
-        return handler(rest) or 0
-    except MissingEnvVarError as e:
-        error(str(e))
-        return 1
-    except ManifestError as e:
-        error(str(e))
-        return 1
-    except Die as e:
-        return e.code if isinstance(e.code, int) else 1
-    except KeyboardInterrupt:
-        return 130
-
-
-if __name__ == "__main__":
-    sys.exit(main())

bot_bottle/cli/_common.py

@@ -0,0 +1,20 @@
+"""Shared constants and tty helper for cli subcommands."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+PROG = "cli.py"
+USER_CWD = os.getcwd()
+REPO_DIR = str(Path(__file__).resolve().parent.parent.parent)
+
+
+def read_tty_line() -> str:
+    """Mirror `IFS= read -r REPLY </dev/tty`. Falls back to stdin."""
+    try:
+        with open("/dev/tty", "r", encoding="utf-8") as tty:
+            return tty.readline().rstrip("\n")
+    except OSError:
+        return sys.stdin.readline().rstrip("\n")

bot_bottle/cli/backend.py

@@ -15,8 +15,8 @@ from __future__ import annotations
 
 import argparse
 
-from ...backend import get_bottle_backend, known_backend_names
-from ..constants import PROG
+from ..backend import get_bottle_backend, known_backend_names
+from ._common import PROG
 
 
 def cmd_backend(args: list[str]) -> int:

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 VM processes and run dirs won't survive a
-docker-only cleanup pass (issue addressed alongside #77).
+firecracker bottle's sidecars won't survive a docker-only cleanup pass
+(issue addressed alongside #77).
 
 Each backend's `prepare_cleanup` enumerates its own resources;
 docker's `_list_orphan_state_dirs` consults
@@ -21,20 +21,16 @@ from __future__ import annotations
 
 import sys
 
-from ...backend import get_bottle_backend, has_backend, known_backend_names
-from ...log import info
-from ...util import read_tty_line
+from ..backend import get_bottle_backend, known_backend_names
+from ..log import info
+from ._common import read_tty_line
 
 
 def cmd_cleanup(_argv: list[str]) -> int:
     # Order: stable backend iteration so the y/N output is
-    # deterministic across runs. Skip backends whose runtime
-    # isn't available on this host so e.g. macos-container
-    # doesn't error on Linux.
+    # deterministic across runs.
     plans = [
-        (name, get_bottle_backend(name))
-        for name in known_backend_names()
-        if has_backend(name)
+        (name, get_bottle_backend(name)) for name in known_backend_names()
     ]
     prepared = [(name, b, b.prepare_cleanup()) for name, b in plans]