fix(git-gate): reject AGit review refs

- Coverage: 83%
- Core coverage: 94%

[skip ci]

.gitea/workflows/test.yml

@@ -212,6 +212,89 @@ jobs:
           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%).
   #

README.md

@@ -30,7 +30,7 @@
 
 ## Architecture
 
-On the default macOS Apple Container backend, a bottle is an agent container on a host-only internal network plus a gateway attached to both that internal network and a NAT egress network. The agent gets HTTP(S)_PROXY and CA bundle env vars pointing at the gateway's internal-network IP, so HTTP/HTTPS traffic flows through the gateway instead of direct egress. `bottle.git` / git-gate is intentionally deferred on this backend until a safe Apple Container key-delivery path exists.
+On the default macOS Apple Container backend, a bottle is an agent container on a host-only internal network plus a gateway attached to both that internal network and a NAT egress network. The agent gets HTTP(S)_PROXY and CA bundle env vars pointing at the gateway's internal-network IP, so HTTP/HTTPS traffic flows through the gateway instead of direct egress. git-gate runs over the gateway's consolidated `git-http` daemon (the legacy per-bottle `git://` daemon is not used on this backend); keys are provisioned dynamically at launch and revoked on teardown.
 
 On the Firecracker backend, a bottle is an agent microVM plus a Docker gateway for egress, git-gate, and supervise. The VM reaches the gateway over a per-bottle point-to-point TAP link; a dedicated fail-closed `nftables` table (`inet bot_bottle_fc`) confines the guest to that link, so nothing leaves the box except through the gateway. The TAP pool and nft table are provisioned once (root); per-launch needs no privilege.
 
@@ -75,6 +75,8 @@ On compatible macOS hosts, the default backend requires Apple's `container` CLI
 
 Use `BOT_BOTTLE_BACKEND=docker ./cli.py start <agent>` on hosts where neither Apple Container nor KVM is available and Docker is the desired backend.
 
+> **CI (macOS Apple Container):** the `integration-macos` job (`.gitea/workflows/test.yml`) runs the integration suite against `BOT_BOTTLE_BACKEND=macos-container` on a self-hosted macOS runner labelled `macos`, because Apple Container needs the host virtualization framework and cannot run in a Linux container (so it can't reuse the `kvm` runner). Provision an Apple Silicon host with the `container` CLI on `PATH` and `container system status` running, then register the runner in **host mode** (not docker mode) with the `macos` label — `brew install gitea-runner` (the `act_runner` rename). Give it a Python ≥ 3.11 with `coverage` importable on the launchd service's `PATH` (a launchd service doesn't inherit your shell profile, so pin `node` and the Python env explicitly). The job is **advisory** — `workflow_dispatch` (manual) only, never triggered by push or PR — since a single laptop that sleeps/roams must not block merges or churn on every push to main; its coverage doesn't feed the gate. The infra container is a singleton (`bot-bottle-mac-infra`), so keep runner concurrency at 1.
+
 ### Containers inside a bottle
 
 A bottle may set `nested_containers: true`. On the macOS backend this starts a

bot_bottle/backend/docker/orchestrator.py

@@ -20,7 +20,6 @@ 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 (
@@ -172,7 +171,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,

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/macos_container/orchestrator.py

@@ -19,10 +19,7 @@ from pathlib import Path
 
 from ... import log
 from ... import resources
-from ...paths import (
-    ORCHESTRATOR_TOKEN_ENV,
-    host_orchestrator_token,
-)
+from ...paths import ORCHESTRATOR_TOKEN_ENV
 from ...orchestrator.lifecycle import (
     DEFAULT_HEALTH_TIMEOUT_SECONDS,
     DEFAULT_PORT,
@@ -136,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/cli/commands/doctor.py

@@ -2,7 +2,8 @@
 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 usable backend. The config directory is a soft
+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.
 """
@@ -13,7 +14,7 @@ import argparse
 import sys
 from pathlib import Path
 
-from ...backend import is_backend_available, known_backend_names
+from ...backend import is_backend_ready, known_backend_names
 from ..constants import PROG
 
 MIN_PYTHON = (3, 11)
@@ -43,19 +44,25 @@ def _check_python() -> bool:
 
 
 def _check_backends() -> bool:
-    """At least one backend must be available on this host. Report each
-    known backend so the operator sees why a missing one is missing."""
-    available = []
+    """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_available(name):
-            available.append(name)
-    if available:
-        _ok("backend", f"available: {', '.join(available)}")
+        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 available; install Apple Container (macOS), "
-        "Firecracker (Linux), or Docker",
+        "no backend is ready to run a bottle; start Docker, or finish "
+        "Apple Container (macOS) / Firecracker (Linux) setup",
     )
     return False
 

bot_bottle/gateway/git_gate/render.py

@@ -252,6 +252,23 @@ cat > "$refs_file"
 
 zero=0000000000000000000000000000000000000000
 
+# AGit creates pull requests by pushing to refs/for/* (with refs/draft/*
+# and refs/for-review/* aliases). Those server-owned review refs are not
+# ordinary repository branches and leave the resulting PR without a
+# branch that the bottle can update later. Require the normal
+# push-branch-then-open-PR workflow instead. Deletion remains allowed so
+# operators can clean up refs created before this guard existed.
+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: AGit review refs are disabled; push to refs/heads/<branch> and open the pull request from that branch" >&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

bot_bottle/orchestrator/client.py

@@ -18,8 +18,8 @@ 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 ..orchestrator_auth import ROLE_CLI
+from ..trust_domain import CONTROL_PLANE
 from .server import ORCHESTRATOR_AUTH_HEADER
 
 DEFAULT_TIMEOUT_SECONDS = 5.0
@@ -32,7 +32,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 ""
 

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/server.py

@@ -63,8 +63,8 @@ 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
 
@@ -413,11 +413,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 +435,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_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/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",
+]

docs/ci.md

@@ -2,11 +2,22 @@
 
 The test workflow lives at [`.gitea/workflows/test.yml`](../.gitea/workflows/test.yml).
 It runs the unit suite plus one integration job per backend
-(`integration-docker`, `integration-firecracker`) on:
+(`integration-docker`, `integration-firecracker`, `integration-macos`) on:
 
 - every push to a branch with an open pull request, and
 - every push to `main`.
 
+`integration-macos` is the exception: it is **advisory**, running only on
+`workflow_dispatch` (manual dispatch), never on push or pull requests. It targets the
+Apple Container backend on a self-hosted macOS runner (label `macos`,
+registered in host mode — Apple Container can't run in a Linux container, so it
+can't reuse the `kvm` runner). A single non-redundant laptop must not be able
+to block a PR merge, so the job stays out of the `coverage` job's `needs` and
+its coverage never feeds the diff-coverage gate. Because the infra container is
+a singleton (`bot-bottle-mac-infra`), the job declares a `concurrency` group
+and tears the container down on exit; keep runner concurrency at 1. See the
+README "macOS Apple Container" CI note for runner provisioning.
+
 Each integration job selects its backend via `BOT_BOTTLE_BACKEND` and
 runs a **preflight** (`./cli.py backend status --backend=<name>`) that
 prints a clear per-check readiness summary and fails the job when the

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

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

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

docs/prds/0071-claude-forward-host-credentials.md

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

docs/prds/0072-nonblocking-supervise.md

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

docs/prds/0073-consolidate-docker-infra-backend.md

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

docs/prds/0074-ci-artifact-coverage.md

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

docs/prds/0075-nested-containers.md

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

docs/prds/0076-modernize-built-in-agent-images.md

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

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

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

docs/prds/0078-install-script.md

@@ -1,6 +1,6 @@
-# PRD prd-new: Quick install script
+# PRD 0078: Quick install script
 
-- **Status:** Draft
+- **Status:** Active
 - **Author:** claude
 - **Created:** 2026-07-25
 - **Issue:** #197
@@ -33,7 +33,7 @@ user whether their host is actually ready to run a bottle.
   `bot-bottle doctor`. It never installs Docker or a VM backend silently
   and never uses `sudo`.
 - `install.sh` is idempotent — safe to re-run.
-- `bot-bottle doctor` reports Python version, backend availability, and
+- `bot-bottle doctor` reports Python version, backend *readiness*, and
   config-dir presence, exiting non-zero when a hard prerequisite is unmet.
 - The package keeps **zero runtime pip dependencies** (stdlib-only,
   matching the existing constraint in `AGENTS.md`).
@@ -129,8 +129,11 @@ A POSIX `sh` bootstrapper that:
 4. Installs via `pipx` if available, else `python3 -m pip install --user`.
    The spec defaults to the git URL and is overridable via
    `BOT_BOTTLE_INSTALL_SPEC` (used by tests / local installs).
-4. Locates the `bot-bottle` entry point (PATH or `~/.local/bin`).
-5. Runs `bot-bottle doctor` and reports the result.
+5. Locates the `bot-bottle` entry point: PATH first, else the
+   interpreter's own user-scheme scripts dir resolved via `sysconfig`
+   (`~/.local/bin` on Linux, `~/Library/Python/<X.Y>/bin` on a python.org
+   macOS interpreter — not hardcoded).
+6. Runs `bot-bottle doctor` and reports the result.
 
 It is idempotent and never calls `sudo`.
 
@@ -140,10 +143,12 @@ A new store-free subcommand (no DB migration required) that checks and
 reports:
 
 - **python** — interpreter version (hard requirement: ≥ 3.11).
-- **backend** — at least one backend available on this host
-  (macos-container / firecracker / docker), reusing
-  `is_backend_available()` rather than hardcoding Docker, since the
-  default backend is now a VM backend. Hard requirement.
+- **backend** — at least one backend *ready* on this host
+  (macos-container / firecracker / docker), via `is_backend_ready()` — a
+  full backend `status()` probe (daemon reachable, network pool present,
+  KVM usable), not a PATH-only check: a stopped daemon or half-configured
+  backend must not report `ok` when `start` can't work. Each not-ready
+  backend prints its own diagnostics. Hard requirement.
 - **config** — whether `~/.bot-bottle/` exists (advisory only; `start`
   provisions on first run).
 
@@ -152,7 +157,8 @@ Exits 0 when both hard requirements pass, non-zero otherwise.
 ## Testing strategy
 
 - Unit test `bot-bottle doctor` success/failure paths with backend
-  availability and Python version mocked.
+  readiness (`is_backend_ready`) and Python version mocked, including the
+  available-but-not-ready → fail case.
 - Unit test that `pyproject.toml` parses, declares the entry point and an
   empty `dependencies` list, and that every `package-data` glob resolves
   to a file that exists on disk (guards against drift).

docs/prds/0079-control-plane-auth-provisioning.md

@@ -0,0 +1,89 @@
+# PRD 0079: Per-service signing keys for control-plane auth
+
+- **Status:** Active
+- **Author:** claude
+- **Created:** 2026-07-26
+- **Issue:** #476
+
+## Summary
+
+Provision control-plane signing keys **per service**, through one shared seam, so
+no service can mint another's credentials. Concretely: the orchestrator holds the
+control-plane key and mints the gateway's and CLI's tokens; the host controller
+(#468, next) gets a **separate** key the orchestrator never holds — so the
+orchestrator cannot forge the credentials it uses to talk to the host controller
+that starts and stops it. Landing this seam also retires the per-backend
+provisioning duplication that made PR #471 take three review rounds.
+
+## Problem
+
+**1. The orchestrator could forge host-controller credentials.** The
+orchestrator's key signs roles `{gateway, cli}`. The tempting way to add the host
+controller (#468) is a third role, `host`, on that same key. But then the
+orchestrator — which holds the key — can mint `host` tokens, and the host
+controller, which owns the orchestrator's lifecycle, must not trust anything the
+orchestrator can mint. The two services need separate keys.
+
+**2. Every backend provisioned auth by hand.** Each launcher (docker
+gateway/infra, macOS infra, firecracker infra) re-derived how to generate the
+signing key, scope it to the orchestrator, mint the gateway JWT, and keep the
+host key file canonical. All three PR #471 High-severity findings were this one
+integration bug in different launchers: the data plane got the full `cli` token;
+the firecracker control plane ran open; the firecracker guest clobbered the host
+key.
+
+## Goals / Success Criteria
+
+- The orchestrator and the host controller sign with **different** keys; neither
+  can mint the other's tokens. (This PR provisions the orchestrator's key and
+  leaves a drop-in seam for the host controller's.)
+- One shared provisioning seam every backend uses — a new backend or daemon
+  implements it instead of rediscovering these four invariants:
+  1. the signing key is host-canonical: a guest is handed it, never generates or
+     overwrites it;
+  2. only the orchestrator process gets the raw key; the gateway gets a
+     pre-minted `gateway` token it can't rewrite into `cli`;
+  3. the host CLI's `cli` token is minted from the same key, so it stays valid
+     across co-running backends;
+  4. the orchestrator never runs open — the signing key is mandatory, with no
+     topology opt-out (a separate host does not stop a caller from reaching the
+     control-plane listener, so it cannot make open mode safe).
+
+## Non-goals
+
+- The host controller itself (#468) — this only provisions the orchestrator's
+  key and the seam #468 plugs into.
+- Rewriting the HMAC primitive: `orchestrator_auth.mint/verify` gain an optional
+  `roles=` arg (default unchanged) so a key can carry a different role set;
+  nothing else changes.
+- Network topology, the plane split (#469), or the server's open-mode fallback
+  for tests.
+
+## Design
+
+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. `mint`/`verify` are scoped to that domain's roles, so a token
+signed by one service's key neither carries nor verifies another service's role.
+
+- `CONTROL_PLANE` — the orchestrator's domain: key `orchestrator-token`, roles
+  `{gateway, cli}`. The orchestrator process holds the key; the gateway holds
+  only a minted `gateway` token; the host CLI mints its own `cli` token.
+- The host controller (#468) will add a second `TrustDomain` — its own key file
+  and role(s) — that the orchestrator never holds.
+
+**`ControlPlaneProvisioning`** is the seam the backends call.
+`orchestrator_key()` returns the raw key for the control-plane process
+(fail-closed for every backend: it raises rather than hand back an empty key that
+would run the server open). `gateway_token()` mints the gateway's token. Each backend applies these through its own transport —
+docker/macOS inject env vars, firecracker pushes over SSH — but none re-derives
+*which* key or role.
+
+`paths.host_signing_key(filename)` generalizes `host_orchestrator_token()` so each
+domain names its own key file.
+
+## Open questions
+
+None blocking. #468 adds its `TrustDomain` and a second
+`ControlPlaneProvisioning`-shaped consumer; renaming that class to something
+service-neutral is a cosmetic call to make then.

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

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

install.sh

@@ -94,13 +94,22 @@ fi
 
 # --- locate the entry point --------------------------------------------------
 
+# The pip --user scripts directory is platform-specific: ~/.local/bin on Linux,
+# but ~/Library/Python/<X.Y>/bin on a python.org macOS interpreter. Ask the
+# interpreter for its own user-scheme scripts dir instead of hardcoding.
+USER_SCRIPTS="$(python3 - <<'PY'
+import sysconfig
+print(sysconfig.get_path("scripts", sysconfig.get_preferred_scheme("user")))
+PY
+)"
+
 if command -v bot-bottle >/dev/null 2>&1; then
     BOT_BOTTLE_BIN="bot-bottle"
-elif [ -x "${HOME}/.local/bin/bot-bottle" ]; then
-    BOT_BOTTLE_BIN="${HOME}/.local/bin/bot-bottle"
-    say "note: add ${HOME}/.local/bin to your PATH to run 'bot-bottle' directly"
+elif [ -n "${USER_SCRIPTS}" ] && [ -x "${USER_SCRIPTS}/bot-bottle" ]; then
+    BOT_BOTTLE_BIN="${USER_SCRIPTS}/bot-bottle"
+    say "note: add ${USER_SCRIPTS} to your PATH to run 'bot-bottle' directly"
 else
-    die "bot-bottle was installed but is not on PATH; add ~/.local/bin to PATH and re-run"
+    die "bot-bottle was installed but is not on PATH; add ${USER_SCRIPTS:-your user scripts dir} to PATH and re-run"
 fi
 
 # --- verify ------------------------------------------------------------------

tests/integration/test_sandbox_escape.py

@@ -67,14 +67,25 @@ _DUMMY_HOST_KEY = (
 )
 
 
+# Backends whose CI runner is HOST-mode (self-hosted), so the test process
+# and the backend share a host. The containerized act_runner (docker on
+# ubuntu-latest) is the one that can't see the host bind mount egress_tls_init
+# uses and hides sibling-gateway network topology; host-mode runners
+# (firecracker/KVM, macos-container) don't have those constraints, so the test
+# runs there. Keep this in sync with the `runs-on` labels in
+# .gitea/workflows/test.yml.
+_HOST_MODE_CI_BACKENDS = frozenset({"firecracker", "macos-container"})
+
+
 @skip_unless_selected_backend_available()
 @unittest.skipIf(
     os.environ.get("GITEA_ACTIONS") == "true"
-    and os.environ.get("BOT_BOTTLE_BACKEND") != "firecracker",
-    "skipped under act_runner unless BOT_BOTTLE_BACKEND=firecracker: "
+    and os.environ.get("BOT_BOTTLE_BACKEND") not in _HOST_MODE_CI_BACKENDS,
+    "skipped under the containerized act_runner (docker on ubuntu-latest): "
     "egress_tls_init uses a host bind mount the runner container can't "
     "see, and the network topology hides sibling-gateway visibility — "
-    "these constraints don't apply on the self-hosted KVM runner",
+    "these constraints don't apply on the self-hosted host-mode runners "
+    "(firecracker/KVM, macos-container)",
 )
 class TestSandboxEscape(unittest.TestCase):
     """End-to-end attacks against a real bottle. The bottle stays

tests/unit/test_cli_doctor.py

@@ -2,8 +2,12 @@
 
 `doctor` is a store-free diagnostic — it must run on a fresh install
 before any DB migration, and its exit code gates only the two hard
-prerequisites (Python and an available backend). The config-dir check is
-advisory and never affects the exit code.
+prerequisites (Python and at least one *ready* backend). The config-dir
+check is advisory and never affects the exit code.
+
+Backend readiness is probed with `is_backend_ready()` (a full status()
+check), not the cheap PATH-only `is_backend_available()` — a host with a
+stopped daemon or half-configured backend must not report `ok`.
 """
 
 from __future__ import annotations
@@ -26,26 +30,43 @@ def _run(argv: list[str] | None = None) -> tuple[int, str]:
 
 
 class TestDoctor(unittest.TestCase):
-    def test_passes_when_python_and_backend_ok(self):
+    def test_passes_when_python_and_backend_ready(self):
         with patch.object(doctor, "known_backend_names", return_value=("docker",)), \
-                patch.object(doctor, "is_backend_available", return_value=True):
+                patch.object(doctor, "is_backend_ready", return_value=True):
             code, out = _run()
         self.assertEqual(0, code)
         self.assertIn("ok:   python", out)
-        self.assertIn("ok:   backend: available: docker", out)
+        self.assertIn("ok:   backend: docker: ready", out)
 
-    def test_fails_when_no_backend_available(self):
+    def test_fails_when_no_backend_ready(self):
+        # The regression the reviewer flagged: a backend whose binary is on PATH
+        # but whose daemon/pool isn't ready must NOT pass. is_backend_ready is
+        # the full status() check, so returning False here means "not ready".
         with patch.object(doctor, "known_backend_names", return_value=("docker", "firecracker")), \
-                patch.object(doctor, "is_backend_available", return_value=False):
+                patch.object(doctor, "is_backend_ready", return_value=False):
             code, out = _run()
         self.assertEqual(1, code)
         self.assertIn("fail: backend", out)
+        self.assertIn("warn: backend: docker: not ready", out)
+
+    def test_passes_when_at_least_one_backend_ready(self):
+        # docker not ready, firecracker ready → overall pass, mixed report.
+        def ready(name: str, *, quiet: bool = False) -> bool:
+            del quiet
+            return name == "firecracker"
+
+        with patch.object(doctor, "known_backend_names", return_value=("docker", "firecracker")), \
+                patch.object(doctor, "is_backend_ready", side_effect=ready):
+            code, out = _run()
+        self.assertEqual(0, code)
+        self.assertIn("warn: backend: docker: not ready", out)
+        self.assertIn("ok:   backend: firecracker: ready", out)
 
     def test_fails_when_python_too_old(self):
         # Force the version gate to fail without touching the interpreter.
         with patch.object(doctor, "MIN_PYTHON", (99, 0)), \
                 patch.object(doctor, "known_backend_names", return_value=("docker",)), \
-                patch.object(doctor, "is_backend_available", return_value=True):
+                patch.object(doctor, "is_backend_ready", return_value=True):
             code, out = _run()
         self.assertEqual(1, code)
         self.assertIn("fail: python", out)
@@ -57,7 +78,7 @@ class TestDoctor(unittest.TestCase):
         with tempfile.TemporaryDirectory() as tmp, \
                 patch.object(doctor.Path, "home", return_value=Path(tmp)), \
                 patch.object(doctor, "known_backend_names", return_value=("docker",)), \
-                patch.object(doctor, "is_backend_available", return_value=True):
+                patch.object(doctor, "is_backend_ready", return_value=True):
             code, out = _run()
         self.assertEqual(0, code)
         self.assertIn("warn: config", out)
@@ -66,7 +87,7 @@ class TestDoctor(unittest.TestCase):
         with tempfile.TemporaryDirectory() as tmp, \
                 patch.object(doctor.Path, "home", return_value=Path(tmp)), \
                 patch.object(doctor, "known_backend_names", return_value=("docker",)), \
-                patch.object(doctor, "is_backend_available", return_value=True):
+                patch.object(doctor, "is_backend_ready", return_value=True):
             (Path(tmp) / ".bot-bottle").mkdir()
             code, out = _run()
         self.assertEqual(0, code)

tests/unit/test_docker_orchestrator.py

@@ -19,7 +19,9 @@ _ORCH = "bot_bottle.backend.docker.orchestrator"
 _RUN = f"{_ORCH}.run_docker"
 _SLEEP = f"{_ORCH}.time.sleep"
 _MONOTONIC = f"{_ORCH}.time.monotonic"
-_TOKEN = f"{_ORCH}.host_orchestrator_token"
+# The signing key is read through the shared provisioning contract (#476); patch
+# its host-canonical key file read to keep it off the real host file.
+_TOKEN = "bot_bottle.trust_domain.host_signing_key"
 # The ABC's is_healthy probes /health via urllib in the lifecycle module.
 _URLOPEN = "bot_bottle.orchestrator.lifecycle.urllib.request.urlopen"
 

tests/unit/test_firecracker_orchestrator.py

@@ -44,7 +44,7 @@ class TestEnsureRunning(unittest.TestCase):
         vm = infra_vm.InfraVm(guest_ip="10.243.255.1", private_key=Path("/k"), vm=MagicMock())
         with patch.object(infra_vm, "boot_vm", return_value=vm) as boot, \
                 patch.object(infra_vm, "push_secret") as push, \
-                patch(f"{_ORCH}.host_orchestrator_token", return_value="host-key"), \
+                patch("bot_bottle.trust_domain.host_signing_key", return_value="host-key"), \
                 patch.object(orch, "is_running", return_value=False), \
                 patch.object(orch, "_ensure_registry_volume", return_value=Path("/reg")), \
                 patch.object(orch, "_wait_for_health"):

tests/unit/test_git_gate.py

@@ -181,6 +181,21 @@ class TestHookRender(unittest.TestCase):
         self.assertNotIn('log_opts="$new"', hook)
         self.assertNotIn('log_opts="$old..$new"', hook)
 
+    def test_agit_review_refs_are_rejected_before_scanning(self):
+        hook = git_gate_render_hook()
+        guard = "refs/for/*|refs/draft/*|refs/for-review/*"
+        self.assertIn(guard, hook)
+        self.assertIn(
+            "AGit review refs are disabled; push to refs/heads/<branch>",
+            hook,
+        )
+        self.assertLess(hook.index(guard), hook.index("# Phase 1: gitleaks"))
+        # Ref deletion must remain possible for cleanup.
+        self.assertLess(
+            hook.index('[ "$new" = "$zero" ] && continue'),
+            hook.index(guard),
+        )
+
     def test_forward_ssh_is_non_interactive_and_bounded(self):
         # No prompt (BatchMode) and a connect timeout, so an unreachable
         # upstream fails fast instead of hanging the receive-pack.

tests/unit/test_install_script.py

@@ -9,6 +9,7 @@ create the config tree, install the package, and verify with `doctor`.
 from __future__ import annotations
 
 import os
+import sysconfig
 import unittest
 from pathlib import Path
 
@@ -68,6 +69,33 @@ class TestInstallScript(unittest.TestCase):
         self.assertIn("EXTERNALLY-MANAGED", self.text)
         self.assertIn("pipx", self.text)
 
+    def test_resolves_user_scripts_dir_not_hardcoded(self):
+        # The pip --user scripts dir differs by platform; the script must ask
+        # the interpreter (sysconfig + the preferred *user* scheme) rather than
+        # hardcoding Linux's ~/.local/bin (which is wrong on macOS python.org).
+        self.assertIn("get_preferred_scheme", self.text)
+        self.assertIn("sysconfig", self.text)
+        # No hardcoded Linux path in executable lines (a comment may mention it).
+        code = "\n".join(
+            ln for ln in self.text.splitlines()
+            if ln.strip() and not ln.lstrip().startswith("#")
+        )
+        self.assertNotIn(".local/bin", code)
+
+    def test_macos_user_scheme_is_not_dot_local_bin(self):
+        # The case the fix exists for: a python.org macOS interpreter uses the
+        # osx_framework_user scheme, whose scripts land under
+        # ~/Library/Python/<X.Y>/bin — NOT ~/.local/bin. Drive the same
+        # sysconfig lookup install.sh uses, with a mac-like userbase, to prove
+        # it resolves a non-~/.local/bin directory.
+        self.assertIn("osx_framework_user", sysconfig.get_scheme_names())
+        scripts = sysconfig.get_path(
+            "scripts", "osx_framework_user",
+            vars={"userbase": "/Users/dev/Library/Python/3.11"},
+        )
+        self.assertEqual("/Users/dev/Library/Python/3.11/bin", scripts)
+        self.assertNotIn("/.local/bin", scripts)
+
 
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_macos_orchestrator.py

@@ -33,7 +33,7 @@ class TestMacosOrchestratorRun(unittest.TestCase):
     def _run(self) -> list[str]:
         run = Mock(return_value=_ok())
         with patch(f"{_ORCH}.container_mod") as mod, \
-                patch(f"{_ORCH}.host_orchestrator_token", return_value="k"):
+                patch("bot_bottle.trust_domain.host_signing_key", return_value="k"):
             mod.dns_server.return_value = "1.1.1.1"
             mod.bind_mount_spec.side_effect = _spec
             mod.run_container_argv = run
@@ -65,7 +65,7 @@ class TestMacosOrchestratorRun(unittest.TestCase):
 
     def test_start_failure_raises(self) -> None:
         with patch(f"{_ORCH}.container_mod") as mod, \
-                patch(f"{_ORCH}.host_orchestrator_token", return_value="k"):
+                patch("bot_bottle.trust_domain.host_signing_key", return_value="k"):
             mod.dns_server.return_value = "1.1.1.1"
             mod.run_container_argv = Mock(return_value=_fail())
             with self.assertRaises(OrchestratorStartError):

tests/unit/test_orchestrator_auth.py

@@ -82,5 +82,26 @@ class TestMintVerify(unittest.TestCase):
             mint(ROLE_GATEWAY, "")
 
 
+class TestCustomRoleSet(unittest.TestCase):
+    """The `roles=` seam a trust domain other than the control plane uses (#476):
+    mint/verify are scoped to the passed role set, not the module default."""
+
+    _ROLES = frozenset({"host"})
+
+    def test_round_trips_a_role_in_the_custom_set(self) -> None:
+        tok = mint("host", _KEY, roles=self._ROLES)
+        self.assertEqual("host", verify(tok, _KEY, roles=self._ROLES))
+
+    def test_mint_rejects_a_role_outside_the_custom_set(self) -> None:
+        with self.assertRaises(ValueError):
+            mint(ROLE_CLI, _KEY, roles=self._ROLES)
+
+    def test_verify_rejects_a_role_outside_the_verifiers_set(self) -> None:
+        # A validly signed token whose role isn't in the verifier's set fails —
+        # this is what keeps one domain's key from asserting another's role.
+        tok = mint(ROLE_CLI, _KEY)  # a control-plane `cli` token
+        self.assertIsNone(verify(tok, _KEY, roles=self._ROLES))
+
+
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_orchestrator_client.py

@@ -20,13 +20,15 @@ _URLOPEN = "bot_bottle.orchestrator.client.urllib.request.urlopen"
 
 class TestHostAuthToken(unittest.TestCase):
     def test_mints_a_cli_token_from_the_host_key(self) -> None:
-        with patch("bot_bottle.orchestrator.client.host_orchestrator_token",
+        # The CLI mints its `cli` token from the control-plane trust domain's
+        # host-canonical key (#476) — patch the key file read underneath it.
+        with patch("bot_bottle.trust_domain.host_signing_key",
                    return_value="signing-key"):
             tok = _host_auth_token()
         self.assertEqual(ROLE_CLI, verify(tok, "signing-key"))
 
     def test_returns_empty_when_key_unreadable(self) -> None:
-        with patch("bot_bottle.orchestrator.client.host_orchestrator_token",
+        with patch("bot_bottle.trust_domain.host_signing_key",
                    side_effect=OSError("no host root")):
             self.assertEqual("", _host_auth_token())
 

tests/unit/test_resources.py

@@ -109,6 +109,15 @@ class TestWheelMode(unittest.TestCase):
                 (root2 / "bot_bottle" / "cli" / "__init__.py").read_text(),
             )
 
+    def test_failed_stage_cleans_up_temp_dir(self):
+        # A failure mid-stage must not leave a half-written temp dir behind.
+        with self._wheel():
+            base = resources.bot_bottle_root() / "build-root"
+            with patch.object(resources.shutil, "copytree", side_effect=OSError("boom")):
+                with self.assertRaises(OSError):
+                    resources.build_root()
+            self.assertEqual([], list(base.glob(".staging-*")))
+
     def test_rebuilds_when_stage_incomplete(self):
         # A crash mid-stage can leave a dir without its `.complete` marker; the
         # next call must rebuild it rather than trust the partial tree.

tests/unit/test_supervise_server.py

@@ -728,7 +728,7 @@ class TestResolvedRoutesPayload(unittest.TestCase):
 
 
 class TestNonBlockingSupervise(unittest.TestCase):
-    """PRD prd-new / issue #412: pending responses carry the proposal id, and
+    """PRD 0072 / issue #412: pending responses carry the proposal id, and
     `check-proposal` polls a queued proposal without blocking or re-proposing."""
 
     _ROUTES = "routes:\n  - host: example.com\n"

tests/unit/test_trust_domain.py

@@ -0,0 +1,105 @@
+"""Unit: trust domains + the shared control-plane provisioning contract (#476)."""
+
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from bot_bottle import orchestrator_auth
+from bot_bottle.orchestrator_auth import ROLE_CLI, ROLE_GATEWAY
+from bot_bottle.trust_domain import (
+    CONTROL_PLANE,
+    ControlPlaneProvisioning,
+    ProvisioningError,
+    TrustDomain,
+)
+
+# A second, unrelated domain — the shape #468's host controller would take: its
+# own key file, its own role, its own env vars. Distinct from CONTROL_PLANE.
+_HOST_CTRL = TrustDomain(
+    name="host-controller",
+    key_filename="host-controller-token",
+    roles=frozenset({"host"}),
+    key_env="BOT_BOTTLE_HOST_CONTROLLER_TOKEN",
+    token_env="BOT_BOTTLE_HOST_CONTROLLER_JWT",
+)
+
+
+class TestTrustDomainMintVerify(unittest.TestCase):
+    def test_mint_verify_round_trips_within_a_domain(self) -> None:
+        with patch("bot_bottle.trust_domain.host_signing_key", return_value="k"):
+            tok = CONTROL_PLANE.mint(ROLE_GATEWAY)
+        self.assertEqual(ROLE_GATEWAY, CONTROL_PLANE.verify(tok, "k"))
+
+    def test_mint_rejects_a_role_outside_the_domain(self) -> None:
+        # `host` is a valid role in _HOST_CTRL but not in the control plane —
+        # the control-plane key must refuse to mint it.
+        with patch("bot_bottle.trust_domain.host_signing_key", return_value="k"):
+            with self.assertRaises(ValueError):
+                CONTROL_PLANE.mint("host")
+
+    def test_a_custom_role_set_verifies_its_own_role(self) -> None:
+        with patch("bot_bottle.trust_domain.host_signing_key", return_value="k"):
+            tok = _HOST_CTRL.mint("host")
+        self.assertEqual("host", _HOST_CTRL.verify(tok, "k"))
+
+    def test_key_from_env_reads_the_domains_env_var(self) -> None:
+        self.assertEqual(
+            "secret", CONTROL_PLANE.key_from_env({CONTROL_PLANE.key_env: " secret "}))
+        self.assertEqual("", CONTROL_PLANE.key_from_env({}))
+
+
+class TestDomainBoundary(unittest.TestCase):
+    """The #476/#468 invariant: two domains, two keys, two role sets — one
+    domain's key can neither mint nor verify the other's tokens."""
+
+    def test_a_control_plane_token_does_not_verify_under_another_domains_key(
+        self,
+    ) -> None:
+        # Even with an IDENTICAL underlying key, a `cli` token minted under the
+        # control-plane domain must not verify as a role in the host-controller
+        # domain — the role isn't in that domain's set.
+        cli_tok = orchestrator_auth.mint(ROLE_CLI, "shared-bytes")
+        self.assertIsNone(_HOST_CTRL.verify(cli_tok, "shared-bytes"))
+
+    def test_distinct_keys_do_not_cross_verify(self) -> None:
+        # The realistic case: distinct host-canonical keys per domain. A token
+        # signed by one key never verifies under the other.
+        host_tok = orchestrator_auth.mint(
+            "host", "host-ctrl-key", roles=_HOST_CTRL.roles)
+        self.assertIsNone(_HOST_CTRL.verify(host_tok, "control-plane-key"))
+        self.assertEqual("host", _HOST_CTRL.verify(host_tok, "host-ctrl-key"))
+
+
+class TestControlPlaneProvisioning(unittest.TestCase):
+    def test_orchestrator_key_returns_the_canonical_key(self) -> None:
+        prov = ControlPlaneProvisioning()
+        with patch("bot_bottle.trust_domain.host_signing_key", return_value="key"):
+            self.assertEqual("key", prov.orchestrator_key())
+
+    def test_orchestrator_key_fail_closes_when_empty(self) -> None:
+        # Invariant 4: the orchestrator must never start without a key — it would
+        # run OPEN and grant every caller that reaches it full `cli`. There is no
+        # topology opt-out: a separate host does not stop the gateway (or any
+        # other caller) from reaching the control-plane listener.
+        prov = ControlPlaneProvisioning()
+        with patch("bot_bottle.trust_domain.host_signing_key", return_value=""):
+            with self.assertRaises(ProvisioningError):
+                prov.orchestrator_key()
+
+    def test_gateway_token_is_a_verifiable_gateway_role_token(self) -> None:
+        prov = ControlPlaneProvisioning()
+        with patch("bot_bottle.trust_domain.host_signing_key", return_value="k"):
+            tok = prov.gateway_token()
+        self.assertEqual(ROLE_GATEWAY, CONTROL_PLANE.verify(tok, "k"))
+
+    def test_gateway_token_cannot_be_reused_as_cli(self) -> None:
+        # The data plane's token is `gateway`-scoped: it never carries `cli`.
+        prov = ControlPlaneProvisioning()
+        with patch("bot_bottle.trust_domain.host_signing_key", return_value="k"):
+            tok = prov.gateway_token()
+        self.assertNotEqual(ROLE_CLI, CONTROL_PLANE.verify(tok, "k"))
+
+
+if __name__ == "__main__":
+    unittest.main()