docs(prd): require shared storage permissions

docs(prd): bound heavy gateway operations
docs(prd): require cleanup execution integrity
2026-07-27 04:45:45 +00:00 · 2026-07-27 04:16:56 +00:00 · 2026-07-27 03:55:18 +00:00 · 2026-07-27 03:31:46 +00:00 · 2026-07-27 02:58:07 +00:00 · 2026-07-27 02:19:11 +00:00
33 changed files with 878 additions and 1277 deletions
@@ -71,21 +71,7 @@ When the agent exits, `cli.py` tears down every gateway and both networks; nothi

 ## Quickstart

-```sh
-curl -fsSL https://gitea.dideric.is/didericis/bot-bottle/raw/branch/main/install.sh | sh
-```
-
-The installer is a bootstrapper: it finds a suitable Python, installs bot-bottle with `pipx` (falling back to `pip --user`), creates `~/.bot-bottle`, and runs `bot-bottle doctor`. It is idempotent and never uses `sudo`. Python-native users can skip it entirely with `pipx install bot-bottle` or `uv tool install bot-bottle`.
-
-### Requirements
-
-**Python ≥ 3.11**, and this is the one that trips people up on macOS: the `python3` Apple ships at `/usr/bin/python3` is **3.9.6**, which is too old. Bare `python3` resolves to that stub far more often than people expect. `path_helper` builds a login shell's `PATH` from `/etc/paths` and then appends `/etc/paths.d/*`, and `/usr/bin` sits in the former — so even when `/opt/homebrew/bin` *is* on the `PATH` (via `/etc/paths.d/homebrew`), it comes after `/usr/bin` and loses. Prepending a newer Python is something your shell profile does, and a fresh account, a launchd job, or a CI runner has no such profile. So the installer looks past bare `python3` before giving up: it tries `python3`, then the versioned `python3.11`–`python3.14` names, then `/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin`, and python.org framework builds — and tells you which one it picked when it isn't the obvious one. Point it somewhere specific with `BOT_BOTTLE_PYTHON=/path/to/python3`.
-
-**No `pipx` required.** If `pipx` is present the installer uses it and stays out of the way. If it isn't, bot-bottle installs into a private venv at `~/.bot-bottle/venv` (override with `BOT_BOTTLE_VENV`) and symlinks the entry point into `~/.local/bin`. There is deliberately no `pip install --user` path: Homebrew, python.org and Debian/Ubuntu interpreters are all externally managed (PEP 668), which blocks `--user` outright — so on a Mac it is never the fallback it appears to be. A venv is exempt from PEP 668, and `venv` is stdlib, so unlike `pipx` there is nothing to bootstrap first.
-
-**`git`**, because the default install spec is a `git+` URL. Set `BOT_BOTTLE_INSTALL_SPEC` to a wheel path or index name to avoid it.
-
-**A backend**, which the installer deliberately does *not* install for you — `doctor` reports what's missing afterwards. On compatible macOS hosts, the default backend requires Apple's `container` CLI and does not require Docker. The Firecracker backend (Linux) requires Docker on the host for the gateway plus the `firecracker` binary and KVM. The legacy Docker backend requires Docker. Claude bottles also need a long-lived Claude Code OAuth token (`claude setup-token`) exported as `BOT_BOTTLE_CLAUDE_OAUTH_TOKEN`.
+On compatible macOS hosts, the default backend requires Apple's `container` CLI and does not require Docker. The Firecracker backend (Linux) requires Docker on the host for the gateway plus the `firecracker` binary and KVM. The legacy Docker backend requires Docker. Claude bottles also need a long-lived Claude Code OAuth token (`claude setup-token`) exported as `BOT_BOTTLE_CLAUDE_OAUTH_TOKEN`.

 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.

@@ -30,6 +30,7 @@ if TYPE_CHECKING:
        BottleImages,
        BottlePlan,
        BottleSpec,
+        EnumerationError,
        ExecResult,
    )
    from .selection import (
@@ -59,6 +60,7 @@ _LAZY_MODULES: dict[str, str] = {
    "BottleImages": "base",
    "BottleBackend": "base",
    "BackendStatus": "base",
+    "EnumerationError": "base",
    "get_bottle_backend": "selection",
    "known_backend_names": "selection",
    "has_backend": "selection",
@@ -100,6 +102,7 @@ __all__ = [
    "BottlePlan",
    "BottleSpec",
    "ExecResult",
+    "EnumerationError",
    "CommitCancelled",
    "Freezer",
    "get_freezer",
@@ -42,6 +42,10 @@ class BackendStatus(enum.IntEnum):
    READY = 0


+class EnumerationError(RuntimeError):
+    """A backend could not produce an authoritative live-resource snapshot."""
+
+
@dataclass(frozen=True)
 class BottleSpec:
    """CLI-supplied intent. Backend-agnostic — each backend's prepare
@@ -16,6 +16,7 @@ from pathlib import Path
 from typing import Any

 from ...log import die, warn
+from ..base import EnumerationError


 # --- Lifecycle helpers (PRD 0018 chunk 3) ----------------------------------
@@ -52,19 +53,20 @@ def slug_from_compose_project(project: str) -> str:


 def list_compose_projects(
-    *, include_stopped: bool = True, warn_on_error: bool = True,
+    *,
+    include_stopped: bool = True,
+    warn_on_error: bool = True,
+    raise_on_error: bool = False,
 ) -> list[str]:
    """All compose project names starting with `bot-bottle-`.
    `include_stopped=True` (default) runs `docker compose ls --all`
    so exited projects appear too; pass False to get only projects
    with at least one running container.

-    Returns [] on docker daemon errors or malformed output rather
-    than raising — callers should treat the empty list as "no
-    projects discoverable", not "no projects exist". `warn_on_error`
-    stays true for explicit operator commands like cleanup, but active
-    discovery paths set it false so dashboard refreshes don't spam
-    stderr while Docker Desktop is stopped."""
+    Best-effort callers get ``[]`` on Docker errors or malformed output.
+    Enumeration callers pass ``raise_on_error=True`` so a failed query is not
+    reported as an authoritative empty result.
+    """
    argv = ["docker", "compose", "ls", "--format", "json"]
    if include_stopped:
        argv.insert(3, "--all")
@@ -72,20 +74,27 @@ def list_compose_projects(
        result = subprocess.run(
            argv, capture_output=True, text=True, check=False,
        )
-    except OSError:
-        # docker unavailable — not on PATH, or on it but not executable by
-        # this user. Same shape as a daemon-down error from the caller's
-        # POV: no projects discoverable.
+    except FileNotFoundError as exc:
+        if raise_on_error:
+            raise EnumerationError(
+                "docker compose ls failed: docker not found"
+            ) from exc
        return []
    if result.returncode != 0:
+        message = f"docker compose ls failed: {result.stderr.strip()}"
+        if raise_on_error:
+            raise EnumerationError(message)
        if warn_on_error:
-            warn(f"docker compose ls failed: {result.stderr.strip()}")
+            warn(message)
        return []
    try:
        projects = json.loads(result.stdout or "[]")
    except json.JSONDecodeError as e:
+        message = f"docker compose ls returned malformed JSON: {e}"
+        if raise_on_error:
+            raise EnumerationError(message) from e
        if warn_on_error:
-            warn(f"docker compose ls returned malformed JSON: {e}")
+            warn(message)
        return []
    names: list[str] = []
    for p in projects:
@@ -98,7 +107,10 @@ def list_compose_projects(


 def list_active_slugs(
-    *, include_stopped: bool = False, warn_on_error: bool = True,
+    *,
+    include_stopped: bool = False,
+    warn_on_error: bool = True,
+    raise_on_error: bool = False,
 ) -> list[str]:
    """Slugs (project name minus prefix) of currently-running
    bottles. Used by the dashboard's operator-edit verbs to choose
@@ -109,6 +121,7 @@ def list_active_slugs(
            for p in list_compose_projects(
                include_stopped=include_stopped,
                warn_on_error=warn_on_error,
+                raise_on_error=raise_on_error,
            )
        ) if slug
    )
@@ -68,6 +68,11 @@ def _network_container_ips(network: str) -> list[str]:
        "docker", "network", "inspect", "--format",
        "{{range .Containers}}{{.IPv4Address}} {{end}}", network,
    ])
+    if proc.returncode != 0:
+        detail = proc.stderr.strip() or f"exit {proc.returncode}"
+        raise ConsolidatedLaunchError(
+            f"could not inspect addresses on gateway network {network}: {detail}"
+        )
    ips: list[str] = []
    for entry in proc.stdout.split():
        ips.append(entry.split("/", 1)[0])
@@ -1,9 +1,8 @@
 """Active-agent enumeration for the docker backend.

 Returns `ActiveAgent` records the CLI `active` command and the
-dashboard agents pane consume. Empty when docker isn't reachable
-— gated by `has_backend('docker')` at the cross-backend caller
-so this module trusts that docker is available when called.
+dashboard agents pane consume. Docker query failures raise rather
+than masquerading as an authoritative empty result.

 The parser (`_parse_services_by_project`) is exposed for direct
 unit testing; the docker `docker ps` invocation is in
@@ -13,17 +12,18 @@ from __future__ import annotations

 import subprocess

-from .. import ActiveAgent
+from .. import ActiveAgent, EnumerationError
 from ...bottle_state import read_metadata
 from .compose import compose_project_name, list_active_slugs


 def enumerate_active() -> list[ActiveAgent]:
-    """All currently-running docker-backed agents. Caller is
-    responsible for gating on `has_backend('docker')` if it
-    matters; if docker is missing the `docker ps` call below
-    returns an empty list silently."""
-    slugs = list_active_slugs(include_stopped=False, warn_on_error=False)
+    """All currently-running docker-backed agents."""
+    slugs = list_active_slugs(
+        include_stopped=False,
+        warn_on_error=False,
+        raise_on_error=True,
+    )
    if not slugs:
        return []
    services_by_project = _query_services_by_project()
@@ -74,9 +74,8 @@ def _query_services_by_project() -> dict[str, set[str]]:
            ],
            capture_output=True, text=True, check=False,
        )
-    except OSError:
-        # docker missing, or on PATH but not executable by this user.
-        return {}
+    except FileNotFoundError as exc:
+        raise EnumerationError("docker ps failed: docker not found") from exc
    if r.returncode != 0:
-        return {}
+        raise EnumerationError(f"docker ps failed: {r.stderr.strip()}")
    return _parse_services_by_project(r.stdout or "")
@@ -29,6 +29,7 @@ import subprocess
 from pathlib import Path

 from ...log import info
+from .. import EnumerationError
 from . import util
 from .bottle_cleanup_plan import FirecrackerBottleCleanupPlan

@@ -62,12 +63,23 @@ def _scan_processes(run_root: Path) -> tuple[set[str], list[int]]:
      * ``orphan_pids`` — firecracker pids whose run dir no longer exists
        (a lingering VMM to kill).
    """
-    result = subprocess.run(
-        ["pgrep", "-a", "firecracker"],
-        capture_output=True, text=True, check=False,
-    )
-    if result.returncode != 0:
+    try:
+        result = subprocess.run(
+            ["pgrep", "-a", "firecracker"],
+            capture_output=True, text=True, check=False,
+        )
+    except OSError as exc:
+        raise EnumerationError(
+            f"could not enumerate Firecracker processes: {exc}"
+        ) from exc
+    if result.returncode == 1:
+        # pgrep's documented "no processes matched" result.
        return set(), []
+    if result.returncode != 0:
+        detail = (result.stderr or "").strip() or f"exit {result.returncode}"
+        raise EnumerationError(
+            f"could not enumerate Firecracker processes: {detail}"
+        )
    live: set[str] = set()
    orphan_pids: list[int] = []
    for line in result.stdout.splitlines():
@@ -1,14 +1,32 @@
 """Active-agent enumeration for the Firecracker backend.

-The backend is disabled during the companion-container removal (#385) — it can't
-launch bottles, so there are none to enumerate. Real enumeration returns
-with the backend's consolidated relaunch (#354).
+Running bottles are the Firecracker processes whose ``--config-file`` points
+at an existing per-bottle run directory. The same authoritative process scan
+protects cleanup from deleting live VMs; operational scan failures propagate
+as ``EnumerationError`` instead of masquerading as an empty host.
 """

 from __future__ import annotations

+from ...bottle_state import read_metadata
 from .. import ActiveAgent
+from .cleanup import live_run_dirs


 def enumerate_active() -> list[ActiveAgent]:
-    return []
+    out: list[ActiveAgent] = []
+    for run_dir in live_run_dirs():
+        slug = run_dir.name
+        metadata = read_metadata(slug)
+        out.append(ActiveAgent(
+            backend_name="firecracker",
+            slug=slug,
+            agent_name=metadata.agent_name if metadata else "?",
+            started_at=metadata.started_at if metadata else "",
+            # Firecracker uses the shared gateway, so there are no
+            # per-bottle gateway service containers to report.
+            services=(),
+            label=metadata.label if metadata else "",
+            color=metadata.color if metadata else "",
+        ))
+    return out
@@ -177,20 +177,14 @@ def gw_slot() -> Slot:
 # --- fail-closed verification ---------------------------------------

 def _run_ok(argv: list[str]) -> bool:
-    """Run a probe command, treating an unavailable binary as failure
+    """Run a probe command, treating a missing binary as failure
    (rather than crashing) so callers can stay fail-closed."""
    try:
        return subprocess.run(
            argv, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
            check=False,
        ).returncode == 0
-    except OSError:
-        # Not only "missing". A name on PATH that isn't executable by this
-        # user raises PermissionError, and CPython reports that EACCES in
-        # preference to the ENOENT from the other PATH entries — which is
-        # how `doctor` came to die with a traceback on a fresh macOS
-        # account. Any OSError means the probe couldn't run, which for a
-        # fail-closed check is indistinguishable from "not present".
+    except FileNotFoundError:
        return False


@@ -250,9 +244,7 @@ def overlapping_routes() -> list[RouteConflict]:
            ["ip", "-json", "route", "show", "table", "all"],
            capture_output=True, text=True, check=False,
        )
-    except OSError:
-        # Missing, or present-but-not-executable for this user; either way
-        # there are no routes we can enumerate. See _run_ok.
+    except FileNotFoundError:
        return []
    if proc.returncode != 0 or not proc.stdout.strip():
        return []
@@ -5,7 +5,7 @@ from __future__ import annotations
 import subprocess

 from ...bottle_state import read_metadata
-from .. import ActiveAgent
+from .. import ActiveAgent, EnumerationError
 from .infra import INFRA_NAME, ORCHESTRATOR_NAME

 # The name every agent container carries: `bot-bottle-<slug>`. Exported
@@ -20,17 +20,18 @@ CONTAINER_NAME_PREFIX = "bot-bottle-"
 _INFRA_NAMES = frozenset({INFRA_NAME, ORCHESTRATOR_NAME})


-class EnumerationError(RuntimeError):
-    """container list failed; the resulting live set is not authoritative."""
-
-
 def enumerate_active() -> list[ActiveAgent]:
-    result = subprocess.run(
-        ["container", "list", "--quiet"],
-        capture_output=True,
-        text=True,
-        check=False,
-    )
+    try:
+        result = subprocess.run(
+            ["container", "list", "--quiet"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise EnumerationError(
+            "container list failed: container CLI not found"
+        ) from exc
    if result.returncode != 0:
        raise EnumerationError(
            f"container list failed: "
@@ -389,19 +389,9 @@ class EgressAddon:
        self._passthrough_conns.discard(conn_id)

    async def request(self, flow: http.HTTPFlow) -> None:
+        config, slug, env = self._request_context(flow)
        request_path, _, query = flow.request.path.partition("?")

-        # Reuse the context stashed by http_connect for HTTPS flows (one
-        # orchestrator round-trip per connection). Plain-HTTP flows have no
-        # prior CONNECT stash, so resolve now and stash for response/websocket.
-        meta = getattr(flow, "metadata", None)
-        if isinstance(meta, dict) and _FLOW_CTX_KEY in meta:
-            config, slug, env = meta[_FLOW_CTX_KEY]
-            self._request_token(flow)  # strip identity headers; token already resolved
-        else:
-            config, slug, env = self._resolve_flow(flow)
-            self._stash_flow_ctx(flow, config, slug, env)
-
        # Introspection ("_egress.local/allowlist") reports the calling bottle's
        # own resolved routes — served after resolution so it reflects this
        # bottle's policy, not a stale global.
@@ -422,6 +412,29 @@ class EgressAddon:
            # the path/query the git checks below rely on.
            request_path, _, query = flow.request.path.partition("?")

+        if not self._allow_git_request(flow, config, request_path, query):
+            return
+
+        self._apply_route_policy(flow, config, route, request_path, env)
+
+    def _request_context(
+        self, flow: http.HTTPFlow,
+    ) -> tuple[Config, str, "typing.Mapping[str, str]"]:
+        """Resolve one bottle context, reusing the HTTPS CONNECT snapshot."""
+        meta = getattr(flow, "metadata", None)
+        if isinstance(meta, dict) and _FLOW_CTX_KEY in meta:
+            config, slug, env = meta[_FLOW_CTX_KEY]
+            self._request_token(flow)
+            return config, slug, env
+        config, slug, env = self._resolve_flow(flow)
+        self._stash_flow_ctx(flow, config, slug, env)
+        return config, slug, env
+
+    def _allow_git_request(
+        self, flow: http.HTTPFlow, config: Config,
+        request_path: str, query: str,
+    ) -> bool:
+        """Apply the HTTPS Git push/fetch boundary before general routing."""
        if is_git_push_request(request_path, query):
            self._block(
                flow,
@@ -430,20 +443,20 @@ class EgressAddon:
                "git-gate's pre-receive hook).",
                ctx=self._req_ctx(flow),
            )
-            return
-
-        if is_git_fetch_request(request_path, query):
-            git_decision = decide_git_fetch(
-                config.routes, flow.request.pretty_host,
-            )
-            if git_decision.action == "block":
-                self._block(
-                    flow,
-                    git_decision.reason,
-                    ctx=self._req_ctx(flow),
-                )
-                return
+            return False
+        if not is_git_fetch_request(request_path, query):
+            return True
+        git_decision = decide_git_fetch(config.routes, flow.request.pretty_host)
+        if git_decision.action != "block":
+            return True
+        self._block(flow, git_decision.reason, ctx=self._req_ctx(flow))
+        return False

+    def _apply_route_policy(
+        self, flow: http.HTTPFlow, config: Config, route: Route | None,
+        request_path: str, env: "typing.Mapping[str, str]",
+    ) -> None:
+        """Strip agent auth, evaluate the route, then inject gateway auth."""
        # Strip agent-set Authorization after DLP scan so smuggled tokens
        # are caught above; the route may inject gateway-owned auth below.
        # Routes with preserve_auth=True pass the header through as-is so the
@@ -1,6 +1,7 @@
 """Run the orchestrator control plane as a plain process (PRD 0070 dev-harness).

-    python -m bot_bottle.orchestrator [--host H] [--port P] [--db PATH]
+    BOT_BOTTLE_ORCHESTRATOR_TOKEN=<signing-key> \
+        python -m bot_bottle.orchestrator [--host H] [--port P] [--db PATH]

 The PRD sequences the orchestrator as a plain-process dev-harness first, so
 the consolidation core (registry + attribution + HTTP control plane + live
@@ -16,12 +17,13 @@ import secrets
 from pathlib import Path

 from .. import log
-from .store.store_manager import StoreManager
+from ..trust_domain import CONTROL_PLANE
 from .broker import LaunchBroker, StubBroker
-from .server import make_server
 from .docker_broker import DockerBroker
-from .store.registry_store import RegistryStore, default_db_path
+from .server import make_server
 from .service import OrchestratorCore
+from .store.store_manager import StoreManager
+from .store.registry_store import RegistryStore, default_db_path


 def main(argv: list[str] | None = None) -> int:
@@ -38,6 +40,11 @@ def main(argv: list[str] | None = None) -> int:
        help="launch broker: 'stub' records requests; 'docker' runs containers",
    )
    args = parser.parse_args(argv)
+    if not CONTROL_PLANE.key_from_env():
+        log.die(
+            f"{CONTROL_PLANE.key_env} is required; refusing to start the "
+            "orchestrator without caller authentication"
+        )

    registry = RegistryStore(args.db)
    registry.migrate()
@@ -59,8 +59,10 @@ import http.server
 import json
 import math
 import os
+import socket
 import socketserver
 import sys
+import threading
 import typing
 from urllib.parse import urlsplit

@@ -80,6 +82,9 @@ Json = dict[str, object]
 # token at all, and a compromised gateway holds only `gateway` — neither can
 # drive the operator routes (approve proposals, rewrite policy, read tokens).
 ORCHESTRATOR_AUTH_HEADER = "x-bot-bottle-orchestrator-auth"
+MAX_BODY_BYTES = 1 * 1024 * 1024
+REQUEST_TIMEOUT_SECONDS = 10.0
+MAX_REQUEST_THREADS = 32

 # The routes the data plane (role `gateway`) is allowed to reach — exactly the
 # per-request lookups PolicyResolver makes. Every other authenticated route is
@@ -116,9 +121,8 @@ def dispatch(  # pylint: disable=too-many-return-statements,too-many-branches
    no I/O beyond the orchestrator — so it is fully testable without a socket.

    `role` is the caller's verified control-plane role (`gateway` or `cli`), or
-    None for an unauthenticated request; an open-mode server (no signing key
-    configured — see `OrchestratorServer`) passes `cli`. Every route except
-    `GET /health` requires a role: a missing role is 401, and a role that
+    None for an unauthenticated request. Every route except `GET /health`
+    requires a role: a missing role is 401, and a role that
    doesn't cover the route is 403 — so a `gateway` data-plane token can reach
    `/resolve` + `/supervise/{propose,poll}` but not the operator routes
    (rewrite policy, read injected tokens, approve its own supervise proposals).
@@ -372,10 +376,33 @@ class Handler(http.server.BaseHTTPRequestHandler):
        plane down for the caller."""
        server = self.server
        assert isinstance(server, OrchestratorServer)
-        length = int(self.headers.get("Content-Length") or 0)
-        body = self.rfile.read(length) if length > 0 else b""
        role = server.role_for(self.headers.get(ORCHESTRATOR_AUTH_HEADER, ""))
+        route = urlsplit(self.path).path.rstrip("/") or "/"
+        if not (method == "GET" and route == "/health") and role is None:
+            self._write_json(
+                401, {"error": "control-plane authentication required"},
+            )
+            return
+        length_header = self.headers.get("Content-Length")
        try:
+            length = int(length_header) if length_header is not None else 0
+        except ValueError:
+            self._write_json(400, {"error": "invalid Content-Length"})
+            return
+        if length < 0:
+            self._write_json(400, {"error": "invalid Content-Length"})
+            return
+        if length > MAX_BODY_BYTES:
+            self._write_json(413, {"error": "request body too large"})
+            return
+        try:
+            body = self.rfile.read(length) if length else b""
+        except (TimeoutError, socket.timeout):
+            self._write_json(408, {"error": "request body read timed out"})
+            return
+        try:
+            status: int
+            payload: Json
            status, payload = dispatch(
                server.orchestrator, method, self.path, body, role=role)
        except Exception as e:  # noqa: BLE001 — the control plane must stay up
@@ -388,6 +415,9 @@ class Handler(http.server.BaseHTTPRequestHandler):
            )
            sys.stderr.flush()
            status, payload = 500, {"error": "internal error"}
+        self._write_json(status, payload)
+
+    def _write_json(self, status: int, payload: Json) -> None:
        data = json.dumps(payload).encode()
        self.send_response(status)
        self.send_header("Content-Type", "application/json")
@@ -414,51 +444,80 @@ class OrchestratorServer(socketserver.ThreadingMixIn, http.server.HTTPServer):
    Holds the per-host control-plane *signing key* (from
    `$BOT_BOTTLE_ORCHESTRATOR_TOKEN`, injected by the launcher into the
    orchestrator process only) and verifies each request's role-scoped token
-    against it. When a key is set, every route but `/health` requires a valid
-    token whose role covers the route; when it is unset the server runs **open**
-    (full `cli` access) and says so loudly at startup — a fail-visible fallback
-    for tests and any backend that hasn't wired the key yet (e.g. Firecracker,
-    whose nft boundary already blocks agents from the control-plane port)."""
+    against it. Every route but `/health` requires a valid token whose role
+    covers the route. Construction fails when the key is absent so a new or
+    misconfigured launcher cannot accidentally expose an open control plane."""

    daemon_threads = True
    allow_reuse_address = True

-    def __init__(self, address: tuple[str, int], orchestrator: OrchestratorCore) -> None:
+    def __init__(
+        self,
+        address: tuple[str, int],
+        orchestrator: OrchestratorCore,
+        *,
+        signing_key: str,
+    ) -> None:
        self.orchestrator = orchestrator
-        # 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()
+        self._signing_key = signing_key.strip()
        if not self._signing_key:
-            sys.stderr.write(
-                "orchestrator: WARNING — no control-plane signing key "
-                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"
+            raise ValueError(
+                "orchestrator control-plane signing key is required; "
+                "refusing to start without caller authentication"
            )
-            sys.stderr.flush()
+        self._request_slots = threading.BoundedSemaphore(MAX_REQUEST_THREADS)
        super().__init__(address, Handler)

+    def get_request(self) -> tuple[socket.socket, typing.Any]:
+        request, client_address = super().get_request()
+        request.settimeout(REQUEST_TIMEOUT_SECONDS)
+        return request, client_address
+
+    def process_request(
+        self, request: typing.Any, client_address: typing.Any,
+    ) -> None:
+        # Bound concurrency before ThreadingMixIn creates a worker. Backpressure
+        # stays in the accept loop instead of allocating an unbounded thread per
+        # slow or malicious connection.
+        self._request_slots.acquire()
+        try:
+            super().process_request(request, client_address)
+        except BaseException:
+            self._request_slots.release()
+            raise
+
+    def process_request_thread(
+        self, request: typing.Any, client_address: typing.Any,
+    ) -> None:
+        try:
+            super().process_request_thread(request, client_address)
+        finally:
+            self._request_slots.release()
+
    def role_for(self, presented: str) -> str | None:
-        """The role the request is authorized as, or None if unauthenticated.
-        Open mode (no signing key) grants full `cli` access — the fail-visible
-        fallback. Otherwise verify the presented signed token; a missing/invalid
-        token yields None (→ 401), a valid one yields its `gateway`/`cli`
-        role (→ per-route 401/403 in `dispatch`)."""
-        if not self._signing_key:
-            return ROLE_CLI
+        """The verified caller role, or None for a missing/invalid token."""
        return CONTROL_PLANE.verify(presented, self._signing_key)


 def make_server(
-    orchestrator: OrchestratorCore, host: str = "127.0.0.1", port: int = 0
+    orchestrator: OrchestratorCore,
+    host: str = "127.0.0.1",
+    port: int = 0,
+    *,
+    signing_key: str | None = None,
 ) -> OrchestratorServer:
-    """Build (but do not start) a control-plane server. `port=0` binds an
-    ephemeral port — read `server.server_address` for the actual one."""
-    return OrchestratorServer((host, port), orchestrator)
+    """Build an authenticated control-plane server.
+
+    ``signing_key=None`` reads the owning process's injected environment.
+    Empty or missing keys are rejected by :class:`OrchestratorServer`.
+    """
+    key = CONTROL_PLANE.key_from_env() if signing_key is None else signing_key
+    return OrchestratorServer(
+        (host, port), orchestrator, signing_key=key,
+    )


 __all__ = [
    "dispatch", "Handler", "OrchestratorServer", "make_server", "Json",
-    "ORCHESTRATOR_AUTH_HEADER",
+    "ORCHESTRATOR_AUTH_HEADER", "MAX_BODY_BYTES",
 ]
@@ -366,15 +366,23 @@ class OrchestratorCore:
        value with *env_var_secret*, and restores ``_tokens[bottle_id]``.
        Returns True on success, False when no stored secrets exist for this
        bottle or decryption fails (wrong key / corrupt data)."""
-        from .store.secret_store import decrypt_value
+        from .store.secret_store import decrypt_value, encrypt_value, is_legacy_blob
        encrypted = self.registry.get_agent_secrets(bottle_id)
        if not encrypted:
            return False
        try:
-            self._tokens[bottle_id] = {k: decrypt_value(env_var_secret, v)
-                                       for k, v in encrypted.items()}
+            decrypted = {
+                k: decrypt_value(env_var_secret, v) for k, v in encrypted.items()
+            }
        except ValueError:
            return False
+        self._tokens[bottle_id] = decrypted
+        if any(is_legacy_blob(value) for value in encrypted.values()):
+            migrated = {
+                key: encrypt_value(env_var_secret, value)
+                for key, value in decrypted.items()
+            }
+            self.registry.store_agent_secrets(bottle_id, migrated)
        return True

    # --- consolidated gateway ----------------------------------------------
@@ -12,9 +12,15 @@ reattachment path reads ENV_VAR_SECRET from the running agent container via
 ``POST /bottles/<id>/reprovision_gateway``; the orchestrator decrypts the
 stored rows and re-populates ``_tokens``.

-Encryption scheme: HMAC-SHA256 used as a PRF in CTR mode (stdlib-only,
-no external deps). Each value is encrypted independently. The output blob is
-``nonce (16 bytes) || ciphertext`` encoded as URL-safe base64 (no padding).
+Encryption scheme: encrypt-then-MAC using independent HMAC-SHA256-derived
+encryption and authentication subkeys (stdlib-only, no external deps). Each
+value is encrypted independently. New output blobs are:
+
+``version || nonce (16 bytes) || ciphertext || tag (32 bytes)``
+
+encoded as URL-safe base64 (no padding). The version marker lets the reader
+accept legacy ``nonce || ciphertext`` rows long enough to rewrite them in the
+authenticated format after a successful reprovision.

    keystream_block_i = HMAC-SHA256(key, nonce || i.to_bytes(4, "big"))
    ciphertext_i      = plaintext_i XOR keystream_block_i[:len(plaintext_i)]
@@ -30,6 +36,8 @@ import secrets
 _KEY_BYTES = 32    # 256-bit key from ENV_VAR_SECRET
 _NONCE_BYTES = 16  # 128-bit random nonce per encrypt call
 _BLOCK = 32        # HMAC-SHA256 output width == one keystream block
+_TAG_BYTES = 32
+_VERSION = b"BBSE1"

 # Env-var name the agent container receives at startup.
 ENV_VAR_SECRET_NAME = "ENV_VAR_SECRET"
@@ -41,7 +49,13 @@ def new_env_var_secret() -> str:


 def _b64dec(s: str) -> bytes:
-    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+    return base64.b64decode(
+        s + "=" * (-len(s) % 4), altchars=b"-_", validate=True,
+    )
+
+
+def _subkey(key: bytes, purpose: bytes) -> bytes:
+    return hmac.new(key, b"bot-bottle-secret-store:" + purpose, hashlib.sha256).digest()


 def _keystream(key: bytes, nonce: bytes, block_index: int) -> bytes:
@@ -53,42 +67,90 @@ def _keystream(key: bytes, nonce: bytes, block_index: int) -> bytes:
 def encrypt_value(secret_b64: str, plaintext: str) -> str:
    """Encrypt a single string value with *secret_b64* (the ENV_VAR_SECRET).

-    Returns a URL-safe base64 blob ``nonce || ciphertext`` suitable for
+    Returns a URL-safe base64 authenticated blob suitable for
    the ``bottled_agent_secrets.value`` column."""
    key = _b64dec(secret_b64)
+    encryption_key = _subkey(key, b"encryption")
+    authentication_key = _subkey(key, b"authentication")
    pt = plaintext.encode()
    nonce = secrets.token_bytes(_NONCE_BYTES)
    ct = bytearray()
    for i in range(0, len(pt), _BLOCK):
        chunk = pt[i : i + _BLOCK]
-        ks = _keystream(key, nonce, i)[: len(chunk)]
+        ks = _keystream(encryption_key, nonce, i // _BLOCK)[: len(chunk)]
        ct.extend(p ^ k for p, k in zip(chunk, ks))
-    return base64.urlsafe_b64encode(nonce + bytes(ct)).rstrip(b"=").decode()
+    authenticated = _VERSION + nonce + bytes(ct)
+    tag = hmac.new(authentication_key, authenticated, hashlib.sha256).digest()
+    return base64.urlsafe_b64encode(authenticated + tag).rstrip(b"=").decode()


-def decrypt_value(secret_b64: str, blob_b64: str) -> str:
-    """Decrypt a blob produced by :func:`encrypt_value`.
-
-    Returns the original plaintext string. Raises ``ValueError`` for malformed
-    input or a key mismatch (wrong key produces garbage, not an error, unless
-    the plaintext is non-UTF-8 — treat all such failures as wrong key)."""
-    key = _b64dec(secret_b64)
+def is_legacy_blob(blob_b64: str) -> bool:
+    """Whether *blob_b64* uses the pre-authentication storage format."""
    try:
-        blob = _b64dec(blob_b64)
-    except Exception as exc:
-        raise ValueError(f"invalid ciphertext blob: {exc}") from exc
+        return not _b64dec(blob_b64).startswith(_VERSION)
+    except (ValueError, TypeError):
+        return False
+
+
+def _decrypt_legacy(key: bytes, blob: bytes) -> str:
+    """Read the original ``nonce || ciphertext`` format for migration only."""
    if len(blob) < _NONCE_BYTES:
        raise ValueError("ciphertext blob too short")
    nonce, ciphertext = blob[:_NONCE_BYTES], blob[_NONCE_BYTES:]
    pt = bytearray()
+    # The legacy format used the byte offset as the PRF counter.
    for i in range(0, len(ciphertext), _BLOCK):
        chunk = ciphertext[i : i + _BLOCK]
        ks = _keystream(key, nonce, i)[: len(chunk)]
        pt.extend(c ^ k for c, k in zip(chunk, ks))
    try:
        return bytes(pt).decode()
+    except UnicodeDecodeError as exc:
+        raise ValueError(f"decryption produced non-UTF-8 output: {exc}") from exc
+
+
+def decrypt_value(secret_b64: str, blob_b64: str) -> str:
+    """Decrypt a blob produced by :func:`encrypt_value`.
+
+    Returns the original plaintext string. Raises ``ValueError`` for malformed
+    input, authentication failure, or a key mismatch. Legacy unauthenticated
+    rows remain readable so callers can migrate them immediately."""
+    key = _b64dec(secret_b64)
+    try:
+        blob = _b64dec(blob_b64)
+    except (ValueError, TypeError) as exc:
+        raise ValueError(f"invalid ciphertext blob: {exc}") from exc
+    if not blob.startswith(_VERSION):
+        return _decrypt_legacy(key, blob)
+    minimum = len(_VERSION) + _NONCE_BYTES + _TAG_BYTES
+    if len(blob) < minimum:
+        raise ValueError("ciphertext blob too short")
+    authenticated, supplied_tag = blob[:-_TAG_BYTES], blob[-_TAG_BYTES:]
+    authentication_key = _subkey(key, b"authentication")
+    expected_tag = hmac.new(
+        authentication_key, authenticated, hashlib.sha256,
+    ).digest()
+    if not hmac.compare_digest(supplied_tag, expected_tag):
+        raise ValueError("ciphertext authentication failed")
+    nonce_start = len(_VERSION)
+    nonce = blob[nonce_start : nonce_start + _NONCE_BYTES]
+    ciphertext = blob[nonce_start + _NONCE_BYTES : -_TAG_BYTES]
+    encryption_key = _subkey(key, b"encryption")
+    pt = bytearray()
+    for i in range(0, len(ciphertext), _BLOCK):
+        chunk = ciphertext[i : i + _BLOCK]
+        ks = _keystream(encryption_key, nonce, i // _BLOCK)[: len(chunk)]
+        pt.extend(c ^ k for c, k in zip(chunk, ks))
+    try:
+        return bytes(pt).decode()
    except UnicodeDecodeError as exc:
        raise ValueError(f"decryption produced non-UTF-8 output (wrong key?): {exc}") from exc


-__all__ = ["ENV_VAR_SECRET_NAME", "new_env_var_secret", "encrypt_value", "decrypt_value"]
+__all__ = [
+    "ENV_VAR_SECRET_NAME",
+    "new_env_var_secret",
+    "encrypt_value",
+    "decrypt_value",
+    "is_legacy_blob",
+]
@@ -40,7 +40,7 @@ from .paths import (

 class ProvisioningError(RuntimeError):
    """A control-plane auth invariant would be violated (e.g. starting the
-    orchestrator without its signing key — which would run OPEN)."""
+    orchestrator without its signing key)."""


@dataclass(frozen=True)
@@ -67,9 +67,8 @@ class TrustDomain:

    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`)."""
+        (default `os.environ`). ``""`` when unset; owning services reject that
+        value rather than start without authentication."""
        env = os.environ if environ is None else environ
        return env.get(self.key_env, "").strip()

@@ -56,8 +56,7 @@ key.
 - 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.
+- Network topology or the plane split (#469).

 ## Design

@@ -0,0 +1,197 @@
+# PRD 0082: Authoritative failure boundaries
+
+- **Status:** Draft
+- **Author:** codex
+- **Created:** 2026-07-27
+- **Issue:** #444
+
+## Summary
+
+Make every security- or lifecycle-sensitive snapshot distinguish authoritative
+empty state from unavailable state, and make every destructive or
+resource-consuming boundary revalidate the assumptions it acts on. This
+finishes the focused quality work begun under #444 without broad rewrites:
+cleanup cannot act on stale identities, policy introspection cannot publish a
+fabricated empty policy, gateway servers bound untrusted work, and daemon
+shutdown does not emit uncaught background-thread failures. Shared
+control-plane storage and gateway credential provisioning also enforce their
+filesystem security contract before sensitive data is written.
+
+## Problem
+
+Several paths are individually fail-closed but compose into unsafe or
+misleading behavior:
+
+1. `cleanup` prepares a plan, waits indefinitely for operator confirmation,
+   then kills stored PIDs and removes stored paths without checking that those
+   identities still describe the same orphan. A PID may be reused or a run
+   directory may become active during the prompt.
+2. The supervisor reuses egress's deny-all fallback for
+   `list-egress-routes`. Deny-all is correct for enforcement, but presenting it
+   as a successful empty route table can cause a later replace-all proposal to
+   discard live routes.
+3. The supervisor and Git HTTP services accept bounded declared body sizes but
+   use blocking reads and unbounded request threads. An untrusted bottle can
+   exhaust the shared gateway with slow or parallel requests.
+4. macOS cleanup enumerates containers and networks independently and treats a
+   failed query as an empty class, so a partial snapshot can still become a
+   destructive plan.
+5. Gateway log-pump threads race stream closure during shutdown and emit
+   uncaught exceptions even when shutdown otherwise succeeds.
+6. Firecracker discovers VMs through whitespace-split `pgrep -a` output.
+   A configured cache path containing spaces can hide a live VM from the
+   snapshot and make its run directory appear orphaned.
+7. Docker cleanup asks compose for its project snapshot in best-effort mode.
+   A transient query failure can therefore become an empty stopped-project
+   set and authorize deletion of associated state directories.
+8. Firecracker artifact downloads and registry publication have no network
+   deadline, so an unresponsive registry can hold setup or release work
+   indefinitely.
+9. Authenticated secret blobs select the unauthenticated legacy decoder when
+   their in-band version prefix is changed, allowing storage tampering to
+   bypass tag verification.
+10. Cleanup executes the entire post-confirmation snapshot rather than the
+    intersection with what the operator saw, and mutation failures are not
+    reflected in the command result.
+11. Git smart-HTTP can retain sixteen 100 MiB request bodies concurrently,
+    cleanup mutations have no subprocess deadline, and Firecracker signalling
+    failures bypass shared mutation accounting.
+12. SQLite creates the shared control-plane database before its mode is
+    restricted, then suppresses permission-repair failures. Gateway transports
+    also differ in whether copied deploy-key modes are preserved.
+
+These are one design problem: state used to authorize deletion, replacement,
+or resource allocation must be authoritative at the point of use.
+
+## Goals / Success Criteria
+
+- Cleanup never signals a PID or recursively deletes a path solely because it
+  appeared in a pre-confirmation snapshot.
+- Firecracker cleanup proves immediately before action that a PID is still the
+  same Firecracker process and that a run directory is still orphaned.
+- Firecracker process discovery reads NUL-delimited argv from `/proc`; paths
+  are never reconstructed from whitespace-delimited process listings.
+- All backend cleanup discovery primitives raise a typed enumeration error on
+  operational failure. No backend may independently continue from a partial
+  snapshot.
+- Shared cleanup control flow lives in the backend layer; concrete backends
+  override resource-specific discovery and validation primitives rather than
+  each implementing a bespoke failure policy.
+- `list-egress-routes` returns an MCP error when attribution or policy
+  resolution is unavailable. A genuine, authoritatively resolved empty policy
+  remains a successful empty list.
+- Supervisor and Git HTTP request bodies have total read deadlines, and each
+  service bounds concurrent request work. Limits apply to authenticated
+  callers because bottles themselves are untrusted.
+- Gateway child-output pumping treats expected stream closure during shutdown
+  as completion while preserving diagnostics for unexpected failures.
+- Artifact pull, existence-check, and publication requests use explicit
+  network deadlines.
+- Persisted secrets accept only the authenticated format. The schema migration
+  intentionally clears legacy rows; local agents are reprovisioned rather
+  than retaining a ciphertext-controlled downgrade path.
+- Cleanup executes only resources present in both the displayed and current
+  authoritative plans, attempts every approved mutation, and returns failure
+  when any mutation does not complete.
+- Git request bodies spool to disk behind a separate heavy-work semaphore;
+  cleanup commands have configurable deadlines; Firecracker signalling
+  failures aggregate while identity-verification uncertainty still aborts.
+- The shared database directory and file are private before SQLite writes any
+  control-plane state; an inability to enforce those modes aborts startup.
+- Gateway credential directories and files receive explicit private modes
+  inside the gateway, independent of Docker, Apple Container, or SSH copy
+  semantics.
+- Unit tests cover PID/path reuse, partial backend enumeration, transient
+  policy resolution failure, slow bodies, concurrency saturation, and stream
+  closure races.
+
+## Non-goals
+
+- Further decomposition solely to reduce module line counts.
+- Replacing gateway stdlib HTTP services with a web framework.
+- Changing egress matching, DLP decisions, proposal semantics, or backend
+  launch behavior beyond the synchronization required for safe cleanup.
+- Making cleanup silently skip uncertain resources. Uncertainty is an
+  operator-visible failure.
+
+## Design
+
+### Shared backend control flow
+
+Follow the backend architecture rule used by gateway attachment: shared
+behavior lives above concrete backends; subclasses provide primitives, not
+control flow.
+
+Cleanup remains previewable, but confirmation authorizes a *new authoritative
+evaluation*, not blind execution of the displayed object. The shared flow:
+
+1. asks each available backend for a preview;
+2. displays the union and asks for confirmation;
+3. refreshes each non-empty backend plan;
+4. validates destructive identities immediately before action;
+5. aborts loudly if the refreshed plan or any identity cannot be proven safe.
+
+Backend-specific primitives define how to identify a resource. Firecracker
+uses process start identity plus canonical config/run paths; container
+backends use authoritative CLI queries and stable resource names/labels.
+
+Container engines expose destructive name-based commands without a portable
+compare-and-delete operation. Cleanup therefore refreshes after confirmation
+and requires every discovery query to succeed, minimizing but not claiming to
+eliminate the final name-reuse race. A future engine-specific stable-ID
+primitive may close that residual window without moving control flow back
+into each backend.
+
+### Enforcement state versus introspection state
+
+Egress enforcement retains its deny-all fallback because uncertainty must not
+grant network access. Supervisor introspection uses a strict resolver path:
+unattributed callers and resolver failures become typed MCP errors, while a
+successfully resolved policy containing zero routes returns `routes: []`.
+
+### Gateway resource boundaries
+
+Both stdlib servers set a per-connection body deadline before reading and use a
+bounded request executor or semaphore. Saturated capacity fails quickly with a
+service-unavailable response. Existing size caps remain independent:
+supervisor proposals retain the 1 MiB cap and Git pack requests retain their
+larger protocol-appropriate cap.
+
+### Shutdown diagnostics
+
+The gateway output pump catches only stream-closure exceptions expected after
+the supervisor closes child pipes. Other I/O failures remain visible and are
+reported through the supervisor's normal diagnostic channel.
+
+### Shared filesystem security
+
+The common SQLite store owns database creation for every backend. It creates
+the parent directory and an empty database with private modes before opening
+SQLite, repairs existing modes, verifies the resulting state, and propagates
+every enforcement failure. Backend launchers do not duplicate this policy.
+
+The backend-neutral gateway provisioner likewise applies directory and file
+modes after transport copies complete. This avoids relying on copy behavior
+that differs among Docker, Apple Container, and Firecracker's SSH transport.
+
+## Implementation chunks
+
+1. Existing fail-closed security and backend enumeration fixes.
+2. FastAPI orchestrator transport and bounded control-plane bodies.
+3. Egress request-policy and outbound-DLP pipeline extraction.
+4. Supervisor MCP dispatch extraction.
+5. Shared cleanup refresh/revalidation plus authoritative macOS discovery.
+6. Strict supervisor introspection and bounded supervisor/Git HTTP work.
+7. Gateway shutdown log-pump closure handling.
+8. Lossless Firecracker process identities, authoritative Docker cleanup
+   queries, and bounded Firecracker artifact transfers.
+9. Mandatory authenticated secret storage, shared cleanup-plan intersection
+   and mutation accounting, and contained Git backend process failures.
+10. Disk-spooled and separately bounded Git bodies, cleanup command deadlines,
+    and classified Firecracker signalling failures.
+11. Fail-closed shared database creation and backend-neutral gateway credential
+    permissions.
+
+## Open questions
+
+None.
@@ -32,17 +32,9 @@ not a principled scope exclusion: both are major hosted sandbox platforms and
 belong in this landscape even though they target platform builders rather than
 bot-bottle's local single-operator workflow.

-Updated 2026-07-27 after a scan of recent Show HN launches: **Black LLAB,
-Eve, CloudRouter, Nucleus, yolo-cage, and Sandbox Agent SDK** added as a
-dated entrant cohort. They sharpen the comparison on three axes the original
-table underweighted: the browser/preview loop, parallel-agent operator UX, and
-a provider-neutral automation/session API.
-
 ## Summary

-The main table compares bot-bottle against fifteen canonical
-isolation/sandbox tools; a later section evaluates six recent HN entrants
-without widening an already unwieldy table.
+The main table compares bot-bottle against fifteen isolation/sandbox tools.
 Governance/pre-action authorization and credential-only layers are covered
 separately because they don't provide VM or container isolation. None
 duplicate bot-bottle's combination of local
@@ -550,199 +542,6 @@ them.
  framework runtime is not compromised.
 - **Maturity**: Specification + reference implementation, 2026.

-## Recent HN entrants (added 2026-07-27)
-
-These are grouped by launch date rather than promoted into the main table.
-Several are young or sparsely documented, and putting them beside mature
-runtime platforms with false precision would obscure the useful comparison.
-The HN launch posts are the evidence snapshot; feature claims should be
-rechecked against their repositories before relying on them for a security
-decision.
-
-### Black LLAB
-
- **Source**: https://github.com/isaacdear/black-llab ;
-  HN launch https://news.ycombinator.com/item?id=47402394
- **Isolation/locality**: Local Docker environment, with an isolated container
-  created for each agent task. Shared host kernel; no stronger boundary is
-  claimed.
- **Agent integration**: General local/cloud model workspace. Its headline is
-  dynamic routing of simple prompts to local models and complex prompts to
-  hosted models, with code execution and web scraping inside the task
-  container.
- **Network/credentials**: No default-deny egress, payload inspection, or
-  host-side credential injection documented in the launch.
- **Competitive read**: Superficial overlap ("a container per agent task"),
-  but not a direct security-policy competitor. Its useful challenge is the
-  integrated model-selection UX, which bot-bottle intentionally leaves to the
-  selected agent provider.
- **Maturity**: Early solo project; HN launch received 1 point.
-
-### Eve
-
- **Source**: https://eve.new/ ;
-  HN launch https://news.ycombinator.com/item?id=47721255
- **Isolation/locality**: Managed, hosted Linux sandbox per user/session
-  (claimed 2 vCPU, 4 GB RAM, 10 GB disk), with filesystem, code execution,
-  headless Chromium, and service connectors.
- **Agent integration**: End-user OpenClaw-style agent product. An orchestrator
-  routes subtasks to specialist models and can run parallel subagents that
-  coordinate through a shared filesystem. Web UI and iMessage are primary
-  interaction surfaces.
- **Network/credentials**: Broad connectors are a product feature; the launch
-  does not document bot-bottle-style default-deny route policy, content DLP,
-  or credentials held outside the sandbox.
- **Competitive read**: Adjacent, not direct. Eve sells a managed colleague;
-  bot-bottle lets an operator run existing coding-agent CLIs under local
-  containment. Eve nevertheless demonstrates the appeal of background work,
-  live progress, browser capability, and mobile notification.
- **Maturity**: Commercial hosted product; HN launch received 71 points and
-  39 comments.
-
-### CloudRouter
-
- **Source**: https://github.com/manaflow-ai/manaflow/tree/main/packages/cloudrouter ;
-  HN launch https://news.ycombinator.com/item?id=47006393
- **Isolation/locality**: Claude Code or Codex runs locally and provisions
-  remote cloud VMs/GPUs for execution. Project files are uploaded to the VM;
-  each machine exposes auth-protected VNC, VS Code, and Jupyter surfaces.
- **Agent integration**: A skill plus CLI lets the coding agent itself start,
-  command, inspect, and tear down machines. Browser automation is integrated,
-  including snapshots and screenshots. Parallel disposable compute is the
-  central workflow.
- **Network/credentials**: The launch emphasizes remote resource isolation and
-  authenticated UI endpoints, not default-deny guest egress, payload DLP, or
-  proxy-held application credentials.
- **Competitive read**: The closest recent workflow competitor. It directly
-  addresses parallel coding agents, environmental conflict, and closing the
-  browser/test loop, but trades local custody for elastic cloud compute.
-  Cloud VMs and GPUs could be a future bot-bottle backend; they do not replace
-  its manifest/policy layer.
- **Maturity**: Active open-source monorepo project; HN launch received
-  138 points and 36 comments.
-
-### Nucleus
-
- **Source**: https://github.com/coproduct-opensource/nucleus ;
-  HN launch https://news.ycombinator.com/item?id=46855770
- **Isolation/locality**: Firecracker microVM with an enforcing MCP tool proxy.
- **Agent integration/config**: Compositional permission envelope for
-  read/write/run actions. The envelope is non-escalating and can tighten or
-  terminate, with scoped approval tokens for gated operations.
- **Network/credentials**: Default-deny egress, DNS allowlist, iptables drift
-  detection, time/budget caps, and hash-chained audit logging are claimed.
-  Remote append-only audit storage and attestation were roadmap items at
-  launch.
- **Competitive read**: Direct on security architecture, especially
-  non-escalating policy and tamper-evident audit. It is an early execution/tool
-  proxy rather than a provider-neutral, one-command coding-agent product. Its
-  tool-level action envelope is semantically finer than bot-bottle's network
-  boundary; bot-bottle is stronger on turnkey agent/provider integration,
-  credential custody, Git mediation, and long-running operator workflow.
- **Maturity**: Early OSS experiment; HN launch received 3 points.
-
-### yolo-cage
-
- **Source**: https://github.com/borenstein/yolo-cage ;
-  HN launch https://news.ycombinator.com/item?id=46706796
- **Isolation/locality**: Local sandbox for running multiple coding agents in
-  YOLO mode. The launch discussion describes a VM boundary.
- **Agent integration**: Built around the native Claude Code experience and
-  motivated by running many agents in parallel without permission-prompt
-  fatigue.
- **Network/Git/credentials**: Strict egress filtering, configurable HTTP
-  middleware, and mediated `git`/`gh` dispatch are the main value. The launch
-  discussion explicitly identifies provider credential handling as unfinished
-  and difficult because Claude state spans multiple host paths.
- **Competitive read**: The closest new threat-model competitor. It shares
-  bot-bottle's premise that filesystem isolation alone is insufficient and
-  that Git plus authorized HTTP channels need mediation. bot-bottle currently
-  leads on cross-provider support, proxy-held Claude/Codex/forge credentials,
-  typed per-role manifests, content DLP, and supervision. yolo-cage's simpler
-  pitch and narrower Claude-first setup may be easier to explain.
- **Maturity**: Early local tool; HN launch received 60 points and 76 comments.
-
-### Sandbox Agent SDK
-
- **Source**: https://github.com/rivet-dev/sandbox-agent ;
-  HN launch https://news.ycombinator.com/item?id=46795584
- **Isolation/locality**: Does not provide the isolation primitive. It runs
-  inside E2B, Daytona, Modal, Cloudflare Containers, Agent Computer, BoxLite,
-  Docker, or another sandbox provider. Embedded mode can also run locally
-  without a sandbox.
- **Agent integration**: Provider-neutral Rust server/SDK exposing a common
-  HTTP/SSE/OpenAPI interface across Claude Code, Codex, OpenCode, Cursor, Amp,
-  and Pi, plus a universal event/session schema for external storage and
-  replay. It also exposes filesystem, managed-process, terminal, MCP, skills,
-  custom-tool, and computer-use APIs. TypeScript is the primary SDK surface.
- **Network/credentials**: Delegated to the chosen sandbox provider.
- **Credential posture**: Its documented convenience command extracts real
-  OpenAI/Anthropic credentials from local agent configuration and passes them
-  as environment variables into the sandbox. That is materially weaker than
-  bot-bottle's host-side credential custody, but it is an integration choice,
-  not a structural limitation: a sandbox provider could put a credential
-  proxy underneath the same SDK.
- **Competitive read**: A serious architectural threat despite not supplying
-  isolation. Sandbox Agent is trying to standardize the boundary *above* the
-  sandbox: one client protocol, session model, and UI/control surface across
-  every coding agent and runtime. If that boundary becomes the ecosystem
-  standard, users and application builders may choose a sandbox provider plus
-  Sandbox Agent rather than a vertically integrated launcher. bot-bottle's
-  manifests would then be valuable chiefly as a local policy/backend
-  implementation unless they expose an equally usable control contract.
- **Maturity**: Apache 2.0, ~1.5k stars and 426 commits at the 2026-07-27
-  check; HN launch received 41 points.
-
-#### Why the Sandbox Agent architecture is strategically different
-
-The manifest and the universal control protocol solve different layers:
-
- A bot-bottle manifest is a **trusted launch-time policy composition**. It
-  selects the agent role, isolation backend, image, skills, egress routes,
-  credentials, Git mediation, and supervision policy. Crucially, identity and
-  secret references live on the host side of the trust boundary.
- Sandbox Agent is a **runtime control and observation protocol**. A remote
-  client creates sessions, sends messages, handles permissions, configures
-  skills/MCP, manipulates files/processes/desktops, and streams normalized
-  events. It deliberately delegates sandbox lifecycle, Git management,
-  storage, network policy, and credential security to other products.
-
-That makes it complementary in a component diagram but competitive in product
-architecture. The layer that becomes the stable integration point tends to own
-the ecosystem. Three plausible threat paths matter:
-
-1. **Standard control plane, interchangeable runtimes.** Applications integrate
-   once with Sandbox Agent and treat E2B, Daytona, BoxLite, Docker, or a future
-   local microVM as replaceable compute. A provider that bundles adequate
-   egress and credential custody makes bot-bottle's end-to-end launcher less
-   necessary.
-2. **Policy grows upward.** Sandbox Agent already configures permissions,
-   skills, MCP, custom tools, filesystem/process access, and computer use. If
-   it adds a declarative, host-verifiable policy document, the overlap with
-   agent/bottle manifests becomes substantial even if enforcement remains
-   delegated.
-3. **UI and session ownership.** Its universal transcript schema, Inspector,
-   React components, event replay, and remote terminal/computer APIs can become
-   the natural basis for desktop, web, and mobile agent managers. bot-bottle's
-   security layer could remain stronger while losing the operator surface and
-   distribution channel.
-
-The counter-position is not to claim that manifests and an API are mutually
-exclusive. The defensible split is:
-
- bot-bottle owns the trusted policy and enforcement plane outside the agent;
- a provider-neutral protocol owns agent process control and normalized
-  events; and
- the operator UI consumes both.
-
-This suggests an explicit compatibility decision rather than parallel,
-accidental protocol design: evaluate running Sandbox Agent inside a bottle and
-exposing it only through the authenticated bot-bottle control plane. If its
-schema is suitable, adopting it could turn a threat into an integration while
-keeping manifests as the higher-trust policy source. If it is unsuitable,
-bot-bottle should still publish a stable provider-neutral session/event API so
-frontends do not depend on Claude/Codex/Pi-specific process behavior.
-
 ## Comparison table

 *Isolation/sandbox tools only. AGT and OAP are governance layers — see their per-project notes above.*
@@ -817,70 +616,6 @@ would be a *backend* bot-bottle could call, not a competitor to its
 manifest layer. endo-familiar is in a different paradigm entirely:
 capability passing rather than kernel boundaries.

-**Recent entrants change two parts of this read.** yolo-cage is closer to the
-actual threat model than agent-safehouse or litterbox: it combines a VM-style
-boundary with mediated Git and filtered HTTP specifically for parallel coding
-agents. Sandbox Agent SDK is the more important strategic entrant even though
-it supplies no isolation. It can become the standard agent-control layer above
-all of these runtimes, including a future bot-bottle backend. CloudRouter is
-the clearest workflow challenge because its browser/desktop/GPU loop makes
-parallel agents visibly more capable, not merely safer.
-
-## Gap evaluation after the 2026-07-27 entrant scan
-
-### Material gaps
-
-1. **A stable provider-neutral control and event protocol.** This is the
-   largest newly visible gap. bot-bottle normalizes launch/provisioning across
-   providers, but an external UI or orchestrator still lacks one documented
-   contract for creating a Claude/Codex/Pi session, sending input, handling
-   permission/supervision events, streaming normalized output, reconnecting,
-   and replaying history. Sandbox Agent SDK addresses exactly this layer and
-   is already portable across many sandbox providers.
-2. **Browser/preview closure.** CloudRouter and Eve make a browser or desktop
-   part of the standard agent environment and expose screenshots/live viewing
-   to the operator. bot-bottle can run dev servers and supports nested
-   containers, but it does not present a first-class browser/computer-use
-   primitive or an auth-protected preview surface. For coding agents expected
-   to verify UI work, this is a real product gap.
-3. **Unified parallel-session operator UX.** Named persistent bottles and
-   supervision provide the substrate, but the recent products make task
-   switching, live progress, notifications, terminal attach, diffs, and
-   session history the product. Security depth will not compensate for a
-   visibly rougher daily loop.
-4. **Normalized transcript persistence and replay.** bot-bottle preserves
-   provider-specific state for resume; it does not expose a provider-neutral
-   event record suitable for audit, replay, analytics, or a web/mobile client.
-   This is both a UX gap and an audit gap.
-
-### Important, but not necessarily bot-bottle features
-
- **Cloud VM/GPU provisioning.** Valuable for elastic workloads and could be a
-  backend, but it conflicts with the local-custody default and should not
-  displace core policy work.
- **Automatic model routing.** Black LLAB and Eve sell task-to-model routing.
-  bot-bottle's provider-template boundary can host that choice without making
-  it part of the trusted sandbox policy.
- **A thousand SaaS connectors.** This broadens capability and blast radius.
-  The bot-bottle-native answer should remain explicit, scoped forge/egress
-  associations rather than connector count as a goal.
- **SDK-driven sandbox lifecycle as the primary configuration model.** Useful
-  for platform builders, but not a replacement for reviewable, host-owned
-  manifests. A control API and a declarative policy source are compatible;
-  neither should silently become the other.
-
-### Areas where bot-bottle remains ahead
-
- real provider and forge credentials remain outside the agent process rather
-  than being extracted into its environment;
- authorized HTTP payloads are scanned, not merely destination-filtered;
- Git writes traverse a distinct gate with secret scanning and host-held
-  upstream credentials;
- role policy is host-owned, composable, and separate from untrusted repo
-  content; and
- local Firecracker/Apple Container execution preserves operator custody
-  without requiring a hosted sandbox platform.
-
 ## Borrowable ideas

 ### Already shipped or otherwise addressed
@@ -907,19 +642,6 @@ parallel agents visibly more capable, not merely safer.

 ### Still worth considering

- **Sandbox Agent compatibility or an equivalent stable protocol (highest
-  priority):** spike running its server inside a bottle behind bot-bottle's
-  authenticated control plane. Compare its session/event schema, permission
-  model, restore semantics, and provider coverage with current provider
-  adapters. Adopt compatibility if it preserves the host-owned trust boundary;
-  otherwise specify bot-bottle's own stable API before building another UI.
- **First-class browser/preview loop** (from CloudRouter and Eve): give a
-  bottle an optional browser/computer-use capability plus an operator-visible,
-  authenticated preview/screenshot surface. Treat its network access as part
-  of the bottle policy, not an implicit bypass.
- **Provider-neutral transcript/event persistence** (from Sandbox Agent SDK):
-  retain enough normalized structure for replay and audit while preserving the
-  provider-native state needed for exact resume.
 - **Live network activity in the supervisor TUI** (from Docker sbx): show
  allowed and blocked connections and let the operator propose policy changes
  from the existing supervision surface.
@@ -930,11 +652,10 @@ parallel agents visibly more capable, not merely safer.
  closer review. This needs a carefully specified trust model before it can be
  more than a heuristic.

-Not worth borrowing: SDK-first *policy configuration* as used by boxlite /
-microsandbox (cuts against the reviewable declarative-manifest stance), and
-the hosted-SaaS custody model of tilde.run (cuts against the "infrastructure I
-control" goal). A provider-neutral runtime-control API is a separate concern
-and is worth borrowing.
+Not worth borrowing: the SDK-first programmatic API style of boxlite /
+microsandbox (cuts against the declarative-manifest stance), and the
+hosted-SaaS dashboard model of tilde.run (cuts against the
+"infrastructure I control" goal).

 ## Publishing and positioning verdict

@@ -958,15 +679,9 @@ bot-bottle remains unusual in combining:
 The practical wedge is “as easy as native yolo, with declarative role policy
 and self-hosted custody,” including scoped access to private LAN/Tailnet
 services that cloud-first runtimes cannot provide without additional network
-plumbing. The main competitive risks are now:
-
- a local wrapper such as yolo-cage, claudebox, or Docker sbx growing a
-  role-manifest and credential-custody layer;
- Sandbox Agent SDK becoming the standard control/session boundary and making
-  the runtime beneath it interchangeable; and
- GUI products such as SuperHQ or CloudRouter adding equivalent policy and
-  audit depth before bot-bottle closes the browser/preview and
-  parallel-session UX gaps.
+plumbing. The main competitive risks are a local wrapper such as claudebox or
+Docker sbx growing a role-manifest layer, and GUI products such as SuperHQ
+adding equivalent policy and audit depth.

 ## Caveats

@@ -1,258 +0,0 @@
-# Testing a clean bot-bottle install on macOS
-
-How do you exercise `install.sh` (and, ideally, a first `bot-bottle start`)
-the way a brand-new user would — on a pristine macOS environment you can
-throw away afterward — *without* permanently polluting your daily-driver
-Mac? The user's framing: is there a VM or boundary that avoids creating a
-separate account, or is spinning up and tearing down a throwaway macOS
-user on the CLI easy enough to just do that?
-
-## Summary
-
-There is no lightweight, in-place macOS sandbox that hands you a clean home
-directory and wipeable system state without *either* a VM or a separate
-user account. `sandbox-exec` (Seatbelt) is deprecated and confines a
-process, not an environment; App Sandbox is for shipping apps, not for
-provisioning a fresh dev host. So the real choice is exactly the two the
-user named: **a disposable macOS VM** or **a throwaway user account** —
-and which one is right turns on a detail specific to *this* project.
-
-bot-bottle's default macOS backend is Apple's `container`, which runs each
-container in its own lightweight VM via `Virtualization.framework`
-([`README.md:27`](../README.md), [`apple-container-backend.md`](apple-container-backend.md)).
-That means a full end-to-end test — install *and* `bot-bottle start` —
-needs virtualization to work wherever bot-bottle runs. Inside a macOS guest
-VM that requires **nested virtualization, which Apple gates to M3 or newer
-chips on macOS 15+**. On M1/M2 you cannot run the Apple Container backend
-(or Docker Desktop, same reason) inside a macOS VM at all.
-
-The recommendation splits on what you're testing and what silicon you have:
-
- **Install-script correctness only** (does `curl | sh` → pipx → config dir
-  → `doctor`'s Python/config checks pass?): a **disposable Tart VM** is the
-  cleanest boundary and works on any Apple Silicon Mac. `doctor` will report
-  the backend as not-ready inside the VM on M1/M2, which is fine — you're
-  testing the installer, not the runtime.
- **Full runtime** (actually launch a bottle) on **M3/M4**: a **disposable
-  Tart VM from a golden base image, cloned per run** is the gold standard —
-  a genuine kernel/state boundary that wipes to nothing.
- **Full runtime** on **M1/M2**, or when you'd rather not fight nested virt:
-  a **throwaway admin user via `sysadminctl`** is the pragmatic pick. It
-  tests the real backend because the backend runs on the host hypervisor —
-  but it is a *hygiene* boundary, not a security one, and it does **not**
-  clean the system-level footprint (see below).
-
-Prefer the VM. Reach for the throwaway user only when nested virt is off the
-table and you accept an imperfect wipe.
-
-## Why "a boundary without a separate user" doesn't really exist on macOS
-
-macOS has no namespace/overlay story like Linux `unshare` + tmpfs. The
-options that sound like in-place sandboxes don't fit:
-
-| Mechanism | Why it doesn't give you a clean, wipeable env |
-|---|---|
-| `sandbox-exec` / Seatbelt | Officially deprecated; confines *one process's* syscalls against a profile. It cannot present a fresh `$HOME` or a pristine `/usr/local`, and it won't let the Apple Container system service work. |
-| App Sandbox | Entitlement-based confinement for signed `.app` bundles, not a provisioning tool for a CLI dev environment. |
-| A second `$HOME` via `HOME=/tmp/foo` | Redirects only what honors `$HOME`. `install.sh` mostly does (it writes `~/.bot-bottle` and pipx/pip `--user` paths), but the Apple `container` install lands in `/usr/local` + a **system service**, and Homebrew lands in `/opt/homebrew` — all outside any `$HOME` you set. You'd get a false sense of "clean." |
-| APFS snapshot rollback (`tmutil localsnapshot`) | You can't roll the live boot volume back to a local snapshot without booting to Recovery; it's not a per-run userspace undo. |
-
-So the honest answer to "is there some boundary that avoids a separate
-user?": yes — a **VM** — and it's the *stronger* boundary anyway. The only
-lighter-weight option is the separate user, with the caveats below.
-
-## What a clean install actually touches (the footprint that decides "wipeable")
-
-Grounding the teardown story in what `install.sh` and the backend create:
-
-| Artifact | Location | In `$HOME`? | Survives user deletion? |
-|---|---|---|---|
-| Config / state / db | `~/.bot-bottle/{agents,bottles,contrib,state,db}` ([`install.sh:80-83`](../install.sh), [`bot_bottle/paths.py:59`](../bot_bottle/paths.py)) | ✅ | ❌ removed with home |
-| pipx venv + shim | `~/.local/pipx/venvs/bot-bottle`, shim in `~/.local/bin` ([`install.sh:87-89`](../install.sh)) | ✅ | ❌ removed with home |
-| private venv fallback (no pipx) | `~/.bot-bottle/venv` + symlink in `~/.local/bin` ([`install.sh`](../install.sh)) | ✅ | ❌ removed with home |
-| PATH / token exports | shell profile (`~/.zprofile`, etc.); `BOT_BOTTLE_CLAUDE_OAUTH_TOKEN` ([`README.md:74`](../README.md)) | ✅ | ❌ removed with home |
-| **Apple `container` install** | `/usr/local/...` + notarized `.pkg` receipts | ❌ | ✅ **stays** |
-| **Apple `container` system service** | launchd system service (`container system start`) | ❌ | ✅ **stays** |
-| **Homebrew** (if used for `container`/python) | `/opt/homebrew` | ❌ | ✅ **stays** |
-| Rosetta 2 (needed for image builds) | system | ❌ | ✅ **stays** |
-
-The three bold rows are the crux: **deleting the throwaway user does not
-uninstall the Apple Container runtime, its system service, Homebrew, or
-Rosetta.** A VM, by contrast, wipes 100% of the above by definition —
-that's its entire advantage for this task.
-
-## Option A — Disposable Tart VM (recommended)
-
-[Tart](https://tart.run) is a CLI-first macOS/Linux VM manager built on
-`Virtualization.framework`, purpose-built for exactly this "does it work on
-a clean macOS, without my settings/permissions/data" workflow. Keep one
-pristine *golden* image, clone a throwaway per run, delete it after.
-
-```sh
-brew install cirruslabs/cli/tart
-
-# One-time: build a golden base (either a prebuilt image or a vanilla IPSW).
-tart clone ghcr.io/cirruslabs/macos-tahoe-base:latest golden   # ~25 GB pull
-# — or a truly vanilla install you click through once —
-# tart create golden --from-ipsw latest --disk-size 60
-
-# Per test run: clone → boot → test → destroy.
-tart clone golden test-run
-tart run test-run &
-ssh admin@"$(tart ip test-run)"
-#   inside the guest:
-#   curl -fsSL https://gitea.dideric.is/didericis/bot-bottle/raw/branch/main/install.sh | sh
-#   bot-bottle doctor
-tart stop test-run
-tart delete test-run          # back to pristine; golden is untouched
-```
-
-Cloning is cheap (sparse files), so the golden image is your reset button —
-every `tart clone` is a fresh macOS. This is the closest thing to a Linux
-`docker run --rm` for a whole Mac.
-
-**The nested-virt caveat (read before relying on it for runtime tests).**
-The Apple Container backend inside the guest needs
-`Virtualization.framework` to work *inside* the VM. Apple enables nested
-virtualization only on **M3 or newer**, on **macOS 15 (Sequoia) or later**;
-M2 and earlier are excluded by Apple, confirmed by Apple DTS. Consequences:
-
- **M3/M4 host:** full runtime works in the guest. `bot-bottle doctor`
-  reports the backend ready and `start` can launch a bottle. Gold standard.
- **M1/M2 host:** the guest can install bot-bottle and pass the Python /
-  config-dir checks, but `doctor`'s backend check will fail and you cannot
-  launch a bottle in the VM. Still perfectly good for testing *the
-  installer*; not for the runtime.
- **M4-specific:** a known bug blocks pre-Ventura guests on M4; use a
-  current macOS guest (which you want anyway, since Apple `container`
-  targets macOS 26 Tahoe).
-
-UTM is the GUI equivalent on the same framework (and was first to expose
-nested virt) if you'd rather click; Tart wins for a scriptable
-spin-up/tear-down loop.
-
-## Option B — Throwaway user via `sysadminctl` (pragmatic fallback)
-
-Creating and deleting a user from the CLI is genuinely a two-liner, and it
-tests the **real** backend on any Apple Silicon Mac because the backend runs
-on the host hypervisor — no nested virt needed.
-
-```sh
-# Create a self-contained admin user (admin needed for the container service).
-sudo sysadminctl -addUser bbtest -fullName "bot-bottle test" \
-    -password 'throwaway' -admin
-
-# Log into that account (fast-user-switch or the login window), then run the
-# installer as bbtest exactly as a new user would. When done:
-
-sudo sysadminctl -deleteUser bbtest -secure   # -secure erases the home dir
-```
-
-Honest accounting of what this does and doesn't buy you:
-
- **Boundary strength:** it's a *hygiene / fresh-`$HOME`* boundary, **not a
-  security boundary.** Same kernel, same admin group; an admin test user can
-  touch system state. If the point is "clean environment," fine. If the point
-  is "contain something untrusted," this is the wrong tool — use a VM.
- **Wipe completeness:** `-secure` erases the home dir (so `~/.bot-bottle`,
-  the pipx venv, and profile exports go away), but as the footprint table
-  shows, the **Apple Container runtime, its launchd system service,
-  Homebrew, and Rosetta persist.** For a truly repeatable "did a *system with
-  nothing installed* work?" test, that residue defeats the purpose — the
-  second run isn't clean.
- **Operational gotchas:** don't pass real passwords on the command line (they
-  land in `ps` and history — this is a throwaway credential, so it's
-  tolerable here). Deletion must run as root from a normally-booted, admin-
-  logged-in session; the Terminal needs **Full Disk Access** or you'll hit
-  error `-14120` and a half-deleted account. Prefer letting the system place
-  the home dir (don't pass `-home`), or deletion can orphan it.
-
-Use this when you're on M1/M2, you specifically want to exercise the live
-backend, and you can tolerate the system-level runtime staying installed
-between runs (or you uninstall Apple `container` / brew by hand to reset).
-
-## Honorable mentions
-
- **External bootable macOS volume.** A fresh macOS on an external SSD (or a
-  separate APFS volume) is bare-metal disposable: no nested-virt limit, real
-  backend works, and you `diskutil` the volume away to reset. Cost is reboot
-  friction per run — good for an occasional thorough pass, poor for a tight
-  loop.
- **Rented / cloud Mac.** AWS EC2 Mac (dedicated Mac minis), Scaleway Apple
-  silicon, or MacStadium give a genuinely throwaway host you release when
-  done. Overkill for local iteration, but this is essentially what the
-  project's own advisory `integration-macos` CI job needs — a self-hosted
-  Apple Silicon runner with the `container` CLI, Python ≥ 3.11, and coverage
-  on the launchd service's PATH ([`README.md:78`](../README.md)). If you end
-  up standing up a cloud Mac for install testing, it doubles as that runner.
-
-## Recommendation
-
-Default to a **disposable Tart VM** — it's the only option that wipes the
-*entire* footprint (including the Apple Container system service that a user
-deletion leaves behind), it's a real boundary, and the spin-up/tear-down
-loop is a two-command `tart clone` / `tart delete`. Confirm your chip first:
-on **M3/M4** it tests install *and* runtime end-to-end; on **M1/M2** it still
-cleanly tests `install.sh` + `doctor`'s Python/config path, and you fall back
-to a **throwaway `sysadminctl` admin user** for live-backend testing —
-accepting that it's a hygiene boundary and that you'll manually uninstall the
-Apple Container runtime / Homebrew between runs to get back to truly clean.
-
-There is no third, lighter-weight "in-place boundary without a user" that
-actually delivers a clean, wipeable macOS — the VM *is* that answer, and it's
-the better one.
-
-## Harness
-
-The throwaway-user loop is scripted in
-[`scripts/macos-install-test.sh`](../../scripts/macos-install-test.sh):
-`up` creates the account, `run` pipes *this checkout's* `install.sh` into it
-headlessly (so a PR is verifiable before it lands) and lets the installer run
-`doctor`, `down` deletes the account and its home (the full reset), and
-`deep-reset` additionally uninstalls the host `container` runtime. It leans on
-the footprint analysis above — the reset is just user deletion because
-everything `install.sh` writes is user-home-local.
-
-`test` chains `up → run → status → down` into the one-shot cycle you normally
-want:
-
-```sh
-sudo ./scripts/macos-install-test.sh test
-```
-
-It refuses to start against an existing account (a reused home is not a clean
-install), and it tears the account down from an `EXIT`/`INT` trap armed the
-moment the account exists, so a failed or Ctrl-C'd run still leaves the machine
-clean. Its verdict is deliberately stricter than the installer's own: note that
-`install.sh` exits **0** when it finishes but `doctor` reports unmet
-prerequisites, so "the installer succeeded" is not the assertion — `test` fails
-if the install fails, if `bot-bottle` never reached the new user's `PATH`, or if
-`doctor` is unhappy. `BB_TEST_KEEP=1` skips the teardown to poke at a failure.
-
-### What a fresh account actually inherits
-
-Expect the first honest run on a developer Mac to fail at the *Python* gate,
-and expect that to be correct. A new account's `PATH` is just `/etc/paths`
-(`/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin`),
-which notably does **not** include `/opt/homebrew/bin`. Homebrew's `shellenv`
-line lives in the *installing* user's `~/.zprofile` and is not inherited, so a
-throwaway user resolves `python3` to `/usr/bin/python3` — the Command Line
-Tools stub, still **3.9.6** on macOS 26 — and `install.sh` correctly dies on its
-`3.11+` requirement. Your own shell resolving `python3` to a 3.14 Homebrew
-build says nothing about what a new user sees; that gap is exactly what this
-harness exists to expose.
-
-## Sources
-
- [Apple Containers on macOS: technical comparison with Docker — The New Stack](https://thenewstack.io/apple-containers-on-macos-a-technical-comparison-with-docker/)
- [How to Set Up Apple Containerization on macOS 26 — Stéphane Paquet](https://spaquet.medium.com/how-to-set-up-apple-containerization-on-macos-26-f870cc8c26cd)
- [Install Apple Container CLI (macOS 15/26) — 4sysops](https://4sysops.com/archives/install-apple-container-cli-running-containers-natively-on-macos-15-sequoia-and-macos-26-tahoe/)
- [Nested virtualization on Apple Silicon (M3+, macOS 15) — UTM issue #6700](https://github.com/utmapp/UTM/issues/6700)
- [macOS 15 Sequoia nested virtualization for M3+ — Parallels Forums](https://forum.parallels.com/threads/macos-15-sequoia-nested-virtualization-for-m3-macs.364397/)
- [M2 nested virtualization restriction (Apple DTS) — Apple Developer Forums](https://developer.apple.com/forums/thread/756723)
- [M4 can't virtualize older macOS — Yahoo/Tech](https://tech.yahoo.com/computing/articles/m4-mac-computers-cant-virtualize-175122301.html)
- [Tart — macOS/Linux VMs on Apple Silicon (Cirrus Labs)](https://tart.run/quick-start/)
- [Tart GitHub](https://github.com/cirruslabs/tart)
- [macOS VMs in a single command — frr.dev](https://www.frr.dev/posts/tart-macos-vms-from-terminal/)
- [sysadminctl reference — SS64](https://ss64.com/mac/sysadminctl.html)
- [User management from the macOS command line — macnotes](https://macnotes.wordpress.com/2019/03/28/user-management-create-remove-change-password-secure-token-from-macos-command-line/)
@@ -8,20 +8,14 @@
 #   pipx install bot-bottle        # from a checkout or a published index
 #   uv tool install bot-bottle
 #
-# This script is a thin bootstrapper: it finds a Python 3.11+ interpreter,
-# installs the package with pipx (falling back to a private venv), creates the
-# config dir, and runs `bot-bottle doctor`. It is idempotent (safe to re-run)
-# and never uses sudo. It does NOT install Docker or a VM backend for you —
-# `doctor` reports what's missing after install.
-#
-# Env:
-#   BOT_BOTTLE_PYTHON        interpreter to install with (skips the search)
-#   BOT_BOTTLE_INSTALL_SPEC  pip/git spec to install instead of the default
-#   BOT_BOTTLE_VENV          where the non-pipx install lives (~/.bot-bottle/venv)
+# This script is a thin bootstrapper: it checks prerequisites, installs the
+# package with pipx (falling back to pip --user), creates the config dir, and
+# runs `bot-bottle doctor`. It is idempotent (safe to re-run) and never uses
+# sudo. It does NOT install Docker or a VM backend for you — `doctor` reports
+# what's missing after install.
 set -eu

 PACKAGE_SPEC="${BOT_BOTTLE_INSTALL_SPEC:-git+https://gitea.dideric.is/didericis/bot-bottle.git}"
-VENV="${BOT_BOTTLE_VENV:-${HOME}/.bot-bottle/venv}"
 MIN_PYTHON_MAJOR=3
 MIN_PYTHON_MINOR=11

@@ -34,97 +28,17 @@ die() {
    exit 1
 }

-# --- prerequisites: find an interpreter new enough ----------------------------
+# --- prerequisites -----------------------------------------------------------

-# Is $1 an interpreter that exists and meets the floor?
-python_ok() {
-    [ -n "${1:-}" ] || return 1
-    command -v "$1" >/dev/null 2>&1 || return 1
-    "$1" - "$MIN_PYTHON_MAJOR" "$MIN_PYTHON_MINOR" <<'PY' >/dev/null 2>&1
+command -v python3 >/dev/null 2>&1 \
+    || die "python3 ${MIN_PYTHON_MAJOR}.${MIN_PYTHON_MINOR}+ is required but was not found"
+
+python3 - "$MIN_PYTHON_MAJOR" "$MIN_PYTHON_MINOR" <<'PY' || die "python3 ${MIN_PYTHON_MAJOR}.${MIN_PYTHON_MINOR} or newer is required"
 import sys

 want = (int(sys.argv[1]), int(sys.argv[2]))
 raise SystemExit(0 if sys.version_info[:2] >= want else 1)
 PY
-}
-
-python_version() {
-    "$1" -c 'import sys; print("%d.%d.%d" % sys.version_info[:3])' 2>/dev/null
-}
-
-# `python3` on PATH is often NOT the newest interpreter installed, and on macOS
-# it is usually the oldest: a fresh login shell's PATH is just /etc/paths, so
-# python3 resolves to the Command Line Tools stub (3.9.x) while the usable
-# 3.11+ build sits in /opt/homebrew/bin or a python.org framework directory,
-# reachable only via a line in the *installing* user's shell profile. A new
-# account inherits none of that. Look past PATH before giving up, so the common
-# case installs instead of dead-ending on a version error.
-find_python() {
-    for candidate in \
-        "${BOT_BOTTLE_PYTHON:-}" \
-        python3 \
-        python3.14 python3.13 python3.12 python3.11 \
-        /opt/homebrew/bin/python3 \
-        /usr/local/bin/python3 \
-        "${HOME}/.local/bin/python3" \
-        /Library/Frameworks/Python.framework/Versions/*/bin/python3
-    do
-        # An unmatched glob arrives here literally; python_ok rejects it.
-        if python_ok "$candidate"; then
-            command -v "$candidate"
-            return 0
-        fi
-    done
-    return 1
-}
-
-# An explicit choice that doesn't work is an error, not a reason to quietly
-# search elsewhere and install somewhere the caller didn't ask for.
-if [ -n "${BOT_BOTTLE_PYTHON:-}" ] && ! python_ok "${BOT_BOTTLE_PYTHON}"; then
-    if command -v "${BOT_BOTTLE_PYTHON}" >/dev/null 2>&1; then
-        die "BOT_BOTTLE_PYTHON=${BOT_BOTTLE_PYTHON} is $(python_version "${BOT_BOTTLE_PYTHON}"), "\
-"below the ${MIN_PYTHON_MAJOR}.${MIN_PYTHON_MINOR} floor. Unset it to search for a newer one."
-    fi
-    die "BOT_BOTTLE_PYTHON=${BOT_BOTTLE_PYTHON} is not an executable interpreter."
-fi
-
-PYTHON="$(find_python || true)"
-
-if [ -z "${PYTHON}" ]; then
-    path_python="$(command -v python3 2>/dev/null || true)"
-    if [ -n "${path_python}" ]; then
-        found="the python3 on your PATH is ${path_python} ($(python_version "${path_python}")), which is too old"
-    else
-        found="no python3 was found on your PATH"
-    fi
-    case "$(uname -s)" in
-        Darwin) fix="  brew install python@3.12
-  # or install from https://www.python.org/downloads/macos/
-  # macOS itself ships only /usr/bin/python3, which is too old" ;;
-        *) fix="  sudo apt install python3.12    # Debian/Ubuntu
-  sudo dnf install python3.12    # Fedora/RHEL" ;;
-    esac
-    die "bot-bottle needs python3 ${MIN_PYTHON_MAJOR}.${MIN_PYTHON_MINOR} or newer, and none was found.
-  ${found}.
-  Also checked: python3.11-3.14, /opt/homebrew/bin, /usr/local/bin,
-  ~/.local/bin, and python.org framework builds.
-
-Install a newer Python, then re-run this installer:
-${fix}
-
-Already have one somewhere? Point at it directly:
-  BOT_BOTTLE_PYTHON=/path/to/python3 sh install.sh"
-fi
-
-# Be explicit when the interpreter isn't the obvious one, so nobody is left
-# wondering which Python their install ended up on.
-path_python="$(command -v python3 2>/dev/null || true)"
-if [ "${PYTHON}" != "${path_python}" ]; then
-    say "using ${PYTHON} ($(python_version "${PYTHON}"))"
-    if [ -n "${path_python}" ]; then
-        say "note: 'python3' on your PATH is ${path_python} ($(python_version "${path_python}")), which is below the ${MIN_PYTHON_MAJOR}.${MIN_PYTHON_MINOR} floor"
-    fi
-fi

 # Installing a `git+` spec (the default) shells out to git under the hood,
 # whether via pipx or pip. Fail early with a clear message rather than deep
@@ -137,6 +51,30 @@ case "${PACKAGE_SPEC}" in
        ;;
 esac

+# The pip fallback needs a usable pip. Externally-managed interpreters
+# (PEP 668, common on Debian/Ubuntu/Homebrew) reject `pip install --user`;
+# pipx sidesteps that, so recommend it when pip can't be used.
+if ! command -v pipx >/dev/null 2>&1; then
+    python3 -m pip --version >/dev/null 2>&1 || die \
+        "neither pipx nor a usable 'python3 -m pip' was found. Install pipx "\
+"(recommended): 'python3 -m pip install --user pipx' or your OS package manager."
+    if python3 - <<'PY'
+import os
+import sys
+import sysconfig
+
+# PEP 668: an EXTERNALLY-MANAGED marker in the stdlib dir means pip refuses
+# to install into this interpreter without --break-system-packages.
+marker = os.path.join(sysconfig.get_path("stdlib"), "EXTERNALLY-MANAGED")
+raise SystemExit(0 if os.path.exists(marker) else 1)
+PY
+    then
+        die "this Python is externally managed (PEP 668), so 'pip install --user' is "\
+"blocked. Install pipx and re-run: 'python3 -m pip install --user --break-system-packages pipx', "\
+"then 'pipx ensurepath'."
+    fi
+fi
+
 # --- config directories ------------------------------------------------------

 mkdir -p \
@@ -146,50 +84,32 @@ mkdir -p \

 # --- install -----------------------------------------------------------------

-BIN_DIR="${HOME}/.local/bin"
-
 if command -v pipx >/dev/null 2>&1; then
-    # --python pins the venv to the interpreter we vetted. Without it pipx uses
-    # whichever Python it was itself installed with, which is not necessarily
-    # the one that passed the version check above.
-    say "installing with pipx (python: ${PYTHON})"
-    pipx install --python "${PYTHON}" --force "${PACKAGE_SPEC}"
-    # Ask pipx where it puts entry points rather than assuming ~/.local/bin.
-    pipx_bin="$(pipx environment --value PIPX_BIN_DIR 2>/dev/null || true)"
-    [ -n "${pipx_bin}" ] && BIN_DIR="${pipx_bin}"
+    say "installing with pipx"
+    pipx install --force "${PACKAGE_SPEC}"
 else
-    # No `pip install --user` fallback: PEP 668 makes it unusable on nearly
-    # every interpreter a Mac offers (Homebrew and python.org are both
-    # externally managed), and on Debian/Ubuntu too. A private venv sidesteps
-    # that entirely — PEP 668 does not apply inside a venv — and `venv` is
-    # stdlib, so unlike pipx there is nothing to bootstrap first.
-    say "pipx not found; installing into a managed venv at ${VENV}"
-    "${PYTHON}" -m venv --clear "${VENV}" || die \
-        "could not create a virtualenv at ${VENV} using ${PYTHON}. On Debian/Ubuntu "\
-"the venv module ships separately: 'sudo apt install python3-venv'."
-    "${VENV}/bin/python" -m pip install --upgrade "${PACKAGE_SPEC}"
-    # Expose the entry point outside the venv, the way pipx would.
-    mkdir -p "${BIN_DIR}"
-    ln -sf "${VENV}/bin/bot-bottle" "${BIN_DIR}/bot-bottle"
+    say "pipx not found; installing with 'python3 -m pip install --user'"
+    python3 -m pip install --user --upgrade "${PACKAGE_SPEC}"
 fi

 # --- locate the entry point --------------------------------------------------

+# The pip --user scripts directory is platform-specific: ~/.local/bin on Linux,
+# but ~/Library/Python/<X.Y>/bin on a python.org macOS interpreter. Ask the
+# interpreter for its own user-scheme scripts dir instead of hardcoding.
+USER_SCRIPTS="$(python3 - <<'PY'
+import sysconfig
+print(sysconfig.get_path("scripts", sysconfig.get_preferred_scheme("user")))
+PY
+)"
+
 if command -v bot-bottle >/dev/null 2>&1; then
    BOT_BOTTLE_BIN="bot-bottle"
-elif [ -x "${BIN_DIR}/bot-bottle" ]; then
-    BOT_BOTTLE_BIN="${BIN_DIR}/bot-bottle"
-    # Name the file the user's own login shell actually reads. ~/.profile is
-    # the safe default for non-zsh: bash falls back to it, and suggesting
-    # ~/.bash_profile could shadow an existing ~/.profile.
-    case "${SHELL:-}" in
-        */zsh) profile="~/.zprofile" ;;
-        *) profile="~/.profile" ;;
-    esac
-    say "note: add ${BIN_DIR} to your PATH to run 'bot-bottle' directly:"
-    say "    echo 'export PATH=\"${BIN_DIR}:\$PATH\"' >> ${profile}"
+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 no entry point turned up in ${BIN_DIR}"
+    die "bot-bottle was installed but is not on PATH; add ${USER_SCRIPTS:-your user scripts dir} to PATH and re-run"
 fi

 # --- verify ------------------------------------------------------------------
@@ -1,294 +0,0 @@
-#!/usr/bin/env bash
-# Clean-install test harness for the macOS (Apple `container`) path.
-#
-# Exercises install.sh the way a brand-new user would, inside a throwaway
-# macOS account you create and delete from the CLI. install.sh's entire
-# footprint is user-home-local — the pipx venv under ~/.local, or the private
-# venv at ~/.bot-bottle/venv plus a ~/.local/bin symlink, and the ~/.bot-bottle
-# config dir. It writes no shell-profile PATH line, and never installs the
-# backend (see
-# the header of install.sh), so deleting the user is a complete,
-# deterministic reset of everything the installer touched. The Apple
-# `container` runtime is a HOST prerequisite installed once and kept;
-# `deep-reset` is the rare escape hatch that also removes it.
-#
-# Why a throwaway user and not a disposable VM: bot-bottle's default macOS
-# backend is Apple `container`, which runs each container in its own
-# Virtualization.framework microVM. Running that backend inside a macOS
-# guest VM needs nested virtualization, which Apple gates to M3+ silicon.
-# On M1/M2 a separate user account is the only way to get a clean $HOME
-# while still reaching the real host backend. Full rationale in
-# docs/research/testing-clean-install-on-macos.md.
-#
-# Usage:
-#   sudo ./scripts/macos-install-test.sh test        # up -> run -> status -> down
-#   sudo ./scripts/macos-install-test.sh up          # create the throwaway user
-#   sudo ./scripts/macos-install-test.sh run         # run install.sh (+doctor) as it
-#        ./scripts/macos-install-test.sh status      # user present? backend ready?
-#   sudo ./scripts/macos-install-test.sh down        # delete user + home (the reset)
-#   sudo ./scripts/macos-install-test.sh deep-reset  # ALSO uninstall host `container`
-#
-# `test` is the one-shot clean cycle and the command you normally want: it
-# refuses to start if the account already exists (a reused home is not a clean
-# install), and it tears the account down on the way out however it exits, so
-# a failed run never leaves an orphan behind. It exits non-zero if the install
-# fails, if `bot-bottle` is missing from the new user's PATH, or if `doctor`
-# reports unmet prerequisites — note install.sh itself exits 0 in that last
-# case, so `test` is a stricter gate than running the installer by hand.
-#
-# Config via env:
-#   BB_TEST_USER         account short name             (default: bbtest)
-#   BB_TEST_FULLNAME     account full name              (default: "bot-bottle install test")
-#   BB_TEST_ADMIN        1=admin (reach container svc), 0=standard  (default: 1)
-#   BB_TEST_INSTALL_URL  curl this install.sh instead of piping the local checkout
-#   BB_TEST_KEEP         1=`test` skips its teardown, to poke at a failure
-#   BOT_BOTTLE_INSTALL_SPEC   passed through to install.sh (pip / git spec)
-#
-# Notes:
-#   * Run from a normally-booted admin session. Grant Terminal *Full Disk
-#     Access* (System Settings -> Privacy & Security) or `down` half-fails
-#     with error -14120 and leaves an orphaned account.
-#   * `sysadminctl` always exits 0 even on failure, so `up`/`down` verify
-#     the result with `dscl` and fail loudly on a mismatch.
-#   * The account is created without a password: `run` drives it headlessly
-#     via `sudo -u`, which never needs the target's password. The account
-#     cannot GUI-login, which this harness does not require.
-#   * `run` covers the installer + `bot-bottle doctor`. Actually launching a
-#     bottle from the throwaway user may need a full launchd user session
-#     (`launchctl asuser`); on M1/M2 the backend can't run under nested virt
-#     anyway, so this harness stops at install + doctor.
-
-set -euo pipefail
-
-USER_NAME="${BB_TEST_USER:-bbtest}"
-FULL_NAME="${BB_TEST_FULLNAME:-bot-bottle install test}"
-ADMIN="${BB_TEST_ADMIN:-1}"
-
-_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-_REPO_ROOT="$(cd "$_SCRIPT_DIR/.." && pwd)"
-
-# Set by `test`, which chains the steps itself and so suppresses the
-# "here's the next command to run" hints the individual steps print.
-IN_TEST=0
-
-# --- guards ----------------------------------------------------------
-require_macos() {
-    [ "$(uname -s)" = "Darwin" ] \
-        || { echo "error: this harness is macOS-only (uname is $(uname -s))" >&2; exit 1; }
-}
-
-require_root() {
-    if [ "$(id -u)" -ne 0 ]; then
-        echo "error: '$1' needs root; re-run under sudo" >&2
-        exit 1
-    fi
-}
-
-user_exists() { dscl . -read "/Users/$USER_NAME" >/dev/null 2>&1; }
-
-# Run a shell snippet as the throwaway user in a fresh login shell.
-run_as_user() { sudo -u "$USER_NAME" -i sh -c "$1"; }
-
-# `bot-bottle doctor` as the throwaway user. Non-zero when no entry point was
-# installed at all, or when doctor itself is unhappy.
-#
-# Deliberately does NOT require `bot-bottle` on PATH: install.sh prints the
-# PATH line rather than editing a shell profile, so on a fresh account the
-# entry point is installed and working but not on PATH. Demanding PATH here
-# would fail every run for a reason the installer intends.
-doctor_as_user() {
-    # shellcheck disable=SC2016  # $HOME/$bb must expand in the *target* user's
-    # shell, not in this one — that's the whole point of the single quotes.
-    run_as_user '
-        for bb in "$HOME/.local/bin/bot-bottle" "$HOME/.bot-bottle/venv/bin/bot-bottle"; do
-            if [ -x "$bb" ]; then
-                command -v bot-bottle >/dev/null 2>&1 \
-                    || echo "  (not on PATH — running $bb directly, as install.sh advises)"
-                exec "$bb" doctor
-            fi
-        done
-        command -v bot-bottle >/dev/null 2>&1 && exec bot-bottle doctor
-        echo "  no bot-bottle entry point found for this user" >&2
-        exit 1
-    '
-}
-
-# --- commands --------------------------------------------------------
-cmd_up() {
-    require_macos
-    require_root up
-    if user_exists; then
-        echo "$USER_NAME already exists; nothing to do (run 'down' first to reset)"
-        return 0
-    fi
-    local admin_flag=()
-    [ "$ADMIN" = "1" ] && admin_flag=(-admin)
-    # No -password: the account is only ever driven headlessly via `sudo -u`,
-    # which doesn't need one. sysadminctl warns about FileVault here; that's
-    # irrelevant to a headless test account.
-    sysadminctl -addUser "$USER_NAME" -fullName "$FULL_NAME" "${admin_flag[@]}" || true
-    # sysadminctl exits 0 regardless of outcome, so confirm the account landed.
-    user_exists || { echo "error: failed to create $USER_NAME" >&2; return 1; }
-    if [ "$IN_TEST" = 1 ]; then
-        echo "created $USER_NAME (admin=$ADMIN)"
-    else
-        echo "created $USER_NAME (admin=$ADMIN). Install into it with: sudo $0 run"
-    fi
-}
-
-cmd_run() {
-    require_macos
-    require_root run
-    user_exists || { echo "error: $USER_NAME does not exist; run 'sudo $0 up' first" >&2; return 1; }
-
-    local spec_env=""
-    [ -n "${BOT_BOTTLE_INSTALL_SPEC:-}" ] \
-        && spec_env="BOT_BOTTLE_INSTALL_SPEC='$BOT_BOTTLE_INSTALL_SPEC' "
-
-    echo "== installing bot-bottle as $USER_NAME =="
-    if [ -n "${BB_TEST_INSTALL_URL:-}" ]; then
-        run_as_user "curl -fsSL '$BB_TEST_INSTALL_URL' | ${spec_env}sh"
-    else
-        # Test THIS checkout's install.sh, not the published one, so a PR is
-        # verifiable before it lands. Feed it in on stdin rather than staging a
-        # copy somewhere the throwaway user can read: the redirect is opened by
-        # root before sudo drops privileges, so the tester's mode-700 home is a
-        # non-issue, there's no temp file to leak if the run is interrupted, and
-        # `sh -s` is the same shape as the documented `curl … | sh` install.
-        run_as_user "${spec_env}sh -s" < "$_REPO_ROOT/install.sh"
-    fi
-    [ "$IN_TEST" = 1 ] \
-        || echo "== install.sh runs 'doctor' itself; re-check anytime with: $0 status =="
-}
-
-# Informational, with one teeth-bearing case: when it can actually reach
-# doctor (root, account present) its exit status is doctor's, so `test` and
-# any other caller can use it as the post-install assertion.
-cmd_status() {
-    require_macos
-    local rc=0
-    if user_exists; then
-        echo "user:    $USER_NAME present"
-        if [ "$(id -u)" -eq 0 ]; then
-            echo "doctor (as $USER_NAME):"
-            doctor_as_user || rc=1
-        else
-            echo "  (re-run under sudo to run 'bot-bottle doctor' as $USER_NAME)"
-        fi
-    else
-        echo "user:    $USER_NAME absent"
-    fi
-    if command -v container >/dev/null 2>&1; then
-        echo "backend: apple 'container' present ($(container --version 2>/dev/null | head -1))"
-    else
-        echo "backend: apple 'container' NOT on PATH (host prerequisite; install once)"
-    fi
-    return "$rc"
-}
-
-cmd_down() {
-    require_macos
-    require_root down
-    if ! user_exists; then
-        echo "$USER_NAME not present; nothing to remove"
-        return 0
-    fi
-    # A plain -deleteUser removes the home dir, which is the whole reset.
-    # -secure is a no-op on modern macOS (secure erase of the home folder
-    # was removed in Sierra), so it buys nothing here.
-    sysadminctl -deleteUser "$USER_NAME" || true
-    if user_exists; then
-        echo "error: $USER_NAME still present after delete." >&2
-        echo "  - grant Terminal Full Disk Access (System Settings > Privacy & Security), or" >&2
-        echo "  - it may hold the last Secure Token (won't happen while another admin exists)" >&2
-        return 1
-    fi
-    echo "removed $USER_NAME and its home — install surface is clean."
-}
-
-# Teardown half of `test`, installed as an EXIT trap the moment the account
-# exists so that a failure — or a Ctrl-C — still leaves the machine clean.
-_test_teardown() {
-    local rc=$?
-    trap - EXIT INT TERM
-    if [ "${BB_TEST_KEEP:-0}" = "1" ]; then
-        echo
-        echo "== [4/4] down: SKIPPED (BB_TEST_KEEP=1) =="
-        echo "   $USER_NAME is still around; remove it with: sudo $0 down"
-        exit "$rc"
-    fi
-    echo
-    echo "== [4/4] down =="
-    cmd_down || rc=1
-    if [ "$rc" -eq 0 ]; then
-        echo
-        echo "PASS: a brand-new user can install bot-bottle and pass doctor."
-    else
-        echo
-        echo "FAIL: see above (the throwaway account was torn down regardless)." >&2
-    fi
-    exit "$rc"
-}
-
-cmd_test() {
-    require_macos
-    require_root test
-    # A pre-existing account means a pre-existing home, which is the one thing
-    # this harness exists to rule out. Don't silently test a dirty install.
-    if user_exists; then
-        echo "error: $USER_NAME already exists, so this would not be a clean install." >&2
-        echo "  reset first:  sudo $0 down" >&2
-        return 1
-    fi
-    IN_TEST=1
-
-    echo "== [1/4] up =="
-    cmd_up
-    trap _test_teardown EXIT INT TERM
-
-    echo
-    echo "== [2/4] run =="
-    cmd_run
-
-    echo
-    echo "== [3/4] status =="
-    # install.sh exits 0 even when doctor reports unmet prerequisites, so the
-    # install succeeding is not the verdict — this is.
-    cmd_status || {
-        echo "error: doctor is unhappy for a freshly installed user (see above)." >&2
-        echo "  re-run with BB_TEST_KEEP=1 to keep $USER_NAME around and dig in." >&2
-        return 1
-    }
-}
-
-cmd_deep_reset() {
-    require_macos
-    require_root deep-reset
-    # Remove the user first (idempotent), then the HOST-level container
-    # runtime that a user deletion leaves behind under /usr/local + launchd.
-    cmd_down || true
-    if command -v container >/dev/null 2>&1; then
-        # The service can run in more than one launchd context (the invoking
-        # user's and root's), so stop both, best-effort.
-        [ -n "${SUDO_USER:-}" ] && sudo -u "$SUDO_USER" container system stop 2>/dev/null || true
-        container system stop 2>/dev/null || true
-        if [ -x /usr/local/bin/uninstall-container.sh ]; then
-            /usr/local/bin/uninstall-container.sh -d || true
-            echo "uninstalled the host Apple 'container' runtime"
-        else
-            echo "note: /usr/local/bin/uninstall-container.sh not found; runtime left as-is" >&2
-        fi
-    else
-        echo "no 'container' runtime on PATH; nothing further to remove"
-    fi
-}
-
-case "${1:-}" in
-    test) cmd_test ;;
-    up) cmd_up ;;
-    run) cmd_run ;;
-    status) cmd_status ;;
-    down) cmd_down ;;
-    deep-reset) cmd_deep_reset ;;
-    *) echo "usage: $0 {test|up|run|status|down|deep-reset}" >&2 ; exit 2 ;;
-esac
@@ -18,6 +18,7 @@ from bot_bottle.backend.docker.compose import (
    list_compose_projects,
    slug_from_compose_project,
 )
+from bot_bottle.backend import EnumerationError


 class TestProjectNaming(unittest.TestCase):
@@ -43,17 +44,6 @@ class TestProjectNaming(unittest.TestCase):


 class TestComposeProjectListing(unittest.TestCase):
-    def test_compose_ls_empty_when_docker_unusable(self):
-        # Missing is the obvious case; present-but-not-executable raises
-        # PermissionError instead, which must not escape as a crash.
-        for exc in (FileNotFoundError, PermissionError(13, "Permission denied", "docker")):
-            with self.subTest(exc=type(exc).__name__):
-                with mock.patch(
-                    "bot_bottle.backend.docker.compose.subprocess.run",
-                    side_effect=exc,
-                ):
-                    self.assertEqual([], list_compose_projects())
-
    def test_compose_ls_error_warns_by_default(self):
        with (
            mock.patch(
@@ -80,6 +70,19 @@ class TestComposeProjectListing(unittest.TestCase):
            self.assertEqual([], list_active_slugs(warn_on_error=False))
        warn.assert_not_called()

+    def test_compose_ls_error_can_be_raised_for_enumeration(self):
+        with mock.patch(
+            "bot_bottle.backend.docker.compose.subprocess.run",
+            return_value=subprocess.CompletedProcess(
+                args=["docker"], returncode=1, stdout="", stderr="no daemon",
+            ),
+        ):
+            with self.assertRaisesRegex(EnumerationError, "no daemon"):
+                list_active_slugs(
+                    warn_on_error=False,
+                    raise_on_error=True,
+                )
+

 if __name__ == "__main__":
    unittest.main()
@@ -7,6 +7,8 @@ from pathlib import Path
 from unittest.mock import MagicMock, Mock, patch

 from bot_bottle.backend.docker.consolidated_launch import (
+    ConsolidatedLaunchError,
+    _network_container_ips,
    launch_consolidated,
    deprovision_consolidated,
 )
@@ -86,6 +88,16 @@ class TestLaunchConsolidated(unittest.TestCase):
        client.teardown_bottle.assert_called_once_with("b1")  # no orphan left


+class TestNetworkContainerIps(unittest.TestCase):
+    def test_fails_closed_when_network_inspection_fails(self) -> None:
+        result = Mock(returncode=1, stdout="", stderr="daemon unavailable")
+        with (
+            patch(f"{_MOD}.run_docker", return_value=result),
+            self.assertRaisesRegex(ConsolidatedLaunchError, "daemon unavailable"),
+        ):
+            _network_container_ips("bot-bottle-gateway")
+
+
 class TestTeardownConsolidated(unittest.TestCase):
    def test_deregisters_and_deprovisions(self) -> None:
        client = Mock()
@@ -19,13 +19,16 @@ of issue #77 — the dashboard now delegates to this layer.

 from __future__ import annotations

+import subprocess
 import tempfile
 import unittest
 from pathlib import Path
+from unittest.mock import patch

 from tests.unit import use_bottle_root
 from bot_bottle import bottle_state
 from bot_bottle.backend.docker import enumerate as _enumerate
+from bot_bottle.backend import EnumerationError


 class TestParseServicesByProject(unittest.TestCase):
@@ -72,6 +75,18 @@ class TestParseServicesByProject(unittest.TestCase):
        self.assertEqual({"bot-bottle-dev-abc": {"egress"}}, out)


+class TestQueryServicesByProject(unittest.TestCase):
+    def test_docker_ps_failure_is_not_an_empty_result(self):
+        with patch(
+            "bot_bottle.backend.docker.enumerate.subprocess.run",
+            return_value=subprocess.CompletedProcess(
+                args=["docker"], returncode=1, stdout="", stderr="daemon down",
+            ),
+        ):
+            with self.assertRaisesRegex(EnumerationError, "daemon down"):
+                _enumerate._query_services_by_project()
+
+
 class _FakeHomeMixin:
    def _setup_fake_home(self) -> None:
        self._tmp = tempfile.TemporaryDirectory(prefix="enum-active.")
@@ -15,6 +15,7 @@ import unittest
 from pathlib import Path
 from unittest.mock import patch

+from bot_bottle.backend import EnumerationError
 from bot_bottle.backend.firecracker import cleanup as fc_cleanup
 from bot_bottle.backend.firecracker.bottle_cleanup_plan import (
    FirecrackerBottleCleanupPlan,
@@ -58,10 +59,37 @@ class TestProcessScan(unittest.TestCase):
        self.assertEqual({str(run_root / "live-a")}, live)
        self.assertEqual([222], orphan_pids)

-    def test_scan_empty_when_pgrep_fails(self):
+    def test_scan_empty_when_pgrep_finds_no_processes(self):
        with patch.object(fc_cleanup.subprocess, "run", return_value=_proc(returncode=1)):
            self.assertEqual((set(), []), fc_cleanup._scan_processes(Path("/x")))

+    def test_scan_raises_when_pgrep_errors(self):
+        proc = subprocess.CompletedProcess(
+            [], 2, stdout="", stderr="invalid process expression",
+        )
+        with (
+            patch.object(fc_cleanup.subprocess, "run", return_value=proc),
+            self.assertRaisesRegex(EnumerationError, "invalid process expression"),
+        ):
+            fc_cleanup._scan_processes(Path("/x"))
+
+    def test_prepare_cleanup_does_not_plan_deletions_when_scan_errors(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            run_root = Path(tmp)
+            live = run_root / "live-a"
+            live.mkdir()
+            with (
+                patch.object(fc_cleanup, "_run_root", return_value=run_root),
+                patch.object(
+                    fc_cleanup.subprocess,
+                    "run",
+                    return_value=_proc(returncode=2),
+                ),
+                self.assertRaises(EnumerationError),
+            ):
+                fc_cleanup.prepare_cleanup()
+            self.assertTrue(live.is_dir())
+
    def test_live_run_dirs_returns_paths_in_stable_order(self):
        with patch.object(fc_cleanup, "_run_root", return_value=Path("/run")), \
             patch.object(fc_cleanup, "_scan_processes",
@@ -0,0 +1,64 @@
+"""Unit tests for Firecracker active-agent enumeration."""
+
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from bot_bottle.backend import EnumerationError
+from bot_bottle.backend.firecracker import enumerate as fc_enumerate
+from bot_bottle.bottle_state import BottleMetadata
+
+
+class TestEnumerateActive(unittest.TestCase):
+    def test_maps_live_run_dirs_to_active_agents(self) -> None:
+        metadata = BottleMetadata(
+            identity="dev-a",
+            agent_name="claude",
+            cwd="",
+            copy_cwd=False,
+            started_at="2026-07-26T12:00:00Z",
+            label="review",
+            color="blue",
+        )
+        with (
+            patch.object(
+                fc_enumerate, "live_run_dirs",
+                return_value=(Path("/cache/run/dev-a"),),
+            ),
+            patch.object(fc_enumerate, "read_metadata", return_value=metadata),
+        ):
+            agents = fc_enumerate.enumerate_active()
+        self.assertEqual(1, len(agents))
+        self.assertEqual("firecracker", agents[0].backend_name)
+        self.assertEqual("dev-a", agents[0].slug)
+        self.assertEqual("claude", agents[0].agent_name)
+        self.assertEqual("review", agents[0].label)
+        self.assertEqual((), agents[0].services)
+
+    def test_missing_metadata_uses_safe_defaults(self) -> None:
+        with (
+            patch.object(
+                fc_enumerate, "live_run_dirs",
+                return_value=(Path("/cache/run/dev-a"),),
+            ),
+            patch.object(fc_enumerate, "read_metadata", return_value=None),
+        ):
+            agent = fc_enumerate.enumerate_active()[0]
+        self.assertEqual("?", agent.agent_name)
+        self.assertEqual("", agent.started_at)
+
+    def test_process_scan_failure_propagates(self) -> None:
+        with (
+            patch.object(
+                fc_enumerate, "live_run_dirs",
+                side_effect=EnumerationError("pgrep failed"),
+            ),
+            self.assertRaisesRegex(EnumerationError, "pgrep failed"),
+        ):
+            fc_enumerate.enumerate_active()
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -56,21 +56,6 @@ class TestNetpoolProbes(unittest.TestCase):
        with patch.object(netpool.subprocess, "run", side_effect=FileNotFoundError):
            self.assertFalse(netpool._run_ok(["nft"]))

-    def test_run_ok_false_on_unexecutable_binary(self):
-        # A name on PATH that this user can't execute raises PermissionError,
-        # not FileNotFoundError — CPython reports that EACCES in preference to
-        # the ENOENT from the other PATH entries. Catching only the latter made
-        # `doctor` die with a traceback on a fresh macOS account.
-        with patch.object(netpool.subprocess, "run",
-                          side_effect=PermissionError(13, "Permission denied", "ip")):
-            self.assertFalse(netpool._run_ok(["ip", "link", "show", "bbfc0"]))
-
-    def test_overlapping_routes_empty_when_ip_unusable(self):
-        for exc in (FileNotFoundError, PermissionError(13, "Permission denied", "ip")):
-            with self.subTest(exc=type(exc).__name__), \
-                 patch.object(netpool.subprocess, "run", side_effect=exc):
-                self.assertEqual([], netpool.overlapping_routes())
-
    def test_tap_and_nft_probes(self):
        with patch.object(netpool, "_run_ok", return_value=True) as ok:
            self.assertTrue(netpool.tap_present("bbfc0"))
@@ -9,7 +9,7 @@ create the config tree, install the package, and verify with `doctor`.
 from __future__ import annotations

 import os
-import re
+import sysconfig
 import unittest
 from pathlib import Path

@@ -17,22 +17,6 @@ REPO_ROOT = Path(__file__).resolve().parents[2]
 INSTALL_SH = REPO_ROOT / "install.sh"


-def code_only(text: str) -> str:
-    """Script text with string literals and comments removed.
-
-    Both are places the script *talks about* commands rather than running
-    them — remediation advice quite reasonably says "sudo apt install …" —
-    so assertions about what the script actually executes must not see them.
-    Strings are stripped before comments because a '#' inside a quoted string
-    is not a comment, and several literals here span multiple lines.
-    """
-    without_strings = re.sub(r"\"(?:[^\"\\]|\\.)*\"|'[^']*'", "", text)
-    return "\n".join(
-        ln for ln in without_strings.splitlines()
-        if ln.strip() and not ln.lstrip().startswith("#")
-    )
-
-
 class TestInstallScript(unittest.TestCase):
    @classmethod
    def setUpClass(cls):
@@ -48,45 +32,20 @@ class TestInstallScript(unittest.TestCase):
        self.assertIn("set -eu", self.text)

    def test_never_uses_sudo(self):
-        # The installer must never *invoke* sudo. It may print it: the "no
-        # usable python" error suggests 'sudo apt install python3.12'.
-        self.assertNotIn("sudo", code_only(self.text))
+        # Only executable lines matter; the header comment may mention sudo.
+        code = [
+            ln for ln in self.text.splitlines()
+            if ln.strip() and not ln.lstrip().startswith("#")
+        ]
+        self.assertNotIn("sudo", "\n".join(code))

    def test_creates_config_tree(self):
        self.assertIn(".bot-bottle/agents", self.text)
        self.assertIn(".bot-bottle/bottles", self.text)

-    def test_installs_via_pipx_with_venv_fallback(self):
+    def test_installs_via_pipx_with_pip_fallback(self):
        self.assertIn("pipx install", self.text)
-        self.assertIn("-m venv", self.text)
-
-    def test_no_pip_user_fallback(self):
-        # `pip install --user` is not a fallback, it's a dead end: PEP 668
-        # blocks it on Homebrew, python.org and Debian/Ubuntu interpreters,
-        # which is every Python a Mac realistically offers. A private venv is
-        # exempt from PEP 668 and needs no bootstrap, since venv is stdlib.
-        # code_only, because the comment explaining the absence says the words.
-        code = code_only(self.text)
-        self.assertNotIn("pip install --user", code)
-        self.assertNotIn("--break-system-packages", code)
-
-    def test_venv_lives_under_the_config_dir(self):
-        # Keeps the whole install footprint inside ~/.bot-bottle (plus the
-        # entry-point symlink), which is what makes deleting a throwaway
-        # account a complete reset in scripts/macos-install-test.sh.
-        self.assertIn(".bot-bottle/venv", self.text)
-        self.assertIn("BOT_BOTTLE_VENV", self.text)
-
-    def test_venv_failure_is_actionable(self):
-        # Debian/Ubuntu ship venv separately; failing there must say so rather
-        # than dumping ensurepip's error.
-        self.assertIn("python3-venv", self.text)
-
-    def test_entry_point_is_exposed_outside_the_venv(self):
-        # A venv's bin dir is never on PATH, so the console script has to be
-        # linked somewhere conventional or `bot-bottle` is unreachable.
-        self.assertIn(".local/bin", self.text)
-        self.assertIn("ln -sf", self.text)
+        self.assertIn("pip install --user", self.text)

    def test_runs_doctor_after_install(self):
        self.assertIn("doctor", self.text)
@@ -101,43 +60,42 @@ class TestInstallScript(unittest.TestCase):
        self.assertIn("command -v git", self.text)
        self.assertIn("git+*|*.git", self.text)

-    def test_installs_into_the_venv_with_its_own_pip(self):
-        # The venv's pip, not the base interpreter's — the base one may not
-        # exist, and using it would install outside the venv.
-        self.assertIn("${VENV}/bin/python\" -m pip install", self.text)
+    def test_checks_pip_usable_before_fallback(self):
+        self.assertIn("python3 -m pip --version", self.text)

-    def test_pipx_is_preferred_when_present(self):
-        # The venv is a fallback, not a takeover: someone who already manages
-        # their Python apps with pipx keeps doing so.
-        self.assertIn("command -v pipx", self.text)
+    def test_detects_externally_managed_python(self):
+        # PEP 668: 'pip install --user' is blocked on externally-managed
+        # interpreters; the script must detect this and point at pipx.
+        self.assertIn("EXTERNALLY-MANAGED", self.text)
+        self.assertIn("pipx", self.text)

-    def test_asks_pipx_where_its_bin_dir_is(self):
-        # PIPX_BIN_DIR is configurable, so the post-install "is it on PATH?"
-        # check must ask rather than assume ~/.local/bin.
-        self.assertIn("PIPX_BIN_DIR", 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_searches_beyond_path_for_an_interpreter(self):
-        # `python3` on PATH is the *oldest* interpreter on a stock Mac: a fresh
-        # account's PATH is /etc/paths, so python3 is the 3.9.6 CLT stub while
-        # the usable build sits somewhere only a shell profile puts on PATH.
-        # Giving up at that point dead-ends every new macOS user.
-        for candidate in ("python3.11", "/opt/homebrew/bin", "Python.framework"):
-            self.assertIn(candidate, self.text)
+    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)

-    def test_interpreter_is_overridable(self):
-        self.assertIn("BOT_BOTTLE_PYTHON", self.text)
-
-    def test_pipx_is_pinned_to_the_vetted_interpreter(self):
-        # Without --python, pipx builds the venv with whichever interpreter
-        # pipx itself was installed with, which need not be the one that
-        # passed the version check.
-        self.assertIn("pipx install --python", self.text)
-
-    def test_version_failure_is_actionable(self):
-        # The failure a new macOS user actually hits must say what to do about
-        # it, not just state the requirement.
-        self.assertIn("brew install python@", self.text)
-        self.assertIn("BOT_BOTTLE_PYTHON=/path/to/python3", self.text)

 if __name__ == "__main__":
    unittest.main()
@@ -5,6 +5,7 @@ from __future__ import annotations
 import unittest
 from unittest.mock import patch

+from bot_bottle.backend import EnumerationError
 from bot_bottle.backend.macos_container import cleanup, enumerate as enum_mod
 from bot_bottle.backend.macos_container.bottle_cleanup_plan import (
    MacosContainerBottleCleanupPlan,
@@ -69,10 +70,18 @@ class TestMacosContainerEnumerate(unittest.TestCase):
        self.assertEqual(["dev-abc"], [a.slug for a in agents])

    def test_raises_when_the_cli_fails(self):
-        from bot_bottle.backend.macos_container.enumerate import EnumerationError
        with self.assertRaises(EnumerationError):
            self._enumerate("", returncode=1)

+    def test_raises_typed_error_when_cli_is_missing(self):
+        with (
+            patch.object(
+                enum_mod.subprocess, "run", side_effect=FileNotFoundError,
+            ),
+            self.assertRaisesRegex(EnumerationError, "CLI not found"),
+        ):
+            enum_mod.enumerate_active()
+

 if __name__ == "__main__":
    unittest.main()
@@ -2,6 +2,9 @@

 from __future__ import annotations

+import base64
+import hashlib
+import hmac
 import unittest

 from bot_bottle.orchestrator.store.secret_store import (
@@ -68,15 +71,28 @@ class TestDecryptErrors(unittest.TestCase):
    def test_wrong_key_raises_value_error(self) -> None:
        ct = encrypt_value(self.secret, "secret-token")
        other_key = new_env_var_secret()
-        # Wrong key produces garbage bytes; decrypt_value raises ValueError
-        # when the result is non-UTF-8 (which is very likely for 12-char data).
-        # We allow it to succeed only if garbage happens to be valid UTF-8, but
-        # the plaintext must not match.
-        try:
-            result = decrypt_value(other_key, ct)
-            self.assertNotEqual("secret-token", result)
-        except ValueError:
-            pass
+        with self.assertRaisesRegex(ValueError, "authentication failed"):
+            decrypt_value(other_key, ct)
+
+    def test_tampered_ciphertext_raises_value_error(self) -> None:
+        raw = bytearray(base64.urlsafe_b64decode(
+            encrypt_value(self.secret, "secret-token") + "=="
+        ))
+        raw[22] ^= 1
+        tampered = base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
+        with self.assertRaisesRegex(ValueError, "authentication failed"):
+            decrypt_value(self.secret, tampered)
+
+    def test_reads_legacy_ciphertext_for_migration(self) -> None:
+        key = base64.urlsafe_b64decode(self.secret + "==")
+        nonce = b"0123456789abcdef"
+        plaintext = b"legacy-token"
+        stream = hmac.new(
+            key, nonce + (0).to_bytes(4, "big"), hashlib.sha256,
+        ).digest()
+        ciphertext = bytes(p ^ k for p, k in zip(plaintext, stream))
+        legacy = base64.urlsafe_b64encode(nonce + ciphertext).rstrip(b"=").decode()
+        self.assertEqual("legacy-token", decrypt_value(self.secret, legacy))

    def test_truncated_blob_raises_value_error(self) -> None:
        with self.assertRaises(ValueError):
@@ -7,6 +7,7 @@ server tests), plus one real-socket round-trip to prove the handler wiring.
 from __future__ import annotations

 import base64
+import http.client
 import io
 import json
 import secrets
@@ -22,7 +23,7 @@ from unittest.mock import MagicMock, patch

 from bot_bottle.orchestrator_auth import ROLE_CLI, ROLE_GATEWAY, mint
 from bot_bottle.orchestrator.broker import StubBroker
-from bot_bottle.orchestrator.server import dispatch, make_server
+from bot_bottle.orchestrator.server import MAX_BODY_BYTES, dispatch, make_server
 from bot_bottle.orchestrator.store.registry_store import BottleRecord, RegistryStore
 from bot_bottle.orchestrator.service import OrchestratorCore
 from bot_bottle.orchestrator.store.store_manager import StoreManager
@@ -251,11 +252,51 @@ class TestDispatch(unittest.TestCase):


 class TestServerRoundTrip(unittest.TestCase):
+    def _raw_status(self, content_length: str, *, authenticated: bool = True) -> int:
+        tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(tmp.cleanup)
+        key = "request-limits-key"
+        server = make_server(
+            _orchestrator(Path(tmp.name) / "r.db"),
+            "127.0.0.1", 0, signing_key=key,
+        )
+        self.addCleanup(server.server_close)
+        threading.Thread(target=server.serve_forever, daemon=True).start()
+        self.addCleanup(server.shutdown)
+        conn = http.client.HTTPConnection(
+            str(server.server_address[0]), server.server_address[1], timeout=5,
+        )
+        self.addCleanup(conn.close)
+        conn.putrequest("POST", "/bottles")
+        conn.putheader("Content-Length", content_length)
+        if authenticated:
+            conn.putheader(
+                "x-bot-bottle-orchestrator-auth", mint(ROLE_CLI, key),
+            )
+        conn.endheaders()
+        return conn.getresponse().status
+
+    def test_rejects_malformed_content_length(self) -> None:
+        self.assertEqual(400, self._raw_status("not-a-number"))
+
+    def test_rejects_oversized_body_without_reading_it(self) -> None:
+        self.assertEqual(413, self._raw_status(str(MAX_BODY_BYTES + 1)))
+
+    def test_rejects_unauthenticated_request_before_reading_body(self) -> None:
+        self.assertEqual(
+            401,
+            self._raw_status(str(MAX_BODY_BYTES), authenticated=False),
+        )
+
    def test_http_register_health_attribute(self) -> None:
        tmp = tempfile.TemporaryDirectory()
        self.addCleanup(tmp.cleanup)
        orch = _orchestrator(Path(tmp.name) / "r.db")
-        server = make_server(orch, "127.0.0.1", 0)
+        signing_key = "round-trip-key"
+        auth = mint(ROLE_CLI, signing_key)
+        server = make_server(
+            orch, "127.0.0.1", 0, signing_key=signing_key,
+        )
        self.addCleanup(server.server_close)
        thread = threading.Thread(target=server.serve_forever, daemon=True)
        thread.start()
@@ -267,7 +308,10 @@ class TestServerRoundTrip(unittest.TestCase):
        reg = json.load(urllib.request.urlopen(
            urllib.request.Request(
                f"{base}/bottles", data=_body({"source_ip": "10.243.0.7"}),
-                method="POST", headers={"Content-Type": "application/json"},
+                method="POST", headers={
+                    "Content-Type": "application/json",
+                    "x-bot-bottle-orchestrator-auth": auth,
+                },
            ), timeout=5,
        ))
        self.assertTrue(reg["bottle_id"])
@@ -279,7 +323,10 @@ class TestServerRoundTrip(unittest.TestCase):
            urllib.request.Request(
                f"{base}/attribute",
                data=_body({"source_ip": "10.243.0.7", "identity_token": reg["identity_token"]}),
-                method="POST", headers={"Content-Type": "application/json"},
+                method="POST", headers={
+                    "Content-Type": "application/json",
+                    "x-bot-bottle-orchestrator-auth": auth,
+                },
            ), timeout=5,
        ))
        self.assertEqual(reg["bottle_id"], attr["bottle_id"])
@@ -287,15 +334,25 @@ class TestServerRoundTrip(unittest.TestCase):
    def test_internal_failure_is_contextual_but_redacted(self) -> None:
        orch = MagicMock()
        orch.registry.all.side_effect = RuntimeError("SENSITIVE request value")
+        signing_key = "failure-path-key"
+        auth = mint(ROLE_CLI, signing_key)
        with patch("sys.stderr", io.StringIO()) as stderr:
-            server = make_server(orch, "127.0.0.1", 0)
+            server = make_server(
+                orch, "127.0.0.1", 0, signing_key=signing_key,
+            )
            self.addCleanup(server.server_close)
            thread = threading.Thread(target=server.serve_forever, daemon=True)
            thread.start()
            self.addCleanup(server.shutdown)
            host, port = server.server_address[0], server.server_address[1]
            with self.assertRaises(urllib.error.HTTPError) as raised:
-                urllib.request.urlopen(f"http://{host}:{port}/bottles", timeout=5)
+                urllib.request.urlopen(
+                    urllib.request.Request(
+                        f"http://{host}:{port}/bottles",
+                        headers={"x-bot-bottle-orchestrator-auth": auth},
+                    ),
+                    timeout=5,
+                )
            payload = json.loads(raised.exception.read())
            output = stderr.getvalue()
        self.assertEqual({"error": "internal error"}, payload)
@@ -369,8 +426,9 @@ class TestOrchestratorAuth(unittest.TestCase):
        self.assertIsNotNone(self.orch.registry.get(rec.bottle_id))

    def _server_with_key(self, signing_key: str):
-        with patch.dict("os.environ", {"BOT_BOTTLE_ORCHESTRATOR_TOKEN": signing_key}):
-            server = make_server(self.orch, "127.0.0.1", 0)
+        server = make_server(
+            self.orch, "127.0.0.1", 0, signing_key=signing_key,
+        )
        self.addCleanup(server.server_close)
        threading.Thread(target=server.serve_forever, daemon=True).start()
        self.addCleanup(server.shutdown)
@@ -399,16 +457,10 @@ class TestOrchestratorAuth(unittest.TestCase):
        self.assertEqual(403, self._status(f"{base}/bottles", header=gateway_tok))
        self.assertEqual(200, self._status(f"{base}/bottles", header=cli_tok))

-    def test_unconfigured_server_runs_open(self) -> None:
-        """No signing key set (tests / nft-protected Firecracker): open mode
-        grants full cli access, so existing round-trip behavior is unchanged."""
-        with patch.dict("os.environ", {}, clear=False):
-            import os
-            os.environ.pop("BOT_BOTTLE_ORCHESTRATOR_TOKEN", None)
-            server = make_server(self.orch, "127.0.0.1", 0)
-        self.addCleanup(server.server_close)
-        self.assertEqual(ROLE_CLI, server.role_for(""))
-        self.assertEqual(ROLE_CLI, server.role_for("anything"))
+    def test_unconfigured_server_refuses_to_start(self) -> None:
+        with patch.dict("os.environ", {}, clear=True):
+            with self.assertRaisesRegex(ValueError, "signing key is required"):
+                make_server(self.orch, "127.0.0.1", 0)


 class TestDispatchSupervise(unittest.TestCase):
@@ -78,8 +78,7 @@ class TestControlPlaneProvisioning(unittest.TestCase):
            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
+        # Invariant 4: the orchestrator must never start without a key. 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()
Author	SHA1	Message	Date
didericis-codex	3dbf1780b4	docs(prd): require shared storage permissions prd-number-check / require-numbered-prds (pull_request) Successful in 11s Details test / image-input-builds (pull_request) Successful in 45s Details test / integration-docker (pull_request) Successful in 1m8s Details test / unit (pull_request) Successful in 2m30s Details test / coverage (pull_request) Successful in 25s Details tracker-policy-pr / check-pr (pull_request) Failing after 12m49s Details	2026-07-27 04:45:45 +00:00
didericis-codex	ff4da6f41e	docs(prd): bound heavy gateway operations prd-number-check / require-numbered-prds (pull_request) Successful in 10s Details test / unit (pull_request) Successful in 54s Details test / coverage (pull_request) Has been skipped Details test / integration-docker (pull_request) Has been cancelled Details test / image-input-builds (pull_request) Successful in 53s Details tracker-policy-pr / check-pr (pull_request) Failing after 14m19s Details	2026-07-27 04:16:56 +00:00
didericis-codex	3bb90da11c	docs(prd): require cleanup execution integrity test / image-input-builds (pull_request) Failing after 14m11s Details test / unit (pull_request) Failing after 14m19s Details prd-number-check / require-numbered-prds (pull_request) Failing after 14m25s Details test / integration-docker (pull_request) Has been cancelled Details test / coverage (pull_request) Has been skipped Details tracker-policy-pr / check-pr (pull_request) Failing after 12m36s Details	2026-07-27 03:55:18 +00:00
didericis-codex	0146450951	docs(prd): extend authoritative cleanup boundaries prd-number-check / require-numbered-prds (pull_request) Successful in 13s Details test / image-input-builds (pull_request) Successful in 3m18s Details test / unit (pull_request) Successful in 57s Details test / integration-docker (pull_request) Successful in 1m9s Details test / coverage (pull_request) Successful in 19s Details tracker-policy-pr / check-pr (pull_request) Failing after 10m30s Details	2026-07-27 03:31:46 +00:00
didericis-codex	ecaf23cdb5	docs(prd): define authoritative failure boundaries prd-number-check / require-numbered-prds (pull_request) Successful in 9s Details test / unit (pull_request) Successful in 52s Details test / integration-docker (pull_request) Waiting to run Details test / coverage (pull_request) Blocked by required conditions Details test / image-input-builds (pull_request) Successful in 2m42s Details tracker-policy-pr / check-pr (pull_request) Failing after 12s Details	2026-07-27 02:58:07 +00:00
didericis-codex	6e46a9b191	fix(orchestrator): satisfy adapter type contracts prd-number-check / require-numbered-prds (pull_request) Successful in 12s Details lint / lint (push) Successful in 53s Details test / image-input-builds (pull_request) Successful in 1m2s Details test / integration-docker (pull_request) Successful in 58s Details test / unit (pull_request) Successful in 46s Details test / coverage (pull_request) Successful in 21s Details tracker-policy-pr / check-pr (pull_request) Failing after 7s Details	2026-07-27 02:19:11 +00:00
didericis-codex	a59e495faa	refactor(egress): split request policy pipeline stages	2026-07-27 02:19:11 +00:00
didericis-codex	b8818948a0	feat(firecracker): enumerate running bottles	2026-07-27 02:19:11 +00:00
didericis-codex	b09952045a	fix(orchestrator): bound unauthenticated HTTP requests	2026-07-27 02:19:11 +00:00
didericis-codex	de192359ee	fix(security): authenticate persisted egress secrets	2026-07-27 02:19:11 +00:00
didericis-codex	7d9933edc0	fix(docker): fail closed on network address scan errors	2026-07-27 02:19:11 +00:00
didericis-codex	2bc9ef8ec0	fix(firecracker): abort cleanup on scan errors	2026-07-27 02:19:11 +00:00
didericis-codex	47b6bead69	refactor(backend): type enumeration failures	2026-07-27 02:19:11 +00:00
didericis-codex	15ecada022	fix(docker): surface enumeration failures	2026-07-27 02:19:11 +00:00
didericis-codex	e2222bd96b	fix(security): prohibit unauthenticated orchestrator	2026-07-27 02:19:11 +00:00