feat(claude): add forward_host_credentials support

Reads the host's Claude OAuth session key from ~/.claude.json at launch and forwards it only to the egress sidecar (never to the agent), placing a placeholder CLAUDE_CODE_OAUTH_TOKEN in the agent env so Claude Code starts without seeing the real credential. Mirrors the existing Codex forward_host_credentials flow (PRD 0029). Adds claude_auth.py to extract and validate the sessionKey, a CLAUDE_HOST_CREDENTIAL_TOKEN_REF constant in egress.py, and updates manifest_agent.py to allow the flag for both 'codex' and 'claude' templates. Also adds a mutual-exclusion check that rejects setting both auth_token and forward_host_credentials together. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> fix(claude): read credentials from ~/.claude/.credentials.json The actual OAuth token is in ~/.claude/.credentials.json under claudeAiOauth.accessToken, not in ~/.claude.json. ~/.claude.json holds only UI state and profile metadata (oauthAccount has no token fields). expiresAt in the credentials file is milliseconds, not seconds. Discovered after testing against Claude Code 2.1.198. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> fix(claude): fall back to macOS Keychain for credentials On macOS, Claude Code stores credentials in the Keychain under service "Claude Code-credentials" rather than in a file. When ~/.claude/.credentials.json is absent, shell out to: security find-generic-password -s "Claude Code-credentials" -w and parse the result as the same JSON schema. ~/.claude.json holds only profile/UI metadata (oauthAccount has no token fields). expiresAt in the credentials is milliseconds. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> docs(prd): fix credential path references (~/.claude/.credentials.json) fix(test): suppress gitleaks false positives on synthetic Claude tokens
test(backend): cover poll_ca_cert timeout paths for diff-coverage gate
2026-07-21 01:46:53 -04:00 · 2026-07-21 04:54:40 +00:00 · 2026-07-21 04:54:40 +00:00 · 2026-07-21 04:54:40 +00:00 · 2026-07-21 04:54:40 +00:00 · 2026-07-21 04:54:40 +00:00
149 changed files with 9478 additions and 1832 deletions
@@ -22,10 +22,7 @@ jobs:
      - name: Checkout
        uses: actions/checkout@v4
-      - name: Set up Python
+      # No actions/setup-python: canaries are stdlib unittest on the image's
-        uses: actions/setup-python@v5
+      # system Python 3.12 (older act_runner mishandles setup-python's PATH).
        with:
          python-version: "3.12"
      - name: Run canaries
        run: python3 -m unittest discover -t . -s tests/canaries -v
@@ -13,20 +13,30 @@ jobs:
    steps:
      - uses: actions/checkout@v3
-      - name: Set up Python
+      # No actions/setup-python: the runner image already ships Python 3.12,
-        uses: actions/setup-python@v4
+      # and older act_runner engines mishandle setup-python's PATH. Install
-        with:
+      # into the ephemeral job container's system Python — the pylint/pyright
-          python-version: "3.12"
+      # 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: Install dev dependencies
-        run: |
+        run: python3 -m pip install --break-system-packages -r requirements-dev.txt
          python -m pip install --upgrade pip
          pip install -r requirements-dev.txt
      - name: Run pylint
        run: |
-          # Run pylint on all Python files in the repo
+          # Pylint's normal exit code is nonzero for any emitted finding,
-          find . -name '*.py' -not -path './.venv/*' -not -path './.git/*' | xargs pylint --fail-under=8.0
+          # 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) }'
      - name: Run pyright
        run: |
@@ -37,11 +37,8 @@ jobs:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}
-      - name: Set up Python
+      # No actions/setup-python: the inline script is stdlib-only on the
-        uses: actions/setup-python@v5
+      # image's system Python 3.12 (older act_runner mishandles its PATH).
        with:
          python-version: "3.12"
      - name: Configure git
        run: |
          git config user.name "github-actions[bot]"
@@ -4,16 +4,15 @@
 # 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
+#   tests/integration/  — need a reachable backend; skip cleanly when
-#                         (via tests/_docker.py:skip_unless_docker) when
+#                         the backend isn't available on the runner
 #                         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
+# Integration tests run once per backend in separate jobs. Each job sets
-# socket to the job container so `docker` commands inside the job can
+# BOT_BOTTLE_BACKEND explicitly so the test suite uses the right backend.
-# reach the daemon. If that's not yet configured on the runner the
+# Backends that aren't available on the runner fail the preflight step
-# integration tests will skip rather than fail.
+# rather than silently skipping inside the test output.
 name: test
@@ -23,24 +22,84 @@ on:
      - main
    paths:
      - '**.py'
      - '.gitea/workflows/**.yml'
      - 'scripts/**'
      - 'README.md'
      # Dockerfiles and pyproject.toml are baked into the infra rootfs; a
      # change here alters what the integration/coverage jobs build locally.
      - 'Dockerfile*'
      - 'pyproject.toml'
  pull_request:
    paths:
      - '**.py'
      - '.gitea/workflows/**.yml'
      - 'scripts/**'
      - 'README.md'
      - 'Dockerfile*'
      - 'pyproject.toml'
  workflow_dispatch:
 jobs:
  stage-firecracker-inputs:
    runs-on: [self-hosted, kvm]
    # Same guard as the other KVM-runner jobs: don't spin the privileged
    # runner for fork PRs (this only copies a non-secret static binary, but
    # keep the posture consistent — build-infra/integration/coverage all
    # depend on it, so gating here gates the whole Firecracker chain).
    if: >-
      github.event_name == 'push' ||
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'pull_request' &&
       github.event.pull_request.head.repo.full_name == github.repository)
    steps:
      - name: Stage the provisioned static dropbear
        run: |
          mkdir -p firecracker-inputs
          cp /var/cache/bot-bottle-fc/dropbear firecracker-inputs/dropbear
      - name: Upload Firecracker build inputs
        uses: actions/upload-artifact@v3
        with:
          name: firecracker-inputs
          path: firecracker-inputs/
  build-infra:
    needs: stage-firecracker-inputs
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Download Firecracker build inputs
        uses: actions/download-artifact@v3
        with:
          name: firecracker-inputs
          path: firecracker-inputs
      - name: Build infra candidate from this checkout
        env:
          BOT_BOTTLE_FC_DROPBEAR: ${{ github.workspace }}/firecracker-inputs/dropbear
        run: python3 -m bot_bottle.backend.firecracker.publish_infra --output infra-candidate
      - name: Upload infra candidate
        uses: actions/upload-artifact@v3
        with:
          name: infra-candidate
          path: infra-candidate/
  unit:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
-      - name: Set up Python
+      # No actions/setup-python: the runner image already ships Python 3.12,
-        uses: actions/setup-python@v5
+      # and older act_runner engines mishandle setup-python's PATH (coverage
-        with:
+      # lands in one interpreter, `python3` resolves to another). Install
-          python-version: "3.12"
+      # 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 -r requirements-dev.txt
+        run: python3 -m pip install --break-system-packages -r requirements-dev.txt
      - name: Run unit tests
        run: python3 -m coverage run -m unittest discover -t . -s tests/unit -v
@@ -48,17 +107,14 @@ jobs:
      - name: Report unit coverage
        run: python3 -m coverage report -m
-  integration:
+  integration-docker:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
-      - name: Set up Python
+      # No actions/setup-python (see the note in the `unit` job); the
-        uses: actions/setup-python@v5
+      # container's system Python 3.12 runs the stdlib test suite directly.
        with:
          python-version: "3.12"
      - name: Show environment
        run: |
          python3 --version
@@ -68,33 +124,150 @@ jobs:
            echo "docker not on PATH — integration tests will skip"
          fi
-      - name: Run integration tests
+      - name: Run integration tests (docker)
        env:
          BOT_BOTTLE_BACKEND: docker
        run: python3 -m unittest discover -t . -s tests/integration -v
-  # Combined unit+integration coverage report (informational). See
+  # Integration tests against the Firecracker backend. Runs on a self-hosted
-  # docs/decisions/0004-coverage-policy.md.
+  # KVM runner (label `kvm`) where /dev/kvm and the TAP/nft pool are available.
  #
-  # The hard diff-coverage gate (changed lines >= 90%) is DEFERRED: the
+  # Restricted to same-repo PRs, push to main, and workflow_dispatch — fork
-  # Firecracker backend's VM/SSH orchestration is covered by the integration
+  # PRs don't execute untrusted code on the privileged runner.
-  # suite, which needs /dev/kvm + the provisioned TAP/nft pool — a
+  #
-  # container-based runner skips it and those lines read uncovered, so the
+  # Runner prerequisites (provision once; see README "Firecracker on Linux"):
-  # gate can't pass here. Re-enabling it on a self-hosted KVM runner is
+  # `firecracker` on PATH, `/dev/kvm` accessible, cached kernel +
-  # tracked separately (see PRD 0069 / #348 and the ci-runner branch).
+  # static dropbear, and the pool as a persistent systemd unit.
  integration-firecracker:
    needs: build-infra
    runs-on: [self-hosted, kvm]
    if: >-
      github.event_name == 'push' ||
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'pull_request' &&
       github.event.pull_request.head.repo.full_name == github.repository)
    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: Download the candidate built from this checkout
        uses: actions/download-artifact@v3
        with:
          name: infra-candidate
          path: infra-candidate
      - 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: the integration suite runs on stdlib
      # `unittest` (pylint/pyright are lint.yml's concern, not this job's),
      # and the self-hosted runner's Nix python env has no `pip` module
      # (`python3 -m pip` → "No module named pip"). Nothing to install.
      - name: Run integration tests (firecracker)
        env:
          BOT_BOTTLE_BACKEND: firecracker
          BOT_BOTTLE_INFRA_ARTIFACT_DIR: ${{ github.workspace }}/infra-candidate
        run: python3 -m unittest discover -t . -s tests/integration -v
  # Combined unit+integration coverage + the diff-coverage gate (the hard
  # gate: new/changed lines >= 90%). See docs/decisions/0004-coverage-policy.md.
  #
  # This runs on a self-hosted KVM runner (label `kvm`), NOT ubuntu-latest,
  # because the Firecracker backend's subprocess/VM orchestration
  # (launch/boot/SSH/isolation-probe) is covered by the integration suite,
  # and that suite needs `/dev/kvm` + the provisioned TAP/nft pool — which a
  # container-based runner doesn't have. On such a runner the firecracker
  # integration test skips and its ~230 orchestration lines read as
  # uncovered, so the gate can't pass there.
  #
  # Restricted to the same events as integration-firecracker (same-repo PRs,
  # push, workflow_dispatch) for the same security reason.
  #
  # See #414 for the planned follow-up: artifact-based coverage combination
  # (run tests once in their respective jobs, combine .coverage files here).
  #
  # build-infra creates one candidate from the checkout. This job boots that
  # same candidate after integration-firecracker has exercised it; the main
  # push path publishes the identical bytes only after every required job.
  coverage:
-    runs-on: ubuntu-latest
+    needs: [build-infra, integration-firecracker]
    timeout-minutes: 15
    runs-on: [self-hosted, kvm]
    if: >-
      github.event_name == 'push' ||
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'pull_request' &&
       github.event.pull_request.head.repo.full_name == github.repository)
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
-      - name: Set up Python
+      - name: Preflight — Firecracker host is ready
-        uses: actions/setup-python@v5
+        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: Download the candidate already exercised by integration
        uses: actions/download-artifact@v3
        with:
-          python-version: "3.12"
+          name: infra-candidate
          path: infra-candidate
-      - name: Install dev requirements
+      # No dev-requirements install: `coverage` is already provided by the
-        run: python3 -m pip install -r requirements-dev.txt
+      # self-hosted runner's Nix python env, and that env has no `pip`
-
+      # module to install into anyway. `scripts/coverage.sh` +
-      - name: Combined coverage report (unit + integration)
+      # `diff_coverage.py` need only `coverage` (not pylint/pyright).
      - name: Combined coverage (unit + integration, incl. firecracker)
        env:
          BOT_BOTTLE_CI_INFRA_ARTIFACT_DIR: ${{ github.workspace }}/infra-candidate
        run: PYTHON=python3 bash scripts/coverage.sh 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: [stage-firecracker-inputs, build-infra, unit, integration-docker, integration-firecracker, coverage]
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - name: Checkout the tested revision
        uses: actions/checkout@v4
      - name: Download the tested candidate
        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. Stage the SAME dropbear build-infra used, or the recheck
      # computes a "<missing>"-dropbear version and rejects the candidate.
      - name: Download the staged dropbear (matches build-infra's version)
        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
@@ -0,0 +1,17 @@
 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
@@ -0,0 +1,18 @@
 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
@@ -20,21 +20,18 @@ jobs:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}
-      - name: Set up Python
+      # No actions/setup-python: the runner image ships Python 3.12 and older
-        uses: actions/setup-python@v4
+      # act_runner engines mishandle setup-python's PATH. Install into the
-        with:
+      # ephemeral job container's system Python (--break-system-packages is
-          python-version: '3.12'
+      # safe because the container is disposable).
      - name: Install dev dependencies
-        run: |
+        run: python3 -m pip install --break-system-packages -r requirements-dev.txt
          python -m pip install --upgrade pip
          pip install -r requirements-dev.txt
      - name: Run coverage and extract percentage
        id: coverage
        run: |
-          python -m coverage run -m unittest discover -t . -s tests/unit > /dev/null 2>&1 || true
+          python3 -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)
+          PERCENT=$(python3 -m coverage report 2>/dev/null | grep '^TOTAL' | grep -oP '\d+(?=%)' | tail -1)
          echo "percent=$PERCENT" >> $GITHUB_OUTPUT
          echo "Coverage: $PERCENT%"
@@ -45,7 +42,7 @@ jobs:
          # 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)
+          PERCENT=$(python3 -m coverage report --include="$INCLUDE" 2>/dev/null | grep '^TOTAL' | grep -oP '\d+(?=%)' | tail -1)
          echo "percent=$PERCENT" >> $GITHUB_OUTPUT
          echo "Core coverage: $PERCENT%"
@@ -16,10 +16,11 @@
 # Layout:
 #
 #   /usr/bin/gitleaks                    gitleaks binary
-#   /app/egress_addon.py + siblings      mitmproxy addon (egress)
+#   /app/egress_addon.py                 mitmproxy addon entry point
 #   /app/egress-entrypoint.sh            mitmdump launcher
-#   /app/supervise_server.py + .py       supervise MCP server
+#   /usr/local/lib/python*/bot_bottle/   installed package (all daemons + shared modules)
-#   /app/gateway_init.py                 PID 1 supervisor
+#   /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
@@ -66,35 +67,41 @@ RUN pip install --no-cache-dir mitmproxy==11.1.3
 # 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=551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb
+ARG GITLEAKS_SHA256_AMD64=551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb
-RUN url="https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" \
+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 "${GITLEAKS_SHA256}  /tmp/gitleaks.tar.gz" | sha256sum -c - \
+ && echo "${sha}  /tmp/gitleaks.tar.gz" | sha256sum -c - \
 && tar -xzf /tmp/gitleaks.tar.gz -C /usr/bin gitleaks \
 && rm /tmp/gitleaks.tar.gz
-# Project Python: addon + server modules + the init supervisor.
+# Install bot_bottle as a proper package so entry-point scripts can use
-# Kept flat under /app/ so mitmdump's loader resolves them as
+# `from bot_bottle.X import Y` absolute imports. A rename or a missing
-# top-level siblings (absolute imports), matching the prior
+# module is caught at pip-install time — not at container runtime.
-# Dockerfile.egress / Dockerfile.supervise layout.
+COPY pyproject.toml /src/
-COPY bot_bottle/egress_addon_core.py /app/egress_addon_core.py
+COPY bot_bottle/    /src/bot_bottle/
-COPY bot_bottle/egress_dlp_config.py /app/egress_dlp_config.py
+RUN pip install --no-cache-dir /src/
-COPY bot_bottle/egress_addon.py      /app/egress_addon.py
+
-COPY bot_bottle/policy_resolver.py   /app/policy_resolver.py
+# mitmdump -s requires a file path, not a module. Write a one-line shim that
-COPY bot_bottle/dlp_detectors.py     /app/dlp_detectors.py
+# re-exports `addons` from the installed package; mitmdump finds it there.
-COPY bot_bottle/yaml_subset.py       /app/yaml_subset.py
+# WORKDIR here also creates /app so the shim + COPYs below can write into it
-COPY bot_bottle/paths.py             /app/paths.py
+# (nothing created /app before this point).
-COPY bot_bottle/migrations.py        /app/migrations.py
+WORKDIR /app
-COPY bot_bottle/db_store.py          /app/db_store.py
+RUN printf 'from bot_bottle.egress_addon import addons\n' > /app/egress_addon.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/gateway_init.py      /app/gateway_init.py
 COPY bot_bottle/git_http_backend.py  /app/git_http_backend.py
 COPY bot_bottle/egress_entrypoint.sh /app/egress-entrypoint.sh
 RUN chmod +x /app/egress-entrypoint.sh
@@ -113,10 +120,6 @@ RUN mkdir -p \
 # 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/gateway_init.py"]
+ENTRYPOINT ["python3", "-m", "bot_bottle.gateway_init"]
@@ -1,45 +1,22 @@
-# Firecracker single infra-VM image (PRD 0070 Stage B).
+# Shared infra image: gateway data plane + orchestrator control plane.
 #
-# The per-host infra VM runs the orchestrator control plane, the gateway
+# Used directly by the Docker backend (run as one `bot-bottle-infra`
-# data plane, AND builds agent images (buildah) — all in one microVM (see
+# container, replacing the prior two-container split). The Firecracker
-# backend/firecracker/infra_vm.py). It composes:
+# backend extends this via Dockerfile.infra.fc, adding buildah/crun/
-#   * FROM the gateway image (mitmproxy / git / gitleaks / supervise + the
+# netavark for in-VM agent-image building.
-#     flat daemon modules) — now trixie-based, so buildah 1.39 is available;
+#
-#   * `COPY --from` the orchestrator image's content (the single definition
+# Dockerfile.orchestrator is the single definition of the orchestrator
-#     of the control-plane payload — see Dockerfile.orchestrator), so this
+# content (the lean `bot_bottle` package on python:3.12-slim). Both this
-#     VM and the docker backend share one orchestrator definition; and
+# image and Dockerfile.infra.fc pull it in via `COPY --from`.
 #   * buildah, installed HERE only (the docker orchestrator/gateway images
 #     never carry it).
 #
 # multi-`FROM` can't union two bases (that's multi-stage, not multiple
 # inheritance), so the orchestrator content is pulled in via `COPY --from`
 # rather than a second base. Both images share the trixie `python:3.12-slim`
 # base, so the copy is clean (same python; future installed deps copy too).
 #
 # The docker backend keeps orchestrator + gateway as separate images; this
 # combined image exists only for the Firecracker single-VM cut. Splitting a
 # service back into its own VM later is a routing change, not a repackaging
 # (PRD 0070's "secret concentration"; a disposable builder can boot from
 # this same image on its own TAP).
 FROM bot-bottle-gateway:latest
-# --- in-VM agent-image builder (PRD 0069 Stage 3) -------------------
+# The orchestrator content, from its single definition. The gateway image
-# The Firecracker backend builds users' agent Dockerfiles *inside this VM*
+# already has the flat daemon modules under /app; this adds the full
-# with buildah (rootless, daemonless) instead of on the host — no host
+# `bot_bottle` package so `python3 -m bot_bottle.orchestrator` resolves —
-# Docker daemon, no root-equivalent `docker` group. `crun` is the OCI
+# used by gateway_init when BOT_BOTTLE_GATEWAY_DAEMONS includes `orchestrator`.
 # runtime; `netavark` + `aardvark-dns` are the network backend for `FROM`
 # pulls + `RUN` egress. Requires the trixie base (buildah 1.39: bookworm's
 # 1.28 can't parse Dockerfile heredocs that agent images use).
 RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      buildah crun netavark aardvark-dns \
 && rm -rf /var/lib/apt/lists/*
 # vfs + chroot: buildah works as root in the bare microVM (no
 # fuse-overlayfs / overlay module / subuid maps). Matches image_builder.
 ENV STORAGE_DRIVER=vfs \
    BUILDAH_ISOLATION=chroot
 # The orchestrator content, pulled from its single definition. The gateway
 # image already has the flat daemon modules under /app; this adds the full
 # `bot_bottle` package so `python3 -m bot_bottle.orchestrator` resolves.
 COPY --from=bot-bottle-orchestrator:latest /app/bot_bottle /app/bot_bottle
@@ -0,0 +1,23 @@
 # Firecracker infra VM image (PRD 0070 Stage B).
 #
 # Extends the shared infra base (Dockerfile.infra: gateway + orchestrator
 # control plane) with 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.
 #
 # Requires the trixie base from bot-bottle-gateway (buildah 1.39: bookworm's
 # 1.28 can't parse Dockerfile heredocs that agent images use).
 #
 # `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). Matches image_builder.
 FROM bot-bottle-infra: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
@@ -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-82%25-brightgreen)](https://coverage.readthedocs.io/)
+[![coverage](https://img.shields.io/badge/coverage-81%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)
+[![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)
 **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.
@@ -90,6 +90,8 @@ 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:** the coverage gate (`.gitea/workflows/test.yml` → `coverage` job) runs on a self-hosted runner labelled `kvm`, because the Firecracker backend's VM/SSH orchestration is exercised only by the integration suite, which needs `/dev/kvm` + the provisioned pool (a container runner would skip it and read as uncovered). Provision that runner exactly like a normal Firecracker host — `firecracker` on `PATH`, `/dev/kvm`, the cached guest kernel + static dropbear, and the pool installed as the persistent systemd unit — then register it with the `kvm` label. A Docker-capable hosted job builds the candidate once; KVM tests boot those exact bytes, and a successful main run publishes them. The unit/lint jobs still run on `ubuntu-latest`.
 ```sh
 ./cli.py start <agent>   # builds the image on first run, drops you into claude
 ```
@@ -171,6 +173,15 @@ 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.
@@ -45,6 +45,10 @@ 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",
@@ -42,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._connect() as conn:
+        with self._connection() as conn:
            conn.execute(
                """
                INSERT INTO supervise_audit_entries (
@@ -66,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._connect() as conn:
+        with self._connection() as conn:
            rows = conn.execute(
                """
                SELECT * FROM supervise_audit_entries
@@ -40,12 +40,13 @@ from abc import ABC, abstractmethod
 from contextlib import AbstractContextManager
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Generic, Sequence, TypeVar
+from typing import TYPE_CHECKING, Any, Generic, Sequence, TypeVar
 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 ..log import die, info, warn
 from ..util import read_tty_line
 from ..manifest import Manifest, ManifestIndex
 from ..supervise import SupervisePlan
 from ..util import expand_tilde
@@ -54,6 +55,9 @@ from ..workspace import WorkspacePlan, workspace_plan
 from .print_util import print_multi, visible_agent_env_names
 from .util import host_skill_dir
 if TYPE_CHECKING:
    from .freeze import CommitCancelled, Freezer, get_freezer
@dataclass(frozen=True)
 class BottleSpec:
@@ -584,68 +588,170 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
        Not called by the launch path or the test suite."""
-# Import concrete backend classes AFTER the base types are defined, so
+# _backends is None until the first call to _get_backends(), at which
-# each backend module can pull BottleSpec / BottlePlan / BottleBackend
+# point all three concrete backend classes are imported and instantiated.
-# via `from . import ...` without hitting a partially-initialized module.
+# Keeping the imports out of module scope means that importing any
-from .docker import DockerBottleBackend  # noqa: E402  # pylint: disable=wrong-import-position
+# backend sub-module (e.g. `backend.docker.util`) no longer drags the
-from .firecracker import FirecrackerBottleBackend  # noqa: E402  # pylint: disable=wrong-import-position
+# firecracker and macos-container implementations into memory.
-from .macos_container import MacosContainerBottleBackend  # noqa: E402  # pylint: disable=wrong-import-position
+#
-
+# Tests may replace _backends with a {name: fake} dict via patch.object;
-# Freezer is imported after the backend classes for the same reason:
+# _get_backends() returns the current module-level value as-is when it
-# Freezer.commit_slug constructs ActiveAgent, which must be fully
+# is not None, so test fakes take effect without triggering real imports.
-# defined first.
+_backends: dict[str, BottleBackend[Any, Any]] | None = None
 from .freeze import CommitCancelled, Freezer, get_freezer  # noqa: E402  # pylint: disable=wrong-import-position
-# The dict is heterogeneous: each value is a BottleBackend specialized
+def _get_backends() -> dict[str, BottleBackend[Any, Any]]:
-# over its own plan type. Concrete plan types are erased here because
+    """Return the registry of all backend instances, loading lazily on first call."""
-# the registry is selected at runtime and the CLI only needs the
+    global _backends  # pylint: disable=global-statement
-# unparameterized methods (prepare → plan → launch(plan), cleanup, etc.).
+    if _backends is None:
-_BACKENDS: dict[str, BottleBackend[Any, Any]] = {
+        from .docker import DockerBottleBackend
-    "docker": DockerBottleBackend(),
+        from .firecracker import FirecrackerBottleBackend
-    "firecracker": FirecrackerBottleBackend(),
+        from .macos_container import MacosContainerBottleBackend
-    "macos-container": MacosContainerBottleBackend(),
+        _backends = {
-}
+            "docker": DockerBottleBackend(),
            "firecracker": FirecrackerBottleBackend(),
            "macos-container": MacosContainerBottleBackend(),
        }
    return _backends
 def __getattr__(name: str) -> Any:
    """Lazily surface concrete backend classes and freeze symbols at the
    package level so existing `from bot_bottle.backend import X` and
    `patch.object(backend_mod, X, ...)` call-sites keep working without
    forcing an import of every backend at module-init time."""
    if name == "DockerBottleBackend":
        from .docker import DockerBottleBackend
        globals()[name] = DockerBottleBackend
        return DockerBottleBackend
    if name == "FirecrackerBottleBackend":
        from .firecracker import FirecrackerBottleBackend
        globals()[name] = FirecrackerBottleBackend
        return FirecrackerBottleBackend
    if name == "MacosContainerBottleBackend":
        from .macos_container import MacosContainerBottleBackend
        globals()[name] = MacosContainerBottleBackend
        return MacosContainerBottleBackend
    if name == "CommitCancelled":
        from .freeze import CommitCancelled
        globals()[name] = CommitCancelled
        return CommitCancelled
    if name == "Freezer":
        from .freeze import Freezer
        globals()[name] = Freezer
        return Freezer
    if name == "get_freezer":
        from .freeze import get_freezer
        globals()[name] = get_freezer
        return get_freezer
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 def get_bottle_backend(
    name: str | None = None,
    *,
    prompt: bool = True,
 ) -> BottleBackend[Any, Any]:
    """Resolve the bottle backend.
    `name` precedence:
-      1. explicit arg (CLI `--backend=<name>` passes through here)
+      1. explicit arg (e.g. resume passes the recorded backend name)
      2. BOT_BOTTLE_BACKEND env var
-      3. `macos-container` on compatible macOS hosts
+      3. auto-selection: VM backend first, docker fallback with prompt
-      4. `firecracker` on KVM-capable Linux hosts
+
-      5. default `docker`
+    `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") or _default_backend_name()
+    resolved = name or os.environ.get("BOT_BOTTLE_BACKEND")
-    if resolved not in _BACKENDS:
+    if resolved is None:
-        known = ", ".join(sorted(_BACKENDS))
+        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]
+    return backends[resolved]
-def _default_backend_name() -> str:
+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"
-    return "docker"
+
    # --- 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 `_BACKENDS`. Used by
+    """Sorted tuple of all backend keys in `_get_backends()`. Used by
    argparse (`--backend` choices) and the dashboard's backend
    picker."""
-    return tuple(sorted(_BACKENDS))
+    return tuple(sorted(_get_backends()))
 def has_backend(name: str) -> bool:
@@ -657,9 +763,10 @@ def has_backend(name: str) -> bool:
    Returns False for unknown names so callers can pass
    arbitrary input without separate validation."""
-    if name not in _BACKENDS:
+    backends = _get_backends()
    if name not in backends:
        return False
-    return _BACKENDS[name].is_available()
+    return backends[name].is_available()
 def enumerate_active_agents() -> list[ActiveAgent]:
@@ -675,10 +782,11 @@ def enumerate_active_agents() -> list[ActiveAgent]:
    deterministic tiebreaker. Agents with missing metadata
    (`started_at == ""`) sort first."""
    out: list[ActiveAgent] = []
-    for name in known_backend_names():
+    backends = _get_backends()
-        if not has_backend(name):
+    for name in sorted(backends):
        if not backends[name].is_available():
            continue
-        out.extend(_BACKENDS[name].enumerate_active())
+        out.extend(backends[name].enumerate_active())
    out.sort(key=lambda a: (a.started_at, a.slug))
    return out
@@ -0,0 +1,60 @@
 """Shared helpers for the consolidated launch sequence (PRD 0070).
 Logic that was duplicated across the docker, macos_container, and
 firecracker consolidated_launch modules — extracted so each backend
 imports it rather than re-implementing it.
 """
 from __future__ import annotations
 from ..egress import EgressPlan
 from ..git_gate import GitGatePlan
 from ..orchestrator.client import OrchestratorClient
 from ..orchestrator.registration import registration_inputs
 from .docker.gateway_provision 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,
 ):
    """Register the bottle and provision its git-gate state. Rolls back the
    registration if provisioning fails so no orphan is left. Returns the
    `RegisteredBottle` from the orchestrator."""
    inputs = registration_inputs(egress_plan)
    reg = client.register_bottle(
        source_ip, image_ref=image_ref, policy=inputs.policy,
        metadata=inputs.metadata, tokens=tokens,
    )
    try:
        provision_git_gate(transport, reg.bottle_id, git_gate_plan)
    except Exception:
        client.teardown_bottle(reg.bottle_id)
        raise
    return reg
 def teardown_consolidated(
    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.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", "teardown_consolidated"]
@@ -1,19 +1,13 @@
 """Consolidated bottle launch sequence for the docker backend (PRD 0070).
-Composes the orchestrator primitives into the register/teardown sequence that
+Composes the orchestrator primitives into the register/teardown sequence:
 replaces the per-bottle gateway:
-  1. ensure the orchestrator control plane + shared gateway are up;
+  1. ensure the single infra container (control plane + gateway) is up;
-  2. allocate the bottle a pinned source IP on the gateway network (the
+  2. allocate the bottle a pinned source IP on the gateway network;
-     attribution key), skipping the gateway's own address + live bottles;
+  3. register it and provision its git-gate repos/creds into the gateway.
  3. register it (egress policy blob + slug metadata) → bottle id + identity
     token;
  4. provision its git-gate repos/creds into the running gateway.
-It returns a `LaunchContext` with everything the agent container needs to
+Returns a `LaunchContext` with everything the agent container needs to
-attach — network, pinned IP, the gateway's address (its proxy target), the
+attach. The agent `docker run` itself is the backend's job; this owns the
 orchestrator URL, and the identity token. The agent `docker run` itself is
 the backend's job (it owns provider provisioning); this owns the
 orchestrator-facing wiring so that sequence stays testable in isolation.
 """
@@ -25,15 +19,12 @@ from ...docker_cmd import run_docker
 from ...egress import EgressPlan
 from ...git_gate import GitGatePlan
 from ...orchestrator.client import OrchestratorClient
-from ...orchestrator.gateway import GATEWAY_NAME, GATEWAY_NETWORK
+from ...orchestrator.gateway import GATEWAY_NETWORK
-from ...orchestrator.lifecycle import OrchestratorService
+from ...orchestrator.lifecycle import INFRA_NAME, OrchestratorService
-from ...orchestrator.registration import registration_inputs
+from ..consolidated_util import provision_bottle
 from ..consolidated_util import teardown_consolidated as _teardown_util
 from .gateway_provision import DockerGatewayTransport
 from .gateway_net import next_free_ip
 from .gateway_provision import (
    DockerGatewayTransport,
    deprovision_git_gate,
    provision_git_gate,
 )
 class ConsolidatedLaunchError(RuntimeError):
@@ -75,24 +66,21 @@ def _container_ip(name: str, network: str) -> str:
    ip = proc.stdout.strip()
    if proc.returncode != 0 or not ip:
        raise ConsolidatedLaunchError(
-            f"gateway {name} has no address on {network}: {proc.stderr.strip()}"
+            f"container {name} has no address on {network}: {proc.stderr.strip()}"
        )
    return ip
 def _network_container_ips(network: str) -> list[str]:
    """Every address currently assigned on the gateway network — the ground
-    truth for "in use": the gateway + orchestrator infrastructure containers
+    truth for "in use": the infra container and every live agent. Read from
-    and every live agent. Read from the network so a new bottle can't collide
+    the network so a new bottle can't collide with anything actually attached."""
    with anything actually attached (a registry-only view would miss the
    orchestrator/gateway containers)."""
    proc = run_docker([
        "docker", "network", "inspect", "--format",
        "{{range .Containers}}{{.IPv4Address}} {{end}}", network,
    ])
    ips: list[str] = []
    for entry in proc.stdout.split():
        # entries look like "172.20.0.2/16" — keep the address.
        ips.append(entry.split("/", 1)[0])
    return ips
@@ -104,33 +92,24 @@ def launch_consolidated(
    image_ref: str = "",
    tokens: dict[str, str] | None = None,
    service: OrchestratorService | None = None,
-    gateway_name: str = GATEWAY_NAME,
+    infra_name: str = INFRA_NAME,
    network: str = GATEWAY_NETWORK,
 ) -> LaunchContext:
-    """Ensure the orchestrator + gateway are up, allocate + register the
+    """Ensure the infra container is up, allocate + register the bottle, and
-    bottle, and provision its git-gate state. Returns the agent's attach
+    provision its git-gate state. Returns the agent's attach context."""
    context. Raises `ConsolidatedLaunchError` (or the primitives' own errors)
    if any step fails — the caller tears down on failure."""
    service = service or OrchestratorService()
    url = service.ensure_running()
    client = OrchestratorClient(url)
    cidr = _network_cidr(network)
-    gateway_ip = _container_ip(gateway_name, network)
+    gateway_ip = _container_ip(infra_name, network)
    source_ip = next_free_ip(cidr, _network_container_ips(network))
-    inputs = registration_inputs(egress_plan)
+    transport = DockerGatewayTransport(infra_name)
-    reg = client.register_bottle(
+    reg = provision_bottle(
-        source_ip, image_ref=image_ref, policy=inputs.policy,
+        client, source_ip, egress_plan, git_gate_plan, transport,
-        metadata=inputs.metadata, tokens=tokens,
+        image_ref=image_ref, tokens=tokens,
    )
    try:
        provision_git_gate(
            DockerGatewayTransport(gateway_name), reg.bottle_id, git_gate_plan)
    except Exception:
        # Roll the registration back so a provisioning failure leaves no orphan.
        client.teardown_bottle(reg.bottle_id)
        raise
    return LaunchContext(
        bottle_id=reg.bottle_id,
        identity_token=reg.identity_token,
@@ -142,12 +121,12 @@ def launch_consolidated(
 def teardown_consolidated(
-    bottle_id: str, *, orchestrator_url: str, gateway_name: str = GATEWAY_NAME,
+    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 from the gateway.
+    """Deregister the bottle and remove its git-gate state. Idempotent."""
-    Both steps are idempotent so this is safe from a cleanup trap."""
+    _teardown_util(bottle_id, DockerGatewayTransport(infra_name),
-    OrchestratorClient(orchestrator_url).teardown_bottle(bottle_id)
+                   orchestrator_url=orchestrator_url, timeout=timeout)
    deprovision_git_gate(DockerGatewayTransport(gateway_name), bottle_id)
 __all__ = [
@@ -94,6 +94,12 @@ def provision_git_gate(
    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:
@@ -62,6 +62,7 @@ from .compose import (
    write_compose_file,
 )
 from .consolidated_compose import consolidated_agent_compose
 from ...orchestrator.config_store import resolve_teardown_timeout
 from .consolidated_launch import launch_consolidated, teardown_consolidated
 from ...orchestrator.gateway import DockerGateway
@@ -133,11 +134,14 @@ def launch(
        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(
-            teardown_consolidated, ctx.bottle_id, orchestrator_url=ctx.orchestrator_url,
+            teardown_consolidated, ctx.bottle_id,
            orchestrator_url=ctx.orchestrator_url,
            timeout=teardown_timeout,
        )
        # Step 4: install the SHARED gateway CA into the agent (replaces the
@@ -27,10 +27,14 @@ def _docker_on_path() -> bool:
 def _daemon_reachable() -> bool:
    if not _docker_on_path():
        return False
-    return subprocess.run(
+    try:
-        ["docker", "info"],
+        return subprocess.run(
-        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
+            ["docker", "info"],
-    ).returncode == 0
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
            check=False, timeout=5,
        ).returncode == 0
    except subprocess.TimeoutExpired:
        return False
 def _print_install_pointer() -> None:
@@ -8,7 +8,7 @@ import os
 import re
 import shutil
 import subprocess
-from typing import Iterable, Iterator
+from typing import Iterator
 from ...docker_cmd import run_docker
 from ...log import die, info
@@ -32,12 +32,7 @@ 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 = subprocess.run(
+    r = run_docker(["docker", "info", "--format", "{{json .Runtimes}}"])
        ["docker", "info", "--format", "{{json .Runtimes}}"],
        capture_output=True,
        text=True,
        check=False,
    )
    return r.returncode == 0 and "runsc" in r.stdout
@@ -51,20 +46,15 @@ def require_docker() -> None:
 def image_exists(ref: str) -> bool:
-    return _silent_run(["docker", "image", "inspect", ref]) == 0
+    return run_docker(["docker", "image", "inspect", ref]).returncode == 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 = subprocess.run(
+    result = run_docker(["docker", "ps", "-a", "-q", "-f", f"name=^{name}$"])
-        ["docker", "ps", "-a", "-q", "-f", f"name=^{name}$"],
+    return result.returncode == 0 and bool(result.stdout.strip())
        capture_output=True,
        text=True,
        check=True,
    )
    return bool(result.stdout.strip())
 def force_remove_container(name: str) -> None:
@@ -72,12 +62,7 @@ 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):
-        subprocess.run(
+        run_docker(["docker", "rm", "-f", name])
            ["docker", "rm", "-f", name],
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL,
            check=False,
        )
 def docker_exec_root(container: str, argv: list[str]) -> None:
@@ -205,22 +190,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 = subprocess.run(
+    result = run_docker(["docker", "commit", container_name, image_tag])
        ["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: "
            f"{(result.stderr or '').strip() or '<no stderr>'}"
        )
    info(f"committed {container_name!r} → {image_tag!r}")
 def _silent_run(cmd: Iterable[str]) -> int:
    return subprocess.run(
        list(cmd),
        stdout=subprocess.DEVNULL,
        stderr=subprocess.DEVNULL,
        check=False,
    ).returncode
@@ -33,8 +33,7 @@ from ...orchestrator.client import OrchestratorClient
 from ...orchestrator.lifecycle import (
    OrchestratorStartError,  # re-exported so callers can catch it
 )
-from ...orchestrator.registration import registration_inputs
+from ..consolidated_util import provision_bottle, teardown_consolidated as _teardown_util
 from ..docker.gateway_provision import deprovision_git_gate, provision_git_gate
 from . import infra_vm
@@ -68,18 +67,11 @@ def launch_consolidated(
    url = infra.control_plane_url
    client = OrchestratorClient(url)
-    inputs = registration_inputs(egress_plan)
+    transport = infra_vm.gateway_transport()
-    reg = client.register_bottle(
+    reg = provision_bottle(
-        guest_ip, image_ref=image_ref, policy=inputs.policy,
+        client, guest_ip, egress_plan, git_gate_plan, transport,
-        metadata=inputs.metadata, tokens=tokens,
+        image_ref=image_ref, tokens=tokens,
    )
    try:
        provision_git_gate(
            infra_vm.gateway_transport(), reg.bottle_id, git_gate_plan)
    except Exception:
        client.teardown_bottle(reg.bottle_id)
        raise
    # The shared gateway CA every agent on this host trusts for TLS
    # interception — fetched from the infra VM over SSH.
    return LaunchContext(
@@ -91,13 +83,15 @@ def launch_consolidated(
    )
-def teardown_consolidated(bottle_id: str, *, orchestrator_url: str) -> None:
+def teardown_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 VM — it's a persistent per-host singleton shared by
    every bottle."""
-    OrchestratorClient(orchestrator_url).teardown_bottle(bottle_id)
+    _teardown_util(bottle_id, infra_vm.gateway_transport(),
-    deprovision_git_gate(infra_vm.gateway_transport(), bottle_id)
+                   orchestrator_url=orchestrator_url, timeout=timeout)
 __all__ = [
@@ -1,9 +1,12 @@
-"""FirecrackerFreezer — snapshot a running microVM to a Docker image.
+"""FirecrackerFreezer — snapshot a running microVM to a rootfs tar.
 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) and rebuild an image from it. The bottle keeps
+channel (SSH here). Unlike the other backends this needs no Docker: the
-running after the snapshot.
+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_agent_base`). The bottle keeps running after the
 snapshot.
 """
 from __future__ import annotations
@@ -11,9 +14,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
@@ -30,14 +33,13 @@ 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?)")
-        image_tag = f"bot-bottle-committed-{agent.slug}:latest"
+        tar_path = committed_rootfs_path(agent.slug)
-        _commit_via_ssh(private_key, guest_ip, image_tag)
+        _commit_rootfs_via_ssh(private_key, guest_ip, tar_path)
-        info(f"committed {agent.slug} -> {image_tag!r}")
+        info(f"committed {agent.slug} -> {tar_path}")
-        return image_tag
+        return str(tar_path)
    def _export_hint(self, slug: str, image_ref: str) -> None:
-        info(f"to export for migration:      docker image save {image_ref} "
+        info(f"to export for migration:      cp {image_ref} {slug}.tar")
             f"-o {slug}.tar")
 def _guest_ip_from_config(config_path: Path) -> str:
@@ -53,24 +55,36 @@ def _guest_ip_from_config(config_path: Path) -> str:
    return ""
-def _commit_via_ssh(private_key: Path, guest_ip: str, image_tag: str) -> None:
+def _commit_rootfs_via_ssh(private_key: Path, guest_ip: str, tar_path: Path) -> None:
-    with tempfile.TemporaryDirectory(prefix="bot-bottle-fc-commit.") as tmp:
+    """Stream the guest rootfs out over SSH into `tar_path`. Excludes the
-        rootfs_tar = os.path.join(tmp, "rootfs.tar")
+    virtual/live mounts (proc/sys/dev/run) — resume recreates those empty
-        ssh = util.ssh_base_argv(private_key, guest_ip)
+    mount points. Written to a `.partial` sibling and renamed on success so
-        with open(rootfs_tar, "wb") as tar_out:
+    a failed freeze never leaves a truncated artifact in its place."""
-            result = subprocess.run(
+    tar_path.parent.mkdir(parents=True, exist_ok=True)
-                [*ssh, "--", "tar", "--create", "--one-file-system",
+    partial = tar_path.with_name(tar_path.name + ".partial")
-                 "--exclude=./proc", "--exclude=./sys", "--exclude=./dev",
+    ssh = util.ssh_base_argv(private_key, guest_ip)
-                 "--exclude=./run", "--file=-", "--directory=/", "."],
+    # The snapshot can contain the bottle's private workspace, so keep it
-                stdout=tar_out, stderr=subprocess.PIPE, check=False,
+    # owner-only (0600) for the whole stream. The `os.open` mode only applies
-            )
+    # on *creation*, so unlink any leftover partial (a prior interrupted run
-        if result.returncode != 0:
+    # could have left it world-readable, or something could swap in a symlink
-            die(f"ssh tar for {guest_ip} failed: "
+    # at this predictable name) and exclusively recreate it — O_EXCL|O_NOFOLLOW
-                f"{(result.stderr or b'').decode().strip() or '<no stderr>'}")
+    # — then fchmod immediately so umask can't loosen it. Re-assert after the
-        with open(os.path.join(tmp, "Dockerfile"), "w", encoding="utf-8") as f:
+    # rename too (os.replace carries the source mode, but be explicit).
-            f.write("FROM scratch\nADD rootfs.tar /\nUSER node\nWORKDIR /home/node\n")
+    partial.unlink(missing_ok=True)
-        build = subprocess.run(
+    fd = os.open(
-            ["docker", "build", "-t", image_tag, tmp], check=False,
+        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,
        )
-        if build.returncode != 0:
+    if result.returncode != 0:
-            die(f"docker build for {image_tag!r} failed")
+        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)
@@ -38,25 +38,39 @@ _BUILD_TIMEOUT_SECONDS = 900.0
 def _dockerfile_hash(dockerfile: Path) -> str:
-    """Cache key: the Dockerfile's content. The shipped agent Dockerfiles
+    """The Dockerfile's content hash. The shipped agent Dockerfiles COPY
-    COPY nothing from the build context (see .dockerignore), so their content
+    nothing from the build context (see .dockerignore), so their content fully
-    fully determines the image; a Dockerfile that adds COPY will want the
+    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 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,
+    same shape `util.build_rootfs_ext4` consumes. Cached by Dockerfile content
-    so a repeat launch skips the rebuild.
+    + 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 = _dockerfile_hash(dockerfile)
+    digest = _rootfs_digest(dockerfile)
    base = util.cache_dir() / "rootfs" / f"agent-{digest}"
    if (base / ".bb-ready").is_file():
        info(f"using cached agent rootfs {base.name}")
@@ -41,11 +41,11 @@ from . import util
 _ARTIFACT_FORMAT = "1"
 _REPO_ROOT = Path(__file__).resolve().parents[3]
-_DOCKERFILES = ("Dockerfile.orchestrator", "Dockerfile.gateway", "Dockerfile.infra")
+_DOCKERFILES = ("Dockerfile.orchestrator", "Dockerfile.gateway", "Dockerfile.infra", "Dockerfile.infra.fc")
 _DEFAULT_BASE = "https://gitea.dideric.is"
 _DEFAULT_OWNER = "didericis"
-_PACKAGE = "bot-bottle-infra"
+_PACKAGE = "bot-bottle-firecracker-infra"
 # Streaming copy chunk for the (hundreds-of-MB) download.
 _CHUNK = 1 << 20
@@ -57,24 +57,39 @@ def local_build_requested() -> bool:
    return os.environ.get("BOT_BOTTLE_INFRA_BUILD", "").strip().lower() == "local"
-def infra_artifact_version(init_script: str) -> str:
+def infra_artifact_version(init_script: str, *, repo_root: Path = _REPO_ROOT) -> str:
    """Content hash (16 hex) of everything baked into the infra rootfs: the
-    whole shipped `bot_bottle` package (the infra image `COPY`s it wholesale),
+    whole shipped `bot_bottle` package, the three fixed Dockerfiles, and the
-    the three fixed Dockerfiles, and the guest init. Deterministic across the
+    guest init. Deterministic across the publish host and the launch host when
-    publish host and the launch host when both run the same checkout, so the
+    both run the same checkout, so the tag the launch host pulls is exactly the
-    tag the launch host pulls is exactly the tag publish produced."""
+    tag publish produced.
    The package is `COPY bot_bottle /app/bot_bottle`'d wholesale into the image,
    so hash *every* regular file under it — not just `*.py`. Non-Python inputs
    (e.g. `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."""
    h = hashlib.sha256()
    h.update(f"format={_ARTIFACT_FORMAT}\n".encode())
-    pkg = _REPO_ROOT / "bot_bottle"
+    pkg = repo_root / "bot_bottle"
-    for path in sorted(pkg.rglob("*.py")):
+    for path in sorted(pkg.rglob("*")):
-        if "__pycache__" in path.parts:
+        if not path.is_file():
            continue
-        h.update(str(path.relative_to(_REPO_ROOT)).encode())
+        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:
        p = _REPO_ROOT / name
        h.update(name.encode())
-        h.update(p.read_bytes())
+        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]
@@ -101,6 +116,7 @@ def artifact_url(version: str, filename: str) -> str:
 _GZ_NAME = "rootfs.ext4.gz"
 _SHA_NAME = "rootfs.ext4.gz.sha256"
 _CANDIDATE_DIR_ENV = "BOT_BOTTLE_INFRA_ARTIFACT_DIR"
 def _cache_root(version: str) -> Path:
@@ -150,6 +166,33 @@ def ensure_artifact_gz(version: str) -> Path:
    """The verified, cached `rootfs.ext4.gz` for `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."""
    candidate_dir = os.environ.get(_CANDIDATE_DIR_ENV, "").strip()
    if candidate_dir:
        root = Path(candidate_dir)
        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: 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 for {version}:\n"
                f"    expected {expected}\n    actual   {actual}"
            )
        return gz
    root = _cache_root(version)
    root.mkdir(parents=True, exist_ok=True)
    gz = root / _GZ_NAME
@@ -33,6 +33,7 @@ from pathlib import Path
 from typing import Generator
 from ...log import die, info
 from .. import util as backend_util
 from ..docker import util as docker_mod
 from ..docker.gateway_provision import GatewayProvisionError
 from . import firecracker_vm, infra_artifact, netpool, util
@@ -93,19 +94,18 @@ class InfraVm:
        """The gateway's mitmproxy CA (PEM) that agents install to trust its
        TLS interception. Generated a moment after boot, so this polls over
        SSH until it appears (mirrors DockerGateway.ca_cert_pem)."""
-        deadline = time.monotonic() + timeout
+        def _fetch() -> str | None:
        while True:
            proc = subprocess.run(
                util.ssh_base_argv(self.private_key, self.guest_ip)
                + [f"cat {_GATEWAY_CA_PATH}"],
                capture_output=True, text=True, timeout=15, check=False,
            )
-            if proc.returncode == 0 and "BEGIN CERTIFICATE" in proc.stdout:
+            ok = proc.returncode == 0 and "BEGIN CERTIFICATE" in proc.stdout
-                return proc.stdout
+            return proc.stdout if ok else None
-            if time.monotonic() >= deadline:
+        try:
-                die(f"gateway CA not available after {timeout:g}s: "
+            return backend_util.poll_ca_cert(_fetch, timeout=timeout)
-                    f"{proc.stderr.strip() or 'empty'}")
+        except TimeoutError as exc:
-            time.sleep(_HEALTH_POLL_SECONDS)
+            die(str(exc))
 def ensure_built() -> None:
@@ -125,16 +125,19 @@ def ensure_built() -> None:
 def build_infra_images_with_docker() -> None:
-    """Build the three fixed images from source with host Docker: orchestrator,
+    """Build the four fixed images from source with host Docker: orchestrator,
-    gateway, then the combined infra image (`COPY --from` orchestrator, `FROM`
+    gateway, the shared infra base (Dockerfile.infra), then the Firecracker
-    gateway). The launch host uses this only in `BOT_BOTTLE_INFRA_BUILD=local`
+    infra image (Dockerfile.infra.fc: FROM infra + buildah). The launch host
-    mode; `publish_infra` uses it off-host to produce the published artifact."""
+    uses this only in `BOT_BOTTLE_INFRA_BUILD=local` mode; `publish_infra`
    uses it off-host to produce the published artifact."""
    docker_mod.build_image(
        _ORCHESTRATOR_IMAGE, str(_REPO_ROOT), dockerfile="Dockerfile.orchestrator")
    docker_mod.build_image(
        _GATEWAY_IMAGE, str(_REPO_ROOT), dockerfile="Dockerfile.gateway")
    docker_mod.build_image(
-        _INFRA_IMAGE, str(_REPO_ROOT), dockerfile="Dockerfile.infra")
+        "bot-bottle-infra:latest", str(_REPO_ROOT), dockerfile="Dockerfile.infra")
    docker_mod.build_image(
        _INFRA_IMAGE, str(_REPO_ROOT), dockerfile="Dockerfile.infra.fc")
 def build_infra_rootfs_dir() -> Path:
@@ -161,20 +164,23 @@ def ensure_running() -> InfraVm:
    slot = netpool.orch_slot()
    url = f"http://{slot.guest_ip}:{CONTROL_PLANE_PORT}"
    key = _infra_dir() / "id_ed25519"
-    if key.exists() and _health_ok(url):
+    want = _expected_version()
    if _adoptable(key, url, want):
        info(f"adopting running infra VM at {url}")
        return InfraVm(guest_ip=slot.guest_ip, private_key=key)
    with _singleton_lock():
        # Re-check under the lock: another launcher may have booted it while
        # we waited for the lock (double-checked, so we adopt not re-boot).
-        if key.exists() and _health_ok(url):
+        if _adoptable(key, url, want):
            info(f"adopting running infra VM at {url}")
            return InfraVm(guest_ip=slot.guest_ip, private_key=key)
-        stop()  # clear a stale/hung VM holding the link before booting fresh
+        # Clear a stale/hung/OUTDATED VM holding the link before booting fresh.
        stop()
        ensure_built()
        infra = boot()
        wait_for_health(infra)
        _record_booted_version(want)
        return infra
@@ -193,9 +199,15 @@ def _singleton_lock() -> Generator[None, None, None]:
 def stop() -> None:
-    """Stop the infra VM singleton (idempotent — absent is success)."""
+    """Stop the infra VM singleton (idempotent — absent is success). Reaps the
    recorded VMM AND any orphaned firecracker still bound to the infra config —
    the PID file drifts after crashes / out-of-band kills, and a survivor would
    hold the orchestrator TAP so the next boot dies with "tap … Resource busy".
    Drops the version marker so a stopped VM is never treated as adoptable."""
    _kill_pidfile()
    _kill_infra_firecrackers()
    _pid_file().unlink(missing_ok=True)
    _version_file().unlink(missing_ok=True)
 def boot() -> InfraVm:
@@ -238,6 +250,36 @@ def _pid_file() -> Path:
    return _infra_dir() / "vm.pid"
 def _version_file() -> Path:
    """Records the infra-artifact version the *running* VM booted from, so a
    later launcher can tell whether the singleton it found is the current code.
    Without it, a healthy VM 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 VM (and races whatever launched next)."""
    return _infra_dir() / "booted-version"
 def _expected_version() -> str:
    return infra_artifact.infra_artifact_version(_infra_init())
 def _adoptable(key: Path, url: str, want: str) -> bool:
    """Adopt a running infra VM only if it booted from the CURRENT version and
    its control plane is healthy. A missing/mismatched marker means a prior
    launcher booted an older infra image — reboot rather than reuse stale code."""
    if not key.exists():
        return False
    try:
        booted = _version_file().read_text(encoding="utf-8").strip()
    except OSError:
        return False
    return booted == want and _health_ok(url)
 def _record_booted_version(version: str) -> None:
    _version_file().write_text(version + "\n", encoding="utf-8")
 # The registry "volume": a host-side ext4 file attached to the infra 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
@@ -309,6 +351,28 @@ def _kill_pidfile() -> None:
        pass
 def _kill_infra_firecrackers(proc_root: Path = Path("/proc")) -> None:
    """SIGKILL any firecracker VMM whose `--config-file` is this host's infra
    config, independent of the PID file — reaps orphans it lost track of so the
    orchestrator TAP is free to rebind. Scoped to the infra config path, so the
    interactive pool's agent/infra VMs (other config paths) are untouched."""
    cfg = str(_infra_dir() / "config.json")
    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") == cfg 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:
@@ -433,7 +497,7 @@ BOT_BOTTLE_ROOT=/var/lib/bot-bottle python3 -m bot_bottle.orchestrator \\
 BOT_BOTTLE_GATEWAY_DAEMONS=egress,git-http,supervise \\
 BOT_BOTTLE_ORCHESTRATOR_URL=http://127.0.0.1:{CONTROL_PLANE_PORT} \\
 SUPERVISE_DB_PATH=/var/lib/bot-bottle/db/bot-bottle.db \\
-    python3 /app/gateway_init.py &
+    python3 -m bot_bottle.gateway_init &
 # Reap as PID 1; children are backgrounded, so `wait` blocks.
 while : ; do wait ; done
@@ -1,7 +1,8 @@
 """Launch flow for the Firecracker backend (PRD 0070, consolidated).
 Per bottle:
-  1. build the agent image (docker), export it to a cached ext4 rootfs;
+  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
@@ -31,6 +32,7 @@ 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,
@@ -45,12 +47,12 @@ from ...git_gate import (
 )
 from ...log import info, warn
 from ...supervise import SUPERVISE_PORT
 from ..docker import util as docker_mod
 from ..docker.egress import EGRESS_PORT
 from ..util import AGENT_CA_BUNDLE, AGENT_CA_PATH
 from . import firecracker_vm, image_builder, isolation_probe, netpool, util
 from .bottle import FirecrackerBottle
 from .bottle_plan import FirecrackerBottlePlan
 from ...orchestrator.config_store import resolve_teardown_timeout
 from .consolidated_launch import (
    launch_consolidated,
    teardown_consolidated,
@@ -111,6 +113,7 @@ def launch(
        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,
@@ -120,6 +123,7 @@ def launch(
        stack.callback(
            teardown_consolidated, ctx.bottle_id,
            orchestrator_url=ctx.orchestrator_url,
            timeout=teardown_timeout,
        )
        # Step 5: install the SHARED gateway CA (replaces the per-bottle CA).
@@ -210,16 +214,13 @@ def _build_agent_base(
 ) -> tuple[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 still
+    the image before export. A committed snapshot (freeze/migrate) is resumed
-    exported via the host docker path until that is ported too."""
+    directly from the rootfs tar the freezer wrote — no host docker either."""
    committed = read_committed_image(plan.slug)
-    if committed and docker_mod.image_exists(committed):
+    committed_tar = committed_rootfs_path(plan.slug)
-        info(f"using committed image {committed!r}")
+    if committed and committed_tar.is_file():
-        plan = dataclasses.replace(
+        info(f"resuming from committed rootfs {committed_tar}")
-            plan,
+        return plan, util.build_committed_rootfs_dir(committed_tar)
            agent_provision=dataclasses.replace(plan.agent_provision, image=committed),
        )
        return plan, util.build_base_rootfs_dir(committed)
    base = image_builder.build_agent_rootfs_dir(
        Path(plan.dockerfile_path),
        image_tag=plan.image,
@@ -5,13 +5,14 @@ never on the launch host. It runs the same pipeline the launch host used to run
 locally — `docker build` the three fixed images, export to a rootfs dir, inject
 the guest boot, `mke2fs` to an ext4 with the buildah build slack — then gzips
 the ext4 and PUTs it (plus a `.sha256`) to
-`…/api/packages/<owner>/generic/bot-bottle-infra/<version>/`.
+`…/api/packages/<owner>/generic/bot-bottle-firecracker-infra/<version>/`.
 The `<version>` is `infra_artifact.infra_artifact_version(...)`, the content
 hash of the rootfs inputs, so a launch host at the same code checkout resolves
 the exact artifact this produced.
-  python3 -m bot_bottle.backend.firecracker.publish_infra [--dry-run] [--force]
+  python3 -m bot_bottle.backend.firecracker.publish_infra --output DIR
  python3 -m bot_bottle.backend.firecracker.publish_infra --publish-dir DIR
 Auth: a token with `write:package` on the target owner, from
 `BOT_BOTTLE_INFRA_ARTIFACT_TOKEN`.
@@ -24,7 +25,6 @@ import gzip
 import hashlib
 import shutil
 import sys
 import tempfile
 import urllib.error
 import urllib.request
 from pathlib import Path
@@ -33,6 +33,18 @@ from . import infra_artifact, infra_vm, util
 _CHUNK = 1 << 20
 # A human-readable description shipped alongside the 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"
 _ABOUT_TEXT = (
    "bot-bottle infra rootfs for the Firecracker backend (PRD 0069 Stage 2, "
    "#348): the per-host infra VM (orchestrator control plane + gateway + "
    "buildah). Prebuilt off-host, gzip ext4; the launch host downloads + "
    "sha256-verifies + boots it, no host Docker. The version tag is a content "
    "hash of the rootfs inputs. Files: rootfs.ext4.gz + rootfs.ext4.gz.sha256.\n"
 )
 def _gzip(src: Path, dest: Path) -> None:
    with open(src, "rb") as fh, gzip.open(dest, "wb") as out:
@@ -47,8 +59,22 @@ def _sha256(path: Path) -> str:
    return h.hexdigest()
-def _put(url: str, body: bytes, token: str) -> None:
+def _put(url: str, body: "bytes | Path", token: str) -> None:
-    req = urllib.request.Request(url, data=body, method="PUT")
+    """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")
@@ -64,6 +90,9 @@ def _put(url: str, body: bytes, token: str) -> None:
        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:
@@ -102,33 +131,79 @@ def build_artifact(out_dir: Path) -> tuple[str, Path, Path]:
    return version, gz, sha
 def _publish_bundle(root: Path, token: str) -> str:
    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():
        raise SystemExit(f"incomplete artifact bundle: {root}")
    version = version_file.read_text(encoding="utf-8").strip()
    expected = infra_artifact.infra_artifact_version(infra_vm._infra_init())
    if version != expected:
        raise SystemExit(
            f"artifact bundle version {version!r} does not match checkout {expected!r}"
        )
    gz = root / "rootfs.ext4.gz"
    sha = root / "rootfs.ext4.gz.sha256"
    if not gz.is_file() or not sha.is_file():
        raise SystemExit(f"incomplete artifact bundle: {root}")
    expected_sha = sha.read_text().split()[0].strip().lower()
    if _sha256(gz) != expected_sha:
        raise SystemExit("artifact bundle checksum mismatch")
    gz_url = infra_artifact.artifact_url(version, gz.name)
    sha_url = infra_artifact.artifact_url(version, sha.name)
    about_url = infra_artifact.artifact_url(version, _ABOUT_NAME)
    # Publishing is idempotent. If this exact complete artifact is already
    # present, a test-only main commit 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 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"infra 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.encode(), token)
    return version
 def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        prog="publish_infra", description="Build + publish the infra rootfs artifact.")
-    parser.add_argument("--dry-run", action="store_true",
+    mode = parser.add_mutually_exclusive_group(required=True)
-                        help="build the artifact but do not upload")
+    mode.add_argument("--output", type=Path,
-    parser.add_argument("--force", action="store_true",
+                      help="build a candidate bundle in DIR without publishing")
-                        help="overwrite an already-published artifact of this version")
+    mode.add_argument("--publish-dir", type=Path,
                      help="publish an already-built and tested candidate bundle")
    args = parser.parse_args(argv)
    _, _, token = infra_artifact._config()
-    if not args.dry_run and not token:
+    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")
-    with tempfile.TemporaryDirectory(prefix="bb-publish-infra.") as tmp:
+    if args.output is not None:
-        version, gz, sha = build_artifact(Path(tmp))
+        args.output.mkdir(parents=True, exist_ok=True)
-        gz_url = infra_artifact.artifact_url(version, gz.name)
+        version, _gz, _sha = build_artifact(args.output)
-        sha_url = infra_artifact.artifact_url(version, sha.name)
+        (args.output / "version.txt").write_text(version + "\n", encoding="utf-8")
-        if args.dry_run:
+        print(f"built infra rootfs candidate {version}")
-            print(f"dry-run: would upload -> {gz_url}")
+        return 0
-            return 0
+
-        if args.force:
+    assert args.publish_dir is not None
-            _delete(gz_url, token)
+    version = _publish_bundle(args.publish_dir, token)
            _delete(sha_url, token)
        _put(gz_url, gz.read_bytes(), token)
        _put(sha_url, sha.read_bytes(), token)
    print(f"published infra rootfs {version}")
    return 0
@@ -14,6 +14,7 @@ and `./cli.py backend setup --backend=firecracker`.
 from __future__ import annotations
 import hashlib
 import os
 import platform
 import shutil
@@ -87,7 +88,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 --backend=macos-container.")
+            "On macOS use the macos-container backend.")
    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")
@@ -212,15 +213,80 @@ def build_base_rootfs_dir(
    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; the infra VM
-    passes its own (control plane + gateway) init."""
+    passes its own (control plane + gateway) init.
-    shutil.copy2(dropbear_path(), rootfs / "bb-dropbear")
+
-    os.chmod(rootfs / "bb-dropbear", 0o755)
+    A committed snapshot is guest-controlled, so `bb-dropbear`/`bb-init`
-    init = rootfs / "bb-init"
+    may already exist as symlinks aimed at a host file (e.g. bb-init ->
-    init.write_text(init_script or _GUEST_INIT)
+    ~/.bashrc). Replace whatever is there and create the files with
-    os.chmod(init, 0o755)
+    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 build_rootfs_ext4(base_dir: Path, out_path: Path, *, slack_mib: int = 1024) -> None:
@@ -302,6 +368,11 @@ 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
 # 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
@@ -89,6 +89,14 @@ class MacosContainerBottleBackend(
        with _launch.launch(plan, provision=self.provision) as bottle:
            yield bottle
    def ensure_orchestrator(self) -> str:
        """Bring up the per-host infra container (control plane + gateway) 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-VM bring-up."""
        from .infra import MacosInfraService
        return MacosInfraService().ensure_running().control_plane_url
    def prepare_cleanup(self) -> MacosContainerBottleCleanupPlan:
        return _cleanup.prepare_cleanup()
@@ -52,6 +52,7 @@ 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
@@ -62,6 +63,20 @@ 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]:
@@ -74,6 +89,12 @@ 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
@@ -94,21 +115,33 @@ 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, check=False).returncode
+            return subprocess.run(agent_argv, env=env, check=False).returncode
-        return subprocess.run(["sh", "-lc", script], check=False).returncode
+        return subprocess.run(["sh", "-lc", script], env=env, 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(
-            ["container", "exec", "--user", user, "--interactive",
+            argv,
             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(
@@ -13,9 +13,13 @@ 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 = ""
    @property
    def container_name(self) -> str:
@@ -0,0 +1,178 @@
 """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 one **infra container** here (see
 `infra`), so `gateway_ip` and the control-plane host are the same address.
 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 ..consolidated_util import provision_bottle, teardown_consolidated as _teardown_util
 from . import util as container_mod
 from .enumerate import CONTAINER_NAME_PREFIX, EnumerationError, enumerate_active
 from .gateway import GATEWAY_NETWORK
 from .gateway_provision import AppleGatewayTransport
 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 (the
    infra container). `gateway_ip` is that container's host-only address, the
    same host the control-plane URL points at."""
    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
 def ensure_gateway(
    *, service: MacosInfraService | None = None,
 ) -> GatewayEndpoint:
    """Ensure the per-host infra container (control plane + gateway) is up and
    report how to reach it. Idempotent — one singleton, 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()
    infra = service.ensure_running()
    return GatewayEndpoint(
        orchestrator_url=infra.control_plane_url,
        gateway_ip=infra.gateway_ip,
        gateway_ca_pem=service.ca_cert_pem(),
        network=service.network,
    )
 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,
 ) -> 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, AppleGatewayTransport(),
        image_ref=image_ref, tokens=tokens,
    )
    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,
    )
 def teardown_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."""
    _teardown_util(bottle_id, AppleGatewayTransport(),
                   orchestrator_url=orchestrator_url, timeout=timeout)
 __all__ = [
    "GatewayEndpoint",
    "LaunchContext",
    "ensure_gateway",
    "live_source_ips",
    "register_agent",
    "teardown_consolidated",
    "ConsolidatedLaunchError",
    "OrchestratorStartError",
    "GATEWAY_NETWORK",
 ]
@@ -1,9 +1,11 @@
 """Host-side egress route-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),
+--signal HUP <container>`) was removed in the companion-container removal
-along with the disabled macOS launch path. Fails closed until the macOS
+(#385). In the consolidated model the shared gateway resolves egress policy
-backend grows the consolidated gateway.
+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.
 """
 from __future__ import annotations
@@ -16,8 +18,8 @@ class MacOSContainerEgressApplicator(EgressApplicator):
        del slug
        raise EgressApplyError(
            "live egress route-apply was removed with the per-bottle "
-            "companion container (#385); the macos-container backend is "
+            "companion container (#385); route changes will flow through "
-            "disabled until it uses the consolidated gateway."
+            "the consolidated gateway in a follow-up."
        )
@@ -1,14 +1,53 @@
-"""Active-agent enumeration for the macOS Apple Container backend.
+"""Active-agent enumeration for the macOS Apple Container backend."""
 The backend is disabled during the companion-container removal (#385) — it can't
 launch bottles, so there are none to enumerate. Enumeration returns when
 the backend grows the consolidated gateway.
 """
 from __future__ import annotations
 import subprocess
 from ...bottle_state import read_metadata
 from .. import ActiveAgent
 from .infra import INFRA_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 shared per-host infra container carries the same prefix as agent
 # containers but is infrastructure, not a bottle — one control plane + gateway
 # serves every agent, so listing it as an agent would invent one per host.
 _INFRA_NAMES = frozenset({INFRA_NAME})
 class EnumerationError(RuntimeError):
    """container list failed; the resulting live set is not authoritative."""
 def enumerate_active() -> list[ActiveAgent]:
-    return []
+    result = subprocess.run(
        ["container", "list", "--quiet"],
        capture_output=True,
        text=True,
        check=False,
    )
    if result.returncode != 0:
        raise EnumerationError(
            f"container list failed: "
            f"{(result.stderr or '').strip() or '<no stderr>'}"
        )
    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:
            continue
        slug = name[len(CONTAINER_NAME_PREFIX):]
        metadata = read_metadata(slug)
        out.append(ActiveAgent(
            backend_name="macos-container",
            slug=slug,
            agent_name=metadata.agent_name if metadata else "?",
            started_at=metadata.started_at if metadata else "",
            services=(),
            label=metadata.label if metadata else "",
            color=metadata.color if metadata else "",
        ))
    return out
@@ -0,0 +1,46 @@
 """Shared network/image constants for the macOS consolidated infra container.
 The gateway data plane no longer runs as its own Apple container — it shares a
 single per-host **infra container** with the control plane (see `infra`),
 because two Apple-Container guests writing one `bot-bottle.db` over virtiofs
 would race incoherent `fcntl` locks. This module holds the pieces both the
 infra service and the launch/provision glue need: the network names, the
 gateway image, and the network-creation helper.
 """
 from __future__ import annotations
 import os
 from ...orchestrator.gateway import GatewayError
 from . import util as container_mod
 # The shared host-only network the infra 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 infra container (and only it) a route out.
 GATEWAY_EGRESS_NETWORK = "bot-bottle-mac-egress"
 GATEWAY_IMAGE = os.environ.get("BOT_BOTTLE_GATEWAY_IMAGE", "bot-bottle-gateway:latest")
 DEFAULT_CA_TIMEOUT_SECONDS = 30.0
 def ensure_networks(
    network: str = GATEWAY_NETWORK, egress_network: str = GATEWAY_EGRESS_NETWORK,
 ) -> None:
    """Create the shared host-only network + the NAT egress network. Idempotent
    — `create_network` tolerates 'already exists'."""
    container_mod.create_network(egress_network)
    container_mod.create_network(network, internal=True)
 __all__ = [
    "GATEWAY_NETWORK",
    "GATEWAY_EGRESS_NETWORK",
    "GATEWAY_IMAGE",
    "GatewayError",
    "DEFAULT_CA_TIMEOUT_SECONDS",
    "ensure_networks",
 ]
@@ -0,0 +1,96 @@
 """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 infra 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"]
@@ -0,0 +1,44 @@
 """`GatewayTransport` for the Apple infra container (PRD 0070).
 The provisioning *logic* (per-bottle creds dirs, namespaced repo init) is
 backend-neutral and lives in `backend.docker.gateway_provision`; this is only
 the transport — how files and commands reach the running gateway. Docker uses
 `docker exec`/`docker cp` and Firecracker uses SSH; Apple uses the `container`
 CLI's equivalents against the infra container that hosts the gateway daemons.
 """
 from __future__ import annotations
 from ..docker.gateway_provision import GatewayProvisionError
 from . import util as container_mod
 from .infra import INFRA_NAME
 class AppleGatewayTransport:
    """`GatewayTransport` for the gateway daemons in the Apple infra container."""
    def __init__(self, gateway: str = INFRA_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__ = ["AppleGatewayTransport", "GatewayProvisionError"]
@@ -0,0 +1,304 @@
 """The per-host infra container for the macOS backend (PRD 0070).
 A single persistent Apple container that runs BOTH the orchestrator control
 plane and the gateway data plane — the macOS analogue of the Firecracker infra
 VM (`backend/firecracker/infra_vm.py`), not the docker backend's two separate
 containers.
 Why one container, not two: Apple Containers are lightweight VMs, each with its
 own kernel. The docker backend runs the orchestrator and gateway as two
 containers safely because they share the host kernel, so their concurrent
 writes to the one `bot-bottle.db` (the orchestrator's registry + the gateway
 supervise daemon's queue) are serialized by coherent `fcntl` locks. Across two
 *guest* kernels sharing a virtiofs-mounted DB those locks are not coherent, and
 concurrent writers can corrupt the file. Firecracker solved this by putting
 both services in one guest with the DB on a device only that guest mounts; this
 does the same with Apple primitives.
 Two consequences fall out of the single container, both simplifications:
 - **No DNS dance.** The control plane and the gateway daemons reach each other
  over `127.0.0.1`, so nothing depends on Apple's (absent) container DNS and
  there is no orchestrator-before-gateway ordering to get right.
 - **The DB is never host-shared.** It lives on a container-only volume, so no
  host process opens the live file. The host CLI reaches registry + supervise
  state through the control-plane HTTP surface (`cli/supervise.py` already uses
  `OrchestratorClient`), exactly as it does for firecracker.
 The control-plane source is bind-mounted (like the docker orchestrator), so a
 code change takes effect on the next launch without an image rebuild; the
 gateway daemons are baked in the gateway image and rebuild through its own
 digest check.
 """
 from __future__ import annotations
 import os
 import time
 import urllib.error
 import urllib.request
 from dataclasses import dataclass
 from pathlib import Path
 from ... import log
 from ...orchestrator.gateway import GATEWAY_CA_CERT
 from ...orchestrator.lifecycle import (
    DEFAULT_PORT,
    DEFAULT_STARTUP_TIMEOUT_SECONDS,
    OrchestratorStartError,
    source_hash,
 )
 from ...paths import (
    CONTROL_PLANE_TOKEN_ENV,
    HOST_DB_FILENAME,
    host_control_plane_token,
 )
 from .. import util as backend_util
 from . import util as container_mod
 from .gateway import (
    DEFAULT_CA_TIMEOUT_SECONDS,
    GATEWAY_EGRESS_NETWORK,
    GATEWAY_IMAGE,
    GATEWAY_NETWORK,
    GatewayError,
    ensure_networks,
 )
 # The one per-host infra container: control plane + gateway data plane.
 INFRA_NAME = "bot-bottle-mac-infra"
 INFRA_LABEL = "bot-bottle-mac-infra=1"
 # Container-only volume holding bot-bottle.db. No host bind-mount, so the DB is
 # written by exactly one kernel (this container's). Survives recreation.
 INFRA_DB_VOLUME = "bot-bottle-mac-db"
 # BOT_BOTTLE_ROOT inside the container; host_db_path() resolves the DB to
 # <root>/db/<filename> and the supervise daemon writes the same file.
 _DB_ROOT_IN_CONTAINER = "/var/lib/bot-bottle"
 _DB_PATH_IN_CONTAINER = f"{_DB_ROOT_IN_CONTAINER}/db/{HOST_DB_FILENAME}"
 _SRC_IN_CONTAINER = "/bot-bottle-src"
 _REPO_ROOT = Path(__file__).resolve().parents[3]
 _HEALTH_POLL_SECONDS = 0.25
 _HEALTH_REQUEST_TIMEOUT_SECONDS = 1.0
 _CA_POLL_SECONDS = 0.5
 # The gateway subset the consolidated model runs (no per-bottle git:// daemon).
 _GATEWAY_DAEMONS = "egress,git-http,supervise"
 def _init_script(port: int) -> str:
    """PID-1 init: start the control plane and the gateway daemons, both in
    this container, reaching each other over loopback. Backgrounded so `wait`
    reaps as PID 1. No `set -e` — a transient daemon failure must not kill the
    whole container (gateway_init applies the same 'stay up' policy)."""
    return (
        "export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\n"
        f"mkdir -p $(dirname {_DB_PATH_IN_CONTAINER})\n"
        # Control plane, from the bind-mounted source (stdlib-only package).
        f"( cd {_SRC_IN_CONTAINER} && BOT_BOTTLE_ROOT={_DB_ROOT_IN_CONTAINER} "
        f"python3 -m bot_bottle.orchestrator --host 0.0.0.0 --port {port} "
        "--broker stub ) &\n"
        # Gateway data plane, multi-tenant against the local control plane.
        f"( cd /app && BOT_BOTTLE_GATEWAY_DAEMONS={_GATEWAY_DAEMONS} "
        f"BOT_BOTTLE_ORCHESTRATOR_URL=http://127.0.0.1:{port} "
        f"SUPERVISE_DB_PATH={_DB_PATH_IN_CONTAINER} python3 -m bot_bottle.gateway_init ) &\n"
        "while : ; do wait ; done\n"
    )
@dataclass(frozen=True)
 class InfraEndpoint:
    """How to reach the running infra container. The control plane and the
    gateway are the same container, so one address serves both."""
    control_plane_url: str   # http://<infra ip>:8099 — host CLI + registration
    gateway_ip: str          # same container; agents' proxy / git-http / MCP target
 class MacosInfraService:
    """Manages the single per-host infra container. Callers use
    `ensure_running()` (returns the endpoint) and `ca_cert_pem()`."""
    def __init__(
        self,
        *,
        port: int = DEFAULT_PORT,
        network: str = GATEWAY_NETWORK,
        egress_network: str = GATEWAY_EGRESS_NETWORK,
        image: str = GATEWAY_IMAGE,
        repo_root: Path = _REPO_ROOT,
        name: str = INFRA_NAME,
        db_volume: str = INFRA_DB_VOLUME,
    ) -> None:
        self.port = port
        self.network = network
        self.egress_network = egress_network
        self.image = image
        self._repo_root = repo_root
        self._name = name
        self._db_volume = db_volume
    def _resolve_url(self) -> str:
        """The control-plane URL, or "" while the container has no address."""
        ip = container_mod.try_container_ipv4_on_network(self._name, self.network)
        return f"http://{ip}:{self.port}" if ip else ""
    def is_healthy(
        self, url: str, *, timeout: float = _HEALTH_REQUEST_TIMEOUT_SECONDS,
    ) -> bool:
        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 _source_current(self, current_hash: str) -> bool:
        """True iff the running infra container was created from the current
        bind-mounted control-plane source. The control-plane process loads that
        code at startup and won't reload it, so a stale container keeps serving
        OLD code."""
        if not container_mod.container_is_running(self._name):
            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 _running_healthy_endpoint(self, current_hash: str) -> InfraEndpoint | None:
        """The endpoint if the running container is BOTH source-current and
        answering /health, else None (→ recreate). Health, not just the source
        label, is what lets a wedged-but-current container self-heal instead of
        being polled to death forever."""
        if not self._source_current(current_hash):
            return None
        url = self._resolve_url()
        if url and self.is_healthy(url):
            return InfraEndpoint(control_plane_url=url, gateway_ip=_ip_of(url))
        return None
    def ensure_built(self) -> None:
        """Ensure the gateway data-plane image exists. The control-plane source
        is bind-mounted, not baked, so only the gateway image needs building."""
        container_mod.build_image(
            self.image, str(self._repo_root), dockerfile="Dockerfile.gateway",
        )
    def ensure_running(
        self, *, startup_timeout: float = DEFAULT_STARTUP_TIMEOUT_SECONDS,
    ) -> InfraEndpoint:
        """Ensure the single infra container is up; return how to reach it.
        Idempotent per-host singleton — a healthy container on current source
        is left untouched, so N launches share the one control plane + gateway.
        Raises `OrchestratorStartError` on startup timeout."""
        current_hash = source_hash(self._repo_root)
        endpoint = self._running_healthy_endpoint(current_hash)
        if endpoint is not None:
            return endpoint
        self.ensure_built()
        log.info("starting infra container", context={"name": self._name})
        self._run_container(current_hash)
        return self._wait_healthy(startup_timeout)
    def _run_container(self, current_hash: str) -> None:
        ensure_networks(self.network, self.egress_network)
        container_mod.force_remove_container(self._name)
        argv = [
            "container", "run", "--detach",
            "--name", self._name,
            "--label", "bot-bottle.backend=macos-container",
            "--label", INFRA_LABEL,
            # NAT network FIRST so the gateway's egress has a default route;
            # the host-only network is where agents (and the host CLI) reach it.
            "--network", self.egress_network,
            "--network", self.network,
            "--dns", container_mod.dns_server(),
            # Container-only DB volume: one kernel writes bot-bottle.db, never
            # shared with the host or another guest.
            "--volume", f"{self._db_volume}:{_DB_ROOT_IN_CONTAINER}",
            # Bind-mount the control-plane source (read-only); a code change
            # takes effect on relaunch with no image rebuild.
            "--mount",
            container_mod.bind_mount_spec(
                str(self._repo_root), _SRC_IN_CONTAINER, readonly=True),
            # Baked onto the container so `_source_current` can detect a real
            # control-plane code change and recreate.
            "--env", f"BOT_BOTTLE_SOURCE_HASH={current_hash}",
            # The control-plane secret, for BOTH the control plane (to require
            # it) and the gateway's PolicyResolver (to present it) — they share
            # this one container. Bare `--env NAME` inherits the value from the
            # run process below, so the secret never lands on argv or in
            # `container inspect`'s command line. The agent runs in a SEPARATE
            # container that is never given this var, which is the whole point.
            "--env", CONTROL_PLANE_TOKEN_ENV,
            "--entrypoint", "sh",
            self.image,
            "-c", _init_script(self.port),
        ]
        run_env = {**os.environ, CONTROL_PLANE_TOKEN_ENV: host_control_plane_token()}
        result = container_mod.run_container_argv(argv, env=run_env)
        if result.returncode != 0:
            raise OrchestratorStartError(
                f"infra container failed to start: "
                f"{(result.stderr or '').strip() or '<no stderr>'}"
            )
    def _wait_healthy(self, startup_timeout: float) -> InfraEndpoint:
        deadline = time.monotonic() + startup_timeout
        while True:
            url = self._resolve_url()
            if url and self.is_healthy(url):
                log.info("infra container healthy", context={"url": url})
                return InfraEndpoint(control_plane_url=url, gateway_ip=_ip_of(url))
            if time.monotonic() >= deadline:
                raise OrchestratorStartError(
                    f"infra container did not become healthy within "
                    f"{startup_timeout:g}s"
                )
            time.sleep(_HEALTH_POLL_SECONDS)
    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 out of the container (the CA lives on a
        container-internal path, not a host mount); 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 stop(self) -> None:
        """Remove the infra container (idempotent). The DB volume persists."""
        container_mod.force_remove_container(self._name)
 def _ip_of(url: str) -> str:
    """The host from an http://host:port URL."""
    return url.split("://", 1)[-1].rsplit(":", 1)[0]
 def probe_control_plane_url(port: int = DEFAULT_PORT) -> str:
    """The running infra container's control-plane URL, or "" if it isn't up.
    Used by host-side control-plane discovery (`discover_orchestrator_url`);
    safe to call on any host — returns "" when the container or the `container`
    CLI isn't present."""
    ip = container_mod.try_container_ipv4_on_network(INFRA_NAME, GATEWAY_NETWORK)
    return f"http://{ip}:{port}" if ip else ""
 __all__ = [
    "MacosInfraService",
    "InfraEndpoint",
    "OrchestratorStartError",
    "GatewayError",
    "INFRA_NAME",
    "INFRA_DB_VOLUME",
 ]
@@ -1,24 +1,80 @@
-"""Launch flow for the macOS Apple Container backend — disabled (#385).
+"""Launch flow for the macOS Apple Container backend (PRD 0070).
-This backend launched a per-bottle companion container (the egress /
+The agent container attaches to the **shared host-only gateway network** and
-git-gate / supervise data plane) alongside the agent container, with the
+proxies egress through the one per-host gateway, replacing the per-bottle
-agent's proxy env pointed at the companion's host-only IP. That
+companion container removed in #385.
 per-bottle-companion architecture was removed in the companion-container removal;
 the macOS backend will be re-enabled once it grows the consolidated
 per-host gateway the docker backend already uses.
-Until then, launching a macOS bottle fails closed. `prepare` / `status`
+The order differs from docker's, forced by Apple Container 1.0.0 having no
-/ cleanup still work.
+`--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.
 """
 from __future__ import annotations
-from contextlib import contextmanager
+import dataclasses
 import os
 import subprocess
 from contextlib import ExitStack, contextmanager
 from pathlib import Path
 from typing import Callable, Generator
-from ...log import die
+from ...bottle_state import (
    egress_state_dir,
    git_gate_state_dir,
    read_committed_image,
 )
 from ...egress import (
    egress_agent_env_entries,
    egress_resolve_token_values,
 )
 from ...git_gate import (
    provision_git_gate_dynamic_keys,
    revoke_git_gate_provisioned_keys,
 )
 from ...git_http_backend import DEFAULT_PORT as _GIT_HTTP_PORT
 from ...log import die, info, warn
 from ...supervise import SUPERVISE_PORT
 from ..docker.egress import EGRESS_PORT
 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 .bottle_plan import MacosContainerBottlePlan
 from ...orchestrator.config_store import resolve_teardown_timeout
 from .consolidated_launch import (
    GatewayEndpoint,
    ensure_gateway,
    register_agent,
    teardown_consolidated,
 )
 _REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)
 _AGENT_SLEEP_SECONDS = "2147483647"
@contextmanager
@@ -27,13 +83,311 @@ def launch(
    *,
    provision: Callable[[MacosContainerBottlePlan, "MacosContainerBottle"], str | None],
 ) -> Generator[MacosContainerBottle, None, None]:
-    """Fail closed: the macOS backend is disabled until it grows the
+    """Build, run, register, provision, and yield an Apple Container bottle on
-    consolidated per-host gateway (the companion-container path it used
+    the shared per-host gateway."""
-    was removed in #385)."""
+    stack = ExitStack()
-    del plan, provision
+    bottle_for_revoke = plan.manifest.bottle
-    die(
+    git_gate_dir_for_revoke = git_gate_state_dir(plan.slug)
-        "the macos-container backend is temporarily disabled during the "
+
-        "companion-container removal (#385); it will return once it uses "
+    def teardown() -> None:
-        "the consolidated gateway. Use --backend=docker for now."
+        teardown_exc: BaseException | None = None
        try:
            stack.close()
        except BaseException as exc:  # noqa: W0718 - teardown must continue
            teardown_exc = exc
            warn(f"macos-container teardown failed: {exc!r}")
        revoke_git_gate_provisioned_keys(bottle_for_revoke, git_gate_dir_for_revoke)
        if teardown_exc is not None:
            raise teardown_exc
    try:
        plan = _build_images(plan)
        # 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)
        # 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)
        # Step 3: run the agent. It has no identity token yet — registration
        # needs the address this run assigns.
        container_mod.force_remove_container(plan.container_name)
        _start_agent(plan, endpoint)
        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,
        )
        stack.callback(
            teardown_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)
        bottle = MacosContainerBottle(
            plan.container_name,
            teardown,
            None,
            agent_command=plan.agent_command,
            agent_prompt_mode=plan.agent_prompt_mode,
            agent_provider_template=plan.agent_provider_template,
            terminal_title=(
                f"{plan.spec.label} ({plan.spec.agent_name})"
                if plan.spec.label else plan.spec.agent_name
            ),
            terminal_color=plan.spec.color,
            agent_workdir=plan.workspace_plan.workdir,
            exec_env=_identity_proxy_env(endpoint, ctx.identity_token),
        )
        bottle.prompt_path = provision(plan, bottle)
        yield bottle
    finally:
        teardown()
 def _build_images(plan: MacosContainerBottlePlan) -> MacosContainerBottlePlan:
    """Build the agent image. The gateway's own image is built by
    `ensure_gateway` — it belongs to the shared singleton, not to a bottle."""
    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,
    )
-    yield  # unreachable — `die` raises; keeps this a generator/contextmanager
+    return plan
 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 _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,
    )
    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 ""
    )
    supervise_url = (
        f"http://{GATEWAY_HOSTNAME}:{SUPERVISE_PORT}/"
        if plan.supervise_plan is not None else ""
    )
    return dataclasses.replace(
        plan,
        agent_git_gate_url=git_gate_url,
        agent_supervise_url=supervise_url,
    )
 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, 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,
    )
    if result.returncode != 0:
        die(
            f"container run for agent {plan.container_name} failed: "
            f"{(result.stderr or '').strip() or '<no stderr>'}"
        )
 def _agent_run_argv(
    plan: MacosContainerBottlePlan, endpoint: GatewayEndpoint,
 ) -> 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",
    ]
    for entry in _agent_env_entries(plan, endpoint):
        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 _agent_env_entries(
    plan: MacosContainerBottlePlan, endpoint: GatewayEndpoint,
 ) -> 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()
    env = [
        f"NO_PROXY={no_proxy}",
        f"no_proxy={no_proxy}",
        f"NODE_EXTRA_CA_CERTS={AGENT_CA_PATH}",
        f"SSL_CERT_FILE={AGENT_CA_BUNDLE}",
        f"REQUESTS_CA_BUNDLE={AGENT_CA_BUNDLE}",
    ]
    if plan.agent_git_gate_url:
        env.append(f"GIT_GATE_URL={plan.agent_git_gate_url}")
    if plan.agent_supervise_url:
        env.append(f"MCP_SUPERVISE_URL={plan.agent_supervise_url}")
    for name, value in sorted(plan.agent_provision.guest_env.items()):
        env.append(f"{name}={value}")
    # 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))
    return tuple(env)
 __all__ = ["launch"]
@@ -360,6 +360,21 @@ def exec_container(name: str, argv: list[str]) -> None:
        )
 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,
@@ -437,22 +452,180 @@ def inspect_container(name: str) -> dict[str, object]:
 def container_ipv4_on_network(name: str, network: str) -> str:
-    data = inspect_container(name)
+    """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
    status = data.get("status")
    networks = status.get("networks") if isinstance(status, dict) else None
    if not isinstance(networks, list):
-        die(f"container inspect {name} did not include status.networks")
+        return ""
    for entry in networks:
-        if not isinstance(entry, dict):
+        if not isinstance(entry, dict) or entry.get("network") != network:
            continue
        if entry.get("network") != network:
            continue
        raw = entry.get("ipv4Address")
-        if not isinstance(raw, str) or not raw:
+        if isinstance(raw, str) and raw:
-            die(f"container {name} has no IPv4 address on {network}")
+            return raw.split("/", 1)[0]
-        return raw.split("/", 1)[0]
+    return ""
-    die(f"container {name} is not attached to network {network}")
+
-    raise AssertionError("unreachable")
+
 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)
 def image_id(ref: str) -> str:
@@ -7,6 +7,8 @@ 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
@@ -15,6 +17,24 @@ 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
@@ -44,6 +44,7 @@ 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
 # live here so chunk 3's `docker compose up` can find them at stable
@@ -200,6 +201,15 @@ 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
@@ -354,6 +364,7 @@ __all__ = [
    "cleanup_state",
    "clear_preserve_marker",
    "committed_image_path",
    "committed_rootfs_path",
    "egress_state_dir",
    "git_gate_state_dir",
    "is_preserved",
@@ -38,6 +38,13 @@ COMMANDS = {
    "supervise": cmd_supervise,
 }
 # Commands that manage host prerequisites (or are otherwise store-free) and
 # must run before — or without — a migrated DB. `backend` provisions/probes
 # the host (TAP pool, /dev/kvm, firecracker) and never opens the store, so
 # gating it on the schema breaks preflight on a fresh CI runner where stdin
 # isn't a TTY and the migration prompt can't be answered.
 NO_MIGRATION_COMMANDS = frozenset({"backend"})
 def usage() -> None:
    sys.stderr.write(f"usage: {PROG} <command> [args...]\n\n")
@@ -80,7 +87,7 @@ def main(argv: list[str] | None = None) -> int:
        usage()
        die(f"unknown command: {command}")
    mgr = StoreManager.instance()
-    if not mgr.is_migrated():
+    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()
@@ -3,18 +3,10 @@
 from __future__ import annotations
 import os
 import sys
 from pathlib import Path
 from ..util import read_tty_line as read_tty_line
 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")
@@ -21,16 +21,20 @@ from __future__ import annotations
 import sys
-from ..backend import get_bottle_backend, known_backend_names
+from ..backend import get_bottle_backend, has_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.
+    # deterministic across runs. Skip backends whose runtime
    # isn't available on this host so e.g. macos-container
    # doesn't error on Linux.
    plans = [
-        (name, get_bottle_backend(name)) for name in known_backend_names()
+        (name, get_bottle_backend(name))
        for name in known_backend_names()
        if has_backend(name)
    ]
    prepared = [(name, b, b.prepare_cleanup()) for name, b in plans]
@@ -27,7 +27,6 @@ from ..backend import (
    BottleSpec,
    enumerate_active_agents,
    get_bottle_backend,
    known_backend_names,
 )
 from ..backend.docker import util as docker_mod
 from ..backend.docker.bottle_plan import DockerBottlePlan
@@ -57,15 +56,6 @@ def cmd_start(argv: list[str]) -> int:
            "into a cached layer."
        ),
    )
    parser.add_argument(
        "--backend",
        choices=known_backend_names(),
        default=None,
        help=(
            "backend to launch the bottle on (default: $BOT_BOTTLE_BACKEND "
            "or host auto-selection). Overrides the env var when set."
        ),
    )
    parser.add_argument(
        "--headless",
        action="store_true",
@@ -115,11 +105,10 @@ def cmd_start(argv: list[str]) -> int:
        os.environ["BOT_BOTTLE_NO_CACHE"] = "1"
    manifest = ManifestIndex.resolve(USER_CWD)
    backend_name: str | None = args.backend
    if args.headless:
        return _start_headless(
-            manifest, args, dry_run=dry_run, backend_name=backend_name
+            manifest, args, dry_run=dry_run
        )
    agent_name: str | None = args.name
@@ -170,7 +159,6 @@ def cmd_start(argv: list[str]) -> int:
    return _launch_bottle(
        spec,
        dry_run=dry_run,
        backend_name=backend_name,
    )
@@ -182,7 +170,6 @@ def _start_headless(
    args: argparse.Namespace,
    *,
    dry_run: bool,
    backend_name: str | None,
 ) -> int:
    """Non-interactive launch path for orchestrators / CI / webhooks.
@@ -230,7 +217,6 @@ def _start_headless(
    return _launch_bottle(
        spec,
        dry_run=dry_run,
        backend_name=backend_name,
        assume_yes=True,
        headless_prompt_text=prompt,
    )
@@ -268,15 +254,18 @@ def prepare_with_preflight(
    injected callable, prompt y/N via the injected callable.
    `backend_name` selects which backend prepares the plan
-    (`None` → `$BOT_BOTTLE_BACKEND` → host auto-selection). The CLI
+    (`None` → `$BOT_BOTTLE_BACKEND` → host auto-selection).
-    passes whatever `--backend` resolved to.
+
    When `spec.headless` is True the docker-fallback prompt is suppressed:
    auto-selection dies with an actionable message rather than blocking
    on a TTY read (which would hang CI, webhook dispatch, and orchestrators).
    Returns `(plan, identity)`. `plan` is None on dry-run or
    operator-N, but `identity` is set as soon as `backend.prepare`
    returns so callers can reap the prepare-time state dir via
    `settle_state(identity)` in their finally — exactly the existing
    semantics."""
-    backend = get_bottle_backend(backend_name)
+    backend = get_bottle_backend(backend_name, prompt=not spec.headless)
    plan = backend.prepare(spec, stage_dir=stage_dir)
    identity = _identity_from_plan(plan)
@@ -0,0 +1,17 @@
 """Shared wire-protocol constants for gateway-bundled modules.
 Single source of truth for values that appear across the egress addon,
 git-http backend, supervise server, and git-gate renderer. Importing
 from this module instead of duplicating the literals means a rename is
 a one-line change and is caught by the type checker at the import site."""
 # App-layer identity token header. Delivered as proxy credentials
 # (HTTPS_PROXY=http://<bottle_id>:<token>@gw) by launch; the egress
 # addon reads and strips it, the supervise server and git-http backend
 # read it for attribution, and none of them forward it upstream.
 IDENTITY_HEADER = "x-bot-bottle-identity"
 # Shared timeout (seconds) for all git-gate subprocess and CGI calls:
 # git daemon (--timeout/--init-timeout), the access-hook subprocess in
 # git_http_backend, and the git http-backend CGI subprocess.
 GIT_GATE_TIMEOUT_SECS = 15
@@ -23,8 +23,9 @@ from ...agent_provider import (
    provider_startup_args,
 )
 from ...backend.docker import util as docker_mod
-from ...egress import EgressRoute
+from ...egress import CLAUDE_HOST_CREDENTIAL_TOKEN_REF, EgressRoute
 from ...log import die, info, warn
 from .claude_auth import claude_host_access_token
 if TYPE_CHECKING:
@@ -118,7 +119,6 @@ class ClaudeAgentProvider(AgentProvider):
        color: str = "",
        provider_settings: dict[str, object] | None = None,
    ) -> AgentProvisionPlan:
        del forward_host_credentials, host_env
        resolved_guest_env = dict(guest_env or {})
        startup_args = provider_startup_args(provider_settings)
        guest_home = self.guest_home
@@ -180,13 +180,24 @@ class ClaudeAgentProvider(AgentProvider):
                claude_settings,
                f"{guest_home}/.claude/settings.json",
            ))
        provisioned_env: dict[str, str] = {}
        if forward_host_credentials:
            _host_env = host_env or dict(os.environ)
            provisioned_env[CLAUDE_HOST_CREDENTIAL_TOKEN_REF] = (
                claude_host_access_token(_host_env)
            )
        cred_token_ref = (
            CLAUDE_HOST_CREDENTIAL_TOKEN_REF if forward_host_credentials
            else auth_token
        )
        egress_routes = (EgressRoute(
            host="api.anthropic.com",
-            auth_scheme="Bearer" if auth_token else "",
+            auth_scheme="Bearer" if (auth_token or forward_host_credentials) else "",
-            token_ref=auth_token,
+            token_ref=cred_token_ref,
        ),)
        hidden_env_names: frozenset[str] = frozenset()
-        if auth_token:
+        if auth_token or forward_host_credentials:
            env_vars["CLAUDE_CODE_OAUTH_TOKEN"] = "egress-placeholder"
            hidden_env_names = frozenset({"CLAUDE_CODE_OAUTH_TOKEN"})
@@ -208,6 +219,7 @@ class ClaudeAgentProvider(AgentProvider):
            files=tuple(files),
            egress_routes=egress_routes,
            hidden_env_names=hidden_env_names,
            provisioned_env=provisioned_env,
        )
    def provision_skills(self, plan: "BottlePlan", bottle: "Bottle") -> None:
@@ -0,0 +1,114 @@
 """Host Claude auth helpers.
 Reads the host's Claude Code credentials and returns only the access
 token needed by egress. Does not expose refresh tokens or raw payloads.
 Credential storage by platform:
  Linux  — ~/.claude/.credentials.json
  macOS  — macOS Keychain, service "Claude Code-credentials"
            (file path is tried first; Keychain is the fallback)
 """
 from __future__ import annotations
 import json
 import os
 import subprocess
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
 from ...log import die
 _KEYCHAIN_SERVICE = "Claude Code-credentials"
 def claude_auth_path(host_env: dict[str, str] | None = None) -> Path:
    env = os.environ if host_env is None else host_env
    home = env.get("HOME")
    if home:
        return Path(home) / ".claude" / ".credentials.json"
    return Path.home() / ".claude" / ".credentials.json"
 def _read_keychain() -> dict[str, object] | None:
    """Try the macOS Keychain. Returns parsed JSON dict or None."""
    if sys.platform != "darwin":
        return None
    try:
        result = subprocess.run(
            ["security", "find-generic-password", "-s", _KEYCHAIN_SERVICE, "-w"],
            capture_output=True,
            text=True,
            timeout=10,
        )
    except (FileNotFoundError, subprocess.TimeoutExpired):
        return None
    if result.returncode != 0 or not result.stdout.strip():
        return None
    try:
        raw = json.loads(result.stdout.strip())
    except json.JSONDecodeError:
        return None
    return raw if isinstance(raw, dict) else None
 def claude_host_access_token(
    host_env: dict[str, str] | None = None,
    *,
    now: datetime | None = None,
 ) -> str:
    path = claude_auth_path(host_env)
    raw: dict[str, object] | None = None
    if path.is_file():
        try:
            raw = json.loads(path.read_text())
        except (OSError, json.JSONDecodeError) as e:
            die(f"claude host credentials: could not read valid JSON at {path}: {e}")
        if not isinstance(raw, dict):
            die(f"claude host credentials: {path} must contain a JSON object")
    else:
        raw = _read_keychain()
        if raw is None:
            die(
                f"claude host credentials: auth file missing at {path} and "
                f"macOS Keychain lookup for '{_KEYCHAIN_SERVICE}' failed. "
                "Run `claude login` on the host or disable "
                "agent_provider.forward_host_credentials."
            )
    oauth = raw.get("claudeAiOauth")
    if not isinstance(oauth, dict):
        die(
            "claude host credentials: claudeAiOauth is missing from credentials. "
            "Run `claude login` on the host or disable "
            "agent_provider.forward_host_credentials."
        )
    access_token = oauth.get("accessToken")
    if not isinstance(access_token, str) or not access_token:
        die(
            "claude host credentials: claudeAiOauth.accessToken is missing or empty. "
            "Run `claude login` on the host and restart the bottle."
        )
    # expiresAt is in milliseconds
    expires_at = oauth.get("expiresAt")
    if isinstance(expires_at, (int, float)):
        check_now = now or datetime.now(timezone.utc)
        exp_dt = datetime.fromtimestamp(float(expires_at) / 1000.0, timezone.utc)
        if exp_dt <= check_now:
            die(
                "claude host credentials: host Claude access token is expired. "
                "Run `claude login` on the host and restart the bottle."
            )
    return access_token
 __all__ = [
    "claude_auth_path",
    "claude_host_access_token",
 ]
@@ -3,6 +3,7 @@
 from __future__ import annotations
 import sqlite3
 from contextlib import contextmanager
 from pathlib import Path
 try:
@@ -28,12 +29,21 @@ class DbStore:
        conn.row_factory = sqlite3.Row
        return conn
    @contextmanager
    def _connection(self):
        conn = self._connect()
        try:
            with conn:
                yield conn
        finally:
            conn.close()
    def is_migrated(self) -> bool:
        """Return True if the DB is fully up-to-date, False if migration is needed."""
        if not self.db_path.exists():
            return False
        try:
-            with self._connect() as conn:
+            with self._connection() as conn:
                row = conn.execute(
                    "SELECT version FROM schema_versions WHERE module = ?",
                    (self._migrations.schema_key,),
@@ -45,7 +55,7 @@ class DbStore:
    def migrate(self) -> None:
        """Apply any pending migrations and set permissions on the DB file."""
-        with self._connect() as conn:
+        with self._connection() as conn:
            self._migrations.apply(conn)
        self._chmod()
@@ -3,9 +3,8 @@
 Pure Python, no mitmproxy dependency. Each detector is a module-level
 function returning `ScanResult | None`.
-Ships flat into the gateway image alongside
+Available in the gateway via the installed `bot_bottle` package
-`egress_addon_core.py` — both this file and the package source use
+(see `Dockerfile.gateway`).
 the same try/except import shim pattern.
 """
 from __future__ import annotations
@@ -20,10 +19,7 @@ from math import log2
 from collections import Counter
 from urllib.parse import quote as url_quote
-try:
+from .egress_addon_core import ScanResult
    from egress_addon_core import ScanResult  # type: ignore[import-not-found]
 except ImportError:  # pragma: no cover - host-side path
    from .egress_addon_core import ScanResult
 # ---------------------------------------------------------------------------
@@ -14,13 +14,20 @@ from __future__ import annotations
 import subprocess
-def run_docker(argv: list[str]) -> subprocess.CompletedProcess[str]:
+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)."""
+    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,
+        argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
        check=False, env=env,
    )
@@ -30,6 +30,7 @@ if TYPE_CHECKING:
    from .manifest import ManifestBottle
 CODEX_HOST_CREDENTIAL_TOKEN_REF = "BOT_BOTTLE_CODEX_HOST_ACCESS_TOKEN"
 CLAUDE_HOST_CREDENTIAL_TOKEN_REF = "BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN"
 EGRESS_HOSTNAME = "egress"
@@ -400,6 +401,7 @@ class Egress(ABC):
        )
 __all__ = [
    "CLAUDE_HOST_CREDENTIAL_TOKEN_REF",
    "CODEX_HOST_CREDENTIAL_TOKEN_REF",
    "EGRESS_HOSTNAME",
    "EGRESS_ROUTES_FILENAME",
@@ -10,14 +10,14 @@ import base64
 import binascii
 import json
 import os
 import signal
 import sys
 import typing
 from pathlib import Path
 from mitmproxy import http  # type: ignore[import-not-found]  # pylint: disable=import-error
-from egress_addon_core import (  # type: ignore[import-not-found]  # pylint: disable=import-error
+from bot_bottle.constants import IDENTITY_HEADER
 from bot_bottle.dlp_detectors import redact_tokens, strip_crlf
 from bot_bottle.egress_addon_core import (
    LOG_BLOCKS,
    LOG_FULL,
    DEFAULT_OUTBOUND_ON_MATCH,
@@ -33,7 +33,6 @@ from egress_addon_core import (  # type: ignore[import-not-found]  # pylint: dis
    decide_git_fetch,
    is_git_fetch_request,
    is_git_push_request,
    load_config,
    match_route,
    resolve_client_context,
    outbound_scan_headers,
@@ -41,42 +40,25 @@ from egress_addon_core import (  # type: ignore[import-not-found]  # pylint: dis
    scan_inbound,
    scan_outbound,
 )
 from bot_bottle import supervise as _sv
 from bot_bottle.policy_resolver import PolicyResolver
 try:
    from dlp_detectors import redact_tokens, strip_crlf  # type: ignore[import-not-found]
 except ImportError:  # pragma: no cover - host-side path
    from bot_bottle.dlp_detectors import (  # type: ignore[import-not-found]
        redact_tokens,
        strip_crlf,
    )
 try:
    import supervise as _sv  # type: ignore[import-not-found]
 except ImportError:  # pragma: no cover - host-side path
    from bot_bottle import supervise as _sv  # type: ignore[import-not-found]
 try:
    from policy_resolver import PolicyResolver  # type: ignore[import-not-found]
 except ImportError:  # pragma: no cover - host-side path
    from bot_bottle.policy_resolver import PolicyResolver
 DEFAULT_ROUTES_PATH = "/etc/egress/routes.yaml"
 INTROSPECT_HOST = "_egress.local"
-# Consolidated (multi-tenant) mode: when this points at the per-host
+# The per-host orchestrator control plane the addon resolves every request's
-# orchestrator's control plane, the addon resolves each client's Config by
+# Config against, by source IP (PRD 0070). Mandatory: the consolidated gateway
-# source IP per request instead of using a single static routes file. Unset
+# is the only topology now — there is no static per-bottle routes file to fall
-# → legacy per-bottle single-tenant mode (unchanged).
+# back to — so an unset value is a fatal misconfiguration (see __init__).
 ORCHESTRATOR_URL_ENV = "BOT_BOTTLE_ORCHESTRATOR_URL"
-# App-layer identity token. Delivered as proxy credentials
+# Per-flow key under which `request()` stashes the resolved (Config, supervise
-# (`HTTPS_PROXY=http://<bottle_id>:<token>@gw`): clients honor it as part of
+# slug, env) so the later `response()` and `websocket_message()` hooks scan
-# the proxy protocol without app changes, and the addon reads + strips it so
+# against the *calling bottle's* policy — the same one the request was decided
-# it never leaks upstream. The legacy `x-bot-bottle-identity` request header
+# on — without a second `/resolve` per response or per WebSocket frame. A hook
-# is still stripped defensively (git-http uses that header on its own port).
+# on a flow that never resolved (no stash) fails closed to deny-all, so it's a
-IDENTITY_HEADER = "x-bot-bottle-identity"
+# safe no-op rather than an unscanned pass.
 _FLOW_CTX_KEY = "bot_bottle_egress_ctx"
 def _token_from_proxy_auth(header: str) -> str:
@@ -109,21 +91,30 @@ _TOKEN_ALLOW_JUSTIFICATION = (
 class EgressAddon:
-    # Class default so addons built via __new__ (e.g. in tests) default to
+    # Bare annotations (no class value): __init__ sets a live PolicyResolver for
-    # single-tenant; __init__ sets the instance attribute for real runs.
+    # real runs, and every host-side test builds an addon via __new__ and sets a
-    _resolver: "PolicyResolver | None" = None
+    # fake resolver. Egress is resolver-only now — the per-request policy always
    # comes from the orchestrator's /resolve (PRD 0070); there is no static
    # per-bottle routes file, SIGHUP reload, or single-tenant fallback.
    _resolver: "PolicyResolver"
    # Class default so __new__-built addons have it (real runs get a fresh
    # per-instance dict in __init__; only http_connect mutates it, which the
    # request-flow tests don't exercise).
    _conn_tokens: "dict[str, str]" = {}
    def __init__(self) -> None:
-        self.routes_path = os.environ.get("EGRESS_ROUTES", DEFAULT_ROUTES_PATH)
+        # Resolver-only: the gateway is always multi-tenant, resolving each
-        self.config: Config = Config(routes=())
+        # request's policy by source IP against the orchestrator control plane
-        # Consolidated mode: resolve per-client Config from the orchestrator.
+        # (PRD 0070). The URL is mandatory — without a policy source the gateway
-        # Absent → single-tenant (static routes file); behaviour unchanged.
+        # must not come up (fail-closed), rather than silently allowing nothing.
        orch_url = os.environ.get(ORCHESTRATOR_URL_ENV, "").strip()
-        self._resolver = PolicyResolver(orch_url) if orch_url else None
+        if not orch_url:
            raise RuntimeError(
                f"{ORCHESTRATOR_URL_ENV} is required: the egress gateway "
                "resolves every request's policy from the orchestrator and has "
                "no static routes file to fall back to."
            )
        self._resolver = PolicyResolver(orch_url)
        # Tokens the operator has approved this session (PRD 0062), keyed by
        # bottle so the shared gateway keeps each bottle's safelist separate —
        # a global set would let bottle A's approved secret pass bottle B's DLP
@@ -134,16 +125,13 @@ class EgressAddon:
        # `Proxy-Authorization` (HTTPS tunnels don't repeat it on the bumped
        # inner requests). Keyed by client_conn.id; cleared on disconnect.
        self._conn_tokens: dict[str, str] = {}
        self._supervise_slug = os.environ.get("SUPERVISE_BOTTLE_SLUG", "").strip()
        self._token_allow_timeout = _token_allow_timeout_from_env(os.environ)
        self._reload(initial=True)
        self._install_sighup()
    @staticmethod
    def _supervise_available(slug: str) -> bool:
        """Supervise is reachable for this request iff we resolved a bottle to
-        attribute its proposals to (single-tenant env slug, or a source-IP
+        attribute its proposals to (the source-IP-attributed bottle id). Empty
-        -attributed bottle id). Empty → fail closed (no queue to write to)."""
+        → fail closed (no queue to write to)."""
        return bool(slug)
    def _safe_tokens_for(self, slug: str) -> set[str]:
@@ -152,40 +140,15 @@ class EgressAddon:
        bottle's approved token into another's scan."""
        return self._safe_tokens.setdefault(slug, set())
-    def _reload(self, *, initial: bool = False) -> None:
+    def _serve_introspection(
-        try:
+        self, flow: http.HTTPFlow, path: str, config: Config,
-            text = Path(self.routes_path).read_text(encoding="utf-8")
+    ) -> None:
-            new_config = load_config(text)
+        """Serve the calling bottle's own allowlist. `config` is this flow's
-        except (OSError, ValueError) as e:
+        resolved policy (the same one every hook uses), so the agent sees the
-            tag = "boot" if initial else "SIGHUP"
+        routes that actually apply to it."""
            sys.stderr.write(
                f"egress: {tag} load failed: {e}\n"
            )
            if initial:
                self.config = Config(routes=())
            return
        self.config = new_config
        log_label = ("off", "blocks", "full")[self.config.log]
        sys.stderr.write(
            f"egress: loaded {len(self.config.routes)} route(s): "
            f"{', '.join(r.host for r in self.config.routes)}"
            f" [log={log_label}]\n"
        )
    def _install_sighup(self) -> None:
        if not hasattr(signal, "SIGHUP"):
            return
        def handler(signum: int, frame: object) -> None:
            del signum, frame
            self._reload()
        signal.signal(signal.SIGHUP, handler)
    def _serve_introspection(self, flow: http.HTTPFlow, path: str) -> None:
        if path == "/allowlist":
            payload = json.dumps(
-                {"routes": [route_to_yaml_dict(r) for r in self.config.routes]},
+                {"routes": [route_to_yaml_dict(r) for r in config.routes]},
                indent=2,
            ).encode("utf-8")
            flow.response = http.Response.make(
@@ -199,11 +162,21 @@ class EgressAddon:
            {"Content-Type": "text/plain; charset=utf-8"},
        )
    def _flow_log(self, flow: http.HTTPFlow) -> int:
        """This flow's log level, from the policy `request()` resolved and
        stashed. The block/redact log gates were a single global in the static-
        config world; they are per bottle now, so they read it from the flow."""
        return self._flow_ctx(flow)[0].log
    def _req_ctx(self, flow: http.HTTPFlow) -> dict[str, object]:
        # Redact with this flow's resolved env overlay (process env + the
        # bottle's /resolve tokens), so the ctx scrubs the calling bottle's
        # provisioned secrets, not just os.environ's.
        env = self._flow_ctx(flow)[2]
        return {
-            "host": redact_tokens(flow.request.pretty_host, env=os.environ),
+            "host": redact_tokens(flow.request.pretty_host, env=env),
            "method": flow.request.method,
-            "path": redact_tokens(flow.request.path, env=os.environ),
+            "path": redact_tokens(flow.request.path, env=env),
        }
    def _block(
@@ -212,7 +185,7 @@ class EgressAddon:
        reason: str,
        ctx: dict[str, object] | None = None,
    ) -> None:
-        if self.config.log >= LOG_BLOCKS:
+        if self._flow_log(flow) >= LOG_BLOCKS:
            entry: dict[str, object] = {"event": "egress_block", "reason": reason}
            if ctx:
                entry.update(ctx)
@@ -223,31 +196,39 @@ class EgressAddon:
            {"Content-Type": "text/plain; charset=utf-8"},
        )
-    def _log_request(self, flow: http.HTTPFlow) -> None:
+    def _log_request(
        self, flow: http.HTTPFlow, env: "typing.Mapping[str, str]",
    ) -> None:
        # `env` is the per-flow resolved overlay (process env + this bottle's
        # /resolve tokens), so the log redaction scrubs the calling bottle's
        # provisioned secrets — not just the process-level ones in os.environ.
        headers = {
-            k: redact_tokens(v, env=os.environ)
+            k: redact_tokens(v, env=env)
            for k, v in flow.request.headers.items()
            if k.lower() != "authorization"
        }
-        body = redact_tokens(flow.request.get_text(strict=False) or "", env=os.environ)
+        body = redact_tokens(flow.request.get_text(strict=False) or "", env=env)
        sys.stderr.write(
            json.dumps({
                "event": "egress_request",
-                "host": redact_tokens(flow.request.pretty_host, env=os.environ),
+                "host": redact_tokens(flow.request.pretty_host, env=env),
                "method": flow.request.method,
-                "path": redact_tokens(flow.request.path, env=os.environ),
+                "path": redact_tokens(flow.request.path, env=env),
                "headers": headers,
                "body": body,
            })
            + "\n"
        )
-    def _log_response(self, flow: http.HTTPFlow) -> None:
+    def _log_response(
        self, flow: http.HTTPFlow, env: "typing.Mapping[str, str]",
    ) -> None:
        # Per-flow env overlay (see _log_request): redact this bottle's tokens.
        headers = {
-            k: redact_tokens(v, env=os.environ)
+            k: redact_tokens(v, env=env)
            for k, v in flow.response.headers.items()
        }
-        body = redact_tokens(flow.response.get_text(strict=False) or "", env=os.environ)
+        body = redact_tokens(flow.response.get_text(strict=False) or "", env=env)
        sys.stderr.write(
            json.dumps({
                "event": "egress_response",
@@ -262,17 +243,12 @@ class EgressAddon:
    def _resolve_flow(
        self, flow: http.HTTPFlow,
    ) -> "tuple[Config, str, typing.Mapping[str, str]]":
-        """The `(Config, supervise slug, env)` to apply to this request.
+        """The calling bottle's `(Config, supervise slug, env)`, resolved by
-        Single-tenant → the static `self.config`, the env slug, and the process
+        source IP in one round-trip against the orchestrator — fail-closed to
-        env. Consolidated → the calling bottle's Config + bottle id + auth
+        deny-all + empty slug if unattributed. `env` is the process env overlaid
-        tokens, resolved by source IP in one round-trip (fail-closed to deny-all
+        with the bottle's `/resolve` tokens, so upstream-auth injection (and DLP)
-        + empty slug if unattributed); `env` is the process env overlaid with
+        use *this* bottle's credentials. The identity token, if the agent
-        the bottle's tokens, so upstream-auth injection (and DLP) use *this*
+        injected one, is read then stripped so it never leaks upstream."""
        bottle's credentials — exactly what the per-bottle gateway daemon's env did.
        The identity token, if the agent injected one, is read then stripped so
        it never leaks upstream."""
        if self._resolver is None:
            return self.config, self._supervise_slug, os.environ
        conn = flow.client_conn
        client_ip = conn.peername[0] if conn and conn.peername else ""
        token = self._request_token(flow)
@@ -280,6 +256,36 @@ class EgressAddon:
        env = {**os.environ, **tokens} if tokens else os.environ
        return config, slug, env
    def _stash_flow_ctx(
        self,
        flow: http.HTTPFlow,
        config: Config,
        slug: str,
        env: "typing.Mapping[str, str]",
    ) -> None:
        """Remember the per-flow context `request()` resolved, so the later
        `response()` / `websocket_message()` hooks reuse it — scanning against
        the same bottle's policy the request was decided on, with one `/resolve`
        per flow rather than one per frame."""
        meta = getattr(flow, "metadata", None)
        if isinstance(meta, dict):
            meta[_FLOW_CTX_KEY] = (config, slug, env)
    def _flow_ctx(
        self, flow: http.HTTPFlow,
    ) -> "tuple[Config, str, typing.Mapping[str, str]]":
        """The `(Config, supervise slug, env)` `request()` resolved for this
        flow, so a later hook scans against the calling bottle's policy. Falls
        back to deny-all (empty routes, empty slug) for a flow that never passed
        through `request()` (or a flow object without metadata) — fail-closed, so
        a DLP hook on such a flow is a safe no-op rather than an unscanned pass."""
        meta = getattr(flow, "metadata", None)
        if isinstance(meta, dict):
            ctx = meta.get(_FLOW_CTX_KEY)
            if ctx is not None:
                return ctx
        return Config(routes=()), "", os.environ
    def _request_token(self, flow: http.HTTPFlow) -> str:
        """The per-bottle identity token for this request, from the proxy
        credentials — the delivery mechanism (`HTTPS_PROXY=http://id:token@gw`)
@@ -314,11 +320,17 @@ class EgressAddon:
    async def request(self, flow: http.HTTPFlow) -> None:
        request_path, _, query = flow.request.path.partition("?")
        if flow.request.pretty_host == INTROSPECT_HOST:
            self._serve_introspection(flow, request_path)
            return
        config, slug, env = self._resolve_flow(flow)
        # Stash for the response / websocket hooks so their DLP scans reuse this
        # bottle's resolved policy (one /resolve per flow — see _flow_ctx).
        self._stash_flow_ctx(flow, config, slug, env)
        # Introspection ("_egress.local/allowlist") reports the calling bottle's
        # own resolved routes — served after resolution so it reflects this
        # bottle's policy, not a stale global.
        if flow.request.pretty_host == INTROSPECT_HOST:
            self._serve_introspection(flow, request_path, config)
            return
        # DLP outbound scan BEFORE stripping auth — catches tokens the
        # agent tried to smuggle in any header, path, query param, or body.
@@ -367,6 +379,7 @@ class EgressAddon:
            env,
            request_method=flow.request.method,
            request_headers=req_headers,
            deny_reason=config.deny_reason,
        )
        if decision.action == "block":
@@ -377,7 +390,7 @@ class EgressAddon:
            flow.request.headers["authorization"] = decision.inject_authorization
        if config.log >= LOG_FULL:
-            self._log_request(flow)
+            self._log_request(flow, env)
    def _block_dlp(self, flow: http.HTTPFlow, result: ScanResult) -> None:
        ctx = self._req_ctx(flow)
@@ -424,7 +437,7 @@ class EgressAddon:
            # forwards; it fails closed only if a match survives the scrub.
            if policy == ON_MATCH_REDACT:
                if self._redact_outbound(flow, route, env):
-                    if self.config.log >= LOG_BLOCKS:
+                    if self._flow_log(flow) >= LOG_BLOCKS:
                        sys.stderr.write(json.dumps({
                            "event": "egress_redacted",
                            "reason": f"egress DLP: {result.reason}",
@@ -546,7 +559,7 @@ class EgressAddon:
            _sv.STATUS_APPROVED, _sv.STATUS_MODIFIED,
        ):
            self._safe_tokens_for(slug).add(result.matched)
-            if self.config.log >= LOG_BLOCKS:
+            if self._flow_log(flow) >= LOG_BLOCKS:
                sys.stderr.write(json.dumps({
                    "event": "egress_token_allowed",
                    "reason": f"egress DLP: {result.reason}",
@@ -586,14 +599,16 @@ class EgressAddon:
            await asyncio.sleep(TOKEN_ALLOW_POLL_INTERVAL_SECONDS)
    def response(self, flow: http.HTTPFlow) -> None:
-        """DLP inbound scan on response headers and body."""
+        """DLP inbound scan on response headers and body, against the calling
-        route = match_route(self.config.routes, flow.request.pretty_host)
+        bottle's resolved config (`request()` stashed it — see `_flow_ctx`)."""
        config, _slug, env = self._flow_ctx(flow)
        route = match_route(config.routes, flow.request.pretty_host)
        if route is None:
            return
        if flow.response is None:
            return
-        if self.config.log >= LOG_FULL:
+        if config.log >= LOG_FULL:
-            self._log_response(flow)
+            self._log_response(flow, env)
        resp_headers = {k.lower(): v for k, v in flow.response.headers.items()}
        body = flow.response.get_text(strict=False) or ""
        scan_text = build_inbound_scan_text(resp_headers, body)
@@ -610,7 +625,7 @@ class EgressAddon:
            resp_ctx = {**resp_ctx, "context": result.context}
        if result.severity == "block":
            self._block(flow, f"egress DLP: {result.reason}", ctx=resp_ctx)
-        elif result.severity == "warn" and self.config.log >= LOG_BLOCKS:
+        elif result.severity == "warn" and config.log >= LOG_BLOCKS:
            sys.stderr.write(
                json.dumps({
                    "event": "egress_warn",
@@ -621,7 +636,9 @@ class EgressAddon:
            )
    def websocket_message(self, flow: http.HTTPFlow) -> None:
-        """DLP scan on WebSocket frames.
+        """DLP scan on WebSocket frames, against the calling bottle's resolved
        config (see `_flow_ctx`). `request()` resolves and stashes the per-flow
        (config, slug, env) at the upgrade, and every frame reuses it.
        Outbound frames (from_client) are scanned for credential leakage;
        inbound frames are scanned for prompt injection.  On a block the
@@ -630,10 +647,8 @@ class EgressAddon:
        """
        if flow.websocket is None:  # type: ignore[union-attr]
            return
-        # WebSocket DLP runs against the static config only (single-tenant); in
+        config, slug, env = self._flow_ctx(flow)
-        # the consolidated gateway self.config has no routes, so this is inert
+        route = match_route(config.routes, flow.request.pretty_host)
        # until websocket routing is made source-IP-aware (a separate slice).
        route = match_route(self.config.routes, flow.request.pretty_host)
        if route is None:
            return
        message = flow.websocket.messages[-1]  # type: ignore[union-attr]
@@ -642,8 +657,8 @@ class EgressAddon:
            # A WebSocket data frame is not an HTTP request line, so CRLF is
            # not an injection vector here — scan only for credential leakage.
            result = scan_outbound(
-                route, content, os.environ,
+                route, content, env,
-                safe_tokens=self._safe_tokens_for(self._supervise_slug), crlf_text="",
+                safe_tokens=self._safe_tokens_for(slug), crlf_text="",
            )
            if result is not None and result.severity == "block":
                sys.stderr.write(f"egress DLP: {result.reason}\n")
@@ -6,9 +6,9 @@ exercise the parse + decision functions without depending on the
 `mitmproxy.http.HTTPFlow` API and is loaded inside the gateway
 container.
-Imports: stdlib + `yaml_subset` (which is itself stdlib-only and
+Imports: stdlib + sibling package modules (`yaml_subset`,
-ships flat into the gateway image alongside this file —
+`egress_dlp_config`). Available in the gateway via the installed
-see `Dockerfile.gateway`)."""
+`bot_bottle` package (see `Dockerfile.gateway`)."""
 from __future__ import annotations
@@ -16,36 +16,20 @@ import re
 import typing
 from dataclasses import dataclass
-try:
+from .yaml_subset import YamlSubsetError, parse_yaml_subset
    from yaml_subset import YamlSubsetError, parse_yaml_subset  # type: ignore[import-not-found]
 except ImportError:  # pragma: no cover - host-side path
    from .yaml_subset import YamlSubsetError, parse_yaml_subset
-# DLP detector-config parsing lives in a sibling module (also flat-bundled
+# DLP detector-config parsing lives in a sibling module. Re-exported below
-# into the gateway — see Dockerfile.gateway). Re-exported below so existing
+# so existing `from egress_addon_core import ON_MATCH_*` callers keep working.
-# `from egress_addon_core import ON_MATCH_*` callers keep working.
+from .egress_dlp_config import (
-try:
+    DEFAULT_OUTBOUND_ON_MATCH,
-    from egress_dlp_config import (  # type: ignore[import-not-found]
+    INBOUND_DETECTOR_NAMES,
-        DEFAULT_OUTBOUND_ON_MATCH,
+    ON_MATCH_BLOCK,
-        INBOUND_DETECTOR_NAMES,
+    ON_MATCH_REDACT,
-        ON_MATCH_BLOCK,
+    ON_MATCH_SUPERVISE,
-        ON_MATCH_REDACT,
+    OUTBOUND_DETECTOR_NAMES,
-        ON_MATCH_SUPERVISE,
+    OUTBOUND_ON_MATCH_VALUES,
-        OUTBOUND_DETECTOR_NAMES,
+    parse_dlp_block,
-        OUTBOUND_ON_MATCH_VALUES,
+)
        parse_dlp_block,
    )
 except ImportError:  # pragma: no cover - host-side path
    from .egress_dlp_config import (
        DEFAULT_OUTBOUND_ON_MATCH,
        INBOUND_DETECTOR_NAMES,
        ON_MATCH_BLOCK,
        ON_MATCH_REDACT,
        ON_MATCH_SUPERVISE,
        OUTBOUND_DETECTOR_NAMES,
        OUTBOUND_ON_MATCH_VALUES,
        parse_dlp_block,
    )
 # ---------------------------------------------------------------------------
@@ -105,6 +89,14 @@ LOG_FULL = 2    # log block/warn events + full request and response bodies
 class Config:
    routes: tuple[Route, ...]
    log: int = LOG_OFF
    # Why this Config is a deny-all, when it is one for a reason *other* than
    # the bottle's own policy genuinely not listing the host. A deny-all is
    # indistinguishable from "policy loaded, host not allowed" at the decision
    # point — both are simply "no matching route" — so without this the
    # operator sees `host X is not in the allowlist` and goes hunting for a
    # missing route that was never the problem. Empty for a normally-parsed
    # policy; `decide` prefers it over the allowlist wording when set.
    deny_reason: str = ""
@dataclass(frozen=True)
@@ -421,16 +413,40 @@ class PolicyResolverLike(typing.Protocol):
        ...
 # Deny-all explanations. Each names the *actual* failure so an operator isn't
 # sent looking for a missing egress route when the bottle never had a policy
 # to begin with — the failure mode that made a bricked registration read like
 # a misconfigured allowlist.
 DENY_UNATTRIBUTED = (
    "egress: this request was not attributed to any bottle, so no egress "
    "policy applies and every host is denied. Either the bottle's registry "
    "row is missing/ambiguous (torn down, or another bottle claimed its "
    "source IP), or the request carried no matching identity token — check "
    "that the caller's proxy URL includes it. This is not an allowlist problem."
 )
 DENY_UNPARSEABLE = (
    "egress: this bottle's egress policy could not be parsed, so it is being "
    "treated as deny-all. Fix the bottle's egress.routes; every host is denied "
    "until it loads."
 )
 DENY_RESOLVER_ERROR = (
    "egress: the orchestrator could not be reached to resolve this bottle's "
    "egress policy, so every host is denied (fail-closed). Check that the "
    "control plane is up; this is not an allowlist problem."
 )
 def _config_from_policy(policy: "str | None") -> "Config":
    """Parse a resolved policy blob into a Config, fail-closed: None / empty /
    unparseable all become a deny-all Config (no routes → every request
-    blocked)."""
+    blocked). Each deny-all carries the reason it is one, so the block message
    names the real fault instead of blaming the allowlist."""
    if not policy:
-        return Config(routes=())  # unattributed or empty → deny-all
+        return Config(routes=(), deny_reason=DENY_UNATTRIBUTED)
    try:
        return load_config(policy)
    except ValueError:
-        return Config(routes=())  # unparseable policy → deny
+        return Config(routes=(), deny_reason=DENY_UNPARSEABLE)
 def resolve_client_config(
@@ -444,7 +460,7 @@ def resolve_client_config(
    try:
        policy = resolver.resolve(client_ip, identity_token)
    except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
-        return Config(routes=())  # orchestrator unreachable/errored → deny
+        return Config(routes=(), deny_reason=DENY_RESOLVER_ERROR)
    return _config_from_policy(policy)
@@ -473,7 +489,7 @@ def resolve_client_context(
            client_ip, identity_token,
        )
    except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
-        return Config(routes=()), "", {}  # orchestrator unreachable/errored → deny
+        return Config(routes=(), deny_reason=DENY_RESOLVER_ERROR), "", {}
    return _config_from_policy(policy), (bottle_id or ""), tokens
@@ -588,12 +604,16 @@ def decide(
    *,
    request_method: str = "GET",
    request_headers: typing.Mapping[str, str] | None = None,
    deny_reason: str = "",
 ) -> Decision:
    """`deny_reason` is `Config.deny_reason`: when the deny-all came from a
    missing/unparseable policy rather than the bottle's own allowlist, report
    that instead of implying a route is merely absent."""
    route = match_route(routes, request_host)
    if route is None:
        return Decision(
            action="block",
-            reason=(
+            reason=deny_reason or (
                f"egress: host {request_host!r} is not in the "
                f"bottle's egress.routes allowlist. Declare a "
                f"route for it or remove the request."
@@ -868,6 +888,9 @@ __all__ = [
    "is_git_push_request",
    "is_git_fetch_request",
    "load_config",
    "DENY_UNATTRIBUTED",
    "DENY_UNPARSEABLE",
    "DENY_RESOLVER_ERROR",
    "resolve_client_config",
    "resolve_client_context",
    "PolicyResolverLike",
@@ -15,11 +15,23 @@
 #     mitmproxy at it. The option REPLACES mitmproxy's default
 #     trust store, so passing the upstream CA alone would break
 #     non-chained hosts.
-#   * `-s /app/egress_addon.py` loads the addon that reads
+#   * `-s /app/egress_addon.py` loads the addon that resolves each
-#     /etc/egress/routes.yaml.
+#     request's policy from the orchestrator control plane by source
 #     IP (PRD 0070). There is no static routes file.
 set -e
 # Fail closed on a missing policy source. The addon itself raises at
 # load when BOT_BOTTLE_ORCHESTRATOR_URL is unset (so mitmdump exits via
 # its errorcheck addon), but that leaves the fail-closed guarantee at the
 # mercy of a mitmproxy version keeping that behavior. Refuse here too, so
 # a misconfigured gateway can never come up as a bare TLS-bumping open
 # proxy with no policy — independent of mitmproxy's startup-error handling.
 if [ -z "$BOT_BOTTLE_ORCHESTRATOR_URL" ]; then
  echo "egress: BOT_BOTTLE_ORCHESTRATOR_URL is required (no static routes fallback)" >&2
  exit 1
 fi
 # Pin mitmproxy's config dir to the bind-mount location of its CA
 # regardless of which user mitmdump runs as. In the legacy
 # four-daemon setup (Dockerfile.egress, USER mitmproxy) this
@@ -61,6 +61,11 @@ class _DaemonSpec:
 _EGRESS_ONLY_ENV_PREFIXES: tuple[str, ...] = ("EGRESS_TOKEN_",)
 _READY_GATED_DAEMONS: tuple[str, ...] = ("git-gate", "git-http")
 # Daemons that must be requested explicitly via BOT_BOTTLE_GATEWAY_DAEMONS
 # and are NOT started in the default (env-var-unset) case. The orchestrator
 # only runs in the combined infra container, never in a standalone gateway.
 _OPT_IN_DAEMONS: frozenset[str] = frozenset({"orchestrator"})
 def _env_for_daemon(name: str, base_env: dict[str, str]) -> dict[str, str]:
    """Egress sees the full bundle env. Everyone else gets a copy
@@ -75,11 +80,18 @@ def _env_for_daemon(name: str, base_env: dict[str, str]) -> dict[str, str]:
    }
 # The orchestrator is listed first so it starts before the gateway daemons,
 # giving the control plane a head start to accept /resolve calls. The gateway
 # daemons tolerate early /resolve failures and retry per-request.
 _DAEMONS: tuple[_DaemonSpec, ...] = (
    _DaemonSpec("orchestrator", (
        "python3", "-m", "bot_bottle.orchestrator",
        "--host", "0.0.0.0", "--port", "8099", "--broker", "stub",
    )),
    _DaemonSpec("egress", ("/bin/sh", "/app/egress-entrypoint.sh")),
    _DaemonSpec("git-gate", ("/bin/sh", "/git-gate-entrypoint.sh")),
-    _DaemonSpec("git-http", ("python3", "/app/git_http_backend.py")),
+    _DaemonSpec("git-http", ("python3", "-m", "bot_bottle.git_http_backend")),
-    _DaemonSpec("supervise", ("python3", "/app/supervise_server.py")),
+    _DaemonSpec("supervise", ("python3", "-m", "bot_bottle.supervise_server")),
 )
@@ -103,18 +115,20 @@ def _selected_daemons(
    env: dict[str, str],
    all_daemons: Sequence[_DaemonSpec] | None = None,
 ) -> tuple[_DaemonSpec, ...]:
-    """Filter the daemon set by the BOT_BOTTLE_GATEWAY_DAEMONS env
+    """Filter the daemon set by the BOT_BOTTLE_GATEWAY_DAEMONS env var.
    var. Unknown names in the list are ignored — the caller is the
    source of truth for which daemons are wired.
-    `all_daemons` defaults to `_DAEMONS` resolved at call time (not
+    When the var is unset/empty, return all non-opt-in daemons (the
-    at definition time), so tests can monkey-patch the module-level
+    standard gateway subset). Opt-in daemons (e.g. `orchestrator`) only
-    `_DAEMONS` and have the new value take effect."""
+    run when explicitly named — they never start in a plain gateway
    container that doesn't set the env var. Unknown names are ignored.
    `all_daemons` defaults to `_DAEMONS` resolved at call time (not at
    definition time), so tests can pass a custom list."""
    if all_daemons is None:
        all_daemons = _DAEMONS
    raw = env.get("BOT_BOTTLE_GATEWAY_DAEMONS", "").strip()
    if not raw:
-        return tuple(all_daemons)
+        return tuple(d for d in all_daemons if d.name not in _OPT_IN_DAEMONS)
    wanted = {n.strip() for n in raw.split(",") if n.strip()}
    return tuple(d for d in all_daemons if d.name in wanted)
@@ -136,7 +150,7 @@ def _pump(name: str, stream: IO[bytes]) -> None:
 def _spawn(spec: _DaemonSpec) -> subprocess.Popen[bytes]:
    env = _env_for_daemon(spec.name, dict(os.environ))
-    proc = subprocess.Popen(
+    proc = subprocess.Popen(  # pylint: disable=consider-using-with
        _argv_for_daemon(spec.name, spec.argv, env),
        stdout=subprocess.PIPE,
        stderr=subprocess.STDOUT,
@@ -183,6 +197,14 @@ class _Supervisor:
                except ProcessLookupError:
                    pass
    def _sigkill_all(self) -> None:
        for _, p in self.procs:
            if p.poll() is None:
                try:
                    p.kill()
                except ProcessLookupError:
                    pass
    def request_restart(self, daemon_name: str) -> bool:
        """Queue a daemon restart for the main loop to process.
@@ -235,12 +257,7 @@ class _Supervisor:
                        f"grace ({_GRACE_SECONDS:.0f}s) elapsed; SIGKILL on "
                        f"{', '.join(still_running)}"
                    )
-                    for _, p in self.procs:
+                    self._sigkill_all()
                        if p.poll() is None:
                            try:
                                p.kill()
                            except ProcessLookupError:
                                pass
        done = all(p.poll() is not None for _, p in self.procs)
        if done:
@@ -361,7 +378,10 @@ def main(argv: Sequence[str] | None = None) -> int:
    # --signal HUP <bundle>` after writing routes.yaml. The kernel
    # delivers SIGHUP to PID 1 (this supervisor); forward it to
    # mitmdump so it reloads its addon.
-    signal.signal(signal.SIGHUP, lambda *_: sup.forward_signal(signal.SIGHUP, "egress"))  # type: ignore
+    signal.signal(
        signal.SIGHUP,
        lambda *_: sup.forward_signal(signal.SIGHUP, "egress"),  # type: ignore[misc]
    )
    while not sup.tick():
        time.sleep(_POLL_INTERVAL)
@@ -112,8 +112,10 @@ class GitGate(ABC):
        access_hook = stage_dir / "git_gate_access_hook.sh"
        access_hook.write_text(git_gate_render_access_hook())
        # 0o700 (not 0o600): git daemon execs --access-hook directly,
-        # not via `sh`, so the script needs the x bit. docker cp
+        # not via `sh`, so the script needs the x bit. The gateway copy
-        # preserves source mode into the container.
+        # does not necessarily preserve this mode (`docker cp` does, the
        # Apple `container cp` does not), so provision_git_gate re-applies
        # +x on the gateway side — see backend/docker/gateway_provision.py.
        access_hook.chmod(0o700)
        upstreams_with_files: list[GitGateUpstream] = []
        for u in upstreams:
@@ -14,18 +14,12 @@ import shlex
 from dataclasses import dataclass
 from pathlib import Path
 from .constants import GIT_GATE_TIMEOUT_SECS, IDENTITY_HEADER
 from .manifest import ManifestBottle, ManifestGitEntry
 # Short network alias for git-gate inside the gateway. The
 # agent's `.gitconfig` insteadOf rewrites resolve through this name.
 GIT_GATE_HOSTNAME = "git-gate"
 # App-layer identity token header the agent's git sends to git-http and the
 # gateway validates (mirrors egress_addon / git_http_backend IDENTITY_HEADER).
 IDENTITY_HEADER = "x-bot-bottle-identity"
 # Shared timeout (seconds) for all git-gate subprocess and CGI calls:
 # git daemon (--timeout/--init-timeout), the access-hook subprocess in
 # git_http_backend, and the git http-backend CGI subprocess.
 GIT_GATE_TIMEOUT_SECS = 15
@dataclass(frozen=True)
@@ -425,18 +419,24 @@ PY
 while IFS=' ' read -r old new ref; do
  [ -z "$ref" ] && continue
  [ "$new" = "$zero" ] && continue
-  if [ "$old" = "$zero" ]; then
+  # Scan only the commits this push introduces — those reachable from
-    # New ref: scan only the commits this push introduces — those
+  # $new but not from any ref the gate already has. Everything already
-    # reachable from $new but not from any ref the gate already has.
+  # on the gate arrived via upstream mirror-fetch or a previously
-    # Everything already on the gate arrived via upstream mirror-fetch
+  # gitleaks-scanned push, so it's already-upstream or already-scanned;
-    # or a previously gitleaks-scanned push, so it's already-upstream
+  # re-scanning it only resurfaces historical fixture findings.
-    # or already-scanned; re-scanning it (the old `$new` full-ancestry
+  #
-    # range) only resurfaces historical findings and blocks every new
+  # Applies to both new refs and updates. The old existing-branch range
-    # branch. See PRD 0028 / issue #106.
+  # `$old..$new` walks commits reachable from the new tip but not the
-    log_opts="$new --not --all"
+  # *old branch tip*: on a rebase/force-push onto a freshly-advanced
-  else
+  # main that pulls in all of main's new history (incl. the deliberate
-    log_opts="$old..$new"
+  # sandbox-escape gitleaks fixtures), blocking the push. `--not --all`
-  fi
+  # excludes anything already on the gate regardless of ancestry, so it
  # is also correct for non-fast-forward pushes (a rebase can skip
  # commits off the direct path). Security-equivalent per PRD 0028's
  # analysis: the bare repo's refs come only from trusted upstream
  # mirror-fetch or gitleaks-gated pushes.
  # See PRD 0028 (open question) / issues #106, #346.
  log_opts="$new --not --all"
  echo "git-gate: gitleaks scanning $ref ($log_opts)" >&2
  if ! gitleaks git --log-opts="$log_opts" --no-banner --redact 1>&2; then
    echo "git-gate: gitleaks rejected push to $ref" >&2
@@ -7,14 +7,13 @@ wrapper serves the same `/git/*.git` bare repos through
 `git http-backend`, so pre-receive and upstream forwarding remain the
 git-gate enforcement point.
-Consolidated (PRD 0070): when `BOT_BOTTLE_ORCHESTRATOR_URL` is set, one
+One shared gateway serves every bottle (PRD 0070): each request is served
-shared gateway serves every bottle, and each request is served from the
+from the calling bottle's repo namespace (`<root>/<bottle_id>`), attributed
-calling bottle's repo namespace (`<root>/<bottle_id>`), attributed from
+from the unspoofable source IP via the orchestrator. Per-repo credentials +
 the unspoofable source IP via the orchestrator. Per-repo credentials +
 hooks scope by repo directory, so isolating the *root* per bottle isolates
-its creds too. Unattributed clients fail closed (404). Unset → the legacy
+its creds too. Unattributed clients — and a missing/unreachable orchestrator
-per-bottle single-tenant flat root, unchanged — a transitional path that
+— fail closed (404). `BOT_BOTTLE_ORCHESTRATOR_URL` is mandatory: there is no
-gets stripped out once every backend runs the consolidated gateway.
+single-tenant flat-root fallback.
 """
 from __future__ import annotations
@@ -27,36 +26,19 @@ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
 from urllib.parse import urlsplit
-# policy_resolver ships flat alongside this file in the gateway
+from bot_bottle.constants import GIT_GATE_TIMEOUT_SECS, IDENTITY_HEADER
-# image (see Dockerfile.gateway); the bot_bottle.* fallback is the
+from bot_bottle.policy_resolver import PolicyResolveError, PolicyResolver
 # host-side / test path. Mirrors egress_addon's import shape.
 try:
    from policy_resolver import (  # type: ignore[import-not-found]
        PolicyResolveError,
        PolicyResolver,
    )
 except ImportError:  # pragma: no cover - host-side path
    from bot_bottle.policy_resolver import PolicyResolveError, PolicyResolver
 DEFAULT_PORT = 9420
-# Consolidated (multi-tenant) mode: when this points at the per-host
+# The per-host orchestrator control plane the backend attributes each request
-# orchestrator's control plane, the backend serves each request from the
+# to, serving from the *calling* bottle's repo namespace selected by source IP.
-# *calling* bottle's repo namespace, selected by source IP, instead of a
+# Mandatory — the same env the egress addon requires; there is no single flat
-# single flat repo root. Unset → legacy per-bottle single-tenant mode
+# repo-root fallback.
 # (unchanged). Same env the egress addon reads, so one orchestrator setting
 # flips the whole shared gateway multi-tenant.
 ORCHESTRATOR_URL_ENV = "BOT_BOTTLE_ORCHESTRATOR_URL"
-# App-layer identity token (defense-in-depth over the source-IP invariant);
+# The base under which each bottle's `<bottle_id>` repo namespace is nested.
 # the agent injects it, the backend reads it for attribution and never
 # forwards it to `git http-backend`. Mirrors egress_addon.IDENTITY_HEADER
 # (duplicated, not imported: egress_addon pulls in mitmproxy).
 IDENTITY_HEADER = "x-bot-bottle-identity"
 # Default flat repo root (single-tenant, and the base under which
 # consolidated mode nests each sandbox's namespace).
 DEFAULT_REPO_ROOT = "/git"
@@ -71,25 +53,16 @@ class ResolverLike(typing.Protocol):
 def resolve_sandbox_root(
-    resolver: "ResolverLike | None",
+    resolver: "ResolverLike",
    base_root: Path,
    source_ip: str,
    identity_token: str = "",
 ) -> Path | None:
-    """The per-sandbox repo root to serve this request from, or None to
+    """The per-sandbox repo root to serve this request from — `base_root/
-    deny (404).
+    <bottle_id>`, where the sandbox is attributed from the source IP via the
-
+    orchestrator — or None to deny (404). Fail-closed: an unattributed client, a
-    Single-tenant (`resolver is None`): the flat `base_root`, unchanged.
+    resolver error, or a namespace that would escape `base_root` all deny, so one
-    NOTE: this legacy per-bottle single-tenant path is transitional — it
+    sandbox can never reach another's repos."""
    will be stripped out once every backend runs the consolidated gateway
    (PRD 0070), leaving only the source-IP-attributed path below.
    Consolidated: `base_root/<bottle_id>`, where the sandbox is attributed
    from the source IP via the orchestrator. Fail-closed — an unattributed
    client, a resolver error, or a namespace that would escape `base_root`
    all deny, so one sandbox can never reach another's repos."""
    if resolver is None:
        return base_root
    try:
        bottle_id = resolver.resolve_bottle_id(source_ip, identity_token)
    except PolicyResolveError:
@@ -102,13 +75,6 @@ def resolve_sandbox_root(
        return None  # bottle_id tried to escape the root → deny
    return namespace
 # Mirrors git_gate_render.GIT_GATE_TIMEOUT_SECS. Duplicated rather than
 # imported: this module ships as a flat top-level sibling in the gateway
 # bundle image (see Dockerfile.gateway), not as part of the bot_bottle
 # package, so `bot_bottle.git_gate` and its dependency chain aren't
 # available at runtime.
 GIT_GATE_TIMEOUT_SECS = 15
 # Bound memory use while still allowing ordinary git push packfiles.
 MAX_BODY_BYTES = 100 * 1024 * 1024
@@ -123,12 +89,13 @@ class GitHttpHandler(BaseHTTPRequestHandler):
        self._run_backend()
    def _sandbox_root(self) -> Path | None:
-        """This request's per-sandbox repo root, or None to deny. Single-tenant
+        """This request's per-sandbox repo root (the calling bottle's source-IP-
-        unless the server was started with a resolver (consolidated mode), in
+        selected `<base>/<bottle_id>` namespace), or None to deny. `GIT_PROJECT_
-        which case the root is the calling sandbox's source-IP-selected
+        ROOT` keeps git's own env-var name."""
        namespace. `GIT_PROJECT_ROOT` keeps git's own env-var name."""
        base = Path(os.environ.get("GIT_PROJECT_ROOT", DEFAULT_REPO_ROOT))
        resolver = getattr(self.server, "policy_resolver", None)
        if resolver is None:
            return None  # server started without a resolver (misconfig) → deny
        token = self.headers.get(IDENTITY_HEADER, "")
        return resolve_sandbox_root(resolver, base, self.client_address[0], token)
@@ -148,12 +115,24 @@ class GitHttpHandler(BaseHTTPRequestHandler):
                "GIT_GATE_ACCESS_HOOK", "/etc/git-gate/access-hook",
            )
            peer = self.client_address[0]
-            hook = subprocess.run(
+            try:
-                [hook_path, "upload-pack", str(repo_dir), peer, peer],
+                hook = subprocess.run(
-                capture_output=True,
+                    [hook_path, "upload-pack", str(repo_dir), peer, peer],
-                check=False,
+                    capture_output=True,
-                timeout=GIT_GATE_TIMEOUT_SECS,
+                    check=False,
-            )
+                    timeout=GIT_GATE_TIMEOUT_SECS,
                )
            except (OSError, subprocess.SubprocessError) as exc:
                # The access-hook couldn't be run (missing, not executable,
                # timed out, …). Fail closed with a real HTTP error rather
                # than letting the exception kill the handler thread — an
                # unhandled exception closes the socket with no response, which
                # the client sees as an opaque "empty reply from server".
                self.log_message(
                    "access-hook could not run for %s: %s", parsed.path, exc,
                )
                self.send_error(503, "git-gate access-hook unavailable")
                return
            if hook.returncode != 0:
                detail = (hook.stderr or hook.stdout).decode(
                    "utf-8", errors="replace",
@@ -188,14 +167,11 @@ class GitHttpHandler(BaseHTTPRequestHandler):
            "SERVER_PORT": str(self.server.server_port),  # type: ignore
            "SERVER_PROTOCOL": self.request_version,
        })
-        # Consolidated mode: attribute the gitleaks-allow supervise proposal
+        # Attribute the gitleaks-allow supervise proposal (written by
-        # (written by receive-pack's pre-receive hook, a child of the CGI we
+        # receive-pack's pre-receive hook, a child of the CGI we spawn below) to
-        # spawn below) to the calling bottle. The namespaced root is
+        # the calling bottle. The namespaced root is `<base>/<bottle_id>`, so its
-        # `<base>/<bottle_id>`, so its final component is the bottle id — the
+        # final component is the bottle id — the same per-bottle key egress uses.
-        # same per-bottle key egress uses. Single-tenant leaves the hook's
+        env["SUPERVISE_BOTTLE_SLUG"] = sandbox_root.name
        # container-stamped SUPERVISE_BOTTLE_SLUG untouched.
        if getattr(self.server, "policy_resolver", None) is not None:
            env["SUPERVISE_BOTTLE_SLUG"] = sandbox_root.name
        for header, variable in (
            ("accept", "HTTP_ACCEPT"),
            ("content-encoding", "HTTP_CONTENT_ENCODING"),
@@ -285,14 +261,20 @@ class GitHttpHandler(BaseHTTPRequestHandler):
 def main() -> int:
    port = int(os.environ.get("GIT_HTTP_PORT", str(DEFAULT_PORT)))
    server = ThreadingHTTPServer(("0.0.0.0", port), GitHttpHandler)
    orch_url = os.environ.get(ORCHESTRATOR_URL_ENV, "").strip()
-    # Consolidated mode: resolve each request's sandbox namespace by source
+    if not orch_url:
-    # IP. Absent → single-tenant (flat repo root); behaviour unchanged.
+        # Resolver-only: without an orchestrator the backend can't attribute a
-    resolver = PolicyResolver(orch_url) if orch_url else None
+        # request to a bottle namespace, so it must not serve (fail-closed).
-    server.policy_resolver = resolver  # type: ignore[attr-defined]
+        sys.stderr.write(
-    mode = "multi-tenant" if orch_url else "single-tenant"
+            f"git-http: {ORCHESTRATOR_URL_ENV} is required "
-    sys.stdout.write(f"git-http listening on 0.0.0.0:{port} ({mode})\n")
+            "(no single-tenant flat-root fallback)\n"
        )
        return 1
    server = ThreadingHTTPServer(("0.0.0.0", port), GitHttpHandler)
    # Resolve each request's sandbox namespace by source IP against the
    # orchestrator control plane.
    server.policy_resolver = PolicyResolver(orch_url)  # type: ignore[attr-defined]
    sys.stdout.write(f"git-http listening on 0.0.0.0:{port} (multi-tenant)\n")
    sys.stdout.flush()
    server.serve_forever()
    return 0
@@ -25,8 +25,9 @@ class ManifestAgentProvider:
    header, and sets a placeholder CLAUDE_CODE_OAUTH_TOKEN in the agent
    so the Claude Code CLI starts.
-    `forward_host_credentials` forwards the host Codex auth token into
+    `forward_host_credentials` forwards the host provider auth token into
-    the egress daemon (Codex only).
+    the egress sidecar (Codex and Claude). For Codex this reads
    `~/.codex/auth.json`; for Claude it reads `~/.claude/.credentials.json`.
    """
    template: str = "claude"
@@ -92,10 +93,15 @@ class ManifestAgentProvider:
                f"is only supported for built-in templates "
                f"({', '.join(sorted(PROVIDER_TEMPLATES))})"
            )
-        if forward_host_credentials and template != "codex":
+        if forward_host_credentials and template not in {"codex", "claude"}:
            raise ManifestError(
                f"bottle '{bottle_name}' agent_provider.forward_host_credentials "
-                "is currently only supported for template 'codex'"
+                "is only supported for templates 'codex' and 'claude'"
            )
        if forward_host_credentials and auth_token:
            raise ManifestError(
                f"bottle '{bottle_name}' agent_provider.forward_host_credentials "
                "and auth_token both set; use one or the other"
            )
        settings = _parse_provider_settings(bottle_name, template, d.get("settings"))
        return cls(
@@ -15,11 +15,25 @@ from __future__ import annotations
 import json
 import urllib.error
 import urllib.request
 from collections.abc import Iterable
 from dataclasses import dataclass
 from ..paths import host_control_plane_token
 from .control_plane import CONTROL_AUTH_HEADER
 DEFAULT_TIMEOUT_SECONDS = 5.0
 def _host_auth_token() -> str:
    """The per-host control-plane secret, or "" if it can't be read. "" means
    'send no auth header' — correct against an open (unconfigured) control
    plane, and harmlessly rejected by a secured one."""
    try:
        return host_control_plane_token()
    except OSError:
        return ""
 class OrchestratorClientError(RuntimeError):
    """A control-plane call failed (unreachable, or an unexpected status)."""
@@ -34,11 +48,24 @@ class RegisteredBottle:
 class OrchestratorClient:
-    """Trusted host-side client for the orchestrator control plane."""
+    """Trusted host-side client for the orchestrator control plane.
-    def __init__(self, base_url: str, *, timeout: float = DEFAULT_TIMEOUT_SECONDS) -> None:
+    Presents the per-host control-plane secret on every call (the header the
    control plane requires on all routes but `/health`). The secret is read
    from the host file — this client only ever runs host-side (CLI, launcher,
    discovery), so it can read what an agent can't. `auth_token` is overridable
    for tests; the default reads the host file, minting it on first use."""
    def __init__(
        self,
        base_url: str,
        *,
        timeout: float = DEFAULT_TIMEOUT_SECONDS,
        auth_token: str | None = None,
    ) -> None:
        self._base = base_url.rstrip("/")
        self._timeout = timeout
        self._auth_token = auth_token if auth_token is not None else _host_auth_token()
    def _request(
        self, method: str, path: str, body: dict[str, object] | None = None,
@@ -49,6 +76,8 @@ class OrchestratorClient:
        callers can treat 404 as a meaningful "no such bottle"."""
        data = json.dumps(body).encode() if body is not None else None
        headers = {"Content-Type": "application/json"} if data is not None else {}
        if self._auth_token:
            headers[CONTROL_AUTH_HEADER] = self._auth_token
        req = urllib.request.Request(
            f"{self._base}{path}", data=data, method=method, headers=headers,
        )
@@ -119,6 +148,20 @@ class OrchestratorClient:
            raise OrchestratorClientError(f"teardown {bottle_id}: HTTP {status}")
        return True
    def reconcile(
        self, live_source_ips: Iterable[str], *, grace_seconds: float | None = None,
    ) -> list[str]:
        """Drop registry rows for bottles that are no longer running
        (`POST /reconcile`), returning the reaped bottle ids. `live_source_ips`
        is the caller's enumeration of its live bottles — the orchestrator
        can't see the backend from inside the infra container."""
        body: dict[str, object] = {"live_source_ips": list(live_source_ips)}
        if grace_seconds is not None:
            body["grace_seconds"] = grace_seconds
        payload = self._ok("POST", "/reconcile", body)
        reaped = payload.get("reaped")
        return [r for r in reaped if isinstance(r, str)] if isinstance(reaped, list) else []
    def set_policy(self, bottle_id: str, policy: str) -> bool:
        """Live-reload a bottle's policy (`PUT /bottles/<id>/policy`). False on
        404 (unknown bottle)."""
@@ -186,6 +229,13 @@ def discover_orchestrator_url(*, timeout: float = 2.0) -> str:
            f"http://{netpool.orch_slot().guest_ip}:{CONTROL_PLANE_PORT}")
    except Exception:  # noqa: BLE001 — backend optional / not firecracker
        pass
    try:  # macOS: infra container control plane on its host-only address
        from ..backend.macos_container.infra import probe_control_plane_url
        url = probe_control_plane_url()
        if url:
            candidates.append(url)
    except Exception:  # noqa: BLE001 — backend optional / not macOS
        pass
    for url in candidates:
        if OrchestratorClient(url, timeout=timeout).health():
            return url
@@ -0,0 +1,107 @@
 """Per-host orchestrator configuration store (settings in bot-bottle.db).
 Co-tenants the shared `bot-bottle.db` via the `DbStore` framework.  Settings
 are readable by the host launch path directly (no HTTP round-trip to the
 orchestrator), so they take effect even before the orchestrator is reachable.
 """
 from __future__ import annotations
 import os
 import sqlite3
 from pathlib import Path
 from ..db_store import DbStore
 from ..migrations import TableMigrations
 from ..paths import host_db_path
 TEARDOWN_TIMEOUT_ENV = "BOT_BOTTLE_ORCHESTRATOR_TEARDOWN_TIMEOUT_SECONDS"
 DEFAULT_TEARDOWN_TIMEOUT_SECONDS = 30.0
 _MIGRATIONS = TableMigrations(
    "orchestrator_config",
    [
        """
        CREATE TABLE IF NOT EXISTS orchestrator_config (
            id                       INTEGER PRIMARY KEY CHECK (id = 1),
            teardown_timeout_seconds REAL
        )
        """,
    ],
 )
 class OrchestratorConfigStore(DbStore):
    """Orchestrator settings in the shared host DB."""
    def __init__(self, db_path: Path | None = None) -> None:
        super().__init__(db_path or host_db_path(), _MIGRATIONS)
    def _connect(self) -> sqlite3.Connection:
        conn = super()._connect()
        conn.execute("PRAGMA busy_timeout=5000")
        return conn
    def get_teardown_timeout_seconds(self) -> float | None:
        """Return the configured teardown timeout, or None if not set."""
        try:
            with self._connection() as conn:
                row = conn.execute(
                    "SELECT teardown_timeout_seconds FROM orchestrator_config WHERE id = 1"
                ).fetchone()
        except sqlite3.OperationalError:
            return None
        return row["teardown_timeout_seconds"] if row else None
    def set_teardown_timeout_seconds(self, value: float) -> None:
        """Persist the teardown timeout."""
        with self._connection() as conn:
            conn.execute(
                "INSERT OR REPLACE INTO orchestrator_config"
                " (id, teardown_timeout_seconds) VALUES (1, ?)",
                (value,),
            )
        self._chmod()
    def delete_teardown_timeout_seconds(self) -> bool:
        """Clear the stored teardown timeout. Returns True if a value existed."""
        with self._connection() as conn:
            cur = conn.execute(
                "UPDATE orchestrator_config SET teardown_timeout_seconds = NULL"
                " WHERE id = 1 AND teardown_timeout_seconds IS NOT NULL"
            )
        return cur.rowcount > 0
 def resolve_teardown_timeout(db_path: Path | None = None) -> float:
    """Return the teardown timeout to use, in priority order:
    1. ``BOT_BOTTLE_ORCHESTRATOR_TEARDOWN_TIMEOUT_SECONDS`` env var
    2. ``teardown_timeout_seconds`` in the orchestrator config DB
    3. ``DEFAULT_TEARDOWN_TIMEOUT_SECONDS`` (30 s)
    """
    raw = os.environ.get(TEARDOWN_TIMEOUT_ENV, "").strip()
    if raw:
        try:
            value = float(raw)
            if value > 0:
                return value
        except ValueError:
            pass
    store = OrchestratorConfigStore(db_path)
    if not store.is_migrated():
        store.migrate()
    db_value = store.get_teardown_timeout_seconds()
    if db_value is not None and db_value > 0:
        return db_value
    return DEFAULT_TEARDOWN_TIMEOUT_SECONDS
 __all__ = [
    "OrchestratorConfigStore",
    "resolve_teardown_timeout",
    "TEARDOWN_TIMEOUT_ENV",
    "DEFAULT_TEARDOWN_TIMEOUT_SECONDS",
 ]
@@ -13,6 +13,9 @@ vsock / unix-socket portability caveats):
    PUT    /bottles/<bottle_id>/policy -> 200 {"updated": true} | 404  (live reload)
                                         body: {"policy"}
    DELETE /bottles/<bottle_id>        -> 200 {"torn_down": true} | 404  (teardown)
    POST   /reconcile                 -> 200 {"reaped": [bottle_id, ...]}
                                         body: {"live_source_ips": [...],
                                                ["grace_seconds"]}
    POST   /attribute                 -> 200 {"bottle_id"} | 403
    POST   /resolve                   -> 200 {"bottle_id","policy"} | 403
                                         body: {"source_ip","identity_token"}
@@ -34,6 +37,7 @@ returned only once, to the caller that launches the bottle.
 from __future__ import annotations
 import hmac
 import http.server
 import json
 import os
@@ -42,11 +46,20 @@ import sys
 import typing
 from urllib.parse import urlsplit
 from ..paths import CONTROL_PLANE_TOKEN_ENV
 from .service import Orchestrator
 # JSON body payload type (parsed request / rendered response).
 Json = dict[str, object]
 # The request header carrying the per-host control-plane secret. Every route
 # except `GET /health` requires it (see `dispatch`). The trusted callers hold
 # the secret (the gateway's PolicyResolver, the host CLI's OrchestratorClient);
 # an agent that can merely *reach* the port cannot present it, so it can't
 # enumerate bottles, rewrite policy, read injected upstream tokens, or approve
 # its own supervise proposals.
 CONTROL_AUTH_HEADER = "x-bot-bottle-control-auth"
 def _parse_json_object(body: bytes) -> Json:
    """Parse a JSON object body. Raises ValueError for non-objects / bad JSON."""
@@ -59,15 +72,29 @@ def _parse_json_object(body: bytes) -> Json:
 def dispatch(  # pylint: disable=too-many-return-statements,too-many-branches
-    orch: Orchestrator, method: str, path: str, body: bytes
+    orch: Orchestrator, method: str, path: str, body: bytes, *, authorized: bool = True,
 ) -> tuple[int, Json]:
    """Route one control-plane request to a (status, payload) pair. Pure —
-    no I/O beyond the orchestrator — so it is fully testable without a socket."""
+    no I/O beyond the orchestrator — so it is fully testable without a socket.
    `authorized` is whether the request presented the control-plane secret (or
    no secret is configured — see `ControlPlaneServer`). Every route except
    `GET /health` requires it: the source-IP + identity-token checks inside
    `/resolve` and `/attribute` authenticate the *bottle* a request is about,
    not the *caller*, so without this gate any agent that can reach the port
    could rewrite another bottle's policy, read the injected upstream tokens,
    or approve its own supervise proposals. Defaults True so unit tests of the
    routing logic don't have to thread it through."""
    route = urlsplit(path).path.rstrip("/") or "/"
    if method == "GET" and route == "/health":
        return 200, {"status": "ok"}
    if not authorized:
        # Everything below is a trusted-caller operation. Deny before touching
        # the registry / broker / supervise store.
        return 401, {"error": "control-plane authentication required"}
    if method == "GET" and route == "/gateway":
        return 200, orch.gateway_status()
@@ -117,6 +144,27 @@ def dispatch(  # pylint: disable=too-many-return-statements,too-many-branches
            return 200, {"torn_down": True}
        return 404, {"error": "no such bottle"}
    if method == "POST" and route == "/reconcile":
        # Host-driven self-heal: the caller enumerates its live bottles (only
        # the host can see the backend) and the orchestrator drops rows for
        # every other active bottle. Trusted-caller only — an agent that could
        # reach this would be able to unregister its neighbours.
        try:
            data = _parse_json_object(body)
        except ValueError as e:
            return 400, {"error": f"invalid JSON: {e}"}
        raw_ips = data.get("live_source_ips")
        if not isinstance(raw_ips, list):
            return 400, {"error": "live_source_ips (list of strings) is required"}
        live = [ip for ip in raw_ips if isinstance(ip, str) and ip]
        grace = data.get("grace_seconds")
        kwargs = (
            {"grace_seconds": float(grace)}
            if isinstance(grace, (int, float)) and not isinstance(grace, bool)
            else {}
        )
        return 200, {"reaped": orch.reconcile(live, **kwargs)}
    if method == "POST" and route == "/attribute":
        try:
            data = _parse_json_object(body)
@@ -209,8 +257,10 @@ class Handler(http.server.BaseHTTPRequestHandler):
        assert isinstance(server, ControlPlaneServer)
        length = int(self.headers.get("Content-Length") or 0)
        body = self.rfile.read(length) if length > 0 else b""
        authorized = server.is_authorized(self.headers.get(CONTROL_AUTH_HEADER, ""))
        try:
-            status, payload = dispatch(server.orchestrator, method, self.path, body)
+            status, payload = dispatch(
                server.orchestrator, method, self.path, body, authorized=authorized)
        except Exception as e:  # noqa: BLE001 — the control plane must stay up
            sys.stderr.write(f"orchestrator: {method} {self.path} failed: {e!r}\n")
            sys.stderr.flush()
@@ -236,15 +286,40 @@ class Handler(http.server.BaseHTTPRequestHandler):
 class ControlPlaneServer(socketserver.ThreadingMixIn, http.server.HTTPServer):
-    """Threading HTTP server that carries the orchestrator for its handlers."""
+    """Threading HTTP server that carries the orchestrator for its handlers.
    Holds the per-host control-plane secret (from `$BOT_BOTTLE_CONTROL_PLANE_TOKEN`,
    injected by the launcher into this container only). When a secret is set,
    every route but `/health` requires it; when it is unset the server runs
    **open** and says so loudly at startup — a fail-visible fallback for tests
    and any backend that hasn't wired the secret yet (e.g. Firecracker, whose
    nft boundary already blocks agents from the control-plane port)."""
    daemon_threads = True
    allow_reuse_address = True
    def __init__(self, address: tuple[str, int], orchestrator: Orchestrator) -> None:
        self.orchestrator = orchestrator
        self._auth_token = os.environ.get(CONTROL_PLANE_TOKEN_ENV, "").strip()
        if not self._auth_token:
            sys.stderr.write(
                "orchestrator: WARNING — no control-plane secret "
                f"(${CONTROL_PLANE_TOKEN_ENV}); running WITHOUT caller "
                "authentication. Any client that can reach this port can drive "
                "it. Backends that put the control plane on an agent-reachable "
                "network MUST set this.\n"
            )
            sys.stderr.flush()
        super().__init__(address, Handler)
    def is_authorized(self, presented: str) -> bool:
        """True iff the request may proceed past `/health`: either no secret is
        configured (open mode) or the presented header matches it. Constant-time
        compare so a wrong token leaks nothing timing-wise."""
        if not self._auth_token:
            return True
        return hmac.compare_digest(presented, self._auth_token)
 def make_server(
    orchestrator: Orchestrator, host: str = "127.0.0.1", port: int = 0
@@ -254,4 +329,7 @@ def make_server(
    return ControlPlaneServer((host, port), orchestrator)
-__all__ = ["dispatch", "Handler", "ControlPlaneServer", "make_server", "Json"]
+__all__ = [
    "dispatch", "Handler", "ControlPlaneServer", "make_server", "Json",
    "CONTROL_AUTH_HEADER",
 ]
@@ -23,7 +23,11 @@ import time
 from pathlib import Path
 from ..docker_cmd import run_docker
-from ..paths import host_db_path
+from ..paths import (
    CONTROL_PLANE_TOKEN_ENV,
    host_control_plane_token,
    host_db_path,
 )
 from ..supervise import DB_PATH_IN_CONTAINER
 # The host DB dir is bind-mounted here so the gateway's supervise daemon
@@ -122,7 +126,10 @@ class DockerGateway(Gateway):
        self.network = network
        # The control-plane URL the gateway's data plane resolves per bottle
        # against — reached by container name over docker DNS on the shared
-        # network (container↔container, no host firewall). Empty → single-tenant.
+        # network (container↔container, no host firewall). Mandatory to *run*
        # the gateway (see `ensure_running`); empty is tolerated only for the
        # construct-then-read-CA path (`ca_cert_pem` on an already-running
        # container), which never launches a container.
        self._orchestrator_url = orchestrator_url
        self._build_context = build_context or _REPO_ROOT
        self._dockerfile = dockerfile
@@ -189,6 +196,16 @@ class DockerGateway(Gateway):
            )
    def ensure_running(self) -> None:
        # 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)"
            )
        # 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.
@@ -215,12 +232,18 @@ class DockerGateway(Gateway):
        ]
        for port in self._host_port_bindings:
            argv += ["--publish", f"0.0.0.0:{port}:{port}"]
-        if self._orchestrator_url:
+        run_env = dict(os.environ)
-            # Makes the gateway's egress / git / supervise daemons multi-tenant:
+        # The gateway's egress / git / supervise daemons resolve source-IP ->
-            # each request resolves source-IP -> policy against the control plane.
+        # policy against the control plane per request (guaranteed non-empty by
-            argv += ["--env", f"BOT_BOTTLE_ORCHESTRATOR_URL={self._orchestrator_url}"]
+        # the check above).
        argv += ["--env", f"BOT_BOTTLE_ORCHESTRATOR_URL={self._orchestrator_url}"]
        # ...and present the control-plane secret on those /resolve calls (the
        # control plane requires it). Bare `--env NAME` keeps the value off argv
        # / `docker inspect`; only the gateway (not the agent) is given it.
        argv += ["--env", CONTROL_PLANE_TOKEN_ENV]
        run_env[CONTROL_PLANE_TOKEN_ENV] = host_control_plane_token()
        argv.append(self.image_ref)
-        proc = run_docker(argv)
+        proc = run_docker(argv, env=run_env)
        if proc.returncode != 0:
            raise GatewayError(f"gateway failed to start: {proc.stderr.strip()}")
@@ -1,17 +1,15 @@
 """Orchestrator + gateway lifecycle (PRD 0070, docker slice).
-Runs the orchestrator control plane **as a container** on the shared gateway
+Runs both the orchestrator control plane and the gateway data plane inside
-network, alongside the gateway container. This is the PRD's "virtualize the
+a single `bot-bottle-infra` container on the shared gateway network —
-orchestrator": container↔container between the gateway and the orchestrator
+matching the structure already used by the macOS and Firecracker backends.
-avoids the host firewall (which drops container→host traffic), and the gateway
+`gateway_init` is PID 1 and supervises both; the infra container is an
-reaches the control plane by container name over docker DNS. The host CLI
+idempotent per-host singleton.
 reaches it via a published loopback port.
-The orchestrator runs with the **register-only broker** — the *backend*
+The combined container replaces the prior two-container split
-launches agent containers (compose), so the orchestrator needs no docker
+(bot-bottle-orchestrator + bot-bottle-orch-gateway). The host CLI reaches
-socket. That keeps this control-plane container unprivileged; the host manages
+the control plane via a published loopback port; gateway daemons reach it
-both containers. `ensure_running` is an idempotent singleton (fixed container
+over 127.0.0.1 (same container).
 names + the published port).
 """
 from __future__ import annotations
@@ -25,50 +23,71 @@ from pathlib import Path
 from .. import log
 from ..docker_cmd import run_docker
-from ..paths import bot_bottle_root
+from ..paths import CONTROL_PLANE_TOKEN_ENV, bot_bottle_root, host_control_plane_token
-from .gateway import GATEWAY_IMAGE, GATEWAY_NETWORK, DockerGateway, GatewayError
+from ..supervise import DB_PATH_IN_CONTAINER
 from .gateway import (
    GATEWAY_CA_VOLUME,
    GATEWAY_DOCKERFILE,
    GATEWAY_IMAGE,
    GATEWAY_NETWORK,
    GatewayError,
    MITMPROXY_HOME,
    _host_db_dir,
 )
 DEFAULT_PORT = 8099
-ORCHESTRATOR_NAME = "bot-bottle-orchestrator"
+DEFAULT_STARTUP_TIMEOUT_SECONDS = 45.0
-ORCHESTRATOR_LABEL = "bot-bottle-orchestrator=1"
+
-# The control-plane's own runtime image — lean (python + the stdlib-only
+INFRA_NAME = "bot-bottle-infra"
-# `bot_bottle` package, bind-mounted at run time), distinct from the heavy
+INFRA_LABEL = "bot-bottle-infra=1"
-# gateway data-plane image it used to borrow (#384). Env override for
+# The combined infra image: gateway data plane + orchestrator content.
-# operators pinning a published build.
+# Built from Dockerfile.infra (FROM gateway + COPY --from orchestrator).
 INFRA_IMAGE = os.environ.get("BOT_BOTTLE_INFRA_IMAGE", "bot-bottle-infra:latest")
 INFRA_DOCKERFILE = "Dockerfile.infra"
 # Baked as a container label so `ensure_running` can detect whether the
 # running container is executing the current bind-mounted source.
 INFRA_SOURCE_HASH_LABEL = "bot-bottle-infra-source-hash"
 # Orchestrator image: the single canonical definition of the control-plane
 # content (lean: python:3.12-slim + bot_bottle package, no mitmproxy/git).
 # Used as a build intermediate: `Dockerfile.infra` COPY --from this image.
 ORCHESTRATOR_IMAGE = os.environ.get(
    "BOT_BOTTLE_ORCHESTRATOR_IMAGE", "bot-bottle-orchestrator:latest"
 )
 ORCHESTRATOR_DOCKERFILE = "Dockerfile.orchestrator"
 # Baked onto the container as a label so `ensure_running` can tell whether the
 # running process is executing the *current* bind-mounted source — see
 # `_source_hash`.
 ORCHESTRATOR_SOURCE_HASH_LABEL = "bot-bottle-orchestrator-source-hash"
-# The repo root is bind-mounted into the control-plane container so
+# The gateway daemons + orchestrator the infra container runs.
-# `python -m bot_bottle.orchestrator` resolves the package (the orchestrator
+# BOT_BOTTLE_GATEWAY_DAEMONS listing `orchestrator` opts it in to
-# is stdlib-only, so the lean orchestrator image's python is enough).
+# gateway_init's supervise tree (see gateway_init._OPT_IN_DAEMONS).
-_REPO_ROOT = Path(__file__).resolve().parents[2]
+_INFRA_DAEMONS = "egress,git-http,supervise,orchestrator"
-_APP_DIR = "/app"
+
 # The bind-mount path for the live control-plane source inside the
 # container. Separate from /app so the gateway's baked scripts
 # (egress_addon.py, egress-entrypoint.sh) are not overlaid.
 _SRC_IN_CONTAINER = "/bot-bottle-src"
 # Bot-bottle host-root bind-mount inside the container (DB + state).
 _ROOT_IN_CONTAINER = "/bot-bottle-root"
 # The supervise daemon writes proposals into the host DB directory.
 _SUPERVISE_DB_DIR_IN_CONTAINER = os.path.dirname(DB_PATH_IN_CONTAINER)
 _HEALTH_POLL_SECONDS = 0.25
 DEFAULT_STARTUP_TIMEOUT_SECONDS = 45.0
 _HEALTH_REQUEST_TIMEOUT_SECONDS = 1.0
 _REPO_ROOT = Path(__file__).resolve().parents[2]
 class OrchestratorStartError(RuntimeError):
-    """The orchestrator container did not become healthy within the timeout."""
+    """The infra container did not become healthy within the timeout."""
-def _source_hash(repo_root: Path) -> str:
+def source_hash(repo_root: Path) -> str:
    """Content hash of the orchestrator's bind-mounted Python source (the
-    `bot_bottle` package the control-plane process imports). This only
+    `bot_bottle` package the control-plane process imports). Changes only
-    changes when the code that would actually run inside the container
+    when the code that would actually run changes — `ensure_running`
-    changes — `ensure_running` recreates the container on a mismatch and
+    recreates the container on a mismatch so a code change takes effect,
-    otherwise leaves a healthy one alone, so a bottle launch that isn't
+    but leaves a healthy up-to-date container alone to preserve in-memory
-    accompanied by a code change doesn't restart the process and drop every
+    egress tokens."""
    *other* active bottle's in-memory egress tokens (`Orchestrator._tokens`
    in `service.py`, never persisted to disk by design)."""
    h = hashlib.sha256()
    for path in sorted((repo_root / "bot_bottle").rglob("*.py")):
        h.update(str(path.relative_to(repo_root)).encode())
@@ -77,52 +96,37 @@ def _source_hash(repo_root: Path) -> str:
 class OrchestratorService:
-    """Manages the orchestrator control-plane container + the shared gateway.
+    """Manages the single per-host infra container (control plane + gateway).
    Callers only need `ensure_running()` + `url`.
-    `orchestrator_name` / `orchestrator_label` let backends run independent
+    `infra_name` / `infra_label` let backends run independent infra containers
-    orchestrators on the same host without name collisions (e.g. the
+    on the same host without name collisions (e.g. isolated integration tests
-    Firecracker backend uses `bot-bottle-fc-orchestrator` alongside the Docker
+    that can't share the production INFRA_NAME singleton)."""
    backend's `bot-bottle-orchestrator`). Subclass and override `_gateway()`
    to supply a backend-specific gateway variant."""
    def __init__(
        self,
        *,
        port: int = DEFAULT_PORT,
        network: str = GATEWAY_NETWORK,
-        image: str = ORCHESTRATOR_IMAGE,
+        image: str = INFRA_IMAGE,
        gateway_image: str = GATEWAY_IMAGE,
        repo_root: Path = _REPO_ROOT,
        host_root: Path | None = None,
-        orchestrator_name: str = ORCHESTRATOR_NAME,
+        infra_name: str = INFRA_NAME,
-        orchestrator_label: str = ORCHESTRATOR_LABEL,
+        infra_label: str = INFRA_LABEL,
    ) -> None:
        self.port = port
        self.network = network
        # Two distinct images (#384): `image` is the lean control-plane
        # runtime this container runs; `_gateway_image` is the heavy egress /
        # git-gate / supervise data plane the gateway container runs. They
        # were one conflated image before the split.
        self.image = image
        self._gateway_image = gateway_image
        self._repo_root = repo_root
        self._host_root = host_root or bot_bottle_root()
-        self._orchestrator_name = orchestrator_name
+        self._infra_name = infra_name
-        self._orchestrator_label = orchestrator_label
+        self._infra_label = infra_label
    @property
    def url(self) -> str:
        """Host-side control-plane URL (published loopback port)."""
        return f"http://127.0.0.1:{self.port}"
    @property
    def internal_url(self) -> str:
        """Control-plane URL as the gateway container reaches it — by name over
        docker DNS on the shared network. This is the gateway's
        BOT_BOTTLE_ORCHESTRATOR_URL."""
        return f"http://{self._orchestrator_name}:{self.port}"
    def is_healthy(self, *, timeout: float = _HEALTH_REQUEST_TIMEOUT_SECONDS) -> bool:
        try:
            with urllib.request.urlopen(f"{self.url}/health", timeout=timeout) as resp:
@@ -134,128 +138,129 @@ class OrchestratorService:
        proc = run_docker(["docker", "ps", "--filter", f"name=^/{name}$", "--format", "{{.Names}}"])
        return name in proc.stdout.split()
-    def _run_orchestrator_container(self, source_hash: str) -> None:
+    def _infra_source_current(self, current_hash: str) -> bool:
-        """Start the control-plane container (idempotent: clears a stale
+        """True iff the running infra container was started from the current
-        fixed-name container first). Register-only broker → no docker socket.
+        bind-mounted source. Mirrors the macOS backend's `_source_current`."""
-        Labels the container with `source_hash` so a later `ensure_running`
+        if not self._container_running(self._infra_name):
        can detect a real code change (see `_source_hash`)."""
        run_docker(["docker", "rm", "--force", self._orchestrator_name])
        proc = run_docker([
            "docker", "run", "--detach",
            "--name", self._orchestrator_name,
            "--label", self._orchestrator_label,
            "--label", f"{ORCHESTRATOR_SOURCE_HASH_LABEL}={source_hash}",
            "--network", self.network,
            # Host CLI reaches the control plane here; bound to loopback so it
            # is not exposed on the host's external interfaces.
            "--publish", f"127.0.0.1:{self.port}:{self.port}",
            "--volume", f"{self._repo_root}:{_APP_DIR}:ro",
            "--workdir", _APP_DIR,
            # Persist the registry DB on the host (sole-owner: only the
            # orchestrator opens bot-bottle.db).
            "--volume", f"{self._host_root}:{_ROOT_IN_CONTAINER}",
            "--env", f"BOT_BOTTLE_ROOT={_ROOT_IN_CONTAINER}",
            "--entrypoint", "python3",
            self.image,
            "-m", "bot_bottle.orchestrator",
            "--host", "0.0.0.0", "--port", str(self.port), "--broker", "stub",
        ])
        if proc.returncode != 0:
            raise OrchestratorStartError(
                f"orchestrator container failed to start: {proc.stderr.strip()}"
            )
    def _gateway(self) -> DockerGateway:
        return DockerGateway(
            self._gateway_image, network=self.network, orchestrator_url=self.internal_url
        )
    def _ensure_orchestrator_image(self) -> None:
        """Build the lean control-plane image from `Dockerfile.orchestrator`
        when it's missing (#384). Cheap — a `FROM python:*-slim` base with no
        deps to install, so the layer cache makes rebuilds a no-op. Unlike the
        gateway image this is build-if-missing, not build-every-time: the
        control plane bind-mounts its source, so a code change is caught by the
        source-hash recreate (below), not by an image rebuild."""
        if run_docker(["docker", "image", "inspect", self.image]).returncode == 0:
            return
        argv = ["docker", "build", "-t", self.image,
                "-f", str(self._repo_root / ORCHESTRATOR_DOCKERFILE),
                str(self._repo_root)]
        if os.environ.get("BOT_BOTTLE_NO_CACHE"):
            argv.insert(2, "--no-cache")
        proc = run_docker(argv)
        if proc.returncode != 0:
            raise GatewayError(
                f"orchestrator image build failed: {proc.stderr.strip()}"
            )
    def _orchestrator_source_current(self, current_hash: str) -> bool:
        """True iff the running orchestrator container was created from the
        *current* bind-mounted source. Mirrors `DockerGateway`'s
        image-staleness check, but by content hash rather than image id since
        the orchestrator runs bind-mounted source, not a built image."""
        if not self._container_running(self._orchestrator_name):
            return False
        proc = run_docker([
            "docker", "inspect", "--format",
-            "{{ index .Config.Labels \"" + ORCHESTRATOR_SOURCE_HASH_LABEL + "\" }}",
+            "{{ index .Config.Labels \"" + INFRA_SOURCE_HASH_LABEL + "\" }}",
-            self._orchestrator_name,
+            self._infra_name,
        ])
        if proc.returncode != 0:
-            return True  # can't compare -> don't churn a working container
+            return True  # can't compare → don't churn a working container
        return proc.stdout.strip() == current_hash
    def _ensure_network(self) -> None:
        if run_docker(["docker", "network", "inspect", self.network]).returncode == 0:
            return
        proc = run_docker(["docker", "network", "create", self.network])
        if proc.returncode != 0 and "already exists" not in proc.stderr:
            raise GatewayError(
                f"gateway network {self.network} failed to create: {proc.stderr.strip()}"
            )
    def _build_images(self) -> None:
        """Build the gateway base, the orchestrator intermediate, then the
        infra image. All are cache-aware: a no-op when nothing changed."""
        for tag, dockerfile in (
            (GATEWAY_IMAGE, GATEWAY_DOCKERFILE),
            (ORCHESTRATOR_IMAGE, ORCHESTRATOR_DOCKERFILE),
            (self.image, INFRA_DOCKERFILE),
        ):
            argv = ["docker", "build", "-t", tag,
                    "-f", str(self._repo_root / 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"{dockerfile} build failed: {proc.stderr.strip()}")
    def _run_infra_container(self, current_hash: str) -> None:
        """Start the combined infra container (idempotent: clears a stale
        fixed-name container first). Labels the container with `current_hash`
        so a later `ensure_running` can detect a real code change."""
        self._ensure_network()
        run_docker(["docker", "rm", "--force", self._infra_name])
        proc = run_docker([
            "docker", "run", "--detach",
            "--name", self._infra_name,
            "--label", self._infra_label,
            "--label", f"{INFRA_SOURCE_HASH_LABEL}={current_hash}",
            "--network", self.network,
            # Host CLI reaches the control plane here (loopback only).
            # gateway_init always starts the orchestrator on DEFAULT_PORT (8099)
            # inside the container; self.port is the host-side published port.
            "--publish", f"127.0.0.1:{self.port}:{DEFAULT_PORT}",
            # Persist the mitmproxy CA so it survives container recreation.
            "--volume", f"{GATEWAY_CA_VOLUME}:{MITMPROXY_HOME}",
            # Shared supervise DB (same file the operator reads over HTTP).
            "--volume", f"{_host_db_dir()}:{_SUPERVISE_DB_DIR_IN_CONTAINER}",
            "--env", f"SUPERVISE_DB_PATH={DB_PATH_IN_CONTAINER}",
            # Live control-plane source, mounted to a path that does not
            # overlay the gateway's baked /app scripts.
            "--volume", f"{self._repo_root}:{_SRC_IN_CONTAINER}:ro",
            # PYTHONPATH lets the orchestrator (and other Python daemons)
            # import the live source ahead of the installed package.
            "--env", f"PYTHONPATH={_SRC_IN_CONTAINER}",
            # Orchestrator registry DB on the host (sole writer: control plane).
            "--volume", f"{self._host_root}:{_ROOT_IN_CONTAINER}",
            "--env", f"BOT_BOTTLE_ROOT={_ROOT_IN_CONTAINER}",
            # Control-plane secret: required by the orchestrator (to enforce)
            # and by the gateway daemons (to present on /resolve calls).
            "--env", CONTROL_PLANE_TOKEN_ENV,
            # Gateway daemons reach the orchestrator over loopback at its
            # fixed internal port (DEFAULT_PORT), independent of self.port.
            "--env", f"BOT_BOTTLE_ORCHESTRATOR_URL=http://127.0.0.1:{DEFAULT_PORT}",
            # Opt the orchestrator into gateway_init's supervise tree.
            "--env", f"BOT_BOTTLE_GATEWAY_DAEMONS={_INFRA_DAEMONS}",
            self.image,
        ], env={**os.environ, CONTROL_PLANE_TOKEN_ENV: host_control_plane_token()})
        if proc.returncode != 0:
            raise OrchestratorStartError(
                f"infra container failed to start: {proc.stderr.strip()}"
            )
    def ensure_running(
        self, *, startup_timeout: float = DEFAULT_STARTUP_TIMEOUT_SECONDS,
    ) -> str:
-        """Ensure the control plane + shared gateway are up; return the host
+        """Ensure the infra container (control plane + gateway) is up; return
-        control-plane URL. Idempotent — a healthy control plane running
+        the host control-plane URL. Idempotent — a healthy container on current
-        current code and a running gateway are left untouched. Raises
+        source is left untouched. Raises `OrchestratorStartError` on timeout."""
-        `OrchestratorStartError` on timeout."""
+        self._build_images()
        gateway = self._gateway()
        gateway.ensure_built()  # rebuild the bundle image on a source change
        gateway.ensure_running()  # creates the shared network + (re)starts gateway
-        # Recreate the orchestrator container only when its bind-mounted
+        current_hash = source_hash(self._repo_root)
-        # source has actually changed since it started — its Python process
+        if self.is_healthy() and self._infra_source_current(current_hash):
        # loaded that code at startup and won't reload, so a stale container
        # would keep running OLD control-plane code. Recreating on *every*
        # launch (the prior behaviour) would drop every other active
        # bottle's in-memory egress tokens each time a new bottle starts,
        # since the orchestrator process holds them only in memory (#381).
        current_hash = _source_hash(self._repo_root)
        if self.is_healthy() and self._orchestrator_source_current(current_hash):
            return self.url
-        self._ensure_orchestrator_image()
+        log.info("starting infra container", context={"name": self._infra_name})
-        log.info(
+        self._run_infra_container(current_hash)
            "starting orchestrator container",
            context={"name": self._orchestrator_name},
        )
        self._run_orchestrator_container(current_hash)
        deadline = time.monotonic() + startup_timeout
        while time.monotonic() < deadline:
            if self.is_healthy():
-                log.info("orchestrator healthy", context={"url": self.url})
+                log.info("infra container healthy", context={"url": self.url})
                return self.url
            time.sleep(_HEALTH_POLL_SECONDS)
        raise OrchestratorStartError(
-            f"orchestrator at {self.url} did not become healthy within {startup_timeout:g}s"
+            f"infra container at {self.url} did not become healthy within {startup_timeout:g}s"
        )
    def stop(self) -> None:
-        """Remove the orchestrator + gateway containers (idempotent)."""
+        """Remove the infra container (idempotent)."""
-        run_docker(["docker", "rm", "--force", self._orchestrator_name])
+        run_docker(["docker", "rm", "--force", self._infra_name])
        self._gateway().stop()
 __all__ = [
    "OrchestratorService",
    "OrchestratorStartError",
-    "ORCHESTRATOR_NAME",
+    "INFRA_NAME",
    "INFRA_IMAGE",
    "INFRA_SOURCE_HASH_LABEL",
    "ORCHESTRATOR_IMAGE",
    "DEFAULT_PORT",
    "DEFAULT_STARTUP_TIMEOUT_SECONDS",
    "source_hash",
 ]
@@ -32,6 +32,7 @@ import hmac
 import secrets
 import sqlite3
 import time
 from collections.abc import Iterable
 from dataclasses import dataclass
 from pathlib import Path
@@ -42,6 +43,12 @@ from ..paths import host_db_path
 # 256 bits of urandom, URL-safe — unguessable per-bottle identity token.
 IDENTITY_TOKEN_BYTES = 32
 # How recently a row must have been registered to be exempt from
 # `reap_absent`. Covers the window between `container run` and the address
 # becoming visible to another launch's enumeration, so reconciliation never
 # reaps a bottle that is still coming up.
 DEFAULT_REAP_GRACE_SECONDS = 120.0
 def new_identity_token() -> str:
    """A fresh per-bottle identity token (PRD 0070 attribution defence)."""
@@ -167,7 +174,7 @@ class RegistryStore(DbStore):
            metadata=metadata,
            policy=policy,
        )
-        with self._connect() as conn:
+        with self._connection() as conn:
            conn.execute(
                "DELETE FROM orchestrator_bottles "
                "WHERE source_ip = ? AND state = 'active' AND bottle_id != ?",
@@ -193,7 +200,7 @@ class RegistryStore(DbStore):
    def set_policy(self, bottle_id: str, policy: str) -> bool:
        """Update a bottle's policy in place (live reload). Returns True if
        the bottle exists."""
-        with self._connect() as conn:
+        with self._connection() as conn:
            cur = conn.execute(
                "UPDATE orchestrator_bottles SET policy = ? WHERE bottle_id = ?",
                (policy, bottle_id),
@@ -203,7 +210,7 @@ class RegistryStore(DbStore):
    def deregister(self, bottle_id: str) -> bool:
        """Remove a bottle. Returns True if a row was deleted."""
-        with self._connect() as conn:
+        with self._connection() as conn:
            cur = conn.execute(
                "DELETE FROM orchestrator_bottles WHERE bottle_id = ?", (bottle_id,)
            )
@@ -211,7 +218,7 @@ class RegistryStore(DbStore):
    def get(self, bottle_id: str) -> BottleRecord | None:
        """Return the bottle by id, or None if absent."""
-        with self._connect() as conn:
+        with self._connection() as conn:
            row = conn.execute(
                "SELECT * FROM orchestrator_bottles WHERE bottle_id = ?", (bottle_id,)
            ).fetchone()
@@ -219,12 +226,76 @@ class RegistryStore(DbStore):
    def all(self) -> list[BottleRecord]:
        """Every registered bottle, oldest first."""
-        with self._connect() as conn:
+        with self._connection() as conn:
            rows = conn.execute(
                "SELECT * FROM orchestrator_bottles ORDER BY created_at"
            ).fetchall()
        return [_row_to_record(r) for r in rows]
    def reap_absent(
        self,
        live_source_ips: Iterable[str],
        *,
        grace_seconds: float = DEFAULT_REAP_GRACE_SECONDS,
        now: float | None = None,
    ) -> list[BottleRecord]:
        """Delete active rows whose source IP is not held by a live bottle.
        A row only ever leaves the registry two ways: an explicit
        `teardown_bottle` (the launcher's cleanup callback) or the supersede
        sweep in `register`. Neither runs when the launching CLI dies hard —
        SIGKILL, a closed terminal, a host sleep/crash — so the row outlives
        its container. That orphan is not inert: source IPs are recycled by
        the backend's DHCP, and `by_source_ip` fail-closes on ambiguity, so a
        leftover row at a reused address can brick the *next* bottle that
        lands on it (no policy resolved -> every host denied, reported to the
        agent as "not in the allowlist"). Reconciling against the live set at
        launch keeps the registry from accumulating those landmines.
        Restores the invariant the data plane needs: **at most one active row
        per live address, and none at all for a dead one.** Two cases, because
        a dead bottle's address may already have been handed to a live one:
          * no live bottle holds the address — every row there is an orphan;
          * a live bottle holds it but several rows claim it — the newest
            registration is authoritative and the rest are orphans, the same
            rule `register`'s same-IP supersede sweep applies. Without this
            second case a recycled address stays ambiguous, which is exactly
            the state that resolves no policy.
        `grace_seconds` protects an in-flight launch: registration happens
        moments after `container run`, and a concurrent launch's address may
        not be visible to the caller's enumeration yet. Rows younger than the
        grace window are never reaped, so reconciliation can't race a bottle
        that is still coming up. Returns the deleted records."""
        live = {ip for ip in live_source_ips if ip}
        cutoff = (time.time() if now is None else now) - grace_seconds
        with self._connection() as conn:
            rows = conn.execute(
                "SELECT * FROM orchestrator_bottles WHERE state = 'active'",
            ).fetchall()
            by_ip: dict[str, list[BottleRecord]] = {}
            for row in rows:
                rec = _row_to_record(row)
                by_ip.setdefault(rec.source_ip, []).append(rec)
            candidates: list[BottleRecord] = []
            for ip, recs in by_ip.items():
                if ip not in live:
                    candidates.extend(recs)
                    continue
                # Keep the newest claim on a live address; supersede the rest.
                recs.sort(key=lambda r: r.created_at)
                candidates.extend(recs[:-1])
            doomed = [r for r in candidates if r.created_at <= cutoff]
            for rec in doomed:
                conn.execute(
                    "DELETE FROM orchestrator_bottles WHERE bottle_id = ?",
                    (rec.bottle_id,),
                )
        if doomed:
            self._chmod()
        return doomed
    def by_source_ip(self, source_ip: str) -> BottleRecord | None:
        """Network-layer attribution: the single active bottle at this source
        IP, or None if unknown or ambiguous (more than one — a
@@ -232,7 +303,7 @@ class RegistryStore(DbStore):
        source IP is unspoofable (Firecracker `/31` + nft) and the control
        plane is reachable only by the trusted gateway; pair with the
        identity token (`attribute`) elsewhere."""
-        with self._connect() as conn:
+        with self._connection() as conn:
            rows = conn.execute(
                "SELECT * FROM orchestrator_bottles "
                "WHERE source_ip = ? AND state = 'active'",
@@ -262,4 +333,5 @@ __all__ = [
    "new_identity_token",
    "default_db_path",
    "IDENTITY_TOKEN_BYTES",
    "DEFAULT_REAP_GRACE_SECONDS",
 ]
@@ -13,15 +13,20 @@ Launch lifecycle:
    and returns the record. If the broker rejects/fails, the registry entry
    is rolled back so a failed launch leaves no orphan.
  * `teardown_bottle` sends a signed teardown request, then deregisters.
  * `reconcile` sweeps rows whose bottle is no longer running — the
    self-heal for the teardown paths that never got to run (a hard-killed
    launcher), since an orphan row at a recycled source IP bricks the next
    bottle that lands on it.
 """
 from __future__ import annotations
 import json
 from collections.abc import Iterable
 from datetime import datetime, timezone
 from .broker import LaunchBroker, LaunchRequest, sign_request
-from .registry import BottleRecord, RegistryStore
+from .registry import DEFAULT_REAP_GRACE_SECONDS, BottleRecord, RegistryStore
 from .gateway import Gateway
 from ..supervise import (
    AuditEntry,
@@ -117,6 +122,30 @@ class Orchestrator:
        self._tokens.pop(bottle_id, None)
        return True
    def reconcile(
        self,
        live_source_ips: Iterable[str],
        *,
        grace_seconds: float = DEFAULT_REAP_GRACE_SECONDS,
    ) -> list[str]:
        """Drop registry rows for bottles that are no longer running, and
        forget their in-memory egress tokens. Returns the reaped bottle ids.
        The caller supplies the live set because only the host can enumerate
        its own containers — the orchestrator runs *inside* the infra
        container and has no view of the backend. Deliberately does not
        broker a teardown: the container is already gone, so there is nothing
        to stop, and a broker error must not stop the sweep from clearing
        the row that would otherwise brick the next bottle at that address.
        See `RegistryStore.reap_absent` for why orphans accumulate and why
        they are harmful rather than merely untidy."""
        reaped = self.registry.reap_absent(
            live_source_ips, grace_seconds=grace_seconds)
        for rec in reaped:
            self._tokens.pop(rec.bottle_id, None)
        return [rec.bottle_id for rec in reaped]
    def tokens_for(self, bottle_id: str) -> dict[str, str]:
        """The bottle's in-memory egress auth tokens (env_name -> value), or
        empty. The gateway injects these per request; they are never
@@ -16,6 +16,8 @@ layer (and to COPY flat into the gateway).
 from __future__ import annotations
 import os
 import secrets
 import stat
 from pathlib import Path
 # The single shared host state DB. All bot-bottle SQLite stores (supervise
@@ -23,6 +25,14 @@ from pathlib import Path
 # TableMigrations schema_key namespaces each store's tables.
 HOST_DB_FILENAME = "bot-bottle.db"
 # The per-host control-plane secret file, and the env var the launchers inject
 # its value into. The control plane requires this secret on every mutating /
 # reading route (see orchestrator/control_plane.py); it is held only by the
 # trusted callers (control plane, gateway, host CLI) and never handed to an
 # agent, so an agent that can reach the control-plane port still can't drive it.
 CONTROL_PLANE_TOKEN_FILENAME = "control-plane-token"
 CONTROL_PLANE_TOKEN_ENV = "BOT_BOTTLE_CONTROL_PLANE_TOKEN"
 def bot_bottle_root() -> Path:
    """The app data root — `$BOT_BOTTLE_ROOT` if set, else `~/.bot-bottle`."""
@@ -40,4 +50,52 @@ def host_db_path() -> Path:
    return bot_bottle_root() / "db" / HOST_DB_FILENAME
-__all__ = ["HOST_DB_FILENAME", "bot_bottle_root", "host_db_path"]
+def host_db_dir() -> Path:
    """The directory holding the shared host state DB, created if missing.
    Backends bind-mount this into their gateway so the supervise daemon writes
    to the one DB the orchestrator (and the operator over HTTP) reads."""
    db_dir = host_db_path().parent
    db_dir.mkdir(parents=True, exist_ok=True)
    return db_dir
 def host_control_plane_token() -> str:
    """The per-host control-plane secret, minted (256-bit, url-safe) and
    persisted 0600 on first use, then reused.
    This is the shared secret the launchers inject into the control-plane and
    gateway containers and that the host CLI presents on every call. It is a
    *host* artifact — the file lives under the root the agent never mounts, and
    the env var is set only on the trusted containers — so reading it here is
    safe on the host launch path but the value never reaches a bottle."""
    path = bot_bottle_root() / CONTROL_PLANE_TOKEN_FILENAME
    try:
        existing = path.read_text().strip()
        if existing:
            return existing
    except OSError:
        pass
    path.parent.mkdir(parents=True, exist_ok=True)
    token = secrets.token_urlsafe(32)
    # Create 0600 up front (O_EXCL loses a concurrent race harmlessly — we
    # re-read the winner's token below) so the secret is never briefly world-
    # readable between write and chmod.
    try:
        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
    except FileExistsError:
        return path.read_text().strip()
    with os.fdopen(fd, "w") as f:
        f.write(token)
    os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
    return token
 __all__ = [
    "HOST_DB_FILENAME",
    "CONTROL_PLANE_TOKEN_FILENAME",
    "CONTROL_PLANE_TOKEN_ENV",
    "bot_bottle_root",
    "host_db_path",
    "host_db_dir",
    "host_control_plane_token",
 ]
@@ -22,18 +22,35 @@ closed too rather than silently serving stale or empty policy.
 The resolved value is the policy blob the orchestrator stores verbatim; the
 consumer parses it (e.g. the egress addon's `load_config`). This module is
-stdlib-only and free of bot-bottle imports so it can be COPYed flat into
+stdlib-only and free of bot-bottle imports.
 the gateway.
 """
 from __future__ import annotations
 import json
 import os
 import urllib.error
 import urllib.request
 DEFAULT_TIMEOUT_SECONDS = 2.0
 # The control-plane secret this gateway presents on every /resolve call, read
 # from the env the launcher injects into the gateway container. The control
 # plane requires it (orchestrator/control_plane.py). Constant + env-var name are
 # duplicated here rather than imported because this module is COPYed flat into
 # the gateway image, free of bot-bottle imports — same rationale as
 # IDENTITY_HEADER in egress_addon / git_http_backend.
 CONTROL_AUTH_HEADER = "x-bot-bottle-control-auth"
 CONTROL_PLANE_TOKEN_ENV = "BOT_BOTTLE_CONTROL_PLANE_TOKEN"
 def _control_auth_headers() -> dict[str, str]:
    """The auth header to send, or {} when no secret is configured (an open
    control plane, e.g. Firecracker behind its nft boundary — sending nothing
    is correct there and harmlessly ignored)."""
    token = os.environ.get(CONTROL_PLANE_TOKEN_ENV, "").strip()
    return {CONTROL_AUTH_HEADER: token} if token else {}
 class PolicyResolveError(RuntimeError):
    """The orchestrator was unreachable or returned an unexpected status —
@@ -57,7 +74,7 @@ class PolicyResolver:
        ).encode()
        req = urllib.request.Request(
            f"{self._base}/resolve", data=body, method="POST",
-            headers={"Content-Type": "application/json"},
+            headers={"Content-Type": "application/json", **_control_auth_headers()},
        )
        try:
            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
@@ -66,7 +66,7 @@ class QueueStore(DbStore):
        super().__init__(resolved, migrations)
    def write_proposal(self, proposal: Proposal) -> Path:
-        with self._connect() as conn:
+        with self._connection() as conn:
            conn.execute(
                """
                INSERT OR REPLACE INTO supervise_proposals (
@@ -89,7 +89,7 @@ class QueueStore(DbStore):
        return self.db_path
    def read_proposal(self, proposal_id: str) -> Proposal:
-        with self._connect() as conn:
+        with self._connection() as conn:
            row = conn.execute(
                """
                SELECT * FROM supervise_proposals
@@ -104,7 +104,7 @@ class QueueStore(DbStore):
    def list_pending_proposals(self) -> list[Proposal]:
        if not self.db_path.is_file():
            return []
-        with self._connect() as conn:
+        with self._connection() as conn:
            rows = conn.execute(
                """
                SELECT p.* FROM supervise_proposals p
@@ -125,7 +125,7 @@ class QueueStore(DbStore):
    def list_all_pending_proposals(self) -> list[Proposal]:
        if not self.db_path.is_file():
            return []
-        with self._connect() as conn:
+        with self._connection() as conn:
            rows = conn.execute(
                """
                SELECT p.* FROM supervise_proposals p
@@ -142,7 +142,7 @@ class QueueStore(DbStore):
        return [self._row_to_proposal(row) for row in rows]
    def write_response(self, response: Response) -> Path:
-        with self._connect() as conn:
+        with self._connection() as conn:
            conn.execute(
                """
                INSERT OR REPLACE INTO supervise_responses (
@@ -161,7 +161,7 @@ class QueueStore(DbStore):
        return self.db_path
    def read_response(self, proposal_id: str) -> Response:
-        with self._connect() as conn:
+        with self._connection() as conn:
            row = conn.execute(
                """
                SELECT * FROM supervise_responses
@@ -176,7 +176,7 @@ class QueueStore(DbStore):
    def archive_proposal(self, proposal_id: str) -> None:
        if not self.db_path.is_file():
            return
-        with self._connect() as conn:
+        with self._connection() as conn:
            conn.execute(
                """
                UPDATE supervise_proposals SET archived = 1
@@ -37,40 +37,23 @@ from abc import ABC
 from dataclasses import dataclass
 from pathlib import Path
-try:
+from .supervise_types import (
-    from .supervise_types import (
+    ACTION_OPERATOR_EDIT,
-        ACTION_OPERATOR_EDIT,
+    AuditEntry,
-        AuditEntry,
+    Proposal,
-        Proposal,
+    Response,
-        Response,
+    STATUSES,
-        STATUSES,
+    STATUS_APPROVED,
-        STATUS_APPROVED,
+    STATUS_MODIFIED,
-        STATUS_MODIFIED,
+    STATUS_REJECTED,
-        STATUS_REJECTED,
+    TOOLS,
-        TOOLS,
+    TOOL_CHECK_PROPOSAL,
-        TOOL_EGRESS_ALLOW,
+    TOOL_EGRESS_ALLOW,
-        TOOL_EGRESS_BLOCK,
+    TOOL_EGRESS_BLOCK,
-        TOOL_EGRESS_TOKEN_ALLOW,
+    TOOL_EGRESS_TOKEN_ALLOW,
-        TOOL_GITLEAKS_ALLOW,
+    TOOL_GITLEAKS_ALLOW,
-        TOOL_LIST_EGRESS_ROUTES,
+    TOOL_LIST_EGRESS_ROUTES,
-    )
+)
 except ImportError:
    from supervise_types import (  # type: ignore[import-not-found,no-redef]  # pylint: disable=import-error,no-name-in-module
        ACTION_OPERATOR_EDIT,
        AuditEntry,
        Proposal,
        Response,
        STATUSES,
        STATUS_APPROVED,
        STATUS_MODIFIED,
        STATUS_REJECTED,
        TOOLS,
        TOOL_EGRESS_ALLOW,
        TOOL_EGRESS_BLOCK,
        TOOL_EGRESS_TOKEN_ALLOW,
        TOOL_GITLEAKS_ALLOW,
        TOOL_LIST_EGRESS_ROUTES,
    )
 try:
@@ -281,6 +264,7 @@ __all__ = [
    "TOOLS",
    "EGRESS_FORWARD_PROXY",
    "EGRESS_INTROSPECT_URL",
    "TOOL_CHECK_PROPOSAL",
    "TOOL_EGRESS_ALLOW",
    "TOOL_EGRESS_BLOCK",
    "TOOL_GITLEAKS_ALLOW",
@@ -2,37 +2,44 @@
 Per-bottle MCP server exposing tools the agent calls to propose egress
 config changes when stuck. The tools are `egress-allow`,
-`egress-block`, and `list-egress-routes`.
+`egress-block`, `list-egress-routes`, and `check-proposal`.
-Each queued tool call:
+Each queued proposal tool call:
  1. Validates the proposed file syntactically.
  2. Writes a Proposal to the host SQLite database.
-  3. Blocks polling for a matching Response row.
+  3. Blocks polling for a matching Response row, up to a short grace
-  4. Returns the operator's `{status, notes}` to the agent.
+     window (`SUPERVISE_RESPONSE_TIMEOUT_SECONDS`, default 30s).
  4. On a decision within the window, returns the operator's
     `{status, notes}`. On timeout, returns `status: pending` **with the
     proposal id** and leaves the proposal queued — the flow is
     non-blocking past the grace window (PRD prd-new / issue #412).
-The bottle slug arrives via SUPERVISE_BOTTLE_SLUG env (stamped at
+`check-proposal` is the non-blocking companion: given a `proposal_id`
-container creation by the backend's start step). SUPERVISE_DB_PATH
+returned by a `pending` response, it reports the current decision
 (`pending` | `approved` | `modified` | `rejected`) without re-proposing,
 so an approval made out-of-band (e.g. a web review console) can be resumed
 without holding an HTTP request open.
 One shared server fronts every bottle (PRD 0070) and attributes each
 proposal to the calling bottle by source IP, resolved from the orchestrator
 — an unattributed or unreachable source fails closed. BOT_BOTTLE_ORCHESTRATOR_URL
 is mandatory: there is no fixed-slug single-tenant fallback. SUPERVISE_DB_PATH
 points at the bind-mounted host database.
 Consolidated (PRD 0070): when BOT_BOTTLE_ORCHESTRATOR_URL is set, one
 shared server fronts every bottle and attributes each proposal to the
 calling bottle by source IP (resolved from the orchestrator) instead of a
 fixed slug — an unattributed source fails closed. Unset → the legacy
 per-bottle single-tenant server, unchanged.
 Speaks MCP over HTTP+JSON-RPC. Methods handled:
  * `initialize`           — handshake; returns server info + caps.
  * `notifications/initialized` — ack-only.
  * `tools/list`           — returns the tool definitions.
-  * `tools/call`           — validates, queues, blocks, returns.
+  * `tools/call`           — validates, queues, waits out the grace
                             window, returns (pending past it); or, for
                             `check-proposal`, a non-blocking status poll.
 Everything else returns JSON-RPC error -32601 (method not found).
-Stdlib-only. The Dockerfile copies this file + bot_bottle/supervise.py
+The Dockerfile copies this script to /app/supervise_server.py and installs
-into the image; the server imports `supervise` for the queue / Proposal
+the bot_bottle package so its `from bot_bottle.*` imports resolve.
 plumbing.
 """
 from __future__ import annotations
@@ -44,33 +51,20 @@ import socketserver
 import sys
 import time
 import typing
 import urllib.error
 import urllib.request
 from dataclasses import dataclass, replace
-try:
+from bot_bottle.constants import IDENTITY_HEADER
-    # Same-directory imports inside the bundle container; these files are
+from bot_bottle.egress_addon_core import (
-    # COPYed flat under /app by Dockerfile.gateway.
+    LOG_OFF, load_config, resolve_client_context, route_to_yaml_dict,
-    from egress_addon_core import (
+)
-        LOG_OFF, load_config, resolve_client_context, route_to_yaml_dict,
+from bot_bottle.policy_resolver import PolicyResolveError, PolicyResolver
-    )
+from bot_bottle import supervise as _sv
    from policy_resolver import PolicyResolveError, PolicyResolver
    import supervise as _sv
 except ModuleNotFoundError:
    # Package imports for host-side tests and tooling.
    from .egress_addon_core import (
        LOG_OFF, load_config, resolve_client_context, route_to_yaml_dict,
    )
    from .policy_resolver import PolicyResolveError, PolicyResolver
    from . import supervise as _sv
 # --- JSON-RPC / MCP plumbing ----------------------------------------------
 MCP_PROTOCOL_VERSION = "2024-11-05"
 # App-layer identity token header (mirrors egress_addon / git_http_backend).
 IDENTITY_HEADER = "x-bot-bottle-identity"
 SERVER_NAME = "bot-bottle-supervise"
 SERVER_VERSION = "0.1.0"
@@ -85,12 +79,10 @@ ERR_INTERNAL = -32603
 DEFAULT_RESPONSE_TIMEOUT_SECONDS = 30.0
 MIN_RESPONSE_POLL_INTERVAL_SECONDS = 0.05
 EGRESS_LIST_TIMEOUT_SECONDS = 5.0
-# Consolidated (multi-tenant) mode: when set, one shared supervise server
+# The per-host orchestrator control plane the shared supervise server attributes
-# fronts every bottle and attributes each proposal to the calling bottle by
+# each proposal to, by source IP. Mandatory — there is no single-tenant
-# source IP (resolved from the orchestrator), instead of a single
+# SUPERVISE_BOTTLE_SLUG fallback.
 # SUPERVISE_BOTTLE_SLUG env. Unset → legacy per-bottle single-tenant.
 ORCHESTRATOR_URL_ENV = "BOT_BOTTLE_ORCHESTRATOR_URL"
@@ -252,6 +244,31 @@ TOOL_DEFINITIONS: list[dict[str, object]] = [
        ),
        "inputSchema": _proposal_input_schema(),
    },
    {
        "name": _sv.TOOL_CHECK_PROPOSAL,
        "description": (
            "Poll a previously queued proposal for the operator's decision "
            "WITHOUT blocking or re-proposing. Pass the `proposal_id` you "
            "got back when an `egress-allow`/`egress-block` call returned "
            "`status: pending`. Returns the current status: `pending` (no "
            "decision yet — poll again later), `approved`, `modified`, "
            "`rejected`, or `unknown` (no such queued proposal — wrong id, "
            "or it was already resolved and read)."
        ),
        "inputSchema": {
            "type": "object",
            "properties": {
                "proposal_id": {
                    "type": "string",
                    "description": (
                        "The proposal id from a `pending` response."
                    ),
                },
            },
            "required": ["proposal_id"],
            "additionalProperties": False,
        },
    },
 ]
@@ -310,42 +327,6 @@ def handle_tools_list(_params: dict[str, object]) -> dict[str, object]:
    return {"tools": TOOL_DEFINITIONS}
 def handle_list_egress_routes(
    _params: dict[str, object],
    _config: ServerConfig,
 ) -> dict[str, object]:
    """Fetch the live egress route table via its
    `_egress.local/allowlist` introspection endpoint. The
    request goes through egress as a forward proxy; the
    addon recognises the magic host and synthesizes a response —
    no real upstream connection, no allowlist enforcement
    against the magic host. Returns the JSON payload as the
    tool's text content."""
    proxy_handler = urllib.request.ProxyHandler({
        "http": _sv.EGRESS_FORWARD_PROXY,
    })
    opener = urllib.request.build_opener(proxy_handler)
    try:
        with opener.open(_sv.EGRESS_INTROSPECT_URL, timeout=EGRESS_LIST_TIMEOUT_SECONDS) as resp:
            body = resp.read().decode("utf-8")
    except (urllib.error.URLError, OSError) as e:
        return {
            "content": [{
                "type": "text",
                "text": (
                    f"list-egress-routes: could not reach "
                    f"{_sv.EGRESS_INTROSPECT_URL!r} via "
                    f"{_sv.EGRESS_FORWARD_PROXY!r}: {e}"
                ),
            }],
            "isError": True,
        }
    return {
        "content": [{"type": "text", "text": body}],
        "isError": False,
    }
 def handle_tools_call(
    params: dict[str, object],
    config: ServerConfig,
@@ -353,14 +334,13 @@ def handle_tools_call(
    """Validates the proposal, writes it to the queue, blocks waiting
    for a Response, returns the result wrapped in MCP `content`.
-    Side-effect-free `list-*` tools short-circuit before the queue/
+    `list-egress-routes` never reaches here — the handler answers it from
-    blocking machinery — they're read-only introspection that
+    the calling bottle's resolved policy before dispatching (see
-    doesn't need operator approval."""
+    `MCPHandler._dispatch`); this path is the queued, operator-approved
    `egress-allow` / `egress-block` tools."""
    name = params.get("name")
    if not isinstance(name, str):
        raise _RpcClientError(ERR_INVALID_PARAMS, "tools/call missing 'name'")
    if name == _sv.TOOL_LIST_EGRESS_ROUTES:
        return handle_list_egress_routes(typing.cast(dict[str, object], params.get("arguments", {})), config)
    args_raw = params.get("arguments", {})
    if not isinstance(args_raw, dict):
@@ -410,7 +390,7 @@ def handle_tools_call(
            deadline=deadline,
        )
    except TimeoutError:
-        text = format_pending_response_text(config.response_timeout_seconds)
+        text = format_pending_response_text(proposal.id, config.response_timeout_seconds)
        return {
            "content": [{"type": "text", "text": text}],
            "isError": False,
@@ -427,6 +407,54 @@ def handle_tools_call(
    }
 def handle_check_proposal(
    params: dict[str, object],
    config: ServerConfig,
 ) -> dict[str, object]:
    """Non-blocking poll of a queued proposal's decision, by id.
    Never creates a Proposal (so `check-proposal` isn't in `TOOLS`); it only
    reads the queue. Resolution order mirrors the synchronous path's terminal
    step — a decided proposal is archived here exactly as `handle_tools_call`
    archives it after `wait_for_response`, so `pending` proposals stay visible
    to the operator until they're both decided *and* polled."""
    args_raw = params.get("arguments", {})
    if not isinstance(args_raw, dict):
        raise _RpcClientError(ERR_INVALID_PARAMS, "tools/call 'arguments' must be an object")
    proposal_id = args_raw.get("proposal_id")
    if not isinstance(proposal_id, str) or not proposal_id.strip():
        raise _RpcClientError(
            ERR_INVALID_PARAMS,
            "check-proposal: 'proposal_id' is required and must be a non-empty string",
        )
    proposal_id = proposal_id.strip()
    try:
        response = _sv.read_response(config.bottle_slug, proposal_id)
    except FileNotFoundError:
        # No decision yet — distinguish "still queued" from "unknown id".
        try:
            _sv.read_proposal(config.bottle_slug, proposal_id)
        except FileNotFoundError:
            return {
                "content": [{"type": "text", "text": format_unknown_proposal_text(proposal_id)}],
                "isError": True,
            }
        return {
            "content": [{"type": "text", "text": format_still_pending_text(proposal_id)}],
            "isError": False,
        }
    try:
        _sv.archive_proposal(config.bottle_slug, proposal_id)
    except OSError as e:
        raise _RpcInternalError(f"failed to archive proposal: {e}") from e
    return {
        "content": [{"type": "text", "text": format_response_text(response)}],
        "isError": response.status == _sv.STATUS_REJECTED,
    }
 def format_response_text(response: "_sv.Response") -> str:
    """Pretty-print a Response for the tool's text content. The agent
    reads the text and decides whether to retry / give up / surface."""
@@ -439,12 +467,35 @@ def format_response_text(response: "_sv.Response") -> str:
    return "\n".join(lines)
-def format_pending_response_text(timeout_seconds: float) -> str:
+def format_pending_response_text(proposal_id: str, timeout_seconds: float) -> str:
    """Grace-window timeout: the proposal stays queued, and the agent is
    told the id so it can `check-proposal` instead of re-proposing."""
    return "\n".join([
        "status: pending",
        f"proposal_id: {proposal_id}",
        (
-            "notes: operator response timed out after "
+            f"notes: no operator decision within {timeout_seconds:g}s; the "
-            f"{timeout_seconds:g}s; proposal remains queued"
+            "proposal remains queued. Poll it (do not re-propose) by calling "
            f"`check-proposal` with proposal_id={proposal_id!r}."
        ),
    ])
 def format_still_pending_text(proposal_id: str) -> str:
    return "\n".join([
        "status: pending",
        f"proposal_id: {proposal_id}",
        "notes: still queued; no operator decision yet. Call `check-proposal` again later.",
    ])
 def format_unknown_proposal_text(proposal_id: str) -> str:
    return "\n".join([
        "status: unknown",
        f"proposal_id: {proposal_id}",
        (
            "notes: no queued proposal with this id for this bottle — the id "
            "may be wrong, or the proposal was already resolved and read."
        ),
    ])
@@ -531,36 +582,40 @@ class MCPHandler(http.server.BaseHTTPRequestHandler):
        if method == "tools/list":
            return handle_tools_list(req.params)
        if method == "tools/call":
-            # `list-egress-routes` is read-only introspection. In consolidated
+            # `list-egress-routes` is read-only introspection. The shared gateway
-            # mode the gateway's *static* route table is empty (routes are
+            # has no static route table (routes are resolved per request by
-            # resolved per request by source IP), so answer it from the calling
+            # source IP), so answer it from the calling bottle's resolved policy.
-            # bottle's resolved policy. Otherwise the agent sees an empty
+            # Otherwise the agent sees an empty allowlist and composes an egress
-            # allowlist and composes an egress proposal that *replaces* the live
+            # proposal that *replaces* the live routes instead of extending them
-            # routes instead of extending them — silently dropping base routes
+            # — silently dropping base routes like api.anthropic.com on approval.
            # like api.anthropic.com when the operator approves it.
            if req.params.get("name") == _sv.TOOL_LIST_EGRESS_ROUTES:
-                resolved = self._resolved_routes_payload()
+                return self._resolved_routes_payload()
-                if resolved is not None:
+            # `check-proposal` is a non-blocking read of the calling bottle's
-                    return resolved
+            # own queue — attributed by source IP like a proposal, but it
-            # Attribute the proposal to the calling bottle. Single-tenant → the
+            # never queues or blocks.
-            # env slug on `config`; consolidated → the source-IP-resolved
+            if req.params.get("name") == _sv.TOOL_CHECK_PROPOSAL:
-            # bottle id, so one shared server queues each bottle's proposal
+                return handle_check_proposal(req.params, self._attributed_config(config))
-            # under its own slug.
+            # Attribute the proposal to the source-IP-resolved bottle, so the one
            # shared server queues each bottle's proposal under its own slug.
            return handle_tools_call(req.params, self._attributed_config(config))
        raise _RpcClientError(ERR_METHOD_NOT_FOUND, f"method not found: {method}")
-    def _resolved_routes_payload(self) -> dict[str, object] | None:
+    def _resolver_or_fail(self) -> "PolicyResolver":
-        """The calling bottle's live egress routes as the `list-egress-routes`
+        """This server's policy resolver. A server started without one is a
-        JSON payload, resolved by (source_ip, identity token) — the same shape
+        misconfiguration, not a tenancy mode — fail closed rather than
-        the single-tenant introspection endpoint returns. None when there is no
+        attribute (or list) anything."""
        resolver (single-tenant), so the caller falls back to that endpoint.
        Fail-closed like `_attributed_config`: an unattributed source or an
        unreachable orchestrator yields an empty route list (never another
        bottle's), courtesy of `resolve_client_context`."""
        resolver = getattr(self.server, "policy_resolver", None)
        if resolver is None:
-            return None
+            raise _RpcInternalError("supervise server has no policy resolver")
        return resolver
    def _resolved_routes_payload(self) -> dict[str, object]:
        """The calling bottle's live egress routes as the `list-egress-routes`
        JSON payload, resolved by (source_ip, identity token). Fail-closed like
        `_attributed_config`: an unattributed source or an unreachable
        orchestrator yields an empty route list (never another bottle's),
        courtesy of `resolve_client_context`."""
        resolver = self._resolver_or_fail()
        headers = getattr(self, "headers", None)
        token = headers.get(IDENTITY_HEADER, "") if headers is not None else ""
        conf, _slug, _tokens = resolve_client_context(
@@ -572,14 +627,11 @@ class MCPHandler(http.server.BaseHTTPRequestHandler):
        return {"content": [{"type": "text", "text": body}], "isError": False}
    def _attributed_config(self, config: ServerConfig) -> ServerConfig:
-        """The ServerConfig with `bottle_slug` bound to *this request's* bottle.
+        """The ServerConfig with `bottle_slug` bound to *this request's* bottle:
-        Single-tenant (no resolver): unchanged. Consolidated: the bottle id
+        the bottle id attributed from the source IP — **fail-closed**, an
-        attributed from the source IP — **fail-closed**, an unattributed or
+        unattributed or unreachable source raises so no proposal is queued under
-        unreachable source raises so no proposal is queued under the wrong (or
+        the wrong (or empty) slug."""
-        empty) slug."""
+        resolver = self._resolver_or_fail()
        resolver = getattr(self.server, "policy_resolver", None)
        if resolver is None:
            return config
        # The agent's MCP client sends the identity token as a request header
        # (provisioned via `mcp add --header`); the orchestrator requires the
        # (source_ip, token) pair, so a missing/wrong token fail-closes below.
@@ -616,8 +668,9 @@ class MCPServer(socketserver.ThreadingMixIn, http.server.HTTPServer):
    allow_reuse_address = True
    daemon_threads = True
    config: ServerConfig = ServerConfig(bottle_slug="")
-    # None → single-tenant (proposals use config.bottle_slug); set → consolidated
+    # Set by `serve`; every proposal is attributed to the source-IP-resolved
-    # (each proposal attributed to the source-IP-resolved bottle).
+    # bottle. The class default is a placeholder — a server without a resolver
    # fails closed per request (see `_resolver_or_fail`).
    policy_resolver: "PolicyResolver | None" = None
@@ -626,21 +679,21 @@ class MCPServer(socketserver.ThreadingMixIn, http.server.HTTPServer):
 def serve(
    *,
-    bottle_slug: str,
+    resolver: "PolicyResolver",
    port: int = _sv.SUPERVISE_PORT,
    bind: str = "0.0.0.0",
    response_timeout_seconds: float = DEFAULT_RESPONSE_TIMEOUT_SECONDS,
    resolver: "PolicyResolver | None" = None,
 ) -> typing.NoReturn:
    server = MCPServer((bind, port), MCPHandler)
    # bottle_slug is a placeholder: every request's proposal is attributed to
    # the source-IP-resolved bottle (see MCPHandler._attributed_config).
    server.config = ServerConfig(
-        bottle_slug=bottle_slug,
+        bottle_slug="",
        response_timeout_seconds=response_timeout_seconds,
    )
    server.policy_resolver = resolver
    mode = "multi-tenant" if resolver else f"slug={bottle_slug!r}"
    sys.stderr.write(
-        f"supervise listening on {bind}:{port}; {mode}; "
+        f"supervise listening on {bind}:{port}; multi-tenant; "
        f"tools: {', '.join(t['name'] for t in TOOL_DEFINITIONS)}\n"  # type: ignore[arg-type]
    )
    sys.stderr.flush()
@@ -656,12 +709,13 @@ def serve(
 def main(argv: list[str]) -> int:
    del argv  # config is env-only, no CLI flags
    orch_url = os.environ.get(ORCHESTRATOR_URL_ENV, "").strip()
-    resolver = PolicyResolver(orch_url) if orch_url else None
+    if not orch_url:
-    bottle_slug = os.environ.get("SUPERVISE_BOTTLE_SLUG", "")
+        # Resolver-only: without an orchestrator the server can't attribute a
-    # Consolidated mode resolves the slug per request, so the env slug is
+        # proposal to a bottle, so it must not serve (fail-closed).
-    # optional there; single-tenant still requires it.
+        sys.stderr.write(
-    if not bottle_slug and resolver is None:
+            f"supervise: {ORCHESTRATOR_URL_ENV} is required "
-        sys.stderr.write("supervise: SUPERVISE_BOTTLE_SLUG env is unset\n")
+            "(no single-tenant SUPERVISE_BOTTLE_SLUG fallback)\n"
        )
        return 2
    port = int(os.environ.get("SUPERVISE_PORT", str(_sv.SUPERVISE_PORT)))
    bind = os.environ.get("SUPERVISE_BIND", "0.0.0.0")
@@ -671,11 +725,10 @@ def main(argv: list[str]) -> int:
        sys.stderr.write(f"supervise: {e}\n")
        return 2
    serve(
-        bottle_slug=bottle_slug,
+        resolver=PolicyResolver(orch_url),
        port=port,
        bind=bind,
        response_timeout_seconds=response_timeout_seconds,
        resolver=resolver,
    )
    return 0  # serve() does not return
@@ -20,6 +20,10 @@ TOOL_EGRESS_ALLOW = "egress-allow"
 TOOL_GITLEAKS_ALLOW = "gitleaks-allow"
 TOOL_EGRESS_TOKEN_ALLOW = "egress-token-allow"
 TOOL_LIST_EGRESS_ROUTES = "list-egress-routes"
 # Read-only agent tool: poll a queued proposal for the operator's decision
 # without blocking or re-proposing. It never becomes a `Proposal.tool` (no
 # queue record is created for it), so it is intentionally NOT in `TOOLS`.
 TOOL_CHECK_PROPOSAL = "check-proposal"
 TOOLS: tuple[str, ...] = (
    TOOL_EGRESS_ALLOW,
    TOOL_EGRESS_BLOCK,
@@ -156,6 +160,7 @@ __all__ = [
    "TOOLS",
    "TOOL_EGRESS_ALLOW",
    "TOOL_EGRESS_BLOCK",
    "TOOL_CHECK_PROPOSAL",
    "TOOL_EGRESS_TOKEN_ALLOW",
    "TOOL_GITLEAKS_ALLOW",
    "TOOL_LIST_EGRESS_ROUTES",
@@ -7,6 +7,7 @@ from __future__ import annotations
 import ipaddress
 import os
 import sys
 def is_ip_literal(value: str) -> bool:
@@ -17,6 +18,15 @@ def is_ip_literal(value: str) -> bool:
    return True
 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")
 def expand_tilde(path: str) -> str:
    """Expand a leading '~' to $HOME. Leaves paths without a leading
    tilde unchanged. Falls back to the empty string if $HOME is unset
@@ -0,0 +1,57 @@
 # ADR 0005: Keep tracker metadata on issues
 - **Status:** Accepted
 - **Date:** 2026-07-18
 - **Deciders:** didericis
 ## Context
 Gitea exposes labels on both issues and pull requests. Applying the same labels
 to both copies planning metadata, creates a synchronization obligation, and
 makes disagreements between the two records possible. At the same time,
 unlabelled objects look accidental unless the repository states which object
 owns the metadata.
 The repository already uses issues as work items and PRs as implementations of
 those work items. At this decision's cutoff, all open PRs reference issues, but
 121 of 219 historically merged PRs do not. Manufacturing retrospective issues
 for that history would create records that never participated in planning and
 would make the issue history less truthful.
 ## Decision
 Issues are the canonical tracker records and own labels. Every issue has at
 least one label. An issue opened or left without labels receives
 `Status/Needs Triage` automatically until it is classified.
 Pull requests carry no labels. Every new PR deliberately references at least
 one existing issue in its title or description with one of these forms:
 - `Closes #123`, `Fixes #123`, or `Resolves #123` when merging completes it.
 - `Part of #123`, `Related to #123`, `Refs #123`, or `References #123` when it
  contributes without completing it.
 Gitea Actions enforces both PR rules as a status check and repairs the empty
 issue-label state. Branch protection makes the PR policy check required.
 The policy applies from 2026-07-18 onward. Existing issues may be labelled as
 they are encountered, but closed PRs are grandfathered: no retrospective
 issues or PR labels are created solely to make history conform.
 ## Consequences
 - Classification, priority, and workflow metadata have one source of truth.
 - A PR's issue link is the navigation path to its planning metadata.
 - Multi-PR issues do not require copied or synchronized labels.
 - `Status/Needs Triage` is an intentional fallback, not a final
  classification.
 - Direct issue creation remains convenient; automation repairs a missing label
  immediately after creation because Gitea has no native required-label rule.
 - The required check must be configured in branch protection after this
  workflow lands.
 ## Links
 - Issue #405.
 - `.gitea/workflows/tracker-policy.yml`.
 - `scripts/tracker_policy.py`.
@@ -1,6 +1,6 @@
 # PRD 0023: smolmachines bottle backend
-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis
@@ -1,6 +1,6 @@
 # PRD 0032: Decompose smolmachines launch and harden bringup sequencing
-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis-claude
@@ -1,6 +1,6 @@
 # PRD 0038: smolmachines Env Contract and Secret-Safe Injection
-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis-codex
@@ -1,6 +1,6 @@
 # PRD 0039: smolmachines Capability-Block Remediation
-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis-codex
@@ -1,6 +1,6 @@
 # PRD 0042: smolmachines Cross-Backend Parity Tests
-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis-codex
@@ -1,6 +1,6 @@
 # PRD 0057: Promote smolmachines to default backend; convert Docker to example-only
-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis
@@ -1,6 +1,6 @@
 # PRD 0068: smolmachines backend on Linux
-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** Claude
@@ -112,12 +112,12 @@ bottle-agnostic**: the per-boot bits (authorized_keys, guest IP) arrive on the
 published ext4 boots on any launch host.
 - **Artifact.** `rootfs.ext4` + a `rootfs.ext4.sha256`, published as a Gitea
-  **generic package** (`bot-bottle-infra/<tag>`) — generic packages take
+  **generic package** (`bot-bottle-firecracker-infra/<tag>`) — generic packages take
  arbitrary large binaries (no attachment size cap / file-type allowlist that
  release attachments impose). The matching `vmlinux` kernel can ship the same
  way, so the whole VM is fetchable.
 - **Pull.** The launch host `GET`s
-  `…/api/packages/<owner>/generic/bot-bottle-infra/<tag>/rootfs.ext4` (+
+  `…/api/packages/<owner>/generic/bot-bottle-firecracker-infra/<tag>/rootfs.ext4` (+
  `.sha256`) for its pinned tag, verifies the checksum, caches it under the
  tag, and attaches it as the infra VM's root disk. Host prerequisite is an
  HTTP client — nothing else. Public packages need no auth to pull; a token
@@ -0,0 +1,146 @@
 # PRD prd-new: Claude forward_host_credentials
 - **Status:** Draft
 - **Author:** claude
 - **Created:** 2026-07-01
 - **Issue:** #325
 ## Summary
 Add `agent_provider.forward_host_credentials: true` support for the
 `claude` template, mirroring the existing Codex flow. When enabled,
 bot-bottle reads the host's Claude OAuth session key from
 `~/.claude/.credentials.json` at launch, forwards it only to the egress sidecar,
 and injects a placeholder `CLAUDE_CODE_OAUTH_TOKEN` into the agent so
 Claude Code starts without ever seeing the real credential.
 ## Problem
 Running a Claude agent in a container today requires the operator to
 manually extract a long-lived OAuth token (`claude setup-token`), export
 it as `BOT_BOTTLE_CLAUDE_OAUTH_TOKEN`, and reference it explicitly in
 the manifest with `agent_provider.auth_token:
 "BOT_BOTTLE_CLAUDE_OAUTH_TOKEN"`. This is a two-step manual ceremony
 that is easy to skip or do incorrectly.
 The host already stores a valid Claude session in `~/.claude/.credentials.json`
 after `claude login`. Codex already automates an
 equivalent extraction from `~/.codex/auth.json`. There is no reason
 Claude bottles cannot do the same.
 ## Goals / Success Criteria
 - A Claude bottle with `forward_host_credentials: true` in the manifest
  uses the host's `~/.claude/.credentials.json` session key at launch with no
  additional operator steps.
 - The agent container receives only `CLAUDE_CODE_OAUTH_TOKEN=egress-placeholder`
  — never the real token.
 - The real session key lives only in the egress sidecar's environment.
 - Missing, malformed, or expired host Claude auth fails launch with a
  clear operator-facing message.
 - Existing `auth_token` behavior is unchanged.
 - `forward_host_credentials: true` is rejected in the manifest when both
  `auth_token` and `forward_host_credentials` are set, since they serve
  the same purpose.
 ## Non-goals
 - Refreshing Claude OAuth tokens in the sidecar.
 - Writing a dummy `~/.claude.json` auth state to the agent (unlike the
  Codex flow, Claude Code reads its credential from `CLAUDE_CODE_OAUTH_TOKEN`
  in env, not from an auth file — no guest-side auth marker is needed).
 - Supporting `forward_host_credentials` for providers other than `codex`
  and `claude`.
 ## Design
 ### Manifest schema
 ```yaml
 agent_provider:
  template: claude
  forward_host_credentials: true
 ```
 Rejects in manifest validation when:
 - Template is not `codex` or `claude`.
 - Both `auth_token` and `forward_host_credentials` are set.
 ### Host auth extraction (`contrib/claude/claude_auth.py`)
 Claude Code credential storage varies by platform:
 - **Linux**: `~/.claude/.credentials.json`
 - **macOS**: macOS Keychain, service `"Claude Code-credentials"`
  (the file path is tried first; Keychain is the fallback when the file
  is absent)
 `~/.claude.json` contains only UI state and profile metadata — no token.
 The credentials JSON schema (same whether from file or Keychain):
 ```json
 {
  "claudeAiOauth": {
    "accessToken": "<access-token>",
    "refreshToken": "<refresh-token>",
    "expiresAt": 1748276587173,
    "scopes": ["user:inference", "user:profile"]
  }
 }
 ```
 `expiresAt` is in **milliseconds** (not seconds).
 At prepare/launch time, when `forward_host_credentials: true`:
 1. Try `~/.claude/.credentials.json`; on macOS, if absent, run
   `security find-generic-password -s "Claude Code-credentials" -w`
   and parse its stdout as JSON.
 2. Require a `claudeAiOauth` dict.
 3. Require a non-empty `claudeAiOauth.accessToken` string.
 4. If `claudeAiOauth.expiresAt` is present, divide by 1000 and require
   the result to be in the future.
 5. Return only the access token to the launch path.
 Errors name the missing or invalid condition and point the operator at
 `claude login`, without printing token values.
 ### Egress route
 When `forward_host_credentials: true`:
 - Provision the session key in `provisioned_env` under
  `BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN` (new constant in `egress.py`).
 - Set up the `api.anthropic.com` egress route with `auth_scheme: Bearer`
  and `token_ref: BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN`.
 - Set `CLAUDE_CODE_OAUTH_TOKEN=egress-placeholder` in the agent env and
  add it to `hidden_env_names`.
 No dummy auth file and no `verify` step are needed — Claude Code reads
 the credential from the env var, not from a file.
 ### Constants
 - `CLAUDE_HOST_CREDENTIAL_TOKEN_REF = "BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN"`
  in `egress.py` (alongside the existing `CODEX_HOST_CREDENTIAL_TOKEN_REF`).
 - `CLAUDE_HOST_CREDENTIAL_HOSTS = ("api.anthropic.com",)` in
  `agent_provider.py` (alongside the existing `CODEX_HOST_CREDENTIAL_HOSTS`).
 ### Data flow
 ```
 Host ~/.claude/.credentials.json  →  bot-bottle launch
                            │
                            ├──► egress sidecar env (real token only)
                            │
                            └──► agent env: CLAUDE_CODE_OAUTH_TOKEN=egress-placeholder
 Agent  →  HTTPS to api.anthropic.com (via egress)
 Egress →  injects Authorization: Bearer <real token>
 Egress →  forwards to api.anthropic.com
 ```
 ## Open questions
 None — the Codex precedent makes the design clear.
@@ -0,0 +1,156 @@
 # PRD prd-new: Consolidate infra backend for Docker
 - **Status:** Active
 - **Author:** Claude
 - **Created:** 2026-07-20
 - **Issue:** #431
 ## Summary
 The Docker backend runs two containers — `bot-bottle-orch-gateway` (gateway
 data plane) and `bot-bottle-orchestrator` (control plane) — where the
 macOS and Firecracker backends already run a single combined infra
 unit. This PRD collapses Docker to the same model: one `bot-bottle-infra`
 container running both processes under the `gateway_init` supervise tree, a
 restructured `Dockerfile.infra` as the shared gateway+orchestrator base,
 and a handful of extracted shared utilities (CA cert polling, teardown
 sequence, launch skeleton) that are currently duplicated across all three
 `consolidated_launch.py` files.
 ## Goals / success criteria
 - Docker backend starts exactly one infra container instead of two.
 - `Dockerfile.infra` is the shared base image (gateway + orchestrator, no
  buildah); the Firecracker image layers buildah on top of it.
 - The orchestrator process runs under the `gateway_init` supervise tree
  inside the combined container (one PID-1, one restart/health surface).
 - CA cert polling, the teardown sequence, and the shared launch skeleton
  (ensure-infra → register → provision → return context) live in a single
  shared module; all three backends import from it.
 - No functional change to macOS or Firecracker launch paths.
 ## Non-goals
 - Changing per-bottle isolation — agents stay one-VM/container-each.
 - Consolidating transport implementations (`DockerGatewayTransport`,
  `AppleGatewayTransport`, `SshGatewayTransport`) — these are already the
  right abstraction boundary.
 - macOS DHCP-inversion of registration order — irreducible backend
  difference, stays as-is.
 - Any changes to the orchestrator RPC protocol or the attribution model.
 ## Design
 ### Dockerfile restructuring
 **Current shape:**
 - `Dockerfile.gateway` — data plane (mitmproxy, gitleaks, git, openssh,
  supervise daemons)
 - `Dockerfile.orchestrator` — control plane (python:3.12-slim + bot_bottle
  package; stdlib-only, no third-party deps)
 - `Dockerfile.infra` — Firecracker only: `FROM bot-bottle-gateway` +
  buildah + `COPY --from bot-bottle-orchestrator`
 **New shape:**
 - `Dockerfile.gateway` — unchanged
 - `Dockerfile.orchestrator` — unchanged (single definition of orchestrator
  content; both Docker infra and Firecracker infra `COPY --from` it)
 - `Dockerfile.infra` — **shared base**: `FROM bot-bottle-gateway` + `COPY
  --from bot-bottle-orchestrator` (no buildah — Docker infra image)
 - `Dockerfile.infra.fc` — Firecracker only: `FROM bot-bottle-infra` +
  buildah/crun/netavark/aardvark-dns (layered on the shared base, same net
  result as today)
 The comment in `Dockerfile.infra` that says "the docker backend keeps
 orchestrator + gateway as separate images; this combined image exists only
 for the Firecracker single-VM cut" is removed.
 ### Orchestrator in the supervise tree
 `gateway_init` already supervises the data-plane daemons (egress, git-http,
 supervise-MCP). The orchestrator control plane is added as another supervised
 process: `python3 -m bot_bottle.orchestrator --host 0.0.0.0 --port <port>
 --broker stub`.
 The orchestrator source is bind-mounted (`/app` → repo root, as today) so
 dev live-reload still works. `source_hash`-based container recreation in
 `OrchestratorService.ensure_running` continues to apply — a code change
 recreates the combined infra container, which bounces both gateway and
 orchestrator. This is acceptable: the docker backend is a dev/legacy target
 where in-flight egress connections across a code deploy are not a hard
 requirement.
 ### `OrchestratorService` changes
 `OrchestratorService` currently starts two containers in sequence: gateway
 first (`DockerGateway.ensure_running`), then orchestrator. After this PRD:
 - Single `docker run` of `bot-bottle-infra:latest`
 - Container name: `bot-bottle-infra` (replaces `bot-bottle-orch-gateway` +
  `bot-bottle-orchestrator`)
 - Published ports: `127.0.0.1:{host_port}:8099` for the control plane
  (`gateway_init` listens on a fixed internal port 8099; the caller-chosen
  host port maps to it)
 - Bind mounts: repo root + host root (same as today)
 - `DockerGateway` becomes an implementation detail of `OrchestratorService`
  rather than a separately started container; the gateway image name
  (`GATEWAY_IMAGE`) is no longer referenced at runtime, only at build time
  for the `Dockerfile.infra` base
 The `_gateway()` / `ensure_running` two-step in `OrchestratorService` is
 replaced by a single `_run_infra_container()`.
 ### Shared backend utilities
 Three items are duplicated across
 `backend/docker/consolidated_launch.py`,
 `backend/macos_container/consolidated_launch.py`, and
 `backend/firecracker/consolidated_launch.py`:
 1. **CA cert polling loop** — `deadline = time.monotonic() + timeout; while
   ...: try fetch CA; sleep` — extracted to
   `backend/consolidated_util.py:poll_ca_cert(transport, *, timeout)`.
 2. **Teardown sequence** — `OrchestratorClient(url).teardown_bottle(id)` +
   `deprovision_git_gate(transport, id)` — extracted to
   `backend/consolidated_util.py:teardown_consolidated(url, transport,
   bottle_id)`.
 3. **Launch skeleton** — all three follow: ensure-infra → allocate/register
   → provision git-gate → fetch CA cert → return launch context. The macOS
   inversion (agent starts before registration, source IP from DHCP) is the
   only deviation. Extract a shared `_provision_bottle(transport, bottle_id,
   plan, orchestrator_url)` helper covering the register → provision →
   return-token steps; the backends keep their own `launch_consolidated`
   wrappers for the before/after (infra-ensure + agent-start + IP
   allocation), calling the shared helper.
 The new `backend/consolidated_util.py` module holds only backend-neutral,
 transport-agnostic logic. All three backends import from it.
 ## Implementation chunks
 1. **(this PR)** Dockerfile restructuring: rename current `Dockerfile.infra`
   content to `Dockerfile.infra.fc`; write new `Dockerfile.infra` as
   gateway+orchestrator base. Update Firecracker image-build references from
   `Dockerfile.infra` → `Dockerfile.infra.fc`.
 2. Add orchestrator process to `gateway_init` supervise tree.
 3. Collapse `OrchestratorService` to a single-container start; rename
   container from `bot-bottle-orch-gateway`/`bot-bottle-orchestrator` →
   `bot-bottle-infra`; update image name constant.
 4. Extract `backend/consolidated_util.py` with `poll_ca_cert`,
   `teardown_consolidated`, and `_provision_bottle`; update all three
   `consolidated_launch.py` files to import from it.
 5. Update tests that reference the old container names or two-container
   startup sequence.
 ## Open questions
 None — the supervise-tree approach and shared Dockerfile layering were
 confirmed in issue #431.
@@ -0,0 +1,125 @@
 # PRD prd-new: Non-blocking supervise (async approval + proposal polling)
 - **Status:** Draft
 - **Author:** didericis
 - **Created:** 2026-07-18
 - **Issue:** #412
 ## Summary
 The per-bottle supervise MCP server (`bot_bottle/supervise_server.py`)
 answers `tools/call` **synchronously**: it queues the agent's proposal and
 blocks the tool call polling for the operator's decision. On timeout it
 returns `status: pending` and leaves the proposal queued — but it hands the
 agent **no proposal id** and offers **no way to poll a specific pending
 proposal**, so the only way to learn the outcome is to re-propose (a
 duplicate).
 This PRD makes the MCP flow non-blocking and pollable, so an approval can
 happen out-of-band (a human taking minutes-to-hours in a review console)
 without holding an HTTP request open or wedging the agent:
 1. Include the `proposal_id` in the `pending` response.
 2. Add a `check-proposal` MCP tool: a non-blocking status lookup by
   proposal id.
 3. Keep the short synchronous grace window for the common "operator is
   right there" fast path.
 ## Problem
 `handle_tools_call` → `_sv.wait_for_response(...)` blocks up to
 `SUPERVISE_RESPONSE_TIMEOUT_SECONDS` (default 30s). Two problems follow:
 - **Human latency ≠ tool-call latency.** A real review — rendered diff,
  RBAC routing to an approver, someone tapping approve on their phone — is
  minutes-to-hours. Holding the MCP request open that long is fragile
  (proxy/keepalive timeouts, the mitmproxy egress hop, and the agent
  harness's own tool-call timeout, which a long block can trip and stall
  the whole turn).
 - **No resume path.** The pending fallback already exists, but without a
  proposal id and a poll tool the agent can't reconnect to that specific
  decision — it re-proposes, duplicating the queue entry.
 This is also the precondition for the planned web-console human-review
 flow (RBAC, audit retention, mobile) — see issue #412.
 **Safety note:** the MCP tools only *propose* policy changes; enforcement
 stays at the egress proxy and the git-gate. Returning early on `pending`
 therefore opens no hole — the agent still cannot egress or push anything
 unapproved.
 ## Goals / success criteria
 - A `pending` MCP response carries the `proposal_id`.
 - An agent can call `check-proposal(proposal_id)` and get the current
  state (`pending` | `approved` | `modified` | `rejected`) **without
  blocking** and **without creating a new proposal**.
 - The synchronous fast path (operator approves within the grace window) is
  unchanged: the first `tools/call` still returns the decision directly.
 - No change to enforcement, attribution (source-IP → bottle), or the
  operator-side queue/response schema.
 ## Non-goals
 - The git-gate `pre-receive` path (it is synchronous by nature and cannot
  poll — its async variant is reject-fast + re-push; tracked as a
  follow-up).
 - Backpressure / in-flight-proposal caps.
 - MCP server→client notifications (event-driven resume).
 - Any web-console UI (this PRD is the protocol groundwork it needs).
 ## Design
 ### `pending` response carries the id
 `handle_tools_call`'s timeout branch formats the pending text with the
 `proposal.id` and a pointer to `check-proposal`, so the agent knows what to
 poll.
 ### `check-proposal` tool
 A new read-only MCP tool (`TOOL_CHECK_PROPOSAL = "check-proposal"`),
 attributed to the calling bottle by source IP exactly like the proposal
 tools. Input: `{ "proposal_id": string }`. Behavior:
 1. `read_response(slug, id)` →
   - **found**: archive the proposal (same terminal step the synchronous
     path takes) and return the decision via `format_response_text`;
     `isError` iff rejected.
 2. **not found** → `read_proposal(slug, id)` →
   - **found**: still queued → return `status: pending`.
   - **not found**: unknown id, or already resolved-and-archived (e.g. a
     second poll) → return `status: unknown`, `isError: true`.
 Both lookups already raise `FileNotFoundError` when absent
 (`queue_store.py`), so the handler needs no new store methods. `check-`
 `proposal` is the only path (besides the synchronous response) that
 archives, so a proposal that times out to `pending` stays visible to the
 operator until it is decided and then polled.
 ### Grace window
 Left at the existing 30s default (`SUPERVISE_RESPONSE_TIMEOUT_SECONDS`),
 which doubles as the instant-approve fast path. Tuning it down is an
 operator setting, not a code change; noted for the console rollout.
 ## Implementation chunks
 1. **(this PR)** `TOOL_CHECK_PROPOSAL` constant; `check-proposal` tool
   definition + `handle_check_proposal`; dispatch wiring; `proposal_id` in
   the pending text; unit tests. Files: `bot_bottle/supervise_types.py`,
   `bot_bottle/supervise.py` (re-export), `bot_bottle/supervise_server.py`,
   `tests/unit/test_supervise_server.py`.
 2. **(follow-up)** git-gate `pre-receive` reject-fast + re-push.
 3. **(follow-up)** per-bottle in-flight-proposal backpressure cap.
 4. **(follow-up)** MCP notifications for event-driven resume; web-console
   review flow (RBAC, audit retention) on top.
 ## Open questions
 - Should a resolved-but-unpolled proposal auto-archive after some TTL, or
  only on poll? (Leaning: only on poll, so a decision is never lost to a
  reaper before the agent sees it.)
 - Does the agent harness need an explicit "you have a pending proposal"
  nudge, or is returning `pending` from the original call enough? (Deferred
  to the notifications chunk.)
@@ -1,32 +1,81 @@
 # Landscape: AI-agent sandbox tools
-A broader survey than [`landscape-containerized-claude.md`](landscape-containerized-claude.md),
+Survey of AI-agent sandbox and containment projects — including local
-which focused on Claude-Code-specific containerizers. This one covers
+coding-agent wrappers, agent-agnostic runtimes, hosted platforms, and
-general AI-agent sandbox / containment projects — some Claude-specific,
+governance layers — contrasted with bot-bottle's design. The original
-some agent-agnostic, some hosted SaaS — and contrasts them with
+Claude-Code-specific containerizer survey was folded into this note on
-bot-bottle's design.
+2026-07-20 so there is one landscape and one positioning verdict.
-Research conducted 2026-05-11.
+Research conducted 2026-05-11. CubeSandbox added 2026-07-18 (see its
 per-project note and the addendum at the end). Also updated 2026-07-18:
 bot-bottle no longer uses **pipelock** — outbound DLP is now bot-bottle's
 own (deliberately simple) egress scanner (a mitmproxy addon with custom
 detectors, PRD 0017 / 0052), and git-push secret scanning is handled by
 **gitleaks** in the git-gate. "pipelock" below has been replaced with the
 current mechanism; it survives only in older PRDs as history.
 Updated again 2026-07-18: six additional tools added (Cleanroom,
 container-use, Docker sbx, Anthropic srt, Microsoft AGT, Open Agent
 Passport); an **Agent-tailored policy** row added to the comparison table;
 a separate Governance layers section added for AGT and OAP. See the
 second addendum at the end.
 Updated 2026-07-20: the borrowable-ideas status was reconciled with the
 current implementation. In-flight credential injection and the microVM
 backends have shipped, while per-use SSH confirmation was superseded by
 keeping git credentials out of the agent entirely.
 Also updated 2026-07-20: **E2B and Daytona added as first-class entries.**
 Earlier revisions mentioned E2B only as the API and lifecycle model that
 CubeSandbox implements, and omitted Daytona entirely. That was a survey gap,
 not a principled scope exclusion: both are major hosted sandbox platforms and
 belong in this landscape even though they target platform builders rather than
 bot-bottle's local single-operator workflow.
 ## Summary
-Eight projects surveyed. None duplicate bot-bottle's combination of
+The main table compares bot-bottle against fifteen isolation/sandbox tools.
-local Docker, declarative JSON manifest, per-agent egress allowlist via
+Governance/pre-action authorization and credential-only layers are covered
-pipelock, and bottle/agent split. Two clusters stand out:
+separately because they don't provide VM or container isolation. None
 duplicate bot-bottle's combination of local
 VM-per-bottle isolation, a declarative per-role manifest, per-agent
 egress allowlist + outbound-content DLP, bottle/agent split, and the
 composable `extends:` policy model. Three clusters stand out:
 - **Closest neighbours** — agent-safehouse and litterbox: local,
  single-user, thin wrappers over an existing OS primitive
  (`sandbox-exec`, Podman + Landlock).
- **Different category** — tilde.run (hosted SaaS), boxlite and
+- **Different category (isolation)** — tilde.run (hosted SaaS), boxlite
-  microsandbox (microVM libraries for platform builders), endo-familiar
+  and microsandbox (microVM libraries for platform builders), E2B and Daytona
  (hosted sandbox platforms), CubeSandbox (self-hosted multi-tenant microVM
  service), endo-familiar
  (capability-security paradigm, no OS isolation).
 - **New: governance/pre-action layers** — Microsoft AGT and Open Agent
  Passport (OAP): framework-embedded tool-call interceptors with
  per-agent declarative policy. Closest competitors on agent-tailored
  policy, but operate at the tool-call level rather than providing
  network/filesystem isolation; they complement rather than substitute.
-The microVM cluster (matchlock, smolmachines, boxlite, microsandbox) is
+The microVM cluster (matchlock, smolmachines, boxlite, microsandbox,
-the most relevant for the v2 isolation discussion in
+CubeSandbox) is the most relevant for the v2 isolation discussion in
 [`stronger-isolation-alternatives.md`](stronger-isolation-alternatives.md):
 libkrun and Apple's Virtualization.framework have made local microVMs
-ergonomic enough that a `"runtime": "microvm"` option on a bottle is now
+ergonomic enough that microVMs are **now bot-bottle's default backend**
-plausible without a heavy stack.
+(Firecracker on KVM Linux, Apple Container on macOS), with Docker kept
 only as a legacy fallback for CI / hosts without KVM or Apple Container.
 That discussion has since shipped, not just been theorized.
 **The one that matters most for positioning is CubeSandbox** — it ships
 bot-bottle's bundle of default-deny egress allowlisting, full audit logs, and
 in-flight credential custody *combined with* per-sandbox microVM isolation,
 open-source under Apache 2.0, with Tencent Cloud behind it and 10.4k
 stars. It's a self-hosted multi-tenant service for platform builders, not
 a single-user declarative tool, so it doesn't collide head-on — but it
 narrows the "nobody else bundles egress custody + credential injection"
 claim that the monetization positioning leans on. Daytona now also offers
 domain/CIDR firewall policy plus in-flight header credential substitution and
 response scrubbing, although its higher tiers are not default-deny and its
 production platform is proprietary. See the addendum.
 ## Per-project notes
@@ -63,7 +112,8 @@ plausible without a heavy stack.
 ### agent-safehouse
 - **Source**: https://agent-safehouse.dev/ ; https://github.com/eugene1g/agent-safehouse
- **License**: Apache 2.0 (~1,400 stars)
+- **HN launch**: [#47301085](https://news.ycombinator.com/item?id=47301085) (March 12 2026) — 823 points
 - **License**: Apache 2.0 (~1,781 stars at launch)
 - **Isolation**: macOS `sandbox-exec` (Seatbelt) profiles — kernel-level
  syscall interception, no container.
 - **Locality**: Local, macOS only.
@@ -73,6 +123,16 @@ plausible without a heavy stack.
 - **Config**: Shell functions or custom `sandbox-exec` profile files;
  LLM-assisted profile generation supported.
 - **Network policy**: Not addressed.
 - **Notable from HN thread**: Creator acknowledged the project is "just a
  policy-generator for `sandbox-exec` — no dependencies, no daemons, no
  subscription; I did put in many hours to identify the minimum required
  permissions for agents to continue working." Simon Willison noted that
  evaluating whether a sandboxing tool actually works as intended is hard.
  Top community sentiment: *"I honestly think that sandboxing is currently
  THE major challenge that needs to be solved for the tech to fully realise
  its potential."* The macOS Docker gap (Docker for Mac runs inside a Linux
  VM, so `sandbox-exec` is the only native primitive for bare-metal macOS
  processes) was the stated motivation.
 - **Maturity**: Active through March 2026.
 ### matchlock
@@ -155,73 +215,474 @@ plausible without a heavy stack.
  also supported.
 - **Maturity**: Active through April 2026.
 ### E2B *(added 2026-07-20)*
 - **Source**: https://github.com/e2b-dev/e2b ; https://e2b.dev/docs
 - **License**: Apache 2.0 (~12.4k stars); commercial hosted service with
  self-hosting/BYOC support.
 - **Isolation**: Firecracker microVM per sandbox.
 - **Locality**: Cloud-hosted by default; self-hosting uses Terraform on AWS or
  GCP (with other targets documented as works in progress).
 - **Agent integration**: LLM-agnostic Python and JavaScript/TypeScript SDKs;
  code-interpreter and desktop-sandbox products. Platform primitive rather
  than a coding-agent wrapper.
 - **Config**: Programmatic SDK/API plus templates. Network configuration
  supports internet on/off, outbound allow/deny rules, and a custom egress
  proxy.
 - **Network policy**: Configurable per sandbox, but not documented as
  default-deny and no built-in outbound-content DLP is documented.
 - **Credentials**: Environment variables passed to the sandbox are explicitly
  not private at the OS level. No built-in in-flight application-credential
  injection is documented.
 - **Persistence**: Full memory + filesystem pause/resume, snapshots, and
  auto-resume. Continuous runtime is tier-limited, while paused sandboxes are
  retained indefinitely.
 - **Maturity**: Established hosted platform and the API compatibility target
  used by CubeSandbox.
 ### Daytona *(added 2026-07-20)*
 - **Source**: https://github.com/daytonaio/daytona ;
  https://www.daytona.io/docs/
 - **License**: Current production platform is proprietary. The former AGPL
  repository remains public but is no longer maintained after Daytona moved
  production development closed-source in June 2026.
 - **Isolation**: Hosted container sandboxes by default, with separate Linux
  and Windows VM sandbox classes for dedicated-OS workloads. Each sandbox has
  its own filesystem and network stack; VM-only features include memory
  pause/resume and forking.
 - **Locality**: Hosted multi-tenant service, with dedicated/custom regions and
  customer runners available.
 - **Agent integration**: LLM/framework-agnostic SDKs (Python, TypeScript, Go,
  Ruby, Java), API, and CLI; official agent-framework guides. Platform
  primitive rather than a local coding-agent wrapper.
 - **Config**: Programmatic per-sandbox image/snapshot, resources, lifecycle,
  firewall, and secrets.
 - **Network policy**: Per-sandbox IPv4/domain allowlists and block-all mode,
  subordinate to organization/tier policy. Full internet access is the
  default on higher tiers, so it is configurable rather than uniformly
  default-deny.
 - **Credentials**: First-class secret manager with the same phantom-token
  pattern as bot-bottle: the sandbox environment gets an opaque placeholder,
  an HTTPS proxy substitutes the real secret in headers only for allowed
  hosts, and responses are scrubbed back to the placeholder.
 - **Persistence**: Persistent filesystem for stopped container sandboxes;
  memory + filesystem pause/resume for VM sandboxes; snapshots and configurable
  auto-stop.
 - **Maturity**: Production commercial platform. Notable April 2026 credential
  exposure was patched; the June 2026 closed-source transition materially
  changes its transparency/self-hosting posture.
 ### Other hosted runtimes carried forward from the earlier survey
 - **Northflank Sandboxes** — hosted or customer-cloud, microVM-backed
  containers with SDK-managed lifecycle, optional persistent volumes, and
  sub-second claimed boot. This is a platform primitive for untrusted code and
  agents, not a local agent wrapper or role-policy layer.
 - **Cloudflare Sandbox SDK** — Workers/Durable Objects API over VM-isolated
  Linux containers for command, file, process, and service execution. It is a
  hosted TypeScript platform primitive; application authentication,
  authorization, and credential-proxy patterns remain the integrator's job.
 Both belong to the same “build your agent platform on this runtime” category as
 E2B and Daytona. They were named but not analyzed in depth by the original
 Claude-specific note, so they remain outside the main comparison table rather
 than being presented with false precision.
 ### CubeSandbox *(added 2026-07-18)*
 - **Source**: https://github.com/TencentCloud/CubeSandbox ;
  HN launch https://news.ycombinator.com/item?id=47863430
 - **License**: Apache 2.0 (~10.4k stars). By Tencent Cloud; described as
  "battle-tested, production-ready" infra already running in Tencent
  Cloud. Rust / Go / C.
 - **Isolation**: MicroVMs via RustVMM + KVM — "each sandbox gets its own
  Guest OS kernel, no Docker shared-kernel escapes." Hardware-level
  isolation, dedicated kernel per instance.
 - **Locality**: Self-hosted, but **server/cluster-oriented**, not a
  single-user local CLI. Deploy guides target PVM cloud VMs, bare metal,
  and dev. A single 96-vCPU host is claimed to run 2,000+ concurrent
  sandboxes.
 - **Agent integration**: **Drop-in E2B SDK replacement** (single env-var
  change) — the headline compatibility claim. OpenClaw assistant
  integration; general LLM-code execution. Aimed at platform builders,
  not one developer's laptop.
 - **Config**: Programmatic via the E2B-compatible SDK. No declarative
  manifest.
 - **Network policy**: This is the striking part — **domain allowlists,
  instant block on unauthorized egress, full audit logs, per-sandbox
  traffic tokens, policy-routing egress**, enforced by an eBPF-based
  virtual switch giving kernel-level network isolation. Closest match yet
  to bot-bottle's own default-deny + per-bottle allowlist egress model.
 - **Credentials**: **Credential vault** — agents call external APIs / LLMs
  while "keys never enter the sandbox, model context, or logs." Same
  in-flight-injection idea as matchlock, but productized as a vault.
 - **Performance**: <60ms cold start (claimed 2.5–50× faster than
  alternatives), <5MB memory per instance; millisecond snapshot rollback
  is upcoming.
 - **Maturity**: Open-sourced July 2026 off production Tencent Cloud use;
  most-starred project in this set (~10.4k).
 ### Cleanroom *(added 2026-07-18)*
 - **Source**: https://github.com/buildkite/cleanroom
 - **License**: Apache 2.0
 - **Isolation**: MicroVM — Firecracker on Linux, Virtualization.framework
  on macOS. Digest-pinned OCI images.
 - **Locality**: Self-hosted server (CI-oriented).
 - **Agent integration**: Generic process sandbox; CI-first, not a
  Claude/agent wrapper.
 - **Config**: `cleanroom.yaml` in the repo being sandboxed defines egress
  rules, resources, and network policy. Cleanroom resolves this from the
  commit being run.
 - **Network policy**: Default-deny + per-repo hostname allowlist (resolved
  from DNS answers + destination IP:port). Co-hosted services on the same
  IP:port are not distinguished. OIDC-backed auth for remote servers.
 - **Credentials**: Host-side only; not injected in-flight but not present
  in the VM.
 - **Notable**: Policy lives in the *repo being sandboxed*, not in an
  agent-role definition — closer to per-repo scoping than per-role.
  Supports Docker-inside-sandbox (`services.docker.required: true`), OIDC
  authorization, suspend/resume lifecycle.
 - **Maturity**: Active Buildkite product.
 ### container-use *(added 2026-07-18)*
 - **Source**: https://github.com/dagger/container-use
 - **License**: Apache 2.0
 - **Isolation**: Docker container per agent + git worktree per agent.
  Containers share the host kernel; stronger than bare host but weaker
  than microVM.
 - **Locality**: Local.
 - **Agent integration**: MCP stdio server — Claude Code, Cursor, Windsurf.
  `claude mcp add container-use -- container-use stdio`.
 - **Config**: None for security policy. Environments are provisioned on
  demand; no allowlist or credential config.
 - **Network policy**: Not addressed.
 - **Notable**: Per-agent git branches (`container-use/<env_name>`);
  parallel agents without filesystem conflict; real-time log visibility
  and terminal attach for intervention; git-based review workflow.
  Oriented toward parallel development safety, not security containment.
 - **Maturity**: Early development, active.
 ### Docker sbx *(added 2026-07-18)*
 - **Source**: Docker proprietary (`sbx` CLI, separate from `docker`).
 - **License**: Proprietary.
 - **Isolation**: MicroVM (Docker's own implementation) — each session gets
  its own kernel, Docker daemon inside the VM, and filesystem.
 - **Locality**: Local (macOS and Windows; does not require Docker Desktop).
 - **Agent integration**: Explicit wrapper — Claude Code, Codex, Gemini
  CLI, Copilot CLI, Kiro. Launches agent inside the VM with
  `--dangerously-skip-permissions` by default.
 - **Config**: Open / Balanced / Locked Down network presets at launch. No
  per-role manifest.
 - **Network policy**: Default-deny; preset levels control strictness. TUI
  dashboard shows a live log of every outbound connection (allowed and
  blocked) with point-and-click allow/block for hosts.
 - **Credentials**: OS keychain + host-side proxy injection — API keys
  never enter the VM.
 - **Notable**: Best DX among microVM tools (one command, works like native
  yolo Claude but inside a VM); branch mode creates a git worktree in
  `.sbx/`. Network policy is preset-based, not role-declarative.
 - **Maturity**: GA 2026.
 ### Anthropic srt *(added 2026-07-18)*
 - **Source**: https://github.com/anthropic-experimental/sandbox-runtime
  (`@anthropic-ai/sandbox-runtime` on npm, `sandbox-runtime` on PyPI)
 - **License**: Apache 2.0 (experimental).
 - **Isolation**: OS-level only — Seatbelt (`sandbox-exec`) on macOS,
  bubblewrap on Linux, WFP (Windows Filtering Platform) account-fenced on
  Windows. **No container or VM.** Lowest overhead in the set.
 - **Locality**: Local.
 - **Agent integration**: Claude Code's sandboxed bash tool uses this
  internally. Can wrap any arbitrary process (`srt <command>`). Cloud
  Claude Code sessions use full microVMs instead.
 - **Config**: Programmatic per-invocation — allow/deny path lists for
  filesystem; allow/denylist for network (HTTP proxy + SOCKS5).
 - **Network policy**: Proxy-based filtering (HTTP + SOCKS5); domain
  allowlist/denylist enforced at proxy layer. Custom proxy supported
  (e.g. mitmproxy for inspection + audit). Processes that ignore proxy
  env vars may bypass filtering on some platforms.
 - **Notable**: Cross-platform (macOS/Linux/Windows); wraps any process,
  not just agents; no role/manifest concept. Annotated as a research
  preview — APIs may change.
 - **Maturity**: Early research preview.
 ## Claude-specific wrappers and developer environments
 These projects were the focus of the original containerized-Claude survey.
 They remain useful comparisons for local developer experience, but most are
 templates or wrappers rather than policy-bearing sandbox platforms, so they
 are grouped here instead of widening the main table further.
 ### claudebox
 - **Source**: https://github.com/RchGrav/claudebox
 - **Isolation**: Docker, with per-project images, authentication state, and
  configuration.
 - **Agent integration**: Claude Code wrapper with 15+ preconfigured language
  and task profiles.
 - **Network policy**: Per-project firewall allowlists.
 - **Closest overlap**: local one-command developer workflow and project-scoped
  network policy.
 - **Difference**: profiles describe development toolchains, not named agent
  roles. There is no bottle/agent split, composable role manifest, provider
  plugin layer, or outbound-content DLP.
 ### Spritz / claude-code-sandbox
 - **Source**: https://github.com/textcortex/claude-code-sandbox (archived;
  points to its successor, Spritz).
 - **Isolation**: The original project ran Claude Code in local Docker with
  bypass permissions; Spritz moved toward Kubernetes-native multi-agent
  infrastructure.
 - **Difference**: the successor targets cluster orchestration rather than a
  low-dependency local launcher. It is architecturally closer to hosted or
  Kubernetes platform runtimes than to bot-bottle's single-operator CLI.
 ### Trail of Bits claude-code-devcontainer
 - **Source**: https://github.com/trailofbits/claude-code-devcontainer
 - **Isolation**: A Docker devcontainer that exposes only project files and is
  designed to run Claude Code with `bypassPermissions` for security audits and
  untrusted-code review.
 - **Difference**: a hardened, reusable environment definition rather than an
  agent launcher or fleet. It has no named-role manifest, per-role credential
  custody, supervision plane, or multi-backend abstraction.
 ### Smaller wrappers and official templates
 Projects such as `arezi/claude-sandbox`, `nkrefman/claude-sandbox`, and
 `VishalJ99/claude-docker`, plus Docker/Anthropic devcontainer templates, prove
 there is steady demand for “Claude in a container.” They are deliberately
 small launch/build configurations. They compete on setup simplicity, not on
 role-aware policy, credential custody, persistent supervision, or a fleet
 model, and are better treated as a product category than as individual rows.
 ### SuperHQ
 - **Source**: https://superhq.ai/
 - **Isolation**: Apple-Silicon desktop application using local microVMs via
  Virtualization.framework/libkrun-era components.
 - **Agent integration**: Claude Code, Codex, and Pi in a GUI, with mobile
  remote access.
 - **Credentials and review**: host-side auth gateway injects credentials on
  the wire; a temporary overlay stages writes for diff-and-accept review.
 - **Closest overlap**: local microVM isolation, multi-provider launching, and
  credential custody for security-minded individual developers.
 - **Difference**: GUI desktop product on Apple Silicon rather than a
  cross-platform declarative CLI/fleet layer. The July 2026 snapshot in the
  original survey recorded a user request for per-run tool-call and network
  audit logging; treat that as point-in-time rather than a permanent gap.
 ## Credential gateway without isolation
 ### OneCLI
 [OneCLI](https://onecli.sh/) is a framework-agnostic identity gateway rather
 than a sandbox. Its phantom-token design gives the agent a placeholder and
 substitutes the encrypted real credential at the network layer. It therefore
 matches bot-bottle closely on secret custody, and is more portable because it
 can sit in front of agents launched by anything, but it supplies no container
 or VM boundary, filesystem isolation, role manifest, or egress-content DLP.
 The positioning consequence from the earlier survey still holds: secret
 custody alone is not unique. bot-bottle's relevant combination is local
 isolation + default-deny egress + payload DLP + declarative roles + credential
 custody. OneCLI's managed tier also places custody with a third party, whereas
 bot-bottle keeps it within operator-controlled infrastructure. See
 [`agent-credential-proxy-landscape.md`](agent-credential-proxy-landscape.md)
 for the detailed build-versus-adopt analysis.
 ## Governance / pre-action authorization layers
 These two tools don't provide VM or filesystem isolation; they intercept
 tool calls before execution and evaluate them against a per-agent
 declarative policy. They are the closest competitors on **agent-tailored
 policy** and complement isolation sandboxes rather than substituting for
 them.
 ### Microsoft Agent Governance Toolkit (AGT) *(added 2026-07-18)*
 - **Source**: https://github.com/microsoft/agent-governance-toolkit
 - **License**: MIT (~3.3k stars, open-sourced April 2, 2026).
 - **Isolation**: None (OS/VM). Execution rings (0–3, inspired by CPU
  privilege levels) control what an agent can do at the framework layer.
  MCP security gateway treats MCP traffic as an untrusted boundary.
 - **Locality**: Embedded in the agent framework (Python, TypeScript, .NET,
  Rust, Go; 20+ framework adapters).
 - **Agent integration**: Framework-agnostic. Plugs into Semantic Kernel,
  AutoGen, and others as a middleware layer.
 - **Config**: YAML policy per agent — tools can be `allowed`, `denied`,
  `sandboxed`, or routed through an `approval` step. Every action passes
  through a governance gate checking: agent DID, trust score, risk tier,
  requested tool, action type, and policy rules.
 - **Network policy**: Not directly — operates at tool-call level.
 - **Credentials**: Per-agent DID (Ed25519 decentralized identifier); agent
  does not borrow a human's credentials.
 - **Notable**: Dynamic trust score (0–1,000, behavioral decay) —
  privilege follows observed behaviour, not just provisioning. Covers all
  10 OWASP Agentic Top 10 risks. Kill switch + SLO monitoring. Sub-ms
  policy enforcement.
 - **Maturity**: MIT, ~3.3k ⭐, v3.7.0 May 2026.
 ### Open Agent Passport (OAP) *(added 2026-07-18)*
 - **Source**: https://github.com/aporthq/aport-spec ; spec at
  https://api.aport.io/spec/spec/oap/oap-spec.md/ ; arXiv 2603.20953
 - **License**: Open specification.
 - **Isolation**: None. Pre-action hook only — intercepts tool calls
  synchronously before execution, evaluates against a cloud-registry
  declarative policy, fails closed.
 - **Locality**: Local hook + cloud policy registry.
 - **Agent integration**: Framework-agnostic; hook pattern.
 - **Config**: Declarative policy rules in a cloud registry (evaluated in
  order; first failing rule denies). Ed25519-signed, hash-chained audit
  records per decision.
 - **Network policy**: Not directly.
 - **Notable**: 53ms median authorization decision (N=1,000). In an
  adversarial testbed ($5,000 bounty, 1,151 sessions), social engineering
  succeeded 74.6% of the time under a permissive policy; under a
  restrictive OAP policy, 0% success across 879 attempts. Assumes
  framework runtime is not compromised.
 - **Maturity**: Specification + reference implementation, 2026.
 ## Comparison table
-| Axis | bot-bottle | endo-familiar | litterbox | agent-safehouse | matchlock | tilde.run | boxlite | microsandbox | smolmachines |
+*Isolation/sandbox tools only. AGT and OAP are governance layers — see their per-project notes above.*
-|---|---|---|---|---|---|---|---|---|---|
+
-| Isolation | Docker + internal net + pipelock; gVisor if present | Object-capability (no OS isolation) | Podman + opt. Landlock | macOS `sandbox-exec` | MicroVM (Firecracker / Virt.fw) | Hosted container (unverified) | MicroVM (KVM / Hypervisor.fw) | MicroVM (libkrun) | MicroVM (libkrun / KVM) |
+| Axis | bot-bottle | endo-familiar | litterbox | agent-safehouse | matchlock | tilde.run | boxlite | microsandbox | smolmachines | E2B | Daytona | CubeSandbox | Cleanroom | container-use | Docker sbx | Anthropic srt |
-| Local vs hosted | Local | Local | Local (Linux) | Local (macOS) | Local | Hosted SaaS | Local | Local | Local |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
-| Open source | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | MIT | No | Apache 2.0 | Apache 2.0 | Apache 2.0 |
+| Isolation | MicroVM per bottle default (Firecracker/KVM on Linux, Apple Container on macOS) + own egress DLP scanner; Docker legacy fallback, gVisor there if present | Object-capability (no OS isolation) | Podman + opt. Landlock | macOS `sandbox-exec` | MicroVM (Firecracker / Virt.fw) | Hosted container (unverified) | MicroVM (KVM / Hypervisor.fw) | MicroVM (libkrun) | MicroVM (libkrun / KVM) | Firecracker microVM | Container or Linux/Windows VM class | MicroVM (RustVMM / KVM) | MicroVM (Firecracker / Virt.fw) | Docker container + git worktree | MicroVM (proprietary) | OS-level (Seatbelt / bubblewrap / WFP) — no container |
-| Agent target | Claude Code | Generic (demo) | Generic | Multi-agent wrapper | Generic (+ Claude/OpenAI SDKs) | Claude focus | Generic | Claude + Cursor (MCP/Skills) | Generic (AGENTS.md) |
+| Local vs hosted | Local | Local | Local (Linux) | Local (macOS) | Local | Hosted SaaS | Local | Local | Local | Hosted; self-host/BYOC available | Hosted; dedicated/custom regions | Self-hosted (server/cluster) | Self-hosted server | Local | Local | Local |
-| Network policy | Default-deny via pipelock + per-bottle allowlist + DLP | Capability model only | Limited | Not addressed | Default-deny + allowlist + secret-injecting proxy | Default-deny + logging | Per-VM net (unverified) | Not documented | Off by default + allowlist |
+| Open source | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | MIT | No | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | Production closed-source; legacy AGPL repo unmaintained | Apache 2.0 | Apache 2.0 | Apache 2.0 | Proprietary | Apache 2.0 (experimental) |
-| Parallel agents | Yes (one bottle per agent) | n/a | Not addressed | One at a time | Multiple VMs | Yes (dashboard) | SDK-level | SDK-level | Architectural |
+| Agent target | Claude Code, Codex, Pi, and provider plugins | Generic (demo) | Generic | Multi-agent wrapper | Generic (+ Claude/OpenAI SDKs) | Claude focus | Generic | Claude + Cursor (MCP/Skills) | Generic (AGENTS.md) | LLM-agnostic platform builders | LLM-agnostic platform builders | E2B-compatible (platform builders) | CI / generic process | Claude Code, Cursor, Windsurf (MCP) | Claude Code, Codex, Gemini CLI, Copilot, Kiro | Claude Code (and any process) |
-| Config | JSON manifest (bottles + agents) | Programmatic refs | CLI wizard | Profile files / shell fns | CLI / SDK | DSL + CLI + SDK | SDK | CLI / SDK / MCP | TOML Smolfile |
+| Network policy | Default-deny via own egress scanner + per-bottle allowlist + content DLP + gitleaks on git push | Capability model only | Limited | Not addressed | Default-deny + allowlist + secret-injecting proxy | Default-deny + logging | Per-VM net (unverified) | Not documented | Off by default + allowlist | Per-sandbox allow/deny rules and custom egress proxy; internet configurable | Per-sandbox CIDR/domain allowlist or block-all; tier policy; secret-injecting proxy | Default-deny allowlist + instant egress block + audit logs + per-sandbox tokens (eBPF) + credential vault | Default-deny + per-repo host allowlist (cleanroom.yaml) | Not addressed | Default-deny; Open / Balanced / Locked Down presets; live TUI network panel | Proxy-based allowlist/denylist (HTTP + SOCKS5); custom proxy supported |
-| Maturity | Active May 2026 | Research (2022+) | Early (~66 ⭐) | Active (~1.4k ⭐) | Experimental (~574 ⭐) | Private preview | YC, ~4.7k ⭐ | YC, ~6k ⭐, beta | ~3.1k ⭐ |
+| Parallel agents | Yes (one bottle per agent) | n/a | Not addressed | One at a time | Multiple VMs | Yes (dashboard) | SDK-level | SDK-level | Architectural | Yes (platform service) | Yes (platform service) | Yes (2,000+/host claimed) | Yes (server model) | Yes (per-agent containers + worktrees) | Yes | Yes |
 | Long-running posture | Persistent by default (named, supervised) | n/a (demo) | Session (up while in use) | Per-invocation | Ephemeral VM per run | Per-run (versioned) | Ephemeral + snapshot/fork | Ephemeral / on-demand | Named persistent by default | Runtime tier limits + indefinite pause/resume | Persistent filesystem; VM pause/resume; configurable auto-stop | Ephemeral + auto pause/resume | Per-run + suspend/resume | Per-agent container (ephemeral) | Per-session; branch mode creates git worktree in .sbx/ | Per-invocation |
 | DX: run Claude yolo-style | One command → interactive yolo Claude (`start <agent>`, `--dangerously-skip-permissions` default) | n/a (lib demo) | Wizard + build, then run claude inside (Linux only) | One-command wrapper (`safehouse claude --dangerously-skip-permissions`) | CLI: run a cmd in a VM (not a Claude wrapper) | Hosted (`tilde exec`), not local-native | SDK code required (build the run yourself) | CLI/MCP: sandbox-as-a-tool for the agent, not a wrapper around it | SSH into a named machine, run claude there | SDK/CLI sandbox; wire the agent yourself | SDK/CLI sandbox; wire the agent yourself | Stand up a cluster + drive via E2B SDK | CI-oriented, not a Claude wrapper | MCP server: `claude mcp add container-use -- container-use stdio` | One command: `sbx` wraps claude with `--dangerously-skip-permissions` default | Library/wrapper, not a standalone CLI |
 | Config | YAML-in-Markdown manifests (bottles + agents) | Programmatic refs | CLI wizard | Profile files / shell fns | CLI / SDK | DSL + CLI + SDK | SDK | CLI / SDK / MCP | TOML Smolfile | SDK/API + templates | SDK/API/CLI + images/snapshots | E2B-compatible SDK | cleanroom.yaml in repo | None (no policy config) | Preset levels at launch | Programmatic per-invocation (allow/deny lists) |
 | Agent-tailored policy | Yes — bottle/agent split; declarative per-role egress + credentials; composable via `extends:` | Partial — capability model scopes per-agent, but no declarative role manifest | No | Partial — per-agent profile files (Seatbelt); no egress | No | Yes — per-agent DSL RBAC (allow/deny/approve per action/repo/agent) | No | No | No | No — per-sandbox SDK config | No — per-sandbox SDK config | No — per-sandbox SDK config, not role-scoped | Partial — per-repo cleanroom.yaml, not per-role | No | No — network presets only | No |
 | Maturity | Active July 2026 | Research (2022+) | Early (~66 ⭐) | Active (~1.8k ⭐) | Experimental (~574 ⭐) | Private preview | YC, ~4.7k ⭐ | YC, ~6k ⭐, beta | ~3.1k ⭐ | Established hosted platform, ~12.4k ⭐ | Production commercial; closed-source since June 2026 | Tencent, prod, ~10.4k ⭐ | Active (Buildkite product) | Early development | GA 2026 | Early research preview |
 ## What's closest, what's different
 **Closest in design and scope.** agent-safehouse and litterbox sit
 nearest bot-bottle: local, single-user, thin wrappers over an
 existing OS primitive, low-dep. The split is the isolation primitive —
-bot-bottle uses Docker + pipelock egress (plus gVisor where
+bot-bottle now defaults to a VM per bottle (Firecracker microVM on KVM
-available); agent-safehouse uses `sandbox-exec`; litterbox uses Podman +
+Linux, Apple Container on macOS) with its own DLP-scanning egress proxy,
-Landlock. matchlock and smolmachines are spiritually close on the
+keeping Docker only as a legacy fallback; agent-safehouse uses
-*policy* side (default-deny net, per-host allowlist) but use microVMs
+`sandbox-exec`; litterbox uses Podman + Landlock. matchlock and
-instead of containers.
+smolmachines are close on *both* the policy side (default-deny net,
 per-host allowlist) and — now that bot-bottle has moved off
 containers-by-default — the microVM isolation primitive. Note: Apple
 Container 1.0 stable shipped June 9 2026 (frozen CLI and APIs), which
 makes the macOS backend stable surface area rather than a moving target.
 **New closest on agent-tailored policy.** Two governance tools are the
 direct competitors on the "coarse-grained sandbox" axis. **tilde.run**
 has had per-agent DSL RBAC since its launch (though it's hosted SaaS).
 **Microsoft AGT** is the most serious new entrant: per-agent DID
 identity, YAML policy that can allow/deny/sandbox/approve individual tool
 calls per agent, and a dynamic behavioural trust score. It operates at
 the framework tool-call layer, not the network layer — so it's
 complementary to bot-bottle's network/filesystem isolation rather than a
 direct substitute, but on the "does this sandbox know what this agent is
 for?" question it is the most complete answer in the field. OAP's
 pre-action hook pattern achieves similar goals with cryptographic audit
 and a 0% adversarial-attack success rate under a restrictive policy.
 **New closest on DX.** **Docker sbx** is the first tool in this set that
 matches bot-bottle on the "one command, dangerously-skip-permissions safe
 by default" DX bar, at microVM isolation strength, with host-side
 credential injection. It is proprietary, preset-based (not role-
 declarative), and cloud-agent-specific, but it directly competes on the
 UX proposition. agent-safehouse was the previous DX peer; Docker sbx
 materially raises the bar.
 **New closest on repo-scoped policy.** **Cleanroom** (Buildkite) is the
 first tool to combine microVM isolation with a declarative egress policy
 file — though the policy lives in the repo being sandboxed
 (`cleanroom.yaml`), not in an agent-role manifest. That makes it per-
 repo rather than per-role: the same Cleanroom config applies to any
 agent running in that repo. The distinction matters for bot-bottle's
 use case (one developer running multiple agent *roles* with different
 egress footprints), but for CI/CD use cases Cleanroom is a direct
 alternative.
 **Solving a different problem.** tilde.run is hosted SaaS for team /
 production agent pipelines with data-versioned rollback — explicitly
-opposite to bot-bottle's "infrastructure I control" goal. boxlite and
+opposite to bot-bottle's "infrastructure I control" goal. E2B and Daytona
-microsandbox are infrastructure libraries aimed at platform builders
+are hosted sandbox platforms, while boxlite, microsandbox, and CubeSandbox
-embedding sandboxes into agent frameworks; they would be a *backend*
+are infrastructure libraries/services aimed at platform builders embedding
-bot-bottle could call, not a competitor to its manifest layer.
+sandboxes into agent frameworks; they
-endo-familiar is in a different paradigm entirely: capability passing
+would be a *backend* bot-bottle could call, not a competitor to its
-rather than kernel boundaries.
+manifest layer. endo-familiar is in a different paradigm entirely:
 capability passing rather than kernel boundaries.
 ## Borrowable ideas
-What bot-bottle already has that the survey suggested as
+### Already shipped or otherwise addressed
-differentiators:
+
- Default-deny egress with a per-agent allowlist (pipelock).
+- Default-deny egress with a per-agent allowlist (own egress scanner).
 - DLP scanning of outbound traffic.
 - Bottle / agent split (manifest layer above the isolation primitive).
 - gVisor auto-detection on Linux.
 - **In-flight secret injection** (suggested by matchlock) — **shipped.**
  Real provider and git-host tokens are held outside the agent and injected
  by the egress gateway on matching routes. The agent receives only proxy
  URLs and, where a client requires a credential-shaped value, a placeholder;
  `GITEA_TOKEN` and equivalent real tokens do not appear in the agent's
  environment.
 - **MicroVM backend** — **shipped.** MicroVMs are now the default:
  Firecracker on KVM Linux and Apple Container on macOS. Docker is the legacy
  fallback.
 - **Per-use SSH key confirmation** (suggested by litterbox) — **addressed by
  stronger credential custody instead.** The agent does not hold the upstream
  git SSH key or an SSH-agent socket: git-gate holds the credential and gates
  git operations. A confirmation wrapper inside the agent would therefore
  protect a credential that is no longer there. Operator approval at the gate
  remains the appropriate control point for any future per-use confirmation.
-Ideas worth considering, without abandoning the Python-stdlib-first / local-Docker
+### Still worth considering
 stance:
-1. **Per-use SSH key confirmation** (from litterbox). Even with
+- **Live network activity in the supervisor TUI** (from Docker sbx): show
-   KnownHostKey pinning and pipelock egress, a wrapper SSH agent that
+  allowed and blocked connections and let the operator propose policy changes
-   prompts on each key use (e.g. via `osascript` / `notify-send`) would
+  from the existing supervision surface.
-   catch an agent doing something off-policy with a key it legitimately
+- **Tamper-evident audit records** (from OAP): sign and hash-chain egress and
-   holds. Pure-stdlib, no new deps.
+  supervision decisions for compliance-sensitive deployments.
-2. **In-flight secret injection** (from matchlock). Pipelock already
+- **Behaviour-informed policy downgrade** (from Microsoft AGT): use repeated
-   does egress allowlisting and DLP; teaching it to *inject* tokens at
+  DLP alerts or supervision holds as a signal to narrow policy or request
-   proxy time so e.g. `GITEA_TOKEN` never appears in the container's
+  closer review. This needs a carefully specified trust model before it can be
-   env would close the "agent reads its own env and exfiltrates" path.
+  more than a heuristic.
   Fits the existing pipelock architecture.
 3. **MicroVM backend as an opt-in bottle type** — already on the radar
   in `stronger-isolation-alternatives.md`. microsandbox, smolmachines,
   and matchlock all show that libkrun + Apple's
   Virtualization.framework is ergonomic enough that a
   `"runtime": "microvm"` field on a bottle is plausible without a heavy
   stack.
 Not worth borrowing: the SDK-first programmatic API style of boxlite /
 microsandbox (cuts against the declarative-manifest stance), and the
 hosted-SaaS dashboard model of tilde.run (cuts against the
 "infrastructure I control" goal).
 ## Publishing and positioning verdict
 Publishing remains worthwhile, but the defensible claim is the combination,
 not any single primitive. Credential custody is matched by OneCLI, matchlock,
 Daytona, Docker sbx, and CubeSandbox; local one-command isolation is matched by
 agent-safehouse and Docker sbx; hosted microVM execution is a crowded platform
 category.
 bot-bottle remains unusual in combining:
 - local, operator-controlled execution with persistent named bottles;
 - one declarative role layer across Claude Code, Codex, Pi, and provider
  plugins;
 - composable agent/bottle manifests, skills, and system prompts;
 - Firecracker/Apple Container isolation with a Docker fallback;
 - default-deny per-role egress, payload DLP, and git-push secret scanning;
 - credentials injected outside the agent process; and
 - supervision and audit state suited to long-running parallel agents.
 The practical wedge is “as easy as native yolo, with declarative role policy
 and self-hosted custody,” including scoped access to private LAN/Tailnet
 services that cloud-first runtimes cannot provide without additional network
 plumbing. The main competitive risks are a local wrapper such as claudebox or
 Docker sbx growing a role-manifest layer, and GUI products such as SuperHQ
 adding equivalent policy and audit depth.
 ## Caveats
 - Star counts and last-commit dates are point-in-time snapshots.
@@ -230,3 +691,180 @@ hosted-SaaS dashboard model of tilde.run (cuts against the
 - The `superradcompany/microsandbox` URL in the original prompt
  redirects to `microsandbox/microsandbox`; the surveyed project is the
  same.
 - CubeSandbox performance/scale numbers (<60ms cold start, <5MB/instance,
  2,000+ sandboxes per 96-vCPU host) are the project's own launch claims,
  not independently verified here.
 ## Addendum 2026-07-18 — CubeSandbox and the positioning read
 CubeSandbox (Tencent Cloud, Apache 2.0, ~10.4k stars, HN launch
 [#47863430](https://news.ycombinator.com/item?id=47863430)) is the first
 open-source, self-hostable project in this survey to combine, in one stack,
 the main primitives
 bot-bottle treated as its differentiator:
 - **Egress custody (connection level)** — default-deny domain allowlist
  (L7 domain/SNI filtering), instant block on unauthorized egress,
  per-sandbox traffic tokens, full audit logs of destinations (eBPF
  virtual switch, "CubeVS"). This matches bot-bottle's egress scanner at
  the *connection level*, productized — see the one thing it does **not**
  match, below.
 - **Credential custody** — a vault where keys "never enter the sandbox,
  model context, or logs." This is the in-flight-injection idea from
  matchlock, but as a first-class feature, and it's exactly the
  cross-vendor "egress audit + custody" wedge the monetization
  positioning treats as the one defensible moat.
 - **Isolation on par with bot-bottle's current default** — a dedicated
  guest kernel per sandbox (RustVMM/KVM). bot-bottle now defaults to the
  same class of boundary (Firecracker microVM / Apple Container), so this
  is parity, not an edge; CubeSandbox's remaining edge is running that
  per-kernel isolation multi-tenant at scale on one host.
 The one axis CubeSandbox does **not** cover — and where bot-bottle stays
 distinctive:
 - **Content DLP on *authorized* channels.** CubeSandbox's egress control
  is connection-level: it decides *whether* a destination is allowed and
  logs it, and its vault keeps *injected* credentials out of the sandbox
  entirely. Neither inspects the *payload* of traffic to an allowed
  destination. So an agent that exfiltrates over a permitted channel —
  pasting a repo's contents, an agent-derived secret, or PHI into an
  allowed API/domain — is not caught by CubeSandbox. bot-bottle's own
  egress DLP scanner does scan that: response + websocket content against
  the resolved per-flow config, with per-bottle token redaction (see
  recent egress commits). The vault
  approach is arguably *stronger* for the specific case of pre-known
  injected credentials (they can't leak if they were never present), but
  it is not a substitute for content inspection of everything else.
 **Long-running posture — a sharper axis than raw isolation.** E2B and
 CubeSandbox are *ephemeral-per-task* by design; a long-running agent is an
 architected pattern on top, not the default. E2B: 5-minute default
 timeout, continuous runtime tier-capped (~1h Hobby / ~24h Pro), duration
 achieved via **pause/resume** (preserves filesystem + memory + processes;
 reconnect by sandbox ID via `Sandbox.connect()`; resume resets the timeout
 to 5 min; auto-pause via `on_timeout: "pause"`). CubeSandbox mirrors this
 (E2B drop-in) with first-class auto pause/resume and hundred-ms
 checkpoint/fork — and, self-hosted, sets its own timeout policy with no
 vendor tier caps. bot-bottle inverts the model: a bottle is **persistent,
 named, and supervised by default** — long-running *is* the default, not a
 session-management loop over pause/resume. smolmachines is the other
 persistent-by-default project in this set. For anyone building agents that
 run for hours/days, this posture difference matters more than the
 isolation primitive.
 **DX — the "run Claude yolo-style" bar.** The reason `claude
 --dangerously-skip-permissions` is so widely used is DX: it's one command
 and the agent just goes. The bottle thesis is to make a *sandboxed* run
 that easy — `start <agent>` builds the image on first run and drops you
 into an interactive Claude session that already has
 `--dangerously-skip-permissions` on by default
 (`contrib/claude/agent_provider.py`), with the sandbox as the guardrail
 instead of per-action prompts. On this axis the field splits cleanly:
 - **Wrappers around the agent** (as-easy-as-native): bot-bottle and
  **agent-safehouse** (`safehouse claude --dangerously-skip-permissions`).
  These *are* the run-Claude experience. agent-safehouse is the real DX
  peer — but it's macOS-only Seatbelt, single-run, and doesn't address
  network egress; bot-bottle adds VM-grade isolation, egress DLP, and
  persistent/parallel bottles across macOS + Linux.
 - **Libraries / services** (you build the run yourself): boxlite,
  microsandbox, CubeSandbox, E2B, Daytona. These hand you an SDK or a cluster and
  expect you to wire the agent in — powerful for platform builders,
  heavyweight for "just run Claude on my laptop." microsandbox's MCP/Skills
  angle is *sandbox-as-a-tool the agent calls*, which is the inverse of
  wrapping the agent.
 - **In between:** litterbox (wizard + build, Linux only), smolmachines
  (SSH into a named machine), matchlock (run a command in a VM).
 So DX is a genuine bot-bottle differentiator. agent-safehouse matches the
 one-command wrapper with weaker isolation and no egress story; Docker sbx now
 matches it at microVM strength but remains proprietary and preset-based. "As
 easy as native yolo, with declarative role policy" is the narrower defensible
 one-liner.
 Why it still doesn't collide head-on:
 1. **Shape.** CubeSandbox is a *multi-tenant service for platform
   builders* (drop-in E2B replacement, SDK-driven, 2,000 sandboxes on a
   box). bot-bottle is a *single-operator, declarative-manifest tool for
   the infrastructure I run*. Different buyer, different ergonomics — no
   declarative role manifest, no bottle/agent split, no "one command on my
   laptop."
 2. **Backend, not competitor.** Like boxlite/microsandbox, CubeSandbox is
   something bot-bottle could sit *on top of* — a `"runtime": "microvm"`
   or `"runtime": "cubesandbox"` backend under the manifest layer — while
   keeping the manifest, the bottle/agent split, and the local,
   single-operator default.
 Why it matters anyway:
 - The "nobody else bundles connection-level egress allowlist + audit +
  in-flight credential custody" line is **no longer true for the
  primitive** — CubeSandbox ships the open-source/self-hosted combination,
  and Daytona ships a proprietary firewall + credential-substitution variant.
  But **content DLP on authorized channels is still not matched** (see
  above), and neither is the *layer above* the primitive (declarative
  manifest, cross-vendor orchestration, operator UX, the
  phone-control/dashboard north star). Those two — outbound-payload DLP
  and the orchestration layer — are where the defensible ground now sits;
  the connection-level allowlist + vault mechanism, on its own, is no
  longer differentiating. Revisit the monetization open/paid line with
  that in mind.
 - Worth a closer look at **how** CubeSandbox does credential injection
  and per-sandbox egress tokens (eBPF virtual switch vs. bot-bottle's
  mitmproxy egress proxy) when hardening bot-bottle's now-shipped
  credential-custody implementation.
 ## Addendum 2026-07-18 (second pass) — agent-tailored policy landscape
 The second-pass question was: how novel is bot-bottle's per-agent,
 role-tailored sandbox relative to the expanded field?
 **The short answer:** on the isolation + network + role-tailoring
 combination, bot-bottle remains the only tool in this set. On
 role-tailored *policy at the tool-call level*, Microsoft AGT and OAP are
 the most complete answers, but they don't provide isolation; they
 complement rather than substitute.
 **The competitive picture by axis:**
 - *Agent-tailored egress (declarative, per-role)* — bot-bottle and
  tilde.run. Cleanroom is per-repo, not per-role. Everyone else is
  per-session or not addressed.
 - *Agent-tailored tool-call policy (declarative, per-agent identity)* —
  Microsoft AGT (YAML policy + DID identity + trust score), OAP
  (declarative policy rules + cryptographic audit). Neither provides
  network/filesystem isolation.
 - *Composable policy (role overlays)* — bot-bottle (`extends:`). No
  other tool surveyed supports composable role-policy inheritance.
 - *Isolation + DX (one-command safe yolo)* — bot-bottle and Docker sbx.
  Docker sbx is proprietary, preset-based, and cloud-agent-specific;
  it's the first DX-class competitor at microVM isolation strength.
 **What the HN "coarse-grained" complaint maps to:** The complaint is
 that a VM isolates the filesystem but doesn't know if the agent
 *should* be sending an email. bot-bottle's bottle/agent split is a
 structural answer to this: the bottle manifest declares exactly what
 the role can reach, and the sandbox enforces it at the network layer.
 Microsoft AGT is the most complete answer at the semantic/tool-call
 layer. The gap both leave open is *intent classification* — knowing
 whether a permitted action is consistent with the agent's actual task.
 See `hn-agent-safety-discourse-july-2026.md` for the blast-radius
 analysis.
 **Open ideas from new tools (also summarized above):**
 - **Microsoft AGT's trust-score decay** — privilege that reflects
  observed behaviour rather than static provisioning. Applied to
  bot-bottle: a bottle that has triggered DLP alerts or supervise holds
  could auto-downgrade its network preset, or flag the session for
  closer review. Fits the existing supervise-server architecture.
 - **Docker sbx's live network TUI** — real-time per-session view of
  allowed and blocked outbound connections with point-and-click
  allow/block. `cli.py supervise` is the right surface; adding a
  live-connections panel would directly address the "I can't see what
  the agent is doing" gap without any backend changes.
 - **OAP's cryptographic audit chain** — Ed25519-signed, hash-chained
  audit records. Currently bot-bottle logs egress decisions but doesn't
  chain them. A tamper-evident audit record per session would be useful
  for the compliance use case the CubeSandbox positioning targets.
@@ -358,3 +358,111 @@ the Apple Container-specific constraints directly:
 Do not implement the backend as a direct clone of Docker Compose
 service aliases. That assumption failed in this run.
 ## Addendum: consolidated-gateway findings (2026-07-17, PRD 0070)
 Re-tested on Apple Container 1.0.0 while porting the backend to the
 per-host consolidated gateway (#351). The two-network shape above still
 holds; these are the additional constraints that shaped the port, each
 verified against the live CLI on this host.
 ### No static IP for a container
 `container run --network` accepts only
 `<name>[,mac=XX:XX:XX:XX:XX:XX][,mtu=VALUE]`. There is no `--ip`. The
 address comes from vmnet's DHCP and is knowable only after the container
 is running:
 ```console
 $ container run --name a --network bb-net --detach alpine sleep 900
 $ container inspect a | jq -r '.[0].status.networks[0].ipv4Address'
 192.168.128.3/24
 ```
 Consequence: the docker backend's "allocate a free IP -> pin it with
 `--ip` -> register -> launch" order cannot be reproduced. macOS inverts
 it to "launch -> read the assigned address -> register". The identity
 token therefore cannot be in the agent's run-time env (registration mints
 it after the container exists) and is delivered at `container exec` time.
 ### Networks are fixed at run time
 There is no `container network connect`; `container network` exposes only
 `create`, `delete`, `list`, `inspect`, `prune`. A network cannot be
 attached to a running container, so a *persistent* shared gateway rules
 out per-bottle networks — they would force a gateway restart per launch.
 One shared host-only network, created up front, is the only shape that
 keeps the gateway a singleton.
 ### No container DNS
 Containers cannot resolve each other by name; the host-only network's
 resolver refuses the query:
 ```console
 $ container exec agent nslookup gw
 ;; connection timed out; no servers could be reached
 $ container exec agent cat /etc/resolv.conf
 nameserver 192.168.128.1
 ```
 Consequence: the gateway is handed the control plane's **IP**, not a
 container name as on docker. That forces the startup order
 orchestrator -> read its address -> gateway.
 ### The host can reach the host-only network directly
 ```console
 $ container inspect c | jq -r '.[0].status.networks[0].ipv4Address'
 192.168.128.2/24
 $ curl -s http://192.168.128.2:8099/i
 ok
 ```
 So no `--publish` hop is needed: the host CLI and the gateway use the
 same control-plane URL. Docker needs `--publish 127.0.0.1:...` plus a
 separate internal URL for the same job.
 ### CAP_NET_RAW is granted by default — and matters for attribution
 Apple grants NET_RAW but not NET_ADMIN. The agent therefore cannot change
 its own address or route:
 ```console
 $ container exec agent ip addr add 192.168.128.99/24 dev eth0
 ip: RTNETLINK answers: Operation not permitted
 $ container exec agent ip route replace default via 192.168.128.2 dev eth0
 ip: RTNETLINK answers: Operation not permitted
 $ container exec agent grep CapEff /proc/self/status
 CapEff:	00000000a80425fb        # bit 13 (NET_RAW) set, bit 12 (NET_ADMIN) clear
 ```
 But NET_RAW permits raw sockets, i.e. source-address forgery against
 neighbours on the shared segment — directly against PRD 0070's invariant
 ("a packet's source address, as seen by the orchestrator, provably
 identifies the originating bottle"). `--cap-drop CAP_NET_RAW` closes it:
 ```console
 $ container run --cap-drop CAP_NET_RAW ... alpine
 $ container exec nr grep CapEff /proc/self/status
 CapEff:	00000000a80405fb        # bit 13 cleared
 $ container exec nr ping -c1 192.168.128.2
 ping: permission denied (are you root?)
 ```
 The agent is run with `--cap-drop CAP_NET_RAW` for this reason.
 ### `container exec` inherits run-time env, and `--env` overrides it
 ```console
 $ container run --name e --env FOO=from_run --detach alpine sleep 120
 $ container exec e sh -c 'echo $FOO'
 from_run
 $ container exec --env FOO=from_exec e sh -c 'echo $FOO'
 from_exec
 ```
 This is what makes exec-time identity-token delivery work: the token-less
 proxy URL baked in at launch is superseded by the token-bearing one at
 exec. Bare `--env NAME` (inherit from the parent process) keeps the token
 value off argv.
@@ -0,0 +1,357 @@
 # HN discourse on agent sandbox safety — June/July 2026
 A survey of community opinion and notable security disclosures on Hacker
 News and adjacent sources over June–July 2026. The question: what does
 the current discourse say about whether sandboxes are sufficient for
 agentic AI safety, and where does bot-bottle land against the issues
 being raised?
 Research conducted 2026-07-18.
 ## Summary
 The past month marks a turning point in community opinion. Earlier in
 2026, the debate was mostly "which sandbox tool is best?" By June–July,
 a cascade of critical CVEs and novel attack classes has shifted the
 framing to "sandboxes are not enough — what else do you need?" The
 attacks that drove this shift are structurally distinct: most route
 through legitimate, trusted channels (Sentry issues, MCP descriptions,
 README files) rather than exploiting the isolation boundary directly.
 bot-bottle's architecture holds up well against the direct-escape class
 (Firecracker/Apple Container default backends, credentials never in the
 agent's env, harness entirely on the host). The remaining gap is prompt
 injection — attacker-controlled data interpreted as model instructions.
 Egress controls and prompt injection defenses are orthogonal: egress
 limits what the agent can *send out*; injection is about what it is
 *told to do*. The two don't substitute for each other. Inside a tightly-
 egressed sandbox a successful injection can't exfiltrate to unknown
 hosts, but it can still corrupt the work product, push malicious commits
 past a secret scanner, or use allowlisted channels for exfiltration.
 Those residual risks are addressed below.
 ## The sandboxing boom sets the stage
 The preceding months generated a wave of sandbox tooling. A March 28
 Ask HN thread
 ([#47444917](https://news.ycombinator.com/item?id=47444917)) catalogued
 the explosion: E2B, AIO Sandbox, AgentSphere, Yolobox, Exe.dev,
 AgentFence, DenoSandbox, Capsule (WASM), ERA, Vibekit, Daytona, Modal,
 Nono, and more — all launched within roughly 12 months. A parallel March
 9 thread ([#47185250](https://news.ycombinator.com/item?id=47185250))
 surveyed what developers were actually deploying: "containers or YOLO"
 dominated. The honest community mood was that most teams hadn't solved
 this and were shipping anyway.
 The March 12 launch of **Agent Safehouse**
 ([#47301085](https://news.ycombinator.com/item?id=47301085), 823 points)
 crystallised the community framing: a zero-dep `sandbox-exec` wrapper for
 macOS that attracted the top comment *"I honestly think that sandboxing is
 currently THE major challenge that needs to be solved for the tech to fully
 realise its potential."* The creator's own framing — "no dependencies, no
 daemons, no subscription; the simplicity is the feature" — and Simon
 Willison's observation that evaluating whether a sandboxing tool works as
 intended is itself hard, both prefigure the June–July shift in tone. See
 [`agent-sandbox-landscape.md`](agent-sandbox-landscape.md) for a full
 per-project breakdown.
 ## The June–July attack cascade
 Six attack patterns broke in quick succession. Together they form the
 argument that the community's framing was wrong: the threat model for
 agents isn't just "code that escapes its container" — it's also prompt
 injection, where attacker-controlled data is interpreted as model
 instructions regardless of whether any isolation boundary was crossed.
 Sections 2–4 below are all the same attack class; the "trusted channel"
 label describes the delivery vector, not a different threat.
 ### 1. Sandbox escape CVEs (DuneSlide, CVE-2026-39861)
 Cato AI Labs disclosed **DuneSlide** (CVE-2026-50548/50549, CVSS 9.8),
 a pair of flaws in Cursor 2.x. CVE-2026-50548 abuses the sandbox's
 `working_directory` parameter to point writes at system files; CVE-26-50549
 exploits a symlink-resolution fallback that fails open. Both start with
 a prompt injection and end in sandbox escape — and Cato's framing was
 blunt: "each CVE defeats a different guardrail; the problem is
 structural, not a string of one-offs."
 Claude Code's own sandbox had a similar escape this year:
 **CVE-2026-39861** (symlink flaw). The CurXecute/MCPoison/CVE-2026-26268
 chain from Cursor added a poisoned Slack message, a swap-after-approval
 MCP config, and a Git hook as three more entry points in the same
 attack class.
 All patched, but the pattern holds: any application-level sandbox that
 takes attacker-influenced values as path parameters is reachable from a
 prompt injection.
 ### 2. Prompt injection via MCP data (Agentjacking)
 Tenet's "Agentjacking" technique planted a fake bug report in Sentry's
 MCP output. When an agent queries Sentry to fix open issues, the
 malicious event is rendered as structured content visually
 indistinguishable from a real Sentry event, and the agent executes the
 embedded instructions with the developer's full privileges. Hit rate
 across Claude Code and Cursor: **85%**. The route is entirely through a
 legitimately-authorized MCP channel — no isolation boundary is crossed;
 the injection arrives inbound through a channel the sandbox explicitly
 trusts.
 The Cloud Security Alliance's summary: treat observability, bug-report,
 and integration data as **untrusted agent input**, not neutral
 development metadata.
 ### 3. README-embedded prompt injection
 A July disclosure showed malicious instructions hidden in `README.md`
 — a file that receives no trust prompt and requires no elevated access.
 When asked point-blank whether the repo held hidden instructions, both
 Claude Sonnet 4.6 and GPT-5.5 said no. A payload written for Sonnet
 4.6 transferred unchanged to Sonnet 5, Opus 4.8, and GPT-5.5. The
 attack surface is every repo an agent is asked to work in.
 ### 4. Prompt injection via MCP tool descriptions
 Microsoft research (June 30) showed that attacker-controlled MCP tool
 description fields can silently redirect agent behavior. The injection
 is embedded in metadata the model reads during tool selection — before
 any sandbox enforcement or egress check runs, and entirely on the
 inbound path that egress controls cannot touch.
 ### 5. MCP STDIO command injection (10 CVEs)
 OX Security disclosed a systemic command injection class in Anthropic's
 MCP protocol, covering 10 CVEs across multiple coding agents. The
 Windsurf case (CVE-2026-30615): processing attacker-controlled HTML
 causes the agent to auto-register a malicious MCP STDIO server and
 execute arbitrary commands with no further user interaction.
 ### 6. LiteLLM gateway compromise (CVE-2026-40217, CVE-2026-42271)
 CVE-2026-40217 exposes LiteLLM's guardrail sandbox via `exec()` with no
 source filtering. CVE-2026-42271 (exploited in the wild, added to CISA's
 KEV catalog) lets callers spawn subprocesses through MCP preview
 endpoints. The threat extends to any agent routed through a compromised
 LiteLLM proxy: the proxy can swap model responses for forged tool calls
 in transit, giving the attacker a reverse shell from the developer's
 machine.
 ## HN community opinion clusters
 **"Move enforcement to the kernel, not the app"** — the Nono Show HN
 ([#46849615](https://news.ycombinator.com/item?id=46849615)) and a
 kernel-sandbox thread
 ([#47066574](https://news.ycombinator.com/item?id=47066574)) both argued
 that application-layer sandboxes are inherently bypassable by the code
 they're sandboxing. The academic framing, from *Red-Teaming the Agentic
 Red-Team* ([arXiv 2606.24496](https://arxiv.org/pdf/2606.24496)):
 "enforcement should occur at the OS level via the kernel refusing system
 calls that violate policy at runtime — not pre-execution argument
 validation in tool calls."
 **"The harness belongs outside the sandbox"** — a May thread
 ([#47990675](https://news.ycombinator.com/item?id=47990675)) converged
 on clean architectural separation: harness in one VM, tool execution in
 another. Top comment: "having the harness in one VM, and tool use applied
 to user data in another, is about as safe as you can be at present."
 Several replies described a hypervisor-like policy layer — sitting outside
 both VMs — as the right long-term model.
 **"Sandboxes are too coarse-grained"** — a Feb thread
 ([#47006445](https://news.ycombinator.com/item?id=47006445)) argued
 that VMs don't answer the real question: knowing whether an agent
 *should* be sending an email or making a transaction. "Everything's just
 in the same big box." This framing picked up traction through June–July
 as the trusted-channel attacks dominated.
 **"MCP's trust model is the real problem"** — the month's recurring
 theme. MCP by design gives agents access to authorized external services.
 Once a trusted channel delivers a malicious payload, filesystem sandboxing
 is irrelevant. The community call: treat all MCP tool metadata and return
 values as untrusted input subject to policy validation before ingestion,
 and disable automatic MCP server loading from untrusted repositories.
 ## How bot-bottle addresses these issues
 ### What it covers well
 **Direct sandbox escape (CVEs, container breakout)**
 bot-bottle's default backends are Firecracker microVM (KVM Linux) and
 Apple Container (macOS). Both run the agent in a separate VM with a
 dedicated kernel — the container-escape CVE class (Dirty Pipe, runc
 escapes, DuneSlide's path-parameter abuse) requires escaping a real
 hypervisor boundary, not just a namespace. On the legacy Docker backend,
 gVisor auto-detection provides a userspace syscall barrier for hosts where
 neither KVM nor Apple Container is available.
 The bot-bottle process itself runs entirely on the host, outside the VM.
 This is the "harness outside the sandbox" architecture the HN thread
 converged on as best practice. The bottle manifest, egress rules, and
 secrets never enter the agent VM.
 **Credential theft on sandbox escape**
 Even on a successful VM/container escape, the agent has nothing useful
 to steal. Credentials are injected in-flight by the gateway proxy
 (`auth.scheme` / `auth.token_ref` in the egress route config) — `printenv`
 inside the agent shows proxy URLs only. The git-gate similarly holds the
 upstream SSH credential on the host; the agent pushes through a
 gitleaks-scanned daemon that forwards clean refs upstream. An escaped
 agent gets the host filesystem, not the keys.
 **Orphaned-agent credential risk**
 bot-bottle is explicitly ephemeral: when the agent exits, `cli.py` tears
 down every gateway and both networks — nothing persists between runs. The
 agent never holds credentials, so there is nothing to orphan.
 **MCP config redirection / STDIO auto-registration**
 The trust boundary at `$HOME` means bottles live only under
 `~/.bot-bottle/bottles/` — a cloned repo cannot add egress routes or
 redirect env vars to attacker hosts (the design rationale is in
 `docs/prds/0011-per-file-md-manifest.md`). Auto-registering a malicious
 MCP STDIO server from within the agent is still sandboxed by the VM, and
 any outbound calls from that server must pass the egress allowlist and
 outbound DLP scanner.
 **Per-agent role tailoring (the "coarse-grained sandbox" complaint)**
 The Feb 2026 HN thread that argued "sandboxes are too coarse-grained"
 was pointing at a real gap: a VM isolates the filesystem but doesn't
 know whether an agent *should* be sending email or calling an external
 API. bot-bottle's bottle/agent split is a structural answer at the
 network layer — the bottle manifest declares exactly what each role can
 reach (which hosts, which paths, which HTTP methods), and the egress
 scanner enforces it. A `gitea-dev` bottle that only lists
 `gitea.dideric.is` and `api.anthropic.com` structurally cannot send
 email or reach AWS, not because the model was told not to, but because
 those routes don't exist.
 The `extends:` composition model means provider-level policy (the Claude
 auth route) lives in one base bottle and role-specific overlays are
 stacked on top — no duplication, and changing the base propagates to all
 derived roles.
 Competitive position on this axis (from `agent-sandbox-landscape.md`):
 | Tool | Agent-tailored policy |
 |---|---|
 | **bot-bottle** | Yes — declarative per-role manifest; `extends:` composition; egress + credentials scoped to role |
 | **tilde.run** | Yes — per-agent DSL RBAC (allow/deny/approve per action/repo/agent), but hosted SaaS |
 | **Microsoft AGT** | Yes — YAML policy + per-agent DID + trust score, but tool-call level only (no network isolation) |
 | **OAP** | Yes — declarative pre-action policy + cryptographic audit, but no isolation |
 | **Cleanroom** | Partial — per-repo `cleanroom.yaml`, not per-role |
 | **Docker sbx** | No — network presets only |
 | **Anthropic srt** | No — programmatic per-invocation |
 | **matchlock / smolmachines / microsandbox** | No |
 | **agent-safehouse** | Partial — per-agent Seatbelt profiles; no egress |
 Two takeaways: bot-bottle and tilde.run are the only isolation tools
 with declarative role-tailored policy; Microsoft AGT and OAP are the
 closest competitors on role-tailoring but operate at the tool-call layer
 without network/filesystem isolation — complementary, not substitutes.
 **Outbound exfiltration (any injection class)**
 Whatever triggers the agent — README injection, Agentjacking, MCP
 description poisoning — the final step in most attacks is exfiltration.
 bot-bottle's egress allowlist is default-deny with a per-bottle host
 allowlist; unknown hosts get a hard 403. Outbound DLP scanning
 (`outbound_detectors: [token_patterns, known_secrets]`) catches tokens
 and secrets in outbound bodies; the `supervise` policy (default for
 manifest routes) holds the request for operator approval rather than
 silently blocking it. Together these limit what a successful injection
 can *do* even if it succeeds at the model layer.
 **LiteLLM / compromised-proxy attacks**
 bot-bottle does not use LiteLLM. The model API route (e.g.
 `api.anthropic.com`) is an auto-injected provider route on the egress
 allowlist; the agent dials the gateway, not the model API directly.
 A compromised third-party proxy is not in the architecture.
 ### Where it is weaker
 **Prompt injection**
 Egress controls and prompt injection defenses are orthogonal. Egress
 limits what the agent can *send out* (outbound leg); prompt injection
 is about what attacker-controlled data *tells the agent to do* (inbound
 leg). The two don't substitute for each other and must be treated
 separately.
 The inbound DLP scanner (`inbound_detectors: [naive_injection_detection]`)
 is the only runtime defense against injection arriving through allowlisted
 channels — Sentry MCP responses, MCP tool descriptions, README content.
 It is explicitly pattern-matching and will not catch a sufficiently
 crafted payload. There is no semantic / intent-level gate between what
 the model decides and what the agent executes.
 **Blast radius within the permitted scope**
 Inside a tightly-egressed sandbox a successful injection can't
 exfiltrate to unknown hosts, but it still has real options:
 - *Work product corruption.* The agent can modify, delete, or backdoor
  files in the working directory. This is within its permitted scope;
  egress controls have nothing to say about it.
 - *Malicious commits past the git-gate.* The git-gate scans outbound
  refs for secrets (gitleaks), not for semantic code intent. A prompt-
  injected agent can commit subtly malicious code — logic bombs,
  backdoored auth paths, code that exfiltrates data through the
  application's own HTTP clients at runtime — that looks clean to a
  secret scanner.
 - *Exfiltration through allowlisted channels.* If an attacker knows or
  can predict what hosts are in the egress allowlist, those channels are
  available for exfiltration. A GitHub remote being allowlisted means
  "push to an attacker-controlled fork" is viable. A logging endpoint
  being allowlisted means structured data can leave through it. The
  outbound DLP scanner catches credential tokens and known secrets but
  not arbitrary business data.
 - *Dependency installation within the sandbox.* An agent that runs
  `npm install` or `pip install` on attacker-specified packages executes
  code inside the sandbox with the same capabilities the agent has:
  filesystem access, tool calls, calls to allowlisted hosts. Supply chain
  injection via package names is in the same injection family, triggered
  by the same prompt-injection path.
 ### What would close the remaining gaps
 The blast-radius risks above point at two distinct mitigations that
 don't yet exist in bot-bottle:
 - *Outbound intent classification.* The egress addon today scans
  outbound request content for token patterns. What it lacks is
  awareness of context — it can't distinguish "agent is pushing a
  legitimate commit" from "agent was injected and is pushing a backdoor."
  The `supervise` policy is already the right shape for human-in-the-loop
  review on sensitive outbound actions; extending it with context from
  the agent's recent tool calls (what files were touched, what was the
  triggering task) would narrow the gap.
 - *Semantic code review on git push.* gitleaks is the wrong tool for
  catching injected logic. A review step on outbound commits — even a
  simple diff summary surfaced in `cli.py supervise` before the push is
  forwarded — would close the malicious-commit path without requiring
  the agent to be fully trusted.
 ## Sources
 - [Ask HN: The new wave of AI agent sandboxes? (Mar 2026)](https://news.ycombinator.com/item?id=47444917)
 - [OK, let's survey how everybody is sandboxing AI coding agents (Mar 2026)](https://news.ycombinator.com/item?id=47185250)
 - [The agent harness belongs outside the sandbox (May 2026)](https://news.ycombinator.com/item?id=47990675)
 - [Show HN: Nono – Kernel-enforced sandboxing for AI agents (Feb 2026)](https://news.ycombinator.com/item?id=46849615)
 - [Kernel-enforced sandbox for AI agents, MCP and LLM workloads (Feb 2026)](https://news.ycombinator.com/item?id=47066574)
 - [Sandboxes will be left in 2026 (Feb 2026)](https://news.ycombinator.com/item?id=47006445)
 - [Critical Cursor Flaws / DuneSlide – The Hacker News](https://thehackernews.com/2026/07/critical-cursor-flaws-could-let-prompt.html)
 - [Agentjacking Attack – The Hacker News](https://thehackernews.com/2026/06/agentjacking-attack-tricks-ai-coding.html)
 - [Friendly Fire: AI Agents Built to Catch Malicious Code – The Hacker News](https://thehackernews.com/2026/07/friendly-fire-ai-agents-built-to-catch.html)
 - [Microsoft Warns Poisoned MCP Tool Descriptions – The Hacker News](https://thehackernews.com/2026/06/microsoft-warns-poisoned-mcp-tool.html)
 - [MCP STDIO Command Injection Advisory – OX Security](https://www.ox.security/blog/mcp-supply-chain-advisory-rce-vulnerabilities-across-the-ai-ecosystem/)
 - [LiteLLM Vulnerability Chain – The Hacker News](https://thehackernews.com/2026/06/litellm-vulnerability-chain-lets-low.html)
 - [Red-Teaming the Agentic Red-Team (arXiv 2606.24496)](https://arxiv.org/pdf/2606.24496)
@@ -1,182 +0,0 @@
 # Landscape: containerized AI coding agent tools
 Research into whether bot-bottle is redundant with existing projects, and
 whether it's worth publishing.
 ## Summary
 The "AI coding agents in isolated sandboxes" space is active but not saturated.
 bot-bottle occupies a distinct position: no surveyed project combines all five
 of its defining features. Publishing is likely worthwhile, with the main risk
 being claudebox expanding to absorb the same niche.
 **Updated 2026-07-09:** bot-bottle now supports three isolation backends
 (Docker, Apple `container`, smolmachines/libkrun microVMs) and three built-in
 agent providers (Claude Code, OpenAI Codex, Pi) with an open plugin system for
 arbitrary providers. This meaningfully strengthens the differentiation against
 all surveyed competitors.
 ## Closest competitor: claudebox
 [RchGrav/claudebox](https://github.com/RchGrav/claudebox) is the most
 feature-complete analog. It runs Claude Code in Docker with per-project
 isolated images, 15+ pre-configured dev-language profiles, and per-project
 network firewall allowlists. Actively maintained with multiple forks.
 What it lacks: manifest-driven named agents, per-agent env resolution modes
 (prompt / host-forward / literal), skill directory injection, per-agent system
 prompts, SSH-agent forwarding without copying private keys, home+project
 manifest merge.
 ## Other surveyed projects
 - **textcortex/claude-code-sandbox → spritz** — evolved toward
  Kubernetes-native multi-agent infra; not stdlib-first or local-Docker.
  Original sandbox repo is archived.
 - **trailofbits/claude-code-devcontainer** — devcontainer config for security
  audits; not a general agent launcher.
 - **Several small solo repos** (arezi/claude-sandbox, nkrefman/claude-sandbox,
  VishalJ99/claude-docker) — lightweight Docker wrappers with no multi-agent
  config layer.
 - **Docker's official sandbox templates** — launch-and-run Dockerfiles plus an
  npm-based runtime; not a manifest-driven fleet manager.
 ## Adjacent (different model)
 - **dagger/container-use** (mid-2025) — exposes an MCP server so the *agent*
  spins up its own containers with Git worktrees. Inverted model vs. bot-bottle
  (agent controls container rather than being launched into one by a manifest).
  Still marked early-development.
 - **E2B, Northflank, Cloudflare Sandbox SDK** — cloud-hosted SaaS sandbox
  runtimes; fundamentally different architecture.
 - **superhq.ai / SuperHQ** (v0.4.4, April 2026) — macOS desktop app (Rust/GPUI)
  that runs Claude Code, Codex, and Pi inside microVMs via Apple's
  Virtualization.framework (their own shuru-sdk / libkrun). Auth gateway
  injects API keys on the wire so the sandbox never sees them; tmpfs overlay
  stages agent writes for diff-and-accept review; mobile remote access via
  remote.superhq.ai. Early alpha, free on launch, Apple Silicon only.
  Overlap: both projects cover agent isolation, credential proxying, and
  multi-provider support (Claude Code / Codex / Pi). Differences: SuperHQ is a
  GUI desktop app with no manifest layer; bot-bottle is a CLI fleet manager with
  named agents, skills injection, per-agent system prompts, and cross-platform
  backends (Docker, Apple `container`, smolmachines). SuperHQ's microVM
  isolation story is now partially matched by bot-bottle's `macos_container` and
  smolmachines backends. Worth watching — it targets the same security-minded
  power-user audience and moves fast.
  **Known gap in SuperHQ (user-requested, as of 2026-07-09):** A named user
  (Brian Cheong, Founder, Dunialabs.io) explicitly called out the absence of
  per-run audit logging: tool calls and network egress. Bot-bottle covers both:
  network egress is logged by pipelock/mitmproxy, and per-run op-log/audit state
  is persisted to SQLite.
 - **OneCLI** ([onecli.sh](https://onecli.sh/)) — YC-backed, GA, open-source
  (Apache-2.0, Rust) "identity gateway for AI agents": a credential/secret
  broker that holds API keys and OAuth tokens out of the agent's reach and
  injects them at the network layer (phantom-token — the agent sees a
  placeholder, the gateway swaps in the real, AES-256-GCM-encrypted credential
  at request time). Framework-agnostic and drop-in for any HTTP-calling agent,
  50+ app integrations, plus a hosted cloud tier with a per-agent dashboard and
  audit logs. Full technical breakdown in
  [`agent-credential-proxy-landscape.md`](agent-credential-proxy-landscape.md).
  **How close a competitor:** near-exact on the *single axis of agent secret
  custody* — the exact thing bot-bottle sells as "the agent never sees real
  credentials, even via `printenv`." OneCLI does that one job well, is mature
  and funded, and is *more portable* (it sits in front of anything; bot-bottle
  only helps agents launched through bot-bottle). Takeaway: bot-bottle should
  stop treating secret custody as a *unique* differentiator. But OneCLI is
  **not** a competitor to bot-bottle's actual product — it does no agent
  sandboxing (containers/microVMs), no fleet/manifest layer, no named agents /
  skills / per-agent system prompts, no multi-provider launching, no egress
  firewall.
  **Our edge:** (1) *Isolation is the product, not a proxy.* OneCLI keeps the
  key out of reach at the network layer, but the agent itself still runs
  unsandboxed — a hijacked agent behind OneCLI has full run of its host and can
  exfil captured data through any allowed host. bot-bottle runs the agent inside
  a kernel/VM-enforced sandbox, injects credentials across that same
  out-of-process boundary, *and* clamps egress with pipelock — defense in depth
  vs. a single network layer. (2) *Fleet + manifest model* with named agents,
  skills, per-agent system prompts, multi-provider and multi-backend — OneCLI
  has no equivalent. (3) *Trust posture:* OneCLI's managed tier reintroduces a
  third-party credential custodian, whereas bot-bottle's OSS-runtime +
  paid-control-plane split keeps custody inside the operator's own boundary —
  the stronger story for the security-minded self-hoster. (4) *Runs inside your
  network boundary — local/internal reach.* Because bot-bottle executes the
  agent on your own host (homelab, corporate LAN, a Tailnet) and egress is a
  manifest field, giving an agent *scoped* access to **internal** resources — a
  private Gitea, a LAN database, a Tailscale node — is just another egress-route
  line, not a networking project (the same move an operator already makes to
  reach their Tailscale services). OneCLI's OSS core can self-host too, but it's
  a credential *broker* for outbound API calls, not an agent runtime, and its
  managed tier + 50+ integrations are oriented at public SaaS — it doesn't put
  the agent behind your firewall for you. This is a reach advantage, distinct
  from the isolation ones above, and it's a wedge cloud-first agent products
  (Devin, Copilot Workspace, OneCLI Cloud) structurally can't match. **Tactical
  read:**
  adopt OneCLI's OSS core for the credential slice if building is undesirable
  (it's mature now); don't build atop its managed tier (competitor, not
  dependency); re-position bot-bottle on isolation + fleet + self-hosted custody
  rather than "we hide your secrets."
 ## What no found project does
 None combine:
 1. Named-agent manifest with per-agent env resolution (prompt / host-forward / literal), supporting multiple providers (Claude Code, Codex, Pi, arbitrary plugins)
 2. Skills directory injection
 3. Per-agent system prompts
 4. SSH-agent key forwarding without copying private keys into the container
 5. Home + project manifest merge
 6. Pluggable isolation backends: Docker (Linux/macOS), Apple `container` (macOS microVMs), smolmachines/libkrun microVMs
 7. Per-run audit log: network egress via pipelock/mitmproxy + op-log persisted to SQLite
 **In-flight directions (not yet shipped):**
 - **Forge-native dispatch (issue #317):** Gitea webhook → orchestrator spins up a bottle
  with the issue body as prompt → agent works → bottle freezes awaiting review comment →
  rehydrates on comment → tears down on PR close. The issue-to-PR lifecycle concept is not
  novel (Devin, Copilot Workspace, SWE-agent all do this as cloud services); what's
  distinct is doing it self-hosted, manifest-driven, inside bot-bottle's isolation
  primitives.
 - **Paid web control plane (issue #327):** Browser-based multi-host agent launch and
  monitoring; account-scoped bottle and agent definitions; secret custody (encrypted at
  rest, injected into the sidecar at launch, never exposed to the agent or returned by any
  read API). Monetization model: OSS runtime free, control plane paid — a standard split
  (HashiCorp, Grafana) applied to a self-hosted agent sandbox. The principled secret
  custody model (agent never sees real credentials, even via printenv) is more rigorous
  than most surveyed tools but not unprecedented.
 ## Publishing verdict
 Worth publishing. Differentiators that matter to the target audience (power
 users running parallel AI coding agent sessions with distinct personas/tooling):
 - The Python-stdlib-first, low-dependency design — competitors are npm-based,
  Rust/GUI, or Kubernetes-native.
 - Named agents with distinct skills and system prompts, not just language profiles.
 - Multi-backend isolation: Docker, Apple `container` microVMs, and
  smolmachines/libkrun — single manifest works across all three.
 - Multi-provider: Claude Code, Codex, Pi, plus an open plugin system for
  arbitrary providers.
 - SSH forwarding without key copying.
 - Per-run audit log (tool calls + network egress) — an explicitly requested gap
  in SuperHQ as of 2026-07-09.
 - Forge-native dispatch and a paid control plane (in flight) bring bot-bottle
  into the same product category as cloud services like Devin and Copilot
  Workspace — but self-hosted, with stronger isolation guarantees and a
  manifest-driven fleet model those services don't have.
 Main risk: claudebox adds manifest/agent config; SuperHQ is moving fast on the
 GUI / microVM side. The space is moving fast enough that publishing sooner is
 better if establishing prior art matters.
 Discovery will be slow without active promotion; an Anthropic Discord post or
 HN "Show HN" would do most of the work.
 ## Caveats
 - GitHub search cannot surface private or very new repos comprehensively.
 - Counts (stars, forks) were not confirmed for every project.
 - Initial research conducted 2026-05-07; SuperHQ entry added 2026-07-09; the space moves fast.
@@ -0,0 +1,204 @@
 # Scanning for malicious commits at the git-gate — and whether the semantic layer is a paid feature
 A sandboxed agent's most durable way out isn't live exfiltration — it's the
 **artifact it pushes**. Code committed through the git-gate leaves the
 sandbox and runs *later*, in CI or production, with none of the bottle's
 isolation or egress control. gitleaks covers *secrets* on that channel
 (see [`git-gate` pre-receive](../../bot_bottle/git_gate_render.py)); this
 note asks the harder question — can we scan for *malicious code* in
 commits — and the product question the answer raises: is the semantic
 (LLM) layer a decent paid feature on "git egress," alongside a paid
 human-review console for the supervise flow?
 ## Summary
 - **No scanner reliably detects malicious code.** It's undecidable in
  general and adversarial in practice — a capable agent hides a backdoor
  from any pattern scanner (and from human reviewers). So the frame is not
  "detect malice"; it's **raise the cost, cover the common/obvious cases,
  and put a human on the high-leverage ones.**
 - **Layered, ranked by ROI:** (1) supply-chain / malicious-dependency
  scanning (Socket, OSV-Scanner, GuardDog) — highest ROI, best git fit;
  (2) fast heuristic / obfuscation / dangerous-sink scanning
  (Semgrep-on-diff) — gitleaks-shaped; (3) **risk-based human gating** via
  the existing supervise plane on high-risk file classes; (4) **LLM
  semantic diff-review** as a best-effort backstop for novel backdoors.
 - **Architecture:** the git-gate's `pre-receive` is *synchronous* (it
  blocks the push), so run only fast scanners inline and push heavy
  analysis (CodeQL, full LLM review) to an **async post-push CI lane** that
  can't hold the developer hostage.
 - **Monetization verdict: yes — but the paid unit is the *governed
  git-egress review bundle*, not the raw scanner.** The pre-receive
  mechanics and the fast OSS scanners stay free (open-core social
  contract, same as gitleaks). The sell is the control-plane workflow
  around them: **managed semantic review + a web-console human-review flow
  + RBAC + audit retention + cross-run policy.** A bare per-push scan is
  borderline "single-run = free" by our own heuristic, and its detection
  accuracy is not something to sell on. Sell the *workflow and the
  governance*, not the detector.
 ## The threat: temporal escape
 This is the one containment fundamentally can't close. bot-bottle's VM
 isolation + egress DLP shrink *live* exfiltration, but the git push
 channel launders a payload past all of it: the agent commits code that
 looks benign at review time and does its work later, outside the
 perimeter — the "blind-XSS"-style temporal escape that both the "3 reasons
 sandboxing won't secure your AI agent" talk and Embroidery's "In sandboxes
 we (shouldn't) trust" call the sharpest gap. gitleaks gates *secrets* on
 this channel; malicious *code* is the uncovered surface, and it's the
 behavioral half of the isolation-vs-behavioral split noted in
 [`agent-sandbox-landscape.md`](agent-sandbox-landscape.md).
 ## Why it's fundamentally hard
 Distinguishing malicious from legitimate code is undecidable in general
 and adversarial in the specific. The underhanded-code contests show humans
 hide backdoors from *human reviewers*; a scanner reduces to regex/dataflow
 heuristics a motivated agent writes around. So "catch malicious commits"
 is the wrong success metric. The right ones: *how much did we raise the
 cost*, *did we cover the common and the obvious*, and *did a human see the
 dangerous changes before they left*.
 ## Landscape of git-pluggable approaches (ranked by ROI)
 1. **Supply-chain / malicious-dependency scanning — highest ROI.** The
   most likely agent-introduced threat is a malicious or typosquatted
   *dependency*, not a hand-written backdoor — and it's far more
   detectable. **Socket** (behavioral analysis of packages: install
   scripts, obfuscation, unexpected network/fs access, typosquats) is the
   closest thing to malicious-intent detection that actually works;
   **OSV-Scanner** (known-bad DB, fast) and **GuardDog** (PyPI/npm
   heuristics) complement it. Trigger only when a commit changes a
   lockfile/manifest → block or escalate.
 2. **Fast heuristic / obfuscation / dangerous-sink scanning.** **Semgrep**
   with a curated ruleset, scanning the *diff* (fast enough for
   pre-receive). Catches obfuscation (`eval(atob(...))`, base64/hex blobs,
   minified source), exfil primitives (`curl | sh`, reverse shells,
   DNS-exfil), and dangerous sinks (`shell=True`, `pickle.loads`, unsafe
   `yaml.load`, `child_process.exec`). Tune noisy rules to *escalate*, not
   block.
 3. **Risk-based human gating — the most robust control, already
   half-built.** The git-gate already escalates `# gitleaks:allow`
   findings to a supervisor proposal and blocks the push pending approval
   (`supervise_gitleaks_allow`, [`git_gate_render.py`](../../bot_bottle/git_gate_render.py)).
   Extend the same flow to **high-risk file classes**: any commit touching
   CI/build/deploy scripts, auth/crypto code, egress config, or
   adding/changing dependencies → route to `./cli.py supervise`. This is
   attribution/policy, not detection, and it's the strongest thing here —
   a human on exactly the temporal-escape surfaces.
 4. **LLM semantic diff-review — the behavioral backstop.** The only
   approach with a shot at a novel, benign-looking backdoor: a model
   reviews the diff for a backdoor / exfiltration / obfuscated payload /
   dangerous behavior. This is the behavioral-detection thesis applied to
   the *artifact* (the diff) rather than the agent's reasoning. Real
   caveats: false positives and negatives, latency/cost, it can be
   prompt-injected by hostile content *in the diff itself*, and it invites
   over-trust. Useful, never a guarantee.
 **Not for this job:** CodeQL, Trivy, Grype, Bandit. They find *known
 vulns and insecure patterns* (bugs), not deliberate backdoors, and the
 powerful ones (CodeQL taint) need a build + database — too heavy for a
 synchronous gate. They belong in the async CI lane if at all.
 ## Fit into bot-bottle's git-gate
 The `pre-receive` hook today is: gitleaks-scan each ref → escalate
 `# gitleaks:allow` findings to supervise → forward to upstream
 ([`git_gate_render.py`](../../bot_bottle/git_gate_render.py)). The
 additions slot in cleanly:
 - **Inline (fast), before forward:** a dep-scan phase (on manifest/lockfile
  change) and a Semgrep-diff phase. Findings block or open a supervise
  proposal, same shape as gitleaks.
 - **New supervise tool types** alongside the existing
  `egress-block/allow`, `gitleaks-allow`, `egress-token-allow`
  ([`supervise_types.py`](../../bot_bottle/supervise_types.py)) — e.g. a
  `commit-review` proposal for risky-file-class gating and for semantic
  review. The supervise plane is already the right abstraction; this is
  another *producer* feeding it, and [`supervise_server.py`](../../bot_bottle/supervise_server.py)
  (JSON-RPC) is already the console backend.
 - **Async lane (heavy):** full LLM review + any CodeQL run out of band
  after the push, feeding the same review/audit surface, so the
  synchronous gate stays fast.
 ## The product question: paid feature on git egress?
 Restating the open-core line bot-bottle runs on: *give away the
 sandbox/runtime, charge for the control plane; single-run/single-node =
 free, cross-run aggregation + central enforcement + identity/fleet = paid;
 the moat is uniform egress audit + secret custody + policy across
 untrusted agents.*
 Against that line, the split is clean:
 **Free (OSS runtime — the trust funnel):**
 - the `pre-receive` gate mechanics and gitleaks;
 - wiring the OSS scanners (Socket CLI / OSV-Scanner / Semgrep);
 - the CLI supervise flow.
 Keeping the raw scanners free is the same social contract as gitleaks and
 preserves the bottom-up distribution funnel.
 **Paid (the governed git-egress bundle — the control plane):**
 - **Managed semantic diff-review** — hosted inference + a curated,
  maintained malicious-pattern/policy set. This is *capability* (metered),
  not *insurance* — the thing individuals actually pay for. Position it as
  **governed code-egress review**, not "we resell inference" (the
  monetization notes explicitly warn against reselling compute).
 - **The web-console supervise/review flow — the strongest anchor.** Turn
  the CLI `./cli.py supervise` approval into a real review surface:
  rendered diff + finding context, approve/reject, **who-approved audit
  trail, RBAC on approvers, mobile/phone-control** (ties to the
  dashboard/vault north star). This is "central enforcement +
  identity/fleet = paid" almost verbatim — and it generalizes across
  *every* supervise proposal (egress block/allow, gitleaks-allow,
  commit-review), so it's worth building for the whole plane, with the
  semantic check as one producer.
 - **Cross-run governance:** fleet-wide policy for what escalates,
  review-decision history/search/export, and drift alerts.
 **Why it fits the moat rather than bolting on:** a git push *is* an egress
 channel. A semantic review + human approval + audit on it extends the
 uniform "egress audit + custody + policy across untrusted agents" wedge to
 **code artifacts** — the same product, applied to the one channel gitleaks
 only half-covers. That's on-moat, not a detour.
 **The honest nuance (don't oversell):** a bare per-push LLM scan is
 arguably *free* by the single-run heuristic, and its detection accuracy is
 not defensible to charge for. The paid value is the **governance around
 it** — the console, RBAC, audit retention, cross-run policy — plus the
 managed capability. Sell the *review-and-approve-and-audit workflow*; let
 the detector be explicitly best-effort. And per the monetization
 guardrail, the "anti-corporate" free crowd must not veto these team
 features: the review console + RBAC + audit *are* the monetization.
 ## Recommendation
 1. **Land the free layer first.** Add the dep-scan and Semgrep-diff phases
   to `pre-receive`, and extend supervise to risky-file-class gating —
   reuses existing machinery, immediate value, stays OSS.
 2. **Build the supervise web console** over `supervise_server`'s JSON-RPC
   (already the Phase-1 move in the monetization path). This is the paid
   anchor and it serves *all* proposal types, not just commit review.
 3. **Add managed semantic diff-review as a paid producer** feeding that
   console — "governed code-egress review," metered, explicitly
   best-effort on detection.
 4. **Don't oversell detection.** Market the workflow (review + approve +
   audit) and the cross-run policy/RBAC, where the value is real and
   defensible; keep the raw scanners open.
 ## Sources / references
 - [`agent-sandbox-landscape.md`](agent-sandbox-landscape.md) — the
  egress-DLP gap and isolation-vs-behavioral framing.
 - Git-gate internals: [`git_gate_render.py`](../../bot_bottle/git_gate_render.py),
  [`supervise_types.py`](../../bot_bottle/supervise_types.py),
  [`supervise_server.py`](../../bot_bottle/supervise_server.py).
 - External tools: Socket (socket.dev), OSV-Scanner (google/osv-scanner),
  GuardDog (DataDog/guarddog), Semgrep (semgrep/semgrep).
 - Threat framing: "3 reasons sandboxing won't secure your AI agent"
  (youtube TsYDazwHJ6U); Embroidery, "In sandboxes we (shouldn't) trust."
 - The authoritative monetization/positioning analysis (the open-core line,
  the wedge, single-run-free/cross-run-paid) lives in the **separate
  `bot-bottle-console` repo**, not this one — cited here from memory, not
  linked.
@@ -1,6 +1,6 @@
 # smolmachines as a VM backend for bot-bottle
-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
 Evaluation of whether [smolmachines](https://smolmachines.com/) would
 simplify the macOS agent-VM-isolation work spelled out in
@@ -0,0 +1,8 @@
 [build-system]
 requires = ["setuptools>=68"]
 build-backend = "setuptools.build_meta"
 [project]
 name = "bot-bottle"
 version = "0.0.0"
 requires-python = ">=3.11"
@@ -26,8 +26,10 @@ rm -f .coverage
 echo "== unit ==" >&2
 "$PY" -m coverage run -m unittest discover -t . -s tests/unit
-echo "== integration (skips without Docker) ==" >&2
+echo "== integration (firecracker; skips docker tests) ==" >&2
-"$PY" -m coverage run --append -m unittest discover -t . -s tests/integration
+BOT_BOTTLE_BACKEND=firecracker SKIP_DOCKER_TESTS=1 \
    BOT_BOTTLE_INFRA_ARTIFACT_DIR="${BOT_BOTTLE_CI_INFRA_ARTIFACT_DIR:-}" \
    "$PY" -m coverage run --append -m unittest discover -t . -s tests/integration
 echo "== combined report ==" >&2
 "$PY" -m coverage report -m
@@ -0,0 +1,135 @@
 #!/usr/bin/env python3
 """Enforce the repository's issue/PR metadata policy in Gitea Actions."""
 from __future__ import annotations
 import argparse
 import json
 import os
 import re
 import urllib.error
 import urllib.request
 from pathlib import Path
 from typing import Any
 ISSUE_REFERENCE = re.compile(
    r"(?im)\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|part\s+of|"
    r"related\s+to|refs?|references)\s+#(\d+)\b"
 )
 TRIAGE_LABEL = "Status/Needs Triage"
 def deliberate_issue_numbers(title: str, body: str) -> set[int]:
    """Return same-repository issue numbers referenced intentionally."""
    return {int(match) for match in ISSUE_REFERENCE.findall(f"{title}\n{body}")}
 class GiteaApi:
    """Small API client using the Actions-provided repository token."""
    def __init__(self, api_url: str, repository: str, token: str) -> None:
        self.base = f"{api_url.rstrip('/')}/repos/{repository}"
        self.token = token
    def request(self, method: str, path: str, payload: object | None = None) -> Any:
        data = None if payload is None else json.dumps(payload).encode()
        request = urllib.request.Request(
            f"{self.base}{path}",
            data=data,
            method=method,
            headers={
                "Authorization": f"token {self.token}",
                "Content-Type": "application/json",
            },
        )
        with urllib.request.urlopen(request, timeout=15) as response:
            if response.status == 204:
                return None
            return json.load(response)
 def check_pull_request(event: dict[str, Any], api: GiteaApi) -> list[str]:
    """Return policy violations for a pull_request event."""
    pull = event["pull_request"]
    errors: list[str] = []
    labels = pull.get("labels") or []
    if labels:
        errors.append(
            "PRs must be unlabeled; put tracker metadata on the linked issue "
            f"(found: {', '.join(label['name'] for label in labels)})."
        )
    numbers = deliberate_issue_numbers(pull.get("title", ""), pull.get("body", ""))
    if not numbers:
        errors.append(
            "PR must reference an issue with Closes/Fixes/Resolves #N, "
            "Part of #N, Related to #N, Refs #N, or References #N."
        )
        return errors
    real_issues = 0
    for number in sorted(numbers):
        try:
            item = api.request("GET", f"/issues/{number}")
        except urllib.error.HTTPError as error:
            if error.code == 404:
                errors.append(f"Referenced issue #{number} does not exist.")
                continue
            raise
        if item.get("pull_request") is not None:
            errors.append(f"#{number} is a pull request, not an issue.")
        else:
            real_issues += 1
    if not real_issues and not errors:
        errors.append("PR must reference at least one real issue.")
    return errors
 def ensure_issue_label(event: dict[str, Any], api: GiteaApi) -> bool:
    """Apply the triage label if an issue event leaves the issue unlabeled."""
    issue = event["issue"]
    if issue.get("pull_request") is not None or issue.get("labels"):
        return False
    labels = api.request("GET", "/labels?limit=100")
    triage = next((label for label in labels if label["name"] == TRIAGE_LABEL), None)
    if triage is None:
        raise RuntimeError(f"repository label {TRIAGE_LABEL!r} does not exist")
    api.request("POST", f"/issues/{issue['number']}/labels", {"labels": [triage["id"]]})
    return True
 def _load_event(path: str) -> dict[str, Any]:
    return json.loads(Path(path).read_text(encoding="utf-8"))
 def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("command", choices=("check-pr", "label-issue"))
    parser.add_argument("--event", default=os.environ.get("GITHUB_EVENT_PATH"))
    args = parser.parse_args()
    if not args.event:
        parser.error("--event or GITHUB_EVENT_PATH is required")
    api = GiteaApi(
        os.environ["GITHUB_API_URL"],
        os.environ["GITHUB_REPOSITORY"],
        os.environ["GITHUB_TOKEN"],
    )
    event = _load_event(args.event)
    if args.command == "check-pr":
        errors = check_pull_request(event, api)
        if errors:
            print("\n".join(f"::error::{error}" for error in errors))
            return 1
        print("PR tracker policy passed.")
        return 0
    changed = ensure_issue_label(event, api)
    print(f"Applied {TRIAGE_LABEL}." if changed else "Issue already has a label.")
    return 0
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,23 @@
 """Resolved paths to system binaries used by subprocess-based tests.
 NixOS and other non-FHS hosts don't populate ``/bin`` (there is no
 ``/bin/sleep``), so tests that spawn real short-lived helper processes
 must resolve the binary from ``PATH`` rather than hardcoding an FHS path.
 Import the resolved constant (e.g. ``SLEEP``) instead of writing
 ``/bin/sleep`` inline.
 """
 from __future__ import annotations
 import shutil
 def resolve(name: str, fallback: str) -> str:
    """Absolute path to ``name`` from ``PATH``; ``fallback`` on FHS hosts
    where the binary isn't on ``PATH`` but lives at a known ``/bin`` path."""
    return shutil.which(name) or fallback
 # Real ``sleep`` binary. ``/bin/sleep`` is absent on NixOS; resolve from
 # PATH so subprocess tests run instead of erroring with FileNotFoundError.
 SLEEP = resolve("sleep", "/bin/sleep")
@@ -2,24 +2,44 @@
 from __future__ import annotations
 import os
 import shutil
 import subprocess
 import unittest
 def docker_available() -> bool:
    if os.environ.get("SKIP_DOCKER_TESTS"):
        return False
    if shutil.which("docker") is None:
        return False
-    return (
+    try:
-        subprocess.run(
+        return (
-            ["docker", "info"],
+            subprocess.run(
-            stdout=subprocess.DEVNULL,
+                ["docker", "info"],
-            stderr=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
-            check=False,
+                stderr=subprocess.DEVNULL,
-        ).returncode
+                check=False,
-        == 0
+                timeout=5,
-    )
+            ).returncode
            == 0
        )
    except subprocess.TimeoutExpired:
        return False
 def skip_unless_docker(reason: str = "docker unreachable"):
    return unittest.skipUnless(docker_available(), reason)
 def skip_unless_docker_or_firecracker(
    reason: str = "neither Docker nor Firecracker selected",
 ):
    """Skip a backend-agnostic test unless one supported backend can run.
    Firecracker does not require the host Docker daemon. The KVM coverage job
    deliberately sets ``SKIP_DOCKER_TESTS`` to exclude Docker-only integration
    classes while still exercising this path.
    """
    firecracker_selected = os.environ.get("BOT_BOTTLE_BACKEND") == "firecracker"
    return unittest.skipUnless(firecracker_selected or docker_available(), reason)
@@ -86,13 +86,12 @@ class TestGatewayImage(unittest.TestCase):
        self.assertIn("Mitmproxy", out)
    def test_python_imports_supervise_module(self):
-        # The bundle's supervise daemon imports `supervise` as a
+        # The supervise daemon is installed as part of the bot_bottle
-        # same-directory sibling of `supervise_server`. Probe the
+        # package (5ad3449), not as flat sibling modules under /app.
-        # import resolves with `python3 -c` from /app (the
+        # Probe that the package imports resolve inside the image.
        # Dockerfile's WORKDIR).
        rc, out = self._run_in_image(
            "python3", "-c",
-            "import supervise; import supervise_server; print('ok')",
+            "from bot_bottle import supervise, supervise_server; print('ok')",
        )
        self.assertEqual(0, rc, msg=out)
        self.assertIn("ok", out)
@@ -0,0 +1,153 @@
 """Integration: the Docker orchestrator's control plane enforces the
 per-host auth secret against a real container (issue #400).
 Unit tests exercise `dispatch()` in-process, socket-free. This starts the
 actual orchestrator + gateway as Docker containers and drives the real HTTP
 server over its published loopback port, the same path an agent sharing the
 gateway network — or the trusted host CLI — would use.
 Gated on a reachable Docker daemon. Uses unique container/network names,
 test-only image tags (never the production `:latest` ones, so a rebuild
 here can't make `_running_image_is_current()` see a real host's running
 gateway as stale and force-recreate it), and a throwaway `BOT_BOTTLE_ROOT`
 so a run never touches or collides with a real per-host orchestrator or
 gateway. The whole stack is brought up once for the class (`setUpClass`),
 not per test method — every test here is a read-only check against the
 same running control plane.
 """
 from __future__ import annotations
 import os
 import secrets
 import subprocess
 import tempfile
 import unittest
 from pathlib import Path
 from bot_bottle.orchestrator.client import OrchestratorClient
 from bot_bottle.orchestrator.lifecycle import OrchestratorService
 from bot_bottle.paths import host_control_plane_token
 from tests._docker import skip_unless_docker
 # Fixed (not per-run-suffixed) so repeated runs reuse the same layer-cached
 # image instead of leaking a new dangling tag on every invocation.
 _TEST_ORCHESTRATOR_IMAGE = "bot-bottle-orchestrator:itest"
 _TEST_GATEWAY_IMAGE = "bot-bottle-gateway:itest"
 _TEST_INFRA_IMAGE = "bot-bottle-infra:itest"
@skip_unless_docker()
@unittest.skipIf(
    os.environ.get("GITEA_ACTIONS") == "true",
    "skipped under act_runner: the orchestrator container bind-mounts the repo "
    "path into a container on the socket-shared host daemon, which can't see the "
    "runner's /workspace — same host-bind-mount constraint as the other "
    "bottle-bringup integration tests",
 )
 class TestDockerControlPlaneAuthIntegration(unittest.TestCase):
    @classmethod
    def setUpClass(cls) -> None:
        suffix = secrets.token_hex(4)
        cls._tmp = tempfile.TemporaryDirectory()  # pylint: disable=consider-using-with
        cls.addClassCleanup(cls._tmp.cleanup)
        # host_control_plane_token() — both the token read below and the one
        # OrchestratorService injects into the container's env — resolves its
        # path via the *ambient* BOT_BOTTLE_ROOT env var, not the host_root
        # kwarg passed to the constructor (that kwarg only controls the DB
        # bind-mount destination). Without pointing the env var at the same
        # throwaway dir, this "isolated" test would read/write the developer's
        # real ~/.bot-bottle/control-plane-token.
        previous_root = os.environ.get("BOT_BOTTLE_ROOT")
        def _restore_root() -> None:
            if previous_root is None:
                os.environ.pop("BOT_BOTTLE_ROOT", None)
            else:
                os.environ["BOT_BOTTLE_ROOT"] = previous_root
        os.environ["BOT_BOTTLE_ROOT"] = cls._tmp.name
        cls.addClassCleanup(_restore_root)
        infra_name = f"bot-bottle-infra-itest-{suffix}"
        network = f"bot-bottle-net-itest-{suffix}"
        host_root = Path(cls._tmp.name)
        cls.addClassCleanup(
            cls._teardown_docker, infra_name, network, host_root
        )
        cls.svc = OrchestratorService(
            infra_name=infra_name,
            network=network,
            image=_TEST_INFRA_IMAGE,
            port=20000 + secrets.randbelow(10000),
            host_root=host_root,
        )
        cls.svc.ensure_running()
        cls.token = host_control_plane_token()
    @staticmethod
    def _teardown_docker(
        infra_name: str, network: str, host_root: Path
    ) -> None:
        subprocess.run(
            ["docker", "rm", "--force", infra_name],
            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
        )
        subprocess.run(
            ["docker", "network", "rm", network],
            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
        )
        # The infra container (no USER directive) wrote the registry
        # DB as root into the throwaway host_root; chown it back so the
        # (non-root) tempdir cleanup can remove it. Same workaround
        # test_multitenant_isolation.py uses for the identical bind mount.
        subprocess.run(
            ["docker", "run", "--rm", "-v", f"{host_root}:/r",
             "--entrypoint", "chown", _TEST_INFRA_IMAGE, "-R",
             f"{os.getuid()}:{os.getgid()}", "/r"],
            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
        )
    def _request(
        self, method: str, path: str, *, token: str = ""
    ) -> tuple[int, dict[str, object]]:
        # Reuses the real host-side client's request/response handling rather
        # than hand-rolling urllib here; _request (not one of the named
        # wrapper methods) is what exposes raw status codes for arbitrary
        # paths/tokens, which is exactly what these auth-boundary tests need.
        client = OrchestratorClient(self.svc.url, auth_token=token)
        return client._request(method, path)  # pylint: disable=protected-access
    def test_health_is_open_without_a_token(self) -> None:
        status, payload = self._request("GET", "/health")
        self.assertEqual(200, status)
        self.assertEqual("ok", payload["status"])
    def test_bottles_rejects_a_caller_with_no_token(self) -> None:
        """The enumeration attack from issue #400: an agent sharing the
        gateway network could list every bottle + its policy with no
        credential at all."""
        status, _ = self._request("GET", "/bottles")
        self.assertEqual(401, status)
    def test_bottles_rejects_a_wrong_token(self) -> None:
        status, _ = self._request("GET", "/bottles", token="not-the-real-secret")
        self.assertEqual(401, status)
    def test_bottles_accepts_the_real_token(self) -> None:
        status, payload = self._request("GET", "/bottles", token=self.token)
        self.assertEqual(200, status)
        self.assertEqual([], payload["bottles"])
    def test_resolve_rejects_a_caller_with_no_token(self) -> None:
        """The credential-lift attack from issue #400: an agent could POST
        /resolve directly and read back the upstream tokens it's never meant
        to see."""
        status, _ = self._request("POST", "/resolve")
        self.assertEqual(401, status)
 if __name__ == "__main__":
    unittest.main()
--- a/Show More
+++ b/Show More