docs(prd): assign PRD number 0082

CI (prd-number-check) rejects unnumbered prd-new-*.md on merge to main.
Rename docs/prds/prd-new-trusted-agent-forge-identity.md to
0082-trusted-agent-forge-identity.md (0081 is claimed by #517/#519) and
update the in-repo 'PRD prd-new-trusted-agent-forge-identity' citations to
'PRD 0082'.

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

.coveragerc

@@ -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

.gitea/workflows/canaries.yml

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

.gitea/workflows/lint.yml

@@ -4,6 +4,13 @@ on:
   push:
     paths:
       - "**.py"
+      - "Dockerfile*"
+      - "bot_bottle/contrib/*/Dockerfile"
+      - "bot_bottle/contrib/*/package.json"
+      - "bot_bottle/contrib/*/package-lock.json"
+      - "bot_bottle/contrib/codex/codex-package_SHA256SUMS"
+      - "requirements.gateway.*"
+      - "image-build-args.json"
       - ".pylintrc"
       - ".gitea/workflows/lint.yml"
 
@@ -13,6 +20,9 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
+      - name: Enforce immutable image inputs
+        run: python3 scripts/check_image_inputs.py
+
       # No actions/setup-python: the runner image already ships Python 3.12,
       # and older act_runner engines mishandle setup-python's PATH. Install
       # into the ephemeral job container's system Python — the pylint/pyright

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

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

.gitea/workflows/prd-number.yml

@@ -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

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

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

.gitea/workflows/refresh-image-locks.yml

@@ -0,0 +1,97 @@
+# Manually refresh the committed package locks and the pinned Codex installer
+# checksum after deliberately changing a direct version in the source files.
+#
+# The job uploads the generated files for review; it never commits or pushes.
+
+name: refresh-image-locks
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - 'requirements.gateway.in'
+      - 'bot_bottle/contrib/claude/package.json'
+      - 'bot_bottle/contrib/pi/package.json'
+      - 'bot_bottle/contrib/codex/Dockerfile'
+      - 'image-build-args.json'
+      - '.gitea/workflows/refresh-image-locks.yml'
+
+permissions:
+  code: read
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Resolve image runtime versions
+        id: runtimes
+        run: |
+          python3 - <<'PY' >> "$GITHUB_OUTPUT"
+          import json
+          import re
+          inputs = json.load(open("image-build-args.json"))
+          for output, name in (
+              ("python-version", "PYTHON_BASE_IMAGE"),
+              ("node-version", "NODE_BASE_IMAGE"),
+          ):
+              match = re.search(r":(\d+\.\d+\.\d+)-", inputs[name])
+              if match is None:
+                  raise SystemExit(f"cannot resolve runtime version from {name}")
+              print(f"{output}={match.group(1)}")
+          PY
+
+      - name: Use the image Python version
+        uses: actions/setup-python@v5
+        with:
+          python-version: '${{ steps.runtimes.outputs.python-version }}'
+
+      - name: Use the image Node version
+        uses: actions/setup-node@v4
+        with:
+          node-version: '${{ steps.runtimes.outputs.node-version }}'
+
+      - name: Compile gateway Python lock
+        run: |
+          python3 -m venv /tmp/image-lock-tools
+          /tmp/image-lock-tools/bin/python -m pip install \
+            pip==25.2 \
+            pip-tools==7.5.1
+          /tmp/image-lock-tools/bin/python -m piptools compile \
+            --generate-hashes \
+            --output-file requirements.gateway.lock \
+            requirements.gateway.in
+
+      - name: Resolve provider npm locks
+        run: |
+          for provider in claude pi; do
+            (
+              cd "bot_bottle/contrib/$provider"
+              npm install --package-lock-only --ignore-scripts --no-audit --no-fund
+            )
+          done
+          python3 scripts/complete_npm_lock_integrity.py \
+            bot_bottle/contrib/claude/package-lock.json \
+            bot_bottle/contrib/pi/package-lock.json
+
+      - name: Refresh pinned Codex archive checksums
+        run: |
+          CODEX_VERSION=$(
+            sed -n 's/^ARG CODEX_VERSION=//p' bot_bottle/contrib/codex/Dockerfile
+          )
+          test -n "$CODEX_VERSION"
+          curl -fsSL \
+            "https://github.com/openai/codex/releases/download/rust-v${CODEX_VERSION}/codex-package_SHA256SUMS" \
+            -o bot_bottle/contrib/codex/codex-package_SHA256SUMS
+
+      - name: Upload refreshed inputs
+        uses: actions/upload-artifact@v3
+        with:
+          name: image-input-locks
+          path: |
+            requirements.gateway.lock
+            bot_bottle/contrib/claude/package-lock.json
+            bot_bottle/contrib/pi/package-lock.json
+            bot_bottle/contrib/codex/codex-package_SHA256SUMS

.gitea/workflows/test.yml

@@ -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
 
@@ -27,32 +12,49 @@ on:
       - 'bot_bottle/**'
       - 'tests/**/*.py'
       - 'cli.py'
+      - 'install.sh'
+      - 'setup.py'
+      - 'MANIFEST.in'
+      - 'flake.nix'
+      - 'nix/firecracker-netpool.nix'
       - 'scripts/coverage.sh'
       - 'scripts/critical-modules.txt'
-      - 'scripts/diff_coverage.py'
-      - 'scripts/tracker_policy.py'
+      - 'scripts/**/*.py'
       - 'scripts/firecracker-netpool.sh'
       - 'Dockerfile*'
+      - 'image-build-args.json'
       - 'pyproject.toml'
       - 'requirements-dev.txt'
+      - 'requirements.gateway.*'
       - '.coveragerc'
       - '.dockerignore'
+      - '.gitea/workflows/test.yml'
+      - '.gitea/workflows/refresh-image-locks.yml'
+      - '.gitea/workflows/pre-release-test.yml'
   pull_request:
     paths:
       - 'bot_bottle/**'
       - 'tests/**/*.py'
       - 'cli.py'
+      - 'install.sh'
+      - 'setup.py'
+      - 'MANIFEST.in'
+      - 'flake.nix'
+      - 'nix/firecracker-netpool.nix'
       - 'scripts/coverage.sh'
       - 'scripts/critical-modules.txt'
-      - 'scripts/diff_coverage.py'
-      - 'scripts/tracker_policy.py'
+      - 'scripts/**/*.py'
       - 'scripts/firecracker-netpool.sh'
       - 'Dockerfile*'
+      - 'image-build-args.json'
       - 'pyproject.toml'
       - 'requirements-dev.txt'
+      - 'requirements.gateway.*'
       - '.coveragerc'
       - '.dockerignore'
-  workflow_dispatch:
+      - '.gitea/workflows/test.yml'
+      - '.gitea/workflows/refresh-image-locks.yml'
+      - '.gitea/workflows/pre-release-test.yml'
 
 jobs:
   unit:
@@ -61,11 +63,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 +76,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
 
@@ -94,33 +87,67 @@ jobs:
 
   integration-docker:
     runs-on: ubuntu-latest
+    concurrency:
+      group: integration-docker-infra
+      cancel-in-progress: false
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      # No actions/setup-python (see the note in the `unit` job); the
-      # container's system Python 3.12 runs the stdlib test suite directly.
       - name: Install coverage
         run: python3 -m pip install --break-system-packages coverage
 
-      # Fail loudly if the backend this job promises isn't actually usable,
-      # rather than letting every test silently `unittest.skip` and the job
-      # go green on zero coverage. `backend status` prints a clear per-check
-      # summary (docker on PATH, daemon reachable) and exits non-zero when a
-      # prerequisite is missing — the same readiness check the skip guards
-      # gate on via `has_backend`.
       - name: Preflight — Docker backend is ready
         run: |
           python3 --version
           python3 cli.py backend status --backend=docker
 
+      - name: Preflight — clear any leftover poisoned gateway network
+        run: |
+          # The gateway network has a fixed name and persists across jobs on
+          # this shared runner. A pre-fix or concurrent launch can leave it with
+          # a malformed IPv6 subnet that trips docker's own ParseAddr in
+          # `network inspect` (see PR #515); the code now self-heals it, but the
+          # heal can't run if `network inspect` is what's broken on some daemon
+          # versions. Drop the network here so this run recreates it IPv4-only.
+          # Remove the attached gateway container first (else `network rm` fails
+          # on active endpoints); both are recreated by ensure_running. Harmless
+          # when absent.
+          docker rm --force bot-bottle-orch-gateway 2>/dev/null || true
+          docker network rm bot-bottle-gateway 2>/dev/null || true
+
       - 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
+        run: |
+          set -euo pipefail
+          # act_runner executes this job in a container while sharing the host
+          # Docker socket. Attach control-plane siblings to the job's network,
+          # and use named volumes for state the host daemon must mount.
+          DOCKER_CLIENT_NETWORK=$(
+            docker inspect "$(hostname)" |
+              python3 -c 'import json,sys; n=json.load(sys.stdin)[0]["NetworkSettings"]["Networks"]; print(next(iter(n)))'
+          )
+          test -n "$DOCKER_CLIENT_NETWORK"
+          RUN_KEY="${GITHUB_RUN_ID:-${GITHUB_RUN_NUMBER:-0}}"
+          export NO_PROXY="*"
+          export no_proxy="*"
+          export BOT_BOTTLE_DOCKER_CLIENT_NETWORK="$DOCKER_CLIENT_NETWORK"
+          export BOT_BOTTLE_DOCKER_ROOT_MOUNT="bot-bottle-ci-root-$RUN_KEY"
+          export BOT_BOTTLE_DOCKER_CA_MOUNT="bot-bottle-ci-ca-$RUN_KEY"
+          python3 -m coverage run -m scripts.unittest_gate \
+            -t . -s tests/integration -v \
+            --minimum-executed 22 --fail-on-skip
+
+      - name: Clean Docker integration volumes
+        if: always()
+        run: |
+          RUN_KEY="${GITHUB_RUN_ID:-${GITHUB_RUN_NUMBER:-0}}"
+          docker volume rm --force \
+            "bot-bottle-ci-root-$RUN_KEY" \
+            "bot-bottle-ci-ca-$RUN_KEY" 2>/dev/null || true
 
-      # 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 +157,118 @@ 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)
+  image-input-builds:
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Preflight — Firecracker host is ready
+      - name: Verify shared bases cover supported architectures
         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
+          set -euo pipefail
+          python_ref=$(python3 -c \
+            'import json; print(json.load(open("image-build-args.json"))["PYTHON_BASE_IMAGE"])')
+          node_ref=$(python3 -c \
+            'import json; print(json.load(open("image-build-args.json"))["NODE_BASE_IMAGE"])')
+          docker_cli_ref=$(python3 -c \
+            'import json; print(json.load(open("image-build-args.json"))["DOCKER_CLI_BASE_IMAGE"])')
+          test -n "$python_ref"
+          test -n "$node_ref"
+          test -n "$docker_cli_ref"
+          for ref in "$python_ref" "$node_ref" "$docker_cli_ref"; do
+            docker buildx imagetools inspect --raw "$ref" |
+              python3 -c '
+          import json
+          import sys
+          manifest = json.load(sys.stdin)
+          platforms = {
+              (item["platform"]["os"], item["platform"]["architecture"])
+              for item in manifest["manifests"]
+              if item.get("platform", {}).get("os") != "unknown"
+          }
+          required = {("linux", "amd64"), ("linux", "arm64")}
+          missing = required - platforms
+          if missing:
+              raise SystemExit(f"base manifest lacks supported platforms: {missing}")
+          '
+          done
 
-      - 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: Verify Codex archives for all supported architectures
+        run: |
+          set -euo pipefail
+          codex_version=$(
+            sed -n 's/^ARG CODEX_VERSION=//p' bot_bottle/contrib/codex/Dockerfile
+          )
+          test -n "$codex_version"
+          tmp=$(mktemp -d)
+          trap 'rm -rf "$tmp"' EXIT
+          for target in \
+            aarch64-unknown-linux-musl \
+            x86_64-unknown-linux-musl
+          do
+            asset="codex-package-${target}.tar.gz"
+            expected=$(
+              awk -v asset="$asset" '$2 == asset { print $1 }' \
+                bot_bottle/contrib/codex/codex-package_SHA256SUMS
+            )
+            test -n "$expected"
+            curl -fsSL \
+              "https://github.com/openai/codex/releases/download/rust-v${codex_version}/${asset}" \
+              -o "$tmp/$asset"
+            echo "$expected  $tmp/$asset" | sha256sum -c -
+            tar -tzf "$tmp/$asset" > "$tmp/$asset.contents"
+            grep -Fx 'bin/codex' "$tmp/$asset.contents"
+            grep -Fx 'bin/codex-code-mode-host' "$tmp/$asset.contents"
+            grep -Fx 'codex-package.json' "$tmp/$asset.contents"
+          done
 
-      - name: Replace the persistent infra VM with the candidate
-        run: python3 -c 'from bot_bottle.backend.firecracker import infra_vm; infra_vm.stop()'
+      - name: Build and smoke-test all supported images
+        run: |
+          set -euo pipefail
+          suffix="${GITHUB_RUN_ID:-${GITHUB_RUN_NUMBER:-image-inputs}}"
+          orchestrator="bot-bottle-orchestrator-inputs:${suffix}"
+          gateway="bot-bottle-gateway-inputs:${suffix}"
+          orchestrator_fc="bot-bottle-orchestrator-fc-inputs:${suffix}"
+          claude="bot-bottle-claude-inputs:${suffix}"
+          codex="bot-bottle-codex-inputs:${suffix}"
+          pi="bot-bottle-pi-inputs:${suffix}"
+          python_base=$(python3 -c \
+            'import json; print(json.load(open("image-build-args.json"))["PYTHON_BASE_IMAGE"])')
+          node_base=$(python3 -c \
+            'import json; print(json.load(open("image-build-args.json"))["NODE_BASE_IMAGE"])')
 
-      # 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
+          docker build --build-arg "PYTHON_BASE_IMAGE=$python_base" \
+            -t "$orchestrator" -f Dockerfile.orchestrator .
+          orchestrator_id=$(docker image inspect --format '{{.Id}}' "$orchestrator")
+          case "$orchestrator_id" in sha256:*) ;; *) exit 1 ;; esac
+          orchestrator_base="bot-bottle-orchestrator-inputs:sha256-${orchestrator_id#sha256:}"
+          docker image tag "$orchestrator_id" "$orchestrator_base"
+          test "$(
+            docker image inspect --format '{{.Id}}' "$orchestrator_base"
+          )" = "$orchestrator_id"
+          docker build --build-arg "PYTHON_BASE_IMAGE=$python_base" \
+            -t "$gateway" -f Dockerfile.gateway .
+          docker build \
+            --build-arg "ORCHESTRATOR_BASE_IMAGE=$orchestrator_base" \
+            -t "$orchestrator_fc" -f Dockerfile.orchestrator.fc .
+          docker build --build-arg "NODE_BASE_IMAGE=$node_base" \
+            -t "$claude" -f bot_bottle/contrib/claude/Dockerfile .
+          docker build --build-arg "NODE_BASE_IMAGE=$node_base" \
+            -t "$codex" -f bot_bottle/contrib/codex/Dockerfile .
+          docker build --build-arg "NODE_BASE_IMAGE=$node_base" \
+            -t "$pi" -f bot_bottle/contrib/pi/Dockerfile .
 
-      # 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
+          docker run --rm --entrypoint python3 "$orchestrator" -c \
+            'import bot_bottle.orchestrator'
+          docker run --rm --entrypoint mitmdump "$gateway" --version
+          docker run --rm "$claude" claude --version
+          docker run --rm "$codex" codex --version
+          docker run --rm "$pi" pi --version
 
-      - 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 +290,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%)
+      - name: Diff-coverage gate (changed lines >= 80%)
         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
+          python3 scripts/diff_coverage.py --base origin/main --min 80

.gitea/workflows/update-badges.yml

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

.gitignore

@@ -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/

AGENTS.md

@@ -44,10 +44,10 @@ backend remains available with `BOT_BOTTLE_BACKEND=docker` or
 
 - Three kinds of doc, each with its own conventions in-folder; see
   `docs/README.md` for when to write which:
-  - **PRDs** (`docs/prds/`) — one feature per file. 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

Dockerfile.gateway

@@ -36,11 +36,23 @@
 #   9420  git-gate smart HTTP (VM-backend agent-facing transport)
 #   9100  supervise (MCP HTTP)
 
-# Based on `python:3.12-slim` (Debian trixie) rather than the
+# Based on an exact `python:3.12.13-slim-trixie` multi-architecture manifest
+# rather than the
 # `mitmproxy/mitmproxy` image (Debian bookworm), matching the trixie base the
 # orchestrator image needs for buildah (Dockerfile.orchestrator.fc). mitmproxy
 # is pip-installed to the same effect as the upstream image.
-FROM python:3.12-slim
+ARG PYTHON_BASE_IMAGE
+FROM ${PYTHON_BASE_IMAGE}
+
+# Freeze apt's package universe as well as the base filesystem. Without a
+# snapshot, the same Dockerfile resolves different package versions over time.
+ARG DEBIAN_SNAPSHOT=20260724T000000Z
+RUN sed -i \
+      -e "s|http://deb.debian.org/debian-security|http://snapshot.debian.org/archive/debian-security/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|https://deb.debian.org/debian-security|http://snapshot.debian.org/archive/debian-security/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|http://deb.debian.org/debian|http://snapshot.debian.org/archive/debian/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|https://deb.debian.org/debian|http://snapshot.debian.org/archive/debian/${DEBIAN_SNAPSHOT}|g" \
+      /etc/apt/sources.list.d/debian.sources
 
 # Runtime system deps:
 #   git supplies the `git daemon` subcommand (no separate package)
@@ -48,16 +60,19 @@ FROM python:3.12-slim
 #   openssh-client supplies the upstream SSH transport the
 #     pre-receive hook uses to forward accepted refs.
 #   ca-certificates is needed for mitmdump upstream TLS.
-RUN apt-get update \
+RUN apt-get -o Acquire::Check-Valid-Until=false update \
  && apt-get install -y --no-install-recommends \
       git openssh-client ca-certificates \
  && rm -rf /var/lib/apt/lists/*
 
 # mitmdump (the egress data plane). The upstream mitmproxy image baked
-# this in; on the plain python base we pip-install the same pinned
-# version. Its CA dir is set explicitly via `--set confdir=` in
+# this in; on the plain python base we install a fully resolved lock whose
+# distributions are all hash-verified. Its CA dir is set explicitly via
+# `--set confdir=` in
 # egress-entrypoint.sh, so it doesn't depend on a `mitmproxy` home user.
-RUN pip install --no-cache-dir mitmproxy==11.1.3
+COPY requirements.gateway.lock /tmp/requirements.gateway.lock
+RUN pip install --no-cache-dir --require-hashes \
+      -r /tmp/requirements.gateway.lock
 
 # gitleaks (the pre-receive hook's secret scanner). Installed from its
 # official release, pinned by version + SHA256 and verified — rather than

Dockerfile.orchestrator

@@ -16,9 +16,12 @@
 # secret-dense control plane on a minimal dependency surface is the point
 # (PRD 0070's "secret concentration").
 #
-# Shares the trixie `python:3.12-slim` base with the gateway image.
+# Shares an exact multi-architecture Python/trixie manifest with the gateway
+# image. The version-qualified tag keeps the human-readable upstream version;
+# the digest makes the bytes immutable.
 
-FROM python:3.12-slim
+ARG PYTHON_BASE_IMAGE
+FROM ${PYTHON_BASE_IMAGE}
 
 WORKDIR /app
 

Dockerfile.orchestrator.fc

@@ -12,10 +12,21 @@
 # bare microVM (no fuse-overlayfs / overlay module / subuid maps). The trixie
 # base (from Dockerfile.orchestrator's python:3.12-slim) carries buildah 1.39,
 # which parses the Dockerfile heredocs agent images use (bookworm's 1.28 can't).
-# Matches image_builder.
-FROM bot-bottle-orchestrator:latest
+# Matches image_builder. There is deliberately no default: the build coordinator
+# passes the exact local image ID returned by `docker image inspect`, so this
+# stage cannot silently resolve a stale `:latest` tag.
+ARG ORCHESTRATOR_BASE_IMAGE
+FROM ${ORCHESTRATOR_BASE_IMAGE}
 
-RUN apt-get update \
+ARG DEBIAN_SNAPSHOT=20260724T000000Z
+RUN sed -i \
+      -e "s|http://deb.debian.org/debian-security|http://snapshot.debian.org/archive/debian-security/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|https://deb.debian.org/debian-security|http://snapshot.debian.org/archive/debian-security/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|http://deb.debian.org/debian|http://snapshot.debian.org/archive/debian/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|https://deb.debian.org/debian|http://snapshot.debian.org/archive/debian/${DEBIAN_SNAPSHOT}|g" \
+      /etc/apt/sources.list.d/debian.sources
+
+RUN apt-get -o Acquire::Check-Valid-Until=false update \
  && apt-get install -y --no-install-recommends \
       buildah crun netavark aardvark-dns \
  && rm -rf /var/lib/apt/lists/*

MANIFEST.in

@@ -0,0 +1,11 @@
+# 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 image-build-args.json
+include requirements.gateway.in
+include requirements.gateway.lock
+include nix/firecracker-netpool.nix
+include scripts/firecracker-netpool.sh

README.md

@@ -5,7 +5,7 @@
 # bot-bottle
 
 [![test](https://gitea.dideric.is/didericis/bot-bottle/actions/workflows/test.yml/badge.svg?branch=main)](https://gitea.dideric.is/didericis/bot-bottle/actions?workflow=test.yml)
-[![coverage](https://img.shields.io/badge/coverage-83%25-brightgreen)](https://coverage.readthedocs.io/)
+[![coverage](https://img.shields.io/badge/coverage-84%25-brightgreen)](https://coverage.readthedocs.io/)
 [![core coverage](https://img.shields.io/badge/core%20coverage-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 advisory `integration-macos` job in `.gitea/workflows/pre-release-test.yml` runs only on manual dispatch. It targets a self-hosted host-mode runner labelled `macos`; Apple Container cannot run inside the Linux pull-request runner. Provision an Apple Silicon host with the `container` CLI running and Python ≥ 3.11 plus `coverage` on the launchd service's explicit `PATH`. The infra container is a singleton (`bot-bottle-mac-infra`), so keep runner concurrency at 1. Its coverage is reported separately and never feeds the required pull-request gate.
+
 ### Containers inside a bottle
 
 A bottle may set `nested_containers: true`. On the macOS backend this starts a
@@ -172,7 +174,7 @@ BOT_BOTTLE_BACKEND=firecracker ./cli.py start <agent>
 
 > **NixOS:** enable `virtualisation.docker`, ensure the KVM module is loaded (`boot.kernelModules = [ "kvm-intel" ];` or `kvm-amd`), and add your user to the `kvm` and `docker` groups. For the network pool, consume the flake module — `imports = [ inputs.bot-bottle.nixosModules.firecracker-netpool ]; services.bot-bottle-firecracker = { enable = true; owner = "you"; };` — then `nixos-rebuild switch` (imperative nft/TAP rules don't survive a rebuild; channel users can `imports = [ <bot-bottle>/nix/firecracker-netpool.nix ]`). `firecracker` isn't in nixpkgs by default as a user binary — install the release binary (pin the version) and put it on `PATH`.
 
-> **CI:** the coverage gate (`.gitea/workflows/test.yml` → `coverage` job) runs on a self-hosted runner labelled `kvm`, because the Firecracker backend's VM/SSH orchestration is exercised only by the integration suite, which needs `/dev/kvm` + the provisioned pool (a container runner would skip it and read as uncovered). Provision that runner exactly like a normal Firecracker host — `firecracker` on `PATH`, `/dev/kvm`, the cached guest kernel + static dropbear, and the pool installed as the persistent systemd unit — then register it with the `kvm` label. A Docker-capable hosted job builds the candidate once; KVM tests boot those exact bytes, and a successful main run publishes them. The unit/lint jobs still run on `ubuntu-latest`.
+> **CI:** Firecracker integration runs in the manually dispatched `.gitea/workflows/pre-release-test.yml` on a self-hosted runner labelled `kvm`; privileged KVM hosts never execute unreviewed PR code automatically. Provision it like a normal Firecracker host: `firecracker` on `PATH`, `/dev/kvm`, the cached guest kernel and static dropbear, and the persistent TAP/nft pool. The required pull-request workflow runs unit plus the complete Docker integration suite on `ubuntu-latest`; see `docs/ci.md`.
 
 ```sh
 ./cli.py start <agent>   # builds the image on first run, drops you into claude
@@ -180,7 +182,9 @@ BOT_BOTTLE_BACKEND=firecracker ./cli.py start <agent>
 
 ## Manifest
 
-Bottles and agents are Markdown files with YAML frontmatter under `~/.bot-bottle/`. The Markdown body is the system prompt. Bottles live in `~/.bot-bottle/bottles/`; agents may also be shipped by a repo at `<repo>/.bot-bottle/agents/<name>.md`.
+Bottles and agents are Markdown files with YAML frontmatter under `~/.bot-bottle/`. The Markdown body is the system prompt. Both bottles and agents are **home-only**: they live under `~/.bot-bottle/bottles/` and `~/.bot-bottle/agents/`. A `<repo>/.bot-bottle/agents/<name>.md` shipped by a workspace is ignored with a warning — since an agent may select a host identity and forge secret, checked-out content must not define one (PRD 0082). Keep repo-specific behavioral instructions in `AGENTS.md` instead.
+
+Identity is **agent-owned**: the author name/email and named forge accounts live on the agent, not under `git-gate` (which now carries only Git transport policy). A bottle repo may optionally name one of the selected agent's forge aliases via `forge:`.
 
 **Bottle** (`~/.bot-bottle/bottles/gitea-dev.md`):
 
@@ -188,37 +192,19 @@ Bottles and agents are Markdown files with YAML frontmatter under `~/.bot-bottle
 ---
 extends: claude          # inherit the Claude provider boundary
 
-env:
-  GIT_AUTHOR_NAME: didericis
-
-git:
-  user:
-    name: "Eric Bauerfeld"
-    email: "eric+claude@dideric.is"
-  remotes:
-    gitea.dideric.is:
-      Name: bot-bottle
-      Upstream: ssh://git@gitea.dideric.is:30009/didericis/bot-bottle.git
-      IdentityFile: /Users/didericis/.ssh/id_ed25519_gitea
-      KnownHostKey: ssh-ed25519 AAAA...
-
-egress:
-  routes:
-    - host: gitea.dideric.is
-      inspect:
-        auth:
-          scheme: token        # Bearer | token
-          token_ref: BOT_BOTTLE_GITEA_TOKEN
-        matches:               # optional — restrict to specific paths/methods/headers
-          - paths:
-              - {type: prefix, value: /api/v1/}
-            methods: [GET, POST, PATCH, DELETE]
-        outbound_detectors: [token_patterns, known_secrets]
-        inbound_detectors: false   # disable response scanning for this host
+git-gate:
+  repos:
+    bot-bottle:
+      url: ssh://git@gitea.dideric.is:30009/didericis/bot-bottle.git
+      key:
+        provider: gitea
+        forge_token_env: GITEA_DEPLOY_TOKEN   # deploy-key admin (push), PRD 0048
+      host_key: "ssh-ed25519 AAAA..."
+      forge: didericis-gitea                  # ← selects the agent's forge alias
 ---
 
-The `gitea-dev` bottle. Provider auth via the inherited Claude route;
-gitea over SSH for push, token over HTTPS for the API.
+The `gitea-dev` bottle. Gitea over SSH for push; the API credential and
+workflow guidance come from the agent's `forge: didericis-gitea` association.
 ````
 
 **Agent** (`~/.bot-bottle/agents/gitea-helper.md`):
@@ -228,11 +214,27 @@ gitea over SSH for push, token over HTTPS for the API.
 bottle: gitea-dev
 skills:
   - init-prd
+author:
+  name: didericis-claude
+  email: eric+claude@dideric.is
+forge-accounts:
+  didericis-gitea:
+    url: https://gitea.dideric.is/api/v1
+    auth:
+      type: token
+      token_secret: GITEA_CLAUDE_TOKEN       # host env var; value never enters the bottle
 ---
 
 You help maintain Gitea-hosted projects.
 ````
 
+`author` populates the bottle's `git config user.name/user.email`. When a
+selected repo names a `forge` alias, bot-bottle resolves the alias's
+`token_secret` from the host env into the egress proxy only (never the bottle),
+adds a scoped, proxy-authenticated route to the Gitea API origin, and appends
+non-secret forge workflow guidance to the agent's system prompt. Neither the
+token value nor its `token_secret` name appears in the bottle env or prompt.
+
 **Egress route fields:**
 
 | Field | Required | Description |

bot_bottle/backend/base.py

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

bot_bottle/backend/docker/gateway.py

@@ -10,12 +10,17 @@ 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
 )
 
+DEFAULT_GATEWAY_SUBNET = "10.242.255.0/24"
+_GATEWAY_SUBNET_LABEL = "bot-bottle.gateway-subnet"
+
+
 class DockerGateway(Gateway):
     """The consolidated gateway as a single, fixed-name Docker container.
 
@@ -34,6 +39,8 @@ class DockerGateway(Gateway):
         build_context: Path | None = None,
         dockerfile: str | None = GATEWAY_DOCKERFILE,
         host_port_bindings: tuple[int, ...] = (),
+        ca_mount_source: str | Path | None = None,
+        subnet: str | None = None,
     ) -> None:
         self.image_ref = image_ref
         self.name = name
@@ -50,12 +57,23 @@ 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;
         # Docker's DNAT + the nft `ct status dnat accept` rule handle the rest.
         self._host_port_bindings = host_port_bindings
+        self._subnet = (
+            subnet
+            or os.environ.get("BOT_BOTTLE_DOCKER_GATEWAY_SUBNET", "").strip()
+            or DEFAULT_GATEWAY_SUBNET
+        )
+        configured_ca = os.environ.get("BOT_BOTTLE_DOCKER_CA_MOUNT", "").strip()
+        self._ca_mount_source = str(
+            ca_mount_source or configured_ca or host_gateway_ca_dir()
+        )
 
     def image_exists(self) -> bool:
         return run_docker(["docker", "image", "inspect", self.image_ref]).returncode == 0
@@ -72,11 +90,17 @@ 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")
+        for name, value in resources.image_build_args(
+            self._dockerfile,
+            context=context,
+        ).items():
+            argv[-1:-1] = ["--build-arg", f"{name}={value}"]
         proc = run_docker(argv)
         if proc.returncode != 0:
             raise GatewayError(f"gateway image build failed: {proc.stderr.strip()}")
@@ -105,10 +129,72 @@ class DockerGateway(Gateway):
     def _ensure_network(self) -> None:
         """Create the shared gateway network if it doesn't exist. Idempotent —
         a concurrent create loses harmlessly (the loser sees 'already exists').
-        Docker picks the subnet; the launcher reads it back to allocate IPs."""
-        if run_docker(["docker", "network", "inspect", self.network]).returncode == 0:
-            return
-        proc = run_docker(["docker", "network", "create", self.network])
+        The explicit subnet is required because bottle attribution pins source
+        IPs; Docker rejects static endpoint addresses on an auto-IPAM network."""
+        inspected = run_docker([
+            "docker", "network", "inspect",
+            "--format", f'{{{{index .Labels "{_GATEWAY_SUBNET_LABEL}"}}}}',
+            self.network,
+        ])
+        if inspected.returncode == 0:
+            marker = inspected.stdout.strip()
+            if marker in {"", self._subnet}:
+                return
+            # Inspectable but mislabelled: the stale auto-IPAM network created
+            # by older releases. Replace it below.
+            stale = True
+        else:
+            # inspect failed. Classify by stderr — do NOT assume "not absent"
+            # implies "poisoned": a transient daemon/API error, permission
+            # failure, timeout, or bad context also fails here, and destroying
+            # the shared gateway on that guess would tear the network out from
+            # under every live bottle.
+            err = inspected.stderr.lower()
+            if "no such network" in err or "not found" in err:
+                # Absent: nothing to replace — create it below.
+                stale = False
+            elif "parseaddr" in err:
+                # Present but poisoned. A daemon that default-enables IPv6
+                # attaches an fdd0::/64 subnet whose `::1/64` gateway trips
+                # docker's own netip.ParseAddr in `network inspect`/`ls`, so the
+                # command exits non-zero with that signature. A fixed release
+                # never *creates* such a network, but one can survive on a
+                # shared host from an older or concurrent launch — and
+                # `--ipv6=false` alone can't heal it, since the create below only
+                # no-ops on "already exists". Force-replace it so later reads
+                # (e.g. `_network_cidr` pinning a source IP) stop failing.
+                stale = True
+            else:
+                # Unrecognized failure: no evidence the network is malformed.
+                # Surface it rather than mutate shared state on a guess.
+                raise GatewayError(
+                    f"gateway network {self.network} could not be inspected: "
+                    f"{inspected.stderr.strip()}"
+                )
+        if stale:
+            # Migrate the stale/poisoned network. Removing the fixed gateway is
+            # safe here: this launch recreates it.
+            run_docker(["docker", "rm", "--force", self.name])
+            removed = run_docker(["docker", "network", "rm", self.network])
+            if removed.returncode != 0 and "no such network" not in removed.stderr.lower():
+                raise GatewayError(
+                    f"gateway network {self.network} needs explicit subnet "
+                    f"{self._subnet} but could not be replaced: "
+                    f"{removed.stderr.strip()}"
+                )
+        proc = run_docker([
+            "docker", "network", "create",
+            # bot-bottle attribution pins IPv4 source IPs; it has no IPv6
+            # support. Disable IPv6 explicitly so a daemon that default-enables
+            # it (default-address-pools) can't attach an fdd0::/64 subnet — a
+            # malformed `::1/64` gateway address then trips docker's own
+            # ParseAddr in `network inspect`/`ls`, which poisons every launch
+            # that reads this network's subnet.
+            "--ipv6=false",
+            "--subnet", self._subnet,
+            "--label", f"{_GATEWAY_SUBNET_LABEL}={self._subnet}",
+            self.network,
+        ])
         if proc.returncode != 0 and "already exists" not in proc.stderr:
             raise GatewayError(
                 f"gateway network {self.network} failed to create: {proc.stderr.strip()}"
@@ -139,9 +225,9 @@ class DockerGateway(Gateway):
         # Recreate when the running container's image is stale (a rebuild),
         # so source changes to the gateway's flat daemons take effect — not
         # just when the container is absent.
+        self._ensure_network()
         if self.is_running() and self._running_image_is_current():
             return
-        self._ensure_network()
         # Clear any stale (stopped OR outdated-image) container holding the
         # fixed name, then start fresh. `rm --force` on an absent name is a
         # tolerated no-op.
@@ -154,7 +240,7 @@ class DockerGateway(Gateway):
             # Persist the self-generated CA on the host so it survives both
             # container recreation AND docker volume pruning (agents trust it)
             # — see host_gateway_ca_dir / issue #450.
-            "--volume", f"{host_gateway_ca_dir()}:{MITMPROXY_HOME}",
+            "--volume", f"{self._ca_mount_source}:{MITMPROXY_HOME}",
             # No DB mount: the data plane (egress / supervise / git-gate) reaches
             # the supervise queue over the control-plane RPC and never opens
             # bot-bottle.db, so the gateway container gets no file handle on it
@@ -249,4 +335,4 @@ class DockerGateway(Gateway):
     def provisioning_transport(self) -> GatewayTransport:
         """The exec/cp transport git-gate provisioning stages per-bottle repos +
         deploy keys through (over the docker socket)."""
-        return DockerGatewayTransport(self.name)
+        return DockerGatewayTransport(self.name)

bot_bottle/backend/docker/infra.py

@@ -33,7 +33,7 @@ from .orchestrator import (
     ORCHESTRATOR_NAME,
     ORCHESTRATOR_NETWORK,
 )
-from ...paths import bot_bottle_root
+from ... import resources
 from ...gateway import (
     GATEWAY_IMAGE,
     GATEWAY_NAME,
@@ -50,8 +50,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,8 +66,10 @@ 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,
+        root_mount_source: str | Path | None = None,
+        gateway_ca_mount_source: str | Path | None = None,
         orchestrator_name: str = ORCHESTRATOR_NAME,
         orchestrator_label: str = ORCHESTRATOR_LABEL,
         gateway_name: str = GATEWAY_NAME,
@@ -79,8 +79,14 @@ class DockerInfraService(InfraService):
         self.control_network = control_network
         self.orchestrator_image = orchestrator_image
         self.gateway_image = gateway_image
-        self._repo_root = repo_root
-        self._host_root = host_root or bot_bottle_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()
+        if host_root is not None and root_mount_source is not None:
+            raise ValueError("pass host_root or root_mount_source, not both")
+        self._host_root = host_root
+        self._root_mount_source = root_mount_source
+        self._gateway_ca_mount_source = gateway_ca_mount_source
         self._orchestrator_name = orchestrator_name
         self._orchestrator_label = orchestrator_label
         self._gateway_name = gateway_name
@@ -97,6 +103,7 @@ class DockerInfraService(InfraService):
             control_network=self.control_network,
             repo_root=self._repo_root,
             host_root=self._host_root,
+            root_mount_source=self._root_mount_source,
         )
 
     def gateway(self) -> DockerGateway:
@@ -111,6 +118,7 @@ class DockerInfraService(InfraService):
             network=self.network,
             control_network=self.control_network,
             build_context=self._repo_root,
+            ca_mount_source=self._gateway_ca_mount_source,
         )
 
     def ensure_running(

bot_bottle/backend/docker/launch.py

@@ -33,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,
     )

bot_bottle/backend/docker/orchestrator.py

@@ -15,11 +15,11 @@ import time
 from pathlib import Path
 
 from ... import log
+from ... import resources
 from .util import run_docker
 from ...paths import (
     ORCHESTRATOR_TOKEN_ENV,
     bot_bottle_root,
-    host_orchestrator_token,
 )
 from ...gateway import GatewayError
 from ...orchestrator.lifecycle import (
@@ -42,13 +42,9 @@ ORCHESTRATOR_IMAGE = os.environ.get(
 )
 ORCHESTRATOR_DOCKERFILE = "Dockerfile.orchestrator"
 # Baked as a container label so `ensure_running` can detect whether the running
-# orchestrator is executing the current bind-mounted source.
+# orchestrator image was built from the current source.
 ORCHESTRATOR_SOURCE_HASH_LABEL = "bot-bottle-orchestrator-source-hash"
 
-# The bind-mount path for the live control-plane source inside the container.
-# PYTHONPATH points here so a code change takes effect on the next launch
-# without an image rebuild.
-_SRC_IN_CONTAINER = "/bot-bottle-src"
 # Bot-bottle host-root bind-mount (DB + state) inside the orchestrator. The
 # control plane opens bot-bottle.db under here (via BOT_BOTTLE_ROOT ->
 # host_db_path()); it is the ONLY container with a handle on it (issue #469).
@@ -56,8 +52,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
@@ -72,23 +66,53 @@ 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,
+        root_mount_source: str | Path | None = None,
+        client_host: str | None = None,
+        client_network: str | None = None,
+        bind_host: str | None = None,
         dockerfile: str | None = ORCHESTRATOR_DOCKERFILE,
     ) -> None:
+        if host_root is not None and root_mount_source is not None:
+            raise ValueError("pass host_root or root_mount_source, not both")
         self.image_ref = image_ref
         self.name = name
         self.label = label
         self.port = port
         self.control_network = control_network
-        self._repo_root = repo_root
-        self._host_root = host_root or bot_bottle_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()
+        configured_root = os.environ.get("BOT_BOTTLE_DOCKER_ROOT_MOUNT", "").strip()
+        self._root_mount_source = str(
+            root_mount_source or configured_root or host_root or bot_bottle_root()
+        )
+        configured_network = os.environ.get(
+            "BOT_BOTTLE_DOCKER_CLIENT_NETWORK", ""
+        ).strip()
+        self._client_network = client_network or configured_network or None
+        configured_host = os.environ.get(
+            "BOT_BOTTLE_DOCKER_HOST_ADDRESS", ""
+        ).strip()
+        self._client_host = (
+            client_host or configured_host
+            or (self.name if self._client_network else "127.0.0.1")
+        )
+        # A socket-shared CI runner reaches published ports through its Docker
+        # network rather than its own loopback. Production stays bound to host
+        # loopback unless a caller explicitly selects another client.
+        self._bind_host = bind_host or (
+            "0.0.0.0"
+            if not self._client_network and self._client_host != "127.0.0.1"
+            else "127.0.0.1"
+        )
         self._dockerfile = dockerfile
 
     def url(self) -> str:
-        """Host-side control-plane URL — the orchestrator's published loopback,
-        which the CLI reaches."""
-        return f"http://127.0.0.1:{self.port}"
+        """Control-plane URL reachable by this Docker client."""
+        port = DEFAULT_PORT if self._client_network else self.port
+        return f"http://{self._client_host}:{port}"
 
     def gateway_url(self) -> str:
         """The URL the gateway's data plane resolves policy against — the
@@ -107,6 +131,11 @@ class DockerOrchestrator(Orchestrator):
                 str(self._repo_root)]
         if os.environ.get("BOT_BOTTLE_NO_CACHE"):
             argv.insert(2, "--no-cache")
+        for name, value in resources.image_build_args(
+            self._dockerfile,
+            context=self._repo_root,
+        ).items():
+            argv[-1:-1] = ["--build-arg", f"{name}={value}"]
         proc = run_docker(argv)
         if proc.returncode != 0:
             raise GatewayError(
@@ -119,8 +148,7 @@ class DockerOrchestrator(Orchestrator):
         return self.name in proc.stdout.split()
 
     def _source_current(self, current_hash: str) -> bool:
-        """True iff the running orchestrator was started from the current
-        bind-mounted source."""
+        """True iff the running orchestrator image matches current source."""
         if not self.is_running():
             return False
         proc = run_docker([
@@ -171,7 +199,9 @@ class DockerOrchestrator(Orchestrator):
         fixed-name container first)."""
         self._ensure_control_network()
         run_docker(["docker", "rm", "--force", self.name])
-        _signing_key = host_orchestrator_token()
+        # The signing key comes through the shared provisioning contract (#476),
+        # which fail-closes rather than yield an empty key that would run OPEN.
+        _signing_key = self.control_plane_key()
         proc = run_docker([
             "docker", "run", "--detach",
             "--name", self.name,
@@ -180,15 +210,19 @@ class DockerOrchestrator(Orchestrator):
             # Control network only — agents are never on it, so they have no
             # route to the control plane (the L3 block, not just the JWT).
             "--network", self.control_network,
-            # Host CLI reaches the control plane here (loopback only). The
+            # Host CLI reaches the control plane here (loopback by default).
+            # Socket-shared CI joins the container directly to the job network;
+            # the host-side mapping remains loopback-only in that topology. The
             # orchestrator listens on the fixed DEFAULT_PORT inside the
             # container; self.port is the host-side published port.
-            "--publish", f"127.0.0.1:{self.port}:{DEFAULT_PORT}",
-            # Live control-plane source (code changes without an image rebuild).
-            "--volume", f"{self._repo_root}:{_SRC_IN_CONTAINER}:ro",
-            "--env", f"PYTHONPATH={_SRC_IN_CONTAINER}",
+            "--publish", f"{self._bind_host}:{self.port}:{DEFAULT_PORT}",
+            # The image was rebuilt from `_repo_root` immediately before this
+            # launch. Running its baked package avoids a host-path bind mount,
+            # which is both more production-like and works with socket-shared
+            # CI where the daemon cannot see the job container's workspace.
             # Orchestrator registry DB on the host (sole writer: control plane).
-            "--volume", f"{self._host_root}:{_ROOT_IN_CONTAINER}",
+            # `root_mount_source` may be a host path or a named Docker volume.
+            "--volume", f"{self._root_mount_source}:{_ROOT_IN_CONTAINER}",
             "--env", f"BOT_BOTTLE_ROOT={_ROOT_IN_CONTAINER}",
             # The signing key — held ONLY by the orchestrator (it verifies
             # tokens); the gateway gets the pre-minted `gateway` JWT, never the
@@ -203,6 +237,15 @@ class DockerOrchestrator(Orchestrator):
             raise OrchestratorStartError(
                 f"orchestrator container failed to start: {proc.stderr.strip()}"
             )
+        if self._client_network:
+            proc = run_docker([
+                "docker", "network", "connect", self._client_network, self.name,
+            ])
+            if proc.returncode != 0:
+                raise OrchestratorStartError(
+                    f"orchestrator container failed to join client network "
+                    f"{self._client_network}: {proc.stderr.strip()}"
+                )
 
     def stop(self) -> None:
         """Remove the control-plane container (idempotent)."""

bot_bottle/backend/docker/util.py

@@ -6,12 +6,18 @@ from __future__ import annotations
 
 import os
 from datetime import datetime, timezone
-import re
 import shutil
 import subprocess
 from typing import Iterator
 
+from ... import resources
 from ...log import die, info
+from ...util import slugify as _slugify
+
+
+def slugify(name: str) -> str:
+    """Compatibility wrapper; new generic callers import ``bot_bottle.util``."""
+    return _slugify(name)
 
 
 def run_docker(
@@ -114,20 +120,13 @@ def docker_cp(src: str, dest: str) -> None:
             f"{(result.stderr or '').strip() or '<no stderr>'}")
 
 
-_SLUG_RE = re.compile(r"[^a-z0-9]+")
-
-
-def slugify(name: str) -> str:
-    """Lowercase, non-alnum runs → '-', trimmed. Dies on empty result."""
-    if not name:
-        die("slugify: missing name")
-    slug = _SLUG_RE.sub("-", name.lower()).strip("-")
-    if not slug:
-        die(f"name '{name}' produced an empty slug; use alphanumeric characters")
-    return slug
-
-
-def build_image(ref: str, context: str, *, dockerfile: str = "") -> None:
+def build_image(
+    ref: str,
+    context: str,
+    *,
+    dockerfile: str = "",
+    build_args: dict[str, str] | None = None,
+) -> None:
     """Invokes `docker build` every call. Layer cache makes no-change
     rebuilds cheap; running every time means Dockerfile edits land
     without manual `docker rmi`.
@@ -147,10 +146,61 @@ def build_image(ref: str, context: str, *, dockerfile: str = "") -> None:
         args.append("--no-cache")
     if dockerfile:
         args.extend(["-f", dockerfile])
+    effective_build_args = resources.image_build_args(
+        dockerfile,
+        context=context,
+    ) if dockerfile else {}
+    effective_build_args.update(build_args or {})
+    for name, value in effective_build_args.items():
+        args.extend(["--build-arg", f"{name}={value}"])
     args.append(context)
     subprocess.run(args, check=True)
 
 
+def image_id(ref: str) -> str:
+    """Return the exact content-addressed ID for a local image.
+
+    This is used when one locally built image is another Dockerfile's base:
+    passing the ID prevents a mutable tag from being resolved between builds.
+    """
+    result = run_docker(["docker", "image", "inspect", "--format", "{{.Id}}", ref])
+    image = result.stdout.strip()
+    if result.returncode != 0 or not image.startswith("sha256:"):
+        detail = (result.stderr or result.stdout or "").strip()
+        die(f"could not resolve exact image ID for {ref!r}: {detail or '<no detail>'}")
+    return image
+
+
+def pinned_local_image_ref(ref: str) -> str:
+    """Give a local image a content-derived tag and verify the tag resolves
+    back to the same image ID.
+
+    BuildKit treats a bare ``sha256:...`` ID in ``FROM`` as a registry
+    repository name. A tag whose complete suffix is the local image ID remains
+    resolvable by BuildKit, while the post-tag inspection keeps the handoff
+    fail-closed.
+    """
+    image = image_id(ref)
+    digest = image.removeprefix("sha256:")
+    if len(digest) != 64 or any(char not in "0123456789abcdef" for char in digest):
+        die(f"could not derive a local base tag from invalid image ID {image!r}")
+
+    repository = ref.split("@", 1)[0]
+    last_slash = repository.rfind("/")
+    last_colon = repository.rfind(":")
+    if last_colon > last_slash:
+        repository = repository[:last_colon]
+    pinned_ref = f"{repository}:sha256-{digest}"
+
+    result = run_docker(["docker", "image", "tag", image, pinned_ref])
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip()
+        die(f"could not tag exact local image {image}: {detail or '<no detail>'}")
+    if image_id(pinned_ref) != image:
+        die(f"content-derived local tag {pinned_ref!r} did not resolve to {image}")
+    return pinned_ref
+
+
 def verify_agent_image(image: str, argv: tuple[str, ...]) -> None:
     """Run `argv` inside a throwaway container of a freshly built agent
     image and die loudly if it fails, instead of shipping an image

bot_bottle/backend/egress_apply.py

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

bot_bottle/backend/firecracker/image_builder.py

@@ -19,12 +19,14 @@ from __future__ import annotations
 import fcntl
 import hashlib
 import os
+import shlex
 import shutil
 import subprocess
 from contextlib import contextmanager
 from pathlib import Path
 from typing import Generator
 
+from ... import resources
 from ...log import die, info
 from . import util
 from .infra import FirecrackerInfraService
@@ -55,6 +57,11 @@ def _rootfs_digest(dockerfile: Path) -> str:
     h = hashlib.sha256()
     h.update(_dockerfile_hash(dockerfile).encode())
     h.update(b"\0")
+    for name, value in resources.image_build_args(dockerfile).items():
+        h.update(name.encode())
+        h.update(b"=")
+        h.update(value.encode())
+        h.update(b"\0")
     h.update(util._GUEST_INIT.encode())
     return h.hexdigest()[:16]
 
@@ -147,7 +154,13 @@ def _build_in_infra(
         if prep.returncode != 0:
             die(f"preparing build dir in the infra VM failed: {prep.stderr.strip()}")
         _send_dockerfile(key, ip, dockerfile, ctx)
-        _buildah_build(key, ip, ctx, tag)
+        _buildah_build(
+            key,
+            ip,
+            ctx,
+            tag,
+            resources.image_build_args(dockerfile),
+        )
         _smoke_test(key, ip, tag, smoke_ctr, smoke_test)
         _stream_rootfs(key, ip, tag, export_ctr, base)
     finally:
@@ -184,15 +197,26 @@ def _send_dockerfile(private_key: Path, guest_ip: str, dockerfile: Path, ctx: st
             f"{proc.stderr.decode(errors='replace').strip()}")
 
 
-def _buildah_build(private_key: Path, guest_ip: str, ctx: str, tag: str) -> None:
+def _buildah_build(
+    private_key: Path,
+    guest_ip: str,
+    ctx: str,
+    tag: str,
+    build_args: dict[str, str],
+) -> None:
     # Stream buildah's step-by-step output straight to our stderr (like the
     # docker backend's `docker build`), so a long first build (base pull +
     # apt/npm installs) shows live progress instead of a silent wait. The
     # remote stderr is where buildah writes its `STEP i/n` lines.
     info(f"buildah build {tag} in the infra VM (streaming output)")
+    arg_flags = " ".join(
+        f"--build-arg {shlex.quote(f'{name}={value}')}"
+        for name, value in build_args.items()
+    )
     rc = _ssh_streamed(
         private_key, guest_ip,
-        f"buildah build {_BUILD_FLAGS} -t {tag} -f {ctx}/Dockerfile {ctx}/ctx",
+        f"buildah build {_BUILD_FLAGS} {arg_flags} "
+        f"-t {tag} -f {ctx}/Dockerfile {ctx}/ctx",
         timeout=_BUILD_TIMEOUT_SECONDS,
     )
     if rc != 0:

bot_bottle/backend/firecracker/infra_artifact.py

@@ -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,15 +45,21 @@ 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.
 ROLES = ("orchestrator", "gateway")
-_DOCKERFILES = {
-    "orchestrator": ("Dockerfile.orchestrator", "Dockerfile.orchestrator.fc"),
-    "gateway": ("Dockerfile.gateway",),
+_BUILD_INPUTS = {
+    "orchestrator": (
+        "image-build-args.json",
+        "Dockerfile.orchestrator",
+        "Dockerfile.orchestrator.fc",
+    ),
+    "gateway": (
+        "image-build-args.json",
+        "Dockerfile.gateway",
+        "requirements.gateway.lock",
+    ),
 }
 
 _DEFAULT_BASE = "https://gitea.dideric.is"
@@ -74,7 +81,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 +96,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"
@@ -100,7 +109,7 @@ def infra_artifact_version(
         h.update(str(path.relative_to(repo_root)).encode())
         h.update(b"\0")
         h.update(path.read_bytes())
-    for name in _DOCKERFILES[role]:
+    for name in _BUILD_INPUTS[role]:
         h.update(name.encode())
         h.update(b"\0")
         h.update((repo_root / name).read_bytes())

bot_bottle/backend/firecracker/infra_vm.py

@@ -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,18 @@ 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")
+    orchestrator_base = docker_mod.pinned_local_image_ref(_ORCHESTRATOR_IMAGE)
     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",
+        build_args={"ORCHESTRATOR_BASE_IMAGE": orchestrator_base},
+    )
 
 
 def build_rootfs_dir(role: str) -> Path:

bot_bottle/backend/firecracker/orchestrator.py

@@ -21,7 +21,6 @@ import time
 from pathlib import Path
 
 from ...log import die, info
-from ...paths import host_orchestrator_token
 from ...orchestrator.lifecycle import (
     DEFAULT_STARTUP_TIMEOUT_SECONDS,
     Orchestrator,
@@ -108,11 +107,13 @@ class FirecrackerOrchestrator(Orchestrator):
             data_drive=self._ensure_registry_volume(),
         )
         # Push the host-canonical signing key (the init waits for it before
-        # starting the control plane). The host token file stays the single
-        # source of truth, so a co-running docker/macOS control plane keeps
-        # working; the guest verifies tokens with the same key the CLI signs from.
+        # starting the control plane). It comes through the shared provisioning
+        # contract (#476) — the same host token file every backend uses, so a
+        # co-running docker/macOS control plane keeps working and the guest
+        # verifies tokens with the same key the CLI signs from; fail-closed, so
+        # the guest is never handed an empty key that would run it OPEN.
         infra_vm.push_secret(
-            vm, host_orchestrator_token(), infra_vm._GUEST_SIGNING_KEY_PATH,
+            vm, self.control_plane_key(), infra_vm._GUEST_SIGNING_KEY_PATH,
             "the control-plane signing key to the orchestrator VM "
             "(its control plane will not start)",
         )

bot_bottle/backend/firecracker/setup.py

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

bot_bottle/backend/macos_container/gateway.py

@@ -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).

bot_bottle/backend/macos_container/infra.py

@@ -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

bot_bottle/backend/macos_container/launch.py

@@ -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
 
 
@@ -108,7 +107,8 @@ def _layer_nested_containers(
     """
     if not plan.nested_containers:
         return agent_image
-    derived = f"{agent_image}{nested_containers_mod.IMAGE_SUFFIX}"
+    pinned_base = container_mod.pinned_local_image_ref(agent_image)
+    derived = f"{pinned_base}{nested_containers_mod.IMAGE_SUFFIX}"
     if plan.spec.image_policy == "cached":
         if not container_mod.image_exists(derived):
             die(
@@ -117,7 +117,10 @@ def _layer_nested_containers(
             )
         info(f"using cached nested-container image {derived!r}")
         return derived
-    return nested_containers_mod.build_image(agent_image, container_mod.build_image)
+    return nested_containers_mod.build_image(
+        pinned_base,
+        container_mod.build_image,
+    )
 
 
 @contextmanager

bot_bottle/backend/macos_container/nested_containers.py

@@ -55,7 +55,7 @@ _GUEST_DEVICES = ("/dev/fuse", "/dev/net/tun")
 
 
 def build_image(
-    base_image: str,
+    pinned_base: str,
     build: Callable[..., None],
 ) -> str:
     """Layer the nested-container tooling onto an already-built agent image.
@@ -66,14 +66,15 @@ def build_image(
     # TODO(#394): replace this hand-rolled Dockerfile with a docker-layer
     # abstraction once that infrastructure exists.
     """
-    image = f"{base_image}{IMAGE_SUFFIX}"
+    image = f"{pinned_base}{IMAGE_SUFFIX}"
     init_script = Path(__file__).with_name("nested-containers-init.sh")
     with tempfile.TemporaryDirectory(prefix="bot-bottle-nested-containers.") as tmp:
         context = Path(tmp)
         shutil.copy2(init_script, context / "nested-containers-init.sh")
         (context / "Dockerfile").write_text(
-            "FROM docker:28-cli AS docker_cli\n"
-            f"FROM {base_image}\n"
+            "ARG DOCKER_CLI_BASE_IMAGE\n"
+            "FROM ${DOCKER_CLI_BASE_IMAGE} AS docker_cli\n"
+            f"FROM {pinned_base}\n"
             "USER root\n"
             "COPY --from=docker_cli /usr/local/bin/docker /usr/local/bin/docker\n"
             "COPY --from=docker_cli /usr/local/libexec/docker/cli-plugins/"

bot_bottle/backend/macos_container/orchestrator.py

@@ -18,10 +18,8 @@ import urllib.request
 from pathlib import Path
 
 from ... import log
-from ...paths import (
-    ORCHESTRATOR_TOKEN_ENV,
-    host_orchestrator_token,
-)
+from ... import resources
+from ...paths import ORCHESTRATOR_TOKEN_ENV
 from ...orchestrator.lifecycle import (
     DEFAULT_HEALTH_TIMEOUT_SECONDS,
     DEFAULT_PORT,
@@ -48,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):
@@ -64,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
@@ -72,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:
@@ -134,7 +133,9 @@ class MacosOrchestrator(Orchestrator):
 
     def _run_container(self, current_hash: str) -> None:
         container_mod.force_remove_container(self.name)
-        _signing_key = host_orchestrator_token()
+        # The signing key comes through the shared provisioning contract (#476),
+        # which fail-closes rather than yield an empty key that would run OPEN.
+        _signing_key = self.control_plane_key()
         argv = [
             "container", "run", "--detach",
             "--name", self.name,

bot_bottle/backend/macos_container/util.py

@@ -13,6 +13,7 @@ import time
 from datetime import datetime, timezone
 from typing import Iterable
 
+from ... import resources
 from ...log import die, info
 
 
@@ -60,7 +61,13 @@ def dns_server() -> str:
     return _host_ipv4_dns() or _DEFAULT_DNS
 
 
-def build_image(ref: str, context: str, *, dockerfile: str = "") -> None:
+def build_image(
+    ref: str,
+    context: str,
+    *,
+    dockerfile: str = "",
+    build_args: dict[str, str] | None = None,
+) -> None:
     """Build an OCI image with Apple's BuildKit-backed `container build`.
 
     Set `BOT_BOTTLE_NO_CACHE=1` (the `start --no-cache` flag) to force
@@ -83,6 +90,13 @@ def build_image(ref: str, context: str, *, dockerfile: str = "") -> None:
         if not os.path.isabs(dockerfile):
             dockerfile = os.path.join(context, dockerfile)
         args.extend(["-f", dockerfile])
+    effective_build_args = resources.image_build_args(
+        dockerfile,
+        context=context,
+    ) if dockerfile else {}
+    effective_build_args.update(build_args or {})
+    for name, value in effective_build_args.items():
+        args.extend(["--build-arg", f"{name}={value}"])
     args.append(context)
     subprocess.run(args, check=True)
 
@@ -668,6 +682,40 @@ def image_id(ref: str) -> str:
     raise AssertionError("unreachable")
 
 
+def pinned_local_image_ref(ref: str) -> str:
+    """Tag a local image with its complete content ID for a stable ``FROM``.
+
+    Agent images are immediately used as bases for the optional
+    nested-containers layer. A content-derived tag prevents another concurrent
+    build from moving the provider's ordinary ``:latest`` tag between those
+    two builds.
+    """
+    image = image_id(ref)
+    digest = image.removeprefix("sha256:")
+    if len(digest) != 64 or any(char not in "0123456789abcdef" for char in digest):
+        die(f"could not derive a local base tag from invalid image ID {image!r}")
+    repository = ref.split("@", 1)[0]
+    last_slash = repository.rfind("/")
+    last_colon = repository.rfind(":")
+    if last_colon > last_slash:
+        repository = repository[:last_colon]
+    pinned_ref = f"{repository}:sha256-{digest}"
+    result = subprocess.run(
+        [_CONTAINER, "image", "tag", image, pinned_ref],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        die(
+            f"could not tag exact local image {image}: "
+            f"{(result.stderr or result.stdout or '').strip() or '<no detail>'}"
+        )
+    if image_id(pinned_ref) != image:
+        die(f"content-derived local tag {pinned_ref!r} did not resolve to {image}")
+    return pinned_ref
+
+
 def image_created_at(ref: str) -> datetime | None:
     """Return the image creation timestamp as an aware UTC datetime, or None
     when the field is absent or unparseable (e.g. FROM-scratch images, images

bot_bottle/backend/preparation.py

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

bot_bottle/backend/resolve_common.py

@@ -24,12 +24,14 @@ from ..bottle_state import (
     supervise_state_dir,
     write_metadata,
 )
-from ..egress import Egress, EgressPlan
+from ..egress import Egress, EgressPlan, egress_forge_routes
 from ..git_gate import GitGate, GitGatePlan
 from ..log import die
 from ..manifest import Manifest, ManifestBottle
+from ..manifest.forge import render_forge_guidance
 from ..supervisor.plan import SupervisePlan
 from ..orchestrator.supervisor import Supervisor
+from ..util import slugify
 from . import BottleSpec
 
 
@@ -44,8 +46,7 @@ def mint_slug(spec: BottleSpec) -> str:
     if spec.identity:
         return spec.identity
     if spec.label:
-        from .docker import util as docker_mod
-        return docker_mod.slugify(spec.label)
+        return slugify(spec.label)
     return bottle_identity(spec.agent_name)
 
 
@@ -71,12 +72,21 @@ def write_launch_metadata(
 
 def prepare_agent_state_dir(slug: str, manifest: Manifest) -> tuple[Path, Path]:
     """Create the agent state subdir, write the prompt file.
-    Returns (agent_dir, prompt_file)."""
+    Returns (agent_dir, prompt_file).
+
+    For repositories associated with a forge, appends generated, non-secret
+    provider-specific workflow guidance to the prompt (PRD
+    0082). The guidance carries neither the
+    token value nor its `token_secret` name."""
     agent = manifest.agent
     agent_dir = agent_state_dir(slug)
     agent_dir.mkdir(parents=True, exist_ok=True)
     prompt_file = agent_dir / "prompt.txt"
-    prompt_file.write_text(agent.prompt or "")
+    prompt = agent.prompt or ""
+    guidance = render_forge_guidance(manifest.forge_associations)
+    if guidance:
+        prompt = f"{prompt.rstrip()}\n\n{guidance}" if prompt.strip() else guidance
+    prompt_file.write_text(prompt)
     prompt_file.chmod(0o600)
     return agent_dir, prompt_file
 
@@ -88,11 +98,18 @@ def prepare_git_gate(bottle: ManifestBottle, slug: str) -> GitGatePlan:
 
 
 def prepare_egress(
-    bottle: ManifestBottle, slug: str, provision: AgentProvisionPlan,
+    manifest: Manifest, slug: str, provision: AgentProvisionPlan,
 ) -> EgressPlan:
+    """Build the egress plan, adding a scoped, proxy-held Gitea API route for
+    each forge alias referenced by a selected git-gate repo (PRD
+    0082). The token is resolved from the host
+    env at launch and never enters the bottle."""
     egress_dir = egress_state_dir(slug)
     egress_dir.mkdir(parents=True, exist_ok=True)
-    return Egress().prepare(bottle, slug, egress_dir, provision.egress_routes)
+    forge_routes = egress_forge_routes(manifest.forge_associations)
+    return Egress().prepare(
+        manifest.bottle, slug, egress_dir, provision.egress_routes, forge_routes,
+    )
 
 
 def prepare_supervise(bottle: ManifestBottle, slug: str) -> SupervisePlan | None:

bot_bottle/cli/commands/__init__.py

@@ -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"]

bot_bottle/cli/commands/doctor.py

@@ -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

bot_bottle/cli/commands/help.py

@@ -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")

bot_bottle/cli/commands/start.py

@@ -25,12 +25,11 @@ from typing import Callable
 from ...agent_provider import get_provider, runtime_for
 from ...backend import (
     Bottle,
+    BottlePlan,
     BottleSpec,
     enumerate_active_agents,
     get_bottle_backend,
 )
-from ...backend.docker import util as docker_mod
-from ...backend.docker.bottle_plan import DockerBottlePlan
 from ...bottle_state import (
     cleanup_state,
     is_preserved,
@@ -40,7 +39,7 @@ from ...image_cache import StaleImageError
 from ...log import info, die
 from ...manifest import Manifest, ManifestIndex
 from ..constants import PROG
-from ...util import read_tty_line
+from ...util import read_tty_line, slugify
 from .. import tui
 
 
@@ -129,7 +128,7 @@ def cmd_start(argv: list[str]) -> int:
         if not manifest.all_agent_names:
             print(
                 "bot-bottle: no agents defined. "
-                "Add an agent to ~/.bot-bottle/agents/ or ./bot-bottle/agents/ to get started.",
+                "Add an agent to ~/.bot-bottle/agents/ to get started.",
                 file=sys.stderr,
             )
             return 1
@@ -257,10 +256,10 @@ def _uniquify_label_headless(label: str) -> str:
     logging the chosen label. Orchestrators fire-and-forget many bottles,
     so silently picking a free name beats erroring on every collision."""
     active_slugs = {a.slug for a in enumerate_active_agents()}
-    if docker_mod.slugify(label) not in active_slugs:
+    if slugify(label) not in active_slugs:
         return label
     n = 2
-    while docker_mod.slugify(f"{label}-{n}") in active_slugs:
+    while slugify(f"{label}-{n}") in active_slugs:
         n += 1
     chosen = f"{label}-{n}"
     info(f"label '{label}' already in use; using '{chosen}'")
@@ -274,11 +273,11 @@ def prepare_with_preflight(
     spec: BottleSpec,
     *,
     stage_dir: Path,
-    render_preflight: Callable[[DockerBottlePlan, str], None],
+    render_preflight: Callable[[BottlePlan, str], None],
     prompt_yes: Callable[[], bool],
     dry_run: bool = False,
     backend_name: str | None = None,
-) -> tuple[DockerBottlePlan | None, str]:
+) -> tuple[BottlePlan | None, str]:
     """Run `backend.prepare`, render the preflight summary via the
     injected callable, prompt y/N via the injected callable.
 
@@ -384,12 +383,9 @@ def _peek_agent_bottle(manifest: ManifestIndex, agent_name: str) -> str:
     from ...manifest.loader import scan_agent_names
     from ...yaml_subset import YamlSubsetError, parse_frontmatter
 
+    # Agents are home-only (PRD 0082).
     home_agents = scan_agent_names(manifest.home_md / "agents")
-    cwd_agents: dict[str, Path] = {}
-    if manifest.cwd_md is not None:
-        cwd_agents = scan_agent_names(manifest.cwd_md / "agents")
-    merged = {**home_agents, **cwd_agents}
-    path = merged.get(agent_name)
+    path = home_agents.get(agent_name)
     if path is None:
         return ""
     try:
@@ -405,7 +401,7 @@ def _resolve_unique_label(label: str, color: str) -> tuple[str, str]:
     in use among running bottles.  Passes through unchanged when no
     collision is found on the first check."""
     while True:
-        slug_candidate = docker_mod.slugify(label)
+        slug_candidate = slugify(label)
         active_slugs = {a.slug for a in enumerate_active_agents()}
         if slug_candidate not in active_slugs:
             return label, color
@@ -432,7 +428,7 @@ def _select_image_policy() -> str | None:
 
 
 def _text_render_preflight():
-    def _render(plan: DockerBottlePlan, backend_name: str) -> None:
+    def _render(plan: BottlePlan, backend_name: str) -> None:
         print(file=sys.stderr)
         print(f"backend: {backend_name}", file=sys.stderr)
         print(_manifest_to_yaml(plan.manifest), file=sys.stderr)
@@ -489,13 +485,19 @@ def _manifest_to_yaml(manifest: Manifest) -> str:
         lines.append("  skills:")
         for s in agent.skills:
             lines.append(f"    - {s}")
-    if not agent.git_user.is_empty():
-        lines.append("  git-gate:")
-        lines.append("    user:")
-        if agent.git_user.name:
-            lines.append(f"      name: {agent.git_user.name}")
-        if agent.git_user.email:
-            lines.append(f"      email: {agent.git_user.email}")
+    if agent.author is not None:
+        lines.append("  author:")
+        lines.append(f"    name: {agent.author.name}")
+        lines.append(f"    email: {agent.author.email}")
+    if agent.forge_accounts:
+        lines.append("  forge-accounts:")
+        for alias, acct in sorted(agent.forge_accounts.items()):
+            lines.append(f"    {alias}:")
+            lines.append(f"      url: {acct.url}")
+            lines.append("      auth:")
+            lines.append(f"        type: {acct.auth_type}")
+            # token_secret name is host config; show the name, never a value.
+            lines.append(f"        token_secret: {acct.token_secret}")
 
     bottle = manifest.bottle
     lines.append("bottle:")
@@ -511,20 +513,14 @@ def _manifest_to_yaml(manifest: Manifest) -> str:
         for k, v in sorted(bottle.env.items()):
             lines.append(f"    {k}: {v}")
 
-    has_git_gate = not bottle.git_user.is_empty() or bottle.git
-    if has_git_gate:
+    if bottle.git:
         lines.append("  git-gate:")
-        if not bottle.git_user.is_empty():
-            lines.append("    user:")
-            if bottle.git_user.name:
-                lines.append(f"      name: {bottle.git_user.name}")
-            if bottle.git_user.email:
-                lines.append(f"      email: {bottle.git_user.email}")
-        if bottle.git:
-            lines.append("    repos:")
-            for entry in bottle.git:
-                lines.append(f"      {entry.Name}:")
-                lines.append(f"        url: {entry.Upstream}")
+        lines.append("    repos:")
+        for entry in bottle.git:
+            lines.append(f"      {entry.Name}:")
+            lines.append(f"        url: {entry.Upstream}")
+            if entry.Forge:
+                lines.append(f"        forge: {entry.Forge}")
 
     if bottle.egress.routes:
         lines.append("  egress:")

bot_bottle/cli/commands/supervise.py

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

bot_bottle/cli/tui.py

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

bot_bottle/contrib/claude/Dockerfile

@@ -8,9 +8,17 @@
 # Layer ordering is deliberate: the npm install lives in its own layer so
 # changes to the rest of the repo (or to the CMD) don't bust it.
 
-# Current Node LTS; slim variant keeps the image small while still
-# providing apt-get for any future additions.
-FROM node:22-trixie-slim
+# Version-qualified Node LTS, pinned to its multi-architecture manifest.
+ARG NODE_BASE_IMAGE
+FROM ${NODE_BASE_IMAGE}
+
+ARG DEBIAN_SNAPSHOT=20260724T000000Z
+RUN sed -i \
+      -e "s|http://deb.debian.org/debian-security|http://snapshot.debian.org/archive/debian-security/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|https://deb.debian.org/debian-security|http://snapshot.debian.org/archive/debian-security/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|http://deb.debian.org/debian|http://snapshot.debian.org/archive/debian/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|https://deb.debian.org/debian|http://snapshot.debian.org/archive/debian/${DEBIAN_SNAPSHOT}|g" \
+      /etc/apt/sources.list.d/debian.sources
 
 # Install runtime system deps. claude-code shells out to git for several
 # features (status checks, commits, PR creation) — without git in the
@@ -20,7 +28,7 @@ FROM node:22-trixie-slim
 # HTTPS_PROXY-aware tool (curl itself, plus anything that shells out
 # to it) works against egress's bumped TLS without the agent needing
 # local DNS.
-RUN apt-get update \
+RUN apt-get -o Acquire::Check-Valid-Until=false update \
   && apt-get install -y --no-install-recommends \
   git \
   ca-certificates \
@@ -35,15 +43,17 @@ RUN apt-get update \
 # (claude-code is a Node CLI), but is convenient for the agent to
 # shell out to for ad-hoc scripts. Kept on its own layer so it can
 # be moved to a downstream image if the base ever needs to shrink.
-RUN apt-get update \
+RUN apt-get -o Acquire::Check-Valid-Until=false update \
   && apt-get install -y --no-install-recommends python3 python3-pip python3-venv \
   && rm -rf /var/lib/apt/lists/*
 
-# Install claude-code globally. Pinned to the version verified in the v1
-# build (`claude --version` returns 2.1.126). Bump deliberately when
-# rolling forward; an unpinned install would mean rebuilds silently pick
-# up new behavior.
-RUN npm install -g --no-fund --no-audit @anthropic-ai/claude-code@2.1.172 \
+# Install from the committed npm lock. `npm ci` verifies every registry
+# artifact against its lockfile integrity and refuses dependency drift.
+COPY bot_bottle/contrib/claude/package.json \
+     bot_bottle/contrib/claude/package-lock.json /opt/claude/
+RUN cd /opt/claude \
+  && npm ci --omit=dev --no-fund --no-audit \
+  && ln -s /opt/claude/node_modules/.bin/claude /usr/local/bin/claude \
   && npm cache clean --force
 
 # Git reads both ~/.gitconfig and ~/.config/git/config. Keep its XDG config

bot_bottle/contrib/claude/package-lock.json

@@ -0,0 +1,140 @@
+{
+  "name": "bot-bottle-claude-image",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "bot-bottle-claude-image",
+      "dependencies": {
+        "@anthropic-ai/claude-code": "2.1.172"
+      }
+    },
+    "node_modules/@anthropic-ai/claude-code": {
+      "version": "2.1.172",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-2.1.172.tgz",
+      "integrity": "sha512-SfwC+5fQcmNbvvm+1vLiZbfUxt0PQz9lbXapj9+FI+XY/2e+3zgteBM4JFEXBjULZj1DtZXHmKtAROUrMM9GZg==",
+      "hasInstallScript": true,
+      "license": "SEE LICENSE IN README.md",
+      "bin": {
+        "claude": "bin/claude.exe"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "@anthropic-ai/claude-code-darwin-arm64": "2.1.172",
+        "@anthropic-ai/claude-code-darwin-x64": "2.1.172",
+        "@anthropic-ai/claude-code-linux-arm64": "2.1.172",
+        "@anthropic-ai/claude-code-linux-arm64-musl": "2.1.172",
+        "@anthropic-ai/claude-code-linux-x64": "2.1.172",
+        "@anthropic-ai/claude-code-linux-x64-musl": "2.1.172",
+        "@anthropic-ai/claude-code-win32-arm64": "2.1.172",
+        "@anthropic-ai/claude-code-win32-x64": "2.1.172"
+      }
+    },
+    "node_modules/@anthropic-ai/claude-code-darwin-arm64": {
+      "version": "2.1.172",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-darwin-arm64/-/claude-code-darwin-arm64-2.1.172.tgz",
+      "integrity": "sha512-pBRgDo8PAgbt2aE4oc6ZrKdOa/Ax36RAduhLCaI8NWD3a0RDb5mETzQciQLwnuenk0bs27vIRh9Yg1jAYG/0+A==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@anthropic-ai/claude-code-darwin-x64": {
+      "version": "2.1.172",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-darwin-x64/-/claude-code-darwin-x64-2.1.172.tgz",
+      "integrity": "sha512-vSgibgeCyvCFiLJSXu/sgcd3L/tUjSiS/tfS9rJLXUjElw8satMJhA5pqPUiBmKMflOWKMufbZgzXvLx+OhvFw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@anthropic-ai/claude-code-linux-arm64": {
+      "version": "2.1.172",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-arm64/-/claude-code-linux-arm64-2.1.172.tgz",
+      "integrity": "sha512-Ql7AbyaXnlA6NwDUaQGO7ZZis21rMjYjbKzpksMCvY35CmsJqanYgbYSn/rE83u/tZpKo+NqOv+bWEDSzsZ02w==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@anthropic-ai/claude-code-linux-arm64-musl": {
+      "version": "2.1.172",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-arm64-musl/-/claude-code-linux-arm64-musl-2.1.172.tgz",
+      "integrity": "sha512-Pa9mGGmp8QCRC2j1cgcWRRkwsK1x4bPsS3CcLRd936Op0k5et62tD3qIYhUPQOIxeuxe9Tt/y7lX1cx7JTDxyA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@anthropic-ai/claude-code-linux-x64": {
+      "version": "2.1.172",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-x64/-/claude-code-linux-x64-2.1.172.tgz",
+      "integrity": "sha512-RYCY9EHkmtoAlwBKcWRzGIhuus+GM2CIVCfU81cTQAwDcCHunoBeFn3NqAcFV1VKb4dk9TRarAmQcWMKJrpPig==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@anthropic-ai/claude-code-linux-x64-musl": {
+      "version": "2.1.172",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-x64-musl/-/claude-code-linux-x64-musl-2.1.172.tgz",
+      "integrity": "sha512-1NflAnV/MqIlD4rzlGDVsJgGK2xJ2ldVd5pkcbu7PsDJBW5dzKYVa4PmD0715K8Yiji8jQovh/nhIo6gYyTfVQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@anthropic-ai/claude-code-win32-arm64": {
+      "version": "2.1.172",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-win32-arm64/-/claude-code-win32-arm64-2.1.172.tgz",
+      "integrity": "sha512-Gj8mIbHDDSGWnoriqB1Jt1uH6cvNBFDQBtIYarCcv0fs+QGCEP6qm2GIaKqxAbwkUaLT0sCW/7+ukvkNdSltuQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@anthropic-ai/claude-code-win32-x64": {
+      "version": "2.1.172",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-win32-x64/-/claude-code-win32-x64-2.1.172.tgz",
+      "integrity": "sha512-OkheFwagiCEKaO2Sb0j3JTO1NrcR3zTlFik/AN+yQPefhUIGP6vHQDbBG5ksuFe+Dyd9s+P95OUh8WDhccb+Ng==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    }
+  }
+}

bot_bottle/contrib/claude/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "bot-bottle-claude-image",
+  "private": true,
+  "dependencies": {
+    "@anthropic-ai/claude-code": "2.1.172"
+  }
+}

bot_bottle/contrib/codex/Dockerfile

@@ -3,9 +3,22 @@
 # Mirrors the default Claude image shape: Node LTS, git/network tooling,
 # non-root node user, and the provider CLI installed for that user.
 
-FROM node:22-trixie-slim
+ARG NODE_BASE_IMAGE
+FROM ${NODE_BASE_IMAGE}
 
-RUN apt-get update \
+# Remote-control requires the standalone package layout. Keep this exact release
+# in sync with the committed upstream archive checksums.
+ARG CODEX_VERSION=0.145.0
+
+ARG DEBIAN_SNAPSHOT=20260724T000000Z
+RUN sed -i \
+      -e "s|http://deb.debian.org/debian-security|http://snapshot.debian.org/archive/debian-security/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|https://deb.debian.org/debian-security|http://snapshot.debian.org/archive/debian-security/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|http://deb.debian.org/debian|http://snapshot.debian.org/archive/debian/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|https://deb.debian.org/debian|http://snapshot.debian.org/archive/debian/${DEBIAN_SNAPSHOT}|g" \
+      /etc/apt/sources.list.d/debian.sources
+
+RUN apt-get -o Acquire::Check-Valid-Until=false update \
   && apt-get install -y --no-install-recommends \
   git \
   ca-certificates \
@@ -19,7 +32,7 @@ RUN apt-get update \
 # (codex is a Node CLI), but is convenient for the agent to shell
 # out to for ad-hoc scripts. Kept on its own layer so it can be
 # moved to a downstream image if the base ever needs to shrink.
-RUN apt-get update \
+RUN apt-get -o Acquire::Check-Valid-Until=false update \
   && apt-get install -y --no-install-recommends python3 python3-pip python3-venv \
   && rm -rf /var/lib/apt/lists/*
 
@@ -30,10 +43,29 @@ WORKDIR /home/node
 
 ENV PATH="/home/node/.local/bin:${PATH}"
 
-# Remote-control support requires the standalone Codex install layout
-# under ~/.codex/packages/standalone/current. The npm package can run
-# the TUI, but remote-control commands expect this installer-owned path.
-RUN mkdir -p /home/node/.codex \
-  && curl -fsSL https://chatgpt.com/codex/install.sh | sh
+# Install the exact standalone release archive selected by the target
+# architecture. The checksum list is copied from the immutable upstream release
+# and committed so a rebuild cannot silently accept changed release bytes.
+COPY --chown=node:node bot_bottle/contrib/codex/codex-package_SHA256SUMS /tmp/codex-package_SHA256SUMS
+RUN case "$(dpkg --print-architecture)" in \
+      amd64) codex_target=x86_64-unknown-linux-musl ;; \
+      arm64) codex_target=aarch64-unknown-linux-musl ;; \
+      *) echo "unsupported Codex architecture: $(dpkg --print-architecture)" >&2; exit 1 ;; \
+    esac \
+  && codex_asset="codex-package-${codex_target}.tar.gz" \
+  && codex_sha256="$(awk -v asset="${codex_asset}" '$2 == asset { print $1 }' /tmp/codex-package_SHA256SUMS)" \
+  && test -n "${codex_sha256}" \
+  && curl -fsSL \
+      "https://github.com/openai/codex/releases/download/rust-v${CODEX_VERSION}/${codex_asset}" \
+      -o "/tmp/${codex_asset}" \
+  && echo "${codex_sha256}  /tmp/${codex_asset}" | sha256sum -c - \
+  && codex_release="/home/node/.codex/packages/standalone/releases/${CODEX_VERSION}-${codex_target}" \
+  && mkdir -p "${codex_release}" /home/node/.local/bin \
+  && tar -xzf "/tmp/${codex_asset}" -C "${codex_release}" \
+  && ln -s bin/codex "${codex_release}/codex" \
+  && ln -s "${codex_release}" /home/node/.codex/packages/standalone/current \
+  && ln -s /home/node/.codex/packages/standalone/current/bin/codex /home/node/.local/bin/codex \
+  && rm "/tmp/${codex_asset}" \
+  && test "$(codex --version)" = "codex-cli ${CODEX_VERSION}"
 
 CMD ["codex"]

bot_bottle/contrib/codex/codex-package_SHA256SUMS

@@ -0,0 +1,2 @@
+54f79a05aba6f9abf8ef988abcae8bf2fcefba20beb549b4ff2b3acdb2cb6f54  codex-package-aarch64-unknown-linux-musl.tar.gz
+71a28d362c96ac9829bf8203a2c71be451aeb726adb843167fdaf0eae8fe7dd9  codex-package-x86_64-unknown-linux-musl.tar.gz

bot_bottle/contrib/pi/Dockerfile

@@ -2,9 +2,18 @@
 #
 # Node LTS, git/network tooling, and the Pi coding-agent CLI installed globally.
 
-FROM node:22-trixie-slim
+ARG NODE_BASE_IMAGE
+FROM ${NODE_BASE_IMAGE}
 
-RUN apt-get update \
+ARG DEBIAN_SNAPSHOT=20260724T000000Z
+RUN sed -i \
+      -e "s|http://deb.debian.org/debian-security|http://snapshot.debian.org/archive/debian-security/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|https://deb.debian.org/debian-security|http://snapshot.debian.org/archive/debian-security/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|http://deb.debian.org/debian|http://snapshot.debian.org/archive/debian/${DEBIAN_SNAPSHOT}|g" \
+      -e "s|https://deb.debian.org/debian|http://snapshot.debian.org/archive/debian/${DEBIAN_SNAPSHOT}|g" \
+      /etc/apt/sources.list.d/debian.sources
+
+RUN apt-get -o Acquire::Check-Valid-Until=false update \
   && apt-get install -y --no-install-recommends \
   git \
   ca-certificates \
@@ -15,13 +24,10 @@ RUN apt-get update \
   && ln -s /usr/bin/fdfind /usr/local/bin/fd \
   && rm -rf /var/lib/apt/lists/*
 
-RUN apt-get update \
+RUN apt-get -o Acquire::Check-Valid-Until=false update \
   && apt-get install -y --no-install-recommends python3 python3-pip python3-venv \
   && rm -rf /var/lib/apt/lists/*
 
-RUN npm install -g --ignore-scripts --no-fund --no-audit @earendil-works/pi-coding-agent \
-  && npm cache clean --force
-
 RUN install -d -o node -g node -m 755 /home/node/.config /home/node/.config/git \
   && mkdir -p /home/node/.pi/agent \
   /home/node/.pi/context-mode/sessions \
@@ -34,10 +40,15 @@ RUN install -d -o node -g node -m 755 /home/node/.config /home/node/.config/git
 USER node
 WORKDIR /home/node
 
-RUN pi install npm:@harms-haus/pi-cwd \
-  && pi install npm:pi-web-access \
-  && pi install npm:context-mode \
-  && pi install npm:pi-subagents \
-  && pi install npm:pi-mcp-adapter
+# Pi discovers npm packages from its agent directory. Installing the CLI and
+# extensions together from the committed lock makes all direct and transitive
+# package versions deterministic, with npm integrity verification.
+COPY --chown=node:node bot_bottle/contrib/pi/package.json \
+     bot_bottle/contrib/pi/package-lock.json /home/node/.pi/agent/
+RUN cd /home/node/.pi/agent \
+  && npm ci --omit=dev --no-fund --no-audit \
+  && npm cache clean --force
+
+ENV PATH="/home/node/.pi/agent/node_modules/.bin:${PATH}"
 
 CMD ["pi"]

bot_bottle/contrib/pi/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "bot-bottle-pi-image",
+  "private": true,
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.81.1",
+    "@earendil-works/pi-agent-core": "0.81.1",
+    "@earendil-works/pi-ai": "0.81.1",
+    "@earendil-works/pi-tui": "0.81.1",
+    "@harms-haus/pi-cwd": "1.0.0",
+    "context-mode": "1.0.169",
+    "pi-mcp-adapter": "2.11.0",
+    "pi-subagents": "0.35.1",
+    "pi-web-access": "0.13.0"
+  }
+}

bot_bottle/egress/__init__.py

@@ -32,6 +32,7 @@ if TYPE_CHECKING:
         EGRESS_ROUTES_IN_CONTAINER,
         Egress,
         egress_agent_env_entries,
+        egress_forge_routes,
         egress_gateway_env_entries,
         egress_manifest_routes,
         egress_render_routes,
@@ -51,6 +52,7 @@ _LAZY: dict[str, str] = {
     "EGRESS_ROUTES_FILENAME": ".service",
     "EGRESS_ROUTES_IN_CONTAINER": ".service",
     "egress_agent_env_entries": ".service",
+    "egress_forge_routes": ".service",
     "egress_gateway_env_entries": ".service",
     "egress_manifest_routes": ".service",
     "egress_render_routes": ".service",
@@ -80,6 +82,7 @@ __all__ = [
     "Egress",
     "EgressPlan",
     "EgressRoute",
+    "egress_forge_routes",
     "egress_manifest_routes",
     "egress_render_routes",
     "egress_resolve_token_values",

bot_bottle/egress/plan.py

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

bot_bottle/egress/service.py

@@ -14,8 +14,8 @@ import secrets
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from ..gateway.egress.addon_core import (
-    ON_MATCH_REDACT,
+from ..gateway.egress.dlp_config import ON_MATCH_REDACT
+from ..gateway.egress.types import (
     HeaderMatch as CoreHeaderMatch,
     MatchEntry as CoreMatchEntry,
     PathMatch as CorePathMatch,
@@ -26,7 +26,7 @@ from ..log import die
 from .plan import EgressPlan, EgressRoute
 
 if TYPE_CHECKING:
-    from ..manifest import ManifestBottle
+    from ..manifest import ManifestBottle, ResolvedForgeAssociation
 
 
 CODEX_HOST_CREDENTIAL_TOKEN_REF = "BOT_BOTTLE_CODEX_HOST_ACCESS_TOKEN"
@@ -119,15 +119,61 @@ def egress_manifest_routes(
     return tuple(out)
 
 
+def egress_forge_routes(
+    associations: "tuple[ResolvedForgeAssociation, ...]",
+) -> tuple[EgressRoute, ...]:
+    """Synthesize one inspected, token-authenticated egress route per distinct
+    forge alias referenced by a selected git-gate repo (PRD
+    0082).
+
+    The route is scoped to the canonical forge origin (host) and API prefix
+    (`/api/v1`): the proxy injects the Gitea `token` scheme using the value of
+    the host env var named by the account's `token_secret`, resolved at launch
+    from the host environment — the token never enters the bottle. Aliases that
+    canonicalize to the same host share a single route (deduplicated).
+
+    Composition (`resolve_forge_associations`) has already rejected referenced
+    aliases that share a host but disagree on origin/auth/token_secret, so this
+    host-dedup only ever collapses genuinely identical credentials — it never
+    silently discards a distinct one."""
+    out: list[EgressRoute] = []
+    seen_hosts: set[str] = set()
+    for assoc in associations:
+        acct = assoc.account
+        host_key = acct.host.lower()
+        if host_key in seen_hosts:
+            continue
+        seen_hosts.add(host_key)
+        out.append(EgressRoute(
+            host=acct.host,
+            matches=(CoreMatchEntry(
+                paths=(CorePathMatch(type="prefix", value=acct.api_prefix),),
+            ),),
+            auth_scheme=acct.auth_type,
+            token_ref=acct.token_secret,
+            inspect=True,
+        ))
+    return tuple(out)
+
+
 def egress_routes_for_bottle(
     bottle: ManifestBottle,
     provider_routes: tuple[EgressRoute, ...] = (),
+    forge_routes: tuple[EgressRoute, ...] = (),
 ) -> tuple[EgressRoute, ...]:
     manifest = egress_manifest_routes(bottle)
-    provisioned_hosts = {pr.host.lower() for pr in provider_routes}
-    merged = list(_default_provider_on_match(provider_routes)) + [
-        r for r in manifest if r.host.lower() not in provisioned_hosts
-    ]
+    # Provider routes (LLM API) default to redact-on-match; forge routes are
+    # host-injected but keep the default DLP policy. Both take precedence over
+    # a manifest route to the same host.
+    reserved_hosts = (
+        {pr.host.lower() for pr in provider_routes}
+        | {fr.host.lower() for fr in forge_routes}
+    )
+    merged = (
+        list(_default_provider_on_match(provider_routes))
+        + list(forge_routes)
+        + [r for r in manifest if r.host.lower() not in reserved_hosts]
+    )
     return _assign_token_slots(merged)
 
 
@@ -367,8 +413,9 @@ class Egress:
         slug: str,
         stage_dir: Path,
         provider_routes: tuple[EgressRoute, ...] = (),
+        forge_routes: tuple[EgressRoute, ...] = (),
     ) -> EgressPlan:
-        routes = egress_routes_for_bottle(bottle, provider_routes)
+        routes = egress_routes_for_bottle(bottle, provider_routes, forge_routes)
         log = bottle.egress.Log
         routes_path = stage_dir / EGRESS_ROUTES_FILENAME
         routes_path.write_text(egress_render_routes(routes, log=log))

bot_bottle/gateway/__init__.py

@@ -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]:

bot_bottle/gateway/egress/addon.py

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

bot_bottle/gateway/egress/context.py

@@ -0,0 +1,77 @@
+"""Fail-closed resolution of a client's policy and egress credentials."""
+
+from __future__ import annotations
+
+import typing
+
+from ...log import debug
+from .types import Config
+
+
+DENY_UNATTRIBUTED = (
+    "egress: this request was not attributed to any bottle, so no egress policy "
+    "applies and every host is denied. Either the bottle's registry row is "
+    "missing/ambiguous (torn down, or another bottle claimed its source IP), or "
+    "the request carried no matching identity token — check that the caller's "
+    "proxy URL includes it. This is not an allowlist problem."
+)
+DENY_UNPARSEABLE = (
+    "egress: this bottle's egress policy could not be parsed, so it is being "
+    "treated as deny-all. Fix the bottle's egress.routes; every host is denied "
+    "until it loads."
+)
+DENY_RESOLVER_ERROR = (
+    "egress: the orchestrator could not be reached to resolve this bottle's "
+    "egress policy, so every host is denied (fail-closed). Check that the "
+    "control plane is up; this is not an allowlist problem."
+)
+
+
+class PolicyResolverLike(typing.Protocol):
+    def resolve(self, source_ip: str, identity_token: str = ...) -> str | None: ...
+
+
+class ContextResolverLike(typing.Protocol):
+    def resolve_policy_and_bottle_id(
+        self, source_ip: str, identity_token: str = ...,
+    ) -> tuple[str | None, str | None, dict[str, str]]: ...
+
+
+def _config_from_policy(policy: str | None) -> Config:
+    # Local import keeps schema parsing independent of resolver protocols.
+    from .schema import load_config
+    if not policy:
+        return Config(routes=(), deny_reason=DENY_UNATTRIBUTED)
+    try:
+        return load_config(policy)
+    except ValueError:
+        return Config(routes=(), deny_reason=DENY_UNPARSEABLE)
+
+
+def resolve_client_config(
+    resolver: PolicyResolverLike, client_ip: str, identity_token: str = "",
+) -> Config:
+    try:
+        policy = resolver.resolve(client_ip, identity_token)
+    except Exception as exc:  # noqa: BLE001 - a policy lookup failure must deny
+        debug(
+            "egress policy resolution failed; applying deny-all",
+            context={"error_type": type(exc).__name__},
+        )
+        return Config(routes=(), deny_reason=DENY_RESOLVER_ERROR)
+    return _config_from_policy(policy)
+
+
+def resolve_client_context(
+    resolver: ContextResolverLike, client_ip: str, identity_token: str = "",
+) -> tuple[Config, str, dict[str, str]]:
+    try:
+        policy, bottle_id, tokens = resolver.resolve_policy_and_bottle_id(
+            client_ip, identity_token)
+    except Exception as exc:  # noqa: BLE001 - a policy lookup failure must deny
+        debug(
+            "egress context resolution failed; applying deny-all",
+            context={"error_type": type(exc).__name__},
+        )
+        return Config(routes=(), deny_reason=DENY_RESOLVER_ERROR), "", {}
+    return _config_from_policy(policy), (bottle_id or ""), tokens

bot_bottle/gateway/egress/dlp.py

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

bot_bottle/gateway/egress/dlp_detectors.py

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

bot_bottle/gateway/egress/matching.py

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

bot_bottle/gateway/egress/schema.py

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

bot_bottle/gateway/egress/types.py

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

bot_bottle/gateway/git_gate/render.py

@@ -252,6 +252,27 @@ cat > "$refs_file"
 
 zero=0000000000000000000000000000000000000000
 
+# Phase 0: reject Gitea AGit review refs before scanning or forwarding.
+# A push to refs/for/*, refs/draft/*, or refs/for-review/* asks Gitea to
+# open a pull request backed by a server-managed refs/pull/<n>/head rather
+# than an ordinary refs/heads/* branch. That breaks the git-gate workflow:
+# follow-up commits can't be pushed back through the branch, and Gitea
+# rejects later direct updates to the generated review ref. Fail the whole
+# push here (before any gitleaks scan or upstream forward) so the caller
+# pushes a real branch and opens the PR against it instead. Deletions
+# (new == zero) stay allowed so stale AGit refs can still be cleaned up.
+while IFS=' ' read -r old new ref; do
+  [ -z "$ref" ] && continue
+  [ "$new" = "$zero" ] && continue
+  case "$ref" in
+    refs/for/*|refs/draft/*|refs/for-review/*)
+      echo "git-gate: refusing AGit review ref $ref" >&2
+      echo "git-gate: push to refs/heads/<branch> and open a branch-backed pull request instead" >&2
+      exit 1
+      ;;
+  esac
+done < "$refs_file"
+
 supervise_gitleaks_allow() {
   log_opts=$1
   ref=$2

bot_bottle/gateway/supervisor/server.py

@@ -17,7 +17,7 @@ Each queued proposal tool call:
   4. On a decision within the window, returns the operator's
      `{status, notes}`. On timeout, returns `status: pending` **with the
      proposal id** and leaves the proposal queued — the flow is
-     non-blocking past the grace window (PRD 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
@@ -58,9 +58,9 @@ import typing
 from dataclasses import dataclass
 
 from bot_bottle.constants import IDENTITY_HEADER
-from bot_bottle.gateway.egress.addon_core import (
-    LOG_OFF, load_config, resolve_client_context, route_to_yaml_dict,
-)
+from bot_bottle.gateway.egress.context import resolve_client_context
+from bot_bottle.gateway.egress.schema import load_config, route_to_yaml_dict
+from bot_bottle.gateway.egress.types import LOG_OFF
 from bot_bottle.gateway.policy_resolver import PolicyResolveError, PolicyResolver
 from bot_bottle.supervisor import types as _sv
 

bot_bottle/manifest/__init__.py

@@ -1,10 +1,10 @@
 """Manifest dataclasses (PRD 0011 layout).
 
-Reads the per-file manifest tree:
+Reads the per-file manifest tree (home-only —
+PRD 0082):
 
   $HOME/.bot-bottle/bottles/<name>.md   — one bottle per file
-  $HOME/.bot-bottle/agents/<name>.md    — home-resident agents
-  $CWD/.bot-bottle/agents/<name>.md     — cwd-supplied agents
+  $HOME/.bot-bottle/agents/<name>.md    — agents
 
 Each file is Markdown with YAML frontmatter. The frontmatter holds
 the structured config (see schema below); for agents the body is
@@ -15,27 +15,38 @@ Bottle schema (frontmatter):
   extends:      <bottle-name>                   # optional (PRD 0025)
   env:          { <NAME>: <env-entry>, ... }
   git-gate:                                     # optional (PRD 0047)
-    user:       { name: <str>, email: <str> }   # optional
     repos:      { <name>: <git-gate-entry>, ... }  # optional
+      # git-gate-entry keys: url, key, host_key, forge
+      # `forge`: optional alias into the selected agent's forge-accounts
   egress: { routes: [ <egress-route>, ... ] }
     # route keys: host, matches, auth, role, dlp
   supervise:    <bool>                          # optional (default true)
   nested_containers: <bool>                     # optional (default false)
 
 Agent schema (frontmatter):
-  bottle:        <bottle-name>          # required
+  bottle:        <bottle-name>          # optional
   skills:        [ <skill-name>, ... ]   # optional
-  git-gate:
-    user:        { name: <str>, email: <str> }  # optional; overlays bottle
+  author:                               # optional; agent git identity
+    name:  <str>                        # required when author is present
+    email: <str>                        # required when author is present
+  forge-accounts:                       # optional; alias -> forge account
+    <alias>:
+      url:  <https Gitea /api/v1 base>
+      auth: { type: token, token_secret: <host env var name> }
   # Claude Code subagent passthrough fields — accepted, ignored:
   name, description, model, color, memory
 
+`author` populates the bottle's git user.name/user.email; `forge-accounts`
+maps a forge alias to a Gitea API origin plus a host token reference. Identity
+is agent-owned — `git-gate` is no longer accepted on an agent (git-gate.user
+moved to `author`; git-gate.repos is bottle-only).
+
 The agent file's Markdown body is the system prompt (stripped).
 Unknown top-level frontmatter keys raise ManifestError with a hint.
 
-Bottles can ONLY live under $HOME. A bottles/ dir under $CWD is a
-warn at load time and contributes nothing. The trust boundary is
-expressed as filesystem layout rather than resolver logic.
+Both bottles and agents can ONLY live under $HOME. An agents/ or bottles/
+dir under $CWD is a warn at load time and contributes nothing. The trust
+boundary is expressed as filesystem layout rather than resolver logic.
 
 Two types are exported:
 
@@ -66,6 +77,11 @@ if TYPE_CHECKING:
     from .agent import ManifestAgent, ManifestAgentProvider
     from .bottle import ManifestBottle
     from .egress import EGRESS_AUTH_SCHEMES, ManifestEgressConfig, ManifestEgressRoute
+    from .forge import (
+        ManifestAuthor,
+        ManifestForgeAccount,
+        ResolvedForgeAssociation,
+    )
     from .git import ManifestGitEntry, ManifestGitUser, ManifestKeyConfig
 
 
@@ -81,6 +97,9 @@ _LAZY_MODULES: dict[str, str] = {
     "EGRESS_AUTH_SCHEMES": "egress",
     "ManifestEgressRoute": "egress",
     "ManifestEgressConfig": "egress",
+    "ManifestAuthor": "forge",
+    "ManifestForgeAccount": "forge",
+    "ResolvedForgeAssociation": "forge",
     "ManifestGitEntry": "git",
     "ManifestGitUser": "git",
     "ManifestKeyConfig": "git",
@@ -115,4 +134,7 @@ __all__ = [
     "EGRESS_AUTH_SCHEMES",
     "ManifestEgressRoute",
     "ManifestEgressConfig",
+    "ManifestAuthor",
+    "ManifestForgeAccount",
+    "ResolvedForgeAssociation",
 ]

bot_bottle/manifest/agent.py

@@ -3,11 +3,11 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import cast
+from typing import Mapping, cast
 
 from ..agent_provider import PROVIDER_TEMPLATES
 from .util import ManifestError, as_json_object
-from .git import ManifestGitUser
+from .forge import ManifestAuthor, ManifestForgeAccount
 from .schema import AGENT_MODEL_KEYS, is_valid_entity_name
 
 
@@ -119,15 +119,29 @@ class ManifestAgent:
     bottle: str = ""
     skills: tuple[str, ...] = ()
     prompt: str = ""
-    # Per-agent git identity (issue #94). Overlays the referenced
-    # bottle's git-gate.user per-field at `Manifest.bottle_for`. Only
-    # `user` is allowed at the agent level; `repos` stays bottle-only
-    # because it carries credentials and host trust.
-    git_user: ManifestGitUser = ManifestGitUser()
+    # Agent-owned identity (PRD 0082).
+    # `author` populates the bottle's git user.name/user.email;
+    # `forge_accounts` maps a forge alias to a canonical Gitea API origin and
+    # a host token reference. Both live only on the agent — never under
+    # `git-gate`, which is bottle-only transport policy.
+    author: ManifestAuthor | None = None
+    forge_accounts: Mapping[str, ManifestForgeAccount] = field(
+        default_factory=dict
+    )
 
     @classmethod
     def from_dict(cls, name: str, raw: object, bottle_names: set[str]) -> "ManifestAgent":
         d = as_json_object(raw, f"agent '{name}'")
+        # git-gate is no longer accepted on an agent (checked before the
+        # generic unknown-key error so the migration pointer is surfaced):
+        # identity moved to `author`, and git-gate.repos is bottle-only.
+        if "git-gate" in d:
+            raise ManifestError(
+                f"agent '{name}' has a 'git-gate' block, which is no longer "
+                f"accepted on an agent (PRD 0082). "
+                f"Move git-gate.user name/email into the 'author' block; "
+                f"git-gate.repos stays on the bottle."
+            )
         unknown = set(d.keys()) - AGENT_MODEL_KEYS
         if unknown:
             allowed = ", ".join(sorted(AGENT_MODEL_KEYS))
@@ -191,24 +205,30 @@ class ManifestAgent:
                 f"(was {type(prompt_raw).__name__})"
             )
 
-        # git-gate: agents may declare only `git-gate.user` (name/email).
-        # `git-gate.repos` is bottle-only — it carries credentials and host trust.
-        git_user = ManifestGitUser()
-        git_raw = d.get("git-gate")
-        if git_raw is not None:
-            gd = as_json_object(git_raw, f"agent '{name}' git-gate")
-            for k in gd:
-                if k != "user":
-                    raise ManifestError(
-                        f"agent '{name}' git-gate.{k} is not allowed at the "
-                        f"agent level; only git-gate.user (name/email) may be "
-                        f"set on an agent. git-gate.repos is bottle-only "
-                        f"(it carries credentials and host trust)."
-                    )
-            if "user" in gd:
-                git_user = ManifestGitUser.from_dict(name, gd["user"])
+        # author: agent-owned git identity (optional; both fields required
+        # when present). Populates the bottle's user.name/user.email.
+        author = (
+            ManifestAuthor.from_dict(name, d["author"])
+            if "author" in d else None
+        )
 
-        return cls(bottle=bottle, skills=skills, prompt=prompt, git_user=git_user)
+        # forge-accounts: alias -> Gitea API origin + host token reference.
+        forge_accounts: dict[str, ManifestForgeAccount] = {}
+        forge_raw = d.get("forge-accounts")
+        if forge_raw is not None:
+            forge_d = as_json_object(forge_raw, f"agent '{name}' forge-accounts")
+            for alias, entry in forge_d.items():
+                forge_accounts[alias] = ManifestForgeAccount.from_dict(
+                    name, alias, entry,
+                )
+
+        return cls(
+            bottle=bottle,
+            skills=skills,
+            prompt=prompt,
+            author=author,
+            forge_accounts=forge_accounts,
+        )
 
 
 def _parse_provider_settings(

bot_bottle/manifest/bottle.py

@@ -107,11 +107,14 @@ class ManifestBottle:
                     )
                 env[var] = value
 
+        # `git_user` is now an internal resolved carrier populated from the
+        # selected agent's `author` at composition time — it is never parsed
+        # from the bottle manifest (PRD 0082).
         git: tuple[ManifestGitEntry, ...] = ()
         git_user = ManifestGitUser()
         git_raw = d.get("git-gate")
         if git_raw is not None:
-            git, git_user = parse_git_gate_config(name, git_raw)
+            git = parse_git_gate_config(name, git_raw)
 
         agent_provider = (
             ManifestAgentProvider.from_dict(name, d["agent_provider"])

bot_bottle/manifest/extends.py

@@ -210,7 +210,7 @@ def _fold_two_bottles(
         for n in names
     }
     if merged_repos_raw:
-        merged_git, _ = parse_git_gate_config("_fold", {"repos": merged_repos_raw})
+        merged_git = parse_git_gate_config("_fold", {"repos": merged_repos_raw})
     else:
         merged_git = ()
 

bot_bottle/manifest/forge.py

@@ -0,0 +1,312 @@
+"""Agent-owned author identity and forge accounts (PRD 0082).
+
+`ManifestAuthor` is the agent's git author identity (name/email) — it moved off
+`git-gate.user` (PRD 0027 / ADR 0002) and onto the trusted agent definition.
+
+`ManifestForgeAccount` maps a **forge alias** to a canonical HTTPS Gitea API
+origin plus the *name* of a host env var holding the operator-provided API
+token. The token value never lives on the manifest; the host resolves it only
+when a selected bottle repository references the alias, and hands it to the
+egress proxy — never to the bottle.
+
+`ResolvedForgeAssociation` is the composed view: one distinct forge alias that
+at least one selected git-gate repository points at, with the repository names
+that reference it. The proxy-provisioning and prompt-guidance steps consume it.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+from dataclasses import dataclass
+
+from .schema import is_valid_entity_name
+from .util import ManifestError, as_json_object
+
+# Only the Gitea `/api/v1` base is supported today. A future provider adds a
+# validator + auth scheme + guidance renderer in code rather than accepting a
+# repository-supplied prompt or path (PRD non-goal: provider-generic prompts).
+GITEA_API_PREFIX = "/api/v1"
+
+# Auth schemes an agent forge account may declare. Gitea uses `token`.
+FORGE_AUTH_TYPES = ("token",)
+
+
+def canonicalize_forge_url(
+    agent_name: str, alias: str, url: object,
+) -> tuple[str, str, str, str]:
+    """Validate and canonicalize a forge account's API base URL.
+
+    Returns `(canonical, origin, host, api_prefix)` where `origin` is
+    `https://host[:port]` and `canonical` is `origin + api_prefix`.
+
+    Fails closed on: non-string, non-`https`, embedded userinfo, query, or
+    fragment, a missing host, or any path other than the supported Gitea API
+    base (`/api/v1`, trailing slash tolerated)."""
+    label = f"agent '{agent_name}' forge-accounts.{alias}.url"
+    if not isinstance(url, str) or not url:
+        raise ManifestError(f"{label} is required (non-empty string)")
+    try:
+        parts = urllib.parse.urlsplit(url)
+    except ValueError as e:
+        raise ManifestError(f"{label} is not a valid URL ({e}): {url!r}") from e
+
+    if parts.scheme != "https":
+        raise ManifestError(
+            f"{label} must use https (got scheme {parts.scheme!r} in {url!r})"
+        )
+    if parts.username or parts.password:
+        raise ManifestError(
+            f"{label} must not embed userinfo (user:pass@); the token is held "
+            f"host-side via auth.token_secret. Got {url!r}"
+        )
+    if parts.query:
+        raise ManifestError(f"{label} must not contain a query string: {url!r}")
+    if parts.fragment:
+        raise ManifestError(f"{label} must not contain a fragment: {url!r}")
+
+    host = parts.hostname
+    if not host:
+        raise ManifestError(f"{label} must include a hostname: {url!r}")
+
+    path = parts.path.rstrip("/")
+    if path != GITEA_API_PREFIX:
+        raise ManifestError(
+            f"{label} path must be the Gitea API base '{GITEA_API_PREFIX}' "
+            f"(got {parts.path!r} in {url!r}); other providers and API paths "
+            f"are not yet supported."
+        )
+
+    host = host.lower()
+    netloc = host if parts.port is None else f"{host}:{parts.port}"
+    origin = f"https://{netloc}"
+    return f"{origin}{path}", origin, host, path
+
+
+@dataclass(frozen=True)
+class ManifestAuthor:
+    """The agent's git author identity. Both fields are required and
+    non-empty — an author that is declared must fully identify the agent.
+    Populates `user.name` / `user.email` inside the bottle."""
+
+    name: str
+    email: str
+
+    @classmethod
+    def from_dict(cls, agent_name: str, raw: object) -> "ManifestAuthor":
+        d = as_json_object(raw, f"agent '{agent_name}' author")
+        for k in d:
+            if k not in {"name", "email"}:
+                raise ManifestError(
+                    f"agent '{agent_name}' author has unknown key {k!r}; "
+                    f"allowed: name, email"
+                )
+        name = d.get("name")
+        if not isinstance(name, str) or not name:
+            raise ManifestError(
+                f"agent '{agent_name}' author.name must be a non-empty string"
+            )
+        email = d.get("email")
+        if not isinstance(email, str) or not email:
+            raise ManifestError(
+                f"agent '{agent_name}' author.email must be a non-empty string"
+            )
+        # Git identity validation: reject values that would break the
+        # `git config user.email` line or smuggle a second config directive.
+        if any(c in email for c in ("\n", "\r", " ", "\t")):
+            raise ManifestError(
+                f"agent '{agent_name}' author.email must not contain whitespace "
+                f"or newlines (got {email!r})"
+            )
+        if any(c in name for c in ("\n", "\r")):
+            raise ManifestError(
+                f"agent '{agent_name}' author.name must not contain newlines "
+                f"(got {name!r})"
+            )
+        return cls(name=name, email=email)
+
+
+@dataclass(frozen=True)
+class ManifestForgeAccount:
+    """One forge alias on an agent: a canonical Gitea API origin plus the
+    host env var name that holds the agent-specific API token. The
+    authenticated account is whoever owns that token — there is no separate
+    account-name field."""
+
+    alias: str
+    url: str          # canonical https base incl. /api/v1, no trailing slash
+    origin: str       # https://host[:port]
+    host: str         # lowercased hostname
+    api_prefix: str   # /api/v1
+    auth_type: str    # "token"
+    token_secret: str  # host env var name holding the API token
+
+    @classmethod
+    def from_dict(
+        cls, agent_name: str, alias: str, raw: object,
+    ) -> "ManifestForgeAccount":
+        if not is_valid_entity_name(alias):
+            raise ManifestError(
+                f"agent '{agent_name}' forge-accounts key {alias!r} is not a "
+                f"valid alias; must match [a-z][a-z0-9-]*"
+            )
+        label = f"agent '{agent_name}' forge-accounts.{alias}"
+        d = as_json_object(raw, label)
+        for k in d:
+            if k not in {"url", "auth"}:
+                raise ManifestError(
+                    f"{label} has unknown key {k!r}; allowed: url, auth"
+                )
+
+        canonical, origin, host, api_prefix = canonicalize_forge_url(
+            agent_name, alias, d.get("url"),
+        )
+
+        if "auth" not in d:
+            raise ManifestError(f"{label} missing required 'auth' block")
+        auth = as_json_object(d.get("auth"), f"{label}.auth")
+        for k in auth:
+            if k not in {"type", "token_secret"}:
+                raise ManifestError(
+                    f"{label}.auth has unknown key {k!r}; allowed: type, "
+                    f"token_secret"
+                )
+        auth_type = auth.get("type")
+        if auth_type not in FORGE_AUTH_TYPES:
+            raise ManifestError(
+                f"{label}.auth.type must be one of "
+                f"{', '.join(FORGE_AUTH_TYPES)} (got {auth_type!r})"
+            )
+        token_secret = auth.get("token_secret")
+        if not isinstance(token_secret, str) or not token_secret:
+            raise ManifestError(
+                f"{label}.auth.token_secret must be a non-empty string (the "
+                f"name of a host env var holding the API token)"
+            )
+        return cls(
+            alias=alias,
+            url=canonical,
+            origin=origin,
+            host=host,
+            api_prefix=api_prefix,
+            auth_type=str(auth_type),
+            token_secret=token_secret,
+        )
+
+
+@dataclass(frozen=True)
+class ResolvedForgeAssociation:
+    """A distinct forge alias referenced by one or more selected git-gate
+    repositories. `repo_names` lists the git-gate repo names pointing at
+    `account.alias` (sorted, deduplicated)."""
+
+    account: ManifestForgeAccount
+    repo_names: tuple[str, ...]
+
+    @property
+    def alias(self) -> str:
+        return self.account.alias
+
+
+def resolve_forge_associations(
+    agent_name: str,
+    forge_accounts: "dict[str, ManifestForgeAccount]",
+    git_entries: "tuple[object, ...]",
+) -> tuple[ResolvedForgeAssociation, ...]:
+    """Compose the agent's forge accounts with the effective bottle's
+    git-gate repos. Each git entry that declares a `forge` alias must match a
+    forge account on the selected agent — otherwise fail closed before launch.
+
+    Returns one association per distinct referenced alias, carrying the repo
+    names that reference it. Unreferenced accounts produce nothing (no token
+    is resolved and no route is created for them)."""
+    by_alias: dict[str, list[str]] = {}
+    for entry in git_entries:
+        alias = getattr(entry, "Forge", "")
+        if not alias:
+            continue
+        if alias not in forge_accounts:
+            available = ", ".join(sorted(forge_accounts)) or "(none)"
+            raise ManifestError(
+                f"git-gate.repos['{getattr(entry, 'Name', '?')}'].forge "
+                f"references forge alias {alias!r}, which is not defined on "
+                f"agent '{agent_name}'. Available forge-accounts: {available}"
+            )
+        by_alias.setdefault(alias, []).append(getattr(entry, "Name", ""))
+
+    associations = tuple(
+        ResolvedForgeAssociation(
+            account=forge_accounts[alias],
+            repo_names=tuple(sorted(set(names))),
+        )
+        for alias, names in sorted(by_alias.items())
+    )
+
+    # The egress proxy routes by host, so two referenced aliases that resolve
+    # to the same host must agree on the credential and target — otherwise the
+    # generated plan would authenticate every call to that host as whichever
+    # alias happened to win, silently acting as the wrong forge account. Fail
+    # closed here (before the bottle is created) rather than dropping a
+    # credential at route-synthesis time.
+    by_host: dict[str, ManifestForgeAccount] = {}
+    for assoc in associations:
+        acct = assoc.account
+        prev = by_host.get(acct.host)
+        if prev is None:
+            by_host[acct.host] = acct
+            continue
+        if (prev.origin, prev.api_prefix, prev.auth_type, prev.token_secret) != (
+            acct.origin, acct.api_prefix, acct.auth_type, acct.token_secret
+        ):
+            raise ManifestError(
+                f"agent '{agent_name}' forge-accounts '{prev.alias}' and "
+                f"'{acct.alias}' both resolve to host '{acct.host}' but differ "
+                f"in origin/auth/token_secret. The egress proxy routes by host, "
+                f"so the intended credential would be ambiguous — every request "
+                f"to '{acct.host}' would authenticate as one account. Give the "
+                f"aliases distinct hosts, or make their url/auth identical."
+            )
+
+    return associations
+
+
+def render_forge_guidance(
+    associations: tuple[ResolvedForgeAssociation, ...],
+) -> str:
+    """Render the non-secret, provider-specific forge workflow guidance
+    appended to the agent's system prompt for associated repositories only.
+
+    Derived entirely from validated typed fields — never repository-supplied
+    Markdown. Contains neither the token value nor its `token_secret` name.
+    Returns "" when there are no associations (no section is generated)."""
+    if not associations:
+        return ""
+    lines: list[str] = [
+        "## Forge access (managed by bot-bottle)",
+        "",
+        "bot-bottle authenticates the forge API requests below for you "
+        "through the egress proxy. Do not read, print, or manually attach "
+        "an authorization token — the proxy injects it. Never place a token "
+        "in a request.",
+    ]
+    for assoc in associations:
+        acct = assoc.account
+        for repo in assoc.repo_names:
+            lines.extend([
+                "",
+                f"### Repository `{repo}` (forge alias `{acct.alias}`)",
+                f"- Forge API base URL: `{acct.url}`.",
+                f"- This git-gate repository (`{repo}`) is tied to forge "
+                f"`{acct.alias}`; use its API for forge actions on this repo.",
+                f"- Call the API at `{acct.url}` over HTTPS through the proxy. "
+                "The proxy adds authentication; you never supply a token "
+                "yourself.",
+                "- Git pushes still use the git-gate remote, not the API.",
+                "- To propose changes: push a normal branch "
+                "(`refs/heads/<branch>`) through the git-gate remote, then open "
+                "a branch-backed pull request through the API.",
+                "- Do NOT push AGit review refs (`refs/for/*`, `refs/draft/*`, "
+                "`refs/for-review/*`); they are prohibited here.",
+                "- Use the API for reviews and comments, and verify the "
+                "returned object state before claiming the task is complete.",
+            ])
+    return "\n".join(lines) + "\n"

bot_bottle/manifest/git.py

@@ -117,6 +117,11 @@ class ManifestGitEntry:
     UpstreamHost: str = ""
     UpstreamPort: str = ""
     UpstreamPath: str = ""
+    # Optional forge alias (PRD 0082). When
+    # set, it must match a `forge-accounts` alias on the selected agent; the
+    # composition enables a scoped proxy-held API credential and forge
+    # workflow guidance for this repo. Empty = no forge association.
+    Forge: str = ""
 
     @classmethod
     def from_repos_entry(
@@ -139,10 +144,10 @@ class ManifestGitEntry:
         label = f"git-gate.repos[{repo_name!r}]"
         d = as_json_object(raw, f"bottle '{bottle_name}' {label}")
         for k in d:
-            if k not in {"url", "key", "host_key"}:
+            if k not in {"url", "key", "host_key", "forge"}:
                 raise ManifestError(
                     f"bottle '{bottle_name}' {label} has unknown key {k!r}; "
-                    f"allowed: url, key, host_key"
+                    f"allowed: url, key, host_key, forge"
                 )
         upstream = d.get("url")
         if not isinstance(upstream, str) or not upstream:
@@ -150,6 +155,21 @@ class ManifestGitEntry:
                 f"bottle '{bottle_name}' {label} missing required string field 'url'"
             )
 
+        forge = d.get("forge", "")
+        if not isinstance(forge, str):
+            raise ManifestError(
+                f"bottle '{bottle_name}' {label} forge must be a string "
+                f"(was {type(forge).__name__})"
+            )
+        if forge and not _GIT_NAME_RE.match(forge):
+            # forge aliases follow the kebab-case identifier grammar; the
+            # cross-check against the agent's forge-accounts happens at
+            # composition time (it needs the resolved agent).
+            raise ManifestError(
+                f"bottle '{bottle_name}' {label} forge {forge!r} is not a "
+                f"valid forge alias; allowed characters: A-Z a-z 0-9 . _ -"
+            )
+
         if "key" not in d:
             raise ManifestError(
                 f"bottle '{bottle_name}' {label} missing required 'key' block"
@@ -176,6 +196,7 @@ class ManifestGitEntry:
             UpstreamHost=host,
             UpstreamPort=port,
             UpstreamPath=path,
+            Forge=forge,
         )
 
 
@@ -286,21 +307,26 @@ class ManifestGitUser:
 def parse_git_gate_config(
     bottle_name: str,
     raw: object,
-) -> tuple[tuple[ManifestGitEntry, ...], ManifestGitUser]:
+) -> tuple[ManifestGitEntry, ...]:
+    """Parse `git-gate` on a bottle. Only `repos` is accepted; `git-gate.user`
+    moved to the agent's `author` block (PRD 0082)."""
     d = as_json_object(raw, f"bottle '{bottle_name}' git-gate")
+    if "user" in d:
+        raise ManifestError(
+            f"bottle '{bottle_name}' git-gate.user is no longer supported "
+            f"(PRD 0082). Move name/email into "
+            f"the selected home agent's 'author' block:\n"
+            f"  author:\n    name: <name>\n    email: <email>\n"
+            f"Identity is agent-owned; git-gate now carries only transport "
+            f"policy (repos)."
+        )
     for k in d:
-        if k not in {"user", "repos"}:
+        if k != "repos":
             raise ManifestError(
                 f"bottle '{bottle_name}' git-gate has unknown key {k!r}; "
-                f"allowed: user, repos"
+                f"allowed: repos"
             )
 
-    git_user = (
-        ManifestGitUser.from_dict(bottle_name, d["user"])
-        if "user" in d
-        else ManifestGitUser()
-    )
-
     git: tuple[ManifestGitEntry, ...] = ()
     repos_raw = d.get("repos")
     if repos_raw is not None:
@@ -311,4 +337,4 @@ def parse_git_gate_config(
         )
         validate_unique_git_names(bottle_name, git)
 
-    return git, git_user
+    return git

bot_bottle/manifest/index.py

@@ -19,6 +19,7 @@ from .util import ManifestError, as_json_object
 from .agent import ManifestAgent
 from .bottle import ManifestBottle
 from .extends import merge_bottles_runtime, resolve_bottles
+from .forge import ResolvedForgeAssociation, resolve_forge_associations
 from .git import ManifestGitUser
 from .loader import (
     check_stale_json,
@@ -37,30 +38,50 @@ def _section_dict(value: object, label: str) -> dict[str, object]:
     return as_json_object(value, label)
 
 
-def _merge_git_user(
-    agent_user: ManifestGitUser, base_user: ManifestGitUser
-) -> ManifestGitUser:
-    """Merge the agent's git.user over the bottle's, agent-wins-on-non-empty."""
-    if agent_user.is_empty():
-        return base_user
-    return ManifestGitUser(
-        name=agent_user.name or base_user.name,
-        email=agent_user.email or base_user.email,
+def _warn_ignored_cwd_dir(cwd_dir: Path, kind: str, home_path: str) -> None:
+    """Warn (once) that manifest files of `kind` under `$CWD/.bot-bottle/`
+    are ignored — the filesystem layout IS the trust boundary. `kind` is the
+    subdir name (`bottles`/`agents`); `home_path` is where they belong."""
+    stale = cwd_dir / kind
+    if not stale.is_dir():
+        return
+    files = sorted(stale.glob("*.md"))
+    if not files:
+        return
+    names = ", ".join(p.name for p in files)
+    warn(
+        f"ignoring {kind[:-1]} file(s) under {stale}: {names}. "
+        f"{kind.capitalize()} can only live under {home_path} "
+        f"(PRD 0082). Move them or delete."
     )
 
 
-def _manifest_with_merged_git_user(
-    agent: "ManifestAgent", raw_bottle: "ManifestBottle"
+def _compose_manifest(
+    agent_name: str,
+    agent: "ManifestAgent",
+    raw_bottle: "ManifestBottle",
 ) -> "Manifest":
-    """Build the single-value Manifest, overlaying the agent's git-gate.user
-    onto the bottle (agent wins on non-empty, per-field). Shared by the eager
-    and lazy load_for_agent paths."""
-    merged = _merge_git_user(agent.git_user, raw_bottle.git_user)
-    bottle = (
-        raw_bottle if merged == raw_bottle.git_user
-        else replace(raw_bottle, git_user=merged)
+    """Build the single-value Manifest from the selected agent and its
+    effective bottle (PRD 0082):
+
+    - the agent's `author` populates the bottle's git user.name/user.email;
+    - each git-gate repo's `forge` alias is resolved against the agent's
+      `forge-accounts` (failing closed on an unknown alias) into the
+      Manifest's forge associations.
+
+    Shared by the eager (from_json_obj) and lazy (from_md_dirs) paths."""
+    identity = (
+        ManifestGitUser(name=agent.author.name, email=agent.author.email)
+        if agent.author is not None else ManifestGitUser()
     )
-    return Manifest(agent=agent, bottle=bottle)
+    bottle = (
+        raw_bottle if identity == raw_bottle.git_user
+        else replace(raw_bottle, git_user=identity)
+    )
+    associations = resolve_forge_associations(
+        agent_name, dict(agent.forge_accounts), bottle.git,
+    )
+    return Manifest(agent=agent, bottle=bottle, forge_associations=associations)
 
 
 def _resolve_effective_bottle_eager(
@@ -121,26 +142,28 @@ def _resolve_effective_bottle_lazy(
 class Manifest:
     """Single-agent/bottle value type. Returned by ManifestIndex.load_for_agent().
 
-    `bottle` is the effective bottle with the agent's git-gate.user already
-    overlaid per-field (agent wins on non-empty). Backends and provisioners
-    use this directly — no agent_name lookup needed."""
+    `bottle` is the effective bottle with the agent's `author` already
+    populated into its git identity. `forge_associations` holds the distinct
+    forge aliases referenced by the effective bottle's git-gate repos, resolved
+    against the agent's `forge-accounts`. Backends and provisioners use this
+    directly — no agent_name lookup needed."""
 
     agent: ManifestAgent
     bottle: ManifestBottle
+    forge_associations: tuple[ResolvedForgeAssociation, ...] = ()
 
     def git_identity_summary(self) -> str | None:
-        """One-line effective git identity with per-field provenance, e.g.
-        `name=claude (agent), email=eric@dideric.is (bottle)`.
-        Returns None when neither agent nor bottle sets an identity."""
-        over = self.agent.git_user        # agent's declared git_user (pre-merge)
-        merged = self.bottle.git_user     # effective git_user (post-merge)
-        if merged.is_empty():
+        """One-line effective git identity, e.g.
+        `name=claude, email=eric@dideric.is`. Sourced from the agent's
+        `author` block. Returns None when the agent declares no author."""
+        gu = self.bottle.git_user
+        if gu.is_empty():
             return None
         parts: list[str] = []
-        if merged.name:
-            parts.append(f"name={merged.name} ({'agent' if over.name else 'bottle'})")
-        if merged.email:
-            parts.append(f"email={merged.email} ({'agent' if over.email else 'bottle'})")
+        if gu.name:
+            parts.append(f"name={gu.name}")
+        if gu.email:
+            parts.append(f"email={gu.email}")
         return ", ".join(parts)
 
 
@@ -164,15 +187,15 @@ class ManifestIndex:
     def resolve(cls, cwd: str, *, missing_ok: bool = False) -> "ManifestIndex":
         """Walk the per-file manifest tree and build a ManifestIndex.
 
-        Layout (PRD 0011):
+        Layout:
           $HOME/.bot-bottle/bottles/<name>.md  — bottles (home-only)
-          $HOME/.bot-bottle/agents/<name>.md   — home agents
-          $CWD/.bot-bottle/agents/<name>.md    — cwd agents
+          $HOME/.bot-bottle/agents/<name>.md   — agents (home-only)
 
-        Cwd agents merge into the home agents on the same name
-        (cwd wins). A bottles/ subdir under $CWD is logged as a
-        warning and ignored — the filesystem layout IS the trust
-        boundary.
+        Both agents and bottles are home-only
+        (PRD 0082): a `bottles/` or `agents/`
+        subdir under $CWD is logged as a warning and ignored — the filesystem
+        layout IS the trust boundary, since an agent may now select a host
+        identity and forge secret.
 
         If `missing_ok` is true, a missing `$HOME/.bot-bottle/`
         returns an empty index instead of dying. This is for
@@ -223,17 +246,12 @@ class ManifestIndex:
         Used by tests to build a ManifestIndex from fixture directories
         without touching `os.environ`."""
         if cwd_dir is not None:
-            stale_bottles = cwd_dir / "bottles"
-            if stale_bottles.is_dir():
-                files = sorted(stale_bottles.glob("*.md"))
-                if files:
-                    names = ", ".join(p.name for p in files)
-                    warn(
-                        f"ignoring bottle file(s) under "
-                        f"{stale_bottles}: {names}. Bottles can only "
-                        f"live under $HOME/.bot-bottle/bottles/ "
-                        f"(PRD 0011). Move them or delete."
-                    )
+            _warn_ignored_cwd_dir(cwd_dir, "bottles", "$HOME/.bot-bottle/bottles/")
+            # Agents became home-only in
+            # PRD 0082: a cwd agent file that
+            # once shadowed a home agent could select a host identity/secret,
+            # so it is now ignored with a migration pointer.
+            _warn_ignored_cwd_dir(cwd_dir, "agents", "$HOME/.bot-bottle/agents/")
         return cls(bottles={}, agents={}, home_md=home_dir, cwd_md=cwd_dir)
 
     @classmethod
@@ -275,13 +293,12 @@ class ManifestIndex:
 
         In names-only mode (from resolve/from_md_dirs) this scans agent
         filenames without reading their content. In eager mode (from
-        from_json_obj) it returns the pre-parsed agents' names."""
+        from_json_obj) it returns the pre-parsed agents' names.
+
+        Agents are home-only (PRD 0082): cwd
+        agent files never contribute names."""
         if self.home_md is not None:
-            home_names = set(scan_agent_names(self.home_md / "agents").keys())
-            cwd_names: set[str] = set()
-            if self.cwd_md is not None:
-                cwd_names = set(scan_agent_names(self.cwd_md / "agents").keys())
-            return sorted(home_names | cwd_names)
+            return sorted(scan_agent_names(self.home_md / "agents").keys())
         return sorted(self.agents.keys())
 
     def load_for_agent(
@@ -326,7 +343,7 @@ class ManifestIndex:
         raw_bottle = _resolve_effective_bottle_eager(
             agent_name, agent, bottle_names, self.bottles
         )
-        return _manifest_with_merged_git_user(agent, raw_bottle)
+        return _compose_manifest(agent_name, agent, raw_bottle)
 
     def _load_for_agent_lazy(
         self, agent_name: str, bottle_names: tuple[str, ...]
@@ -334,20 +351,17 @@ class ManifestIndex:
         """Lazy path (resolve/from_md_dirs): read and parse the agent file and
         its bottle chain from disk for the first time here."""
         assert self.home_md is not None  # guaranteed by load_for_agent dispatch
-        # Locate the agent file; cwd wins over home on name collision.
+        # Agents are home-only (PRD 0082):
+        # a cwd agent file must not select a host identity or forge secret.
         home_agents = scan_agent_names(self.home_md / "agents")
-        cwd_agents: dict[str, Path] = {}
-        if self.cwd_md is not None:
-            cwd_agents = scan_agent_names(self.cwd_md / "agents")
-        merged_agents = {**home_agents, **cwd_agents}
 
-        if agent_name not in merged_agents:
-            available = ", ".join(sorted(merged_agents.keys())) or "(none)"
+        if agent_name not in home_agents:
+            available = ", ".join(sorted(home_agents.keys())) or "(none)"
             raise ManifestError(
                 f"agent '{agent_name}' not defined. Available: {available}"
             )
 
-        agent_path = merged_agents[agent_name]
+        agent_path = home_agents[agent_name]
         try:
             fm, body = parse_frontmatter(agent_path.read_text())
         except OSError as e:
@@ -374,15 +388,18 @@ class ManifestIndex:
         }
         if agent_bottle:
             agent_dict["bottle"] = agent_bottle
-        if "git-gate" in fm:
-            agent_dict["git-gate"] = fm["git-gate"]
+        # Surface agent-owned identity keys (and any stale git-gate, so
+        # ManifestAgent.from_dict raises the migration error).
+        for key in ("author", "forge-accounts", "git-gate"):
+            if key in fm:
+                agent_dict[key] = fm[key]
         # Pass the effective bottle name as the known-bottles set so agents
         # that have bottle: set are validated; agents without bottle: pass {}
         # since bottle_names were already resolved above.
         known = {effective_bottle_name} if effective_bottle_name else set()
         agent = ManifestAgent.from_dict(agent_name, agent_dict, known)
 
-        return _manifest_with_merged_git_user(agent, raw_bottle)
+        return _compose_manifest(agent_name, agent, raw_bottle)
 
     def has_agent(self, name: str) -> bool:
         return name in self.agents
@@ -394,13 +411,9 @@ class ManifestIndex:
         if self.has_agent(name):
             return
         if self.home_md is not None:
-            # Names-only mode: check file existence without parsing.
-            home_path = self.home_md / "agents" / f"{name}.md"
-            cwd_path = (
-                self.cwd_md / "agents" / f"{name}.md"
-                if self.cwd_md else None
-            )
-            if home_path.is_file() or (cwd_path and cwd_path.is_file()):
+            # Names-only mode: check home file existence without parsing.
+            # Agents are home-only; a cwd agent file is never selectable.
+            if (self.home_md / "agents" / f"{name}.md").is_file():
                 return
         available = ", ".join(self.all_agent_names) or "(none)"
         raise ManifestError(

bot_bottle/manifest/schema.py

@@ -22,7 +22,10 @@ BOTTLE_KEYS = frozenset(
     }
 )
 AGENT_KEYS_REQUIRED: frozenset[str] = frozenset()
-AGENT_KEYS_OPTIONAL = frozenset({"bottle", "skills", "git-gate"})
+# `author` / `forge-accounts` are agent-owned identity (PRD
+# 0082). `git-gate` is no longer accepted on an
+# agent: `git-gate.user` moved to `author`, and `git-gate.repos` is bottle-only.
+AGENT_KEYS_OPTIONAL = frozenset({"bottle", "skills", "author", "forge-accounts"})
 
 # Claude Code subagent fields bot-bottle ignores at launch but does
 # not reject. This lets the same file double as

bot_bottle/orchestrator/client.py

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

bot_bottle/orchestrator/lifecycle.py

@@ -21,8 +21,7 @@ import urllib.error
 import urllib.request
 from pathlib import Path
 
-from ..orchestrator_auth import ROLE_GATEWAY, mint
-from ..paths import host_orchestrator_token
+from ..trust_domain import ControlPlaneProvisioning
 
 DEFAULT_PORT = 8099
 DEFAULT_STARTUP_TIMEOUT_SECONDS = 45.0
@@ -58,6 +57,12 @@ class Orchestrator(abc.ABC):
     so it — not the gateway — mints the gateway's role-scoped token.
     Backend-neutral."""
 
+    # The shared control-plane auth provisioning contract (#476). Every backend
+    # gets its signing key + gateway token through this one seam rather than
+    # re-deriving the wiring; it is fail-closed for every backend — the
+    # orchestrator never starts without its signing key.
+    provisioning: ControlPlaneProvisioning = ControlPlaneProvisioning()
+
     def ensure_built(self) -> None:
         """Ensure the orchestrator's image / rootfs exists, building it if
         needed. Default: nothing to build (e.g. a pre-pulled image). Call before
@@ -105,9 +110,17 @@ class Orchestrator(abc.ABC):
     def mint_gateway_token(self) -> str:
         """Mint a role-scoped `gateway` JWT from the host signing key for the
         gateway to present. The orchestrator holds the key; the gateway never
-        does (#469). Backend-neutral — the same host token file is the single
-        source of truth across backends."""
-        return mint(ROLE_GATEWAY, host_orchestrator_token())
+        does (#469). Routed through the shared provisioning contract (#476), so
+        the same host token file is the single source of truth across backends."""
+        return self.provisioning.gateway_token()
+
+    def control_plane_key(self) -> str:
+        """The raw signing key the control-plane *process* must receive — the ONE
+        place a backend obtains it (docker/macOS inject it as `key_env`;
+        firecracker pushes it to the guest). Fail-closed via the provisioning
+        contract: it raises rather than yield an empty key that would run the
+        server OPEN (#476)."""
+        return self.provisioning.orchestrator_key()
 
 
 __all__ = [
@@ -117,4 +130,5 @@ __all__ = [
     "OrchestratorStartError",
     "source_hash",
     "Orchestrator",
+    "ControlPlaneProvisioning",
 ]

bot_bottle/orchestrator/reprovision.py

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

bot_bottle/orchestrator/server.py

@@ -57,14 +57,15 @@ from __future__ import annotations
 
 import http.server
 import json
+import math
 import os
 import socketserver
 import sys
 import typing
 from urllib.parse import urlsplit
 
-from ..orchestrator_auth import ROLE_CLI, ROLES, verify
-from ..paths import ORCHESTRATOR_TOKEN_ENV
+from ..orchestrator_auth import ROLE_CLI, ROLES
+from ..trust_domain import CONTROL_PLANE
 from ..supervisor.types import TOOLS
 from .service import OrchestratorCore
 
@@ -217,13 +218,18 @@ def dispatch(  # pylint: disable=too-many-return-statements,too-many-branches
         raw_ips = data.get("live_source_ips")
         if not isinstance(raw_ips, list):
             return 400, {"error": "live_source_ips (list of strings) is required"}
-        live = [ip for ip in raw_ips if isinstance(ip, str) and ip]
+        if any(not isinstance(ip, str) or not ip for ip in raw_ips):
+            return 400, {"error": "live_source_ips must contain non-empty strings"}
+        live = raw_ips
         grace = data.get("grace_seconds")
-        kwargs = (
-            {"grace_seconds": float(grace)}
-            if isinstance(grace, (int, float)) and not isinstance(grace, bool)
-            else {}
-        )
+        kwargs: dict[str, float] = {}
+        if grace is not None:
+            if isinstance(grace, bool) or not isinstance(grace, (int, float)):
+                return 400, {"error": "grace_seconds must be a non-negative finite number"}
+            parsed_grace = float(grace)
+            if not math.isfinite(parsed_grace) or parsed_grace < 0:
+                return 400, {"error": "grace_seconds must be a non-negative finite number"}
+            kwargs["grace_seconds"] = parsed_grace
         return 200, {"reaped": orch.reconcile(live, **kwargs)}
 
     if method == "POST" and route == "/attribute":
@@ -373,9 +379,15 @@ class Handler(http.server.BaseHTTPRequestHandler):
             status, payload = dispatch(
                 server.orchestrator, method, self.path, body, role=role)
         except Exception as e:  # noqa: BLE001 — the control plane must stay up
-            sys.stderr.write(f"orchestrator: {method} {self.path} failed: {e!r}\n")
+            # Do not echo exception messages to the caller or logs: broker and
+            # persistence exceptions can contain request data. The operation,
+            # route, and exception type are enough to correlate a traceback.
+            sys.stderr.write(
+                f"orchestrator: {method} {self.path} failed "
+                f"[error_type={type(e).__name__}]\n"
+            )
             sys.stderr.flush()
-            status, payload = 500, {"error": f"internal error: {e}"}
+            status, payload = 500, {"error": "internal error"}
         data = json.dumps(payload).encode()
         self.send_response(status)
         self.send_header("Content-Type", "application/json")
@@ -413,11 +425,13 @@ class OrchestratorServer(socketserver.ThreadingMixIn, http.server.HTTPServer):
 
     def __init__(self, address: tuple[str, int], orchestrator: OrchestratorCore) -> None:
         self.orchestrator = orchestrator
-        self._signing_key = os.environ.get(ORCHESTRATOR_TOKEN_ENV, "").strip()
+        # The control-plane trust domain's signing key, as injected into THIS
+        # (the owning) process by the launcher (#476). Unset → open mode below.
+        self._signing_key = CONTROL_PLANE.key_from_env()
         if not self._signing_key:
             sys.stderr.write(
                 "orchestrator: WARNING — no control-plane signing key "
-                f"(${ORCHESTRATOR_TOKEN_ENV}); running WITHOUT caller "
+                f"(${CONTROL_PLANE.key_env}); running WITHOUT caller "
                 "authentication. Any client that can reach this port can drive "
                 "it. Backends that put the control plane on an agent-reachable "
                 "network MUST set this.\n"
@@ -433,7 +447,7 @@ class OrchestratorServer(socketserver.ThreadingMixIn, http.server.HTTPServer):
         role (→ per-route 401/403 in `dispatch`)."""
         if not self._signing_key:
             return ROLE_CLI
-        return verify(presented, self._signing_key)
+        return CONTROL_PLANE.verify(presented, self._signing_key)
 
 
 def make_server(

bot_bottle/orchestrator/store/registry_store.py

@@ -113,7 +113,7 @@ _MIGRATIONS = TableMigrations(
         # egress allowlist / routes / git config selected by source IP. The
         # multi-tenant gateway resolves it per request via `attribute`.
         "ALTER TABLE orchestrator_bottles ADD COLUMN policy TEXT NOT NULL DEFAULT ''",
-        # v4 — per-bottle encrypted egress secrets (PRD 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

bot_bottle/orchestrator/store/secret_store.py

@@ -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

bot_bottle/orchestrator_auth.py

@@ -59,12 +59,17 @@ _HEADER_SEGMENT = _b64url_encode(
 )
 
 
-def mint(role: str, secret: str) -> str:
+def mint(role: str, secret: str, *, roles: frozenset[str] = ROLES) -> str:
     """A compact HS256 token asserting `role`, signed with `secret`.
 
-    Raises ValueError for an unknown role (mint only what the control plane will
-    accept) or an empty signing key (an unsigned credential is never valid)."""
-    if role not in ROLES:
+    `roles` is the set the signing key is allowed to sign (default: the
+    orchestrator's `{gateway, cli}`). A separate service (e.g. the host
+    controller) passes its own key + role set so its tokens can't be forged with
+    the orchestrator's key — see `trust_domain.py`, issues #476/#468.
+
+    Raises ValueError for a role outside `roles`, or an empty signing key (an
+    unsigned credential is never valid)."""
+    if role not in roles:
         raise ValueError(f"unknown control-plane role {role!r}")
     if not secret:
         raise ValueError("cannot mint a control-plane token without a signing key")
@@ -73,10 +78,11 @@ def mint(role: str, secret: str) -> str:
     return f"{signing_input}.{_sign(secret, signing_input)}"
 
 
-def verify(token: str, secret: str) -> str | None:
+def verify(token: str, secret: str, *, roles: frozenset[str] = ROLES) -> str | None:
     """The role a valid `token` carries, or None if it is malformed, wrongly
-    signed, or names an unknown role. Constant-time signature check; rejects any
-    header whose alg isn't HS256 (no alg-confusion / `none`)."""
+    signed, or names a role outside `roles` (the verifying trust domain's set —
+    default `{gateway, cli}`). Constant-time signature check; rejects any header
+    whose alg isn't HS256 (no alg-confusion / `none`)."""
     if not token or not secret:
         return None
     parts = token.split(".")
@@ -94,7 +100,7 @@ def verify(token: str, secret: str) -> str | None:
     if not isinstance(header, dict) or header.get("alg") != _ALG:
         return None
     role = payload.get("role") if isinstance(payload, dict) else None
-    return role if isinstance(role, str) and role in ROLES else None
+    return role if isinstance(role, str) and role in roles else None
 
 
 __all__ = ["ROLE_GATEWAY", "ROLE_CLI", "ROLES", "mint", "verify"]

bot_bottle/paths.py

@@ -97,16 +97,17 @@ def host_gateway_ca_dir() -> Path:
     return ca_dir
 
 
-def host_orchestrator_token() -> str:
-    """The per-host control-plane secret, minted (256-bit, url-safe) and
-    persisted 0600 on first use, then reused.
+def host_signing_key(filename: str) -> str:
+    """A per-host signing key at `<root>/<filename>`, minted (256-bit, url-safe)
+    and persisted 0600 on first use, then reused.
 
-    This is the shared secret the launchers inject into the control-plane and
-    gateway containers and that the host CLI presents on every call. It is a
-    *host* artifact — the file lives under the root the agent never mounts, and
-    the env var is set only on the trusted containers — so reading it here is
-    safe on the host launch path but the value never reaches a bottle."""
-    path = bot_bottle_root() / ORCHESTRATOR_TOKEN_FILENAME
+    The generic form of `host_orchestrator_token()`: each service names its own
+    key file (`trust_domain.py`), so the orchestrator and a separate service like
+    the host controller (#468) get distinct keys neither can read. It is a *host*
+    artifact — the file lives under the root the agent never mounts, and its value
+    is injected only into the trusted control-plane process — so reading it here
+    is safe on the launch path but the value never reaches a bottle."""
+    path = bot_bottle_root() / filename
     try:
         existing = path.read_text().strip()
         if existing:
@@ -128,6 +129,14 @@ def host_orchestrator_token() -> str:
     return token
 
 
+def host_orchestrator_token() -> str:
+    """The per-host control-plane signing key — the host-canonical key the
+    launchers inject into the control-plane process and the host CLI mints its
+    own `cli` token from. The `control-plane` trust domain's specialization of
+    `host_signing_key()`."""
+    return host_signing_key(ORCHESTRATOR_TOKEN_FILENAME)
+
+
 __all__ = [
     "HOST_DB_FILENAME",
     "ORCHESTRATOR_TOKEN_FILENAME",
@@ -138,5 +147,6 @@ __all__ = [
     "host_db_path",
     "host_db_dir",
     "host_gateway_ca_dir",
+    "host_signing_key",
     "host_orchestrator_token",
 ]

bot_bottle/resources.py

@@ -0,0 +1,232 @@
+"""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 json
+import os
+import re
+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",
+    "image-build-args.json",
+    "Dockerfile.gateway",
+    "Dockerfile.orchestrator",
+    "Dockerfile.orchestrator.fc",
+    "requirements.gateway.lock",
+    "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"
+_IMAGE_BUILD_ARGS_FILE = "image-build-args.json"
+_CENTRAL_BUILD_ARG_NAMES = frozenset({
+    "DOCKER_CLI_BASE_IMAGE",
+    "NODE_BASE_IMAGE",
+    "PYTHON_BASE_IMAGE",
+})
+
+
+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 image_build_args(
+    dockerfile_path: str | Path,
+    *,
+    context: str | Path | None = None,
+) -> dict[str, str]:
+    """Return centralized arguments declared by ``dockerfile_path``.
+
+    Base-image arguments deliberately have no Dockerfile defaults. Their
+    digest-pinned values live in one repository input file and every supported
+    build path calls this helper before invoking its OCI builder. Explicit
+    caller-supplied arguments may still override this returned mapping.
+    """
+    path = Path(dockerfile_path)
+    if not path.is_absolute() and context is not None:
+        path = Path(context) / path
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        # Generic callers and tests may build an ephemeral Dockerfile outside
+        # bot-bottle. The builder will report a genuinely missing file.
+        return {}
+    declared = set(re.findall(
+        r"(?m)^\s*ARG\s+([A-Za-z_][A-Za-z0-9_]*)\s*$",
+        text,
+    ))
+    wanted = declared & _CENTRAL_BUILD_ARG_NAMES
+    if not wanted:
+        return {}
+    # Generated Dockerfiles (notably the macOS nested-container layer) live in
+    # temporary build contexts. Resolve their declaration there, but take the
+    # centralized values from that context only when it carries its own input
+    # file; otherwise use bot-bottle's staged build root.
+    context_root = Path(context) if context is not None else None
+    root = (
+        context_root
+        if context_root is not None
+        and (context_root / _IMAGE_BUILD_ARGS_FILE).is_file()
+        else build_root()
+    )
+    inputs_path = root / _IMAGE_BUILD_ARGS_FILE
+    try:
+        inputs = json.loads(inputs_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ResourceError(
+            f"cannot read centralized image build arguments from {inputs_path}: {exc}"
+        ) from exc
+    if not isinstance(inputs, dict):
+        raise ResourceError(f"{inputs_path} must contain a JSON object")
+    missing = wanted - inputs.keys()
+    if missing:
+        raise ResourceError(
+            f"{inputs_path} lacks required image build arguments: "
+            f"{', '.join(sorted(missing))}"
+        )
+    invalid = [name for name in wanted if not isinstance(inputs[name], str)]
+    if invalid:
+        raise ResourceError(
+            f"{inputs_path} has non-string image build arguments: "
+            f"{', '.join(sorted(invalid))}"
+        )
+    return {name: inputs[name] for name in sorted(wanted)}
+
+
+def nix_netpool_module() -> Path:
+    """Absolute path to the firecracker netpool NixOS module."""
+    return build_root() / "nix" / "firecracker-netpool.nix"
+
+
+def netpool_script() -> Path:
+    """Absolute path to the firecracker netpool bring-up script."""
+    return build_root() / "scripts" / "firecracker-netpool.sh"
+
+
+def _content_digest() -> str:
+    """A 16-hex digest of the installed package + bundled resources.
+
+    Keys the staged build root by *content*, so a force-reinstall over the same
+    version string (the installer defaults to a git branch + ``pipx install
+    --force``, and ``version`` stays ``0.1.0``) yields a different key and
+    re-stages, rather than reusing an old commit's tree. ``_PKG`` already
+    contains ``_resources``, so walking it covers both."""
+    h = hashlib.sha256()
+    for path in sorted(_PKG.rglob("*")):
+        if not path.is_file() or "__pycache__" in path.parts or path.suffix == ".pyc":
+            continue
+        h.update(str(path.relative_to(_PKG)).encode())
+        h.update(b"\0")
+        h.update(path.read_bytes())
+    return h.hexdigest()[:16]
+
+
+def _stage_build_root() -> Path:
+    """Materialize a repo-root-shaped build context from the installed wheel's
+    bundled resources, keyed by content digest. Idempotent and concurrency-safe:
+    a file lock serializes staging, a partial/stale tree is replaced, and the
+    finished tree is published with an atomic rename."""
+    if not _BUNDLED.is_dir():
+        raise ResourceError(
+            "bot-bottle build resources are missing from this install "
+            f"(expected {_BUNDLED}). Reinstall the package."
+        )
+    base = bot_bottle_root() / "build-root"
+    base.mkdir(parents=True, exist_ok=True)
+    dest = base / _content_digest()
+    if (dest / ".complete").is_file():
+        return dest
+
+    # Serialize staging across processes: a concurrent `start` after an install
+    # must not race on the shared tree. The lock is held only around stage +
+    # atomic publish; the fast path above never blocks.
+    with open(base / ".stage.lock", "w", encoding="utf-8") as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        if (dest / ".complete").is_file():  # another process staged while we waited
+            return dest
+        # Stage into a private temp dir on the same filesystem, then publish by
+        # rename — never populate a shared path other processes might read.
+        staging = Path(tempfile.mkdtemp(prefix=".staging-", dir=base))
+        try:
+            # The package itself, minus caches and the bundled-resource copies,
+            # so the staged ``bot_bottle/`` matches a checkout's (keeps the
+            # firecracker infra-artifact hash stable across checkout and wheel).
+            shutil.copytree(
+                _PKG,
+                staging / "bot_bottle",
+                ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "_resources"),
+            )
+            # The bundled root files, restored to their checkout-relative layout.
+            for rel in BUNDLED_RESOURCES:
+                dst = staging / rel
+                dst.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(_BUNDLED / rel, dst)
+            (staging / ".complete").write_text("")
+            # Replace any partial leftover for this digest (safe: we hold the
+            # lock), then publish atomically.
+            if dest.exists():
+                shutil.rmtree(dest)
+            os.replace(staging, dest)
+            staging = None  # published; nothing to clean up
+        finally:
+            if staging is not None:
+                shutil.rmtree(staging, ignore_errors=True)
+    return dest

bot_bottle/trust_domain.py

@@ -0,0 +1,140 @@
+"""Per-service control-plane signing keys (issue #476).
+
+A `TrustDomain` is one service's signing material: its host-canonical key file,
+the roles that key may sign, and the env vars its key and a pre-minted token ride
+in. Scoping `mint`/`verify` to a domain's roles keeps one service's key from
+signing (or accepting) another service's tokens.
+
+Today there is one domain, `CONTROL_PLANE` — the orchestrator's key (roles
+`{gateway, cli}`): the orchestrator holds it and mints the gateway's and CLI's
+tokens. The host controller (#468) will add a **second** domain with its own key
+the orchestrator never holds. That is the point: the host controller starts and
+stops the orchestrator, so the orchestrator must not be able to mint the
+credentials it uses to talk to it. Adding a `host` role to `CONTROL_PLANE`
+instead would defeat that — the orchestrator holds that key, so it could forge
+`host` tokens.
+
+`ControlPlaneProvisioning` is the one seam every backend launcher uses to get the
+orchestrator its key and the gateway its token, instead of re-deriving that
+wiring per backend (the bug class behind PR #471 — see
+`docs/prds/0079-control-plane-auth-provisioning.md`).
+
+Stdlib-only: the HMAC lives in `orchestrator_auth`, the key file in `paths`.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from . import orchestrator_auth
+from .orchestrator_auth import ROLE_GATEWAY
+from .paths import (
+    ORCHESTRATOR_AUTH_JWT_ENV,
+    ORCHESTRATOR_TOKEN_ENV,
+    ORCHESTRATOR_TOKEN_FILENAME,
+    host_signing_key,
+)
+
+
+class ProvisioningError(RuntimeError):
+    """A control-plane auth invariant would be violated (e.g. starting the
+    orchestrator without its signing key — which would run OPEN)."""
+
+
+@dataclass(frozen=True)
+class TrustDomain:
+    """One service's signing material: a host-canonical key file, the roles that
+    key may sign, and the env vars its key and a minted token ride in.
+
+    The service that *owns* the domain (e.g. the orchestrator) receives the raw
+    key via `key_env`; a delegate (e.g. the gateway) receives only a pre-minted,
+    role-scoped token via `token_env` it cannot rewrite. `mint`/`verify` are
+    scoped to `roles`, so this service's key can neither sign nor accept another
+    service's role."""
+
+    name: str
+    key_filename: str
+    roles: frozenset[str]
+    key_env: str
+    token_env: str
+
+    def signing_key(self) -> str:
+        """This service's host-canonical signing key (minted 0600 on first use).
+        Host-side only — the value is injected into the owning process."""
+        return host_signing_key(self.key_filename)
+
+    def key_from_env(self, environ: Mapping[str, str] | None = None) -> str:
+        """The signing key as the owning process sees it — read from `key_env`
+        (default `os.environ`). "" when unset; the caller decides whether that is
+        fatal (`ControlPlaneProvisioning`) or the open-mode fallback
+        (`OrchestratorServer`)."""
+        env = os.environ if environ is None else environ
+        return env.get(self.key_env, "").strip()
+
+    def mint(self, role: str) -> str:
+        """A role-scoped token for a delegate, signed with this service's key.
+        Raises ValueError for a role this service doesn't sign."""
+        if role not in self.roles:
+            raise ValueError(f"role {role!r} is not in trust domain {self.name!r}")
+        return orchestrator_auth.mint(role, self.signing_key(), roles=self.roles)
+
+    def verify(self, token: str, key: str) -> str | None:
+        """The role `token` carries under `key`, or None. `key` is passed in
+        (not read from disk) because the verifier — the control-plane process —
+        holds it in `key_env`, not on disk in its guest."""
+        return orchestrator_auth.verify(token, key, roles=self.roles)
+
+
+# The orchestrator's domain: the key the orchestrator (and host CLI) holds, the
+# `gateway` token it mints for the data plane, and the `cli` token the CLI mints
+# for itself. #468's host controller will add a second, separate domain.
+CONTROL_PLANE = TrustDomain(
+    name="control-plane",
+    key_filename=ORCHESTRATOR_TOKEN_FILENAME,
+    roles=orchestrator_auth.ROLES,
+    key_env=ORCHESTRATOR_TOKEN_ENV,
+    token_env=ORCHESTRATOR_AUTH_JWT_ENV,
+)
+
+
+@dataclass(frozen=True)
+class ControlPlaneProvisioning:
+    """The one seam every backend launcher uses to provision control-plane auth,
+    instead of re-deriving the four invariants that each cost a PR #471 review
+    round: the orchestrator gets the raw key (`orchestrator_key`), the gateway
+    gets a minted `gateway` token (`gateway_token`), the host CLI mints its own
+    `cli` token from the same host-canonical key, and the orchestrator never
+    starts open."""
+
+    domain: TrustDomain = CONTROL_PLANE
+
+    def orchestrator_key(self) -> str:
+        """The raw signing key the orchestrator process must receive (carry it in
+        `domain.key_env`). Fail-closed: raises rather than return "", since an
+        empty key runs the server open — and being on a separate host does not
+        stop the gateway from reaching the control plane (it must, for
+        `/resolve`), so an open orchestrator would treat that gateway as `cli`."""
+        key = self.domain.signing_key()
+        if not key:
+            raise ProvisioningError(
+                f"refusing to start the {self.domain.name} orchestrator without "
+                "a signing key: an open orchestrator authenticates no one and "
+                "grants every caller that reaches it full `cli` (#476)"
+            )
+        return key
+
+    def gateway_token(self) -> str:
+        """The `gateway`-role token the gateway receives (carry it in
+        `domain.token_env`) — minted from the key, never the key itself, so a
+        compromised gateway cannot forge a `cli` token."""
+        return self.domain.mint(ROLE_GATEWAY)
+
+
+__all__ = [
+    "ProvisioningError",
+    "TrustDomain",
+    "CONTROL_PLANE",
+    "ControlPlaneProvisioning",
+]

bot_bottle/util.py

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

docs/README.md

@@ -7,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. |

docs/ci.md

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

docs/decisions/0004-coverage-policy.md

@@ -3,6 +3,10 @@
 - **Status:** Accepted
 - **Date:** 2026-06-25
 - **Deciders:** didericis
+- **Revised:** 2026-07-27 — thresholds relaxed (critical minimum 90→85%,
+  diff-coverage gate 90→80%) to cut low-value test churn on changed lines.
+  The risk-weighting structure and the "global is informational" rule are
+  unchanged.
 
 ## Context
 
@@ -34,12 +38,13 @@ a regression (Goodhart's law).
 Coverage is **risk-weighted**, measured over the **combined unit +
 integration** suites, with three rules:
 
-1. **Critical modules target ≥ 90%.** The security/logic core —
-   `egress_addon{,_core}.py`, `dlp_detectors.py`, `egress.py`,
-   `manifest*.py`, `git_gate.py`, `git_http_backend.py`, `supervise.py`,
-   `yaml_subset.py`, `bottle_state.py` — is Docker-independent and
-   unit-testable, so it carries the high bar. We ratchet toward 90% as
-   these modules are touched; new gaps in them are not acceptable.
+1. **Critical modules must remain ≥ 85%.** The curated security/logic core
+   covers the host and gateway egress policy, manifest trust boundary,
+   git-gate enforcement, supervise protocol/server, YAML parser, and bottle
+   state. The concrete module list lives in `scripts/critical-modules.txt`;
+   `scripts/critical_modules.py` rejects stale or ambiguous entries before
+   Coverage.py can silently ignore them. These modules are unit-testable, so
+   CI enforces the aggregate minimum independently of diff coverage.
 
 2. **Subprocess/backend orchestration is covered by the integration
    suite, not omitted.** `scripts/coverage.sh` runs unit + integration
@@ -54,7 +59,7 @@ integration** suites, with three rules:
 
 The forward-looking guard is a **diff-coverage gate**
 (`scripts/diff_coverage.py`): new/changed executable lines on a branch
-must be ≥ 90% covered. This catches regressions where they are
+must be ≥ 80% covered. This catches regressions where they are
 introduced without forcing a back-fill crusade through legacy glue. The
 gate skips lines in omitted files (there is no coverage data for them),
 so the omit list cannot launder *new* logic into the dark: anything that
@@ -82,6 +87,9 @@ omit list.
   (critical-module standard + diff coverage) are Docker-independent.
 - "We're at N%" is now a curated figure; outsiders should read the
   policy, not just the badge.
+- A rename or removal in the curated list fails CI. Updating the list is an
+  explicit review of where the security-critical behavior moved, not a way to
+  improve the percentage by omission.
 
 ## Links
 

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

@@ -1,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`.

docs/design-workflow.md

@@ -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.**

docs/image-build-inputs.md

@@ -0,0 +1,68 @@
+# Container image build inputs
+
+Bot-bottle's supported images are intended to rebuild from the same declared
+inputs on Linux amd64 and arm64. The repository enforces four layers of
+immutability:
+
+- Python, Node, and nested-container Docker CLI base images are required,
+  defaultless Docker build arguments.
+  Their version-qualified tags and multi-platform OCI index digests live
+  together in `image-build-args.json`; every supported builder reads that
+  file and passes only the arguments its Dockerfile declares.
+- Debian packages resolve from the same dated `snapshot.debian.org` archive in
+  every image that runs `apt-get install`. The snapshot endpoint uses HTTP so a
+  fresh image does not need a host-specific TLS interception CA; APT still
+  authenticates the repository metadata and package hashes with Debian's
+  signed Release files.
+- Gateway Python dependencies install from `requirements.gateway.lock` with
+  `pip --require-hashes`; provider npm packages install with `npm ci` from
+  committed lockfiles.
+- The Codex standalone archive is fetched from the exact `CODEX_VERSION`
+  release and checked against the committed upstream
+  `codex-package_SHA256SUMS` before extraction.
+  The standalone layout is retained because Codex remote control requires it.
+
+`Dockerfile.orchestrator.fc` is the one intentionally dynamic `FROM`. It has no
+default value: the Firecracker build coordinator resolves the freshly built
+orchestrator's local `sha256:` image ID, creates a local tag containing the
+complete ID, verifies that tag resolves to the same ID, and supplies the
+content-derived reference as `ORCHESTRATOR_BASE_IMAGE`. This accommodates
+BuildKit, which treats a bare image ID in `FROM` as a registry repository.
+
+## Refreshing inputs
+
+Make refreshes on a feature branch and review them like an application
+dependency update:
+
+1. For a Python or Node base update, select a version-qualified tag and update
+   its one digest-pinned value in `image-build-args.json`. Confirm the index
+   still contains `linux/amd64` and `linux/arm64`.
+2. For Debian packages, advance `DEBIAN_SNAPSHOT` to one fixed UTC timestamp in
+   every Dockerfile that uses apt. Do not use the moving Debian mirrors.
+3. Change direct Python versions in `requirements.gateway.in`, direct npm
+   versions in the provider's `package.json`, or `CODEX_VERSION` in the Codex
+   Dockerfile. Direct versions must be exact—no ranges, dist-tags, or
+   unversioned package names.
+4. Push the feature branch or manually run the `refresh-image-locks` workflow.
+   It regenerates the four derived files with the image's exact Python and Node
+   versions and uploads them as the `image-input-locks` artifact. It never
+   writes to the branch, so a refresh cannot race with developer pushes.
+5. Download the artifact, replace the four committed files, review the lock
+   diff, and let both normal CI and `image-input-builds` pass.
+   The latter checks both base architectures, builds every supported image,
+   exercises the exact local Firecracker base-ID handoff, and runs each
+   provider CLI's version smoke test.
+
+Run the fast policy check locally at any point:
+
+```sh
+python3 scripts/check_image_inputs.py
+```
+
+The check rejects mutable or `latest` bases, moving apt repositories,
+network-to-shell installers, unlocked npm/Pi installs, non-exact direct
+dependencies, missing npm integrity values, and unhashed gateway Python
+requirements.
+
+Image signing and attestation are tracked separately in issue #339; this policy
+covers deterministic and integrity-checked build inputs.

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

@@ -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

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

@@ -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 /

docs/prds/0011-per-file-md-manifest.md

@@ -1,9 +1,19 @@
 # PRD 0011: Per-file Markdown manifest
 
-- **Status:** Active
+- **Status:** Active (agent cwd-discovery superseded)
 - **Author:** didericis
 - **Created:** 2026-05-24
 
+> **Superseded in part by PRD 0082.**
+> The `$CWD/.bot-bottle/agents/<name>.md` discovery/override path described
+> below is removed: agents are now **home-only**, like bottles. Once an agent
+> definition can select a host identity (`author`) and a host forge secret
+> (`forge-accounts`), letting checked-out workspace content define or override
+> an agent would let untrusted content select host credentials. A cwd
+> `agents/` (or `bottles/`) directory is now warned-about and ignored. The
+> filesystem-layout trust boundary still holds — it just admits nothing from
+> `$CWD`.
+
 ## Summary
 
 Replace the single-file `bot-bottle.json` manifest with a

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

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

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

@@ -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

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

@@ -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

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

@@ -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

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

@@ -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

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

@@ -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

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

@@ -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,

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

@@ -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