docs: defer broker replay protection to its own issue (#494 )

Per PR review, replay protection is too heavy for the host control server MVP. Drop it from the four-gap framing (now three gaps), remove the enforcement design section and implementation chunk, and track the iat-window + jti-cache work in #494 as an independent in-process change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
docs: PRD for host-side control server (#468 )
2026-07-26 02:56:34 -04:00 · 2026-07-26 02:56:34 -04:00 · 2026-07-26 02:54:56 -04:00 · 2026-07-26 02:54:56 -04:00 · 2026-07-26 02:54:56 -04:00 · 2026-07-26 02:54:56 -04:00
72 changed files with 2447 additions and 410 deletions
@@ -20,3 +20,9 @@ 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
@@ -0,0 +1,26 @@
+name: prd-number-check
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+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."
@@ -1,122 +0,0 @@
-# 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
@@ -0,0 +1,337 @@
+# 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
+    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: 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
+
+      - 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
@@ -1,21 +1,6 @@
-# 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.
+# 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.

 name: test

@@ -37,6 +22,7 @@ on:
      - 'requirements-dev.txt'
      - '.coveragerc'
      - '.dockerignore'
+      - '.gitea/workflows/test.yml'
  pull_request:
    paths:
      - 'bot_bottle/**'
@@ -52,7 +38,7 @@ on:
      - 'requirements-dev.txt'
      - '.coveragerc'
      - '.dockerignore'
-  workflow_dispatch:
+      - '.gitea/workflows/test.yml'

 jobs:
  unit:
@@ -61,11 +47,6 @@ 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

@@ -79,10 +60,6 @@ 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

@@ -98,17 +75,9 @@ jobs:
      - 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
@@ -120,7 +89,6 @@ jobs:
          COVERAGE_FILE: ${{ github.workspace }}/.coverage.docker
        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

@@ -130,107 +98,10 @@ 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, integration-firecracker]
+    needs: [unit, integration-docker]
    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
@@ -252,55 +123,15 @@ 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 + integration, incl. firecracker)
+      - name: Combined coverage (unit + docker integration)
        run: PYTHON=python3 bash scripts/coverage.sh aggregate critical

      - name: Diff-coverage gate (changed lines >= 90%)
        run: |
          git fetch --no-tags origin main:refs/remotes/origin/main
          python3 scripts/diff_coverage.py --base origin/main --min 90
-
-  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
@@ -17,6 +17,9 @@ __pycache__/
 *.py[cod]
 *$py.class
 *.egg-info/
+# setuptools/build_meta output (wheels, sdists, build tree)
+/build/
+/dist/
 .venv/
 venv/
 .pytest_cache/
@@ -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. 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`) →
+  - **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`) →
    Superseded/Retargeted. Format in `docs/prds/README.md`.
  - **Research notes** (`docs/research/`) — opinionated investigations;
    unnumbered kebab-case, freeform and verdict-first. See
@@ -0,0 +1,8 @@
+# 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
@@ -5,7 +5,7 @@
 # bot-bottle

 [![test](https://gitea.dideric.is/didericis/bot-bottle/actions/workflows/test.yml/badge.svg?branch=main)](https://gitea.dideric.is/didericis/bot-bottle/actions?workflow=test.yml)
-[![coverage](https://img.shields.io/badge/coverage-84%25-brightgreen)](https://coverage.readthedocs.io/)
+[![coverage](https://img.shields.io/badge/coverage-83%25-brightgreen)](https://coverage.readthedocs.io/)
 [![core coverage](https://img.shields.io/badge/core%20coverage-94%25-brightgreen)](https://gitea.dideric.is/didericis/bot-bottle/src/branch/main/docs/decisions/0004-coverage-policy.md)

 **Problem:** Developer wants to run a coding agent without supervision, but they don't want a prompt injected or misbehaving agent wrecking their environment or exfiltrating sensitive data.
@@ -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. `bottle.git` / git-gate is intentionally deferred on this backend until a safe Apple Container key-delivery path exists.
+On the default macOS Apple Container backend, a bottle is an agent container on a host-only internal network plus a gateway attached to both that internal network and a NAT egress network. The agent gets HTTP(S)_PROXY and CA bundle env vars pointing at the gateway's internal-network IP, so HTTP/HTTPS traffic flows through the gateway instead of direct egress. 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 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,6 +75,8 @@ 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 `integration-macos` job (`.gitea/workflows/test.yml`) runs the integration suite against `BOT_BOTTLE_BACKEND=macos-container` on a self-hosted macOS runner labelled `macos`, because Apple Container needs the host virtualization framework and cannot run in a Linux container (so it can't reuse the `kvm` runner). Provision an Apple Silicon host with the `container` CLI on `PATH` and `container system status` running, then register the runner in **host mode** (not docker mode) with the `macos` label — `brew install gitea-runner` (the `act_runner` rename). Give it a Python ≥ 3.11 with `coverage` importable on the launchd service's `PATH` (a launchd service doesn't inherit your shell profile, so pin `node` and the Python env explicitly). The job is **advisory** — `workflow_dispatch` (manual) only, never triggered by push or PR — since a single laptop that sleeps/roams must not block merges or churn on every push to main; its coverage doesn't feed the gate. The infra container is a singleton (`bot-bottle-mac-infra`), so keep runner concurrency at 1.
+
 ### Containers inside a bottle

 A bottle may set `nested_containers: true`. On the macOS backend this starts a
@@ -10,9 +10,10 @@ 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, REPO_ROOT, GATEWAY_LABEL, MITMPROXY_HOME,
+  GATEWAY_DOCKERFILE, GATEWAY_LABEL, MITMPROXY_HOME,
  DEFAULT_CA_TIMEOUT_SECONDS, CA_POLL_SECONDS, GATEWAY_CA_CERT, GatewayError
 )

@@ -50,7 +51,9 @@ class DockerGateway(Gateway):
        # `address` / `stop` work on an already-running gateway without it.
        self._orchestrator_url = ""
        self._gateway_token = ""
-        self._build_context = build_context or REPO_ROOT
+        # Resolved lazily in ensure_built() so merely constructing a gateway to
+        # read its CA never stages a build root from an installed wheel.
+        self._build_context = build_context
        self._dockerfile = dockerfile
        # Ports published on the host (0.0.0.0). Used by the Firecracker
        # backend's dev-harness gateway so VMs can reach it via their TAP link;
@@ -72,9 +75,10 @@ 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(self._build_context / self._dockerfile),
-                str(self._build_context)]
+                "-f", str(context / self._dockerfile),
+                str(context)]
        if os.environ.get("BOT_BOTTLE_NO_CACHE"):
            argv.insert(2, "--no-cache")
        proc = run_docker(argv)
@@ -34,6 +34,7 @@ from .orchestrator import (
    ORCHESTRATOR_NETWORK,
 )
 from ...paths import bot_bottle_root
+from ... import resources
 from ...gateway import (
    GATEWAY_IMAGE,
    GATEWAY_NAME,
@@ -50,8 +51,6 @@ 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.
@@ -68,7 +67,7 @@ class DockerInfraService(InfraService):
        control_network: str = ORCHESTRATOR_NETWORK,
        orchestrator_image: str = ORCHESTRATOR_IMAGE,
        gateway_image: str = GATEWAY_IMAGE,
-        repo_root: Path = _REPO_ROOT,
+        repo_root: Path | None = None,
        host_root: Path | None = None,
        orchestrator_name: str = ORCHESTRATOR_NAME,
        orchestrator_label: str = ORCHESTRATOR_LABEL,
@@ -79,7 +78,9 @@ class DockerInfraService(InfraService):
        self.control_network = control_network
        self.orchestrator_image = orchestrator_image
        self.gateway_image = gateway_image
-        self._repo_root = repo_root
+        # 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._host_root = host_root or bot_bottle_root()
        self._orchestrator_name = orchestrator_name
        self._orchestrator_label = orchestrator_label
@@ -33,7 +33,6 @@ 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
@@ -65,10 +64,7 @@ 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
-
-
-# Where the repo root lives, for `docker build` context. Computed once.
-_REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)
+from ... import resources


 def build_or_load_images(plan: DockerBottlePlan) -> BottleImages:
@@ -88,7 +84,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, _REPO_DIR, dockerfile=plan.dockerfile_path)
+    docker_mod.build_image(plan.image, str(resources.build_root()), dockerfile=plan.dockerfile_path)
    docker_mod.verify_agent_image(
        plan.image, runtime_for(plan.agent_provider_template).smoke_test,
    )
@@ -15,6 +15,7 @@ import time
 from pathlib import Path

 from ... import log
+from ... import resources
 from .util import run_docker
 from ...paths import (
    ORCHESTRATOR_TOKEN_ENV,
@@ -55,8 +56,6 @@ _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
@@ -71,7 +70,7 @@ class DockerOrchestrator(Orchestrator):
        label: str = ORCHESTRATOR_LABEL,
        port: int = DEFAULT_PORT,
        control_network: str = ORCHESTRATOR_NETWORK,
-        repo_root: Path = _REPO_ROOT,
+        repo_root: Path | None = None,
        host_root: Path | None = None,
        dockerfile: str | None = ORCHESTRATOR_DOCKERFILE,
    ) -> None:
@@ -80,7 +79,9 @@ class DockerOrchestrator(Orchestrator):
        self.label = label
        self.port = port
        self.control_network = control_network
-        self._repo_root = repo_root
+        # 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._host_root = host_root or bot_bottle_root()
        self._dockerfile = dockerfile

@@ -37,6 +37,7 @@ import urllib.error
 import urllib.request
 from pathlib import Path

+from ... import resources
 from ...log import die, info
 from . import util

@@ -44,8 +45,6 @@ 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.
@@ -74,7 +73,7 @@ def local_build_requested() -> bool:


 def infra_artifact_version(
-    init_script: str, role: str, *, repo_root: Path = _REPO_ROOT,
+    init_script: str, role: str, *, repo_root: Path | None = None,
 ) -> str:
    """Content hash (16 hex) of everything baked into `role`'s infra rootfs: the
    whole shipped `bot_bottle` package, that role's Dockerfiles, and its guest
@@ -89,6 +88,8 @@ 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"
@@ -42,6 +42,7 @@ 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
@@ -65,7 +66,6 @@ _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,12 +130,13 @@ 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, str(_REPO_ROOT), dockerfile="Dockerfile.orchestrator")
+        _ORCHESTRATOR_IMAGE, root, dockerfile="Dockerfile.orchestrator")
    docker_mod.build_image(
-        _GATEWAY_IMAGE, str(_REPO_ROOT), dockerfile="Dockerfile.gateway")
+        _GATEWAY_IMAGE, root, dockerfile="Dockerfile.gateway")
    docker_mod.build_image(
-        _ORCHESTRATOR_FC_IMAGE, str(_REPO_ROOT), dockerfile="Dockerfile.orchestrator.fc")
+        _ORCHESTRATOR_FC_IMAGE, root, dockerfile="Dockerfile.orchestrator.fc")


 def build_rootfs_dir(role: str) -> Path:
@@ -20,6 +20,7 @@ import subprocess
 import sys
 from pathlib import Path

+from ... import resources
 from . import netpool
 from . import util

@@ -42,13 +43,13 @@ def _has_systemd() -> bool:


 def _module_path() -> str:
-    """Absolute path to the importable NixOS module in this checkout."""
-    return str(Path(__file__).resolve().parents[3] / "nix" / "firecracker-netpool.nix")
+    """Absolute path to the importable NixOS module (checkout or wheel)."""
+    return str(resources.nix_netpool_module())


 def _script_path() -> str:
-    """Absolute path to the bundled bring-up script in this checkout."""
-    return str(Path(__file__).resolve().parents[3] / "scripts" / "firecracker-netpool.sh")
+    """Absolute path to the bundled bring-up script (checkout or wheel)."""
+    return str(resources.netpool_script())


 def _print_prereqs() -> None:
@@ -28,6 +28,7 @@ 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

@@ -52,8 +53,6 @@ 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,
@@ -84,14 +83,16 @@ class MacosGateway(Gateway):
        network: str = GATEWAY_NETWORK,
        egress_network: str = GATEWAY_EGRESS_NETWORK,
        control_network: str = CONTROL_NETWORK,
-        repo_root: Path = _REPO_ROOT,
+        repo_root: Path | None = None,
    ) -> None:
        self.image_ref = image_ref
        self.name = name
        self.network = network
        self.egress_network = egress_network
        self.control_network = control_network
-        self._repo_root = repo_root
+        # Build context: the repo root in a checkout, a staged copy from the
+        # installed wheel otherwise (bot_bottle.resources).
+        self._repo_root = repo_root if repo_root is not None else resources.build_root()
        # Set by `connect_to_orchestrator`: the URL the daemons resolve policy
        # against + the pre-minted `gateway` token they present. The gateway
        # never mints, so it never holds the signing key (#469).
@@ -24,6 +24,7 @@ from __future__ import annotations

 from pathlib import Path

+from ... import resources
 from ...orchestrator.lifecycle import (
    DEFAULT_PORT,
    DEFAULT_STARTUP_TIMEOUT_SECONDS,
@@ -53,8 +54,6 @@ 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
@@ -70,7 +69,7 @@ class MacosInfraService(InfraService):
        control_network: str = CONTROL_NETWORK,
        gateway_image: str = GATEWAY_IMAGE,
        orchestrator_image: str = ORCHESTRATOR_IMAGE,
-        repo_root: Path = _REPO_ROOT,
+        repo_root: Path | None = None,
        orchestrator_name: str = ORCHESTRATOR_NAME,
        gateway_name: str = INFRA_NAME,
        db_volume: str = ORCHESTRATOR_DB_VOLUME,
@@ -81,7 +80,9 @@ class MacosInfraService(InfraService):
        self.control_network = control_network
        self.gateway_image = gateway_image
        self.orchestrator_image = orchestrator_image
-        self._repo_root = repo_root
+        # Build context / bind-mount source: the repo root in a checkout, a
+        # staged copy from the installed wheel otherwise (bot_bottle.resources).
+        self._repo_root = repo_root if repo_root is not None else resources.build_root()
        self._orchestrator_name = orchestrator_name
        self._gateway_name = gateway_name
        self._db_volume = db_volume
@@ -36,7 +36,6 @@ import dataclasses
 import os
 import subprocess
 from contextlib import ExitStack, contextmanager
-from pathlib import Path
 from typing import Callable, Generator

 from ...bottle_state import (
@@ -49,6 +48,7 @@ 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,7 +71,6 @@ from .consolidated_launch import (
    deprovision_consolidated,
 )

-_REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)
 _AGENT_SLEEP_SECONDS = "2147483647"


@@ -94,7 +93,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, _REPO_DIR, dockerfile=plan.dockerfile_path)
+    container_mod.build_image(plan.image, str(resources.build_root()), dockerfile=plan.dockerfile_path)
    return plan.image


@@ -18,6 +18,7 @@ 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,
@@ -45,7 +46,6 @@ _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 = _REPO_ROOT,
+        repo_root: Path | None = None,
        db_volume: str = ORCHESTRATOR_DB_VOLUME,
    ) -> None:
        self.image_ref = image_ref
@@ -69,7 +69,9 @@ class MacosOrchestrator(Orchestrator):
        self.label = label
        self.port = port
        self.control_network = control_network
-        self._repo_root = repo_root
+        # Build context / bind-mount source: the repo root in a checkout, a
+        # staged copy from the installed wheel otherwise (bot_bottle.resources).
+        self._repo_root = repo_root if repo_root is not None else resources.build_root()
        self._db_volume = db_volume

    def url(self) -> str:
@@ -21,6 +21,7 @@ _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",
@@ -53,6 +54,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", "help", "login"})
+NO_MIGRATION_COMMANDS = frozenset({"backend", "doctor", "help", "login"})

 __all__ = ["COMMANDS", "NO_MIGRATION_COMMANDS"]
@@ -0,0 +1,88 @@
+"""`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
@@ -25,6 +25,7 @@ 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")
@@ -62,7 +62,6 @@ 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]:
@@ -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 prd-new / issue #412).
+     non-blocking past the grace window (PRD 0072 / issue #412).

 `check-proposal` is the non-blocking companion: given a `proposal_id`
 returned by a `pending` response, it reports the current decision
@@ -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 prd-new-secret-provider).
+        # v4 — per-bottle encrypted egress secrets (PRD 0080).
        # 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
@@ -1,4 +1,4 @@
-"""Symmetric encryption for per-bottle egress secrets (PRD prd-new-secret-provider).
+"""Symmetric encryption for per-bottle egress secrets (PRD 0080).

 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
@@ -0,0 +1,159 @@
+"""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
@@ -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/prd-new-control-plane-auth-provisioning.md`).
+`docs/prds/0079-control-plane-auth-provisioning.md`).

 Stdlib-only: the HMAC lives in `orchestrator_auth`, the key file in `paths`.
 """
@@ -7,6 +7,7 @@ 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. |
@@ -2,11 +2,22 @@

 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:
+(`integration-docker`, `integration-firecracker`, `integration-macos`) on:

 - every push to a branch with an open pull request, and
 - every push to `main`.

+`integration-macos` is the exception: it is **advisory**, running only on
+`workflow_dispatch` (manual dispatch), never on push or pull requests. It targets the
+Apple Container backend on a self-hosted macOS runner (label `macos`,
+registered in host mode — Apple Container can't run in a Linux container, so it
+can't reuse the `kvm` runner). A single non-redundant laptop must not be able
+to block a PR merge, so the job stays out of the `coverage` job's `needs` and
+its coverage never feeds the diff-coverage gate. Because the infra container is
+a singleton (`bot-bottle-mac-infra`), the job declares a `concurrency` group
+and tears the container down on exit; keep runner concurrency at 1. See the
+README "macOS Apple Container" CI note for runner provisioning.
+
 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
@@ -1,9 +1,13 @@
-# ADR 0005: Keep tracker metadata on issues
+# ADR 0005: Keep tracker metadata on one tracker object

 - **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
@@ -20,19 +24,29 @@ would make the issue history less truthful.

 ## Decision

-Issues are the canonical tracker records and own labels. Every issue has at
-least one label. An issue opened or left without labels receives
-`Status/Needs Triage` automatically until it is classified.
+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.

-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:
+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:

 - `Closes #123`, `Fixes #123`, or `Resolves #123` when merging completes it.
 - `Part of #123`, `Related to #123`, `Refs #123`, or `References #123` when it
  contributes without completing it.

-Gitea Actions enforces both PR rules as a status check and repairs the empty
-issue-label state. Branch protection makes the PR policy check required.
+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.

 The policy applies from 2026-07-18 onward. Existing issues may be labelled as
 they are encountered, but closed PRs are grandfathered: no retrospective
@@ -40,9 +54,13 @@ issues or PR labels are created solely to make history conform.

 ## Consequences

- Classification, priority, and workflow metadata have one source of truth.
- A PR's issue link is the navigation path to its planning metadata.
+- 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.
 - 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
@@ -53,5 +71,6 @@ issues or PR labels are created solely to make history conform.
 ## Links

 - Issue #405.
- `.gitea/workflows/tracker-policy.yml`.
+- `.gitea/workflows/tracker-policy-pr.yml`.
+- `.gitea/workflows/tracker-policy-issues.yml`.
 - `scripts/tracker_policy.py`.
@@ -0,0 +1,218 @@
+# 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.**
@@ -1,9 +1,14 @@
 # PRD 0001: Per-agent egress proxy via pipelock

- **Status:** Active
+- **Status:** Superseded by [PRD 0017](0017-egress-proxy-via-mitmproxy.md)
+  and [PRD 0052](0052-egress-dlp-addon.md)
 - **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
@@ -1,9 +1,14 @@
 # PRD 0006: pipelock native TLS interception

- **Status:** Active
+- **Status:** Superseded by [PRD 0017](0017-egress-proxy-via-mitmproxy.md)
+  and [PRD 0052](0052-egress-dlp-addon.md)
 - **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 /
@@ -1,11 +1,17 @@
 # PRD 0015: pipelock block remediation

- **Status:** Active
+- **Status:** Superseded by [PRD 0017](0017-egress-proxy-via-mitmproxy.md)
+  and [PRD 0052](0052-egress-dlp-addon.md)
 - **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.
@@ -4,6 +4,11 @@
 - **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
@@ -4,6 +4,11 @@
 - **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
@@ -4,6 +4,11 @@
 - **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
@@ -1,9 +1,13 @@
 # PRD 0024: Consolidate per-bottle sidecars into a single bundle

- **Status:** Active
+- **Status:** Superseded by [PRD 0070](0070-per-host-orchestrator.md)
 - **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
@@ -1,10 +1,16 @@
 # PRD 0037: Pipelock YAML Render Contract

- **Status:** Active
+- **Status:** Superseded by [PRD 0017](0017-egress-proxy-via-mitmproxy.md)
+  and [PRD 0052](0052-egress-dlp-addon.md)
 - **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
@@ -1,10 +1,17 @@
 # PRD 0067: SQLite local storage

- **Status:** Active
+- **Status:** Retargeted by [PRD 0070](0070-per-host-orchestrator.md) and
+  issues #469/#471
 - **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,
@@ -1,6 +1,6 @@
 # PRD 0069: Firecracker-native, Docker-free backend

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

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

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

- **Status:** Draft
+- **Status:** Active
 - **Author:** didericis
 - **Created:** 2026-07-18
 - **Issue:** #412
@@ -1,4 +1,4 @@
-# PRD prd-new: Consolidate infra backend for Docker
+# PRD 0073: Consolidate infra backend for Docker

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

 - **Status:** Active
 - **Author:** Claude
@@ -1,6 +1,6 @@
-# PRD prd-new: Containers inside a bottle
+# PRD 0075: Containers inside a bottle

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

- **Status:** Draft
+- **Status:** Active
 - **Author:** Codex
 - **Created:** 2026-07-21
 - **Issue:** #451
@@ -0,0 +1,142 @@
+# 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.
@@ -0,0 +1,172 @@
+# 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.
@@ -1,6 +1,6 @@
-# PRD prd-new: Per-service signing keys for control-plane auth
+# PRD 0079: Per-service signing keys for control-plane auth

- **Status:** Draft
+- **Status:** Active
 - **Author:** claude
 - **Created:** 2026-07-26
 - **Issue:** #476
@@ -1,4 +1,4 @@
-# PRD prd-new: Encrypted at-rest egress secrets (SecretProvider, interim slice)
+# PRD 0080: Encrypted at-rest egress secrets (SecretProvider, interim slice)

 - **Status:** Draft
 - **Author:** didericis
@@ -7,10 +7,13 @@ document vs. a research note or a decision record).

 ## Naming and numbering

-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.
+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.

 Once numbered, the filename stays fixed for the life of the doc.

@@ -26,7 +29,7 @@ The `Status:` line near the top tracks the PRD's lifecycle:
 ## Format

 ```markdown
-# PRD prd-new: <short title>    ← placeholder; CI fills in the number on merge
+# PRD prd-new: <short title>    ← replace with the final number before merge

 - **Status:** Draft
 - **Author:** <who>
@@ -0,0 +1,273 @@
+# 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.
@@ -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/prd-new-nested-containers.md`](../prds/prd-new-nested-containers.md).
+[`docs/prds/0075-nested-containers.md`](../prds/0075-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.

@@ -0,0 +1,123 @@
+#!/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
@@ -4,5 +4,42 @@ build-backend = "setuptools.build_meta"

 [project]
 name = "bot-bottle"
-version = "0.0.0"
+version = "0.1.0"
+description = "Self-hosted sandbox for running AI coding agents with egress controls"
+readme = "README.md"
 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",
+]
@@ -5,3 +5,6 @@
 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
@@ -54,18 +54,20 @@ def check_pull_request(event: dict[str, Any], api: GiteaApi) -> list[str]:
    pull = event["pull_request"]
    errors: list[str] = []
    labels = pull.get("labels") or []
-    if labels:
-        errors.append(
-            "PRs must be unlabeled; put tracker metadata on the linked issue "
-            f"(found: {', '.join(label['name'] for label in labels)})."
-        )
-
    numbers = deliberate_issue_numbers(pull.get("title", ""), pull.get("body", ""))
-    if not numbers:
+    if labels and numbers:
        errors.append(
-            "PR must reference an issue with Closes/Fixes/Resolves #N, "
-            "Part of #N, Related to #N, Refs #N, or References #N."
+            "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."
        )
+    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."
+            )
        return errors

    real_issues = 0
@@ -0,0 +1,46 @@
+"""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})
@@ -67,14 +67,25 @@ _DUMMY_HOST_KEY = (
 )


+# Backends whose CI runner is HOST-mode (self-hosted), so the test process
+# and the backend share a host. The containerized act_runner (docker on
+# ubuntu-latest) is the one that can't see the host bind mount egress_tls_init
+# uses and hides sibling-gateway network topology; host-mode runners
+# (firecracker/KVM, macos-container) don't have those constraints, so the test
+# runs there. Keep this in sync with the `runs-on` labels in
+# .gitea/workflows/test.yml.
+_HOST_MODE_CI_BACKENDS = frozenset({"firecracker", "macos-container"})
+
+
@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: "
+    and os.environ.get("BOT_BOTTLE_BACKEND") not in _HOST_MODE_CI_BACKENDS,
+    "skipped under the containerized act_runner (docker on ubuntu-latest): "
    "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",
+    "these constraints don't apply on the self-hosted host-mode runners "
+    "(firecracker/KVM, macos-container)",
 )
 class TestSandboxEscape(unittest.TestCase):
    """End-to-end attacks against a real bottle. The bottle stays
@@ -0,0 +1,98 @@
+"""Unit: `bot-bottle doctor` host prerequisite checks (ADR 0004).
+
+`doctor` is a store-free diagnostic — it must run on a fresh install
+before any DB migration, and its exit code gates only the two hard
+prerequisites (Python and at least one *ready* backend). The config-dir
+check is advisory and never affects the exit code.
+
+Backend readiness is probed with `is_backend_ready()` (a full status()
+check), not the cheap PATH-only `is_backend_available()` — a host with a
+stopped daemon or half-configured backend must not report `ok`.
+"""
+
+from __future__ import annotations
+
+import io
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest.mock import patch
+
+from bot_bottle.cli.commands import doctor
+
+
+def _run(argv: list[str] | None = None) -> tuple[int, str]:
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        code = doctor.cmd_doctor(argv or [])
+    return code, buf.getvalue()
+
+
+class TestDoctor(unittest.TestCase):
+    def test_passes_when_python_and_backend_ready(self):
+        with patch.object(doctor, "known_backend_names", return_value=("docker",)), \
+                patch.object(doctor, "is_backend_ready", return_value=True):
+            code, out = _run()
+        self.assertEqual(0, code)
+        self.assertIn("ok:   python", out)
+        self.assertIn("ok:   backend: docker: ready", out)
+
+    def test_fails_when_no_backend_ready(self):
+        # The regression the reviewer flagged: a backend whose binary is on PATH
+        # but whose daemon/pool isn't ready must NOT pass. is_backend_ready is
+        # the full status() check, so returning False here means "not ready".
+        with patch.object(doctor, "known_backend_names", return_value=("docker", "firecracker")), \
+                patch.object(doctor, "is_backend_ready", return_value=False):
+            code, out = _run()
+        self.assertEqual(1, code)
+        self.assertIn("fail: backend", out)
+        self.assertIn("warn: backend: docker: not ready", out)
+
+    def test_passes_when_at_least_one_backend_ready(self):
+        # docker not ready, firecracker ready → overall pass, mixed report.
+        def ready(name: str, *, quiet: bool = False) -> bool:
+            del quiet
+            return name == "firecracker"
+
+        with patch.object(doctor, "known_backend_names", return_value=("docker", "firecracker")), \
+                patch.object(doctor, "is_backend_ready", side_effect=ready):
+            code, out = _run()
+        self.assertEqual(0, code)
+        self.assertIn("warn: backend: docker: not ready", out)
+        self.assertIn("ok:   backend: firecracker: ready", out)
+
+    def test_fails_when_python_too_old(self):
+        # Force the version gate to fail without touching the interpreter.
+        with patch.object(doctor, "MIN_PYTHON", (99, 0)), \
+                patch.object(doctor, "known_backend_names", return_value=("docker",)), \
+                patch.object(doctor, "is_backend_ready", return_value=True):
+            code, out = _run()
+        self.assertEqual(1, code)
+        self.assertIn("fail: python", out)
+
+    def test_missing_config_dir_is_advisory_not_fatal(self):
+        # A missing ~/.bot-bottle warns but must not fail. Point home at a
+        # fresh empty dir so the shared suite HOME (which other tests may
+        # populate) can't turn this into an "ok: config".
+        with tempfile.TemporaryDirectory() as tmp, \
+                patch.object(doctor.Path, "home", return_value=Path(tmp)), \
+                patch.object(doctor, "known_backend_names", return_value=("docker",)), \
+                patch.object(doctor, "is_backend_ready", return_value=True):
+            code, out = _run()
+        self.assertEqual(0, code)
+        self.assertIn("warn: config", out)
+
+    def test_present_config_dir_reports_ok(self):
+        with tempfile.TemporaryDirectory() as tmp, \
+                patch.object(doctor.Path, "home", return_value=Path(tmp)), \
+                patch.object(doctor, "known_backend_names", return_value=("docker",)), \
+                patch.object(doctor, "is_backend_ready", return_value=True):
+            (Path(tmp) / ".bot-bottle").mkdir()
+            code, out = _run()
+        self.assertEqual(0, code)
+        self.assertIn("ok:   config", out)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,101 @@
+"""Unit: install.sh bootstrapper contract.
+
+The installer is a thin, sudo-free, idempotent bootstrapper. These are
+static checks on the script text (no network / no real install) so CI can
+run them anywhere: it must be executable, fail-fast, never call sudo,
+create the config tree, install the package, and verify with `doctor`.
+"""
+
+from __future__ import annotations
+
+import os
+import sysconfig
+import unittest
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+INSTALL_SH = REPO_ROOT / "install.sh"
+
+
+class TestInstallScript(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.text = INSTALL_SH.read_text()
+
+    def test_exists_and_executable(self):
+        self.assertTrue(INSTALL_SH.is_file())
+        self.assertTrue(os.access(INSTALL_SH, os.X_OK), "install.sh must be executable")
+
+    def test_posix_shebang_and_failfast(self):
+        first = self.text.splitlines()[0]
+        self.assertEqual("#!/bin/sh", first)
+        self.assertIn("set -eu", self.text)
+
+    def test_never_uses_sudo(self):
+        # Only executable lines matter; the header comment may mention sudo.
+        code = [
+            ln for ln in self.text.splitlines()
+            if ln.strip() and not ln.lstrip().startswith("#")
+        ]
+        self.assertNotIn("sudo", "\n".join(code))
+
+    def test_creates_config_tree(self):
+        self.assertIn(".bot-bottle/agents", self.text)
+        self.assertIn(".bot-bottle/bottles", self.text)
+
+    def test_installs_via_pipx_with_pip_fallback(self):
+        self.assertIn("pipx install", self.text)
+        self.assertIn("pip install --user", self.text)
+
+    def test_runs_doctor_after_install(self):
+        self.assertIn("doctor", self.text)
+
+    def test_install_spec_is_overridable(self):
+        # Tests / local installs point BOT_BOTTLE_INSTALL_SPEC at a checkout.
+        self.assertIn("BOT_BOTTLE_INSTALL_SPEC", self.text)
+
+    def test_requires_git_for_git_specs(self):
+        # A git+ / .git spec (the default) shells out to git; the script must
+        # gate on it rather than failing opaquely inside pipx/pip.
+        self.assertIn("command -v git", self.text)
+        self.assertIn("git+*|*.git", self.text)
+
+    def test_checks_pip_usable_before_fallback(self):
+        self.assertIn("python3 -m pip --version", self.text)
+
+    def test_detects_externally_managed_python(self):
+        # PEP 668: 'pip install --user' is blocked on externally-managed
+        # interpreters; the script must detect this and point at pipx.
+        self.assertIn("EXTERNALLY-MANAGED", self.text)
+        self.assertIn("pipx", self.text)
+
+    def test_resolves_user_scripts_dir_not_hardcoded(self):
+        # The pip --user scripts dir differs by platform; the script must ask
+        # the interpreter (sysconfig + the preferred *user* scheme) rather than
+        # hardcoding Linux's ~/.local/bin (which is wrong on macOS python.org).
+        self.assertIn("get_preferred_scheme", self.text)
+        self.assertIn("sysconfig", self.text)
+        # No hardcoded Linux path in executable lines (a comment may mention it).
+        code = "\n".join(
+            ln for ln in self.text.splitlines()
+            if ln.strip() and not ln.lstrip().startswith("#")
+        )
+        self.assertNotIn(".local/bin", code)
+
+    def test_macos_user_scheme_is_not_dot_local_bin(self):
+        # The case the fix exists for: a python.org macOS interpreter uses the
+        # osx_framework_user scheme, whose scripts land under
+        # ~/Library/Python/<X.Y>/bin — NOT ~/.local/bin. Drive the same
+        # sysconfig lookup install.sh uses, with a mac-like userbase, to prove
+        # it resolves a non-~/.local/bin directory.
+        self.assertIn("osx_framework_user", sysconfig.get_scheme_names())
+        scripts = sysconfig.get_path(
+            "scripts", "osx_framework_user",
+            vars={"userbase": "/Users/dev/Library/Python/3.11"},
+        )
+        self.assertEqual("/Users/dev/Library/Python/3.11/bin", scripts)
+        self.assertNotIn("/.local/bin", scripts)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -283,7 +283,7 @@ class TestBuildOrLoadImages(unittest.TestCase):
            images = launch_mod.build_or_load_images(plan)

        build.assert_called_once_with(
-            "agent:base", launch_mod._REPO_DIR,  # pylint: disable=protected-access
+            "agent:base", str(launch_mod.resources.build_root()),
            dockerfile="/repo/Dockerfile",
        )
        derived.assert_called_once_with("agent:base", build)
@@ -1,4 +1,4 @@
-"""Unit tests for per-bottle egress secret encryption (PRD prd-new-secret-provider)."""
+"""Unit tests for per-bottle egress secret encryption (PRD 0080)."""

 from __future__ import annotations

@@ -0,0 +1,45 @@
+"""Unit: pyproject.toml packaging contract.
+
+Guards the install/distribution surface: the console-script entry point,
+the stdlib-only (empty) dependency list, and that every package-data glob
+still points at a file that exists (so an installed wheel isn't missing a
+Dockerfile or entrypoint the runtime reads).
+"""
+
+from __future__ import annotations
+
+import tomllib
+import unittest
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+PYPROJECT = REPO_ROOT / "pyproject.toml"
+
+
+class TestPyproject(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        with PYPROJECT.open("rb") as fh:
+            cls.data = tomllib.load(fh)
+
+    def test_entry_point_targets_cli_main(self):
+        scripts = self.data["project"]["scripts"]
+        self.assertEqual("bot_bottle.cli:main", scripts["bot-bottle"])
+
+    def test_no_runtime_dependencies(self):
+        # AGENTS.md: the package has no runtime pip dependencies.
+        self.assertEqual([], self.data["project"]["dependencies"])
+
+    def test_requires_python_311(self):
+        self.assertEqual(">=3.11", self.data["project"]["requires-python"])
+
+    def test_package_data_files_exist(self):
+        pkg_data = self.data["tool"]["setuptools"]["package-data"]["bot_bottle"]
+        self.assertTrue(pkg_data, "expected package-data entries")
+        for rel in pkg_data:
+            path = REPO_ROOT / "bot_bottle" / rel
+            self.assertTrue(path.is_file(), f"package-data missing: {path}")
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,184 @@
+"""Unit: bot_bottle.resources — build-resource resolution for both a source
+checkout and an installed wheel.
+
+The checkout path is what the whole test suite already runs under; the wheel
+path is exercised here by faking an installed layout (a package dir with a
+bundled ``_resources/`` and no sibling Dockerfiles) and asserting that
+``build_root()`` stages a repo-root-shaped context. See
+``test_wheel_install.py`` for the end-to-end build+install check.
+"""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from contextlib import contextmanager
+from pathlib import Path
+from unittest.mock import patch
+
+from bot_bottle import resources
+
+from tests.unit import use_bottle_root
+
+
+class TestCheckoutMode(unittest.TestCase):
+    """The environment the suite runs in: a real source checkout."""
+
+    def test_is_source_checkout(self):
+        self.assertTrue(resources.is_source_checkout())
+
+    def test_build_root_is_repo_root(self):
+        root = resources.build_root()
+        self.assertTrue((root / "bot_bottle").is_dir())
+        self.assertTrue((root / "pyproject.toml").is_file())
+        self.assertTrue((root / "Dockerfile.gateway").is_file())
+
+    def test_resource_helpers_resolve(self):
+        self.assertTrue(resources.dockerfile("Dockerfile.gateway").is_file())
+        self.assertTrue(resources.nix_netpool_module().is_file())
+        self.assertTrue(resources.netpool_script().is_file())
+
+    def test_bundled_resources_all_exist_at_root(self):
+        # Drift guard: every path setup.py bundles must exist in the checkout.
+        root = resources.build_root()
+        for rel in resources.BUNDLED_RESOURCES:
+            self.assertTrue((root / rel).is_file(), f"missing bundled resource: {rel}")
+
+
+class TestWheelMode(unittest.TestCase):
+    """Fake an installed wheel: a package dir with _resources/ and no
+    checkout Dockerfiles beside it."""
+
+    def _fake_install(self, tmp: Path) -> Path:
+        pkg = tmp / "site-packages" / "bot_bottle"
+        (pkg / "cli").mkdir(parents=True)
+        (pkg / "__init__.py").write_text("")
+        (pkg / "cli" / "__init__.py").write_text("# module\n")
+        bundled = pkg / "_resources"
+        for rel in resources.BUNDLED_RESOURCES:
+            dst = bundled / rel
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            dst.write_text(f"# fake {rel}\n")
+        return pkg
+
+    @contextmanager
+    def _wheel(self):
+        """Point `resources` at a fake installed wheel with an isolated
+        app-data dir; yields the package dir so a test can mutate it."""
+        with tempfile.TemporaryDirectory() as tmpname:
+            tmp = Path(tmpname)
+            pkg = self._fake_install(tmp)
+            self.addCleanup(use_bottle_root(tmp / "appdata"))
+            with patch.object(resources, "_PKG", pkg), \
+                    patch.object(resources, "_BUNDLED", pkg / "_resources"), \
+                    patch.object(resources, "_CHECKOUT_ROOT", tmp / "no-checkout"):
+                yield pkg
+
+    def test_stage_and_resolve(self):
+        with self._wheel():
+            self.assertFalse(resources.is_source_checkout())
+            root = resources.build_root()
+            # Staged context looks like a repo root.
+            self.assertTrue((root / "bot_bottle" / "__init__.py").is_file())
+            self.assertTrue((root / "bot_bottle" / "cli" / "__init__.py").is_file())
+            self.assertTrue((root / "pyproject.toml").is_file())
+            self.assertTrue((root / "Dockerfile.gateway").is_file())
+            self.assertTrue((root / "nix" / "firecracker-netpool.nix").is_file())
+            self.assertTrue((root / "scripts" / "firecracker-netpool.sh").is_file())
+            # The bundled-resource copies are NOT re-nested under the staged
+            # package (keeps it byte-identical to a checkout package).
+            self.assertFalse((root / "bot_bottle" / "_resources").exists())
+            # Helpers resolve off the staged root.
+            self.assertEqual(root / "Dockerfile.gateway",
+                             resources.dockerfile("Dockerfile.gateway"))
+            # Idempotent: second call returns the same completed dir.
+            self.assertEqual(root, resources.build_root())
+
+    def test_refreshes_when_content_changes_at_same_version(self):
+        # Regression for the stale-cache bug: `pipx install --force` of a newer
+        # commit keeps version 0.1.0, so keying on version would reuse the old
+        # tree. Keying on content must re-stage when a package file changes.
+        with self._wheel() as pkg:
+            root1 = resources.build_root()
+            self.assertTrue((root1 / ".complete").is_file())
+            (pkg / "cli" / "__init__.py").write_text("# new commit, same version\n")
+            root2 = resources.build_root()
+            self.assertNotEqual(root1, root2)
+            self.assertEqual(
+                "# new commit, same version\n",
+                (root2 / "bot_bottle" / "cli" / "__init__.py").read_text(),
+            )
+
+    def test_failed_stage_cleans_up_temp_dir(self):
+        # A failure mid-stage must not leave a half-written temp dir behind.
+        with self._wheel():
+            base = resources.bot_bottle_root() / "build-root"
+            with patch.object(resources.shutil, "copytree", side_effect=OSError("boom")):
+                with self.assertRaises(OSError):
+                    resources.build_root()
+            self.assertEqual([], list(base.glob(".staging-*")))
+
+    def test_rebuilds_when_stage_incomplete(self):
+        # A crash mid-stage can leave a dir without its `.complete` marker; the
+        # next call must rebuild it rather than trust the partial tree.
+        with self._wheel():
+            root = resources.build_root()
+            (root / ".complete").unlink()
+            (root / "sentinel").write_text("stale")
+            again = resources.build_root()
+            self.assertEqual(root, again)  # same content digest → same dir
+            self.assertTrue((again / ".complete").is_file())
+            self.assertFalse((again / "sentinel").exists())  # rebuilt clean
+
+    def test_reuses_peer_stage_after_lock_wait(self):
+        # Regression for the staging race: a caller that loses the lock must,
+        # once it wins, see the peer's completed tree and reuse it — never
+        # re-clobber a shared path. Drive it deterministically: hold the lock,
+        # let a worker block after its fast-path miss, publish a complete tree
+        # as the "peer", then release so the worker takes the reuse path.
+        import fcntl
+        import threading
+        import time
+
+        with self._wheel():
+            base = resources.bot_bottle_root() / "build-root"
+            base.mkdir(parents=True, exist_ok=True)
+            dest = base / resources._content_digest()  # pylint: disable=protected-access
+
+            result: dict[str, Path] = {}
+            with open(base / ".stage.lock", "w", encoding="utf-8") as held:
+                fcntl.flock(held, fcntl.LOCK_EX)
+
+                def worker() -> None:
+                    result["root"] = resources.build_root()
+
+                t = threading.Thread(target=worker)
+                t.start()
+                # Let the worker miss the fast path (dest not yet complete) and
+                # block on the held lock, then publish a complete tree as a peer
+                # would have and release the lock.
+                time.sleep(0.3)
+                dest.mkdir(parents=True)
+                (dest / ".complete").write_text("")
+                fcntl.flock(held, fcntl.LOCK_UN)
+                t.join(timeout=10)
+
+            self.assertEqual(dest, result["root"])
+            self.assertFalse(t.is_alive())
+
+    def test_missing_bundle_raises(self):
+        with tempfile.TemporaryDirectory() as tmpname:
+            tmp = Path(tmpname)
+            pkg = tmp / "bot_bottle"
+            pkg.mkdir()
+            restore = use_bottle_root(tmp / "appdata")
+            self.addCleanup(restore)
+            with patch.object(resources, "_PKG", pkg), \
+                    patch.object(resources, "_BUNDLED", pkg / "_resources"), \
+                    patch.object(resources, "_CHECKOUT_ROOT", tmp / "no-checkout"):
+                with self.assertRaises(resources.ResourceError):
+                    resources.build_root()
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -728,7 +728,7 @@ class TestResolvedRoutesPayload(unittest.TestCase):


 class TestNonBlockingSupervise(unittest.TestCase):
-    """PRD prd-new / issue #412: pending responses carry the proposal id, and
+    """PRD 0072 / issue #412: pending responses carry the proposal id, and
    `check-proposal` polls a queued proposal without blocking or re-proposing."""

    _ROUTES = "routes:\n  - host: example.com\n"
@@ -27,7 +27,41 @@ class TestCheckPullRequest(unittest.TestCase):
        event = {"pull_request": {"title": "Change", "body": "Part of #12", "labels": []}}
        self.assertEqual(check_pull_request(event, api), [])

-    def test_rejects_labels_and_pr_reference(self):
+    def test_accepts_labelled_pr_without_issue(self):
+        api = Mock()
+        event = {
+            "pull_request": {
+                "title": "Change",
+                "body": "",
+                "labels": [{"name": "Kind/Documentation"}],
+            }
+        }
+        self.assertEqual(check_pull_request(event, api), [])
+        api.request.assert_not_called()
+
+    def test_rejects_unlabelled_pr_without_issue(self):
+        api = Mock()
+        event = {"pull_request": {"title": "Change", "body": "", "labels": []}}
+        errors = check_pull_request(event, api)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("either have a label or reference an issue", errors[0])
+        api.request.assert_not_called()
+
+    def test_rejects_labelled_pr_linked_to_real_issue(self):
+        api = Mock()
+        api.request.return_value = {"number": 12, "pull_request": None}
+        event = {
+            "pull_request": {
+                "title": "Change",
+                "body": "Closes #12",
+                "labels": [{"name": "Kind/Documentation"}],
+            }
+        }
+        errors = check_pull_request(event, api)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("exactly one tracking mode", errors[0])
+
+    def test_still_validates_issue_reference_when_both_modes_are_used(self):
        api = Mock()
        api.request.return_value = {"number": 12, "pull_request": {}}
        event = {
@@ -39,7 +73,7 @@ class TestCheckPullRequest(unittest.TestCase):
        }
        errors = check_pull_request(event, api)
        self.assertEqual(len(errors), 2)
-        self.assertIn("unlabeled", errors[0])
+        self.assertIn("exactly one tracking mode", errors[0])
        self.assertIn("not an issue", errors[1])


@@ -0,0 +1,119 @@
+"""Integration: build the wheel, install it into an isolated venv, and prove
+the installed distribution is self-contained.
+
+This is the boundary a source-tree existence test can't reach (issue #197
+review): under an installed wheel the package lives in ``site-packages`` with
+no repo root above it, so anything resolving Dockerfiles / nix / scripts from
+``__file__``'s parents would break. Here we install for real and assert that
+``bot-bottle doctor`` runs from the console script and that
+``bot_bottle.resources`` stages a valid, repo-root-shaped build context.
+
+It does NOT run `start` — building images needs a Docker/KVM host (CI). It
+skips cleanly when the build/venv toolchain isn't available.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+class TestWheelInstall(unittest.TestCase):
+    """`build` is a declared dev dependency (requirements-dev.txt), so this runs
+    in CI. A build/install failure is a real packaging regression and FAILS —
+    only genuinely-unsupported infra (no `venv`/`ensurepip`) skips."""
+
+    _tmp: "tempfile.TemporaryDirectory[str]"
+    venv_py: Path
+    app_root: Path
+
+    @classmethod
+    def setUpClass(cls):
+        cls._tmp = tempfile.TemporaryDirectory(  # pylint: disable=consider-using-with
+            prefix="bb-wheel-")
+        tmp = Path(cls._tmp.name)
+        dist = tmp / "dist"
+
+        # A failed wheel build is exactly the regression this test guards — fail,
+        # don't skip. `build` is installed via requirements-dev.txt.
+        built = subprocess.run(
+            [sys.executable, "-m", "build", "--wheel", "--outdir", str(dist), str(REPO_ROOT)],
+            capture_output=True, text=True, check=False,
+        )
+        if built.returncode != 0:
+            raise AssertionError(f"wheel build failed:\n{built.stderr[-2000:]}")
+        wheels = list(dist.glob("*.whl"))
+        if not wheels:
+            raise AssertionError(f"no wheel produced:\n{built.stdout[-2000:]}")
+
+        # A missing `venv`/`ensurepip` is unsupported optional infra, not a
+        # packaging bug — skip only here.
+        venv = tmp / "venv"
+        made = subprocess.run([sys.executable, "-m", "venv", str(venv)],
+                              capture_output=True, text=True, check=False)
+        if made.returncode != 0:
+            raise unittest.SkipTest(f"venv/ensurepip unavailable:\n{made.stderr[-1500:]}")
+        cls.venv_py = venv / "bin" / "python"
+
+        # Installing the freshly-built wheel must succeed — fail if it doesn't.
+        install = subprocess.run(
+            [str(cls.venv_py), "-m", "pip", "install", "--quiet", str(wheels[0])],
+            capture_output=True, text=True, check=False,
+        )
+        if install.returncode != 0:
+            raise AssertionError(f"pip install of the wheel failed:\n{install.stderr[-2000:]}")
+
+        # Isolate the staged build root the wheel writes under the app-data dir.
+        cls.app_root = tmp / "appdata"
+
+    @classmethod
+    def tearDownClass(cls):
+        cls._tmp.cleanup()
+
+    def _run(self, tail: "list[str]") -> "subprocess.CompletedProcess[str]":
+        """Run the installed venv's python with `tail` appended, from a neutral
+        cwd so the source checkout isn't on sys.path — we must import the
+        *installed* package, not the repo we built from."""
+        env = {"BOT_BOTTLE_ROOT": str(self.app_root), "PATH": "/usr/bin:/bin"}
+        return subprocess.run(
+            [str(self.venv_py), *tail],
+            capture_output=True, text=True, env=env, cwd=self._tmp.name, check=False,
+        )
+
+    def test_console_entry_point_installed(self):
+        # The `bot-bottle` script the wheel declares must exist in the venv.
+        script = self.venv_py.parent / "bot-bottle"
+        self.assertTrue(script.is_file(), "bot-bottle console script not installed")
+
+    def test_doctor_runs_from_installed_package(self):
+        proc = self._run(["-m", "bot_bottle.cli", "doctor"])
+        # doctor exits non-zero here (no backend), but it must RUN and report.
+        self.assertIn("python", proc.stdout)
+        self.assertIn(proc.returncode, (0, 1))
+
+    def test_installed_wheel_is_self_contained(self):
+        # From the installed layout (not a checkout), resources must resolve
+        # Dockerfiles and stage a repo-root-shaped build context.
+        script = (
+            "import bot_bottle.resources as r\n"
+            "assert not r.is_source_checkout(), 'should not look like a checkout'\n"
+            "assert r.dockerfile('Dockerfile.gateway').is_file()\n"
+            "assert r.nix_netpool_module().is_file()\n"
+            "assert r.netpool_script().is_file()\n"
+            "root = r.build_root()\n"
+            "assert (root / 'bot_bottle' / '__init__.py').is_file(), 'no package in context'\n"
+            "assert (root / 'pyproject.toml').is_file(), 'no pyproject in context'\n"
+            "assert (root / 'Dockerfile.gateway').is_file(), 'no Dockerfile in context'\n"
+            "print('SELF_CONTAINED_OK')\n"
+        )
+        proc = self._run(["-c", script])
+        self.assertIn("SELF_CONTAINED_OK", proc.stdout, msg=proc.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()
Author	SHA1	Message	Date
didericis-claude	a86ad630e2	docs: defer broker replay protection to its own issue (#494 ) prd-number-check / require-numbered-prds (pull_request) Failing after 9s Details lint / lint (push) Successful in 1m0s Details tracker-policy-pr / check-pr (pull_request) Successful in 20s Details Per PR review, replay protection is too heavy for the host control server MVP. Drop it from the four-gap framing (now three gaps), remove the enforcement design section and implementation chunk, and track the iat-window + jti-cache work in #494 as an independent in-process change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-26 02:56:34 -04:00
didericis-claude	8e459647fb	docs: PRD for host-side control server (#468 ) Promote the in-process launch broker into a standalone host control server: the single privileged host component that brokers launches, owns orchestrator lifecycle, and is the sole writer of host-durable state. Closes the four broker gaps (transport, durable provisioned secret, replay protection, disciplined op vocabulary) and splits host state by owner and lifetime (orchestrator SQLite / host JSONL audit / gateway none). The payoff is dropping the Docker socket from the CLI. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-26 02:56:34 -04:00
didericis-codex	0fc5457e41	docs(adr): align tracker policy title test / integration-docker (push) Successful in 17s Details test / unit (push) Successful in 48s Details lint / lint (push) Successful in 59s Details test / coverage (push) Successful in 16s Details Update Quality Badges / update-badges (push) Successful in 4m4s Details	2026-07-26 02:54:56 -04:00
didericis-codex	c0493f0b01	ci(tracker): require one metadata owner per pull request	2026-07-26 02:54:56 -04:00
didericis-codex	5828f5e900	ci(tracker): allow labelled standalone pull requests	2026-07-26 02:54:56 -04:00
didericis-codex	be025ff8fb	docs(prd): explain superseded dashboard designs	2026-07-26 02:54:56 -04:00
didericis-codex	9537c96586	docs: streamline design workflow guidance	2026-07-26 02:54:56 -04:00
didericis-codex	6b43fe73c1	docs: add design workflow guide	2026-07-26 02:54:56 -04:00
didericis-codex	d3370a88bb	ci(prd): require manual numbering before merge prd-number-check / require-numbered-prds (pull_request) Successful in 10s Details tracker-policy-pr / check-pr (pull_request) Successful in 14s Details test / unit (pull_request) Successful in 54s Details test / integration-docker (pull_request) Successful in 54s Details test / coverage (pull_request) Successful in 18s Details test / integration-docker (push) Successful in 16s Details test / unit (push) Successful in 50s Details lint / lint (push) Successful in 1m0s Details test / coverage (push) Successful in 15s Details Update Quality Badges / update-badges (push) Successful in 4m1s Details	2026-07-26 02:33:14 -04:00
didericis-codex	39167528db	ci(test): publish infra after pre-release checks tracker-policy-pr / check-pr (pull_request) Successful in 10s Details test / integration-docker (pull_request) Successful in 20s Details test / unit (pull_request) Successful in 4m11s Details test / coverage (pull_request) Successful in 17s Details test / integration-docker (push) Successful in 15s Details test / unit (push) Successful in 49s Details test / coverage (push) Successful in 23s Details	2026-07-26 06:24:28 +00:00
didericis-codex	b25ace4c00	ci(test): split automated and pre-release suites tracker-policy-pr / check-pr (pull_request) Successful in 11s Details test / integration-docker (pull_request) Successful in 22s Details test / unit (pull_request) Successful in 54s Details test / coverage (pull_request) Successful in 17s Details	2026-07-26 06:22:53 +00:00
didericis-codex	9c06702b32	docs(prd): number merged placeholder documents prd-number / assign-numbers (push) Failing after 25s Details lint / lint (push) Successful in 4m7s Details Update Quality Badges / update-badges (push) Failing after 13m37s Details test / coverage (push) Has been skipped Details test / integration-docker (push) Failing after 13m51s Details test / integration-firecracker (push) Failing after 13m48s Details test / integration-macos (push) Failing after 13m54s Details test / unit (push) Failing after 13m53s Details test / publish-infra (push) Has been skipped Details	2026-07-26 06:06:04 +00:00
didericis-codex	cd0983d943	docs(prd): update shipped draft statuses prd-number / assign-numbers (push) Failing after 24s Details	2026-07-26 06:04:15 +00:00
didericis-codex	99176b1edf	docs(prd): mark superseded architecture contracts	2026-07-26 06:02:47 +00:00
Quality Badge Bot	652f14dcb1	chore: update quality badges - Coverage: 83% - Core coverage: 94% [skip ci]	2026-07-26 02:36:35 +00:00
didericis-claude	38c13708c7	Merge pull request 'PRD prd-new: macOS (Apple Container) CI runner' (#479 ) from prd-macos-container-ci-runner into main test / integration-macos (push) Has been skipped Details prd-number / assign-numbers (push) Failing after 27s Details test / integration-docker (push) Successful in 16s Details lint / lint (push) Successful in 1m7s Details Update Quality Badges / update-badges (push) Successful in 58s Details test / unit (push) Successful in 2m11s Details test / integration-firecracker (push) Successful in 5m2s Details test / coverage (push) Successful in 25s Details test / publish-infra (push) Successful in 2m1s Details	2026-07-25 22:34:47 -04:00
didericis-claude	82669b22d5	fix: doctor probes backend readiness; install.sh resolves user-scripts dir test / integration-docker (push) Successful in 20s Details prd-number / assign-numbers (push) Failing after 24s Details test / unit (push) Successful in 57s Details lint / lint (push) Successful in 1m1s Details Update Quality Badges / update-badges (push) Failing after 54s Details test / integration-firecracker (push) Successful in 5m7s Details test / coverage (push) Successful in 27s Details test / publish-infra (push) Successful in 2m34s Details Addresses the third review round on PR #481. - `bot-bottle doctor` now checks `is_backend_ready()` (a full backend status() probe: daemon reachable, network pool present, KVM usable) instead of the cheap PATH-only `is_backend_available()`. A host with a stopped Docker daemon or half-configured Firecracker no longer reports `ok: backend` / exit 0 when `start` can't actually work; each not-ready backend prints its own diagnostics, and doctor passes only if at least one backend is ready. - `install.sh` resolves the pip `--user` scripts directory from the interpreter (`sysconfig.get_path("scripts", get_preferred_scheme("user"))`) instead of hardcoding `~/.local/bin`, which is wrong on a python.org macOS interpreter (`~/Library/Python/<X.Y>/bin`). The PATH guidance now prints the actual directory. Tests: doctor tests mock `is_backend_ready` (the readiness contract) and cover the not-ready → fail path; a new install-script test drives the macOS `osx_framework_user` scheme and asserts it resolves a non-~/.local/bin directory. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-25 22:34:25 -04:00
didericis-claude	1a4b390e8a	fix: make installed wheel self-contained + harden install.sh prereqs Addresses the review on PR #481. Self-contained wheel (review point 1): the gateway/infra/orchestrator images build from a context that must hold bot_bottle/, pyproject.toml, and the root-level Dockerfiles. Modules previously located these by walking __file__ to the repo root, so an installed wheel (package in site-packages, no repo root) passed `doctor` but failed `start`. - Add bot_bottle/resources.py: build_root() returns the repo root in a checkout (unchanged) or a staged copy from the wheel's bundled _resources/ otherwise; dockerfile()/nix_netpool_module()/ netpool_script() derive from it. - setup.py bundles the root Dockerfiles, nix module, netpool script, and pyproject.toml into bot_bottle/_resources/ at build; MANIFEST.in ships them in the sdist. - Route every _REPO_ROOT/_REPO_DIR call site (docker/macos launch, macos infra, firecracker infra_vm/infra_artifact/setup, orchestrator lifecycle/gateway) through resources. Checkout behavior is unchanged. install.sh prerequisites (review point 2): check for git when installing a git+ spec, and — before the pip fallback — that pip is usable and the interpreter isn't externally managed (PEP 668), pointing at pipx. Tests: test_resources covers checkout + staged-wheel layouts; test_wheel_install builds the wheel, installs it into an isolated venv, and asserts `doctor` runs and build_root() yields a valid context. Running `start` end-to-end still needs a Docker/KVM host (CI). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-25 22:34:25 -04:00
didericis-claude	955cb3bcbd	feat: add quick install script and packaging (#197 ) Give bot-bottle a real distribution path so new users can install without cloning the repo: - pyproject.toml: full project metadata, a `bot-bottle` console-script entry point (bot_bottle.cli:main), and package-data for the runtime assets (Dockerfiles, egress entrypoint, netpool defaults, macos init). Still zero runtime pip dependencies. - install.sh: POSIX, sudo-free, idempotent bootstrapper — checks Python >= 3.11, creates ~/.bot-bottle/{agents,bottles,contrib}, installs via pipx (pip --user fallback), then runs `bot-bottle doctor`. - `bot-bottle doctor`: new store-free subcommand reporting Python version, backend availability (reuses is_backend_available rather than hardcoding Docker), and config-dir presence. Exits non-zero when a hard prerequisite is unmet. - PRD prd-new-install-script and unit tests for doctor, the packaging contract, and the install script. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-25 22:34:25 -04:00
didericis-claude	605146d287	ci(integration-macos): dump infra logs on failure before teardown test / integration-macos (pull_request) Has been skipped Details test / integration-docker (pull_request) Successful in 20s Details tracker-policy-pr / check-pr (pull_request) Successful in 23s Details test / unit (pull_request) Successful in 40s Details test / integration-firecracker (pull_request) Successful in 2m8s Details test / coverage (pull_request) Successful in 21s Details test / publish-infra (pull_request) Has been skipped Details A control-plane failure (e.g. the orchestrator becoming unreachable at bottle registration) is undiagnosable from CI as-is: the `if: always()` teardown runs `MacosInfraService().stop()`, which deletes the orchestrator and gateway containers — and their logs — on every run. Add an `if: failure()` step that dumps `container ls`/`network ls`, plus `inspect` and `logs` for `bot-bottle-mac-orchestrator` and `bot-bottle-mac-infra`, ordered before the teardown so the evidence is captured while the containers still exist. Best-effort (never fails the job; tolerates an already-removed container). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-26 02:22:52 +00:00
didericis-claude	27dea58ae1	integration-macos: dispatch-only (drop push-to-main trigger) test / integration-macos (pull_request) Has been skipped Details tracker-policy-pr / check-pr (pull_request) Successful in 11s Details test / integration-docker (pull_request) Successful in 34s Details test / unit (pull_request) Successful in 44s Details lint / lint (push) Successful in 1m2s Details test / integration-firecracker (pull_request) Successful in 2m6s Details test / coverage (pull_request) Successful in 17s Details test / publish-infra (pull_request) Has been skipped Details Make the advisory macOS Apple Container job run on workflow_dispatch only, removing the push-to-`main` trigger so a single non-redundant laptop never runs unattended on every push. Updates the job comment, docs/ci.md, README CI note, and the PRD accordingly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-25 22:05:26 -04:00
didericis	5401f036a9	docs: correct git-gate status on macOS backend (not deferred) git-gate is fully implemented on the macos-container backend via the gateway's consolidated git-http daemon with dynamic key provisioning/revocation; only the legacy per-bottle git:// daemon is unused. Fixes a stale README claim that git-gate is "deferred" and removes the PRD open-question built on that false premise (sandbox-escape attack 5 runs the same on macOS as on the other backends). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-25 22:05:26 -04:00
didericis	238f5f7614	ci: add advisory macOS Apple Container integration runner Adds an `integration-macos` job that runs the integration suite against BOT_BOTTLE_BACKEND=macos-container on a self-hosted host-mode macOS runner (label `macos`), plus the PRD and provisioning docs. The job is advisory (push-to-main + workflow_dispatch only, never PRs, not in coverage.needs) since it targets a single non-redundant laptop. It preflights `container`/`backend status` so a misprovisioned runner fails loudly, serializes on a concurrency group, and tears down the `bot-bottle-mac-infra` singleton on exit (#425). Also relaxes the TestSandboxEscape CI skip guard: it skipped every backend but firecracker under GITEA_ACTIONS, which would also skip on a host-mode macOS runner. The guard's real target is the containerized act_runner, so it now allows both host-mode backends (firecracker, macos-container) through — otherwise the macOS job would go green while skipping the one end-to-end test that proves the backend launches. Closes #426 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-25 22:05:26 -04:00