docs: redesign forge identity trust boundary

Revised per PR #480 (#5607 owner clarification + #5608 codex resolution;
#5612 directs the update):

- The audit row no longer implies upstream observation or agent-only
  authorship. Reworded the guarantee: the row cryptographically binds
  commit bytes (control-plane-RECOMPUTED SHA) to access to the activation
  signing key, and binds that key to control-plane-owned activation
  metadata. An agent can sign arbitrary contents but cannot verify as a
  different activation or choose the recorded metadata.
- Control plane accepts gateway-delivered opaque bytes, independently
  recomputes the Git object ID, verifies the embedded signature against
  the activation key, and stamps its own metadata. Trusts no gateway
  SHA/key/verdict/metadata. No upstream fetch.
- Purged overclaims: removed "a compromised gateway cannot fabricate an
  audit binding" (the sidecar holds the signing capability, so it can —
  and that's acceptable under the intended guarantee), plus "accepted
  push" / "introduced upstream" framing.
- Resolved the control-plane-transport open question in-PRD (was left
  open; codex asked to resolve): transport is gateway bytes +
  recompute + verify; mirror-read is no stronger.

Issue: #423

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.coveragerc

@@ -20,9 +20,3 @@ omit =
     bot_bottle/cli/tui.py
     bot_bottle/cli/init.py
     tests/*
-    # Build-time only: setuptools invokes it out-of-process to build the
-    # wheel/sdist (it's never imported by the running app), so in-process
-    # coverage can't reach it. Its one job — bundling the root resources into
-    # bot_bottle/_resources/ — is exercised end-to-end by test_wheel_install,
-    # which builds and installs a real wheel and checks the result.
-    setup.py

.gitea/workflows/canaries.yml

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

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

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

.gitea/workflows/prd-number.yml

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

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

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

.gitea/workflows/test.yml

@@ -1,6 +1,21 @@
-# Run the automated test gate when package or runtime inputs change on a PR
-# or on push to main. Privileged self-hosted backends live in the manually
-# dispatched pre-release-test workflow.
+# Run the project's test suite when package or runtime inputs change on a PR
+# or on push to main.
+#
+# The suite uses stdlib `unittest` discovery — no external Python
+# dependencies are required to execute it. Tests are split by directory:
+#
+#   tests/unit/         — pure unit tests; always run
+#   tests/integration/  — need a reachable backend; skip cleanly when
+#                         the backend isn't available on the runner
+#   tests/canaries/     — upstream regression canaries; run on a separate
+#                         schedule (see canaries.yml), not here
+#
+# Each test job runs once under coverage and uploads a small .coverage.*
+# artifact. The `coverage` job combines them — no test reruns, no KVM
+# dependency on that job. For main-branch pushes only, the tested rootfs
+# and matching dropbear are uploaded so `publish-infra` can publish the
+# byte-identical artifact that was tested. PRs avoid the ~194 MB rootfs
+# transfer entirely.
 
 name: test
 
@@ -12,43 +27,32 @@ on:
       - 'bot_bottle/**'
       - 'tests/**/*.py'
       - 'cli.py'
-      - 'install.sh'
-      - 'setup.py'
-      - 'MANIFEST.in'
-      - 'flake.nix'
-      - 'nix/firecracker-netpool.nix'
       - 'scripts/coverage.sh'
       - 'scripts/critical-modules.txt'
-      - 'scripts/**/*.py'
+      - 'scripts/diff_coverage.py'
+      - 'scripts/tracker_policy.py'
       - 'scripts/firecracker-netpool.sh'
       - 'Dockerfile*'
       - 'pyproject.toml'
       - 'requirements-dev.txt'
       - '.coveragerc'
       - '.dockerignore'
-      - '.gitea/workflows/test.yml'
-      - '.gitea/workflows/pre-release-test.yml'
   pull_request:
     paths:
       - 'bot_bottle/**'
       - 'tests/**/*.py'
       - 'cli.py'
-      - 'install.sh'
-      - 'setup.py'
-      - 'MANIFEST.in'
-      - 'flake.nix'
-      - 'nix/firecracker-netpool.nix'
       - 'scripts/coverage.sh'
       - 'scripts/critical-modules.txt'
-      - 'scripts/**/*.py'
+      - 'scripts/diff_coverage.py'
+      - 'scripts/tracker_policy.py'
       - 'scripts/firecracker-netpool.sh'
       - 'Dockerfile*'
       - 'pyproject.toml'
       - 'requirements-dev.txt'
       - '.coveragerc'
       - '.dockerignore'
-      - '.gitea/workflows/test.yml'
-      - '.gitea/workflows/pre-release-test.yml'
+  workflow_dispatch:
 
 jobs:
   unit:
@@ -57,6 +61,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      # No actions/setup-python: the runner image already ships Python 3.12,
+      # and older act_runner engines mishandle setup-python's PATH (coverage
+      # lands in one interpreter, `python3` resolves to another). Install
+      # straight into the ephemeral job container's system Python —
+      # --break-system-packages is safe because the container is disposable.
       - name: Install dev requirements
         run: python3 -m pip install --break-system-packages -r requirements-dev.txt
 
@@ -70,6 +79,10 @@ jobs:
           COVERAGE_FILE: ${{ github.workspace }}/.coverage.unit
         run: python3 -m coverage report -m
 
+      # upload-artifact@v3's glob skips dotfiles, so a bare `.coverage.unit`
+      # silently uploads nothing ("No files were found"). Stage it under a
+      # non-dot name; the coverage job renames it back before `coverage
+      # combine`. `cp` also fails loudly if coverage never wrote the file.
       - name: Stage unit coverage for upload
         run: cp .coverage.unit coverage-unit.dat
 
@@ -81,16 +94,21 @@ jobs:
 
   integration-docker:
     runs-on: ubuntu-latest
-    concurrency:
-      group: integration-docker-infra
-      cancel-in-progress: false
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
+      # No actions/setup-python (see the note in the `unit` job); the
+      # container's system Python 3.12 runs the stdlib test suite directly.
       - name: Install coverage
         run: python3 -m pip install --break-system-packages coverage
 
+      # Fail loudly if the backend this job promises isn't actually usable,
+      # rather than letting every test silently `unittest.skip` and the job
+      # go green on zero coverage. `backend status` prints a clear per-check
+      # summary (docker on PATH, daemon reachable) and exits non-zero when a
+      # prerequisite is missing — the same readiness check the skip guards
+      # gate on via `has_backend`.
       - name: Preflight — Docker backend is ready
         run: |
           python3 --version
@@ -100,34 +118,9 @@ jobs:
         env:
           BOT_BOTTLE_BACKEND: docker
           COVERAGE_FILE: ${{ github.workspace }}/.coverage.docker
-        run: |
-          set -euo pipefail
-          # act_runner executes this job in a container while sharing the host
-          # Docker socket. Attach control-plane siblings to the job's network,
-          # and use named volumes for state the host daemon must mount.
-          DOCKER_CLIENT_NETWORK=$(
-            docker inspect "$(hostname)" |
-              python3 -c 'import json,sys; n=json.load(sys.stdin)[0]["NetworkSettings"]["Networks"]; print(next(iter(n)))'
-          )
-          test -n "$DOCKER_CLIENT_NETWORK"
-          RUN_KEY="${GITHUB_RUN_ID:-${GITHUB_RUN_NUMBER:-0}}"
-          export NO_PROXY="*"
-          export no_proxy="*"
-          export BOT_BOTTLE_DOCKER_CLIENT_NETWORK="$DOCKER_CLIENT_NETWORK"
-          export BOT_BOTTLE_DOCKER_ROOT_MOUNT="bot-bottle-ci-root-$RUN_KEY"
-          export BOT_BOTTLE_DOCKER_CA_MOUNT="bot-bottle-ci-ca-$RUN_KEY"
-          python3 -m coverage run -m scripts.unittest_gate \
-            -t . -s tests/integration -v \
-            --minimum-executed 22 --fail-on-skip
-
-      - name: Clean Docker integration volumes
-        if: always()
-        run: |
-          RUN_KEY="${GITHUB_RUN_ID:-${GITHUB_RUN_NUMBER:-0}}"
-          docker volume rm --force \
-            "bot-bottle-ci-root-$RUN_KEY" \
-            "bot-bottle-ci-ca-$RUN_KEY" 2>/dev/null || true
+        run: python3 -m coverage run -m unittest discover -t . -s tests/integration -v
 
+      # Non-dot name so upload-artifact's dotfile-skipping glob picks it up.
       - name: Stage docker coverage for upload
         run: cp .coverage.docker coverage-docker.dat
 
@@ -137,10 +130,107 @@ jobs:
           name: coverage-docker
           path: coverage-docker.dat
 
+  # Integration tests against the Firecracker backend. Runs on a self-hosted
+  # KVM runner (label `kvm`) where /dev/kvm and the TAP/nft pool are available.
+  #
+  # Restricted to same-repo PRs, push to main, and workflow_dispatch — fork
+  # PRs don't execute untrusted code on the privileged runner.
+  #
+  # Runner prerequisites (provision once; see README "Firecracker on Linux"):
+  # `firecracker` on PATH, `/dev/kvm` accessible, cached kernel +
+  # static dropbear at /var/cache/bot-bottle-fc/dropbear, and the pool as a
+  # persistent systemd unit.
+  #
+  # The infra candidate is built here directly (no artifact download) to
+  # eliminate the ~70 s ubuntu-latest upload + ~83 s combined download that
+  # the old build-infra → integration-firecracker + coverage chain incurred.
+  # For main-branch pushes the tested rootfs and matching dropbear are
+  # uploaded so publish-infra can publish the byte-identical artifact; PRs
+  # skip those uploads entirely.
+  integration-firecracker:
+    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: Build infra candidate from this checkout
+        env:
+          BOT_BOTTLE_FC_DROPBEAR: /var/cache/bot-bottle-fc/dropbear
+        run: python3 -m bot_bottle.backend.firecracker.publish_infra --output infra-candidate --reuse-published
+
+      - name: Replace the persistent infra VM with the candidate
+        run: python3 -c 'from bot_bottle.backend.firecracker import infra_vm; infra_vm.stop()'
+
+      # No dev-requirements install: `coverage` is already provided by the
+      # self-hosted runner's Nix python env, and that env has no `pip`
+      # module to install into anyway.
+      - name: Run integration tests (firecracker) with coverage
+        env:
+          BOT_BOTTLE_BACKEND: firecracker
+          BOT_BOTTLE_INFRA_ARTIFACT_DIR: ${{ github.workspace }}/infra-candidate
+          COVERAGE_FILE: ${{ github.workspace }}/.coverage.firecracker
+        run: python3 -m coverage run -m unittest discover -t . -s tests/integration -v
+
+      # Non-dot name so upload-artifact's dotfile-skipping glob picks it up.
+      - name: Stage firecracker coverage for upload
+        run: cp .coverage.firecracker coverage-firecracker.dat
+
+      - name: Upload firecracker coverage artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: coverage-firecracker
+          path: coverage-firecracker.dat
+
+      # Only upload the large rootfs artifact on main-branch pushes;
+      # PRs avoid the ~194 MB transfer. publish-infra only runs on main
+      # and downloads these to publish the byte-identical tested rootfs.
+      - name: Upload tested rootfs (main branch only)
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-artifact@v3
+        with:
+          name: infra-candidate
+          path: infra-candidate/
+
+      - name: Upload dropbear for publish verification (main branch only)
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-artifact@v3
+        with:
+          name: firecracker-inputs
+          path: /var/cache/bot-bottle-fc/dropbear
+
+  # Combined coverage gate: aggregates .coverage.* artifacts uploaded by each
+  # test job, then runs the diff-coverage gate (new/changed lines >= 90%).
+  #
+  # Runs on ubuntu-latest — no KVM needed, no test reruns. Coverage files use
+  # relative_files = True (.coveragerc) so they combine cleanly across runners.
+  # Each test job sets COVERAGE_FILE to an absolute path so coverage.py writes
+  # to a known location that upload-artifact can find regardless of runner env.
+  #
+  # Restricted to the same events as integration-firecracker: it depends on
+  # that job's coverage artifact and skips for fork PRs alongside it.
   coverage:
-    needs: [unit, integration-docker]
+    needs: [unit, integration-docker, integration-firecracker]
     timeout-minutes: 15
     runs-on: ubuntu-latest
+    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
@@ -162,15 +252,55 @@ jobs:
           name: coverage-docker
           path: ${{ github.workspace }}
 
+      - name: Download firecracker coverage artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: coverage-firecracker
+          path: ${{ github.workspace }}
+
+      # Rename the non-dot upload names back to the .coverage.* files that
+      # `coverage combine` discovers (see the staging steps in each test job).
       - name: Reassemble coverage data files
         run: |
           mv coverage-unit.dat .coverage.unit
           mv coverage-docker.dat .coverage.docker
+          mv coverage-firecracker.dat .coverage.firecracker
 
-      - name: Combined coverage (unit + docker integration)
+      - name: Combined coverage (unit + integration, incl. firecracker)
         run: PYTHON=python3 bash scripts/coverage.sh aggregate critical
 
       - name: Diff-coverage gate (changed lines >= 90%)
         run: |
           git fetch --no-tags origin main:refs/remotes/origin/main
           python3 scripts/diff_coverage.py --base origin/main --min 90
+
+  publish-infra:
+    needs: [unit, integration-docker, integration-firecracker, 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 rootfs
+        uses: actions/download-artifact@v3
+        with:
+          name: infra-candidate
+          path: infra-candidate
+
+      # publish_infra re-derives the version from the checkout to confirm the
+      # bundle matches before uploading, and the version hashes the dropbear
+      # bytes. Download the SAME dropbear integration-firecracker used, or
+      # the recheck computes a "<missing>"-dropbear version and rejects the
+      # candidate.
+      - name: Download the staged dropbear (matches build'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

.gitea/workflows/update-badges.yml

@@ -33,28 +33,19 @@ jobs:
       - name: Run coverage and extract percentage
         id: coverage
         run: |
-          set -euo pipefail
-          # Never publish a badge from a failed or partial test run.
-          python3 -m coverage run -m unittest discover -t . -s tests/unit
-          REPORT=$(python3 -m coverage report)
-          printf '%s\n' "$REPORT"
-          PERCENT=$(printf '%s\n' "$REPORT" | awk '$1 == "TOTAL" {gsub("%", "", $NF); print $NF}')
-          test -n "$PERCENT"
+          python3 -m coverage run -m unittest discover -t . -s tests/unit > /dev/null 2>&1 || true
+          PERCENT=$(python3 -m coverage report 2>/dev/null | grep '^TOTAL' | grep -oP '\d+(?=%)' | tail -1)
           echo "percent=$PERCENT" >> $GITHUB_OUTPUT
           echo "Coverage: $PERCENT%"
 
       - name: Extract core (critical-module) coverage percentage
         id: core_coverage
         run: |
-          set -euo pipefail
           # Reuses the .coverage data from the previous step. The core list is
-          # validated single source of truth. Fail if a listed path disappeared
-          # or if the measured core falls below ADR 0004's 90% minimum.
-          INCLUDE=$(python3 scripts/critical_modules.py)
-          REPORT=$(python3 -m coverage report --include="$INCLUDE" --fail-under=90)
-          printf '%s\n' "$REPORT"
-          PERCENT=$(printf '%s\n' "$REPORT" | awk '$1 == "TOTAL" {gsub("%", "", $NF); print $NF}')
-          test -n "$PERCENT"
+          # the single source of truth in scripts/critical-modules.txt; every
+          # core module is unit-tested, so the unit-only run is accurate for it.
+          INCLUDE=$(grep -vE '^[[:space:]]*(#|$)' scripts/critical-modules.txt | paste -sd, -)
+          PERCENT=$(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%"
 

.gitignore

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

AGENTS.md

@@ -44,10 +44,10 @@ backend remains available with `BOT_BOTTLE_BACKEND=docker` or
 
 - Three kinds of doc, each with its own conventions in-folder; see
   `docs/README.md` for when to write which:
-  - **PRDs** (`docs/prds/`) — one feature per file. A draft may initially
-    use `prd-new-<kebab>.md`, but its author must assign the next
-    sequential number before merge; CI rejects unnumbered PRDs. A
-    `Status:` line tracks lifecycle: Draft → Active (shipped to `main`) →
+  - **PRDs** (`docs/prds/`) — one feature per file. While a PR is open
+    the file is named `prd-new-<kebab>.md`; CI assigns a sequential
+    number on merge to `main` and renames it. A `Status:` line tracks
+    lifecycle: Draft → Active (shipped to `main`) →
     Superseded/Retargeted. Format in `docs/prds/README.md`.
   - **Research notes** (`docs/research/`) — opinionated investigations;
     unnumbered kebab-case, freeform and verdict-first. See

MANIFEST.in

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

README.md

@@ -30,7 +30,7 @@
 
 ## Architecture
 
-On the default macOS Apple Container backend, a bottle is an agent container on a host-only internal network plus a gateway attached to both that internal network and a NAT egress network. The agent gets HTTP(S)_PROXY and CA bundle env vars pointing at the gateway's internal-network IP, so HTTP/HTTPS traffic flows through the gateway instead of direct egress. git-gate runs over the gateway's consolidated `git-http` daemon (the legacy per-bottle `git://` daemon is not used on this backend); keys are provisioned dynamically at launch and revoked on teardown.
+On the default macOS Apple Container backend, a bottle is an agent container on a host-only internal network plus a gateway attached to both that internal network and a NAT egress network. The agent gets HTTP(S)_PROXY and CA bundle env vars pointing at the gateway's internal-network IP, so HTTP/HTTPS traffic flows through the gateway instead of direct egress. `bottle.git` / git-gate is intentionally deferred on this backend until a safe Apple Container key-delivery path exists.
 
 On the Firecracker backend, a bottle is an agent microVM plus a Docker gateway for egress, git-gate, and supervise. The VM reaches the gateway over a per-bottle point-to-point TAP link; a dedicated fail-closed `nftables` table (`inet bot_bottle_fc`) confines the guest to that link, so nothing leaves the box except through the gateway. The TAP pool and nft table are provisioned once (root); per-launch needs no privilege.
 
@@ -75,8 +75,6 @@ On compatible macOS hosts, the default backend requires Apple's `container` CLI
 
 Use `BOT_BOTTLE_BACKEND=docker ./cli.py start <agent>` on hosts where neither Apple Container nor KVM is available and Docker is the desired backend.
 
-> **CI (macOS Apple Container):** the advisory `integration-macos` job in `.gitea/workflows/pre-release-test.yml` runs only on manual dispatch. It targets a self-hosted host-mode runner labelled `macos`; Apple Container cannot run inside the Linux pull-request runner. Provision an Apple Silicon host with the `container` CLI running and Python ≥ 3.11 plus `coverage` on the launchd service's explicit `PATH`. The infra container is a singleton (`bot-bottle-mac-infra`), so keep runner concurrency at 1. Its coverage is reported separately and never feeds the required pull-request gate.
-
 ### Containers inside a bottle
 
 A bottle may set `nested_containers: true`. On the macOS backend this starts a
@@ -174,7 +172,7 @@ BOT_BOTTLE_BACKEND=firecracker ./cli.py start <agent>
 
 > **NixOS:** enable `virtualisation.docker`, ensure the KVM module is loaded (`boot.kernelModules = [ "kvm-intel" ];` or `kvm-amd`), and add your user to the `kvm` and `docker` groups. For the network pool, consume the flake module — `imports = [ inputs.bot-bottle.nixosModules.firecracker-netpool ]; services.bot-bottle-firecracker = { enable = true; owner = "you"; };` — then `nixos-rebuild switch` (imperative nft/TAP rules don't survive a rebuild; channel users can `imports = [ <bot-bottle>/nix/firecracker-netpool.nix ]`). `firecracker` isn't in nixpkgs by default as a user binary — install the release binary (pin the version) and put it on `PATH`.
 
-> **CI:** Firecracker integration runs in the manually dispatched `.gitea/workflows/pre-release-test.yml` on a self-hosted runner labelled `kvm`; privileged KVM hosts never execute unreviewed PR code automatically. Provision it like a normal Firecracker host: `firecracker` on `PATH`, `/dev/kvm`, the cached guest kernel and static dropbear, and the persistent TAP/nft pool. The required pull-request workflow runs unit plus the complete Docker integration suite on `ubuntu-latest`; see `docs/ci.md`.
+> **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

bot_bottle/backend/base.py

@@ -23,14 +23,14 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Generator, Generic, Sequence, TypeVar
 
-from ..agent_provider import AgentProvisionPlan, get_provider
+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 ..util import expand_tilde
 from ..manifest import Manifest, ManifestIndex
 from ..supervisor.plan import SupervisePlan
-from ..env import ResolvedEnv
+from ..env import resolve_env, ResolvedEnv
 from ..workspace import WorkspacePlan, workspace_plan
 from .print_util import print_multi, visible_agent_env_names
 from .util import host_skill_dir
@@ -296,18 +296,82 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
         backend-specific resolution (names, scratch files, etc.). The
         validation step is enforced here so a future backend cannot
         accidentally skip it. No remote/runtime resources are created."""
-        from .preparation import BottlePreparationPlanner
-        prepared = BottlePreparationPlanner(self).prepare(spec)
+        from .resolve_common import (
+            merge_provision_env_vars,
+            mint_slug,
+            prepare_agent_state_dir,
+            prepare_egress,
+            prepare_git_gate,
+            prepare_supervise,
+            reject_nested_containers,
+            resolve_manifest_dockerfile,
+            write_launch_metadata,
+        )
+
+        manifest = self._validate(spec)
+
+        if not self.supports_nested_containers:
+            reject_nested_containers(self.name, manifest)
+
+        self._preflight()
+
+        from ..git_gate import GitGate
+        manifest = GitGate().preflight_host_keys(
+            manifest,
+            headless=spec.headless,
+            home_md=spec.manifest.home_md,
+        )
+
+        manifest_bottle = manifest.bottle
+        manifest_agent_provider = manifest_bottle.agent_provider
+        agent_provider = get_provider(manifest_agent_provider.template)
+        resolved_env = resolve_env(manifest)
+        workspace = workspace_plan(spec, guest_home=agent_provider.guest_home)
+
+        slug = mint_slug(spec)
+        write_launch_metadata(slug, spec, compose_project="", backend=self.name)
+
+        # Manifest may override the Dockerfile per-bottle; otherwise fall
+        # back to the provider plugin's bundled Dockerfile (next to its
+        # agent_provider.py module).
+        if manifest_agent_provider.dockerfile:
+            agent_dockerfile_path = resolve_manifest_dockerfile(
+                manifest_agent_provider.dockerfile, spec,
+            )
+        else:
+            agent_dockerfile_path = str(agent_provider.dockerfile)
+
+        agent_dir, prompt_file = prepare_agent_state_dir(slug, manifest)
+
+        agent_provision_plan = build_agent_provision_plan(
+            template=manifest_agent_provider.template,
+            dockerfile=agent_dockerfile_path,
+            state_dir=agent_dir,
+            instance_name=f"bot-bottle-{slug}",
+            prompt_file=prompt_file,
+            guest_env=self._build_guest_env(resolved_env),
+            forward_host_credentials=manifest_agent_provider.forward_host_credentials,
+            auth_token=manifest_agent_provider.auth_token,
+            host_env=dict(os.environ),
+            trusted_project_path=workspace.workdir,
+            label=spec.label,
+            color=spec.color,
+            provider_settings=manifest_agent_provider.settings,
+        )
+        agent_provision_plan = merge_provision_env_vars(agent_provision_plan)
+        egress_plan = prepare_egress(manifest_bottle, slug, agent_provision_plan)
+        supervise_plan = prepare_supervise(manifest_bottle, slug)
+        git_gate_plan = prepare_git_gate(manifest_bottle, slug)
 
         return self._resolve_plan(
             spec,
-            manifest=prepared.manifest,
-            slug=prepared.slug,
-            resolved_env=prepared.resolved_env,
-            agent_provision_plan=prepared.agent_provision_plan,
-            egress_plan=prepared.egress_plan,
-            supervise_plan=prepared.supervise_plan,
-            git_gate_plan=prepared.git_gate_plan,
+            manifest=manifest,
+            slug=slug,
+            resolved_env=resolved_env,
+            agent_provision_plan=agent_provision_plan,
+            egress_plan=egress_plan,
+            supervise_plan=supervise_plan,
+            git_gate_plan=git_gate_plan,
             stage_dir=stage_dir,
         )
 

bot_bottle/backend/docker/gateway.py

@@ -10,17 +10,12 @@ from ...paths import (
     ORCHESTRATOR_AUTH_JWT_ENV,
     host_gateway_ca_dir,
 )
-from ... import resources
 from ...gateway import (
   Gateway, GatewayTransport, GATEWAY_IMAGE, GATEWAY_NAME, GATEWAY_NETWORK,
-  GATEWAY_DOCKERFILE, GATEWAY_LABEL, MITMPROXY_HOME,
+  GATEWAY_DOCKERFILE, REPO_ROOT, GATEWAY_LABEL, MITMPROXY_HOME,
   DEFAULT_CA_TIMEOUT_SECONDS, CA_POLL_SECONDS, GATEWAY_CA_CERT, GatewayError
 )
 
-DEFAULT_GATEWAY_SUBNET = "10.242.255.0/24"
-_GATEWAY_SUBNET_LABEL = "bot-bottle.gateway-subnet"
-
-
 class DockerGateway(Gateway):
     """The consolidated gateway as a single, fixed-name Docker container.
 
@@ -39,8 +34,6 @@ class DockerGateway(Gateway):
         build_context: Path | None = None,
         dockerfile: str | None = GATEWAY_DOCKERFILE,
         host_port_bindings: tuple[int, ...] = (),
-        ca_mount_source: str | Path | None = None,
-        subnet: str | None = None,
     ) -> None:
         self.image_ref = image_ref
         self.name = name
@@ -57,23 +50,12 @@ class DockerGateway(Gateway):
         # `address` / `stop` work on an already-running gateway without it.
         self._orchestrator_url = ""
         self._gateway_token = ""
-        # Resolved lazily in ensure_built() so merely constructing a gateway to
-        # read its CA never stages a build root from an installed wheel.
-        self._build_context = build_context
+        self._build_context = build_context or REPO_ROOT
         self._dockerfile = dockerfile
         # Ports published on the host (0.0.0.0). Used by the Firecracker
         # backend's dev-harness gateway so VMs can reach it via their TAP link;
         # Docker's DNAT + the nft `ct status dnat accept` rule handle the rest.
         self._host_port_bindings = host_port_bindings
-        self._subnet = (
-            subnet
-            or os.environ.get("BOT_BOTTLE_DOCKER_GATEWAY_SUBNET", "").strip()
-            or DEFAULT_GATEWAY_SUBNET
-        )
-        configured_ca = os.environ.get("BOT_BOTTLE_DOCKER_CA_MOUNT", "").strip()
-        self._ca_mount_source = str(
-            ca_mount_source or configured_ca or host_gateway_ca_dir()
-        )
 
     def image_exists(self) -> bool:
         return run_docker(["docker", "image", "inspect", self.image_ref]).returncode == 0
@@ -90,10 +72,9 @@ class DockerGateway(Gateway):
         forces a full rebuild (parity with `start --no-cache`)."""
         if self._dockerfile is None:
             return
-        context = self._build_context or resources.build_root()
         argv = ["docker", "build", "-t", self.image_ref,
-                "-f", str(context / self._dockerfile),
-                str(context)]
+                "-f", str(self._build_context / self._dockerfile),
+                str(self._build_context)]
         if os.environ.get("BOT_BOTTLE_NO_CACHE"):
             argv.insert(2, "--no-cache")
         proc = run_docker(argv)
@@ -124,34 +105,10 @@ class DockerGateway(Gateway):
     def _ensure_network(self) -> None:
         """Create the shared gateway network if it doesn't exist. Idempotent —
         a concurrent create loses harmlessly (the loser sees 'already exists').
-        The explicit subnet is required because bottle attribution pins source
-        IPs; Docker rejects static endpoint addresses on an auto-IPAM network."""
-        inspected = run_docker([
-            "docker", "network", "inspect",
-            "--format", f'{{{{index .Labels "{_GATEWAY_SUBNET_LABEL}"}}}}',
-            self.network,
-        ])
-        if inspected.returncode == 0:
-            marker = inspected.stdout.strip()
-            if marker in {"", self._subnet}:
-                return
-        if inspected.returncode == 0:
-            # Migrate the stale auto-IPAM network created by older releases.
-            # Removing the fixed gateway is safe here: this launch recreates it.
-            run_docker(["docker", "rm", "--force", self.name])
-            removed = run_docker(["docker", "network", "rm", self.network])
-            if removed.returncode != 0:
-                raise GatewayError(
-                    f"gateway network {self.network} needs explicit subnet "
-                    f"{self._subnet} but could not be replaced: "
-                    f"{removed.stderr.strip()}"
-                )
-        proc = run_docker([
-            "docker", "network", "create",
-            "--subnet", self._subnet,
-            "--label", f"{_GATEWAY_SUBNET_LABEL}={self._subnet}",
-            self.network,
-        ])
+        Docker picks the subnet; the launcher reads it back to allocate IPs."""
+        if run_docker(["docker", "network", "inspect", self.network]).returncode == 0:
+            return
+        proc = run_docker(["docker", "network", "create", self.network])
         if proc.returncode != 0 and "already exists" not in proc.stderr:
             raise GatewayError(
                 f"gateway network {self.network} failed to create: {proc.stderr.strip()}"
@@ -182,9 +139,9 @@ class DockerGateway(Gateway):
         # Recreate when the running container's image is stale (a rebuild),
         # so source changes to the gateway's flat daemons take effect — not
         # just when the container is absent.
-        self._ensure_network()
         if self.is_running() and self._running_image_is_current():
             return
+        self._ensure_network()
         # Clear any stale (stopped OR outdated-image) container holding the
         # fixed name, then start fresh. `rm --force` on an absent name is a
         # tolerated no-op.
@@ -197,7 +154,7 @@ class DockerGateway(Gateway):
             # Persist the self-generated CA on the host so it survives both
             # container recreation AND docker volume pruning (agents trust it)
             # — see host_gateway_ca_dir / issue #450.
-            "--volume", f"{self._ca_mount_source}:{MITMPROXY_HOME}",
+            "--volume", f"{host_gateway_ca_dir()}:{MITMPROXY_HOME}",
             # No DB mount: the data plane (egress / supervise / git-gate) reaches
             # the supervise queue over the control-plane RPC and never opens
             # bot-bottle.db, so the gateway container gets no file handle on it
@@ -292,4 +249,4 @@ class DockerGateway(Gateway):
     def provisioning_transport(self) -> GatewayTransport:
         """The exec/cp transport git-gate provisioning stages per-bottle repos +
         deploy keys through (over the docker socket)."""
-        return DockerGatewayTransport(self.name)
+        return DockerGatewayTransport(self.name)

bot_bottle/backend/docker/infra.py

@@ -33,7 +33,7 @@ from .orchestrator import (
     ORCHESTRATOR_NAME,
     ORCHESTRATOR_NETWORK,
 )
-from ... import resources
+from ...paths import bot_bottle_root
 from ...gateway import (
     GATEWAY_IMAGE,
     GATEWAY_NAME,
@@ -50,6 +50,8 @@ from ...orchestrator.lifecycle import (
 # the pair's public identity.
 INFRA_NAME = GATEWAY_NAME  # the container agents attribute against is the gateway
 
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+
 
 class DockerInfraService(InfraService):
     """Composes the per-host control plane + gateway as two containers.
@@ -66,10 +68,8 @@ class DockerInfraService(InfraService):
         control_network: str = ORCHESTRATOR_NETWORK,
         orchestrator_image: str = ORCHESTRATOR_IMAGE,
         gateway_image: str = GATEWAY_IMAGE,
-        repo_root: Path | None = None,
+        repo_root: Path = _REPO_ROOT,
         host_root: Path | None = None,
-        root_mount_source: str | Path | None = None,
-        gateway_ca_mount_source: str | Path | None = None,
         orchestrator_name: str = ORCHESTRATOR_NAME,
         orchestrator_label: str = ORCHESTRATOR_LABEL,
         gateway_name: str = GATEWAY_NAME,
@@ -79,14 +79,8 @@ class DockerInfraService(InfraService):
         self.control_network = control_network
         self.orchestrator_image = orchestrator_image
         self.gateway_image = gateway_image
-        # Build context: the repo root in a checkout, a staged copy from the
-        # installed wheel otherwise (bot_bottle.resources).
-        self._repo_root = repo_root if repo_root is not None else resources.build_root()
-        if host_root is not None and root_mount_source is not None:
-            raise ValueError("pass host_root or root_mount_source, not both")
-        self._host_root = host_root
-        self._root_mount_source = root_mount_source
-        self._gateway_ca_mount_source = gateway_ca_mount_source
+        self._repo_root = repo_root
+        self._host_root = host_root or bot_bottle_root()
         self._orchestrator_name = orchestrator_name
         self._orchestrator_label = orchestrator_label
         self._gateway_name = gateway_name
@@ -103,7 +97,6 @@ class DockerInfraService(InfraService):
             control_network=self.control_network,
             repo_root=self._repo_root,
             host_root=self._host_root,
-            root_mount_source=self._root_mount_source,
         )
 
     def gateway(self) -> DockerGateway:
@@ -118,7 +111,6 @@ class DockerInfraService(InfraService):
             network=self.network,
             control_network=self.control_network,
             build_context=self._repo_root,
-            ca_mount_source=self._gateway_ca_mount_source,
         )
 
     def ensure_running(

bot_bottle/backend/docker/launch.py

@@ -33,6 +33,7 @@ from __future__ import annotations
 import dataclasses
 import os
 from contextlib import ExitStack, contextmanager
+from pathlib import Path
 from typing import Callable, Generator
 
 from ...agent_provider import runtime_for
@@ -64,7 +65,10 @@ from ...orchestrator.store.config_store import resolve_teardown_timeout
 from .consolidated_launch import launch_consolidated, deprovision_consolidated
 from .infra import INFRA_NAME
 from .gateway import DockerGateway
-from ... import resources
+
+
+# Where the repo root lives, for `docker build` context. Computed once.
+_REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)
 
 
 def build_or_load_images(plan: DockerBottlePlan) -> BottleImages:
@@ -84,7 +88,7 @@ def build_or_load_images(plan: DockerBottlePlan) -> BottleImages:
             )
         info(f"using cached agent image {plan.image!r}")
         return BottleImages(agent=plan.image)
-    docker_mod.build_image(plan.image, str(resources.build_root()), dockerfile=plan.dockerfile_path)
+    docker_mod.build_image(plan.image, _REPO_DIR, dockerfile=plan.dockerfile_path)
     docker_mod.verify_agent_image(
         plan.image, runtime_for(plan.agent_provider_template).smoke_test,
     )

bot_bottle/backend/docker/orchestrator.py

@@ -15,7 +15,6 @@ import time
 from pathlib import Path
 
 from ... import log
-from ... import resources
 from .util import run_docker
 from ...paths import (
     ORCHESTRATOR_TOKEN_ENV,
@@ -42,9 +41,13 @@ ORCHESTRATOR_IMAGE = os.environ.get(
 )
 ORCHESTRATOR_DOCKERFILE = "Dockerfile.orchestrator"
 # Baked as a container label so `ensure_running` can detect whether the running
-# orchestrator image was built from the current source.
+# orchestrator is executing the current bind-mounted source.
 ORCHESTRATOR_SOURCE_HASH_LABEL = "bot-bottle-orchestrator-source-hash"
 
+# The bind-mount path for the live control-plane source inside the container.
+# PYTHONPATH points here so a code change takes effect on the next launch
+# without an image rebuild.
+_SRC_IN_CONTAINER = "/bot-bottle-src"
 # Bot-bottle host-root bind-mount (DB + state) inside the orchestrator. The
 # control plane opens bot-bottle.db under here (via BOT_BOTTLE_ROOT ->
 # host_db_path()); it is the ONLY container with a handle on it (issue #469).
@@ -52,6 +55,8 @@ _ROOT_IN_CONTAINER = "/bot-bottle-root"
 
 _HEALTH_POLL_SECONDS = 0.25
 
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+
 
 class DockerOrchestrator(Orchestrator):
     """The control plane as a single fixed-name container. `ensure_built` builds
@@ -66,53 +71,23 @@ class DockerOrchestrator(Orchestrator):
         label: str = ORCHESTRATOR_LABEL,
         port: int = DEFAULT_PORT,
         control_network: str = ORCHESTRATOR_NETWORK,
-        repo_root: Path | None = None,
+        repo_root: Path = _REPO_ROOT,
         host_root: Path | None = None,
-        root_mount_source: str | Path | None = None,
-        client_host: str | None = None,
-        client_network: str | None = None,
-        bind_host: str | None = None,
         dockerfile: str | None = ORCHESTRATOR_DOCKERFILE,
     ) -> None:
-        if host_root is not None and root_mount_source is not None:
-            raise ValueError("pass host_root or root_mount_source, not both")
         self.image_ref = image_ref
         self.name = name
         self.label = label
         self.port = port
         self.control_network = control_network
-        # Build context: the repo root in a checkout, a staged copy from the
-        # installed wheel otherwise (bot_bottle.resources).
-        self._repo_root = repo_root if repo_root is not None else resources.build_root()
-        configured_root = os.environ.get("BOT_BOTTLE_DOCKER_ROOT_MOUNT", "").strip()
-        self._root_mount_source = str(
-            root_mount_source or configured_root or host_root or bot_bottle_root()
-        )
-        configured_network = os.environ.get(
-            "BOT_BOTTLE_DOCKER_CLIENT_NETWORK", ""
-        ).strip()
-        self._client_network = client_network or configured_network or None
-        configured_host = os.environ.get(
-            "BOT_BOTTLE_DOCKER_HOST_ADDRESS", ""
-        ).strip()
-        self._client_host = (
-            client_host or configured_host
-            or (self.name if self._client_network else "127.0.0.1")
-        )
-        # A socket-shared CI runner reaches published ports through its Docker
-        # network rather than its own loopback. Production stays bound to host
-        # loopback unless a caller explicitly selects another client.
-        self._bind_host = bind_host or (
-            "0.0.0.0"
-            if not self._client_network and self._client_host != "127.0.0.1"
-            else "127.0.0.1"
-        )
+        self._repo_root = repo_root
+        self._host_root = host_root or bot_bottle_root()
         self._dockerfile = dockerfile
 
     def url(self) -> str:
-        """Control-plane URL reachable by this Docker client."""
-        port = DEFAULT_PORT if self._client_network else self.port
-        return f"http://{self._client_host}:{port}"
+        """Host-side control-plane URL — the orchestrator's published loopback,
+        which the CLI reaches."""
+        return f"http://127.0.0.1:{self.port}"
 
     def gateway_url(self) -> str:
         """The URL the gateway's data plane resolves policy against — the
@@ -143,7 +118,8 @@ class DockerOrchestrator(Orchestrator):
         return self.name in proc.stdout.split()
 
     def _source_current(self, current_hash: str) -> bool:
-        """True iff the running orchestrator image matches current source."""
+        """True iff the running orchestrator was started from the current
+        bind-mounted source."""
         if not self.is_running():
             return False
         proc = run_docker([
@@ -205,19 +181,15 @@ class DockerOrchestrator(Orchestrator):
             # Control network only — agents are never on it, so they have no
             # route to the control plane (the L3 block, not just the JWT).
             "--network", self.control_network,
-            # Host CLI reaches the control plane here (loopback by default).
-            # Socket-shared CI joins the container directly to the job network;
-            # the host-side mapping remains loopback-only in that topology. The
+            # Host CLI reaches the control plane here (loopback only). The
             # orchestrator listens on the fixed DEFAULT_PORT inside the
             # container; self.port is the host-side published port.
-            "--publish", f"{self._bind_host}:{self.port}:{DEFAULT_PORT}",
-            # The image was rebuilt from `_repo_root` immediately before this
-            # launch. Running its baked package avoids a host-path bind mount,
-            # which is both more production-like and works with socket-shared
-            # CI where the daemon cannot see the job container's workspace.
+            "--publish", f"127.0.0.1:{self.port}:{DEFAULT_PORT}",
+            # Live control-plane source (code changes without an image rebuild).
+            "--volume", f"{self._repo_root}:{_SRC_IN_CONTAINER}:ro",
+            "--env", f"PYTHONPATH={_SRC_IN_CONTAINER}",
             # Orchestrator registry DB on the host (sole writer: control plane).
-            # `root_mount_source` may be a host path or a named Docker volume.
-            "--volume", f"{self._root_mount_source}:{_ROOT_IN_CONTAINER}",
+            "--volume", f"{self._host_root}:{_ROOT_IN_CONTAINER}",
             "--env", f"BOT_BOTTLE_ROOT={_ROOT_IN_CONTAINER}",
             # The signing key — held ONLY by the orchestrator (it verifies
             # tokens); the gateway gets the pre-minted `gateway` JWT, never the
@@ -232,15 +204,6 @@ class DockerOrchestrator(Orchestrator):
             raise OrchestratorStartError(
                 f"orchestrator container failed to start: {proc.stderr.strip()}"
             )
-        if self._client_network:
-            proc = run_docker([
-                "docker", "network", "connect", self._client_network, self.name,
-            ])
-            if proc.returncode != 0:
-                raise OrchestratorStartError(
-                    f"orchestrator container failed to join client network "
-                    f"{self._client_network}: {proc.stderr.strip()}"
-                )
 
     def stop(self) -> None:
         """Remove the control-plane container (idempotent)."""

bot_bottle/backend/docker/util.py

@@ -6,17 +6,12 @@ from __future__ import annotations
 
 import os
 from datetime import datetime, timezone
+import re
 import shutil
 import subprocess
 from typing import Iterator
 
 from ...log import die, info
-from ...util import slugify as _slugify
-
-
-def slugify(name: str) -> str:
-    """Compatibility wrapper; new generic callers import ``bot_bottle.util``."""
-    return _slugify(name)
 
 
 def run_docker(
@@ -119,6 +114,19 @@ def docker_cp(src: str, dest: str) -> None:
             f"{(result.stderr or '').strip() or '<no stderr>'}")
 
 
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+
+def slugify(name: str) -> str:
+    """Lowercase, non-alnum runs → '-', trimmed. Dies on empty result."""
+    if not name:
+        die("slugify: missing name")
+    slug = _SLUG_RE.sub("-", name.lower()).strip("-")
+    if not slug:
+        die(f"name '{name}' produced an empty slug; use alphanumeric characters")
+    return slug
+
+
 def build_image(ref: str, context: str, *, dockerfile: str = "") -> None:
     """Invokes `docker build` every call. Layer cache makes no-change
     rebuilds cheap; running every time means Dockerfile edits land

bot_bottle/backend/egress_apply.py

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

bot_bottle/backend/firecracker/infra_artifact.py

@@ -37,7 +37,6 @@ import urllib.error
 import urllib.request
 from pathlib import Path
 
-from ... import resources
 from ...log import die, info
 from . import util
 
@@ -45,6 +44,8 @@ from . import util
 # scheme can't collide with a cached/published artifact of the old one.
 _ARTIFACT_FORMAT = "1"
 
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+
 # The two per-plane infra VM roles. Each publishes/pulls its own rootfs artifact
 # from its own generic package; the Dockerfiles baked into each differ (only the
 # orchestrator rootfs carries buildah), so the versions are hashed separately.
@@ -73,7 +74,7 @@ def local_build_requested() -> bool:
 
 
 def infra_artifact_version(
-    init_script: str, role: str, *, repo_root: Path | None = None,
+    init_script: str, role: str, *, repo_root: Path = _REPO_ROOT,
 ) -> str:
     """Content hash (16 hex) of everything baked into `role`'s infra rootfs: the
     whole shipped `bot_bottle` package, that role's Dockerfiles, and its guest
@@ -88,8 +89,6 @@ def infra_artifact_version(
     version or a launch host could boot a stale rootfs whose code differs from
     its checkout. `__pycache__`/`.pyc` are the only exclusions — build artifacts,
     never copied."""
-    if repo_root is None:
-        repo_root = resources.build_root()
     h = hashlib.sha256()
     h.update(f"format={_ARTIFACT_FORMAT}\nrole={role}\n".encode())
     pkg = repo_root / "bot_bottle"

bot_bottle/backend/firecracker/infra_vm.py

@@ -42,7 +42,6 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Generator
 
-from ... import resources
 from ...log import die, info
 from ..docker import util as docker_mod
 from . import firecracker_vm, infra_artifact, netpool, util
@@ -66,6 +65,7 @@ _GUEST_GATEWAY_JWT_PATH = "/var/lib/bot-bottle/gateway-jwt"
 _GATEWAY_IMAGE = "bot-bottle-gateway:latest"
 _ORCHESTRATOR_IMAGE = "bot-bottle-orchestrator:latest"
 _ORCHESTRATOR_FC_IMAGE = "bot-bottle-orchestrator-fc:latest"
+_REPO_ROOT = Path(__file__).resolve().parents[3]
 
 # Per-role rootfs source image + the extra free space `mke2fs` leaves for the
 # guest to grow into. The orchestrator keeps buildah's large build slack; the
@@ -130,13 +130,12 @@ def build_infra_images_with_docker() -> None:
     orchestrator + buildah). The gateway VM boots the gateway image directly.
     The launch host uses this only in `BOT_BOTTLE_INFRA_BUILD=local` mode;
     `publish_infra` uses it off-host to produce the published artifacts."""
-    root = str(resources.build_root())
     docker_mod.build_image(
-        _ORCHESTRATOR_IMAGE, root, dockerfile="Dockerfile.orchestrator")
+        _ORCHESTRATOR_IMAGE, str(_REPO_ROOT), dockerfile="Dockerfile.orchestrator")
     docker_mod.build_image(
-        _GATEWAY_IMAGE, root, dockerfile="Dockerfile.gateway")
+        _GATEWAY_IMAGE, str(_REPO_ROOT), dockerfile="Dockerfile.gateway")
     docker_mod.build_image(
-        _ORCHESTRATOR_FC_IMAGE, root, dockerfile="Dockerfile.orchestrator.fc")
+        _ORCHESTRATOR_FC_IMAGE, str(_REPO_ROOT), dockerfile="Dockerfile.orchestrator.fc")
 
 
 def build_rootfs_dir(role: str) -> Path:

bot_bottle/backend/firecracker/setup.py

@@ -20,7 +20,6 @@ import subprocess
 import sys
 from pathlib import Path
 
-from ... import resources
 from . import netpool
 from . import util
 
@@ -43,13 +42,13 @@ def _has_systemd() -> bool:
 
 
 def _module_path() -> str:
-    """Absolute path to the importable NixOS module (checkout or wheel)."""
-    return str(resources.nix_netpool_module())
+    """Absolute path to the importable NixOS module in this checkout."""
+    return str(Path(__file__).resolve().parents[3] / "nix" / "firecracker-netpool.nix")
 
 
 def _script_path() -> str:
-    """Absolute path to the bundled bring-up script (checkout or wheel)."""
-    return str(resources.netpool_script())
+    """Absolute path to the bundled bring-up script in this checkout."""
+    return str(Path(__file__).resolve().parents[3] / "scripts" / "firecracker-netpool.sh")
 
 
 def _print_prereqs() -> None:

bot_bottle/backend/macos_container/gateway.py

@@ -28,7 +28,6 @@ from ...paths import (
     ORCHESTRATOR_AUTH_JWT_ENV,
     host_gateway_ca_dir,
 )
-from ... import resources
 from .. import util as backend_util
 from . import util as container_mod
 
@@ -53,6 +52,8 @@ GATEWAY_DAEMONS = "egress,git-http,supervise"
 
 GATEWAY_IMAGE = os.environ.get("BOT_BOTTLE_GATEWAY_IMAGE", "bot-bottle-gateway:latest")
 
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+
 
 def ensure_networks(
     network: str = GATEWAY_NETWORK,
@@ -83,16 +84,14 @@ class MacosGateway(Gateway):
         network: str = GATEWAY_NETWORK,
         egress_network: str = GATEWAY_EGRESS_NETWORK,
         control_network: str = CONTROL_NETWORK,
-        repo_root: Path | None = None,
+        repo_root: Path = _REPO_ROOT,
     ) -> None:
         self.image_ref = image_ref
         self.name = name
         self.network = network
         self.egress_network = egress_network
         self.control_network = control_network
-        # Build context: the repo root in a checkout, a staged copy from the
-        # installed wheel otherwise (bot_bottle.resources).
-        self._repo_root = repo_root if repo_root is not None else resources.build_root()
+        self._repo_root = repo_root
         # Set by `connect_to_orchestrator`: the URL the daemons resolve policy
         # against + the pre-minted `gateway` token they present. The gateway
         # never mints, so it never holds the signing key (#469).

bot_bottle/backend/macos_container/infra.py

@@ -24,7 +24,6 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from ... import resources
 from ...orchestrator.lifecycle import (
     DEFAULT_PORT,
     DEFAULT_STARTUP_TIMEOUT_SECONDS,
@@ -54,6 +53,8 @@ from .orchestrator import (
 # still import it (probe / reprovision attribute against the gateway).
 INFRA_NAME = GATEWAY_NAME
 
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+
 
 class MacosInfraService(InfraService):
     """Composes the per-host orchestrator + gateway containers. Callers use
@@ -69,7 +70,7 @@ class MacosInfraService(InfraService):
         control_network: str = CONTROL_NETWORK,
         gateway_image: str = GATEWAY_IMAGE,
         orchestrator_image: str = ORCHESTRATOR_IMAGE,
-        repo_root: Path | None = None,
+        repo_root: Path = _REPO_ROOT,
         orchestrator_name: str = ORCHESTRATOR_NAME,
         gateway_name: str = INFRA_NAME,
         db_volume: str = ORCHESTRATOR_DB_VOLUME,
@@ -80,9 +81,7 @@ class MacosInfraService(InfraService):
         self.control_network = control_network
         self.gateway_image = gateway_image
         self.orchestrator_image = orchestrator_image
-        # Build context / bind-mount source: the repo root in a checkout, a
-        # staged copy from the installed wheel otherwise (bot_bottle.resources).
-        self._repo_root = repo_root if repo_root is not None else resources.build_root()
+        self._repo_root = repo_root
         self._orchestrator_name = orchestrator_name
         self._gateway_name = gateway_name
         self._db_volume = db_volume

bot_bottle/backend/macos_container/launch.py

@@ -36,6 +36,7 @@ import dataclasses
 import os
 import subprocess
 from contextlib import ExitStack, contextmanager
+from pathlib import Path
 from typing import Callable, Generator
 
 from ...bottle_state import (
@@ -48,7 +49,6 @@ from ...git_gate import GitGate
 from ...gateway.git_gate.http_backend import DEFAULT_PORT as _GIT_HTTP_PORT
 from ...image_cache import check_stale
 from ...log import die, info, warn
-from ... import resources
 from .. import BottleImages
 from ...supervisor.types import SUPERVISE_PORT
 from ..docker.egress import EGRESS_PORT
@@ -71,6 +71,7 @@ from .consolidated_launch import (
     deprovision_consolidated,
 )
 
+_REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)
 _AGENT_SLEEP_SECONDS = "2147483647"
 
 
@@ -93,7 +94,7 @@ def _agent_image(plan: MacosContainerBottlePlan) -> str:
             )
         info(f"using cached agent image {plan.image!r}")
         return plan.image
-    container_mod.build_image(plan.image, str(resources.build_root()), dockerfile=plan.dockerfile_path)
+    container_mod.build_image(plan.image, _REPO_DIR, dockerfile=plan.dockerfile_path)
     return plan.image
 
 

bot_bottle/backend/macos_container/orchestrator.py

@@ -18,7 +18,6 @@ import urllib.request
 from pathlib import Path
 
 from ... import log
-from ... import resources
 from ...paths import ORCHESTRATOR_TOKEN_ENV
 from ...orchestrator.lifecycle import (
     DEFAULT_HEALTH_TIMEOUT_SECONDS,
@@ -46,6 +45,7 @@ _DB_ROOT_IN_CONTAINER = "/var/lib/bot-bottle"
 _SRC_IN_CONTAINER = "/bot-bottle-src"
 
 _HEALTH_POLL_SECONDS = 0.25
+_REPO_ROOT = Path(__file__).resolve().parents[3]
 
 
 class MacosOrchestrator(Orchestrator):
@@ -61,7 +61,7 @@ class MacosOrchestrator(Orchestrator):
         label: str = ORCHESTRATOR_LABEL,
         port: int = DEFAULT_PORT,
         control_network: str = CONTROL_NETWORK,
-        repo_root: Path | None = None,
+        repo_root: Path = _REPO_ROOT,
         db_volume: str = ORCHESTRATOR_DB_VOLUME,
     ) -> None:
         self.image_ref = image_ref
@@ -69,9 +69,7 @@ class MacosOrchestrator(Orchestrator):
         self.label = label
         self.port = port
         self.control_network = control_network
-        # Build context / bind-mount source: the repo root in a checkout, a
-        # staged copy from the installed wheel otherwise (bot_bottle.resources).
-        self._repo_root = repo_root if repo_root is not None else resources.build_root()
+        self._repo_root = repo_root
         self._db_volume = db_volume
 
     def url(self) -> str:

bot_bottle/backend/preparation.py

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

bot_bottle/backend/resolve_common.py

@@ -30,7 +30,6 @@ from ..log import die
 from ..manifest import Manifest, ManifestBottle
 from ..supervisor.plan import SupervisePlan
 from ..orchestrator.supervisor import Supervisor
-from ..util import slugify
 from . import BottleSpec
 
 
@@ -45,7 +44,8 @@ def mint_slug(spec: BottleSpec) -> str:
     if spec.identity:
         return spec.identity
     if spec.label:
-        return slugify(spec.label)
+        from .docker import util as docker_mod
+        return docker_mod.slugify(spec.label)
     return bottle_identity(spec.agent_name)
 
 

bot_bottle/cli/commands/__init__.py

@@ -21,7 +21,6 @@ _HANDLERS: dict[str, str] = {
     "backend": "backend:cmd_backend",
     "cleanup": "cleanup:cmd_cleanup",
     "commit": "commit:cmd_commit",
-    "doctor": "doctor:cmd_doctor",
     "edit": "edit:cmd_edit",
     "help": "help:cmd_help",
     "init": "init:cmd_init",
@@ -54,6 +53,6 @@ COMMANDS = {name: _lazy(spec) for name, spec in _HANDLERS.items()}
 # 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. `help` and `login`
 # likewise never touch the store.
-NO_MIGRATION_COMMANDS = frozenset({"backend", "doctor", "help", "login"})
+NO_MIGRATION_COMMANDS = frozenset({"backend", "help", "login"})
 
 __all__ = ["COMMANDS", "NO_MIGRATION_COMMANDS"]

bot_bottle/cli/commands/doctor.py

@@ -1,88 +0,0 @@
-"""`doctor` CLI command — validate host prerequisites for running
-bot-bottle and report what's ready.
-
-Fails (non-zero exit) only on the two hard requirements: a new-enough
-Python and at least one backend that is *ready* (passes its full status
-checks, so `start` can actually work). The config directory is a soft
-check — `install.sh` creates it, but a missing one only warrants a note,
-not a failure, since `start` provisions what it needs on first run.
-"""
-
-from __future__ import annotations
-
-import argparse
-import sys
-from pathlib import Path
-
-from ...backend import is_backend_ready, known_backend_names
-from ..constants import PROG
-
-MIN_PYTHON = (3, 11)
-CONFIG_DIR = ".bot-bottle"
-
-
-def _ok(label: str, detail: str) -> None:
-    print(f"ok:   {label}: {detail}")
-
-
-def _warn(label: str, detail: str) -> None:
-    print(f"warn: {label}: {detail}")
-
-
-def _fail(label: str, detail: str) -> None:
-    print(f"fail: {label}: {detail}")
-
-
-def _check_python() -> bool:
-    v = sys.version_info
-    detail = f"{v.major}.{v.minor}.{v.micro}"
-    if (v.major, v.minor) >= MIN_PYTHON:
-        _ok("python", detail)
-        return True
-    _fail("python", f"{detail}; need {MIN_PYTHON[0]}.{MIN_PYTHON[1]} or newer")
-    return False
-
-
-def _check_backends() -> bool:
-    """At least one backend must be *ready* to run a bottle — i.e. pass its
-    full status() checks (daemon reachable, network pool present, KVM usable),
-    not merely have a binary on PATH. A binary-only check would report `ok`
-    on a host with a stopped Docker daemon or a half-configured Firecracker,
-    where `start` still can't work. Each not-ready backend prints its own
-    diagnostics (quiet=False) so the operator sees exactly what's missing."""
-    ready = []
-    for name in known_backend_names():
-        if is_backend_ready(name, quiet=False):
-            _ok("backend", f"{name}: ready")
-            ready.append(name)
-        else:
-            _warn("backend", f"{name}: not ready (see diagnostics above)")
-    if ready:
-        return True
-    _fail(
-        "backend",
-        "no backend is ready to run a bottle; start Docker, or finish "
-        "Apple Container (macOS) / Firecracker (Linux) setup",
-    )
-    return False
-
-
-def _check_config_dir() -> None:
-    config = Path.home() / CONFIG_DIR
-    if config.is_dir():
-        _ok("config", str(config))
-    else:
-        _warn("config", f"{config} does not exist yet (created on first use)")
-
-
-def cmd_doctor(argv: list[str]) -> int:
-    parser = argparse.ArgumentParser(
-        prog=f"{PROG} doctor",
-        description="Check host prerequisites for running bot-bottle.",
-    )
-    parser.parse_args(argv)
-
-    # Hard requirements gate the exit code; the config note is advisory.
-    required = [_check_python(), _check_backends()]
-    _check_config_dir()
-    return 0 if all(required) else 1

bot_bottle/cli/commands/help.py

@@ -25,7 +25,6 @@ def cmd_help(argv: list[str] | None = None) -> int:
     w("  backend   set up / check / undo a backend's host prerequisites (setup|status|teardown)\n")
     w("  cleanup   stop and remove all active bot-bottle containers\n")
     w("  commit    snapshot a running bottle's container state to a Docker image\n")
-    w("  doctor    check host prerequisites (Python, backend, config dir)\n")
     w("  edit      open an agent in vim for editing\n")
     w("  help      show this command list\n")
     w("  init      interactively create a new agent and add it to bot-bottle.json\n")

bot_bottle/cli/commands/start.py

@@ -25,11 +25,12 @@ from typing import Callable
 from ...agent_provider import get_provider, runtime_for
 from ...backend import (
     Bottle,
-    BottlePlan,
     BottleSpec,
     enumerate_active_agents,
     get_bottle_backend,
 )
+from ...backend.docker import util as docker_mod
+from ...backend.docker.bottle_plan import DockerBottlePlan
 from ...bottle_state import (
     cleanup_state,
     is_preserved,
@@ -39,7 +40,7 @@ from ...image_cache import StaleImageError
 from ...log import info, die
 from ...manifest import Manifest, ManifestIndex
 from ..constants import PROG
-from ...util import read_tty_line, slugify
+from ...util import read_tty_line
 from .. import tui
 
 
@@ -256,10 +257,10 @@ def _uniquify_label_headless(label: str) -> str:
     logging the chosen label. Orchestrators fire-and-forget many bottles,
     so silently picking a free name beats erroring on every collision."""
     active_slugs = {a.slug for a in enumerate_active_agents()}
-    if slugify(label) not in active_slugs:
+    if docker_mod.slugify(label) not in active_slugs:
         return label
     n = 2
-    while slugify(f"{label}-{n}") in active_slugs:
+    while docker_mod.slugify(f"{label}-{n}") in active_slugs:
         n += 1
     chosen = f"{label}-{n}"
     info(f"label '{label}' already in use; using '{chosen}'")
@@ -273,11 +274,11 @@ def prepare_with_preflight(
     spec: BottleSpec,
     *,
     stage_dir: Path,
-    render_preflight: Callable[[BottlePlan, str], None],
+    render_preflight: Callable[[DockerBottlePlan, str], None],
     prompt_yes: Callable[[], bool],
     dry_run: bool = False,
     backend_name: str | None = None,
-) -> tuple[BottlePlan | None, str]:
+) -> tuple[DockerBottlePlan | None, str]:
     """Run `backend.prepare`, render the preflight summary via the
     injected callable, prompt y/N via the injected callable.
 
@@ -404,7 +405,7 @@ def _resolve_unique_label(label: str, color: str) -> tuple[str, str]:
     in use among running bottles.  Passes through unchanged when no
     collision is found on the first check."""
     while True:
-        slug_candidate = slugify(label)
+        slug_candidate = docker_mod.slugify(label)
         active_slugs = {a.slug for a in enumerate_active_agents()}
         if slug_candidate not in active_slugs:
             return label, color
@@ -431,7 +432,7 @@ def _select_image_policy() -> str | None:
 
 
 def _text_render_preflight():
-    def _render(plan: BottlePlan, backend_name: str) -> None:
+    def _render(plan: DockerBottlePlan, backend_name: str) -> None:
         print(file=sys.stderr)
         print(f"backend: {backend_name}", file=sys.stderr)
         print(_manifest_to_yaml(plan.manifest), file=sys.stderr)

bot_bottle/cli/commands/supervise.py

@@ -368,7 +368,7 @@ def _main_loop(stdscr: "curses._CursesWindow") -> None:  # type: ignore  # pragm
         elif key in (curses.KEY_UP, ord("k")):
             selected = max(selected - 1, 0)
         elif key in (curses.KEY_ENTER, 10, 13):
-            status_line = _detail_view(stdscr, qp, green_attr=green_attr)
+            _detail_view(stdscr, qp, green_attr=green_attr)
         elif key == ord("a"):
             try:
                 status_line = _approve_from_tui(stdscr, qp)
@@ -456,7 +456,7 @@ def _detail_view(
     qp: QueuedProposal,
     *,
     green_attr: int = 0,
-) -> str:  # pragma: no cover
+) -> None:  # pragma: no cover
     """Render the full proposal. Scrollable. Press q to return."""
     lines = _detail_lines(qp, green_attr=green_attr)
     offset = 0
@@ -473,7 +473,7 @@ def _detail_view(
         stdscr.refresh()
         key = stdscr.getch()
         if key in (ord("q"), 27):
-            return ""
+            return
         if key in (curses.KEY_DOWN, ord("j")):
             offset = min(offset + 1, max(0, len(lines) - 1))
         elif key in (curses.KEY_UP, ord("k")):
@@ -484,34 +484,31 @@ def _detail_view(
             offset = max(0, len(lines) - 1)
         elif key == ord("a"):
             try:
-                return _approve_from_tui(stdscr, qp)
-            except ApplyError as exc:
-                return f"apply failed: {exc}"
+                _approve_from_tui(stdscr, qp)
+            except ApplyError:
+                pass
+            return
         elif key == ord("m"):
             if qp.proposal.tool in _REPORT_ONLY_TOOLS:
-                return f"modify unavailable for {qp.proposal.tool}"
+                return
             edited = _modify(stdscr, qp)
-            if edited is None:
-                return "modify aborted (no change)"
-            try:
-                return _approve_from_tui(
-                    stdscr, qp, final_file=edited,
-                    notes="operator modified before approving",
-                )
-            except ApplyError as exc:
-                return f"apply failed: {exc}"
+            if edited is not None:
+                try:
+                    _approve_from_tui(
+                        stdscr, qp, final_file=edited,
+                        notes="operator modified before approving",
+                    )
+                except ApplyError:
+                    pass
+            return
         elif key == ord("r"):
             reason = _prompt(stdscr, "reject reason: ")
             if reason:
                 reject(qp, reason=reason)
-                return f"rejected {qp.proposal.tool} for [{qp.label}]"
-            return "reject aborted (empty reason)"
+            return
 
 
-def _modify(
-    stdscr: "curses._CursesWindow",  # type: ignore
-    qp: QueuedProposal,
-) -> str | None:  # pragma: no cover
+def _modify(stdscr: "curses._CursesWindow", qp: QueuedProposal) -> str | None:  # type: ignore  # pragma: no cover
     """Suspend curses, open $EDITOR on the proposed file, return edited content."""
     suffix = _suffix_for_tool(qp.proposal.tool)
     curses.endwin()

bot_bottle/cli/tui.py

@@ -16,8 +16,6 @@ import os
 import sys
 from typing import Any, Optional
 
-from ..log import debug
-
 
 def filter_multiselect(
     items: list[str],
@@ -44,11 +42,7 @@ def filter_multiselect(
 
     try:
         tty_fd = open(tty_path, "r+b", buffering=0)
-    except OSError as exc:
-        debug(
-            "multi-select unavailable; treating it as cancellation",
-            context={"error_type": type(exc).__name__, "tty": tty_path},
-        )
+    except OSError:
         return None
 
     try:
@@ -79,11 +73,7 @@ def filter_select(
 
     try:
         tty_fd = open(tty_path, "r+b", buffering=0)
-    except OSError as exc:
-        debug(
-            "filter-select unavailable; treating it as cancellation",
-            context={"error_type": type(exc).__name__, "tty": tty_path},
-        )
+    except OSError:
         return None
 
     try:
@@ -139,11 +129,7 @@ def _run_picker(items: list[str], *, title: str, tty_fd: int) -> Optional[str]:
             curses.nocbreak()
             curses.echo()
             curses.endwin()
-    except Exception as exc:  # noqa: W0718 — curses can raise many error types
-        debug(
-            "filter-select display failed; treating it as cancellation",
-            context={"error_type": type(exc).__name__},
-        )
+    except Exception:  # noqa: W0718 — curses can raise many error types
         return None
     finally:
         sys.__stdin__ = orig_stdin    # type: ignore[assignment]
@@ -306,11 +292,7 @@ def _run_multiselect(
             curses.nocbreak()
             curses.echo()
             curses.endwin()
-    except Exception as exc:  # noqa: W0718
-        debug(
-            "multi-select display failed; treating it as cancellation",
-            context={"error_type": type(exc).__name__},
-        )
+    except Exception:  # noqa: W0718
         return None
     finally:
         sys.__stdin__ = orig_stdin    # type: ignore[assignment]
@@ -576,21 +558,13 @@ def name_color_modal(
     """
     try:
         tty_fd = open(tty_path, "r+b", buffering=0)  # pylint: disable=consider-using-with
-    except OSError as exc:
-        debug(
-            "name/color picker unavailable; using defaults",
-            context={"error_type": type(exc).__name__, "tty": tty_path},
-        )
+    except OSError:
         return default_label, ""
 
     try:
         fd_dup = os.dup(tty_fd.fileno())
         return _run_name_color(default_label, tty_fd=fd_dup, disclaimer=disclaimer)
-    except Exception as exc:  # noqa: BLE001  # pylint: disable=broad-exception-caught
-        debug(
-            "name/color picker failed; using defaults",
-            context={"error_type": type(exc).__name__},
-        )
+    except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
         return default_label, ""
     finally:
         tty_fd.close()

bot_bottle/egress/plan.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from pathlib import Path
 
-from ..gateway.egress.types import Route
+from ..gateway.egress.addon_core import Route
 
 
 @dataclass(frozen=True)
@@ -19,7 +19,7 @@ class EgressRoute(Route):
     """Host-side extension of the addon's `Route`.
 
     Inherits `host`, `matches`, `auth_scheme`, and `token_env`
-    from the gateway's wire `Route` — those are the fields that cross the
+    from `egress_addon_core.Route` — those are the fields that cross the
     YAML wire into the gateway. The fields below are host-only and
     are never serialised to the addon.
 

bot_bottle/egress/service.py

@@ -14,8 +14,8 @@ import secrets
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from ..gateway.egress.dlp_config import ON_MATCH_REDACT
-from ..gateway.egress.types import (
+from ..gateway.egress.addon_core import (
+    ON_MATCH_REDACT,
     HeaderMatch as CoreHeaderMatch,
     MatchEntry as CoreMatchEntry,
     PathMatch as CorePathMatch,

bot_bottle/gateway/__init__.py

@@ -62,6 +62,7 @@ GATEWAY_CA_GLOB = "mitmproxy-ca*"
 # that lands. Env override matches the backend's BOT_BOTTLE_GATEWAY_IMAGE.
 GATEWAY_IMAGE = os.environ.get("BOT_BOTTLE_GATEWAY_IMAGE", "bot-bottle-gateway:latest")
 GATEWAY_DOCKERFILE = "Dockerfile.gateway"
+REPO_ROOT = Path(__file__).resolve().parents[2]
 
 
 def rotate_gateway_ca(ca_dir: Path | None = None) -> list[Path]:

bot_bottle/gateway/egress/addon.py

@@ -17,34 +17,28 @@ from mitmproxy import http  # type: ignore[import-not-found]  # pylint: disable=
 
 from bot_bottle.constants import IDENTITY_HEADER
 from bot_bottle.gateway.egress.dlp_detectors import redact_tokens, strip_crlf
-from bot_bottle.gateway.egress.dlp_config import (
+from bot_bottle.gateway.egress.addon_core import (
+    LOG_BLOCKS,
+    LOG_FULL,
     DEFAULT_OUTBOUND_ON_MATCH,
     ON_MATCH_BLOCK,
     ON_MATCH_REDACT,
-)
-from bot_bottle.gateway.egress.context import resolve_client_context
-from bot_bottle.gateway.egress.dlp import (
+    Config,
+    Route,
+    ScanResult,
     build_inbound_scan_text,
     build_outbound_scan_text,
     build_token_allow_payload,
-    outbound_scan_headers,
-    scan_inbound,
-    scan_outbound,
-)
-from bot_bottle.gateway.egress.matching import (
     decide,
     decide_git_fetch,
     is_git_fetch_request,
     is_git_push_request,
     match_route,
-)
-from bot_bottle.gateway.egress.schema import route_to_yaml_dict
-from bot_bottle.gateway.egress.types import (
-    LOG_BLOCKS,
-    LOG_FULL,
-    Config,
-    Route,
-    ScanResult,
+    resolve_client_context,
+    outbound_scan_headers,
+    route_to_yaml_dict,
+    scan_inbound,
+    scan_outbound,
 )
 from bot_bottle.gateway.policy_resolver import PolicyResolveError, PolicyResolver
 from bot_bottle.supervisor.types import (

bot_bottle/gateway/egress/context.py

@@ -1,77 +0,0 @@
-"""Fail-closed resolution of a client's policy and egress credentials."""
-
-from __future__ import annotations
-
-import typing
-
-from ...log import debug
-from .types import Config
-
-
-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."
-)
-
-
-class PolicyResolverLike(typing.Protocol):
-    def resolve(self, source_ip: str, identity_token: str = ...) -> str | None: ...
-
-
-class ContextResolverLike(typing.Protocol):
-    def resolve_policy_and_bottle_id(
-        self, source_ip: str, identity_token: str = ...,
-    ) -> tuple[str | None, str | None, dict[str, str]]: ...
-
-
-def _config_from_policy(policy: str | None) -> Config:
-    # Local import keeps schema parsing independent of resolver protocols.
-    from .schema import load_config
-    if not policy:
-        return Config(routes=(), deny_reason=DENY_UNATTRIBUTED)
-    try:
-        return load_config(policy)
-    except ValueError:
-        return Config(routes=(), deny_reason=DENY_UNPARSEABLE)
-
-
-def resolve_client_config(
-    resolver: PolicyResolverLike, client_ip: str, identity_token: str = "",
-) -> Config:
-    try:
-        policy = resolver.resolve(client_ip, identity_token)
-    except Exception as exc:  # noqa: BLE001 - a policy lookup failure must deny
-        debug(
-            "egress policy resolution failed; applying deny-all",
-            context={"error_type": type(exc).__name__},
-        )
-        return Config(routes=(), deny_reason=DENY_RESOLVER_ERROR)
-    return _config_from_policy(policy)
-
-
-def resolve_client_context(
-    resolver: ContextResolverLike, client_ip: str, identity_token: str = "",
-) -> tuple[Config, str, dict[str, str]]:
-    try:
-        policy, bottle_id, tokens = resolver.resolve_policy_and_bottle_id(
-            client_ip, identity_token)
-    except Exception as exc:  # noqa: BLE001 - a policy lookup failure must deny
-        debug(
-            "egress context resolution failed; applying deny-all",
-            context={"error_type": type(exc).__name__},
-        )
-        return Config(routes=(), deny_reason=DENY_RESOLVER_ERROR), "", {}
-    return _config_from_policy(policy), (bottle_id or ""), tokens

bot_bottle/gateway/egress/dlp.py

@@ -1,99 +0,0 @@
-"""DLP scan dispatch and safe proposal rendering for egress requests."""
-
-from __future__ import annotations
-
-import typing
-
-from .types import Route, ScanResult
-
-
-def build_outbound_scan_text(host: str, path: str, query: str,
-                             headers: typing.Mapping[str, str], body: str) -> str:
-    parts = [host, path]
-    if query:
-        parts.append(query)
-    parts.extend(f"{name}: {value}" for name, value in headers.items())
-    if body:
-        parts.append(body)
-    return "\n".join(parts)
-
-
-def outbound_scan_headers(route: Route, headers: typing.Mapping[str, str]) -> dict[str, str]:
-    """Drop agent Authorization when the route injects gateway-owned auth."""
-    skip_auth = bool(route.auth_scheme and route.token_env)
-    return {name: value for name, value in headers.items()
-            if not (skip_auth and name.lower() == "authorization")}
-
-
-def build_inbound_scan_text(headers: typing.Mapping[str, str], body: str) -> str:
-    parts = [f"{name}: {value}" for name, value in headers.items()]
-    if body:
-        parts.append(body)
-    return "\n".join(parts)
-
-
-def _enabled(configured: tuple[str, ...] | None, name: str) -> bool:
-    return configured is None or name in configured
-
-
-def scan_outbound(route: Route, body: str | bytes, environ: typing.Mapping[str, str], *,
-                  safe_tokens: typing.AbstractSet[str] | None = None,
-                  crlf_text: str | None = None) -> ScanResult | None:
-    if not route.inspect:
-        return None
-    try:
-        from dlp_detectors import (  # type: ignore[import-not-found]
-            scan_crlf_injection, scan_entropy, scan_known_secrets, scan_token_patterns)
-    except ImportError:  # pragma: no cover - gateway's flat module path
-        from .dlp_detectors import (
-            scan_crlf_injection, scan_entropy, scan_known_secrets, scan_token_patterns)
-    if isinstance(body, bytes):
-        try:
-            text = body.decode("utf-8")
-        except UnicodeDecodeError:
-            text = body.decode("latin-1")
-    else:
-        text = body
-    result = scan_crlf_injection(text if crlf_text is None else crlf_text)
-    if result is not None:
-        return result
-    if _enabled(route.outbound_detectors, "token_patterns"):
-        result = scan_token_patterns(text, location="body", safe_tokens=safe_tokens)
-        if result is not None:
-            return result
-    if _enabled(route.outbound_detectors, "known_secrets"):
-        extra = tuple(prefix for prefix in environ.get(
-            "BOT_BOTTLE_SENSITIVE_PREFIXES", "").split(",") if prefix)
-        result = scan_known_secrets(text, location="body", env=environ,
-                                    sensitive_prefixes=("EGRESS_TOKEN_",) + extra,
-                                    safe_tokens=safe_tokens)
-        if result is not None:
-            return result
-    if route.outbound_detectors is not None and "entropy" in route.outbound_detectors:
-        return scan_entropy(text, location="body")
-    return None
-
-
-def build_token_allow_payload(host: str, method: str, path: str, result: ScanResult) -> str:
-    """Render redacted operator context; the raw matched secret is excluded."""
-    lines = [
-        "egress blocked an outbound request carrying a detected token",
-        f"host: {host}", f"method: {method}", f"path: {path}",
-        f"detector: {result.reason}",
-    ]
-    if result.context:
-        lines.append(f"context: {result.context}")
-    return "\n".join(lines) + "\n"
-
-
-def scan_inbound(route: Route, body: str | bytes) -> ScanResult | None:
-    if not route.inspect:
-        return None
-    try:
-        from dlp_detectors import scan_naive_injection  # type: ignore[import-not-found]
-    except ImportError:  # pragma: no cover - gateway's flat module path
-        from .dlp_detectors import scan_naive_injection
-    text = body if isinstance(body, str) else body.decode("utf-8", errors="replace")
-    if _enabled(route.inbound_detectors, "naive_injection_detection"):
-        return scan_naive_injection(text)
-    return None

bot_bottle/gateway/egress/dlp_detectors.py

@@ -19,7 +19,7 @@ from math import log2
 from collections import Counter
 from urllib.parse import quote as url_quote
 
-from .types import ScanResult
+from .addon_core import ScanResult
 
 
 # ---------------------------------------------------------------------------

bot_bottle/gateway/egress/matching.py

@@ -1,112 +0,0 @@
-"""Route matching and request-policy decisions for the egress gateway."""
-
-from __future__ import annotations
-
-import typing
-
-from .types import Decision, MatchEntry, PathMatch, Route
-
-
-def _path_matches(pm: PathMatch, request_path: str) -> bool:
-    if pm.type == "exact":
-        return request_path == pm.value
-    if pm.type == "prefix":
-        if request_path == pm.value:
-            return True
-        if not pm.value.endswith("/"):
-            return request_path.startswith(pm.value + "/")
-        return request_path.startswith(pm.value)
-    return (
-        pm.type == "regex"
-        and pm.compiled is not None
-        and pm.compiled.search(request_path) is not None
-    )
-
-
-def _entry_matches(
-    entry: MatchEntry, request_path: str, request_method: str,
-    request_headers: typing.Mapping[str, str],
-) -> bool:
-    if entry.paths and not any(_path_matches(pm, request_path) for pm in entry.paths):
-        return False
-    if entry.methods and request_method.upper() not in entry.methods:
-        return False
-    for match in entry.headers:
-        value = request_headers.get(match.name.lower())
-        if value is None:
-            return False
-        if match.type == "exact" and value != match.value:
-            return False
-        if match.type == "regex" and (
-            match.compiled is None or match.compiled.search(value) is None
-        ):
-            return False
-    return True
-
-
-def evaluate_matches(
-    route: Route, request_path: str, request_method: str = "GET",
-    request_headers: typing.Mapping[str, str] | None = None,
-) -> bool:
-    """Return whether a request satisfies a route's optional match entries."""
-    if not route.matches:
-        return True
-    return any(_entry_matches(entry, request_path, request_method, request_headers or {})
-               for entry in route.matches)
-
-
-def is_git_push_request(path: str, query: str) -> bool:
-    return path.endswith("/git-receive-pack") or (
-        path.endswith("/info/refs") and any(
-            pair.partition("=") == ("service", "=", "git-receive-pack")
-            for pair in query.split("&")
-        )
-    )
-
-
-def is_git_fetch_request(path: str, query: str) -> bool:
-    return path.endswith("/git-upload-pack") or (
-        path.endswith("/info/refs") and any(
-            pair.partition("=") == ("service", "=", "git-upload-pack")
-            for pair in query.split("&")
-        )
-    )
-
-
-def match_route(routes: typing.Sequence[Route], request_host: str) -> Route | None:
-    target = request_host.lower()
-    return next((route for route in routes if route.host.lower() == target), None)
-
-
-def decide(
-    routes: typing.Sequence[Route], request_host: str, request_path: str,
-    environ: typing.Mapping[str, str], *, request_method: str = "GET",
-    request_headers: typing.Mapping[str, str] | None = None, deny_reason: str = "",
-) -> Decision:
-    route = match_route(routes, request_host)
-    if route is None:
-        return Decision("block", deny_reason or (
-            f"egress: host {request_host!r} is not in the bottle's egress.routes "
-            "allowlist. Declare a route for it or remove the request."))
-    if not evaluate_matches(route, request_path, request_method, request_headers):
-        return Decision("block", (
-            f"egress: request {request_method} {request_path!r} does not match any "
-            f"entry in matches for {route.host!r}"))
-    if route.auth_scheme and route.token_env:
-        token = environ.get(route.token_env, "")
-        if not token:
-            return Decision("block", (
-                f"egress: route for {route.host!r} declared auth but env var "
-                f"{route.token_env!r} is unset"))
-        return Decision("forward", inject_authorization=f"{route.auth_scheme} {token}")
-    return Decision("forward")
-
-
-def decide_git_fetch(routes: typing.Sequence[Route], request_host: str) -> Decision:
-    route = match_route(routes, request_host)
-    if route is not None and route.git_fetch:
-        return Decision("forward")
-    return Decision("block", (
-        "egress: git fetch/clone over HTTPS is not allowed by default; use git-gate "
-        "for declared repos or set egress.routes[].git.fetch=true for explicit "
-        "read-only HTTPS Git access."))

bot_bottle/gateway/egress/schema.py

@@ -1,349 +0,0 @@
-"""Egress policy schema parsing and serialization (PRD 0017 / 0053)."""
-
-from __future__ import annotations
-
-import re
-import typing
-
-from ...yaml_subset import YamlSubsetError, parse_yaml_subset
-from .dlp_config import parse_inspect_block
-from .types import (
-    HEADER_MATCH_TYPES,
-    LOG_BLOCKS,
-    LOG_FULL,
-    LOG_OFF,
-    PATH_MATCH_TYPES,
-    VALID_METHODS,
-    Config,
-    HeaderMatch,
-    MatchEntry,
-    PathMatch,
-    Route,
-)
-
-# Parsing
-# ---------------------------------------------------------------------------
-
-def _parse_path_match(idx: int, j: int, raw: object) -> PathMatch:
-    label = f"route[{idx}] matches paths[{j}]"
-    if not isinstance(raw, dict):
-        raise ValueError(f"{label}: must be an object")
-    raw_dict: dict[str, object] = typing.cast(dict[str, object], raw)
-    ptype = raw_dict.get("type", "prefix")
-    if not isinstance(ptype, str) or ptype not in PATH_MATCH_TYPES:
-        raise ValueError(
-            f"{label}: 'type' must be one of {', '.join(PATH_MATCH_TYPES)} "
-            f"(got {ptype!r})"
-        )
-    value = raw_dict.get("value")
-    if not isinstance(value, str) or not value:
-        raise ValueError(f"{label}: 'value' must be a non-empty string")
-    if ptype in ("exact", "prefix") and not value.startswith("/"):
-        raise ValueError(
-            f"{label}: value {value!r} must start with '/' for "
-            f"type {ptype!r}"
-        )
-    compiled: re.Pattern[str] | None = None
-    if ptype == "regex":
-        try:
-            compiled = re.compile(value)
-        except re.error as e:
-            raise ValueError(
-                f"{label}: regex {value!r} failed to compile: {e}"
-            ) from e
-    for k in raw_dict:
-        if k not in ("type", "value"):
-            raise ValueError(f"{label}: unknown key {k!r}")
-    return PathMatch(type=ptype, value=value, compiled=compiled)
-
-
-def _parse_header_match(idx: int, j: int, raw: object) -> HeaderMatch:
-    label = f"route[{idx}] matches headers[{j}]"
-    if not isinstance(raw, dict):
-        raise ValueError(f"{label}: must be an object")
-    raw_dict: dict[str, object] = typing.cast(dict[str, object], raw)
-    name = raw_dict.get("name")
-    if not isinstance(name, str) or not name:
-        raise ValueError(f"{label}: 'name' must be a non-empty string")
-    value = raw_dict.get("value")
-    if not isinstance(value, str):
-        raise ValueError(f"{label}: 'value' must be a string")
-    htype = raw_dict.get("type", "exact")
-    if not isinstance(htype, str) or htype not in HEADER_MATCH_TYPES:
-        raise ValueError(
-            f"{label}: 'type' must be one of {', '.join(HEADER_MATCH_TYPES)} "
-            f"(got {htype!r})"
-        )
-    compiled: re.Pattern[str] | None = None
-    if htype == "regex":
-        try:
-            compiled = re.compile(value)
-        except re.error as e:
-            raise ValueError(
-                f"{label}: regex {value!r} failed to compile: {e}"
-            ) from e
-    for k in raw_dict:
-        if k not in ("name", "value", "type"):
-            raise ValueError(f"{label}: unknown key {k!r}")
-    return HeaderMatch(name=name, value=value, type=htype, compiled=compiled)
-
-
-def _parse_match_entry(idx: int, k: int, raw: object) -> MatchEntry:
-    label = f"route[{idx}] matches[{k}]"
-    if not isinstance(raw, dict):
-        raise ValueError(f"{label}: must be an object")
-    raw_dict: dict[str, object] = typing.cast(dict[str, object], raw)
-
-    paths: tuple[PathMatch, ...] = ()
-    paths_raw = raw_dict.get("paths")
-    if paths_raw is not None:
-        if not isinstance(paths_raw, list):
-            raise ValueError(f"{label}: 'paths' must be a list")
-        paths_list = typing.cast(list[object], paths_raw)
-        paths = tuple(_parse_path_match(idx, j, p) for j, p in enumerate(paths_list))
-
-    methods: tuple[str, ...] = ()
-    methods_raw = raw_dict.get("methods")
-    if methods_raw is not None:
-        if not isinstance(methods_raw, list):
-            raise ValueError(f"{label}: 'methods' must be a list")
-        methods_list = typing.cast(list[object], methods_raw)
-        normalised: list[str] = []
-        for j, m in enumerate(methods_list):
-            if not isinstance(m, str):
-                raise ValueError(f"{label}: methods[{j}] must be a string")
-            upper = m.upper()
-            if upper not in VALID_METHODS:
-                raise ValueError(
-                    f"{label}: methods[{j}] {m!r} is not a valid HTTP method"
-                )
-            normalised.append(upper)
-        methods = tuple(normalised)
-
-    headers: tuple[HeaderMatch, ...] = ()
-    headers_raw = raw_dict.get("headers")
-    if headers_raw is not None:
-        if not isinstance(headers_raw, list):
-            raise ValueError(f"{label}: 'headers' must be a list")
-        headers_list = typing.cast(list[object], headers_raw)
-        headers = tuple(
-            _parse_header_match(idx, j, h) for j, h in enumerate(headers_list)
-        )
-
-    for key in raw_dict:
-        if key not in ("paths", "methods", "headers"):
-            raise ValueError(f"{label}: unknown key {key!r}")
-
-    return MatchEntry(paths=paths, methods=methods, headers=headers)
-
-
-def parse_routes(payload: object) -> tuple[Route, ...]:
-    if not isinstance(payload, dict):
-        raise ValueError("routes payload: top-level must be an object")
-    payload_dict: dict[str, object] = typing.cast(dict[str, object], payload)
-    raw: object = payload_dict.get("routes")
-    if not isinstance(raw, list):
-        raise ValueError("routes payload: 'routes' must be a list")
-    raw_list: list[object] = typing.cast(list[object], raw)
-    out: list[Route] = []
-    for i, r in enumerate(raw_list):
-        out.append(_parse_one(i, r))
-    return tuple(out)
-
-
-def _parse_one(idx: int, raw: object) -> Route:
-    label = f"route[{idx}]"
-    if not isinstance(raw, dict):
-        raise ValueError(f"{label}: must be an object (got {type(raw).__name__})")
-    raw_dict: dict[str, object] = typing.cast(dict[str, object], raw)
-    host: object = raw_dict.get("host")
-    if not isinstance(host, str) or not host:
-        raise ValueError(f"{label}: 'host' must be a non-empty string")
-    legacy_flat = "inspect" not in raw_dict
-    inspect_raw = raw_dict.get("inspect", {})
-    if inspect_raw is False:
-        inspect = False
-        settings: dict[str, object] = {}
-    elif isinstance(inspect_raw, dict):
-        inspect = True
-        settings = (
-            {k: v for k, v in raw_dict.items() if k != "host"}
-            if legacy_flat
-            else typing.cast(dict[str, object], inspect_raw)
-        )
-        legacy_dlp = settings.pop("dlp", None)
-        if isinstance(legacy_dlp, dict):
-            settings.update(typing.cast(dict[str, object], legacy_dlp))
-        elif legacy_dlp is not None:
-            raise ValueError(
-                f"{label} ({host}): legacy 'dlp' must be an object"
-            )
-    else:
-        raise ValueError(f"{label} ({host}): 'inspect' must be false or an object")
-
-    # matches
-    matches: tuple[MatchEntry, ...] = ()
-    matches_raw = settings.get("matches")
-    if matches_raw is not None:
-        if not isinstance(matches_raw, list):
-            raise ValueError(f"{label} ({host}): 'matches' must be a list")
-        matches_list = typing.cast(list[object], matches_raw)
-        matches = tuple(
-            _parse_match_entry(idx, k, m) for k, m in enumerate(matches_list)
-        )
-
-    # auth (unchanged wire format)
-    auth_scheme: object = settings.get("auth_scheme", "")
-    token_env: object = settings.get("token_env", "")
-    if not isinstance(auth_scheme, str):
-        raise ValueError(f"{label} ({host}): 'auth_scheme' must be a string")
-    if not isinstance(token_env, str):
-        raise ValueError(f"{label} ({host}): 'token_env' must be a string")
-    if bool(auth_scheme) != bool(token_env):
-        raise ValueError(
-            f"{label} ({host}): 'auth_scheme' and 'token_env' must be both "
-            f"set or both empty (got auth_scheme={auth_scheme!r}, "
-            f"token_env={token_env!r})"
-        )
-
-    # git-over-HTTPS policy
-    git_fetch = False
-    git_raw = settings.get("git")
-    if git_raw is not None:
-        if not isinstance(git_raw, dict):
-            raise ValueError(f"{label} ({host}): 'git' must be an object")
-        git_dict: dict[str, object] = typing.cast(dict[str, object], git_raw)
-        fetch_raw = git_dict.get("fetch", False)
-        if fetch_raw is True or fetch_raw is False:
-            git_fetch = fetch_raw
-        else:
-            raise ValueError(f"{label} ({host}): 'git.fetch' must be a boolean")
-        for k in git_dict:
-            if k != "fetch":
-                raise ValueError(
-                    f"{label} ({host}): git has unknown key {k!r}; "
-                    "accepted key is 'fetch'"
-                )
-
-    # dlp detectors
-    outbound_detectors, inbound_detectors, outbound_on_match = parse_inspect_block(
-        idx, host, settings,
-    )
-
-    preserve_auth_raw = settings.get("preserve_auth", False)
-    if preserve_auth_raw is not True and preserve_auth_raw is not False:
-        raise ValueError(
-            f"{label} ({host}): 'preserve_auth' must be a boolean"
-        )
-    preserve_auth: bool = preserve_auth_raw
-
-    for k in settings:
-        if k not in (
-            "matches", "auth_scheme", "token_env", "git", "preserve_auth",
-            "outbound_detectors", "inbound_detectors", "outbound_on_match",
-        ):
-            raise ValueError(
-                f"{label} ({host}): inspect has unknown key {k!r}"
-            )
-    for k in raw_dict:
-        if not legacy_flat and k not in ("host", "inspect"):
-            raise ValueError(
-                f"{label} ({host}): unknown key {k!r}; accepted keys "
-                f"are 'host' and 'inspect'"
-            )
-
-    return Route(
-        host=host,
-        matches=matches,
-        auth_scheme=auth_scheme,
-        token_env=token_env,
-        git_fetch=git_fetch,
-        outbound_detectors=outbound_detectors,
-        inbound_detectors=inbound_detectors,
-        outbound_on_match=outbound_on_match,
-        preserve_auth=preserve_auth,
-        inspect=inspect,
-    )
-
-
-def _path_match_to_dict(pm: PathMatch) -> dict[str, object]:
-    d: dict[str, object] = {"value": pm.value}
-    if pm.type != "prefix":
-        d["type"] = pm.type
-    return d
-
-
-def _header_match_to_dict(hm: HeaderMatch) -> dict[str, object]:
-    d: dict[str, object] = {"name": hm.name, "value": hm.value}
-    if hm.type != "exact":
-        d["type"] = hm.type
-    return d
-
-
-def _match_entry_to_dict(me: MatchEntry) -> dict[str, object]:
-    d: dict[str, object] = {}
-    if me.paths:
-        d["paths"] = [_path_match_to_dict(p) for p in me.paths]
-    if me.methods:
-        d["methods"] = list(me.methods)
-    if me.headers:
-        d["headers"] = [_header_match_to_dict(h) for h in me.headers]
-    return d
-
-
-def route_to_yaml_dict(r: Route) -> dict[str, object]:
-    """Serialize a Route to YAML-schema-compatible dict.
-
-    Uses the same field names the YAML parser accepts, so the output
-    can be round-tripped directly into an `allow` or `egress-block`
-    proposal without translation. Fields that are empty/default are
-    omitted so the agent doesn't copy irrelevant keys."""
-    d: dict[str, object] = {"host": r.host}
-    if not r.inspect:
-        d["inspect"] = False
-        return d
-    inspected: dict[str, object] = {}
-    if r.auth_scheme:
-        inspected["auth_scheme"] = r.auth_scheme
-        inspected["token_env"] = r.token_env
-    if r.matches:
-        inspected["matches"] = [_match_entry_to_dict(m) for m in r.matches]
-    if r.git_fetch:
-        inspected["git"] = {"fetch": True}
-    if r.outbound_detectors is not None:
-        inspected["outbound_detectors"] = list(r.outbound_detectors)
-    if r.inbound_detectors is not None:
-        inspected["inbound_detectors"] = list(r.inbound_detectors)
-    if r.outbound_on_match:
-        inspected["outbound_on_match"] = r.outbound_on_match
-    if r.preserve_auth:
-        inspected["preserve_auth"] = True
-    if inspected:
-        d["inspect"] = inspected
-    return d
-
-
-def parse_config(payload: object) -> "Config":
-    """Parse a full egress config payload (top-level log level + routes)."""
-    if not isinstance(payload, dict):
-        raise ValueError("routes payload: top-level must be an object")
-    payload_dict: dict[str, object] = typing.cast(dict[str, object], payload)
-
-    log_raw: object = payload_dict.get("log", LOG_OFF)
-    if log_raw is True or log_raw is False or not isinstance(log_raw, int) \
-            or log_raw not in (LOG_OFF, LOG_BLOCKS, LOG_FULL):
-        raise ValueError(
-            f"routes payload: 'log' must be {LOG_OFF}, {LOG_BLOCKS}, or {LOG_FULL}"
-        )
-
-    routes = parse_routes(payload)
-    return Config(routes=routes, log=log_raw)
-
-
-def load_config(text: str) -> "Config":
-    """Parse YAML text → Config (routes + log flag)."""
-    try:
-        payload = parse_yaml_subset(text)
-    except YamlSubsetError as e:
-        raise ValueError(f"routes payload: invalid YAML: {e}") from e
-    return parse_config(payload)

bot_bottle/gateway/egress/types.py

@@ -1,81 +0,0 @@
-"""Shared egress policy value objects.
-
-Kept dependency-free so the schema parser, matcher, DLP scanner, and addon
-adapter can use the same immutable public shapes without importing each other.
-"""
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-
-
-PATH_MATCH_TYPES = ("exact", "prefix", "regex")
-HEADER_MATCH_TYPES = ("exact", "regex")
-VALID_METHODS = frozenset({
-    "GET", "HEAD", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "TRACE",
-    "CONNECT",
-})
-
-LOG_OFF = 0
-LOG_BLOCKS = 1
-LOG_FULL = 2
-
-
-@dataclass(frozen=True)
-class PathMatch:
-    type: str
-    value: str
-    compiled: re.Pattern[str] | None = None
-
-
-@dataclass(frozen=True)
-class HeaderMatch:
-    name: str
-    value: str
-    type: str = "exact"
-    compiled: re.Pattern[str] | None = None
-
-
-@dataclass(frozen=True)
-class MatchEntry:
-    paths: tuple[PathMatch, ...] = ()
-    methods: tuple[str, ...] = ()
-    headers: tuple[HeaderMatch, ...] = ()
-
-
-@dataclass(frozen=True)
-class Route:
-    host: str
-    matches: tuple[MatchEntry, ...] = ()
-    auth_scheme: str = ""
-    token_env: str = ""
-    git_fetch: bool = False
-    outbound_detectors: tuple[str, ...] | None = None
-    inbound_detectors: tuple[str, ...] | None = None
-    outbound_on_match: str = ""
-    preserve_auth: bool = False
-    inspect: bool = True
-
-
-@dataclass(frozen=True)
-class Config:
-    routes: tuple[Route, ...]
-    log: int = LOG_OFF
-    deny_reason: str = ""
-
-
-@dataclass(frozen=True)
-class Decision:
-    action: str
-    reason: str = ""
-    inject_authorization: str | None = None
-
-
-@dataclass(frozen=True)
-class ScanResult:
-    severity: str
-    reason: str
-    location: str = ""
-    context: str = ""
-    matched: str = ""

bot_bottle/gateway/supervisor/server.py

@@ -17,7 +17,7 @@ Each queued proposal tool call:
   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 0072 / issue #412).
+     non-blocking past the grace window (PRD prd-new / issue #412).
 
 `check-proposal` is the non-blocking companion: given a `proposal_id`
 returned by a `pending` response, it reports the current decision
@@ -58,9 +58,9 @@ import typing
 from dataclasses import dataclass
 
 from bot_bottle.constants import IDENTITY_HEADER
-from bot_bottle.gateway.egress.context import resolve_client_context
-from bot_bottle.gateway.egress.schema import load_config, route_to_yaml_dict
-from bot_bottle.gateway.egress.types import LOG_OFF
+from bot_bottle.gateway.egress.addon_core import (
+    LOG_OFF, load_config, resolve_client_context, route_to_yaml_dict,
+)
 from bot_bottle.gateway.policy_resolver import PolicyResolveError, PolicyResolver
 from bot_bottle.supervisor import types as _sv
 

bot_bottle/orchestrator/client.py

@@ -18,7 +18,6 @@ import urllib.request
 from collections.abc import Iterable
 from dataclasses import dataclass
 
-from ..log import debug
 from ..orchestrator_auth import ROLE_CLI
 from ..trust_domain import CONTROL_PLANE
 from .server import ORCHESTRATOR_AUTH_HEADER
@@ -54,23 +53,6 @@ class RegisteredBottle:
     env_var_secret: str = ""
 
 
-@dataclass(frozen=True)
-class BackendProbeFailure:
-    """Safe diagnostic for an optional backend discovery probe."""
-
-    backend: str
-    error_type: str
-
-
-def _probe_failure(backend: str, exc: BaseException) -> BackendProbeFailure:
-    failure = BackendProbeFailure(backend, type(exc).__name__)
-    debug(
-        "orchestrator discovery probe unavailable",
-        context={"backend": failure.backend, "error_type": failure.error_type},
-    )
-    return failure
-
-
 class OrchestratorClient:
     """Trusted host-side client for the orchestrator control plane.
 
@@ -263,41 +245,32 @@ def discover_orchestrator_url(*, timeout: float = 2.0) -> str:
     orchestrator TAP. Returns the first that answers `/health`; raises if none
     do (no orchestrator up — launch a bottle first)."""
     candidates: list[str] = []
-    failures: list[BackendProbeFailure] = []
     try:  # docker: loopback-published control plane
         from .lifecycle import DEFAULT_PORT as _DOCKER_PORT
         candidates.append(f"http://127.0.0.1:{_DOCKER_PORT}")
-    except Exception as exc:  # noqa: BLE001 — backend optional
-        failures.append(_probe_failure("docker", exc))
+    except Exception:  # noqa: BLE001 — backend optional
         candidates.append("http://127.0.0.1:8099")
     try:  # firecracker: infra VM control plane on the orchestrator TAP
         from ..backend.firecracker import netpool
         from ..backend.firecracker.infra_vm import ORCHESTRATOR_PORT
         candidates.append(
             f"http://{netpool.orch_slot().guest_ip}:{ORCHESTRATOR_PORT}")
-    except Exception as exc:  # noqa: BLE001 — backend optional / not firecracker
-        failures.append(_probe_failure("firecracker", exc))
+    except Exception:  # noqa: BLE001 — backend optional / not firecracker
+        pass
     try:  # macOS: orchestrator container on its host-only address
         from ..backend.macos_container.infra import probe_orchestrator_url
         url = probe_orchestrator_url()
         if url:
             candidates.append(url)
-    except Exception as exc:  # noqa: BLE001 — backend optional / not macOS
-        failures.append(_probe_failure("macos-container", exc))
+    except Exception:  # noqa: BLE001 — backend optional / not macOS
+        pass
     for url in candidates:
         if OrchestratorClient(url, timeout=timeout).health():
             return url
-    detail = ""
-    if failures:
-        detail = "; optional probes unavailable: " + ", ".join(
-            f"{failure.backend} ({failure.error_type})" for failure in failures
-        )
     raise OrchestratorClientError(
         "no running orchestrator control plane found (tried "
         + ", ".join(candidates)
-        + ")"
-        + detail
-        + "; launch a bottle first"
+        + "); launch a bottle first"
     )
 
 

bot_bottle/orchestrator/reprovision.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-from ..log import debug
 from .client import OrchestratorClient, OrchestratorClientError
 
 
@@ -28,14 +27,7 @@ def reprovision_bottles(
         try:
             if client.reprovision_gateway(bottle_id, secret):
                 restored += 1
-        except OrchestratorClientError as exc:
-            debug(
-                "gateway secret reprovision failed; continuing with other bottles",
-                context={
-                    "bottle_id": bottle_id,
-                    "error_type": type(exc).__name__,
-                },
-            )
+        except OrchestratorClientError:
             continue
     return restored
 

bot_bottle/orchestrator/server.py

@@ -57,7 +57,6 @@ from __future__ import annotations
 
 import http.server
 import json
-import math
 import os
 import socketserver
 import sys
@@ -218,18 +217,13 @@ def dispatch(  # pylint: disable=too-many-return-statements,too-many-branches
         raw_ips = data.get("live_source_ips")
         if not isinstance(raw_ips, list):
             return 400, {"error": "live_source_ips (list of strings) is required"}
-        if any(not isinstance(ip, str) or not ip for ip in raw_ips):
-            return 400, {"error": "live_source_ips must contain non-empty strings"}
-        live = raw_ips
+        live = [ip for ip in raw_ips if isinstance(ip, str) and ip]
         grace = data.get("grace_seconds")
-        kwargs: dict[str, float] = {}
-        if grace is not None:
-            if isinstance(grace, bool) or not isinstance(grace, (int, float)):
-                return 400, {"error": "grace_seconds must be a non-negative finite number"}
-            parsed_grace = float(grace)
-            if not math.isfinite(parsed_grace) or parsed_grace < 0:
-                return 400, {"error": "grace_seconds must be a non-negative finite number"}
-            kwargs["grace_seconds"] = parsed_grace
+        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":
@@ -379,15 +373,9 @@ class Handler(http.server.BaseHTTPRequestHandler):
             status, payload = dispatch(
                 server.orchestrator, method, self.path, body, role=role)
         except Exception as e:  # noqa: BLE001 — the control plane must stay up
-            # Do not echo exception messages to the caller or logs: broker and
-            # persistence exceptions can contain request data. The operation,
-            # route, and exception type are enough to correlate a traceback.
-            sys.stderr.write(
-                f"orchestrator: {method} {self.path} failed "
-                f"[error_type={type(e).__name__}]\n"
-            )
+            sys.stderr.write(f"orchestrator: {method} {self.path} failed: {e!r}\n")
             sys.stderr.flush()
-            status, payload = 500, {"error": "internal error"}
+            status, payload = 500, {"error": f"internal error: {e}"}
         data = json.dumps(payload).encode()
         self.send_response(status)
         self.send_header("Content-Type", "application/json")

bot_bottle/orchestrator/store/registry_store.py

@@ -113,7 +113,7 @@ _MIGRATIONS = TableMigrations(
         # egress allowlist / routes / git config selected by source IP. The
         # multi-tenant gateway resolves it per request via `attribute`.
         "ALTER TABLE orchestrator_bottles ADD COLUMN policy TEXT NOT NULL DEFAULT ''",
-        # v4 — per-bottle encrypted egress secrets (PRD 0080).
+        # v4 — per-bottle encrypted egress secrets (PRD prd-new-secret-provider).
         # One row per env-var: key (env-var name) is plaintext for auditing;
         # value is the encrypted token string. The encryption key (ENV_VAR_SECRET)
         # lives only in the agent's environment — a row alone cannot recover the

bot_bottle/orchestrator/store/secret_store.py

@@ -1,4 +1,4 @@
-"""Symmetric encryption for per-bottle egress secrets (PRD 0080).
+"""Symmetric encryption for per-bottle egress secrets (PRD prd-new-secret-provider).
 
 Each agent receives a random ENV_VAR_SECRET at startup — passed as an env var,
 never logged or persisted. The host uses this key to encrypt each egress auth

bot_bottle/resources.py

@@ -1,159 +0,0 @@
-"""Locate build-time resources whether bot-bottle runs from a source
-checkout or an installed wheel.
-
-The gateway / infra / orchestrator images are built from a Docker (or Apple
-`container`) build context that must contain the `bot_bottle` package,
-`pyproject.toml`, and the root-level Dockerfiles as siblings. In a source
-checkout that context is simply the repo root, one level above the package.
-An installed wheel has no repo root: the same root-level files are shipped
-inside the package under ``bot_bottle/_resources/`` (see ``setup.py``), and a
-repo-root-shaped build context is staged on demand into the app-data dir.
-
-``build_root()`` is the single source of truth — it returns a directory laid
-out like a repo root (has ``bot_bottle/``, ``pyproject.toml``, the
-Dockerfiles, ``nix/``, ``scripts/``). Every caller that needs a build
-context, a Dockerfile path, the nix netpool module, or the netpool script
-derives from it, so checkout and wheel installs share one downstream path.
-"""
-
-from __future__ import annotations
-
-import fcntl
-import hashlib
-import os
-import shutil
-import tempfile
-from pathlib import Path
-
-from .paths import bot_bottle_root
-
-_PKG = Path(__file__).resolve().parent          # …/bot_bottle
-_CHECKOUT_ROOT = _PKG.parent                     # repo root in a checkout
-_BUNDLED = _PKG / "_resources"                   # wheel-shipped copies
-
-# Root-level files bundled into the wheel under ``_resources/`` (paths are
-# relative to the checkout root, and preserved verbatim under ``_resources/``
-# and in the staged build root). ``setup.py`` copies exactly this set; keep
-# the two lists in sync (``test_resources`` guards that every entry exists).
-BUNDLED_RESOURCES: tuple[str, ...] = (
-    "pyproject.toml",
-    "Dockerfile.gateway",
-    "Dockerfile.orchestrator",
-    "Dockerfile.orchestrator.fc",
-    "nix/firecracker-netpool.nix",
-    "scripts/firecracker-netpool.sh",
-)
-
-# Present at a checkout root, never in a bare installed package — the cheap
-# tell for which layout we're in.
-_CHECKOUT_MARKER = "Dockerfile.gateway"
-
-
-class ResourceError(RuntimeError):
-    """Build resources are missing from the install (corrupt/partial wheel)."""
-
-
-def is_source_checkout() -> bool:
-    """True when running from a source tree (the root Dockerfiles sit beside
-    the package); False from an installed wheel."""
-    return (_CHECKOUT_ROOT / _CHECKOUT_MARKER).is_file()
-
-
-def build_root() -> Path:
-    """A directory shaped like a repo root: ``bot_bottle/``, ``pyproject.toml``,
-    the root Dockerfiles, ``nix/``, and ``scripts/``.
-
-    A checkout returns the repo root itself (no copying). An installed wheel
-    returns a staged copy under the app-data dir, materialized once and reused.
-    The stage is keyed by a digest of the installed package + bundled resources
-    (not the distribution version), so a force-reinstall of a newer commit that
-    keeps ``version = 0.1.0`` still rebuilds instead of reusing a stale tree."""
-    if is_source_checkout():
-        return _CHECKOUT_ROOT
-    return _stage_build_root()
-
-
-def dockerfile(name: str) -> Path:
-    """Absolute path to a root-level Dockerfile, e.g. ``Dockerfile.gateway``."""
-    return build_root() / name
-
-
-def nix_netpool_module() -> Path:
-    """Absolute path to the firecracker netpool NixOS module."""
-    return build_root() / "nix" / "firecracker-netpool.nix"
-
-
-def netpool_script() -> Path:
-    """Absolute path to the firecracker netpool bring-up script."""
-    return build_root() / "scripts" / "firecracker-netpool.sh"
-
-
-def _content_digest() -> str:
-    """A 16-hex digest of the installed package + bundled resources.
-
-    Keys the staged build root by *content*, so a force-reinstall over the same
-    version string (the installer defaults to a git branch + ``pipx install
-    --force``, and ``version`` stays ``0.1.0``) yields a different key and
-    re-stages, rather than reusing an old commit's tree. ``_PKG`` already
-    contains ``_resources``, so walking it covers both."""
-    h = hashlib.sha256()
-    for path in sorted(_PKG.rglob("*")):
-        if not path.is_file() or "__pycache__" in path.parts or path.suffix == ".pyc":
-            continue
-        h.update(str(path.relative_to(_PKG)).encode())
-        h.update(b"\0")
-        h.update(path.read_bytes())
-    return h.hexdigest()[:16]
-
-
-def _stage_build_root() -> Path:
-    """Materialize a repo-root-shaped build context from the installed wheel's
-    bundled resources, keyed by content digest. Idempotent and concurrency-safe:
-    a file lock serializes staging, a partial/stale tree is replaced, and the
-    finished tree is published with an atomic rename."""
-    if not _BUNDLED.is_dir():
-        raise ResourceError(
-            "bot-bottle build resources are missing from this install "
-            f"(expected {_BUNDLED}). Reinstall the package."
-        )
-    base = bot_bottle_root() / "build-root"
-    base.mkdir(parents=True, exist_ok=True)
-    dest = base / _content_digest()
-    if (dest / ".complete").is_file():
-        return dest
-
-    # Serialize staging across processes: a concurrent `start` after an install
-    # must not race on the shared tree. The lock is held only around stage +
-    # atomic publish; the fast path above never blocks.
-    with open(base / ".stage.lock", "w", encoding="utf-8") as lock:
-        fcntl.flock(lock, fcntl.LOCK_EX)
-        if (dest / ".complete").is_file():  # another process staged while we waited
-            return dest
-        # Stage into a private temp dir on the same filesystem, then publish by
-        # rename — never populate a shared path other processes might read.
-        staging = Path(tempfile.mkdtemp(prefix=".staging-", dir=base))
-        try:
-            # The package itself, minus caches and the bundled-resource copies,
-            # so the staged ``bot_bottle/`` matches a checkout's (keeps the
-            # firecracker infra-artifact hash stable across checkout and wheel).
-            shutil.copytree(
-                _PKG,
-                staging / "bot_bottle",
-                ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "_resources"),
-            )
-            # The bundled root files, restored to their checkout-relative layout.
-            for rel in BUNDLED_RESOURCES:
-                dst = staging / rel
-                dst.parent.mkdir(parents=True, exist_ok=True)
-                shutil.copy2(_BUNDLED / rel, dst)
-            (staging / ".complete").write_text("")
-            # Replace any partial leftover for this digest (safe: we hold the
-            # lock), then publish atomically.
-            if dest.exists():
-                shutil.rmtree(dest)
-            os.replace(staging, dest)
-            staging = None  # published; nothing to clean up
-        finally:
-            if staging is not None:
-                shutil.rmtree(staging, ignore_errors=True)
-    return dest

bot_bottle/trust_domain.py

@@ -17,7 +17,7 @@ instead would defeat that — the orchestrator holds that key, so it could forge
 `ControlPlaneProvisioning` is the one seam every backend launcher uses to get the
 orchestrator its key and the gateway its token, instead of re-deriving that
 wiring per backend (the bug class behind PR #471 — see
-`docs/prds/0079-control-plane-auth-provisioning.md`).
+`docs/prds/prd-new-control-plane-auth-provisioning.md`).
 
 Stdlib-only: the HMAC lives in `orchestrator_auth`, the key file in `paths`.
 """

bot_bottle/util.py

@@ -9,11 +9,8 @@ import difflib
 import hashlib
 import ipaddress
 import os
-import re
 import sys
 
-from .log import die
-
 
 def sha256_hex(content: str) -> str:
     """Hex SHA-256 of a UTF-8 string."""
@@ -70,20 +67,3 @@ def expand_tilde(path: str) -> str:
         home = os.environ.get("HOME", "")
         return home + path[1:]
     return path
-
-
-_SLUG_RE = re.compile(r"[^a-z0-9]+")
-
-
-def slugify(name: str) -> str:
-    """Return a portable bottle identifier from a human-readable name.
-
-    This is deliberately a root utility: names are part of the generic CLI
-    and state model, not a Docker container concern.
-    """
-    if not name:
-        die("slugify: missing name")
-    slug = _SLUG_RE.sub("-", name.lower()).strip("-")
-    if not slug:
-        die(f"name '{name}' produced an empty slug; use alphanumeric characters")
-    return slug

docs/README.md

@@ -7,7 +7,6 @@ picking the right document for what you're capturing.
 
 | Artifact | For |
 |---|---|
-| **Design workflow** (`docs/design-workflow.md`) | How discussion becomes canonical design, how dependencies are recorded, and when implementation may begin. |
 | **Glossary** (`docs/glossary.md`) | Canonical term definitions — what words mean in this project. |
 | **PRD** (`docs/prds/`) | A feature: what to build, scope, success criteria. |
 | **Research note** (`docs/research/`) | A landscape/tradeoff investigation. |

docs/ci.md

@@ -1,53 +1,39 @@
 # CI
 
-## Required pull-request gate
+The test workflow lives at [`.gitea/workflows/test.yml`](../.gitea/workflows/test.yml).
+It runs the unit suite plus one integration job per backend
+(`integration-docker`, `integration-firecracker`) on:
 
-[`.gitea/workflows/test.yml`](../.gitea/workflows/test.yml) runs the unit
-suite, Docker integration suite, combined coverage report, and diff-coverage
-gate when tested package/build inputs change on a pull request or on `main`.
+- every push to a branch with an open pull request, and
+- every push to `main`.
 
-The Docker job preflights the backend before discovery. Gitea's `act_runner`
-runs the job in a container with the host Docker socket, so the test process
-reaches control-plane siblings through the job's Docker network and uses named
-Docker volumes for orchestrator/CA state the host daemon must mount. The
-orchestrator runs the package baked into the image built from the checkout; it
-does not bind the job container's invisible workspace into a sibling container.
-Docker integration jobs share fixed singleton names, so required and manual
-runs use one non-cancelling concurrency group. The shared agent/gateway network
-has an explicit subnet, which Docker requires for the pinned source IPs used as
-the isolation/attribution key.
+Each integration job selects its backend via `BOT_BOTTLE_BACKEND` and
+runs a **preflight** (`./cli.py backend status --backend=<name>`) that
+prints a clear per-check readiness summary and fails the job when the
+backend is missing — so absent infrastructure is visible at the job level
+rather than hidden among per-test `unittest.skip` lines. The skip guards in
+[`tests/_backend.py`](../tests/_backend.py) gate on the same readiness
+check (`bot_bottle.backend.has_backend`): backend-agnostic tests use
+`skip_unless_selected_backend_available()` and run through whichever
+backend is selected (checking, e.g., Linux + `/dev/kvm` for Firecracker
+rather than unrelated Docker availability); Docker-implementation tests use
+`skip_unless_backend("docker")` and no-op under a non-Docker run.
 
-`scripts.unittest_gate` enforces the Docker job's contract: all 22 integration
-tests must execute and none may skip. This includes the real gateway-image,
-control-plane authentication, multitenant policy/token isolation,
-sandbox-escape, and orphan-network tests. Backend skip decorators remain useful
-for local runs, but the CI preflight plus execution-count gate prevents a
-missing backend or runner-topology regression from becoming a green job.
+A small subset of integration tests skip when running specifically
+under Gitea Actions (`GITEA_ACTIONS=true`), because `act_runner` runs
+the job inside a container with the host's `/var/run/docker.sock`
+mounted in. That topology breaks two assumptions those tests make:
 
-Combined unit + Docker coverage is informational globally. Two focused gates
-are enforced:
+- networks created via the host daemon aren't always visible to a
+  same-process `docker network ls` call from inside the job container,
+  and
+- ports published by sibling containers land on the host's loopback,
+  not on the job container's `127.0.0.1` — so HTTP probes against
+  `http://127.0.0.1:<host_port>` from inside the job time out.
 
-- changed executable Python lines must be at least 90% covered; and
-- the validated critical security/logic core must remain at least 90% covered.
-
-## Privileged pre-release matrix
-
-[`.gitea/workflows/pre-release-test.yml`](../.gitea/workflows/pre-release-test.yml)
-is manually dispatched before a release. It repeats unit and Docker integration
-coverage, then runs:
-
-- Firecracker integration on the self-hosted `kvm` runner; and
-- advisory Apple Container integration on the self-hosted `macos` runner.
-
-These privileged host-mode runners never execute unreviewed pull-request code
-automatically. Firecracker coverage is combined in the manual pre-release
-report; macOS reports advisory coverage in its own job. The macOS infra
-container is a singleton, so its job uses a concurrency group and always tears
-the service down.
-
-## Scheduled canary
-
-[`.gitea/workflows/canaries.yml`](../.gitea/workflows/canaries.yml) runs weekly
-and on manual dispatch. It verifies the pinned gitleaks release URL, checksum,
-archive shape, and executable. The same unittest execution gate requires at
-least one executed canary and rejects skips.
+The affected tests (`test_orphan_cleanup.test_create_and_remove`,
+`test_gateway_image.TestGatewayImage`) still run
+locally where the test process and Docker daemon share a host.
+Making them work in CI is a follow-up: either re-write them to
+discover container IPs via `docker inspect`, or reconfigure the
+runner with host networking.

docs/decisions/0004-coverage-policy.md

@@ -34,13 +34,12 @@ a regression (Goodhart's law).
 Coverage is **risk-weighted**, measured over the **combined unit +
 integration** suites, with three rules:
 
-1. **Critical modules must remain ≥ 90%.** The curated security/logic core
-   covers the host and gateway egress policy, manifest trust boundary,
-   git-gate enforcement, supervise protocol/server, YAML parser, and bottle
-   state. The concrete module list lives in `scripts/critical-modules.txt`;
-   `scripts/critical_modules.py` rejects stale or ambiguous entries before
-   Coverage.py can silently ignore them. These modules are unit-testable, so
-   CI enforces the aggregate minimum independently of diff coverage.
+1. **Critical modules target ≥ 90%.** The security/logic core —
+   `egress_addon{,_core}.py`, `dlp_detectors.py`, `egress.py`,
+   `manifest*.py`, `git_gate.py`, `git_http_backend.py`, `supervise.py`,
+   `yaml_subset.py`, `bottle_state.py` — is Docker-independent and
+   unit-testable, so it carries the high bar. We ratchet toward 90% as
+   these modules are touched; new gaps in them are not acceptable.
 
 2. **Subprocess/backend orchestration is covered by the integration
    suite, not omitted.** `scripts/coverage.sh` runs unit + integration
@@ -83,9 +82,6 @@ omit list.
   (critical-module standard + diff coverage) are Docker-independent.
 - "We're at N%" is now a curated figure; outsiders should read the
   policy, not just the badge.
-- A rename or removal in the curated list fails CI. Updating the list is an
-  explicit review of where the security-critical behavior moved, not a way to
-  improve the percentage by omission.
 
 ## Links
 

docs/decisions/0005-issues-own-tracker-metadata.md

@@ -1,13 +1,9 @@
-# ADR 0005: Keep tracker metadata on one tracker object
+# ADR 0005: Keep tracker metadata on issues
 
 - **Status:** Accepted
 - **Date:** 2026-07-18
 - **Deciders:** didericis
 
-> **Amended 2026-07-26.** A pull request may carry labels directly instead of
-> linking a tracking issue. When a PR does link an issue, the issue remains the
-> canonical owner of planning metadata and the reference is validated.
-
 ## Context
 
 Gitea exposes labels on both issues and pull requests. Applying the same labels
@@ -24,29 +20,19 @@ would make the issue history less truthful.
 
 ## Decision
 
-Issues are the canonical tracker records and own labels when a separate work
-item exists. Every issue has at least one label. An issue opened or left
-without labels receives `Status/Needs Triage` automatically until it is
-classified.
+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.
 
-Every new pull request is tracked in exactly one of two mutually exclusive
-ways:
-
-1. It deliberately references at least one existing issue in its title or
-   description. Tracker metadata stays on that issue and the PR remains
-   unlabelled.
-2. It carries at least one label directly when a separate issue would add no
-   useful planning context.
-
-Issue references use one of these forms:
+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 the exclusive either/or PR rule, validates any issue
-references, and repairs the empty issue-label state. Branch protection makes
-the PR policy check required.
+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
@@ -54,13 +40,9 @@ issues or PR labels are created solely to make history conform.
 
 ## Consequences
 
-- Classification, priority, and workflow metadata have one source of truth for
-  each change: the linked issue when one exists, otherwise the PR.
-- For issue-backed changes, the PR's issue link is the navigation path to its
-  planning metadata.
+- 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.
-- Small standalone changes do not require a tracking issue created solely to
-  satisfy automation.
 - `Status/Needs Triage` is an intentional fallback, not a final
   classification.
 - Direct issue creation remains convenient; automation repairs a missing label
@@ -71,6 +53,5 @@ issues or PR labels are created solely to make history conform.
 ## Links
 
 - Issue #405.
-- `.gitea/workflows/tracker-policy-pr.yml`.
-- `.gitea/workflows/tracker-policy-issues.yml`.
+- `.gitea/workflows/tracker-policy.yml`.
 - `scripts/tracker_policy.py`.

docs/design-workflow.md

@@ -1,218 +0,0 @@
-# Design workflow
-
-How bot-bottle turns discussion into canonical design and then into
-implementation without leaving the repository's architecture scattered across
-issue and review threads.
-
-The goal is not more documentation. The goal is one discoverable current answer
-for every load-bearing design question.
-
-## Sources of truth
-
-Design artifacts have different jobs:
-
-| Artifact | Authority |
-|---|---|
-| Decision records | Stable system-wide boundaries, policies, and invariants |
-| PRDs | The current design for a feature |
-| Research notes | Evidence and tradeoff analysis; informative, not normative |
-| Issues | Work tracking, open questions, and discussion |
-| Pull-request comments | Review history; never the final home of a design decision |
-
-When a discussion changes the design, update the relevant PRD or decision
-record before treating the discussion as resolved. A comment may explain why a
-decision changed, but future implementers must not need to reconstruct the
-decision from a thread.
-
-Avoid duplicating the same rule in several canonical documents. Prefer one
-canonical statement and links from dependent documents.
-
-## Choosing the canonical artifact
-
-Use a PRD when the decision describes a feature: its behavior, scope, success
-criteria, trust model, implementation slices, and tests.
-
-Use a decision record when the choice is broader than one feature or will
-constrain several future features. Examples include state ownership, credential
-boundaries, compatibility policy, and what the project does or does not claim
-as a security guarantee.
-
-Use a research note when the conclusion depends on comparing external systems,
-protocols, or approaches. Promote any resulting project decision into a PRD or
-decision record.
-
-## From discussion to implementation
-
-### 1. Open the design discussion
-
-An issue may start with incomplete requirements. Record:
-
-- the problem and desired outcome;
-- known security or compatibility constraints;
-- the current owner of affected state and credentials;
-- related PRDs, decisions, issues, and pull requests;
-- open questions that would materially change the implementation.
-
-Do not disguise an unresolved trust-boundary or state-ownership decision as an
-implementation detail.
-
-### 2. Draft or update the canonical design
-
-Before substantial implementation, write the feature PRD and update any
-system-wide decision it changes.
-
-An active design should make these relationships visible near its top:
-
-```markdown
-Status: Draft | Active | Superseded | Retargeted
-Depends on: #...
-Supersedes: ...
-```
-
-Record dependencies only on the dependent document. Do not maintain reverse
-`Blocks` lists that can drift as dependent work changes.
-
-For security-sensitive work, state:
-
-- the exact guarantee and explicit non-guarantees;
-- trusted and untrusted components;
-- who creates each identity or attribution field;
-- who owns durable state;
-- failure and recovery behavior;
-- how the design is tested at its boundaries.
-
-### 3. Resolve review into the repository
-
-When review settles a design-changing question:
-
-1. Update the canonical document in the same pull request.
-2. Mark conflicting documents Superseded or Retargeted, or update them.
-3. Add or adjust dependency links.
-4. Leave a concise resolution comment linking to the canonical change.
-
-A useful resolution comment is:
-
-```text
-Resolution: <what was decided>
-Canonicalized in: <document/section/commit>
-Supersedes: <older statement, if any>
-Follow-up: <remaining implementation or question>
-```
-
-The resolution is incomplete until the repository reflects it.
-
-### 4. Check design readiness
-
-Implementation may begin when:
-
-- the PRD's material trust, ownership, and compatibility questions are settled;
-- dependencies and blockers are explicit;
-- the design agrees with current architecture and decision records;
-- superseded documents are marked or updated;
-- success criteria and boundary tests are concrete;
-- remaining open questions can be answered during implementation without
-  changing the feature's guarantee or component ownership.
-
-Small exploratory spikes may happen earlier. A spike proves feasibility; it does
-not establish a production contract or silently settle the design.
-
-### 5. Implement in ordered slices
-
-Prefer small, independently reviewable slices after the parent design is
-accepted. Record the dependency chain explicitly.
-
-Parallel work is safe when slices do not compete for the same unsettled
-interface or ownership boundary. If a foundational change will alter the
-transport, schema, state owner, or trust domain used by another slice, land the
-foundation first.
-
-An implementation pull request should identify:
-
-- the PRD or decision it implements;
-- the implementation chunk;
-- its base and blockers;
-- any design deviation discovered during implementation.
-
-If implementation reveals a load-bearing design change, pause that slice and
-update the canonical design. Do not let the code and review thread become an
-undocumented replacement for the PRD.
-
-## Dependency and staleness management
-
-### Dependency direction
-
-Write dependencies in terms of contracts, not chronology:
-
-```text
-credential provisioning contract
-  -> host-controller authentication
-    -> privileged host operations
-```
-
-If only part of a feature is blocked, say so. For example, a manifest parser may
-proceed while that feature's durable audit-storage chunk waits for the canonical
-audit schema.
-
-### Superseding documents
-
-Do not silently edit history to make an old design appear to have always said
-the new thing. Preserve the rationale, but make current status unmistakable:
-
-```markdown
-Status: Superseded
-Superseded by: <document>
-Reason: <one paragraph>
-```
-
-If part of a PRD remains valid, mark it Retargeted and identify which scope moved
-elsewhere.
-
-Add a short supersession note near the top explaining what changed, why the old
-design is no longer current, and where the current design lives. For a research
-note whose original analysis remains useful, preserve that analysis and append
-a dated addendum with the newer finding instead of rewriting the note as though
-it had always reached the new conclusion.
-
-### Architecture sweeps
-
-After a foundational change, do a targeted architecture sweep before building
-more features on it:
-
-1. Identify the concepts the change affects, such as `bot-bottle.db`, host
-   controller, orchestrator, audit ownership, or signing key.
-2. Search active PRDs, decisions, and open issues for those concepts.
-3. Update or supersede contradictory statements.
-4. Refresh dependency links and the current architecture summary.
-5. Confirm stacked implementation branches still have the correct base.
-
-This is a milestone activity, not a recurring documentation ceremony.
-
-## Pull-request checklist
-
-Use the relevant items in design and implementation pull requests:
-
-- [ ] The canonical PRD or decision is linked.
-- [ ] Design-changing review decisions are reflected in-repo.
-- [ ] Dependencies and blockers are explicit.
-- [ ] State, credential, and trust ownership agree with current architecture.
-- [ ] Superseded or retargeted documents are marked.
-- [ ] Security guarantees and non-guarantees are precise.
-- [ ] Open questions do not change the promised guarantee or ownership model.
-- [ ] Implementation deviations updated the canonical design.
-
-## Lightweight maintenance
-
-Automation should enforce document shape, not pretend to understand
-architecture. Useful checks include:
-
-- active PRDs contain status and dependency metadata;
-- superseded PRDs link to their replacement;
-- referenced documents and issues exist;
-- implementation pull requests identify their PRD and chunk;
-- document filenames and lifecycle states follow repository conventions.
-
-Human review remains responsible for detecting conflicting guarantees or
-ownership claims.
-
-The durable rule is simple: **discussion discovers the decision; the repository
-records it; implementation follows it.**

docs/prds/0001-per-agent-egress-proxy-via-pipelock.md

@@ -1,14 +1,9 @@
 # PRD 0001: Per-agent egress proxy via pipelock
 
-- **Status:** Superseded by [PRD 0017](0017-egress-proxy-via-mitmproxy.md)
-  and [PRD 0052](0052-egress-dlp-addon.md)
+- **Status:** Active
 - **Author:** didericis
 - **Created:** 2026-05-08
 
-> **Superseded.** Pipelock was removed in issue #193. PRD 0017 moved
-> egress enforcement and credential injection to mitmproxy; PRD 0052 moved DLP
-> enforcement into the egress addon. The design below is retained as history.
-
 ## Summary
 
 Run pipelock as a sidecar container on each bot-bottle agent's only

docs/prds/0006-pipelock-tls-interception.md

@@ -1,14 +1,9 @@
 # PRD 0006: pipelock native TLS interception
 
-- **Status:** Superseded by [PRD 0017](0017-egress-proxy-via-mitmproxy.md)
-  and [PRD 0052](0052-egress-dlp-addon.md)
+- **Status:** Active
 - **Author:** didericis
 - **Created:** 2026-05-12
 
-> **Superseded.** Pipelock was removed in issue #193. TLS interception now
-> belongs to the mitmproxy egress design in PRD 0017, with DLP implemented by
-> the egress addon in PRD 0052. The design below is retained as history.
-
 ## Summary
 
 Turn on pipelock's built-in `tls_interception` so its DLP / URL /

docs/prds/0015-pipelock-block-remediation.md

@@ -1,17 +1,11 @@
 # PRD 0015: pipelock block remediation
 
-- **Status:** Superseded by [PRD 0017](0017-egress-proxy-via-mitmproxy.md)
-  and [PRD 0052](0052-egress-dlp-addon.md)
+- **Status:** Active
 - **Author:** didericis
 - **Created:** 2026-05-25
 - **Parent:** PRD 0012
 - **Depends on:** PRD 0013
 
-> **Superseded.** Pipelock and its restart-based allowlist remediation path
-> were removed in issue #193. Current egress enforcement is the mitmproxy
-> design from PRD 0017 with DLP in PRD 0052. The design below is retained as
-> history.
-
 ## Summary
 
 Wires the **pipelock block** path (PRD 0012 *Stuck categories*) end-to-end. The supervisor, on approval of a `pipelock-block` proposal, writes the new pipelock allowlist to the host and restarts pipelock; the agent's in-flight outbound calls may drop and rely on retry. The TUI gains a proactive `pipelock edit <bottle>` verb for operator-initiated edits unrelated to a tool call. The pipelock audit log (format defined in PRD 0013) is filled in with real entries on every edit.

docs/prds/0019-active-agents-in-dashboard.md

@@ -4,11 +4,6 @@
 - **Author:** didericis
 - **Created:** 2026-05-26
 
-> **Superseded.** PRD 0049 removed the active-agents pane and agent-scoped
-> operator edit verbs when the dashboard was narrowed back to a proposal-only
-> supervise TUI. A future agent-management surface was deferred rather than
-> carried forward from this design. The design below is retained as history.
-
 ## Summary
 
 The dashboard today is proposal-centric: it lists every pending

docs/prds/0020-start-and-attach-from-dashboard.md

@@ -4,11 +4,6 @@
 - **Author:** didericis
 - **Created:** 2026-05-26
 
-> **Superseded.** PRD 0049 removed start, re-attach, and stop actions from the
-> dashboard when it became the proposal-only supervise TUI. Bottle lifecycle
-> remains in the dedicated CLI commands; no dashboard replacement from this
-> design remains active. The design below is retained as history.
-
 ## Summary
 
 Today the dashboard is read-only: it surfaces pending proposals

docs/prds/0021-dashboard-tmux-split-pane.md

@@ -4,11 +4,6 @@
 - **Author:** didericis
 - **Created:** 2026-05-26
 
-> **Superseded.** PRD 0049 removed agent handoff and tmux pane management when
-> the dashboard was reduced to the proposal-only supervise TUI. The split-pane
-> interaction described below has no active replacement and is retained only
-> as design history.
-
 ## Summary
 
 When the dashboard runs inside tmux, lay it out as the **left

docs/prds/0024-consolidate-sidecar-bundle.md

@@ -1,13 +1,9 @@
 # PRD 0024: Consolidate per-bottle sidecars into a single bundle
 
-- **Status:** Superseded by [PRD 0070](0070-per-host-orchestrator.md)
+- **Status:** Active
 - **Author:** didericis
 - **Created:** 2026-05-26
 
-> **Superseded.** PRD 0070 replaced the per-bottle sidecar bundle with a
-> persistent per-host gateway and separate orchestrator control plane. The
-> design below is retained as history.
-
 ## Summary
 
 Replace the four per-bottle sidecar containers in the Docker

docs/prds/0037-pipelock-yaml-render-contract.md

@@ -1,16 +1,10 @@
 # PRD 0037: Pipelock YAML Render Contract
 
-- **Status:** Superseded by [PRD 0017](0017-egress-proxy-via-mitmproxy.md)
-  and [PRD 0052](0052-egress-dlp-addon.md)
+- **Status:** Active
 - **Author:** didericis-codex
 - **Created:** 2026-06-02
 - **Issue:** #130
 
-> **Superseded.** Pipelock and its YAML renderer were removed in issue #193.
-> Current egress configuration is consumed by the mitmproxy design from PRD
-> 0017 and its DLP addon from PRD 0052. The contract below is retained as
-> history.
-
 ## Summary
 
 Lock down the contract between `pipelock_build_config` and

docs/prds/0067-sqlite-local-storage.md

@@ -1,17 +1,10 @@
 # PRD 0067: SQLite local storage
 
-- **Status:** Retargeted by [PRD 0070](0070-per-host-orchestrator.md) and
-  issues #469/#471
+- **Status:** Active
 - **Author:** codex
 - **Created:** 2026-07-01
 - **Issue:** #319
 
-> **Retargeted.** The SQLite storage and migration foundation remains in use,
-> but the writable data-plane database mount described below is no longer the
-> active ownership model. Issues #469/#471 removed `bot-bottle.db` from the
-> data plane; under PRD 0070 only the orchestrator control plane opens the
-> operational database, and gateway components reach state through RPC.
-
 ## Summary
 
 Add a small stdlib SQLite storage layer for bot-bottle host runtime state,

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

@@ -1,6 +1,6 @@
 # PRD 0069: Firecracker-native, Docker-free backend
 
-- **Status:** Retargeted by [PRD 0070](0070-per-host-orchestrator.md)
+- **Status:** Draft (partially superseded)
 - **Author:** Claude
 - **Created:** 2026-07-12
 - **Issue:** #348

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

@@ -1,6 +1,6 @@
 # PRD 0070: Per-host orchestrator service
 
-- **Status:** Active
+- **Status:** Draft
 - **Author:** Claude
 - **Created:** 2026-07-12
 - **Issue:** #351

docs/prds/0077-macos-container-ci-runner.md

@@ -1,142 +0,0 @@
-# PRD 0077: macOS (Apple Container) CI runner
-
-- **Status:** Active
-- **Author:** Claude
-- **Created:** 2026-07-25
-- **Issue:** #426
-
-## Summary
-
-CI has no runner for the `macos-container` (Apple Container) backend.
-`.gitea/workflows/test.yml` exercises Docker (`ubuntu-latest`) and
-Firecracker (self-hosted `kvm`) but never the macOS backend. This PRD adds a
-self-hosted macOS runner (label `macos`) and an advisory `integration-macos`
-job that runs the integration suite against `BOT_BOTTLE_BACKEND=macos-container`,
-so the backend that is the default on macOS stops shipping unexercised.
-
-## Problem
-
-The gap is not theoretical. `5ad3449` moved `bot_bottle` from flat files under
-`/app` into a pip-installed package but left init scripts spawning the
-supervisor as `python3 /app/gateway_init.py`, which no longer exists. Both the
-Firecracker and macOS backends carried the identical bug:
-
-- **firecracker** — caught and fixed in `127ba49` because the KVM runner
-  (added in `c193b04`, PR #349) runs that backend's integration suite.
-- **macos-container** — survived on `main` and only surfaced when a human ran
-  `bot-bottle start` by hand.
-
-The failure mode is expensive to debug: the supervisor never starts, so
-mitmdump never generates its CA, and launch dies downstream with
-`GatewayError: gateway CA not available`, which points at TLS rather than at
-the supervisor. Unit tests did not help — `test_macos_infra` asserted the
-substring `"gateway_init.py"`, which the *broken* path satisfies. (That
-specific assertion has since been tightened to the module form
-`bot_bottle.gateway_init`, matching its Firecracker twin, so the exact
-regression is now covered on `ubuntu-latest`. What remains missing is the
-end-to-end runner that would catch the *next* macOS-only launch regression.)
-
-PR #470 (#414) already made the integration suite backend-agnostic:
-`skip_unless_selected_backend_available()` gates on the *selected* backend's
-own `is_backend_ready()` rather than `docker_available()`, and each
-integration job runs `./cli.py backend status --backend=<name>` as a preflight
-that fails loudly when the backend is missing. That is the machinery this job
-plugs into; this PRD supplies the runner and the job.
-
-## Goals / Success criteria
-
-- A macOS runner is registered and picks up jobs by the `macos` label.
-- An `integration-macos` job runs the integration suite against
-  `BOT_BOTTLE_BACKEND=macos-container`.
-- The job **fails, not skips**, when the backend is unavailable on the runner
-  (via the `backend status` preflight).
-- Reverting the `macos_container/infra.py` supervisor fix makes the job fail:
-  the broken supervisor path throws `GatewayError` at bottle launch, which is
-  `TestSandboxEscape.setUpClass`, failing the whole class before any individual
-  attack runs.
-
-## Non-goals
-
-- Making `integration-macos` a **required** PR check. It runs on
-  `workflow_dispatch` (manual dispatch) only — never on push or PRs. A single
-  non-redundant laptop that sleeps and roams must never be able to block a PR
-  merge or churn unattended on every push to main, and it is deliberately kept
-  out of the `coverage` job's `needs` so the diff-coverage gate never depends on
-  it.
-- Multi-machine or hosted macOS runners. Apple Container needs the host
-  virtualization framework, so the runner must be a physical/VM macOS host on
-  Apple Silicon — it cannot reuse the KVM runner or run in a Linux container.
-- Coverage aggregation from the macOS job into the combined gate (would couple
-  the gate to the laptop).
-
-## Design
-
-### Runner (operational, provisioned once)
-
-- Apple Silicon macOS host with Apple's `container` CLI installed and
-  `container system status` reporting `running`.
-- Install the runner: `brew install gitea-runner` (the `act_runner` rename),
-  registered in **host mode** with label `macos` — not docker mode, because
-  Apple Container needs the host `container` CLI and virtualization framework,
-  not a nested container.
-- A Python ≥ 3.11 with `coverage` importable on the runner's `PATH`. Because a
-  launchd service does not inherit an interactive shell's `PATH`, pin `node`
-  (for the JS `actions/*`) and the Python env explicitly in the service
-  environment rather than relying on `nvm`/shell profile.
-- Concurrency 1. The infra container is a singleton (`bot-bottle-mac-infra`),
-  so two simultaneous runs on one host collide (#425). The job also declares a
-  `concurrency` group as belt-and-suspenders and tears the singleton down after
-  each run.
-
-### `integration-macos` job
-
-Modeled on `integration-firecracker`:
-
-- `runs-on: [self-hosted, macos]`.
-- `if:` `workflow_dispatch` only (advisory, manual dispatch; never push or PRs,
-  so no fork-PR exposure, no merge-blocking, and no unattended runs on push).
-- `concurrency: { group: integration-macos-infra, cancel-in-progress: false }`
-  to serialize runs against the singleton.
-- **Preflight** — `command -v container`, `container system status`, then
-  `./cli.py backend status --backend=macos-container`; any failure exits
-  non-zero so a misprovisioned runner fails loudly instead of silently
-  skipping.
-- Run the integration suite under coverage with
-  `BOT_BOTTLE_BACKEND=macos-container` and print a `coverage report -m` for
-  visibility (no upload, not in the gate).
-- **Teardown** (`if: always()`) — `MacosInfraService().stop()` removes the
-  singleton so a crashed run cannot wedge the next one.
-
-### The `test_sandbox_escape` CI guard (the trap #470 left)
-
-`TestSandboxEscape` is the only backend-agnostic integration test that boots a
-real bottle, so it is the one that would catch a macOS launch regression. It
-still carries a second guard that skips under `GITEA_ACTIONS` for every backend
-except `firecracker`:
-
-```python
-@unittest.skipIf(
-    os.environ.get("GITEA_ACTIONS") == "true"
-    and os.environ.get("BOT_BOTTLE_BACKEND") != "firecracker",
-    ...,
-)
-```
-
-The skip exists because the *containerized* `act_runner` (docker on
-`ubuntu-latest`) can't see a host bind mount and hides sibling-gateway network
-topology. Those constraints do not apply to a **host-mode** runner — neither
-the KVM host runner nor a macOS host runner is containerized. This PRD relaxes
-the guard to allow both host-mode backends (`firecracker`, `macos-container`)
-through while still skipping on the containerized Docker job. Without this
-change the macOS job would run green while skipping the exact test that proves
-the backend launches — the very false-green this issue is about.
-
-## Open questions
-
-- None known that block the job. git-gate is fully implemented on the macOS
-  backend (the gateway's consolidated `git-http` daemon plus dynamic key
-  provisioning/revocation), so `TestSandboxEscape` attack 5 — secret exfil
-  pushed through git-gate, rejected by the gitleaks hook before the upstream
-  push — runs the same as on the other backends. Any genuinely
-  macOS-specific test adjustment would surface at first runner bring-up, but
-  none is anticipated from the current backend implementation.

docs/prds/0078-install-script.md

@@ -1,172 +0,0 @@
-# PRD 0078: Quick install script
-
-- **Status:** Active
-- **Author:** claude
-- **Created:** 2026-07-25
-- **Issue:** #197
-
-## Summary
-
-Add a proper Python package distribution (`pyproject.toml` with a
-`bot-bottle` entry point) plus a thin `install.sh` bootstrapper, so users
-can install bot-bottle with a single command instead of cloning the repo
-and invoking `cli.py` directly. A new `bot-bottle doctor` subcommand
-verifies host prerequisites after install.
-
-## Problem
-
-There is currently no install path for new users. The only way to run
-bot-bottle is to clone the repo and invoke `./cli.py`. This blocks any
-public demo: readers want `curl | sh` or `pipx install`, not a manual
-clone-and-configure flow. There is also no single command that tells a
-user whether their host is actually ready to run a bottle.
-
-## Goals / Success Criteria
-
-- `curl -fsSL <raw-url>/install.sh | sh` leaves a working `bot-bottle`
-  command on PATH.
-- Python-native users can install with `pipx install bot-bottle` or
-  `uv tool install bot-bottle` (once published) — or from a local
-  checkout today.
-- `install.sh` validates prerequisites (Python ≥ 3.11), creates the
-  `~/.bot-bottle/` config tree, installs the package, and runs
-  `bot-bottle doctor`. It never installs Docker or a VM backend silently
-  and never uses `sudo`.
-- `install.sh` is idempotent — safe to re-run.
-- `bot-bottle doctor` reports Python version, backend *readiness*, and
-  config-dir presence, exiting non-zero when a hard prerequisite is unmet.
-- The package keeps **zero runtime pip dependencies** (stdlib-only,
-  matching the existing constraint in `AGENTS.md`).
-
-## Non-goals
-
-- Bundling a Python runtime or producing a standalone binary.
-- Automatic Docker / VM-backend installation.
-- Plugin-architecture changes (issue #197 floats a containerized-plugin
-  direction; that's a separate feature).
-- Publishing to a package index in this PR — the package *structure* is
-  the deliverable; publishing is a follow-up step.
-
-## Design
-
-### Package structure (`pyproject.toml`)
-
-Fill out the previously-stub `pyproject.toml` with project metadata, a
-console-script entry point, and package-data for the non-Python assets the
-runtime reads from inside the package:
-
-```toml
-[project]
-name = "bot-bottle"
-version = "0.1.0"
-requires-python = ">=3.11"
-dependencies = []
-
-[project.scripts]
-bot-bottle = "bot_bottle.cli:main"
-```
-
-`bot_bottle.cli:main` already exists (the `cli.py` shim calls it), so no
-refactor of the entry point is needed. `package-data` ships the non-Python
-assets that live *inside* the package (`egress_entrypoint.sh`, the contrib
-Dockerfiles, the firecracker netpool defaults, the macos-container init
-script).
-
-### Self-contained wheel (build resources)
-
-The gateway / infra / orchestrator images are built from a Docker (or Apple
-`container`) build context that must contain the `bot_bottle` package,
-`pyproject.toml`, and the **root-level** Dockerfiles as siblings. Several
-modules used to locate that context by walking `__file__`'s parents to the
-repo root (`_REPO_ROOT = Path(__file__)…parents[N]`) and reading
-`Dockerfile.gateway`, `nix/firecracker-netpool.nix`, and
-`scripts/firecracker-netpool.sh` from it. In an installed wheel the package
-lives in `site-packages` with no repo root above it, so those reads fail —
-`doctor` passes but `start` / backend setup breaks.
-
-Fix: a single resolver, `bot_bottle/resources.py`.
-
-- `build_root()` returns a directory shaped like a repo root (has
-  `bot_bottle/`, `pyproject.toml`, the Dockerfiles, `nix/`, `scripts/`).
-  In a **checkout** it's the repo root itself — unchanged behavior. From an
-  **installed wheel** it stages a copy under the app-data dir, keyed by a
-  **content digest** of the installed package + bundled resources (not the
-  distribution version): the installer defaults to a git branch and
-  `pipx install --force` while `version` stays `0.1.0`, so a version key
-  would reuse a previous commit's tree — the digest key re-stages instead.
-  Staging is concurrency-safe: a file lock serializes it, each writer builds
-  into a private temp dir, and the finished tree is published with an atomic
-  rename (never populating a shared path another process might read).
-- The root-level resources are shipped inside the wheel under
-  `bot_bottle/_resources/` by a `setup.py` `build_py` step (kept in sync
-  with `resources.BUNDLED_RESOURCES`); `MANIFEST.in` includes them in the
-  sdist.
-- Every former `_REPO_ROOT` / `_REPO_DIR` call site now derives from
-  `resources`: the docker/macos agent-image launch, each backend's
-  `orchestrator` / `gateway` / `infra` service, firecracker `infra_vm` /
-  `infra_artifact` / `setup`, and the shared `gateway` build context. So
-  checkout and wheel installs share one downstream path.
-
-Verification: `test_resources` exercises both layouts — including the staged
-wheel context, a re-stage when package content changes at the same version,
-and a rebuild of a partial (crashed) stage. `test_wheel_install` builds the
-wheel, installs it into an isolated venv, and asserts `bot-bottle doctor`
-runs and `build_root()` produces a valid context; `build` is in
-`requirements-dev.txt` so it runs in CI, and a build/install failure fails
-the test (it does not skip). Running `start` end-to-end still needs a
-Docker/KVM host (CI), not a source checkout.
-
-### `install.sh`
-
-A POSIX `sh` bootstrapper that:
-
-1. Checks `python3` is present and ≥ 3.11; exits with a clear message
-   otherwise.
-2. Checks `git` when installing a `git+` spec, and — when falling back to
-   pip — that pip is usable and the interpreter isn't externally managed
-   (PEP 668), pointing at pipx otherwise.
-3. Creates `~/.bot-bottle/{agents,bottles,contrib}`.
-4. Installs via `pipx` if available, else `python3 -m pip install --user`.
-   The spec defaults to the git URL and is overridable via
-   `BOT_BOTTLE_INSTALL_SPEC` (used by tests / local installs).
-5. Locates the `bot-bottle` entry point: PATH first, else the
-   interpreter's own user-scheme scripts dir resolved via `sysconfig`
-   (`~/.local/bin` on Linux, `~/Library/Python/<X.Y>/bin` on a python.org
-   macOS interpreter — not hardcoded).
-6. Runs `bot-bottle doctor` and reports the result.
-
-It is idempotent and never calls `sudo`.
-
-### `bot-bottle doctor`
-
-A new store-free subcommand (no DB migration required) that checks and
-reports:
-
-- **python** — interpreter version (hard requirement: ≥ 3.11).
-- **backend** — at least one backend *ready* on this host
-  (macos-container / firecracker / docker), via `is_backend_ready()` — a
-  full backend `status()` probe (daemon reachable, network pool present,
-  KVM usable), not a PATH-only check: a stopped daemon or half-configured
-  backend must not report `ok` when `start` can't work. Each not-ready
-  backend prints its own diagnostics. Hard requirement.
-- **config** — whether `~/.bot-bottle/` exists (advisory only; `start`
-  provisions on first run).
-
-Exits 0 when both hard requirements pass, non-zero otherwise.
-
-## Testing strategy
-
-- Unit test `bot-bottle doctor` success/failure paths with backend
-  readiness (`is_backend_ready`) and Python version mocked, including the
-  available-but-not-ready → fail case.
-- Unit test that `pyproject.toml` parses, declares the entry point and an
-  empty `dependencies` list, and that every `package-data` glob resolves
-  to a file that exists on disk (guards against drift).
-- Unit test that `install.sh` is executable, POSIX-ish (`set -eu`), never
-  calls `sudo`, and runs `doctor` after install.
-
-## Open questions
-
-- Should `version` be derived from a git tag at build time (e.g.
-  `hatch-vcs`) or kept static? Static (`0.1.0`) is simpler for now.
-- Publishing target (PyPI vs. a self-hosted index) is deferred.

docs/prds/README.md

@@ -7,13 +7,10 @@ document vs. a research note or a decision record).
 
 ## Naming and numbering
 
-New PRDs may use a `prd-new-<kebab-title>.md` placeholder name while the
-design is being drafted. Before merge, assign the next sequential number
-after the highest-numbered PRD on `main`, rename the file to
-`NNNN-<kebab-title>.md`, and update the title header. CI blocks merging
-while any `prd-new-*.md` placeholder remains. If concurrent PRs select the
-same number, the later PR must take the next available number before it
-merges. Numbers are never reused; gaps are fine.
+New PRDs use a `prd-new-<kebab-title>.md` placeholder name while the PR
+is open. On merge to `main` a CI workflow assigns the next sequential
+number (`0024-…`, `0025-…`), renames the file, and updates the title
+header. Numbers are never reused; gaps are fine.
 
 Once numbered, the filename stays fixed for the life of the doc.
 
@@ -29,7 +26,7 @@ The `Status:` line near the top tracks the PRD's lifecycle:
 ## Format
 
 ```markdown
-# PRD prd-new: <short title>    ← replace with the final number before merge
+# PRD prd-new: <short title>    ← placeholder; CI fills in the number on merge
 
 - **Status:** Draft
 - **Author:** <who>

docs/prds/prd-new-ci-artifact-coverage.md

@@ -1,4 +1,4 @@
-# PRD 0074: CI artifact-based coverage and local Firecracker candidate flow
+# PRD prd-new: CI artifact-based coverage and local Firecracker candidate flow
 
 - **Status:** Active
 - **Author:** Claude

docs/prds/prd-new-claude-forward-host-credentials.md

@@ -1,6 +1,6 @@
-# PRD 0071: Claude forward_host_credentials
+# PRD prd-new: Claude forward_host_credentials
 
-- **Status:** Active
+- **Status:** Draft
 - **Author:** claude
 - **Created:** 2026-07-01
 - **Issue:** #325

docs/prds/prd-new-consolidate-docker-infra-backend.md

@@ -1,4 +1,4 @@
-# PRD 0073: Consolidate infra backend for Docker
+# PRD prd-new: Consolidate infra backend for Docker
 
 - **Status:** Active
 - **Author:** Claude

docs/prds/prd-new-control-plane-auth-provisioning.md

@@ -1,6 +1,6 @@
-# PRD 0079: Per-service signing keys for control-plane auth
+# PRD prd-new: Per-service signing keys for control-plane auth
 
-- **Status:** Active
+- **Status:** Draft
 - **Author:** claude
 - **Created:** 2026-07-26
 - **Issue:** #476

docs/prds/prd-new-host-control-server.md

@@ -1,273 +0,0 @@
-# PRD prd-new: Host control server
-
-- **Status:** Draft
-- **Author:** Claude
-- **Created:** 2026-07-26
-- **Issue:** #468
-
-## Summary
-
-Promote the in-process launch broker into a standalone **host control
-server**: the single privileged component on the host. Both the CLI and the
-orchestrator drive it over HTTP; it brokers agent launches, owns the
-orchestrator's own lifecycle, and is the sole writer of host-durable state (the
-tamper-evident audit record). This closes the three gaps between today's
-well-formed broker *contract* ([`orchestrator/broker.py`](../../bot_bottle/orchestrator/broker.py))
-and a real out-of-process service — transport, durable provisioned secret,
-and a disciplined op vocabulary — and splits host state by
-owner and lifetime. The prize: **the CLI no longer needs the Docker socket**,
-which is what finally lets a dedicated Gitea runner user drop the
-root-equivalent `docker` group (PRD 0070, "Relationship to other work").
-
-## Problem
-
-Container launches run directly from a short-lived CLI process against the
-Docker socket. That socket is root-equivalent, so every host that launches
-bottles hands root to whoever invokes the CLI — including a CI runner user we
-want to keep unprivileged. PRD 0070 already argues for replacing the fat socket
-with a **thin, structured, auditable** launch broker, and the contract for that
-broker exists and is tested in-process. But it is *only* in-process:
-`LaunchBroker.submit(token)` is a method call from
-`OrchestratorCore.launch_bottle` ([`service.py:116`](../../bot_bottle/orchestrator/service.py)),
-and `DockerBroker` is on no production path — every backend starts the
-orchestrator with `--broker stub` ([`__main__.py:54`](../../bot_bottle/orchestrator/__main__.py)).
-
-Three gaps stand between that scaffold and a host service:
-
-1. **No transport.** `submit` is an in-process call. A real service needs a
-   `BrokerClient` that POSTs the signed token and a host-side HTTP server that
-   verifies and acts.
-2. **The signing secret is ephemeral and self-generated.**
-   [`__main__.py:53`](../../bot_bottle/orchestrator/__main__.py) does
-   `secrets.token_bytes(32)` and hands the *same value* to signer and verifier —
-   viable only because they share a process. A separate daemon needs the secret
-   provisioned out of band and durable across orchestrator restarts.
-3. **The op vocabulary is `launch` / `teardown` only.** Everything else
-   host-privileged still lives in the CLI, so the schema has to grow — carefully,
-   since PRD 0070's security argument rests on "structured requests only, static
-   flags + ids."
-
-Separately, host state has no clear owner. `OrchestratorCore.reconcile` takes
-`live_source_ips` as a parameter *only because the orchestrator cannot see the
-backend* ([`service.py:137`](../../bot_bottle/orchestrator/service.py)); the
-egress traffic log is written to the container's stderr; and there is no durable,
-tamper-evident home for the audit record that survives orchestrator destruction.
-
-## Goals / Success Criteria
-
-- A standalone host control server that the CLI and orchestrator reach over
-  **HTTP**, with three entry paths working end to end:
-  - `web console -(iroh)-> orchestrator -(http)-> host controller -> launch`
-  - `cli -(http)-> orchestrator -(http)-> host controller -> launch`
-  - `cli -(http)-> host controller` — start / restart / status of the
-    orchestrator **itself** (the bootstrap/recovery path #391 targets).
-- The launch op is expressed as a **signed JWT of static flags + ids only**,
-  verified against a closed schema.
-- The signing secret is **provisioned out of band and durable** across
-  orchestrator restarts (a `TrustDomain` per #476, with a key the orchestrator
-  never holds for the host controller's *own* endpoints).
-- Host-privileged operations move off the CLI to the control server; **the CLI
-  no longer opens the Docker socket** for bottle operations.
-- `Orchestrator.reconcile` no longer takes `live_source_ips` — live-bottle
-  enumeration becomes an internal control-server call.
-- Host-durable state lands as an **append-only, hash-chained JSONL** audit log
-  owned solely by the host controller; operational state stays SQLite owned
-  solely by the orchestrator.
-
-## Non-goals
-
-- **Removing standing privilege.** This converts on-demand privilege (a CLI the
-  user invokes) into standing privilege (a daemon under launchd/systemd). The
-  win is that the privilege is *narrower* (structured requests vs. a raw socket),
-  not that it disappears. "Always running" is an accepted new property.
-- **Asymmetric signing.** We stay HS256 — see Design / "Signing stays
-  symmetric."
-- **Integrity against a live compromised orchestrator.** Host-location of the
-  audit log does not buy this: the orchestrator makes the decisions being audited
-  and can forge or omit entries wherever the file lives. An off-box copy is the
-  answer, tracked separately.
-- **A single unified DB for all state.** Impossible over a guest-kernel share
-  (SQLite locking is not coherent); state is split by owner and lifetime instead.
-- **The generic `SecretProvider` (#355)** and **remote terminal design (#478)** —
-  both ride the same door but are their own work.
-
-## Design
-
-### Topology
-
-The host controller is the sole privileged component. The orchestrator becomes a
-client of it for launches, and the CLI becomes a client of it for *both* bottle
-operations (indirectly, through the orchestrator) and orchestrator lifecycle
-(directly, for bootstrap/recovery — startup can't route through the thing being
-started).
-
-```
-web console ─(iroh)─▶ orchestrator ─┐
-                                    ├─(http, signed JWT)─▶ host controller ─▶ launch
-cli ────────(http)──▶ orchestrator ─┘
-cli ────────(http, bearer)──────────────────────────────▶ host controller   (orchestrator lifecycle)
-```
-
-### Transport: `BrokerClient` + host server
-
-`LaunchBroker.submit(token)` keeps its exact signature and semantics; only the
-*wire* changes. A new `BrokerClient` implements the same submit contract by
-POSTing the signed token to the host controller (stdlib `urllib`, like the
-existing [`orchestrator/client.py`](../../bot_bottle/orchestrator/client.py)),
-and the host controller's launch handler is the existing `verify_request` +
-`_launch`/`_teardown` path, now reached over HTTP instead of a method call. The
-in-process `StubBroker` stays for the dev-harness and tests; `DockerBroker`'s
-`_launch`/`_teardown` bodies move behind the server unchanged. Because the client
-satisfies the same interface `OrchestratorCore` already depends on, the core does
-not change to gain a real backend.
-
-### Signing stays symmetric (HS256)
-
-PRD 0070 nominally specifies asymmetric; the code is HS256 and we keep it.
-Asymmetric matters when the verifier is *less* privileged than the signer — here
-it is the reverse: the host controller (verifier) is strictly more privileged
-than the orchestrator (signer), and a controller that could forge orchestrator
-requests gains nothing, since it is already the component that launches. Staying
-symmetric also honors the no-runtime-deps policy (stdlib has no Ed25519). This
-matches the reasoning already inlined in `broker.py`'s module docstring.
-
-### Replay protection is out of scope (tracked in #494)
-
-Once the launch token travels over a wire, a captured token could be replayed —
-`sign_request` already emits `jti`/`iat` but `verify_request` reads neither, so
-there is no expiry window or `jti` cache today. Enforcing that (an `iat` window +
-a self-trimming `jti` cache) is a pure in-process change that lands independently
-of this work, and it is deferred to **#494** rather than gating the MVP of the
-host control server. Nothing here depends on it; it can merge before or after.
-
-### Op vocabulary and the "ids + static flags" rule (gap 3)
-
-Each op moved off the CLI widens the privileged surface, so growth is governed by
-one explicit rule, enforced in `verify_request`'s schema check:
-
-> A broker op carries **only ids and enumerated static flags** — a bottle id, a
-> pool slot, a **content-addressed** image ref chosen from a fixed set, an op
-> name from a closed vocabulary. Never a free-form path, argv, command, or
-> caller-supplied filesystem location. If an operation cannot be expressed that
-> way, it does not become a broker op.
-
-Operations that fit and move off the CLI (all today in
-`backend/*/consolidated_launch.py`, driven by a short-lived CLI process):
-
-| Op | What it does | Fits the rule because |
-|---|---|---|
-| `launch` / `teardown` | existing | ids + slot + image ref |
-| `orchestrator.ensure_running` | start the infra container | no arguments |
-| `orchestrator.{start,restart,status}` | lifecycle (the #391 path) | no arguments |
-| `list_live` | enumerate running bottles for reconcile | no arguments; returns ids/IPs |
-| `allocate_ip` | `next_free_ip` over `_network_container_ips` | no arguments; returns an IP |
-| `provision_git_gate` | `cp`/`exec` a per-bottle deploy key into the gateway | bottle id + key handle, no path |
-| `reprovision` | `docker exec printenv <ENV_VAR_SECRET>` on a live agent | bottle id + secret *name* |
-
-Image **builds** stay with the orchestrator for v1 (PRD 0070 §Memory: builds run
-control-plane-side; a dedicated slim build unit is later, #468-adjacent), so no
-`build` broker op is added here.
-
-With `list_live` as an internal control-server call, `Orchestrator.reconcile`'s
-`live_source_ips` parameter goes away — the tell PRD 0070 called out that the
-orchestrator couldn't see the backend disappears with it.
-
-### Secret provisioning (gap 2)
-
-The shared HS256 secret becomes a durable, out-of-band artifact via the
-**`TrustDomain`** seam (#476,
-[`trust_domain.py`](../../bot_bottle/trust_domain.py)):
-
-- The **launch-broker secret** is a `TrustDomain` whose key
-  (`host_signing_key(<file>)`, minted 0600 on first use, durable under
-  `bot_bottle_root()`) is provisioned to the orchestrator (signer) and the host
-  controller (verifier). Durability across orchestrator restarts is what makes
-  re-adoption work — a restart re-verifies against the same key.
-- The **host controller's own lifecycle endpoints** (the direct `cli -> host
-  controller` path) get a **separate** `TrustDomain` key the orchestrator never
-  holds — exactly the second domain #476's PRD reserves. The orchestrator must
-  not be able to mint the credentials used to start and stop it.
-
-This reuses the seam #476 landed rather than re-deriving provisioning per
-backend (the PR #471 bug class).
-
-### One daemon, structurally separate handlers (open decision 1)
-
-The audit writer and the broker live in **one daemon** for install simplicity,
-but with **no shared parsing** and **different credentials per handler**:
-
-- the **launch** handler requires the signed launch **JWT** (provenance +
-  un-coercible schema);
-- the **audit-append** handler takes a plain **bearer token** and writes to the
-  JSONL log.
-
-This does not defend against orchestrator compromise (it holds both creds) — it
-stops a bug in the boring audit path from reaching the privileged launch path.
-The launcher stays small enough to audit line-by-line, per PRD 0070.
-
-### State ownership: split by owner and lifetime
-
-A single mounted DB is impossible — SQLite locking is not coherent across guest
-kernels over a share, which is why the macOS backend already uses a container-only
-volume (`INFRA_DB_VOLUME`). So state splits three ways (depends on #469, which
-gets `bot-bottle.db` off the data plane first):
-
-| Owner | State | Home | Shape |
-|---|---|---|---|
-| **Orchestrator** | `orchestrator_bottles` registry; `bottled_agent_secrets` (encrypted egress tokens); `supervise_proposals` / `supervise_responses` | volume nothing else mounts (generalizing the macOS design) | **SQLite** — mutable, transactional, queried |
-| **Host controller** | supervise audit entries; egress traffic log (today → container stderr); host-side config | host filesystem, survives orchestrator/volume destruction | **JSONL** — append-only |
-| **Gateway** | none | — | after #469 the data plane holds no DB state |
-
-The historical record is **JSONL, not SQLite**, because it is append-only, never
-updated, never transactionally queried: `O_APPEND` writes are atomic, there is no
-locking protocol to get wrong, hash-chaining for tamper-evidence is cheap, and it
-survives container-runtime volume pruning (the #450 lesson) and stays readable
-without the orchestrator running. Both halves of "the audit record" — supervise
-decisions and the egress traffic log — land in the one place.
-
-The orchestrator is **sole mounter and sole writer** of its SQLite volume; the
-host controller is **sole writer** of the JSONL log, over the authenticated
-audit-append channel.
-
-## Implementation chunks
-
-Ordered, each independently mergeable:
-
-1. **`BrokerClient` + host launch server** over HTTP, reusing `verify_request`
-   and the existing `DockerBroker` bodies. Wire `OrchestratorCore` to a
-   `BrokerClient` behind a flag; keep `StubBroker` for the dev-harness. Closes
-   gap 1.
-2. **Durable secret via `TrustDomain`** — provision the launch-broker key to
-   signer + verifier; add the host controller's own lifecycle `TrustDomain`.
-   Closes gap 2.
-3. **Grow the op vocabulary** one op at a time (`list_live` first — it also
-   removes `reconcile`'s `live_source_ips`), each behind the ids + static-flags
-   rule. Closes gap 3.
-4. **JSONL audit log** — the host-controller-owned, hash-chained historical
-   record with the plain-bearer audit-append handler; redirect the egress traffic
-   log into it.
-5. **Drop the Docker socket from the CLI** once every host-privileged op it used
-   is a broker op — the payoff that unblocks the unprivileged Gitea runner user.
-
-## Open questions
-
-1. **Schema-width rule enforcement.** The "ids + static flags" rule is stated;
-   should `verify_request` reject unknown claim keys outright (strict schema) to
-   keep the surface from drifting? Leaning yes.
-2. **Audit-append back-pressure.** What the audit handler does if the JSONL sink
-   is unavailable (fail-closed vs. buffer) — resolve before shipping chunk 5.
-
-## References
-
-- **PRD 0070** — the contract, the launch broker, and the state tiers this
-  implements.
-- **#469** — get `bot-bottle.db` off the data plane (lands underneath this).
-- **#476** ([`prd-new-control-plane-auth-provisioning`](prd-new-control-plane-auth-provisioning.md))
-  — the `TrustDomain` seam this plugs the host controller's key into.
-- **#391** — backend-agnostic orchestrator restart (the bootstrap path).
-- **#494** — enforce broker replay protection (`iat` window + `jti` cache); split
-  out of this PRD as an independent in-process change.
-- **#386** — prebuilt images from the Gitea OCI registry (the fixed image set the
-  broker validates against).
-- **#355** — generic `SecretProvider`.
-- **#478** — remote terminal design.

docs/prds/prd-new-modernize-built-in-agent-images.md

@@ -1,6 +1,6 @@
-# PRD 0076: Modernize built-in agent images
+# PRD prd-new: Modernize built-in agent images
 
-- **Status:** Active
+- **Status:** Draft
 - **Author:** Codex
 - **Created:** 2026-07-21
 - **Issue:** #451

docs/prds/prd-new-nested-containers.md

@@ -1,6 +1,6 @@
-# PRD 0075: Containers inside a bottle
+# PRD prd-new: Containers inside a bottle
 
-- **Status:** Active
+- **Status:** Draft
 - **Author:** Claude
 - **Created:** 2026-07-21
 - **Issue:** #392

docs/prds/prd-new-nonblocking-supervise.md

@@ -1,6 +1,6 @@
-# PRD 0072: Non-blocking supervise (async approval + proposal polling)
+# PRD prd-new: Non-blocking supervise (async approval + proposal polling)
 
-- **Status:** Active
+- **Status:** Draft
 - **Author:** didericis
 - **Created:** 2026-07-18
 - **Issue:** #412

docs/prds/prd-new-secret-provider-encrypted-env.md

@@ -1,4 +1,4 @@
-# PRD 0080: Encrypted at-rest egress secrets (SecretProvider, interim slice)
+# PRD prd-new: Encrypted at-rest egress secrets (SecretProvider, interim slice)
 
 - **Status:** Draft
 - **Author:** didericis

docs/prds/prd-new-signed-commits-attribution.md

@@ -0,0 +1,651 @@
+# PRD prd-new: Trusted agent forge identity, signed commits & audit attribution
+
+- **Status:** Draft
+- **Author:** didericis-claude
+- **Created:** 2026-07-25
+- **Issue:** #423
+
+## Summary
+
+Give each **host-trusted agent definition** an author identity and named forge
+accounts, and let a bottle associate each git-gate repository with one of those
+accounts. The resolved association provisions authenticated forge API access
+through the egress proxy and injects provider-specific workflow instructions
+into the agent's system prompt without exposing the token. Repository-local
+agent and bottle definitions are no longer discovered because they would
+otherwise be able to select host credential references or impersonate an agent.
+
+For bottles that opt into signing, give each bottled agent a **per-activation
+signing key** so every commit it produces is signed in the git-gate trust
+boundary (outside the bottle) and recorded in bot-bottle's **host-owned audit
+store**, which is the portable source of truth. Each row cryptographically binds
+a commit's bytes (and their control-plane-recomputed SHA) to **access to that
+activation's signing key**, and binds the key to control-plane-owned activation
+metadata — bottle, host, manifest, agent, activation interval, retained public
+key, configured agent author — and separately records the commit's *claimed*
+author/committer. The gate mints a short-lived Ed25519 key at spin-up, holds the
+private half in the sidecar `ssh-agent`, and forwards only `SSH_AUTH_SOCK` into
+the bottle. The gate rejects any commit it forwards that is not signed by the
+activation key; separately, the **control plane** independently recomputes each
+commit's object ID and verifies its signature before recording attribution — it
+never trusts a SHA, key, or verdict asserted by the gate.
+
+This PRD deliberately does **not** enforce or cryptographically vouch
+author/committer identity. The trusted agent definition supplies the configured
+name/email, while the values in each commit remain claims carried inside the
+signed object; making the gate reject a mismatch is a possible future add (see
+**Non-goals** and **Deferred: identity enforcement**). Git push capability stays
+exactly as PRD 0048 deploy keys. Forge API identity uses an operator-provided,
+agent-specific token referenced from the trusted host environment; bot-bottle
+does not mint forge users or tokens.
+
+Successor to:
+
+- **PRD 0027 (agent git identity, #94)** / **ADR 0002** — established that
+  agent name/email is *claimed, not vouched*. This PRD moves that identity from
+  the bottle/git-gate overlay to the trusted agent definition and adds signed
+  **provenance** plus a durable host record, not identity enforcement.
+- **PRD 0011 (per-file manifests)** — allowed repository-local agent files to
+  override home agents. This PRD removes that trust path: agents and bottles are
+  loaded only from the host-owned `~/.bot-bottle` tree.
+- **PRD 0048 (deploy-key provisioning, #169)** — the host-side mint-at-spin-up /
+  revoke-at-teardown lifecycle the signing key follows. Deploy keys are
+  unchanged.
+- **PRD 0070 (per-host orchestrator, #351)** — the orchestrator/control plane is
+  the sole owner of `bot-bottle.db`; audit verification and recording live
+  there, not in the data-plane gate (see **Trust boundary**).
+
+## The guarantee
+
+The crisp property this feature provides:
+
+> The **host-owned audit store** binds a set of commit bytes — whose Git object
+> ID the control plane **recomputes** itself — to **access to this activation's
+> signing key**, and binds that key to **control-plane-owned activation
+> metadata**: bottle, host, manifest, agent, activation interval, retained public
+> key, configured agent author. An agent may author and sign arbitrary commit
+> contents, but it cannot make that signature verify as a *different*
+> activation, and it cannot choose the activation metadata the control plane
+> records. The commit's author/committer identity is **recorded separately as a
+> claim**, not enforced or vouched. The forge is an external transport and
+> collaboration surface, not the source of attribution truth.
+
+What this does and does not prove (issue #423, comments #5554 / #5607 / #5608):
+
+- It proves **access to activation *Y*'s signing key**: whoever assembled these
+  commit bytes could sign with that key. Recomputing the object ID and verifying
+  the embedded signature binds the SHA to activation *Y*, and the control plane's
+  own records bind *Y*'s key to *Y*'s metadata.
+- It does **not** prove the commit was ever pushed, observed upstream, kept
+  (vs. later reverted or dropped), or produced by the *agent* rather than by any
+  other holder of the activation signing capability (the sidecar itself). The
+  store deliberately makes no claim about publication or sole-agent authorship
+  — the owner's requirement is attribution of *what manifest/agent/etc. was in
+  use when a commit was signed*, not proof of where the commit went (#5607).
+- It does **not** make author/committer identity cryptographically vouched. The
+  bottle chooses every byte sent through the forwarded agent, so a signature over
+  `author Mallory <mallory@example>` is just as valid. Those fields are a claim
+  carried inside the signed object and recorded as-is.
+- The binding is trustworthy because the **control plane** supplies the SHA (it
+  recomputes it), the public key, and the activation metadata from its own state
+  — never from a value the gateway asserts (see **Trust boundary**). The
+  residual, by design: anything that holds the activation signing capability can
+  produce commits that attribute to that activation. That is inherent to a
+  binding on *activation-key access*, not a defect.
+
+## Problem
+
+An agent runs on the developer's machine as a *subrole*, scoped down per role.
+Locally that is fine because the machine is single-tenant. The git history an
+agent produces, however, is a durable artifact that outlives the session and
+can be pushed to shared repositories, and today bot-bottle offers no
+tamper-evidence over it:
+
+- **No provenance.** Nothing ties a pushed commit to the bottle/activation that
+  actually produced it. The configured name/email is forgeable and cosmetic
+  (ADR 0002); a commit could be produced anywhere.
+- **No durable, portable record.** There is no host-side ledger that says "SHA
+  *X* was produced by agent *A* in bottle *B* on host *H* during interval
+  *[t0,t1]*, signed by key *K*," independent of any forge and surviving key
+  rotation.
+- **Forge workflow context is missing.** The agent prompt does not know which
+  forge backs a git-gate repository, which API base URL to use, or that
+  authenticated requests must go through the egress proxy. Bespoke prompt text
+  has drifted between agents, causing incorrect PR creation behavior such as
+  using Gitea AGit review refs instead of a branch-backed pull request.
+- **Identity is owned by the wrong layer.** `git-gate.user` puts an agent
+  property on a repository transport component. The same author identity and
+  forge actor should follow the agent across bottles and repositories.
+- **Repository-local agents are a trust escalation.** Today
+  `$CWD/.bot-bottle/agents/*.md` can override a host agent. Once an agent
+  definition may reference a forge token, allowing the checked-out repository
+  to choose that definition would let untrusted workspace content select host
+  identities and credentials.
+
+## Goals / Success Criteria
+
+- **Per-activation signing key.** A fresh Ed25519 keypair is minted host-side at
+  each activation; the private half lives only in the sidecar `ssh-agent`, never
+  in the bottle. Only `SSH_AUTH_SOCK` crosses the boundary.
+- **Agent-owned identity.** Author name/email and named forge accounts live on
+  the agent definition, not under `git-gate`.
+- **Bottle-owned repository policy.** Signing remains an opt-in property of the
+  bottle, and each bottle repository may associate itself with one named forge
+  account from the selected agent.
+- **Forge-aware prompting.** The resolved agent+bottle manifest contributes a
+  generated, provider-specific system-prompt section describing the forge API
+  URL, proxy-authenticated access path, repository mapping, and safe PR
+  workflow. No token value or token environment-variable name appears in the
+  prompt.
+- **Proxy-held forge credential.** The host resolves the forge account's token
+  reference and gives it only to the egress proxy, which injects authentication
+  for the configured forge origin. The bottle receives neither the token nor a
+  credential file containing it.
+- **Trusted definitions only.** Agent and bottle files are discovered only
+  under the host-owned `~/.bot-bottle/{agents,bottles}` directories.
+  `$CWD/.bot-bottle/{agents,bottles}` never contributes definitions or
+  overrides.
+- **Signed commits with no SHA divergence.** Commits produced in the bottle are
+  signed at commit time; the SHA the agent observes is the SHA that reaches the
+  upstream through the gate.
+- **Gate rejects unsigned commits.** Before the gate forwards a push, every
+  newly-introduced commit (those not already reachable from the advertised
+  upstream refs) must verify against the activation public key; a push with any
+  unsigned or wrong-key new commit is rejected, loudly, with the offending SHA.
+  This is a **signature** check only — no author/committer matching.
+- **Control-plane-owned attribution.** The orchestrator/control plane (sole
+  owner of `bot-bottle.db`, PRD 0070) recomputes each commit's object ID from the
+  bytes, verifies the embedded signature against the activation public key it
+  holds, and attaches activation metadata from its own state — accepting no SHA,
+  key, verdict, or metadata asserted by the gateway. No upstream fetch is
+  required.
+- **Host is the source of truth.** The audit record binds each recomputed SHA to
+  the bottle, host, manifest, agent, configured agent author, activation
+  interval, and retained public key, and separately records the commit's claimed
+  author/committer.
+- **Verifiable after teardown.** The audit record retains the **full public
+  key, fingerprint, principal, and validity interval** — enough to regenerate an
+  allowed-signers file and run `git verify-commit` long after the activation
+  ends and the key is gone.
+- **Reprovision-per-activation, fail-loud teardown.** The signing key is minted
+  once per activation (persists across restarts within that activation) and
+  discarded at teardown; deploy-key revocation continues to follow PRD 0048's
+  fail-loud discipline.
+- **Push capability unchanged.** Git transport remains PRD 0048 deploy keys.
+  The forge account token is for forge API actions such as opening and
+  commenting on pull requests; it is not used for Git push.
+
+## Non-goals
+
+- **Author/committer enforcement.** Explicitly out of scope for this PRD (issue
+  #423, comment #5590). The gate does not reject a commit for carrying a foreign
+  author or committer; those fields are recorded as claims. We rely on the
+  cross-forge audit store of signed commits and the authors recorded there. See
+  **Deferred: identity enforcement** for what a future add would look like.
+- **Cryptographically-vouched author identity.** Not claimed — see **The
+  guarantee**.
+- **Forge account or token minting.** Bot-bottle does not create subusers or
+  PATs. The operator creates the agent-specific account/token out of band and
+  names the host environment secret in the trusted agent definition.
+- **Forge-side attribution surfaces.** No commit-status badges, no forge
+  "Verified" badge. The latter is doubly unsuitable: it renders dynamically
+  against a *currently registered* key (so it would lie the moment a
+  reprovisioned key is revoked), and on Gitea registering a signing key also
+  grants push. Attribution lives in the host record and local `git
+  verify-commit`, not the forge.
+- **Non-Gitea forges, dashboard UI for orphan cleanup, mid-session rotation,
+  dirty-teardown reconciliation.** As before; a separate cleanup/sync pass
+  handles orphans left by a crash or discarded snapshot.
+
+## Scope evolution
+
+This PRD started as "forge subroles" (forge subuser accounts + provisioned API
+tokens + optional forge status posting + signing). Review first narrowed it,
+then restored only the part needed for correct agent operation:
+
+1. **Dropped forge account/token provisioning** (#5518 → #5556): the PAT
+   bootstrap is not implementable as sketched (Basic-Auth-as-target-user
+   constraint), and the signature never vouched the author anyway. The host
+   audit store remains the portable source of truth.
+2. **Dropped author/committer enforcement** (#5590): rely on the audit store of
+   signed commits and the authors recorded there; gate enforcement of the
+   identity fields is a possible future add, not part of this slice.
+3. **Restored declarative forge accounts, not provisioning** (#6002): agents
+   still need an operator-supplied API identity and forge-specific system
+   instructions to open and update PRs correctly. The trusted agent definition
+   therefore references an existing host secret; bot-bottle neither creates nor
+   rotates that credential.
+4. **Moved identity to the agent trust domain** (#6002): author and forge
+   accounts are agent properties. Bottle repositories select an account by
+   name, while git-gate remains transport-only. Because these references grant
+   access to host credentials, repository-local agent/bottle discovery is
+   removed.
+
+The resulting feature is **trusted agent identity + operator-provided forge API
+access + forge-aware prompting + signed commits + a host-owned,
+independently-verified audit record.** Identity enforcement (the gate rejecting
+a foreign author/committer) remains a candidate future PRD.
+
+## Design
+
+### Trust boundary (control plane vs data plane)
+
+git-gate is the **data plane**: it parses hostile bytes from inside the bottle
+and forwards pushes. The orchestrator is the **control plane** and, per PRD
+0070, is the sole owner of `bot-bottle.db`. These are different trust boundaries,
+and the audit record must be anchored in the control plane:
+
+- The gate performs a **synchronous pre-forward signature check** (below) and
+  can reject a push before it reaches the upstream. This is a data-plane gate on
+  what leaves the bottle, not the audit binding.
+- The **control plane** takes the commit bytes to attribute (gateway-delivered
+  opaque bytes are fine), **recomputes the Git object ID**, **verifies the
+  embedded signature** against the activation public key it minted and holds, and
+  writes `attributed_commit` attaching metadata from its own state. It accepts
+  **no** gateway-supplied `verified` flag, claimed SHA, public key, or activation
+  identity.
+
+The precise trust statement (issue #423, review by didericis-codex on d8362ec,
+resolved in #5608): the row binds *these commit bytes / this recomputed SHA* to
+*access to this activation's signing key*, and the control plane binds that key
+to the recorded activation metadata. It does **not** assert forge observation or
+that only the agent (not the signing sidecar) authored the commit — so this PRD
+does **not** claim a compromised gateway cannot obtain an attribution row.
+Because the sidecar holds the activation signing capability, a compromised
+gateway *can* assemble and sign a commit and have it attributed to that
+activation; what it cannot do is make the signature verify as a *different*
+activation or choose the metadata the control plane records. That residual is
+acceptable under the intended guarantee (#5607) and is why the guarantee is
+worded as activation-key access, not agent-only authorship or upstream
+publication. The gate therefore cannot stand in for host-side verification: the
+control plane recomputes the object ID and verifies the signature itself rather
+than trusting the gate's word.
+
+### Identity model
+
+Per **bottled agent** (agent definition ∘ sealed bottle), realized per
+activation:
+
+| Part | Value | Source | Role |
+|------|-------|--------|------|
+| Signing key | one Ed25519 keypair | minted host-side per activation | signs every commit; private half sidecar-only; the anchor of provenance |
+| Author/committer | name + email | trusted agent definition `author` | written into commits and **recorded** as a claim; **not** enforced |
+| Forge actor | named account + API origin + token reference | trusted agent definition `forge-accounts` | authenticates forge API actions through the egress proxy |
+| Repository/forge association | forge account name | bottle `git-gate.repos.<repo>.forge` | selects the actor and generated workflow guidance for that repository |
+
+### Manifest surface
+
+Identity belongs to the agent. Repository capability and policy belong to the
+bottle. The following files are both host-owned:
+
+```yaml
+# ~/.bot-bottle/agents/claude.md
+---
+author:
+  name: didericis-claude
+  email: eric+claude@dideric.is
+forge-accounts:
+  didericis-gitea:
+    auth:
+      type: token
+      token_secret: GITEA_CLAUDE_TOKEN
+    url: https://gitea.dideric.is/api/v1
+---
+```
+
+```yaml
+# ~/.bot-bottle/bottles/dev.md
+---
+git-gate:
+  signing:
+    enabled: true                # NEW — opt-in per-activation signing + audit
+  repos:
+    bot-bottle:
+      url: ssh://git@100.78.141.42:30009/didericis/bot-bottle.git
+      provisioned_key:           # PRD 0048 — push capability, UNCHANGED
+        provider: gitea
+        token_env: GITEA_DEPLOY_TOKEN
+      host_key: "ssh-ed25519 AAAA..."
+      forge: didericis-gitea     # account from the selected agent definition
+---
+```
+
+- `author` is agent-only and replaces the `git-gate.user` agent/bottle overlay.
+  It is required when `git-gate.signing.enabled` is true or when any selected
+  repository has a `forge` association. The resolved values populate
+  `user.name` and `user.email`.
+- `forge-accounts` is an agent-only map keyed by the existing manifest
+  kebab-case identifier grammar (`[a-z][a-z0-9-]*`). Each entry contains:
+  - `url`: an HTTPS forge API base URL. This PRD supports Gitea API URLs; a
+    future provider must add explicit typed validation and prompt generation
+    rather than accepting arbitrary prompt text supplied by a repository.
+  - `auth.type`: `token` in this slice.
+  - `auth.token_secret`: the name of a host environment variable containing the
+    operator-provided, agent-specific API token. The value is resolved only by
+    host provisioning and passed only to the egress proxy.
+- `git-gate.repos.<name>.forge` is bottle-only and must resolve to an account in
+  the selected agent definition. An unknown account, an unsupported forge URL,
+  a non-HTTPS URL, or a missing/empty host secret fails launch before creating
+  the bottle.
+- `git-gate.signing.enabled: true` opts a bottle in. Without it, behavior is
+  exactly as today. There is **no `enforce` sub-key** — this PRD does not enforce
+  identity fields, so no knob is needed (and a knob that weakened a guarantee
+  was flagged as a contradiction in review).
+- `git-gate.signing`, `git-gate.repos`, and their `forge` associations are
+  bottle-only. `author` and `forge-accounts` are agent-only. Validation errors
+  point to the correct file/type instead of silently ignoring misplaced keys.
+- `provisioned_key.token_env` remains the deploy-key administration credential
+  from PRD 0048. It is separate from the forge actor's `token_secret`: the
+  former provisions Git push capability, while the latter performs API actions
+  as the agent.
+- Existing `git-gate.user` fields fail with migration guidance to move the
+  values into the selected home agent's `author` block. There is no period where
+  bottle identity silently overrides agent identity.
+
+### Definition trust and discovery
+
+Only the host-owned manifest tree is authoritative:
+
+- Agents: `~/.bot-bottle/agents/*.md`
+- Bottles: `~/.bot-bottle/bottles/*.md`
+
+`$CWD/.bot-bottle/agents/*.md` no longer contributes new agents and no longer
+overrides a home agent. `$CWD/.bot-bottle/bottles/*.md` remains unusable. If
+either repository-local directory contains manifest files, bot-bottle emits a
+warning that they are ignored and points to the home paths. Agent enumeration,
+`require_agent`, lazy loading, and dashboard selectors all use the same
+home-only index so there is no alternate path that can still select a workspace
+definition.
+
+This intentionally supersedes PRD 0011's repository-agent overlay. Workspace
+instructions remain repository content (for example `AGENTS.md`), but executable
+runtime policy, host secret references, and actor identity do not.
+
+Programmatic in-memory manifests remain available for tests and internal
+composition; they are already supplied by trusted host code and are not a
+filesystem discovery path.
+
+### Forge API provisioning and generated prompt
+
+For each distinct forge account referenced by the selected bottle's repos, the
+host:
+
+1. Parses and canonicalizes the HTTPS API origin and rejects credentials in the
+   URL, fragments, and unsupported path shapes.
+2. Resolves `auth.token_secret` from the host environment. The secret value is
+   copied only into the egress proxy's credential environment.
+3. Adds an inspected egress route scoped to that forge origin/API prefix with
+   the provider's authentication scheme (`token` for Gitea). Authentication is
+   injected by the proxy; the bottle sends an unauthenticated request to the
+   configured URL.
+4. Appends a generated, non-secret section to bot-bottle's existing system
+   prompt file. The section is derived from validated typed fields, not copied
+   Markdown from a repository.
+
+For the example above, the generated guidance communicates:
+
+- account alias `didericis-gitea` and API base
+  `https://gitea.dideric.is/api/v1`;
+- repository `bot-bottle` uses that account;
+- forge API calls must use the configured HTTPS URL through the proxy and must
+  not read, print, or manually attach an authorization token;
+- Git pushes still use the bottle's git-gate remote;
+- create/update a normal `refs/heads/<branch>` and open a branch-backed Gitea
+  pull request through the API; do not push `refs/for/*`, `refs/draft/*`, or
+  `refs/for-review/*`;
+- use the API for review/comment operations and verify the returned object/state
+  before claiming the action completed.
+
+The prompt includes neither the token value nor `GITEA_CLAUDE_TOKEN`. Keeping
+even the environment-variable name out of the bottle reduces accidental
+credential probing and prevents bespoke agent prompts from needing secret
+implementation details.
+
+### Signing: sign at commit time via a forwarded ssh-agent
+
+The reason SHAs never diverge:
+
+- The **sidecar** (the git-gate trust boundary) runs an `ssh-agent` holding the
+  short-lived signing private key.
+- **Only `SSH_AUTH_SOCK`** is forwarded into the bottle — a bounded signing
+  capability, not the key.
+- The provisioner writes the bottle `.gitconfig`:
+
+  ```ini
+  [commit]
+      gpgsign = true
+  [gpg]
+      format = ssh
+  [user]
+      name = didericis-claude
+      email = eric+claude@dideric.is
+      signingkey = ssh-ed25519 AAAA...   # activation signing PUBLIC key
+  ```
+
+- `git commit` asks the forwarded agent to sign; the signature is embedded at
+  object creation, so the agent-space SHA equals the pushed SHA. No transcoder,
+  no SHA translation table.
+
+### Gate pre-forward signature check (data plane)
+
+The gate already fetches from upstream before every `upload-pack` and mirrors
+bidirectionally (PRD 0008). When `git-gate.signing.enabled` is set, after
+gitleaks and before forwarding a push upstream:
+
+1. **Compute the newly-introduced set.** Commits reachable from the pushed ref
+   tips but **not** reachable from any ref already advertised by the upstream
+   (which the gate knows because it fetches upstream first) — equivalent to
+   `git rev-list <new-tips> --not <all-known-upstream-refs>`. This excludes
+   pulled/merged existing history; a merge commit the bottle creates is itself
+   new and is checked, its already-upstream ancestors are not.
+2. **Verify each new commit's signature** against the activation public key. A
+   commit that is unsigned or signed by any other key causes the push to be
+   **rejected** with the offending SHA.
+3. No author/committer matching is performed.
+
+This is a synchronous safety gate on what leaves the bottle; it is not the audit
+record.
+
+### Control-plane verification & recording
+
+For each commit to attribute (the gate hands the control plane the commit bytes;
+opaque gateway-delivered bytes are acceptable because nothing the gateway *says*
+about them is trusted), the orchestrator/control plane:
+
+1. **Recomputes the Git object ID** from the bytes itself. The stored `sha` is
+   this recomputed value, never a SHA the gateway claims.
+2. **Verifies the embedded signature** against the activation public key it
+   minted and holds for that activation (via a generated allowed-signers file) —
+   ignoring any `verified` flag, key, or activation identity supplied by the
+   gateway.
+3. Writes `attributed_commit` only for bytes that pass, stamping the activation
+   metadata (bottle/manifest/agent/host/interval) from its **own** state — not
+   from anything the gateway provides — and recording the commit's claimed
+   author/committer.
+
+No upstream fetch is required: the guarantee is a byte↔activation-key binding, so
+the object does not need to come from the forge (issue #423, #5608). Bytes that
+do not verify against the activation key are **not** recorded as attributed (they
+may be logged as an anomaly instead).
+
+### Audit trail
+
+The host SQLite store (PRD 0067, `~/.bot-bottle/bot-bottle.db`, owned by the
+control plane per PRD 0070) records the signing-key lifecycle and per-commit
+attribution. Retention is the **full public key, fingerprint, principal, and
+validity interval** — enough to regenerate an allowed-signers file and verify
+commits after teardown (issue #423, comment #5554, resolution 3). Never any
+private key material.
+
+```sql
+CREATE TABLE bottled_agent_activation (
+    bottled_agent_slug TEXT NOT NULL,
+    activation_id      TEXT NOT NULL,     -- one per activation cycle
+    host              TEXT NOT NULL,
+    manifest_digest   TEXT NOT NULL,      -- ties the record to the sealed manifest
+    agent             TEXT NOT NULL,
+    configured_author_name  TEXT NOT NULL, -- trusted agent definition value
+    configured_author_email TEXT NOT NULL, -- trusted agent definition value
+    signing_pubkey    TEXT NOT NULL,      -- full ssh-ed25519 public key (for verify-commit)
+    signing_fpr       TEXT NOT NULL,      -- SHA256:... fingerprint (stable handle)
+    principal         TEXT NOT NULL,      -- allowed-signers principal, e.g. the author email
+    valid_from        TEXT NOT NULL,
+    valid_until       TEXT,               -- NULL while active; set at teardown
+    status            TEXT NOT NULL,      -- active | retired
+    PRIMARY KEY (bottled_agent_slug, activation_id)
+);
+
+CREATE TABLE attributed_commit (
+    sha                TEXT NOT NULL,      -- control-plane-RECOMPUTED object ID, not gateway-claimed
+    bottled_agent_slug TEXT NOT NULL,
+    activation_id      TEXT NOT NULL,
+    repo               TEXT NOT NULL,
+    author_name        TEXT NOT NULL,     -- CLAIMED, recorded as-is (not enforced)
+    author_email       TEXT NOT NULL,     -- CLAIMED
+    committer_name     TEXT NOT NULL,     -- CLAIMED
+    committer_email    TEXT NOT NULL,     -- CLAIMED
+    observed_at        TEXT NOT NULL,
+    PRIMARY KEY (sha, repo)
+);
+```
+
+Verification/allowed-signers generation is a stated part of the design: for a
+given SHA, join `attributed_commit → bottled_agent_activation`, emit
+`<principal> <signing_pubkey>` to a temporary allowed-signers file, and
+`git verify-commit` (or `ssh-keygen -Y verify`) against it. The
+`(pubkey, principal, valid_from/until)` tuple is exactly what that requires. The
+activation's `configured_author_*` columns preserve the trusted agent
+configuration. The attributed commit's author/committer columns are the
+commit's *claim*; consumers compare the two if useful, understanding that a
+mismatch is recorded but not rejected.
+
+### Credential lifecycle
+
+Signing follows PRD 0048's lifecycle discipline. The operator-provided forge
+actor token is referenced, not provisioned:
+
+- **Activation:** mint a fresh Ed25519 signing keypair; load the private half
+  into the sidecar `ssh-agent`; write the public half into `.gitconfig` and the
+  `bottled_agent_activation` row (`active`, `valid_from` set). Deploy keys are
+  provisioned exactly as PRD 0048. Resolve each referenced forge actor token
+  from the host environment and install it only in the egress proxy process.
+  Minting is **per activation** (a restart re-attaches the same key; a new
+  activation mints a new key and retires the old row), so frozen snapshots
+  don't accumulate live keys.
+- **Teardown (fail-loud):** revoke provisioned deploy keys via the forge API
+  (0048); discard the signing key from the sidecar agent and set the activation
+  row to `retired` with `valid_until`. The signing key was never on the forge,
+  so there is nothing to revoke there — only the local retire. Deploy-key
+  revocation failure halts teardown (0048); 404 = already-gone = success. Stop
+  the egress proxy to discard its copy of the forge actor token. The
+  operator-owned token itself is not revoked because bot-bottle did not mint it
+  and it may be reused by later activations of the same trusted agent.
+- **Dirty teardown** is assumed handled; a separate cleanup/sync pass reconciles
+  orphaned deploy keys.
+
+## Deferred: identity enforcement
+
+If a future PRD wants the gate to *enforce* that new commits carry the manifest
+identity, the natural shape is: extend the gate pre-forward check to also require
+each new commit's author **and** committer name/email to equal the resolved
+agent `author`,
+rejecting mismatches — with the same control-plane re-verification before
+recording. This is deliberately left out now (issue #423, comment #5590); it is
+noted so the door stays open and the current schema (which records the claimed
+author/committer) already carries what such a check would compare against. Note
+that even then the property would be gate-*enforced*, not signature-*vouched*; a
+validating signing broker in front of the key would be required for the latter.
+
+## Implementation chunks
+
+1. **This PRD.** Sets the revised design and trust boundary.
+2. **Trusted definition boundary.** Remove `$CWD/.bot-bottle/agents` from
+   discovery, override, enumeration, lazy loading, and selectors. Keep both
+   agent and bottle definitions home-only; warn on ignored repository files.
+   Update PRD 0011-facing docs and migration guidance.
+3. **Identity and forge manifest surface.** Add agent-only `author` and
+   `forge-accounts`; remove `git-gate.user`; add bottle-only
+   `git-gate.signing` (`enabled` only) and
+   `git-gate.repos.<name>.forge`. Validate account references after composing
+   the selected agent+bottle and fail closed on missing host secrets or
+   unsupported URLs/providers.
+4. **Forge proxy + prompt provisioning.** Resolve referenced actor tokens into
+   scoped egress proxy routes and generate provider-specific, non-secret system
+   instructions from typed manifest fields. Gitea guidance covers API usage,
+   branch-backed PRs, prohibited AGit refs, and verifying mutations. Test that
+   neither token values nor token secret names enter the bottle or prompt.
+5. **Signing pipeline.** Sidecar `ssh-agent` provisioning; forward
+   `SSH_AUTH_SOCK` into the bottle across docker, smolmachines, macOS-container,
+   and firecracker backends; emit the `commit.gpgsign` / `gpg.format=ssh` /
+   `user.signingkey` gitconfig. Integration test: a bottle commit is
+   `verify-commit`-valid and its SHA is unchanged through the gate; the private
+   key is absent from the bottle.
+6. **Gate pre-forward signature check.** Compute the newly-introduced set
+   (excluding upstream-reachable commits), verify each against the activation
+   key, reject unsigned/wrong-key with the offending SHA. Tests: unsigned
+   rejected; wrong-key rejected; pulled/merged upstream history passes; an
+   all-signed push succeeds. A foreign-author commit that is correctly signed
+   **passes the gate** (identity is not enforced here).
+7. **Control-plane verification + audit.** `bottled_agent_activation` /
+   `attributed_commit` tables (PRD 0067 store, control-plane-owned per PRD 0070);
+   the control plane recomputes each commit's object ID and verifies the
+   signature before writing a row; retain full pubkey + fingerprint + principal +
+   validity interval; record claimed author/committer; allowed-signers generation
+   + a post-teardown `verify-commit` helper. Tests: a gateway-claimed SHA/key/
+   verdict is ignored — the row's `sha` is the recomputed ID and bytes not signed
+   by the activation key produce **no** row.
+8. **Docs.** Glossary entries for forge account and per-bottle signed commits;
+   README agent/bottle schema and home-only migration; ADR note that
+   signing-enabled bottles gain signed *provenance* and a host-owned audit
+   record while authorship stays *claimed* (ADR 0002 unchanged).
+
+## Testing strategy
+
+- **Unit — trust boundary (must):** cwd agent files are ignored with a warning,
+  cannot override a home agent, are absent from enumeration/selectors, and
+  cannot be loaded by name. Cwd bottle behavior remains home-only.
+- **Unit — manifest (must):** `author`, `forge-accounts`,
+  `git-gate.signing`, and repo `forge` parsing/validation; misplaced-field
+  rejection; kebab-case account names; unknown account references; HTTPS/API
+  URL validation; missing token-secret environment values.
+- **Unit — prompt/proxy (must):** only referenced forge accounts produce proxy
+  routes and guidance; Gitea instructions name the API/repo and branch-backed
+  workflow; token values and `token_secret` names are absent from the prompt and
+  bottle environment; auth is scoped to the validated forge API origin.
+- **Integration — signing (must):** end-to-end signed commit verifies with
+  `git verify-commit`; SHA observed in the bottle equals the SHA upstream; the
+  private key is absent from the bottle.
+- **Integration — gate check (must):** unsigned rejected; wrong-key rejected;
+  the upstream-reachable exclusion (pull + merge human history and push a signed
+  merge); a correctly-signed foreign-author commit **passes** (no identity
+  enforcement); a clean all-signed push succeeds.
+- **Control plane (must):** the control plane recomputes the object ID and
+  records a row for bytes genuinely signed by the activation key; a gateway-
+  supplied SHA/key/verdict is ignored (the stored `sha` is the recomputed value);
+  bytes signed by a foreign/invalid key produce **no** row; the activation
+  retains the configured agent author while a differing commit author is
+  recorded separately as an unenforced claim.
+- **Lifecycle:** activation mints the key and writes an `active` row; teardown
+  retires it (`valid_until`) and revokes deploy keys fail-loud; a restart
+  re-attaches the same key (no new row); a fresh activation mints a new key and
+  retires the old.
+- **Post-teardown verification:** regenerate the allowed-signers file from a
+  `retired` row and confirm `verify-commit` still succeeds for an attributed SHA.
+
+## Resolved: control-plane transport
+
+Raised in review and **resolved** (issue #423, #5608): the commit object does not
+need to come from the forge, and reading the gateway-owned mirror is no stronger
+than accepting gateway-delivered bytes — both are fabricatable, and neither
+matters because the control plane trusts nothing the gateway *asserts*. The
+transport is therefore: the gate hands the control plane the raw commit bytes,
+the control plane **recomputes the object ID** and **verifies the signature**
+against the activation key, and stamps its own activation metadata. No upstream
+fetch. This is exactly what makes the byte↔activation-key binding sound
+regardless of transport.
+
+## Open questions
+
+- **Where the gate check slots into PRD 0008 ordering.** Modeled as a
+  pre-forward step after gitleaks; confirm it composes with the existing
+  access-hook / mirror ordering rather than needing a separate hook.

docs/research/rootless-docker-in-apple-container-spike.md

@@ -4,7 +4,7 @@ Spike branch: `spike/rootless-docker-macos` (`a4d8461`)
 
 **Outcome:** the podman recommendation below shipped as the
 `nested_containers` bottle flag — see
-[`docs/prds/0075-nested-containers.md`](../prds/0075-nested-containers.md).
+[`docs/prds/prd-new-nested-containers.md`](../prds/prd-new-nested-containers.md).
 The `docker_access` name used throughout the spike text was renamed on the
 way in; it granted no access to anything on the host.
 

install.sh

@@ -1,123 +0,0 @@
-#!/bin/sh
-# bot-bottle quick installer.
-#
-# Usage:
-#   curl -fsSL https://gitea.dideric.is/didericis/bot-bottle/raw/branch/main/install.sh | sh
-#
-# Python-native users can skip this entirely:
-#   pipx install bot-bottle        # from a checkout or a published index
-#   uv tool install bot-bottle
-#
-# This script is a thin bootstrapper: it checks prerequisites, installs the
-# package with pipx (falling back to pip --user), creates the config dir, and
-# runs `bot-bottle doctor`. It is idempotent (safe to re-run) and never uses
-# sudo. It does NOT install Docker or a VM backend for you — `doctor` reports
-# what's missing after install.
-set -eu
-
-PACKAGE_SPEC="${BOT_BOTTLE_INSTALL_SPEC:-git+https://gitea.dideric.is/didericis/bot-bottle.git}"
-MIN_PYTHON_MAJOR=3
-MIN_PYTHON_MINOR=11
-
-say() {
-    printf 'bot-bottle install: %s\n' "$*" >&2
-}
-
-die() {
-    say "error: $*"
-    exit 1
-}
-
-# --- prerequisites -----------------------------------------------------------
-
-command -v python3 >/dev/null 2>&1 \
-    || die "python3 ${MIN_PYTHON_MAJOR}.${MIN_PYTHON_MINOR}+ is required but was not found"
-
-python3 - "$MIN_PYTHON_MAJOR" "$MIN_PYTHON_MINOR" <<'PY' || die "python3 ${MIN_PYTHON_MAJOR}.${MIN_PYTHON_MINOR} or newer is required"
-import sys
-
-want = (int(sys.argv[1]), int(sys.argv[2]))
-raise SystemExit(0 if sys.version_info[:2] >= want else 1)
-PY
-
-# Installing a `git+` spec (the default) shells out to git under the hood,
-# whether via pipx or pip. Fail early with a clear message rather than deep
-# inside the installer's output.
-case "${PACKAGE_SPEC}" in
-    git+*|*.git)
-        command -v git >/dev/null 2>&1 || die \
-            "git is required to install from '${PACKAGE_SPEC}'. Install git, or set "\
-"BOT_BOTTLE_INSTALL_SPEC to a non-git spec (e.g. a wheel path or a package index name)."
-        ;;
-esac
-
-# The pip fallback needs a usable pip. Externally-managed interpreters
-# (PEP 668, common on Debian/Ubuntu/Homebrew) reject `pip install --user`;
-# pipx sidesteps that, so recommend it when pip can't be used.
-if ! command -v pipx >/dev/null 2>&1; then
-    python3 -m pip --version >/dev/null 2>&1 || die \
-        "neither pipx nor a usable 'python3 -m pip' was found. Install pipx "\
-"(recommended): 'python3 -m pip install --user pipx' or your OS package manager."
-    if python3 - <<'PY'
-import os
-import sys
-import sysconfig
-
-# PEP 668: an EXTERNALLY-MANAGED marker in the stdlib dir means pip refuses
-# to install into this interpreter without --break-system-packages.
-marker = os.path.join(sysconfig.get_path("stdlib"), "EXTERNALLY-MANAGED")
-raise SystemExit(0 if os.path.exists(marker) else 1)
-PY
-    then
-        die "this Python is externally managed (PEP 668), so 'pip install --user' is "\
-"blocked. Install pipx and re-run: 'python3 -m pip install --user --break-system-packages pipx', "\
-"then 'pipx ensurepath'."
-    fi
-fi
-
-# --- config directories ------------------------------------------------------
-
-mkdir -p \
-    "${HOME}/.bot-bottle/agents" \
-    "${HOME}/.bot-bottle/bottles" \
-    "${HOME}/.bot-bottle/contrib"
-
-# --- install -----------------------------------------------------------------
-
-if command -v pipx >/dev/null 2>&1; then
-    say "installing with pipx"
-    pipx install --force "${PACKAGE_SPEC}"
-else
-    say "pipx not found; installing with 'python3 -m pip install --user'"
-    python3 -m pip install --user --upgrade "${PACKAGE_SPEC}"
-fi
-
-# --- locate the entry point --------------------------------------------------
-
-# The pip --user scripts directory is platform-specific: ~/.local/bin on Linux,
-# but ~/Library/Python/<X.Y>/bin on a python.org macOS interpreter. Ask the
-# interpreter for its own user-scheme scripts dir instead of hardcoding.
-USER_SCRIPTS="$(python3 - <<'PY'
-import sysconfig
-print(sysconfig.get_path("scripts", sysconfig.get_preferred_scheme("user")))
-PY
-)"
-
-if command -v bot-bottle >/dev/null 2>&1; then
-    BOT_BOTTLE_BIN="bot-bottle"
-elif [ -n "${USER_SCRIPTS}" ] && [ -x "${USER_SCRIPTS}/bot-bottle" ]; then
-    BOT_BOTTLE_BIN="${USER_SCRIPTS}/bot-bottle"
-    say "note: add ${USER_SCRIPTS} to your PATH to run 'bot-bottle' directly"
-else
-    die "bot-bottle was installed but is not on PATH; add ${USER_SCRIPTS:-your user scripts dir} to PATH and re-run"
-fi
-
-# --- verify ------------------------------------------------------------------
-
-say "running '${BOT_BOTTLE_BIN} doctor'"
-if "${BOT_BOTTLE_BIN}" doctor; then
-    say "done. Run '${BOT_BOTTLE_BIN} --help' to get started."
-else
-    say "install completed, but 'doctor' reported unmet prerequisites (see above)."
-    say "resolve them, then re-run '${BOT_BOTTLE_BIN} doctor'."
-fi

pyproject.toml

@@ -4,42 +4,5 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bot-bottle"
-version = "0.1.0"
-description = "Self-hosted sandbox for running AI coding agents with egress controls"
-readme = "README.md"
+version = "0.0.0"
 requires-python = ">=3.11"
-license = { text = "Apache-2.0" }
-authors = [{ name = "didericis" }]
-keywords = ["ai", "agents", "sandbox", "security", "egress"]
-classifiers = [
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3 :: Only",
-    "Operating System :: POSIX :: Linux",
-    "Operating System :: MacOS",
-]
-# The package itself has no runtime pip dependencies (stdlib-only); the
-# only language runtime is the Python interpreter. Keep this empty.
-dependencies = []
-
-[project.urls]
-Homepage = "https://gitea.dideric.is/didericis/bot-bottle"
-Source = "https://gitea.dideric.is/didericis/bot-bottle"
-
-[project.scripts]
-bot-bottle = "bot_bottle.cli:main"
-
-[tool.setuptools.packages.find]
-include = ["bot_bottle*"]
-
-# Non-Python assets the runtime reads from inside the package (container
-# build contexts, entrypoints, netpool defaults). Keep in sync with the
-# files shipped under bot_bottle/; test_pyproject.py asserts they exist.
-[tool.setuptools.package-data]
-bot_bottle = [
-    "gateway/egress/entrypoint.sh",
-    "contrib/claude/Dockerfile",
-    "contrib/codex/Dockerfile",
-    "contrib/pi/Dockerfile",
-    "backend/firecracker/netpool.defaults.env",
-    "backend/macos_container/nested-containers-init.sh",
-]

requirements-dev.txt

@@ -5,6 +5,3 @@
 pylint>=3.0.0
 pyright>=1.1.411
 coverage>=7.0.0
-# PEP 517 build front-end used by tests/unit/test_wheel_install.py to build and
-# install a real wheel (proves the installed distribution is self-contained).
-build>=1.0.0

scripts/coverage.sh

@@ -20,10 +20,10 @@ cd "$(dirname "$0")/.."
 
 PY="${PYTHON:-python3}"
 
-# Critical security/logic core held to the high bar by ADR 0004. The helper
-# fails before coverage when a curated path was renamed or removed; Coverage.py
-# itself would silently ignore that stale include and inflate the score.
-CRITICAL=$("$PY" scripts/critical_modules.py)
+# Critical security/logic core held to the high bar by ADR 0004. The list
+# lives in one place (scripts/critical-modules.txt) so this report and the
+# README "core coverage" badge can't drift; comma-join it for --include.
+CRITICAL=$(grep -vE '^[[:space:]]*(#|$)' scripts/critical-modules.txt | paste -sd, -)
 
 if [ "${1:-}" = "aggregate" ]; then
     # Aggregate mode: combine .coverage.* artifacts already in the workspace.
@@ -34,8 +34,8 @@ if [ "${1:-}" = "aggregate" ]; then
     "$PY" -m coverage report -m
 
     if [ "${2:-}" = "critical" ]; then
-        echo "== critical modules (ADR 0004 minimum: 90%) ==" >&2
-        "$PY" -m coverage report --include="$CRITICAL" --fail-under=90
+        echo "== critical modules (ADR 0004 target: 90%) ==" >&2
+        "$PY" -m coverage report --include="$CRITICAL"
     fi
     exit 0
 fi
@@ -55,6 +55,6 @@ echo "== combined report ==" >&2
 "$PY" -m coverage report -m
 
 if [ "${1:-}" = "critical" ]; then
-    echo "== critical modules (ADR 0004 minimum: 90%) ==" >&2
-    "$PY" -m coverage report --include="$CRITICAL" --fail-under=90
+    echo "== critical modules (ADR 0004 target: 90%) ==" >&2
+    "$PY" -m coverage report --include="$CRITICAL"
 fi

scripts/critical-modules.txt

@@ -7,48 +7,19 @@
 # number that silently stops measuring a module is worse than no badge.
 #
 # One module path per line, relative to the repo root. Blank lines and
-# `#` comments are ignored. scripts/critical_modules.py rejects missing,
-# duplicate, non-Python, and out-of-repository entries before coverage runs.
-
-# Host-side egress planning and secret preparation.
-bot_bottle/egress/plan.py
-bot_bottle/egress/service.py
-
-# Gateway egress policy, matching, and DLP enforcement.
+# `#` comments are ignored.
 bot_bottle/gateway/egress/addon.py
 bot_bottle/gateway/egress/addon_core.py
-bot_bottle/gateway/egress/context.py
-bot_bottle/gateway/egress/dlp.py
-bot_bottle/gateway/egress/dlp_config.py
 bot_bottle/gateway/egress/dlp_detectors.py
-bot_bottle/gateway/egress/matching.py
-bot_bottle/gateway/egress/schema.py
-bot_bottle/gateway/egress/types.py
-
-# Manifest trust boundary and schema.
-bot_bottle/manifest/agent.py
-bot_bottle/manifest/bottle.py
-bot_bottle/manifest/egress.py
-bot_bottle/manifest/extends.py
-bot_bottle/manifest/git.py
-bot_bottle/manifest/index.py
-bot_bottle/manifest/loader.py
-bot_bottle/manifest/schema.py
-bot_bottle/manifest/util.py
-
-# Host-side and gateway-side git policy enforcement.
-bot_bottle/git_gate/host_key.py
-bot_bottle/git_gate/plan.py
-bot_bottle/git_gate/provision.py
-bot_bottle/git_gate/service.py
+bot_bottle/egress.py
+bot_bottle/manifest.py
+bot_bottle/manifest_egress.py
+bot_bottle/manifest_agent.py
+bot_bottle/manifest_schema.py
+bot_bottle/git_gate.py
 bot_bottle/gateway/git_gate/render.py
+bot_bottle/git_gate_provision.py
 bot_bottle/gateway/git_gate/http_backend.py
-
-# Supervise proposal protocol and data plane.
-bot_bottle/supervisor/plan.py
-bot_bottle/supervisor/types.py
-bot_bottle/gateway/supervisor/server.py
-
-# Shared parsers and state validation.
+bot_bottle/supervise.py
 bot_bottle/yaml_subset.py
 bot_bottle/bottle_state.py

scripts/critical_modules.py

@@ -1,101 +0,0 @@
-#!/usr/bin/env python3
-"""Validate and render the critical-module coverage manifest.
-
-Coverage.py silently ignores an ``--include`` path that does not exist.  That
-is useful for broad globs, but dangerous for bot-bottle's curated security
-core: a rename could otherwise improve the reported percentage by removing a
-module from the measurement.  Keep the validation in one small stdlib helper
-and make every coverage consumer call it.
-"""
-
-from __future__ import annotations
-
-import argparse
-import sys
-from pathlib import Path
-
-
-REPO_ROOT = Path(__file__).resolve().parents[1]
-DEFAULT_MANIFEST = REPO_ROOT / "scripts" / "critical-modules.txt"
-
-
-class CriticalModulesError(ValueError):
-    """The critical-module manifest is empty, ambiguous, or stale."""
-
-
-def load_critical_modules(manifest: Path, *, root: Path) -> list[str]:
-    """Return validated module paths relative to *root*.
-
-    Entries must be unique, concrete Python files inside the repository.
-    Globs are deliberately rejected by the file check: each rename must update
-    this explicit security review surface.
-    """
-
-    root = root.resolve()
-    try:
-        lines = manifest.read_text(encoding="utf-8").splitlines()
-    except OSError as exc:
-        raise CriticalModulesError(
-            f"cannot read critical-module manifest {manifest}: {exc}"
-        ) from exc
-
-    modules: list[str] = []
-    seen: set[str] = set()
-    errors: list[str] = []
-    for line_number, raw in enumerate(lines, start=1):
-        entry = raw.strip()
-        if not entry or entry.startswith("#"):
-            continue
-        path = Path(entry)
-        prefix = f"{manifest}:{line_number}: {entry!r}"
-        if path.is_absolute():
-            errors.append(f"{prefix} must be relative to the repository root")
-            continue
-        try:
-            resolved = (root / path).resolve()
-            resolved.relative_to(root)
-        except ValueError:
-            errors.append(f"{prefix} escapes the repository root")
-            continue
-        if entry in seen:
-            errors.append(f"{prefix} is duplicated")
-            continue
-        seen.add(entry)
-        if path.suffix != ".py":
-            errors.append(f"{prefix} is not a Python module")
-            continue
-        if not resolved.is_file():
-            errors.append(f"{prefix} does not exist")
-            continue
-        modules.append(path.as_posix())
-
-    if not modules and not errors:
-        errors.append(f"{manifest}: contains no critical modules")
-    if errors:
-        raise CriticalModulesError("\n".join(errors))
-    return modules
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        description="validate and print the critical coverage include list"
-    )
-    parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
-    parser.add_argument("--root", type=Path, default=REPO_ROOT)
-    parser.add_argument(
-        "--check", action="store_true",
-        help="validate only; do not print the comma-separated include list",
-    )
-    args = parser.parse_args(argv)
-    try:
-        modules = load_critical_modules(args.manifest, root=args.root)
-    except CriticalModulesError as exc:
-        print(f"critical-modules: {exc}", file=sys.stderr)
-        return 1
-    if not args.check:
-        print(",".join(modules))
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

scripts/tracker_policy.py

@@ -54,20 +54,18 @@ def check_pull_request(event: dict[str, Any], api: GiteaApi) -> list[str]:
     pull = event["pull_request"]
     errors: list[str] = []
     labels = pull.get("labels") or []
-    numbers = deliberate_issue_numbers(pull.get("title", ""), pull.get("body", ""))
-    if labels and numbers:
+    if labels:
         errors.append(
-            "PR must use exactly one tracking mode: remove PR labels when "
-            "linking an issue, or remove the issue reference when labels "
-            "belong on the PR."
+            "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:
-        if not labels:
-            errors.append(
-                "PR must either have a label or reference an issue with "
-                "Closes/Fixes/Resolves #N, Part of #N, Related to #N, "
-                "Refs #N, or References #N."
-            )
+        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

scripts/unittest_gate.py

@@ -1,67 +0,0 @@
-#!/usr/bin/env python3
-"""Run unittest discovery with explicit execution-count assurances.
-
-The standard unittest CLI exits successfully when a suite contains skipped
-tests. That is normally useful, but it let the Docker integration job stay
-green while its security-boundary classes were all skipped under act_runner.
-This wrapper keeps normal unittest output and adds opt-in minimum-executed and
-no-skip gates for jobs that promise a concrete integration surface.
-"""
-
-from __future__ import annotations
-
-import argparse
-import sys
-import unittest
-
-
-def assurance_errors(
-    *, tests_run: int, skipped: int, minimum_executed: int, fail_on_skip: bool
-) -> list[str]:
-    """Return human-readable assurance failures for a completed suite."""
-
-    executed = tests_run - skipped
-    errors: list[str] = []
-    if executed < minimum_executed:
-        errors.append(
-            f"executed {executed} test(s), below required minimum "
-            f"{minimum_executed} (discovered {tests_run}, skipped {skipped})"
-        )
-    if fail_on_skip and skipped:
-        errors.append(f"{skipped} test(s) skipped in a no-skip suite")
-    return errors
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        description="unittest discovery with execution-count assurance"
-    )
-    parser.add_argument("-s", "--start-directory", default=".")
-    parser.add_argument("-t", "--top-level-directory", default=None)
-    parser.add_argument("-p", "--pattern", default="test*.py")
-    parser.add_argument("--minimum-executed", type=int, default=0)
-    parser.add_argument("--fail-on-skip", action="store_true")
-    parser.add_argument("-v", "--verbose", action="store_true")
-    args = parser.parse_args(argv)
-
-    suite = unittest.defaultTestLoader.discover(
-        args.start_directory,
-        pattern=args.pattern,
-        top_level_dir=args.top_level_directory,
-    )
-    result = unittest.TextTestRunner(
-        verbosity=2 if args.verbose else 1,
-    ).run(suite)
-    failures = assurance_errors(
-        tests_run=result.testsRun,
-        skipped=len(result.skipped),
-        minimum_executed=args.minimum_executed,
-        fail_on_skip=args.fail_on_skip,
-    )
-    for failure in failures:
-        print(f"unittest-gate: {failure}", file=sys.stderr)
-    return 0 if result.wasSuccessful() and not failures else 1
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

setup.py

@@ -1,46 +0,0 @@
-"""Build shim. Project metadata lives in ``pyproject.toml``; this only adds a
-build step that copies the root-level build resources (the Dockerfiles, the
-nix netpool module, the netpool script, and ``pyproject.toml``) into
-``bot_bottle/_resources/`` so an installed wheel is self-contained and can
-build its gateway/infra/orchestrator images without a source checkout.
-
-Kept in sync with ``bot_bottle.resources.BUNDLED_RESOURCES`` — the
-``test_resources`` suite guards against drift between the two lists.
-"""
-
-from __future__ import annotations
-
-import shutil
-from pathlib import Path
-
-from setuptools import setup
-from setuptools.command.build_py import build_py
-
-_ROOT = Path(__file__).resolve().parent
-
-# Must match bot_bottle.resources.BUNDLED_RESOURCES (paths relative to root).
-_BUNDLED_RESOURCES = (
-    "pyproject.toml",
-    "Dockerfile.gateway",
-    "Dockerfile.orchestrator",
-    "Dockerfile.orchestrator.fc",
-    "nix/firecracker-netpool.nix",
-    "scripts/firecracker-netpool.sh",
-)
-
-
-class _BundleResources(build_py):
-    """Copy the root-level build resources into the built package tree so they
-    ship inside the wheel under ``bot_bottle/_resources/``."""
-
-    def run(self) -> None:
-        super().run()
-        pkg_resources = Path(self.build_lib) / "bot_bottle" / "_resources"
-        for rel in _BUNDLED_RESOURCES:
-            src = _ROOT / rel
-            dst = pkg_resources / rel
-            dst.parent.mkdir(parents=True, exist_ok=True)
-            shutil.copy2(src, dst)
-
-
-setup(cmdclass={"build_py": _BundleResources})

tests/README.md

@@ -20,11 +20,10 @@ tests/
     ...                             # many others; see unit/ directory
   integration/
     test_gateway_image.py
-    test_sandbox_escape.py
+    test_dry_run_plan.py
     test_orphan_cleanup.py
     ...
-  canaries/
-    test_gitleaks_release.py        # opt-in upstream artifact check
+  canaries/                         # opt-in; see below (currently empty)
 ```
 
 Classification falls out of the directory — no hand-maintained list to
@@ -44,27 +43,24 @@ Discovery is invoked with `-t .` (top-level dir = repo root) so the
 
 ## What the integration tests cover
 
+- `test_dry_run_plan.py` — `cli.py start --dry-run --format=json` emits
+  a structured plan that contains the resolved egress allowlist and
+  the bottle's runtime, and creates zero Docker resources.
 - `test_orphan_cleanup.py` — `network_remove` is idempotent against
   missing resources, so the EXIT trap can call it unconditionally.
 - `test_gateway_image.py` — builds Dockerfile.gateway and
   probes that gitleaks / mitmdump / supervise are all reachable
   inside the gateway image.
-- `test_orchestrator_docker_auth.py` — drives the real control-plane
-  container and verifies role-scoped authentication.
-- `test_multitenant_isolation.py` and `test_sandbox_escape.py` — exercise
-  token/allowlist separation and end-to-end escape attempts.
 
 ## Canaries
 
 `tests/canaries/` holds upstream-regression checks gated on
 `BOT_BOTTLE_RUN_CANARIES=1` and not part of the per-push suite.
-They're invoked by the scheduled `canaries` workflow. The gitleaks canary
-downloads the exact release archive pinned by `Dockerfile.gateway`, verifies
-its architecture-specific checksum, and executes the binary.
+They're invoked by the scheduled `canaries` workflow. Currently
+no canaries are defined.
 
 ```bash
-BOT_BOTTLE_RUN_CANARIES=1 python -m scripts.unittest_gate \
-  -t . -s tests/canaries -v --minimum-executed 1 --fail-on-skip
+BOT_BOTTLE_RUN_CANARIES=1 python -m unittest discover -t . -s tests/canaries -v
 ```
 
 ## What's NOT covered

tests/canaries/test_gitleaks_release.py

@@ -1,85 +0,0 @@
-"""Canary: the pinned gitleaks release remains downloadable and executable.
-
-The gateway Dockerfile verifies this archive during an image build. Repeating
-the upstream check weekly keeps registry/release drift out of normal pull
-requests while proving that the pinned URL, architecture checksum, archive
-shape, and binary still agree.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import os
-import platform
-import re
-import subprocess
-import tarfile
-import tempfile
-import unittest
-import urllib.request
-from pathlib import Path
-
-
-ROOT = Path(__file__).resolve().parents[2]
-DOCKERFILE = ROOT / "Dockerfile.gateway"
-
-
-def _docker_arg(text: str, name: str) -> str:
-    match = re.search(rf"^ARG {re.escape(name)}=(\S+)$", text, re.MULTILINE)
-    if match is None:
-        raise AssertionError(f"Dockerfile.gateway has no concrete ARG {name}")
-    return match.group(1)
-
-
-@unittest.skipUnless(
-    os.environ.get("BOT_BOTTLE_RUN_CANARIES") == "1",
-    "canary suite is opt-in; set BOT_BOTTLE_RUN_CANARIES=1 to run",
-)
-class TestGitleaksRelease(unittest.TestCase):
-    def test_pinned_archive_checksum_and_binary(self) -> None:
-        dockerfile = DOCKERFILE.read_text(encoding="utf-8")
-        version = _docker_arg(dockerfile, "GITLEAKS_VERSION")
-        machine = platform.machine().lower()
-        architectures = {
-            "x86_64": ("linux_x64", "GITLEAKS_SHA256_AMD64"),
-            "amd64": ("linux_x64", "GITLEAKS_SHA256_AMD64"),
-            "aarch64": ("linux_arm64", "GITLEAKS_SHA256_ARM64"),
-            "arm64": ("linux_arm64", "GITLEAKS_SHA256_ARM64"),
-        }
-        if machine not in architectures:
-            self.fail(f"unsupported canary runner architecture: {machine}")
-        asset, checksum_arg = architectures[machine]
-        expected_checksum = _docker_arg(dockerfile, checksum_arg)
-        url = (
-            "https://github.com/gitleaks/gitleaks/releases/download/"
-            f"v{version}/gitleaks_{version}_{asset}.tar.gz"
-        )
-
-        with tempfile.TemporaryDirectory(prefix="bot-bottle-gitleaks-canary.") as tmp:
-            archive = Path(tmp) / "gitleaks.tar.gz"
-            urllib.request.urlretrieve(url, archive)
-            self.assertEqual(
-                expected_checksum,
-                hashlib.sha256(archive.read_bytes()).hexdigest(),
-                "the pinned upstream archive no longer matches Dockerfile.gateway",
-            )
-            with tarfile.open(archive, "r:gz") as bundle:
-                member = bundle.getmember("gitleaks")
-                source = bundle.extractfile(member)
-                if source is None:
-                    self.fail("gitleaks archive member is not a regular file")
-                binary = Path(tmp) / "gitleaks"
-                binary.write_bytes(source.read())
-            binary.chmod(0o755)
-            result = subprocess.run(
-                [str(binary), "version"],
-                capture_output=True,
-                text=True,
-                check=False,
-            )
-            self.assertEqual(0, result.returncode, result.stderr)
-            self.assertIn(version, result.stdout + result.stderr)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/integration/test_gateway_image.py

@@ -14,7 +14,9 @@ the chunk-1 contract:
     expected "no daemons selected" line when the supervisor is
     pointed at an empty daemon set.
 
-Skips cleanly only when the selected Docker backend is unavailable.
+Skips cleanly when docker is unavailable, or under act_runner
+where the host bind-mount topology breaks multi-stage builds
+that pull large bases.
 """
 
 from __future__ import annotations
@@ -31,6 +33,12 @@ _DOCKERFILE = "Dockerfile.gateway"
 
 
 @skip_unless_backend("docker")
+@unittest.skipIf(
+    os.environ.get("GITEA_ACTIONS") == "true",
+    "skipped under act_runner: multi-stage build pulls a 200+MB "
+    "mitmproxy base + two upstream gateway images; runner storage "
+    "+ time budget make this an interactive-only test",
+)
 class TestGatewayImage(unittest.TestCase):
     """Builds the image once for the class, then runs a few
     `docker run` probes against it."""
@@ -43,11 +51,10 @@ class TestGatewayImage(unittest.TestCase):
              "-f", _DOCKERFILE, "."],
             cwd=repo_root,
             stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
-            check=False,
         )
         if proc.returncode != 0:
-            raise AssertionError(
-                f"docker build failed; image probes cannot run.\n"
+            raise unittest.SkipTest(
+                f"docker build failed; skipping image probes.\n"
                 f"{proc.stdout.decode('utf-8', errors='replace')[-2000:]}"
             )
 
@@ -56,16 +63,14 @@ class TestGatewayImage(unittest.TestCase):
         subprocess.run(
             ["docker", "image", "rm", "-f", _IMAGE],
             stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
-            check=False,
         )
 
     def _run_in_image(self, *cmd: str, timeout: float = 30.0) -> tuple[int, str]:
         proc = subprocess.run(
             ["docker", "run", "--rm", "--entrypoint", cmd[0], _IMAGE,
-            *cmd[1:]],
+             *cmd[1:]],
             stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
             timeout=timeout,
-            check=False,
         )
         return proc.returncode, proc.stdout.decode("utf-8", errors="replace")
 
@@ -86,9 +91,7 @@ class TestGatewayImage(unittest.TestCase):
         # Probe that the package imports resolve inside the image.
         rc, out = self._run_in_image(
             "python3", "-c",
-            "from bot_bottle.supervisor import types; "
-            "from bot_bottle.gateway.supervisor import server as supervise_server; "
-            "print('ok')",
+            "from bot_bottle.supervisor import types; from bot_bottle.gateway.supervisor import server as supervise_server; print('ok')",
         )
         self.assertEqual(0, rc, msg=out)
         self.assertIn("ok", out)
@@ -103,7 +106,6 @@ class TestGatewayImage(unittest.TestCase):
              _IMAGE],
             stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
             timeout=10.0,
-            check=False,
         )
         out = proc.stdout.decode("utf-8", errors="replace")
         self.assertEqual(0, proc.returncode, msg=out)

tests/integration/test_multitenant_isolation.py

@@ -16,10 +16,11 @@ throwaway BOT_BOTTLE_ROOT for a clean registry and tears everything down.
 
 from __future__ import annotations
 
-import secrets
+import os
 import subprocess
-import time
+import tempfile
 import unittest
+from pathlib import Path
 
 from bot_bottle.backend.docker.consolidated_launch import (
     _network_cidr,
@@ -72,12 +73,19 @@ _PROBE_SRC = (
 
 
 @skip_unless_backend("docker")
+@unittest.skipIf(
+    os.environ.get("GITEA_ACTIONS") == "true",
+    "skipped under act_runner: the orchestrator container bind-mounts the repo "
+    "path into a container on the socket-shared host daemon, which can't see the "
+    "runner's /workspace — same host-bind-mount constraint as the other "
+    "bottle-bringup integration tests",
+)
 class TestMultitenantIsolation(unittest.TestCase):
     def setUp(self) -> None:
-        # Named volume → a clean registry DB that is also visible to a
-        # socket-shared host daemon when the test process runs in act_runner.
-        self._root_volume = "bot-bottle-mtitest-root-" + secrets.token_hex(4)
-        self.svc = DockerInfraService(root_mount_source=self._root_volume)
+        self._tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmp.cleanup)
+        # Throwaway root → a clean registry DB, independent of the host's.
+        self.svc = DockerInfraService(host_root=Path(self._tmp.name))
         self.addCleanup(self._teardown_docker)
         # ensure_running builds the bundle image (slow on a cold cache) and
         # brings up the shared network + gateway + orchestrator.
@@ -92,8 +100,13 @@ class TestMultitenantIsolation(unittest.TestCase):
         self.svc.stop()
         subprocess.run(["docker", "network", "rm", GATEWAY_NETWORK],
                        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False)
+        # The orchestrator container wrote the registry DB as root into the
+        # throwaway root; chown it back so the (non-root) tempdir cleanup can
+        # remove it.
         subprocess.run(
-            ["docker", "volume", "rm", "--force", self._root_volume],
+            ["docker", "run", "--rm", "-v", f"{self._tmp.name}:/r",
+             "--entrypoint", "chown", GATEWAY_IMAGE, "-R",
+             f"{os.getuid()}:{os.getgid()}", "/r"],
             stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False)
 
     @staticmethod
@@ -119,61 +132,29 @@ class TestMultitenantIsolation(unittest.TestCase):
         taken = _network_container_ips(GATEWAY_NETWORK) + extra_taken
         return next_free_ip(_network_cidr(GATEWAY_NETWORK), taken)
 
-    def _probe(self, source_ip: str, identity_token: str, host: str) -> str:
-        deadline = time.monotonic() + 30
-        last = subprocess.CompletedProcess([], 1, "", "probe not attempted")
-        while time.monotonic() < deadline:
-            last = subprocess.run(
-                [
-                    "docker", "run", "--rm",
-                    "--network", GATEWAY_NETWORK, "--ip", source_ip,
-                    "--entrypoint", "python3", GATEWAY_IMAGE, "-c", _PROBE_SRC,
-                    f"http://bottle:{identity_token}@{self.gw_ip}:{EGRESS_PORT}",
-                    host,
-                ],
-                stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
-                check=False, timeout=90,
-            )
-            output = last.stdout.strip()
-            if last.returncode == 0 and output:
-                return output
-            time.sleep(0.25)
-        self.fail(
-            f"gateway probe did not become ready: "
-            f"exit={last.returncode}, stderr={last.stderr.strip()!r}"
+    def _probe(self, source_ip: str, host: str) -> str:
+        proc = subprocess.run(
+            ["docker", "run", "--rm", "--network", GATEWAY_NETWORK, "--ip", source_ip,
+             "--entrypoint", "python3", GATEWAY_IMAGE, "-c", _PROBE_SRC,
+             f"http://{self.gw_ip}:{EGRESS_PORT}", host],
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, check=False, timeout=90,
         )
+        return proc.stdout.strip()
 
     def test_two_bottles_share_gateway_with_isolated_tokens_and_allowlists(self) -> None:
         ip_a = self._free_ip([])
         ip_b = self._free_ip([ip_a])
-        bottle_a = self.client.register_bottle(
-            ip_a, policy=_POLICY_A, tokens={"EGRESS_TOKEN_0": _TOKEN_A}
-        )
-        bottle_b = self.client.register_bottle(
-            ip_b, policy=_POLICY_B, tokens={"EGRESS_TOKEN_0": _TOKEN_B}
-        )
+        self.client.register_bottle(ip_a, policy=_POLICY_A, tokens={"EGRESS_TOKEN_0": _TOKEN_A})
+        self.client.register_bottle(ip_b, policy=_POLICY_B, tokens={"EGRESS_TOKEN_0": _TOKEN_B})
 
         # Each bottle gets its OWN token injected on the shared route — no bleed.
-        self.assertEqual(
-            f"200 AUTH=Bearer {_TOKEN_A}",
-            self._probe(ip_a, bottle_a.identity_token, "echo-shared"),
-        )
-        self.assertEqual(
-            f"200 AUTH=Bearer {_TOKEN_B}",
-            self._probe(ip_b, bottle_b.identity_token, "echo-shared"),
-        )
+        self.assertEqual(f"200 AUTH=Bearer {_TOKEN_A}", self._probe(ip_a, "echo-shared"))
+        self.assertEqual(f"200 AUTH=Bearer {_TOKEN_B}", self._probe(ip_b, "echo-shared"))
 
         # Allowlist is per-bottle: echo-bonly is only in B's policy.
-        self.assertTrue(
-            self._probe(
-                ip_a, bottle_a.identity_token, "echo-bonly"
-            ).startswith("403"),  # fail-closed for A
-            "A reached a host outside its allowlist",
-        )
-        self.assertEqual(
-            "200 AUTH=NONE",
-            self._probe(ip_b, bottle_b.identity_token, "echo-bonly"),
-        )  # allowed, unauthed for B
+        self.assertTrue(self._probe(ip_a, "echo-bonly").startswith("403"),  # fail-closed for A
+                        "A reached a host outside its allowlist")
+        self.assertEqual("200 AUTH=NONE", self._probe(ip_b, "echo-bonly"))  # allowed, unauthed for B
 
 
 if __name__ == "__main__":

tests/integration/test_orchestrator_docker_auth.py

@@ -23,6 +23,7 @@ import secrets
 import subprocess
 import tempfile
 import unittest
+from pathlib import Path
 
 from bot_bottle.orchestrator_auth import ROLE_CLI, ROLE_GATEWAY, mint
 from bot_bottle.orchestrator.client import OrchestratorClient
@@ -37,6 +38,13 @@ _TEST_GATEWAY_IMAGE = "bot-bottle-gateway:itest"
 
 
 @skip_unless_backend("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 TestDockerOrchestratorAuthIntegration(unittest.TestCase):
     @classmethod
     def setUpClass(cls) -> None:
@@ -66,10 +74,10 @@ class TestDockerOrchestratorAuthIntegration(unittest.TestCase):
         gateway_name = f"bot-bottle-gateway-itest-{suffix}"
         network = f"bot-bottle-net-itest-{suffix}"
         control_network = f"bot-bottle-ctrl-itest-{suffix}"
-        root_volume = f"bot-bottle-root-itest-{suffix}"
+        host_root = Path(cls._tmp.name)
         cls.addClassCleanup(
             cls._teardown_docker,
-            orchestrator_name, gateway_name, network, control_network, root_volume,
+            orchestrator_name, gateway_name, network, control_network, host_root,
         )
 
         cls.svc = DockerInfraService(
@@ -80,7 +88,7 @@ class TestDockerOrchestratorAuthIntegration(unittest.TestCase):
             orchestrator_image=_TEST_ORCHESTRATOR_IMAGE,
             gateway_image=_TEST_GATEWAY_IMAGE,
             port=20000 + secrets.randbelow(10000),
-            root_mount_source=root_volume,
+            host_root=host_root,
         )
         cls.svc.ensure_running()
         # The control plane now verifies role-scoped signed tokens, not the raw
@@ -92,7 +100,7 @@ class TestDockerOrchestratorAuthIntegration(unittest.TestCase):
     @staticmethod
     def _teardown_docker(
         orchestrator_name: str, gateway_name: str,
-        network: str, control_network: str, root_volume: str,
+        network: str, control_network: str, host_root: Path,
     ) -> None:
         for name in (gateway_name, orchestrator_name):
             subprocess.run(
@@ -104,8 +112,14 @@ class TestDockerOrchestratorAuthIntegration(unittest.TestCase):
                 ["docker", "network", "rm", net],
                 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
             )
+        # The orchestrator 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", "volume", "rm", "--force", root_volume],
+            ["docker", "run", "--rm", "-v", f"{host_root}:/r",
+             "--entrypoint", "chown", _TEST_ORCHESTRATOR_IMAGE, "-R",
+             f"{os.getuid()}:{os.getgid()}", "/r"],
             stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
         )
 

tests/integration/test_orphan_cleanup.py

@@ -42,6 +42,11 @@ class TestOrphanCleanup(unittest.TestCase):
         # Returning True == idempotent success.
         self.assertTrue(network_remove(f"bot-bottle-net-{self.slug}-does-not-exist"))
 
+    @unittest.skipIf(
+        os.environ.get("GITEA_ACTIONS") == "true",
+        "skipped under act_runner: docker socket mount topology breaks "
+        "in-process visibility of networks created on the host daemon",
+    )
     def test_create_and_remove(self):
         self.internal_name = network_create_internal(self.slug)
         self.egress_name = network_create_egress(self.slug)

tests/integration/test_sandbox_escape.py

@@ -68,6 +68,14 @@ _DUMMY_HOST_KEY = (
 
 
 @skip_unless_selected_backend_available()
+@unittest.skipIf(
+    os.environ.get("GITEA_ACTIONS") == "true"
+    and os.environ.get("BOT_BOTTLE_BACKEND") != "firecracker",
+    "skipped under act_runner unless BOT_BOTTLE_BACKEND=firecracker: "
+    "egress_tls_init uses a host bind mount the runner container can't "
+    "see, and the network topology hides sibling-gateway visibility — "
+    "these constraints don't apply on the self-hosted KVM runner",
+)
 class TestSandboxEscape(unittest.TestCase):
     """End-to-end attacks against a real bottle. The bottle stays
     up for the whole class — bringup is ~10-30s, so per-test
@@ -170,7 +178,7 @@ class TestSandboxEscape(unittest.TestCase):
                 missing.append(tool)
         if missing:
             cls._teardown_resources()
-            raise AssertionError(
+            raise unittest.SkipTest(
                 f"agent missing required tools: {', '.join(missing)} — "
                 f"add them to the backend's base image"
             )

tests/unit/test_architecture_guardrails.py

@@ -1,96 +0,0 @@
-"""Architecture rules that should fail before coupling becomes entrenched."""
-
-from __future__ import annotations
-
-import ast
-import unittest
-from pathlib import Path
-
-
-ROOT = Path(__file__).resolve().parents[2]
-
-
-class TestCliBackendBoundaries(unittest.TestCase):
-    def test_cli_does_not_import_a_concrete_backend(self) -> None:
-        forbidden = (
-            "backend.docker", "backend.firecracker", "backend.macos_container",
-            "bot_bottle.backend.docker", "bot_bottle.backend.firecracker",
-            "bot_bottle.backend.macos_container",
-        )
-        violations: list[str] = []
-        for path in (ROOT / "bot_bottle" / "cli").rglob("*.py"):
-            tree = ast.parse(path.read_text(), filename=str(path))
-            for node in ast.walk(tree):
-                if isinstance(node, ast.ImportFrom):
-                    module = node.module
-                    if module and module.startswith(forbidden):
-                        violations.append(
-                            f"{path.relative_to(ROOT)}:{node.lineno}: {module}"
-                        )
-                if isinstance(node, ast.Import):
-                    violations.extend(
-                        f"{path.relative_to(ROOT)}:{node.lineno}: {alias.name}"
-                        for alias in node.names if alias.name.startswith(forbidden)
-                    )
-        self.assertEqual([], violations, "generic CLI imports concrete backend internals:\n" +
-                         "\n".join(violations))
-
-
-class TestRuntimeModuleSizes(unittest.TestCase):
-    def test_no_runtime_module_grows_beyond_global_ceiling(self) -> None:
-        """A coarse ceiling catches new monoliths; focused caps stay tighter."""
-        ceiling = 850
-        oversized = [
-            f"{path.relative_to(ROOT)} ({len(path.read_text().splitlines())})"
-            for path in (ROOT / "bot_bottle").rglob("*.py")
-            if len(path.read_text().splitlines()) > ceiling
-        ]
-        self.assertEqual(
-            [], oversized,
-            f"runtime modules must stay at or below {ceiling} lines: "
-            + ", ".join(oversized),
-        )
-
-    def test_egress_modules_stay_focused(self) -> None:
-        caps = {
-            "addon_core.py": 100,
-            "schema.py": 400,
-            "types.py": 180,
-            "matching.py": 180,
-            "dlp.py": 180,
-            "context.py": 140,
-        }
-        directory = ROOT / "bot_bottle" / "gateway" / "egress"
-        oversized = [f"{name} ({len((directory / name).read_text().splitlines())}>{cap})"
-                     for name, cap in caps.items()
-                     if len((directory / name).read_text().splitlines()) > cap]
-        self.assertEqual([], oversized, "split a module rather than raising its cap: " +
-                         ", ".join(oversized))
-
-    def test_runtime_code_uses_focused_egress_modules(self) -> None:
-        """addon_core is compatibility-only, never an internal dependency."""
-        violations: list[str] = []
-        package = ROOT / "bot_bottle"
-        facade = package / "gateway" / "egress" / "addon_core.py"
-        package_init = package / "gateway" / "egress" / "__init__.py"
-        for path in package.rglob("*.py"):
-            if path in (facade, package_init):
-                continue
-            text = path.read_text()
-            if "gateway.egress.addon_core import" in text or \
-                    ".addon_core import" in text:
-                violations.append(str(path.relative_to(ROOT)))
-        self.assertEqual([], violations)
-
-    def test_backend_contract_does_not_absorb_preparation_logic(self) -> None:
-        caps = {
-            ROOT / "bot_bottle" / "backend" / "base.py": 580,
-            ROOT / "bot_bottle" / "backend" / "preparation.py": 160,
-        }
-        oversized = [
-            f"{path.relative_to(ROOT)} "
-            f"({len(path.read_text().splitlines())}>{cap})"
-            for path, cap in caps.items()
-            if len(path.read_text().splitlines()) > cap
-        ]
-        self.assertEqual([], oversized)