docs(prd): renumber 0083 -> 0081, and point at the umbrella issue

cf6bbc43 renumbered this PRD 0081 -> 0083 as "0081 already taken", but 0081 is free: main goes 0080, 0082, and no other branch claims it. 0083 is the number that is actually taken — feat/pinned-infra-artifacts holds docs/prds/0083-packaged-infra-artifacts.md, renamed there from its prd-new- form, so both PRDs were sitting on 0083 and whichever merged second would have collided. Move back to 0081 and leave 0083 to the infra-artifacts PRD. The Issue header pointed at #510 (CA) and #512 (git-gate), which have since been folded into #516 and closed. #516 carries both symptoms plus the shared root cause, so it is the reference that stays useful. requirements.gateway.lock also matches "0083" — inside a sha256 hash, left alone.
docs(prd): renumber 0081 -> 0083 (0081 already taken)
2026-07-27 11:33:23 -04:00 · 2026-07-27 15:14:54 +00:00 · 2026-07-27 15:14:33 +00:00 · 2026-07-27 15:14:33 +00:00 · 2026-07-27 15:14:33 +00:00 · 2026-07-27 10:56:59 -04:00
64 changed files with 1589 additions and 238 deletions
@@ -15,7 +15,7 @@
 ## Features

 - **Per-bottle egress allowlist** — TLS-bumped HTTP/HTTPS chokepoint with a per-manifest host allowlist; per-route path/method/header `matches` filtering; outbound DLP scanning for known tokens and secrets, inbound DLP scanning for prompt-injection attempts; DoH and arbitrary hosts blocked by default.
- **Per-route token-match policy** — each egress route picks what happens when the outbound DLP catches a token via `dlp.outbound_on_match`: `supervise` (default) holds the request and surfaces it in `./cli.py supervise` for approval (an approved value is remembered for the life of the proxy); `redact` scrubs the value and forwards; `block` is a hard `403`. Cuts false-positive friction without weakening default-deny.
+- **Per-route token-match policy** — each egress route picks what happens when the outbound DLP catches a token via `dlp.outbound_on_match`: `supervise` (default) holds the request and surfaces it in `bot-bottle supervise` for approval (an approved value is remembered for the life of the proxy); `redact` scrubs the value and forwards; `block` is a hard `403`. Cuts false-positive friction without weakening default-deny.
 - **Tokens the agent never sees** — host secrets live in a gateway; the agent dials `http://gateway:9099/<path>` and the proxy strips inbound `Authorization` and injects the real token before forwarding. `printenv` in the agent shows proxy URLs only.
 - **Gitleaks-scanned push (git-gate)** — `bottle.git` remotes route through a per-bottle `git daemon` that gitleaks-scans incoming refs pre-receive and forwards clean refs upstream over SSH. The agent never holds the upstream credential.
 - **Manifest-scoped skills + secrets** — each bottle declares its skills, env, git identity, remotes, and egress routes; unknown keys die at load.
@@ -39,7 +39,7 @@ On the legacy Docker backend, the same logical bottle is two containers per agen
 The Docker topology looks like this:

 ```
-                            host  ( ./cli.py )
+                            host  ( bot-bottle )
                                  │
                          starts  │  stops
                                  ▼
@@ -71,9 +71,23 @@ When the agent exits, `cli.py` tears down every gateway and both networks; nothi

 ## Quickstart

-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`.
+```sh
+curl -fsSL https://gitea.dideric.is/didericis/bot-bottle/raw/branch/main/install.sh | sh
+```

-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.
+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`.
+
+Use `BOT_BOTTLE_BACKEND=docker bot-bottle start <agent>` on hosts where neither Apple Container nor KVM is available and Docker is the desired backend.

 > **CI (macOS Apple Container):** the advisory `integration-macos` job in `.gitea/workflows/pre-release-test.yml` runs only on manual dispatch. It targets a self-hosted host-mode runner labelled `macos`; Apple Container cannot run inside the Linux pull-request runner. Provision an Apple Silicon host with the `container` CLI running and Python ≥ 3.11 plus `coverage` on the launchd service's explicit `PATH`. The infra container is a singleton (`bot-bottle-mac-infra`), so keep runner concurrency at 1. Its coverage is reported separately and never feeds the required pull-request gate.

@@ -166,10 +180,10 @@ On Linux, a KVM-capable host defaults to the Firecracker backend. It needs:
 - **`/dev/kvm`** present and accessible. Load `kvm-intel` or `kvm-amd` (and enable virtualization in BIOS/firmware). The invoking user must be in the `kvm` group: `sudo usermod -aG kvm "$USER"` then re-login. bot-bottle preflights this and reports exactly what's missing.
 - **`firecracker`** on `PATH`: grab a release from <https://github.com/firecracker-microvm/firecracker/releases>. Start flows print this pointer when the binary is missing.
 - **Docker** for the gateway and image build.
- **A one-time privileged network setup** — the per-bottle TAP pool plus the fail-closed `nftables` isolation table. Run `./cli.py backend setup --backend=firecracker` for the host-appropriate config (a NixOS module, a `sudo` script elsewhere); `./cli.py backend status --backend=firecracker` reports what's present, including whether the pool range collides with an existing route. The pool defaults to `10.243.0.0/16` (an obscure RFC-1918 block that dodges docker/libvirt/LAN and, deliberately, Tailscale's `100.64.0.0/10` CGNAT range); override with `BOT_BOTTLE_FC_IP_BASE` if it clashes on your host.
+- **A one-time privileged network setup** — the per-bottle TAP pool plus the fail-closed `nftables` isolation table. Run `bot-bottle backend setup --backend=firecracker` for the host-appropriate config (a NixOS module, a `sudo` script elsewhere); `bot-bottle backend status --backend=firecracker` reports what's present, including whether the pool range collides with an existing route. The pool defaults to `10.243.0.0/16` (an obscure RFC-1918 block that dodges docker/libvirt/LAN and, deliberately, Tailscale's `100.64.0.0/10` CGNAT range); override with `BOT_BOTTLE_FC_IP_BASE` if it clashes on your host.

 ```sh
-BOT_BOTTLE_BACKEND=firecracker ./cli.py start <agent>
+BOT_BOTTLE_BACKEND=firecracker bot-bottle start <agent>
 ```

 > **NixOS:** enable `virtualisation.docker`, ensure the KVM module is loaded (`boot.kernelModules = [ "kvm-intel" ];` or `kvm-amd`), and add your user to the `kvm` and `docker` groups. For the network pool, consume the flake module — `imports = [ inputs.bot-bottle.nixosModules.firecracker-netpool ]; services.bot-bottle-firecracker = { enable = true; owner = "you"; };` — then `nixos-rebuild switch` (imperative nft/TAP rules don't survive a rebuild; channel users can `imports = [ <bot-bottle>/nix/firecracker-netpool.nix ]`). `firecracker` isn't in nixpkgs by default as a user binary — install the release binary (pin the version) and put it on `PATH`.
@@ -177,7 +191,7 @@ BOT_BOTTLE_BACKEND=firecracker ./cli.py start <agent>
 > **CI:** Firecracker integration runs in the manually dispatched `.gitea/workflows/pre-release-test.yml` on a self-hosted runner labelled `kvm`; privileged KVM hosts never execute unreviewed PR code automatically. Provision it like a normal Firecracker host: `firecracker` on `PATH`, `/dev/kvm`, the cached guest kernel and static dropbear, and the persistent TAP/nft pool. The required pull-request workflow runs unit plus the complete Docker integration suite on `ubuntu-latest`; see `docs/ci.md`.

 ```sh
-./cli.py start <agent>   # builds the image on first run, drops you into claude
+bot-bottle start <agent>   # builds the image on first run, drops you into claude
 ```

 ## Manifest
@@ -253,7 +267,7 @@ You help maintain Gitea-hosted projects.
 | `dlp.outbound_on_match` | no | What to do when an outbound token is detected: `supervise` (default for manifest routes — hold for operator approval), `redact` (scrub the value and forward), or `block` (hard 403). Agent-provider routes (e.g. `api.anthropic.com`) default to `redact`. |
 | `git.fetch` | no | `true` permits smart HTTP clone/fetch (`git-upload-pack`) for this host. Push (`git-receive-pack`) remains blocked. |

-When an outbound DLP detector matches a token, the route's `dlp.outbound_on_match` policy decides what happens. Under the default `supervise`, the proxy queues an `egress-token-allow` proposal for the operator's `./cli.py supervise` TUI and holds the request open until it is answered (or `EGRESS_TOKEN_ALLOW_TIMEOUT_SECONDS`, default 300s, elapses — after which it fails closed). The operator never sees the raw token, only the host, method, path, and a redacted snippet; approving adds the value to an in-memory safelist for the life of the egress proxy. Under `redact`, the matched value is scrubbed from the body, headers, and path and the request is forwarded (failing closed if a match lands somewhere unredactable, like the hostname). Under `block` it stays a hard `403`. Structural blocks (CRLF injection) and not-in-allowlist host blocks are always hard `403`s regardless of policy.
+When an outbound DLP detector matches a token, the route's `dlp.outbound_on_match` policy decides what happens. Under the default `supervise`, the proxy queues an `egress-token-allow` proposal for the operator's `bot-bottle supervise` TUI and holds the request open until it is answered (or `EGRESS_TOKEN_ALLOW_TIMEOUT_SECONDS`, default 300s, elapses — after which it fails closed). The operator never sees the raw token, only the host, method, path, and a redacted snippet; approving adds the value to an in-memory safelist for the life of the egress proxy. Under `redact`, the matched value is scrubbed from the body, headers, and path and the request is forwarded (failing closed if a match lands somewhere unredactable, like the hostname). Under `block` it stays a hard `403`. Structural blocks (CRLF injection) and not-in-allowlist host blocks are always hard `403`s regardless of policy.

 More examples in `examples/`. Full design lives under `docs/prds/`; the trust-boundary rationale is in `docs/prds/0011-per-file-md-manifest.md`.

@@ -226,7 +226,7 @@ class AgentProvider(ABC):
        initial task in a non-interactive (headless) session.

        Called only when ``--prompt`` is passed to
-        ``./cli.py start --headless``; the returned args are appended
+        ``bot-bottle start --headless``; the returned args are appended
        after the provider's ``bypass_args`` and ``startup_args``."""

    def provision_ca(self, bottle: "Bottle", plan: "BottlePlan") -> None:
@@ -531,7 +531,7 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
        host-appropriate config or commands. Prints to stdout/stderr and
        returns a shell exit code (0 = nothing to report / success). A
        backend that needs no host setup prints a short note and returns
-        0. Invoked generically by `./cli.py backend setup [--backend=…]`
+        0. Invoked generically by `bot-bottle backend setup [--backend=…]`
        so operators can provision any backend without a
        backend-specific command. Classmethod (like `is_available`) —
        it's a host query, not per-bottle state."""
@@ -548,14 +548,14 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
        stderr. When quiet=True returns the status code silently —
        useful for cheap programmatic checks.

-        Invoked by `./cli.py backend status [--backend=…]` (quiet=False)
+        Invoked by `bot-bottle backend status [--backend=…]` (quiet=False)
        and by is_backend_ready() (caller-controlled)."""

    @classmethod
    @abstractmethod
    def teardown(cls) -> int:
        """Undo `setup()` — the inverse operation, surfaced as
-        `./cli.py backend teardown [--backend=…]` (uninstall). Symmetric
+        `bot-bottle backend teardown [--backend=…]` (uninstall). Symmetric
        with setup: where setup is advisory (prints the privileged
        commands / declarative config to apply), teardown prints the
        commands / config change to remove the host prerequisites. A
@@ -74,10 +74,13 @@ def list_compose_projects(
        result = subprocess.run(
            argv, capture_output=True, text=True, check=False,
        )
-    except FileNotFoundError as exc:
+    except OSError as exc:
+        # Not only "not found": docker on PATH but not executable by this
+        # user raises PermissionError. Either way the query never ran, so an
+        # enumeration caller must not read the empty result as authoritative.
        if raise_on_error:
            raise EnumerationError(
-                "docker compose ls failed: docker not found"
+                f"docker compose ls failed: docker unavailable ({exc})"
            ) from exc
        return []
    if result.returncode != 0:
@@ -74,8 +74,9 @@ def _query_services_by_project() -> dict[str, set[str]]:
            ],
            capture_output=True, text=True, check=False,
        )
-    except FileNotFoundError as exc:
-        raise EnumerationError("docker ps failed: docker not found") from exc
+    except OSError as exc:
+        # Missing, or on PATH but not executable by this user (PermissionError).
+        raise EnumerationError(f"docker ps failed: docker unavailable ({exc})") from exc
    if r.returncode != 0:
        raise EnumerationError(f"docker ps failed: {r.stderr.strip()}")
    return _parse_services_by_project(r.stdout or "")
@@ -8,7 +8,7 @@ pointer, and `status()` reports whether docker is usable.
 This is intentionally minimal; a richer version (daemon config checks,
 gVisor/runsc install guidance, rootless-docker hints) is tracked
 separately. Reached via `DockerBottleBackend.setup` / `.status`, which
-the generic `./cli.py backend {setup,status}` dispatches to.
+the generic `bot-bottle backend {setup,status}` dispatches to.
 """

 from __future__ import annotations
@@ -69,7 +69,7 @@ def teardown() -> int:
    sys.stderr.write(
        "Docker backend: nothing to undo — it provisions no privileged host "
        "state (networks and the gateway are per-launch and are "
-        "removed by `./cli.py cleanup`). Docker itself is left installed.\n"
+        "removed by `bot-bottle cleanup`). Docker itself is left installed.\n"
    )
    return 0

@@ -89,5 +89,5 @@ def status() -> int:
    runsc = _docker_on_path() and _util.runsc_available()
    sys.stderr.write(f"gVisor runsc runtime: {'registered' if runsc else 'not registered (optional)'}\n")
    if not ok:
-        sys.stderr.write("\nRun: ./cli.py backend setup --backend=docker\n")
+        sys.stderr.write("\nRun: bot-bottle backend setup --backend=docker\n")
    return 0 if ok else 1
@@ -204,7 +204,7 @@ def boot_vm(
    Records the PID."""
    if not netpool.tap_present(slot.iface):
        die(f"infra link {slot.iface} not present.\n"
-            f"    ./cli.py backend setup --backend=firecracker")
+            f"    bot-bottle backend setup --backend=firecracker")

    run_dir.mkdir(parents=True, exist_ok=True)
    rootfs = run_dir / "rootfs.ext4"
@@ -108,7 +108,7 @@ def verify_isolation(private_key: Path, guest_ip: str) -> None:
        die(f"ISOLATION FAILURE: the VM reached the host canary "
            f"{canary_ip}:{canary_port}. The egress boundary is not in "
            f"force — refusing to run the agent (fail-closed). Verify the "
-            f"nft table with: ./cli.py backend setup --backend=firecracker")
+            f"nft table with: bot-bottle backend setup --backend=firecracker")
    if result.returncode == 2:
        die("isolation probe inconclusive: the guest has no python3/bash/nc "
            "to run the connectivity test. Refusing to continue "
@@ -3,7 +3,7 @@ config renderers (shell command + NixOS module) shown to operators.

 The Firecracker backend needs a privileged one-time network setup:
 a pool of point-to-point TAP devices (owned by the invoking user, so
-`./cli.py start` never needs root) and a dedicated nftables table that
+`bot-bottle start` never needs root) and a dedicated nftables table that
 isolates every VM. The pool parameters live in exactly one place —
 `netpool.defaults.env`, a plain KEY=VALUE file next to this module —
 and every consumer reads *that*: this module (below), the shell script
@@ -177,14 +177,20 @@ def gw_slot() -> Slot:
 # --- fail-closed verification ---------------------------------------

 def _run_ok(argv: list[str]) -> bool:
-    """Run a probe command, treating a missing binary as failure
+    """Run a probe command, treating an unavailable 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 FileNotFoundError:
+    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".
        return False


@@ -244,7 +250,9 @@ def overlapping_routes() -> list[RouteConflict]:
            ["ip", "-json", "route", "show", "table", "all"],
            capture_output=True, text=True, check=False,
        )
-    except FileNotFoundError:
+    except OSError:
+        # Missing, or present-but-not-executable for this user; either way
+        # there are no routes we can enumerate. See _run_ok.
        return []
    if proc.returncode != 0 or not proc.stdout.strip():
        return []
@@ -307,11 +315,11 @@ def allocate(slug: str) -> tuple[Slot, IO[str]]:
        return s, handle
    die(f"Firecracker TAP pool exhausted ({pool_size()} slots, all in "
        f"use). Stop a running bottle or raise BOT_BOTTLE_FC_POOL_SIZE "
-        f"and re-run `./cli.py backend setup --backend=firecracker`.")
+        f"and re-run `bot-bottle backend setup --backend=firecracker`.")
    raise AssertionError("unreachable")


-# --- config renderers (shown by `./cli.py backend setup`) -----------
+# --- config renderers (shown by `bot-bottle backend setup`) -----------

 # The persistent unit is the portable install: the same systemd oneshot
 # on every systemd distro (Debian/Ubuntu/Fedora/RHEL/Arch/…).
@@ -8,7 +8,7 @@ bundled setup script. `status()` reports what's present, including
 whether the pool range collides with an existing route.

 Called through `FirecrackerBottleBackend.setup` / `.status`, which the
-generic `./cli.py backend {setup,status}` command dispatches to.
+generic `bot-bottle backend {setup,status}` command dispatches to.
 """

 from __future__ import annotations
@@ -34,7 +34,7 @@ _UNIT_PATH = Path("/etc/systemd/system") / netpool.SYSTEMD_UNIT

 def _owner() -> str:
    # Under `sudo`, USER is root but SUDO_USER is the real invoker — the
-    # TAPs must be owned by them so `./cli.py start` stays rootless.
+    # TAPs must be owned by them so `bot-bottle start` stays rootless.
    return os.environ.get("SUDO_USER") or os.environ.get("USER") or "youruser"


@@ -161,7 +161,7 @@ def _setup_systemd() -> None:
        if rc == 0:
            sys.stderr.write(
                f"Installed and started {netpool.SYSTEMD_UNIT}. Verify with "
-                f"`./cli.py backend status --backend=firecracker`.\n"
+                f"`bot-bottle backend status --backend=firecracker`.\n"
            )
        else:
            sys.stderr.write(
@@ -181,7 +181,7 @@ def _setup_systemd() -> None:
    )
    sys.stderr.write(
        f"\n(Or re-run this as root to install it directly: "
-        f"sudo ./cli.py backend setup --backend=firecracker)\n"
+        f"sudo bot-bottle backend setup --backend=firecracker)\n"
    )


@@ -334,7 +334,7 @@ def status() -> int:
        sys.stderr.write(f"range overlap: none (base {netpool.ip_base()})\n")
    _report_persistence()
    if not ok:
-        sys.stderr.write("\nRun: ./cli.py backend setup --backend=firecracker\n")
+        sys.stderr.write("\nRun: bot-bottle backend setup --backend=firecracker\n")
    return 0 if ok else 1


@@ -9,7 +9,7 @@ generation.

 The privileged network setup (TAP pool + nft table) is a one-time
 operator step — see `netpool.py`, `scripts/firecracker-netpool.sh`,
-and `./cli.py backend setup --backend=firecracker`.
+and `bot-bottle backend setup --backend=firecracker`.
 """

 from __future__ import annotations
@@ -132,18 +132,18 @@ def _require_network_pool() -> None:
             f"{netpool.pool_size()} slots) overlaps existing routes: "
             f"{detail}. This can shadow or be shadowed by that route; "
             f"set BOT_BOTTLE_FC_IP_BASE to a free range and re-run "
-             f"./cli.py backend setup --backend=firecracker.")
+             f"bot-bottle backend setup --backend=firecracker.")
    missing = netpool.missing_taps()
    if missing:
        die(f"network pool incomplete — missing TAP devices: "
-            f"{', '.join(missing)}.\n    ./cli.py backend setup --backend=firecracker")
+            f"{', '.join(missing)}.\n    bot-bottle backend setup --backend=firecracker")
    if shutil.which("nft") is not None and not netpool.nft_table_present():
        # nft is queryable and says the table is absent — that's a
        # definite, catchable misconfiguration; fail early.
        warn(f"isolation table `inet {netpool.NFT_TABLE}` not found via nft. "
             "If this is a permissions issue it will be re-checked "
             "empirically after boot; otherwise run: "
-             "./cli.py backend setup --backend=firecracker")
+             "bot-bottle backend setup --backend=firecracker")


 # --- rootfs pipeline (rootless) -------------------------------------
@@ -43,7 +43,7 @@ class Freezer(ABC):

        Calls _freeze for the backend-specific snapshot, then writes the
        committed image reference to per-bottle state and marks the bottle
-        preserved so the next `./cli.py resume` boots from the snapshot.
+        preserved so the next `bot-bottle resume` boots from the snapshot.

        Raises CommitCancelled if the user declines an interactive
        confirmation prompt (e.g. the macos-container stop prompt).
@@ -51,7 +51,7 @@ class Freezer(ABC):
        image_ref = self._freeze(agent)
        write_committed_image(agent.slug, image_ref)
        mark_preserved(agent.slug)
-        info(f"to resume from this snapshot: ./cli.py resume {agent.slug}")
+        info(f"to resume from this snapshot: bot-bottle resume {agent.slug}")
        self._export_hint(agent.slug, image_ref)

    @abstractmethod
@@ -5,7 +5,7 @@ Like Docker, this backend needs no privileged network-pool provisioning
 running. `setup()` points at the install/`container system start` steps;
 `status()` reports readiness. Reached via
 `MacosContainerBottleBackend.setup` / `.status`, dispatched from the
-generic `./cli.py backend {setup,status}`.
+generic `bot-bottle backend {setup,status}`.
 """

 from __future__ import annotations
@@ -75,5 +75,5 @@ def status() -> int:
        if not _service_running():
            ok = False
    if not ok:
-        sys.stderr.write("\nRun: ./cli.py backend setup --backend=macos-container\n")
+        sys.stderr.write("\nRun: bot-bottle backend setup --backend=macos-container\n")
    return 0 if ok else 1
@@ -689,6 +689,13 @@ def pinned_local_image_ref(ref: str) -> str:
    nested-containers layer. A content-derived tag prevents another concurrent
    build from moving the provider's ordinary ``:latest`` tag between those
    two builds.
+
+    Unlike Docker, `container image tag` only accepts ``image-name[:tag]`` as
+    its source and rejects a bare image ID ("cannot specify 64 byte hex string
+    as reference"), so the mutable ``ref`` is what gets tagged here. The
+    post-tag inspection below is what keeps that fail-closed: if ``ref`` moved
+    between the two commands, the new tag will not resolve to the ID this call
+    derived its name from.
    """
    image = image_id(ref)
    digest = image.removeprefix("sha256:")
@@ -701,14 +708,14 @@ def pinned_local_image_ref(ref: str) -> str:
        repository = repository[:last_colon]
    pinned_ref = f"{repository}:sha256-{digest}"
    result = subprocess.run(
-        [_CONTAINER, "image", "tag", image, pinned_ref],
+        [_CONTAINER, "image", "tag", ref, pinned_ref],
        capture_output=True,
        text=True,
        check=False,
    )
    if result.returncode != 0:
        die(
-            f"could not tag exact local image {image}: "
+            f"could not tag exact local image {image} via {ref!r}: "
            f"{(result.stderr or result.stdout or '').strip() or '<no detail>'}"
        )
    if image_id(pinned_ref) != image:
@@ -86,7 +86,7 @@ def _print_vm_install_instructions() -> None:
        info("Then start the service:  container system start")
    else:
        info("Install Firecracker: https://github.com/firecracker-microvm/firecracker/releases")
-        info("Configure the host:  ./cli.py backend setup")
+        info("Configure the host:  bot-bottle backend setup")


 def _auto_select_backend(prompt: bool = True) -> str:
@@ -1,9 +1,9 @@
 """`backend` CLI command — generic host setup/status across backends.

-`./cli.py backend setup    [--backend=NAME]` provisions (or points at how
+`bot-bottle backend setup    [--backend=NAME]` provisions (or points at how
 to provision) the chosen backend's one-time host prerequisites.
-`./cli.py backend status   [--backend=NAME]` reports readiness.
-`./cli.py backend teardown [--backend=NAME]` undoes setup (uninstall).
+`bot-bottle backend status   [--backend=NAME]` reports readiness.
+`bot-bottle backend teardown [--backend=NAME]` undoes setup (uninstall).

 All dispatch to the backend's `setup()` / `status()` / `teardown()`
 classmethods, so there are no backend-specific commands — swapping
@@ -1,7 +1,7 @@
 """cleanup: stop and remove all orphaned bot-bottle resources.

 Walks every registered backend (docker, firecracker, macos-container)
-so a single `./cli.py cleanup` reaps every backend's leftovers — a
+so a single `bot-bottle cleanup` reaps every backend's leftovers — a
 firecracker bottle's VM processes and run dirs won't survive a
 docker-only cleanup pass (issue addressed alongside #77).

@@ -4,7 +4,7 @@ Docker bottles are committed to a local Docker image. Macos-container
 bottles are exported and rebuilt as a local Apple Container image.
 Firecracker bottles stream the guest rootfs out over SSH and rebuild a
 local Docker image. The resulting reference is stored in per-bottle
-state so the next `./cli.py resume <slug>` boots from the snapshot
+state so the next `bot-bottle resume <slug>` boots from the snapshot
 instead of rebuilding from the Dockerfile.
 """

@@ -37,7 +37,7 @@ def cmd_commit(argv: list[str]) -> int:
    if slug is None:
        active = enumerate_active_agents()
        if not active:
-            die("no active bottles; start one with `./cli.py start`")
+            die("no active bottles; start one with `bot-bottle start`")
        choices = [a.slug for a in active]
        slug = tui.filter_select(choices, title="Select bottle to commit")
        if slug is None:
@@ -8,7 +8,7 @@ override and transcript snapshot under the same state dir.

 Use case: an interrupted or preserved bottle needs to be relaunched;
 the operator runs
-    ./cli.py resume <identity>
+    bot-bottle resume <identity>
 to bring up the replacement from the recorded state.
 """

@@ -203,19 +203,19 @@ def _start_headless(
    if not os.isatty(stdin_fd):
        die(
            "--headless requires a PTY on stdin; run via:\n"
-            "  script -q /dev/null ./cli.py start ..."
+            "  script -q /dev/null bot-bottle start ..."
        )

    agent_name = args.name
    if not agent_name:
-        die("--headless requires an agent name: ./cli.py start <agent> --headless")
+        die("--headless requires an agent name: bot-bottle start <agent> --headless")
    manifest.require_agent(agent_name)  # raises ManifestError if unknown

    prompt = args.prompt
    if not prompt:
        die(
            "--headless requires --prompt: "
-            "./cli.py start <agent> --headless --prompt 'Do the thing'"
+            "bot-bottle start <agent> --headless --prompt 'Do the thing'"
        )

    if args.bottle:
@@ -319,9 +319,9 @@ def attach_agent(

    `resume=True` adds `--continue` so claude picks up its most
    recent session non-interactively (no session-picker prompt).
-    First-attach paths (`./cli.py start`) leave it False.
+    First-attach paths (`bot-bottle start`) leave it False.

-    Used as the inner step of `./cli.py start`."""
+    Used as the inner step of `bot-bottle start`."""
    runtime = runtime_for(agent_provider_template)
    info(
        f"attaching interactive {agent_provider_template} session "
@@ -354,7 +354,7 @@ def settle_state(identity: str) -> None:
    if not identity:
        return
    if is_preserved(identity):
-        info(f"to resume this bottle: ./cli.py resume {identity}")
+        info(f"to resume this bottle: bot-bottle resume {identity}")
        return
    cleanup_state(identity)

@@ -110,7 +110,7 @@ def discover_pending() -> list[QueuedProposal]:
 def _approval_status(qp: QueuedProposal, verb: str) -> str:
    """Status-line text after a successful approval."""
    base = f"{verb} {qp.proposal.tool} for [{qp.label}]"
-    return f"{base}; resume: ./cli.py resume {qp.label}"
+    return f"{base}; resume: bot-bottle resume {qp.label}"


 def _detail_lines(
@@ -385,7 +385,7 @@ PY
      ;;
  esac
  echo "git-gate: queued # gitleaks:allow supervisor approval $proposal_id" >&2
-  echo "git-gate: approve with './cli.py supervise' to continue this push" >&2
+  echo "git-gate: approve with 'bot-bottle supervise' to continue this push" >&2
  waited=0
  while [ "$waited" -lt "$timeout" ]; do
    status=$(PYTHONPATH="/app${PYTHONPATH:+:$PYTHONPATH}" python3 - "$proposal_id" <<'PY'
@@ -50,6 +50,12 @@ class ReprovisionBody(_StrictModel):
    env_var_secret: StrictStr


+class SecretBody(_StrictModel):
+    name: StrictStr
+    value: StrictStr
+    env_var_secret: StrictStr
+
+
 class ReconcileBody(_StrictModel):
    live_source_ips: list[StrictStr]
    grace_seconds: float | None = None
@@ -259,6 +265,21 @@ def create_app(orch: OrchestratorCore, *, signing_key: str) -> FastAPI:
            return {"reprovisioned": True}
        raise HTTPException(404, "no stored secrets for this bottle")

+    @app.post("/bottles/{bottle_id}/secret")
+    def update_secret(bottle_id: str, body: SecretBody) -> dict[str, object]:
+        # Update ONE egress token for a running bottle in place — the
+        # single-secret form of reprovision, for refreshing a short-lived host
+        # credential (e.g. the Codex access token) without a relaunch. cli-only
+        # (not in _GATEWAY_ROUTES): a bottle must never set its own tokens.
+        if orch.update_agent_secret(
+            bottle_id,
+            _required(body.name, "name"),
+            _required(body.value, "value"),
+            _required(body.env_var_secret, "env_var_secret"),
+        ):
+            return {"updated": True}
+        raise HTTPException(404, "no such bottle")
+
    @app.delete("/bottles/{bottle_id}")
    def teardown(bottle_id: str) -> dict[str, object]:
        if orch.teardown_bottle(bottle_id):
@@ -184,6 +184,27 @@ class OrchestratorClient:
            )
        return True

+    def update_agent_secret(
+        self, bottle_id: str, name: str, value: str, env_var_secret: str,
+    ) -> bool:
+        """Update ONE egress token for a running bottle in place
+        (`POST /bottles/<id>/secret`) — the single-secret form of
+        `reprovision_gateway`, for pushing a freshly-refreshed host credential
+        into a bottle without a relaunch. Returns True on success, False when the
+        orchestrator doesn't know the bottle (404)."""
+        status, _ = self._request(
+            "POST",
+            f"/bottles/{bottle_id}/secret",
+            {"name": name, "value": value, "env_var_secret": env_var_secret},
+        )
+        if status == 404:
+            return False
+        if not 200 <= status < 300:
+            raise OrchestratorClientError(
+                f"update_agent_secret {bottle_id}: HTTP {status}"
+            )
+        return True
+
    def teardown_bottle(self, bottle_id: str) -> bool:
        """Tear a bottle down (`DELETE /bottles/<id>`). False if the
        orchestrator didn't know it (404) — idempotent for cleanup paths."""
@@ -379,6 +379,30 @@ class OrchestratorCore:
        self._tokens[bottle_id] = decrypted
        return True

+    def update_agent_secret(
+        self, bottle_id: str, name: str, value: str, env_var_secret: str,
+    ) -> bool:
+        """Update ONE egress token for a known bottle in place — the
+        single-secret form of ``reprovision_from_secret``.
+
+        Sets the in-memory token AND upserts the single re-encrypted row under
+        *env_var_secret* (the same key the rest of the rows are encrypted with, so
+        the whole set stays decryptable by a later ``reprovision_from_secret``),
+        leaving every other token untouched. Returns False if the bottle is
+        unknown.
+
+        Unlike ``reprovision_from_secret`` (which restores the values captured at
+        launch), this pushes a *caller-supplied* value — used to refresh a
+        short-lived host credential (e.g. the Codex access token) into a
+        still-running bottle without a relaunch."""
+        from .store.secret_store import encrypt_value
+        if self.registry.get(bottle_id) is None:
+            return False
+        self._tokens.setdefault(bottle_id, {})[name] = value
+        self.registry.store_agent_secret(
+            bottle_id, name, encrypt_value(env_var_secret, value))
+        return True
+
    # --- consolidated gateway ----------------------------------------------

    def gateway_status(self) -> dict[str, object]:
@@ -370,6 +370,30 @@ class RegistryStore(DbStore):
            )
        self._chmod()

+    def store_agent_secret(
+        self,
+        bottle_id: str,
+        key: str,
+        encrypted_value: str,
+        secret_type: str = "injected_env_var",
+    ) -> None:
+        """Upsert ONE encrypted secret row (env-var name → ciphertext) for
+        *bottle_id*, leaving the bottle's other secrets untouched — the per-key
+        counterpart of ``store_agent_secrets``' replace-all. Delete-then-insert
+        because the table carries no unique constraint to `ON CONFLICT` against."""
+        with self._connection() as conn:
+            conn.execute(
+                "DELETE FROM bottled_agent_secrets "
+                "WHERE bottled_agent_id = ? AND key = ? AND type = ?",
+                (bottle_id, key, secret_type),
+            )
+            conn.execute(
+                "INSERT INTO bottled_agent_secrets "
+                "(bottled_agent_id, key, value, type) VALUES (?, ?, ?, ?)",
+                (bottle_id, key, encrypted_value, secret_type),
+            )
+        self._chmod()
+
    def get_agent_secrets(
        self,
        bottle_id: str,
@@ -1,4 +1,4 @@
-# VHS tape — drives `./cli.py start demo` interactively and asks
+# VHS tape — drives `bot-bottle start demo` interactively and asks
 # claude (the AI) to run four probes via natural-language prompts.
 # Setup (manifest + dummy SSH key + image pre-warm) and teardown
 # happen outside the tape; record via `bash scripts/demo-record.sh`,
@@ -29,7 +29,7 @@ Show
 # defaults), one git upstream (unreachable on purpose so gitleaks runs
 # before the gate would forward), and a FAKE_TOKEN env var shaped like
 # a GitHub PAT.
-Type "./cli.py start demo"
+Type "bot-bottle start demo"
 Enter
 Sleep 8s

@@ -132,7 +132,7 @@ Each test runs against a temporary `$HOME` and a temporary `$CWD`:
  can revisit, but the v1 of this PRD is one file = one bottle.

 - **Hot-reload.** Changes to manifest files take effect at next
-  `./cli.py start`; we do not watch the directory.
+  `bot-bottle start`; we do not watch the directory.

 ## Scope

@@ -290,7 +290,7 @@ After this PRD:

 ### Cleanup CLI

-`./cli.py cleanup` switches from "list every container with prefix
+`bot-bottle cleanup` switches from "list every container with prefix
 `bot-bottle-` and every network with prefix `bot-bottle-net-`
 or `bot-bottle-egress-`" to:

@@ -369,7 +369,7 @@ Sized for one PR each, in order.
   `docker compose up -d` + attach + teardown. Per-sidecar `start()`/
   `stop()` lifecycle methods deleted in the same chunk. Compose-
   log dump on teardown added.
-4. **Cleanup CLI on compose.** Switch `./cli.py cleanup` to
+4. **Cleanup CLI on compose.** Switch `bot-bottle cleanup` to
   `docker compose ls`-based discovery; keep prefix-scan as
   fallback for one release.
 5. **Dashboard.** Decide on the discovery question (open question
@@ -37,7 +37,7 @@ Two rough edges in the current dashboard:
   shows only pending proposals. If no agent has called a tool,
   the screen reads "no pending proposals" — even when five
   bottles are quietly working. The operator has to `docker
-   compose ls` (or `./cli.py cleanup -n` to see the y/N preview)
+   compose ls` (or `bot-bottle cleanup -n` to see the y/N preview)
   to find out what's actually live.

 2. **`e` / `p` re-discover-and-disambiguate every invocation.**
@@ -82,12 +82,12 @@ the "operator wants to make an unprompted change" case.
  global across bottles. Filtering ("show me only this agent's
  proposals") might be a follow-up but isn't this PRD.
 - **Agent lifecycle from the dashboard.** Starting / stopping
-  agents stays in `./cli.py start` / `./cli.py cleanup`. The
+  agents stays in `bot-bottle start` / `bot-bottle cleanup`. The
  dashboard reads state; it doesn't change it.
 - **Preserved-but-not-running bottles.** The active-agents list
  is strictly "what's running now" (cross-referenced from
  `docker compose ls`). Preserved state dirs without a live
-  project don't appear — `./cli.py resume <identity>` is the
+  project don't appear — `bot-bottle resume <identity>` is the
  path for those.
 - **A separate per-agent detail view.** The agent rows are
  one-line summaries. Pressing Enter on a proposal still drops
@@ -125,7 +125,7 @@ the "operator wants to make an unprompted change" case.
 - Changes to proposal handling (`a` / `m` / `r` / Enter all
  unchanged).
 - Changes to the queue-dir / supervise sidecar protocol.
- New CLI surface beyond what's in `./cli.py dashboard`.
+- New CLI surface beyond what's in `bot-bottle dashboard`.
 - Touching the manifest, compose renderer, launch lifecycle.

 ## Proposed design
@@ -14,8 +14,8 @@
 Today the dashboard is read-only: it surfaces pending proposals
 and active agents (PRD 0019) but can't *start* an agent or
 *re-enter* one. The operator's path is split — they launch
-agents from one terminal (`./cli.py start <name>`), and watch
-them from another (`./cli.py dashboard`).
+agents from one terminal (`bot-bottle start <name>`), and watch
+them from another (`bot-bottle dashboard`).

 This PRD collapses that split. The dashboard becomes the
 operator's single surface: pressing a key opens an agent picker,
@@ -31,7 +31,7 @@ claude session AND the dashboard process. Exit claude → back to
 dashboard, bottle still running. Start another agent → two
 bottles up at once. Quit the dashboard → bottles continue
 running. Teardown is **always explicit**: the operator presses
-`x` on an agent, or runs `./cli.py cleanup` later.
+`x` on an agent, or runs `bot-bottle cleanup` later.

 ## Problem

@@ -45,7 +45,7 @@ Two real frictions today:
   open and the dashboard's "active agents" pane is hopelessly
   behind reality because they just spawned three in a row.

-2. **`./cli.py start` ties the bottle to a single claude
+2. **`bot-bottle start` ties the bottle to a single claude
   session.** The start command's `ExitStack` brings the bottle
   up, runs claude, and tears down on Ctrl-D — fine for a one-
   shot session, wrong for "let me bounce in and out of this
@@ -60,7 +60,7 @@ captures full-merged logs per bottle (PRD 0018). It already

 ## Goals / Success Criteria

-1. From inside `./cli.py dashboard`, pressing `n` (new) opens
+1. From inside `bot-bottle dashboard`, pressing `n` (new) opens
   an agent picker listing every agent defined in the manifest.
   Selecting one runs `prepare → preflight → launch`.
 2. The preflight Y/N summary renders cleanly — either as a
@@ -83,7 +83,7 @@ captures full-merged logs per bottle (PRD 0018). It already
   state cleanup) without quitting the dashboard.
 7. Quitting the dashboard (`q`) leaves every running bottle
   running. Bottle teardown is always explicit (per-bottle `x`
-   or `./cli.py cleanup`). The next `./cli.py dashboard`
+   or `bot-bottle cleanup`). The next `bot-bottle dashboard`
   invocation re-discovers them via `list_active_slugs()` and
   surfaces re-attach for any it can reconstruct context for
   (see "Cross-dashboard re-attach" below).
@@ -94,13 +94,13 @@ captures full-merged logs per bottle (PRD 0018). It already
  embedded-emulator option from the research doc is out of
  scope. The handoff (option 1) is the v1; option 2 is a
  separate PRD if and when handoff is observably insufficient.
- **Adopting bottles started by an out-of-dashboard `./cli.py
+- **Adopting bottles started by an out-of-dashboard `bot-bottle
  start` invocation.** Those have their own ExitStack-owner and
  the dashboard treats them as read-only-watch (already does
  today). Re-attach only applies to bottles the *current
  dashboard process* started.
 - **Resurrecting an out-of-process bottle into a new dashboard
-  with full re-attach.** A bottle started by `./cli.py start`
+  with full re-attach.** A bottle started by `bot-bottle start`
  in another terminal — or by a previous dashboard run, now
  exited — appears in the agents pane (already does, PRD 0019)
  and can be re-attached via `docker exec -it claude` because
@@ -109,12 +109,12 @@ captures full-merged logs per bottle (PRD 0018). It already
  context object to drive teardown — e.g., the
  ExitStack-tracked CA + state cleanup `_settle_state` performs
  today. Cross-dashboard re-attach uses the existing
-  `./cli.py cleanup` for teardown, not an `x` keypress (see
+  `bot-bottle cleanup` for teardown, not an `x` keypress (see
  open questions).
 - **Multi-window UI.** Single curses window, two existing
  panes (proposals + agents); the agent picker is a modal, not
  a third pane.
- **Removing `./cli.py start`.** Stays as the script-friendly /
+- **Removing `bot-bottle start`.** Stays as the script-friendly /
  legacy entry point. The dashboard is the new default.

 ## Scope
@@ -140,7 +140,7 @@ captures full-merged logs per bottle (PRD 0018). It already

 ### Out of scope

- Changes to `./cli.py start` itself. It keeps its current
+- Changes to `bot-bottle start` itself. It keeps its current
  shape; the dashboard reuses its internal pieces (backend.
  prepare / backend.launch) without reaching through the CLI
  layer.
@@ -157,7 +157,7 @@ captures full-merged logs per bottle (PRD 0018). It already
 Today's flow:

 ```
-./cli.py start agent
+bot-bottle start agent
  └─ with backend.launch(plan) as bottle:        ← bottle alive while inside `with`
       bottle.exec_agent([...], tty=True)       ← blocks until claude exits
     # context exits → compose down → state cleanup
@@ -166,7 +166,7 @@ Today's flow:
 The proposed dashboard-driven flow:

 ```
-./cli.py dashboard
+bot-bottle dashboard
  └─ bottles: dict[str, tuple[ContextManager, DockerBottle]] = {}

     # operator presses `n`, picks agent
@@ -205,7 +205,7 @@ Two shifts:
   evaluation, state-dir reap) doesn't fire on a quit-while-
   running bottle. It DOES fire when the operator explicitly
   stops via `x`, because that calls `cm.__exit__`. For
-   bottles a previous dashboard quit on, `./cli.py cleanup`
+   bottles a previous dashboard quit on, `bot-bottle cleanup`
   is the path — its compose-down + state-reap logic
   already covers the case.

@@ -213,7 +213,7 @@ Two shifts:

 When the dashboard discovers a bottle in `discover_active_agents`
 that it didn't itself start (a previous-dashboard or external
-`./cli.py start` bottle), Enter still attaches via `docker exec
+`bot-bottle start` bottle), Enter still attaches via `docker exec
 -it … claude` — the agent container is running `sleep infinity`
 exactly the same way regardless of who started it. The only
 thing the current dashboard lacks for those bottles is the
@@ -221,8 +221,8 @@ launch-context object needed to drive a clean teardown via
 `x`.

 For v1 we surface this honestly: pressing `x` on a non-owned
-agent shows a status hint pointing at `./cli.py cleanup` (or
-`./cli.py cleanup` targeted at the slug if we add that flag
+agent shows a status hint pointing at `bot-bottle cleanup` (or
+`bot-bottle cleanup` targeted at the slug if we add that flag
 later). The agent stays alive; the operator handles teardown
 out-of-band. Enter (re-attach) works for both owned and
 non-owned bottles.
@@ -288,7 +288,7 @@ agents pane.

 `x` on a non-owned agent (discovered via `list_active_slugs`
 but not in `bottles` dict): no-op with status hint pointing
-at `./cli.py cleanup` (the existing path that tears down
+at `bot-bottle cleanup` (the existing path that tears down
 ANY bot-bottle compose project plus reaps state dirs).

 ### Dashboard quit
@@ -300,7 +300,7 @@ the `docker compose` project keeps running. The next dashboard
 invocation discovers the bottles via `list_active_slugs` and
 surfaces re-attach.

-This is a real departure from today's `./cli.py start`
+This is a real departure from today's `bot-bottle start`
 semantics (which couples bottle lifetime to the process via
 ExitStack). It's intentional: the dashboard is a watching +
 acting surface, not a lifetime owner.
@@ -322,7 +322,7 @@ Sized for one PR each.
   dashboard's ExitStack; handoff invokes `attach_agent`.
 3. **Re-attach via Enter on owned agents-pane row.** Looks up
   the slug in the dashboard's `bottles` map; if present →
-   handoff; else → status-line hint pointing at `./cli.py
+   handoff; else → status-line hint pointing at `bot-bottle
   resume`.
 4. **Explicit per-bottle stop (`x` keybinding).** Pop the
   bottle's `close` callback off the stack, call it, refresh.
@@ -369,7 +369,7 @@ Sized for one PR each.
   bottles dict goes out of scope without invoking `__exit__`,
   so the `docker compose` projects keep running. Bottle
   teardown is always explicit: per-bottle `x` (for
-   dashboard-owned), or `./cli.py cleanup` (for everything).
+   dashboard-owned), or `bot-bottle cleanup` (for everything).

 ## Open questions

@@ -46,7 +46,7 @@ window, two panes, no terminal handoff.

 ## Goals / Success Criteria

-1. When the operator runs `./cli.py dashboard` from inside a
+1. When the operator runs `bot-bottle dashboard` from inside a
   tmux session (`$TMUX` set), the dashboard establishes a
   two-pane layout: dashboard in the left pane, an initially-
   empty right pane reserved for claude sessions.
@@ -313,7 +313,7 @@ Sized small.
 3. **Dashboard launched OUTSIDE tmux but tmux is installed.**
   Should the dashboard auto-exec itself inside a fresh tmux
   session to get the split-pane experience? Convenient but
-   surprising (`./cli.py dashboard` shouldn't silently
+   surprising (`bot-bottle dashboard` shouldn't silently
   change what session you're in). v1 leaves this off —
   operators who want split-pane mode start tmux themselves
   and then run the dashboard.
@@ -332,7 +332,7 @@ Sized small.
   PRD-0019 focus indicator?

 6. **Concurrent dashboards in different tmux windows.**
-   Multiple `./cli.py dashboard` invocations in different
+   Multiple `bot-bottle dashboard` invocations in different
   tmux windows would each create their own right pane —
   probably fine, each has its own state, but worth
   verifying that `tmux list-panes` is scoped to the right
@@ -14,7 +14,7 @@ Today bot-bottle is hard-wired around Claude Code assumptions. When Claude runs

 ## Goals / Success Criteria

- A Codex agent can be started from the dashboard and via `./cli.py start` alongside a Claude agent.
+- A Codex agent can be started from the dashboard and via `bot-bottle start` alongside a Claude agent.
 - The manifest can express the agent provider/template and, where needed, a custom agent Dockerfile.
 - Claude-specific default egress/auth behavior is no longer implicit; provider-specific auth is expressed through explicit bottle egress routes and roles.
 - The launcher preserves required infrastructure behavior for sidecars, egress, pipelock, supervisor MCP, CA handling, git, and shell basics.
@@ -30,7 +30,7 @@ across every bottle spin-up. This has several consequences:
  to grant that access.
 - **Manual rotation burden.** Operators must manage key files on disk, keeping
  them secure, rotating them on a schedule, and distributing them across hosts
-  that run `./cli.py start`.
+  that run `bot-bottle start`.

 ## Goals / Success Criteria

@@ -6,7 +6,7 @@

 ## Summary

-The `./cli.py dashboard` command has grown from its PRD 0013 roots
+The `bot-bottle dashboard` command has grown from its PRD 0013 roots
 (triage supervise proposals) into a parallel-agent control surface
 (PRDs 0019/0020/0021): an active-agents pane, agent picker + start,
 re-attach, per-bottle stop, tmux split-pane handoff, operator-
@@ -21,7 +21,7 @@ proposals, approve / modify / reject each one, write audit entries,
 deliver the response that unblocks the agent's tool call. Everything
 that's about *starting / re-entering / stopping* bottles, or about
 *operator-initiated* config edits, comes out. The command is renamed
-`./cli.py supervise` so the name matches what it does after the cut.
+`bot-bottle supervise` so the name matches what it does after the cut.

 Future agent-management UX is explicitly punted: if and when a
 control surface for parallel agents resurfaces, the working
@@ -41,9 +41,9 @@ Three concrete pains, all downstream of the dashboard's growth:
  ExitStack-free bottle ownership are intricate enough that
  shipping the next polish increment costs more than it returns.
 2. **No clear ownership of "starts and stops bottles".** Today
-  that responsibility is split: `./cli.py start` owns one-shot
+  that responsibility is split: `bot-bottle start` owns one-shot
  sessions; the dashboard owns multi-session bottles it started
-  itself; `./cli.py cleanup` owns everything else. The dashboard
+  itself; `bot-bottle cleanup` owns everything else. The dashboard
  tracking its own `bottles: dict[str, (cm, bottle, identity)]`
  that doesn't survive a quit is a confusing third lane.
 3. **Wrong target shape for a "manage many agents" UI.** The
@@ -97,12 +97,12 @@ problem is everything that got bolted onto that core after.
  dashboard. After this PRD they don't exist anywhere — operators
  who need ad-hoc edits use the same path the agents do (call the
  supervise tool from inside the bottle) or hand-edit the host-
-  side files and restart the sidecar. Adding a `./cli.py routes
+  side files and restart the sidecar. Adding a `bot-bottle routes
  edit <slug>` verb is a follow-up if the loss bites.
- **Removing `./cli.py start` or changing its semantics.** Start
+- **Removing `bot-bottle start` or changing its semantics.** Start
  remains the one-shot launch path. PRD 0020's bottle-outlives-
  process model is removed; the only path to a long-running
-  bottle is `./cli.py start` (foreground) plus `cli.py cleanup`
+  bottle is `bot-bottle start` (foreground) plus `cli.py cleanup`
  for teardown.
 - **Removing the supervise-sidecar protocol or any of the three
  block-remediation engines.** PRDs 0013–0016 stay Active. The
@@ -122,8 +122,8 @@ problem is everything that got bolted onto that core after.

 ### In scope

- **Rename the subcommand.** `./cli.py dashboard` becomes
-  `./cli.py supervise`. The module moves from `bot_bottle/cli/
+- **Rename the subcommand.** `bot-bottle dashboard` becomes
+  `bot-bottle supervise`. The module moves from `bot_bottle/cli/
  dashboard.py` to `bot_bottle/cli/supervise.py`. The dispatcher
  in `bot_bottle/cli/__init__.py` and the help text both update.
 - **Strip the curses loop to proposal-only.** The remaining
@@ -167,7 +167,7 @@ problem is everything that got bolted onto that core after.

 - Any new feature in the supervise TUI. The cut is purely
  subtractive (except for the rename).
- Behavior changes in `./cli.py start`, `cli.py cleanup`,
+- Behavior changes in `bot-bottle start`, `cli.py cleanup`,
  `cli.py resume`, `cli.py list`, `cli.py info`, `cli.py edit`,
  `cli.py init` — unchanged.
 - Changes to the supervise sidecar (`supervise_server.py`,
@@ -181,7 +181,7 @@ problem is everything that got bolted onto that core after.

 ### Final shape of the TUI

-After this PRD the `./cli.py supervise` curses surface is:
+After this PRD the `bot-bottle supervise` curses surface is:

 ```
 bot-bottle supervise  (3 pending)
@@ -307,8 +307,8 @@ The PR closes issue #174.

 1. **`e` / `p` operator-initiated edits — gone for good or
  moved to a separate CLI verb?** The PRD removes them with no
-  replacement. The simplest replacement is `./cli.py routes
-  edit <slug>` and `./cli.py pipelock edit <slug>`, sharing
+  replacement. The simplest replacement is `bot-bottle routes
+  edit <slug>` and `bot-bottle pipelock edit <slug>`, sharing
  the existing `apply_routes_change` / `apply_allowlist_change`
  engines. If the loss is felt within the first parallel
  run after this lands, that follow-up is a small PR. Leaving
@@ -7,12 +7,12 @@

 ## Summary

-When `./cli.py start` is run without an agent name, or without a backend
+When `bot-bottle start` is run without an agent name, or without a backend
 explicitly specified, the user currently gets an argparse error (missing
 positional) or falls through to the `docker` default silently. This PRD
 adds a terminal UI that appears in those gaps: a filter-select screen
 built with `curses` that lets the operator pick the agent and/or backend
-interactively rather than memorising names or consulting `./cli.py list`.
+interactively rather than memorising names or consulting `bot-bottle list`.

 ## Problem

@@ -29,15 +29,15 @@ visible.

 ## Goals / Success Criteria

-1. `./cli.py start` (no arguments) shows an interactive agent selector;
+1. `bot-bottle start` (no arguments) shows an interactive agent selector;
   the selected name is used exactly as if it had been passed on the
   command line.
-2. `./cli.py start <name>` (no `--backend`, no `BOT_BOTTLE_BACKEND`)
+2. `bot-bottle start <name>` (no `--backend`, no `BOT_BOTTLE_BACKEND`)
   shows an interactive backend selector; the selected backend is used
   exactly as if `--backend=<selected>` had been passed.
-3. `./cli.py start <name> --backend=<b>` (both explicit) shows neither
+3. `bot-bottle start <name> --backend=<b>` (both explicit) shows neither
   screen — no behavioural change from today.
-4. `./cli.py start` (no arguments, no env backend) shows the agent
+4. `bot-bottle start` (no arguments, no env backend) shows the agent
   selector first, then the backend selector.
 5. The filter-select widget is a standalone utility
   (`bot_bottle/cli/tui.py`) shared by both selectors.
@@ -57,7 +57,7 @@ visible.
 - No pagination beyond what fits in the terminal window (scroll via
  cursor movement is sufficient for typical agent counts).
 - No multi-select; exactly one item is chosen per invocation.
- No changes to `./cli.py resume`, `./cli.py list`, or any other
+- No changes to `bot-bottle resume`, `bot-bottle list`, or any other
  subcommand.

 ## Design
@@ -83,7 +83,7 @@ def filter_select(

 The widget renders to the tty file descriptor opened via `curses.initscr`
 (or `curses.newterm` on the tty fd so stdout remains clean for callers
-that pipe `./cli.py`).
+that pipe `bot-bottle`).

 Layout (full-width, minimal):

@@ -140,7 +140,7 @@ agent picker can populate itself from the real manifest. The same
 `filter_select` opens `/dev/tty` and feeds it as the input file to
 `curses.wrapper`-equivalent code (using `curses.newterm` to avoid
 clobbering the caller's stdout/stderr). This keeps the picker
-composable — callers can pipe `./cli.py` output without the curses
+composable — callers can pipe `bot-bottle` output without the curses
 draw sequences contaminating the pipe.

 ## Implementation chunks
@@ -30,12 +30,12 @@ snapshot before a planned host reboot or hardware migration.

 ## Goals / Success Criteria

- `./cli.py commit [<slug>]` takes a snapshot of the running agent and
+- `bot-bottle commit [<slug>]` takes a snapshot of the running agent and
  stores it as a local artifact.
 - Without a slug argument the command shows the same interactive picker
  as `start` (the list of active slugs).
 - The committed artifact reference is stored in per-bottle state so
-  that the next `./cli.py resume <slug>` automatically uses the
+  that the next `bot-bottle resume <slug>` automatically uses the
  snapshot instead of rebuilding from the Dockerfile.
 - `mark_preserved` is called so the state dir survives the normal
  session-end cleanup.
@@ -81,7 +81,7 @@ to the committed `.smolmachine` artifact.
 ### `commit` command

 ```
-./cli.py commit [<slug>]
+bot-bottle commit [<slug>]
 ```

 1. Resolve slug (arg or interactive picker from `enumerate_active_agents`).
@@ -37,7 +37,7 @@ egress policy), the operator must duplicate the agent file and change the
   selection order, as the effective bottle for the session.
 5. Confirming with an empty selection falls back to the agent's `bottle:` field.
   If neither is set, a ManifestError is raised pointing the operator at the fix.
-6. The ordered bottle list is stored in launch metadata so `./cli.py resume`
+6. The ordered bottle list is stored in launch metadata so `bot-bottle resume`
   uses the same bottles.
 7. The preflight summary (`y/N` screen) shows the effective bottle name(s).
 8. The multi-select picker supports incremental filtering, Space/Enter to toggle
@@ -52,7 +52,7 @@ egress policy), the operator must duplicate the agent file and change the
 - Reordering the selection list from within the picker (order = insertion order;
  drag-and-drop is out of scope).
 - Storing bottle selection history / MRU.
- Changes to `./cli.py edit`, `./cli.py list`, or `./cli.py info`.
+- Changes to `bot-bottle edit`, `bot-bottle list`, or `bot-bottle info`.
 - Removing the `bottle:` key from the agent schema (it stays, now optional).

 ## Design
@@ -74,7 +74,7 @@ macOS-only for v1. Three concrete blockers:

 ## Goals / Success Criteria

- `BOT_BOTTLE_BACKEND=smolmachines ./cli.py start <agent>` launches,
+- `BOT_BOTTLE_BACKEND=smolmachines bot-bottle start <agent>` launches,
  runs, and tears down a bottle on a Linux host with `/dev/kvm`.
 - The TSI allowlist is enforced on Linux: PRD 0022's
  `tests/integration/test_sandbox_escape.py` passes against
@@ -39,7 +39,7 @@ end-to-end runner that would catch the *next* macOS-only launch regression.)
 PR #470 (#414) already made the integration suite backend-agnostic:
 `skip_unless_selected_backend_available()` gates on the *selected* backend's
 own `is_backend_ready()` rather than `docker_available()`, and each
-integration job runs `./cli.py backend status --backend=<name>` as a preflight
+integration job runs `bot-bottle backend status --backend=<name>` as a preflight
 that fails loudly when the backend is missing. That is the machinery this job
 plugs into; this PRD supplies the runner and the job.

@@ -98,7 +98,7 @@ Modeled on `integration-firecracker`:
 - `concurrency: { group: integration-macos-infra, cancel-in-progress: false }`
  to serialize runs against the singleton.
 - **Preflight** — `command -v container`, `container system status`, then
-  `./cli.py backend status --backend=macos-container`; any failure exits
+  `bot-bottle backend status --backend=macos-container`; any failure exits
  non-zero so a misprovisioned runner fails loudly instead of silently
  skipping.
 - Run the integration suite under coverage with
@@ -16,7 +16,7 @@ verifies host prerequisites after install.
 ## Problem

 There is currently no install path for new users. The only way to run
-bot-bottle is to clone the repo and invoke `./cli.py`. This blocks any
+bot-bottle is to clone the repo and invoke `bot-bottle`. This blocks any
 public demo: readers want `curl | sh` or `pipx install`, not a manual
 clone-and-configure flow. There is also no single command that tells a
 user whether their host is actually ready to run a bottle.
@@ -0,0 +1,117 @@
+# PRD 0081: Reprovision gateway-dependent state on gateway bring-up
+
+- **Status:** Active
+- **Author:** claude
+- **Created:** 2026-07-26
+- **Issue:** #516
+
+## Summary
+
+When the gateway is (re)built, reconcile every already-running bottle against the
+fresh gateway instead of persisting the gateway's state. On a gateway cold boot,
+the gateway reconciles all live bottles in one flow: **replace** each agent's
+trusted CA with the freshly-minted gateway CA, **re-provision** each bottle's
+git-gate repos + creds onto the gateway, and **restore** each bottle's egress
+tokens. One mechanism across all three services; the CA rotates for free on every
+bring-up.
+
+## Problem
+
+A gateway rebuild/restart silently breaks every already-running bottle:
+
+- **CA (#510).** The gateway's mitmproxy mints a new CA on a fresh rootfs; agents
+  still trust the old one, so egress fails TLS verification (`SSL certificate
+  verification failed`).
+- **git-gate (#512).** Per-bottle bare repos (`/git/<id>`) + deploy creds
+  (`/git-gate/creds/<id>`) live in the gateway's ephemeral rootfs; a rebuild wipes
+  them and the agent 404s on fetch/push.
+
+Both are the same root cause: per-bottle gateway-dependent state is provisioned
+**once, at bottle launch**, and nothing restores it for already-running bottles
+when the gateway comes back. The existing launch-time reprovision
+(`reprovision_bottles`) restores **only** egress tokens, and only as a side effect
+of the *next* launch.
+
+Persisting the state (a host bind-mount / a per-VM data volume per service) was
+prototyped and rejected: it differs per service (a volume for the CA, another for
+git-gate, reprovision for tokens), it pins the CA static forever (no rotation),
+and it adds volume surface that `docker volume prune` / a wiped cache can silently
+destroy (the original #450 failure mode).
+
+## Goals / Success Criteria
+
+- A gateway (re)boot restores **all** running bottles' gateway-dependent state
+  with no manual step and no relaunch — the agent's next egress / fetch / push
+  just works.
+- **One** reconcile flow covering CA, git-gate, and egress tokens, rather than a
+  different mechanism per service.
+- The CA **rotates** on every gateway bring-up (no long-lived CA), distributed to
+  running agents by the same reconcile.
+- Per-bottle failures are tolerated: one unreachable or malformed bottle does not
+  block the others or the gateway coming up.
+- **All backends** (Firecracker, docker, macOS) reconcile through the *same*
+  contract — an abstract method on the backend base class, so a new backend
+  cannot forget to implement it and none drifts onto a bespoke mechanism.
+
+## Non-goals
+
+- Deliberate mid-session CA rotation *without* a gateway restart — `rotate_ca`
+  stays for that operator action.
+- Changing source-IP attribution, `/resolve`, or the plane split (#469).
+
+## Design
+
+**The contract — `attach_bottled_agents_to_gateway()` on the backend ABC.**
+Reconciling running bottles against the current gateway is a backend
+responsibility (only the backend can enumerate its agents and reach them —
+firecracker over SSH, docker/macOS over `exec`/`cp`), so it is an
+`@abc.abstractmethod` on `BottleBackend` (`backend/base.py`). Every backend
+implements it; the host calls it whenever the gateway is (re)brought up. This is
+what makes the fix cross-backend by construction rather than a per-backend
+follow-up. It reprovisions **all** registered bottles' gateway-dependent state:
+CA, git-gate, and egress tokens.
+
+**Trigger — the gateway bring-up path.** The host calls
+`attach_bottled_agents_to_gateway()` only when the gateway was actually
+(re)brought up — the cold-boot branch of the infra bring-up (e.g.
+`FirecrackerInfraService.ensure_running` after it boots a fresh pair), never on an
+adopt of a healthy, current gateway (state intact). So it fires exactly when the
+gateway was (re)booted — including orchestrator restarts, since the pair boots
+together — and there is no bare-restart path that bypasses bring-up.
+
+**Per-backend implementation.** Each backend's `attach_bottled_agents_to_gateway`
+enumerates its live bottles and, for each, reconciles the three services against
+the current gateway. The firecracker implementation, once the gateway VM is up
+and its CA is available:
+
+1. Map each live bottle's guest IP → `bottle_id` from the orchestrator registry
+   (`list_bottles`).
+2. Install the **current** shared git-gate hooks (`git_gate_render_hook` /
+   `git_gate_render_access_hook`) into the fresh gateway once — rendered from
+   code, never from a bottle's possibly-stale state dir.
+3. For each live agent VM (enumerated from its run dir):
+   - **CA:** SSH the current gateway CA into the agent's trust store and run
+     `update-ca-certificates` (unconditional replace — there is one gateway, so no
+     fingerprint match is needed).
+   - **git-gate:** rebuild the bottle's upstreams from its persisted git-gate
+     state dir (deploy key, known_hosts, upstream URL) and re-init its bare repos
+     + per-repo creds under `/git/<bottle_id>`.
+   - **egress token:** read the agent's `ENV_VAR_SECRET` and feed
+     `reprovision_bottles`, restoring the orchestrator's in-memory tokens.
+4. Every per-bottle step is wrapped so one failure is logged and skipped.
+
+**Retire the persistence prototype.** No CA data volume, no git-gate data volume
+(the abandoned PRs #511 / #513). The launch-time `_reprovision_running_bottles`
+call folds into this bring-up reconcile, so egress tokens are restored on the same
+cold-boot trigger (an adopt needs no restore — the orchestrator never restarted).
+
+**CA rotation.** Because the gateway rootfs is ephemeral, every cold boot mints a
+fresh CA; reconcile is what distributes it, so a routine gateway rebuild doubles
+as a CA rotation with zero extra machinery.
+
+## Open questions
+
+- Docker's existing host-bind-mounted CA (`host_gateway_ca_dir`): once docker's
+  `attach_bottled_agents_to_gateway` pushes the CA to running agents on bring-up,
+  the bind-mount is redundant — drop it (so docker rotates like firecracker) or
+  keep it as belt-and-suspenders? Leaning drop, for one behaviour across backends.
@@ -6,7 +6,7 @@ Can bot-bottle grow a built-in supervisor — TUI inventory plus PR-feedback rou

 ## Context

-bot-bottle today is a fleet *executor*: `./cli.py start <agent>` brings up one bottle (agent container + pipelock + optional git-gate + optional cred-proxy on a per-bottle internal network), and `cli.py` tears it down when the session ends. There is no inventory view, no idle-detection, no automated reaction to PR or CI events. In parallel use, a human is the supervisor — opening one terminal per bottle, switching between them, and watching upstream PR state by hand.
+bot-bottle today is a fleet *executor*: `bot-bottle start <agent>` brings up one bottle (agent container + pipelock + optional git-gate + optional cred-proxy on a per-bottle internal network), and `cli.py` tears it down when the session ends. There is no inventory view, no idle-detection, no automated reaction to PR or CI events. In parallel use, a human is the supervisor — opening one terminal per bottle, switching between them, and watching upstream PR state by hand.

 A separate survey of the broader ecosystem ([agent control dashboards research, mid-2026](https://gitea.dideric.is/didericis/consilium-research/src/branch/main/developer-workflow/agent-control-dashboards-2026-05-24.md)) sorts dashboards into five tiers (session managers, parallel runners, Kanban boards, mission-control SPAs, observability backends). The earlier first-pass conclusion was that a full SPA tier conflicts with bot-bottle's isolation model. This doc reconsiders the smaller question: a TUI supervisor in the existing Python CLI.

@@ -25,13 +25,13 @@ A supervisor doesn't have to be heavy. A TUI built into the existing Python CLI,

 Three layers, each independently useful, in order of ambition:

-### 1. `./cli.py status` — read-only inventory
+### 1. `bot-bottle status` — read-only inventory

 Reads `docker ps` filtered by a bottle label and tails each bottle's session log. Reports per bottle: name, agent, uptime, last-activity timestamp, token spend if available, associated PR/branch if recorded.

 No new daemons. No new ports. No new credentials. ~100 lines.

-### 2. `./cli.py watch` — TUI over the same data
+### 2. `bot-bottle watch` — TUI over the same data

 Same data as `status`, rendered with auto-refresh and keyboard shortcuts that shell out to the existing `cli.py attach / stop / start` commands.

@@ -39,7 +39,7 @@ Library choice: prefer the stdlib `curses` module to stay stdlib-first; fall bac

 This is the Claude Squad / tmux-agent-status pattern, applied to bottles instead of tmux sessions. The whole category exists *because* a TUI is the lightweight shape that doesn't require what the SPA tier requires.

-### 3. `./cli.py supervise` — PR feedback router
+### 3. `bot-bottle supervise` — PR feedback router

 The optional, more ambitious layer. The bottle manifest gains an optional field:

@@ -49,7 +49,7 @@ pr_watch:
  branch: agent/task-42
 ```

-`./cli.py supervise` polls the named upstream for new review comments and CI failures on `branch`. When one fires, it surfaces as a desktop notification or a flash in the TUI. The human decides what to do with the feedback — there is no autonomous loop that feeds the comment back into a bottle's next prompt (see "Where to be conservative" for why).
+`bot-bottle supervise` polls the named upstream for new review comments and CI failures on `branch`. When one fires, it surfaces as a desktop notification or a flash in the TUI. The human decides what to do with the feedback — there is no autonomous loop that feeds the comment back into a bottle's next prompt (see "Where to be conservative" for why).

 The polling token is a **host** token (the same `GH_PAT` / Gitea token the host already keeps in shell env), not a bottle credential. The supervisor never holds bottle secrets.

@@ -62,7 +62,7 @@ The load-bearing question is whether the supervisor introduces the privileged-ch
 | Reaching into running bottles | Supervisor reads `docker ps` and host-side log files. The host already sees both — Docker is the trust boundary, the supervisor is on the host side of it. |
 | Holding bottle credentials | The polling token is a host token. The supervisor never receives `bottle.cred_proxy.routes` entries; it has no path to them. |
 | Bridging between bottles | The supervisor does not relay state from bottle A to bottle B. It relays *upstream PR state* to a bottle's next prompt — and only if the manifest opts in. |
-| New attack surface | All "control" actions go through `./cli.py start <agent>`, which already enforces the manifest. The supervisor is an automated caller of the existing CLI, not a parallel control plane. |
+| New attack surface | All "control" actions go through `bot-bottle start <agent>`, which already enforces the manifest. The supervisor is an automated caller of the existing CLI, not a parallel control plane. |

 The boundary stays at the bottle wall. The supervisor looks outward at git/PR state and downward at Docker; it does not look *inward* through pipelock.

@@ -13,11 +13,11 @@ What's the cheapest path to that, and where does it bottom out?

 ## What "interact" means

-Today the flow is bimodal. `./cli.py start <agent>` brings the
+Today the flow is bimodal. `bot-bottle start <agent>` brings the
 bottle up and immediately drops you into an interactive
 `docker exec -it bot-bottle-<slug> claude ...` — claude-code
 owns the whole terminal until you Ctrl-D out, at which point the
-bottle tears down. The dashboard (`./cli.py dashboard`) is a
+bottle tears down. The dashboard (`bot-bottle dashboard`) is a
 *separate* invocation that watches across bottles but never
 exposes the claude TUI itself.

@@ -107,7 +107,7 @@ What's not good:

 This is the v1 the project's existing code-shape strongly
 prefers. It clears the bar of "let me talk to claude-code
-without quitting `./cli.py dashboard`."
+without quitting `bot-bottle dashboard`."

 ## Option 2: Embedded emulator

@@ -84,7 +84,7 @@ dangerous changes before they left*.
   (`supervise_gitleaks_allow`, [`git_gate_render.py`](../../bot_bottle/git_gate_render.py)).
   Extend the same flow to **high-risk file classes**: any commit touching
   CI/build/deploy scripts, auth/crypto code, egress config, or
-   adding/changing dependencies → route to `./cli.py supervise`. This is
+   adding/changing dependencies → route to `bot-bottle supervise`. This is
   attribution/policy, not detection, and it's the strongest thing here —
   a human on exactly the temporal-escape surfaces.
 4. **LLM semantic diff-review — the behavioral backstop.** The only
@@ -146,7 +146,7 @@ preserves the bottom-up distribution funnel.
  **governed code-egress review**, not "we resell inference" (the
  monetization notes explicitly warn against reselling compute).
 - **The web-console supervise/review flow — the strongest anchor.** Turn
-  the CLI `./cli.py supervise` approval into a real review surface:
+  the CLI `bot-bottle supervise` approval into a real review surface:
  rendered diff + finding context, approve/reject, **who-approved audit
  trail, RBAC on approvers, mobile/phone-control** (ties to the
  dashboard/vault north star). This is "central enforcement +
@@ -100,7 +100,7 @@ resolver globs each directory.
  becomes file ops (mkdir, mv, rm) instead of editing one file.
  Power users prefer that; new users may not.
 - Discovery requires `ls`, not "grep one file." Tooling helps
-  (e.g. `./cli.py list`) but the manifest is no longer a single
+  (e.g. `bot-bottle list`) but the manifest is no longer a single
  artifact to email or ship.
 - Atomicity: swapping a bottle name across agents touches
  multiple files. Git handles this fine; a one-shot text editor
@@ -364,7 +364,7 @@ wins; none of the body-prose or dependency story.
  warns / ignores / breaks. If it warns, we'd want a different
  field name (e.g. `bot-bottle-bottle`) or a namespaced block.
 - **Migration story.** Is the project willing to ship a one-shot
-  `./cli.py migrate-manifest` command that does the JSON → MD
+  `bot-bottle migrate-manifest` command that does the JSON → MD
  conversion? Or do users just rewrite by hand from the new docs?
 - **Bottle file body content.** If most bottle .md files have an
  empty body, is the MD-with-frontmatter format still warranted?
@@ -34,7 +34,7 @@ on top of working onboarding.

 A first-time user today goes through five steps: install Docker,
 install `uv`, set `BOT_BOTTLE_CLAUDE_OAUTH_TOKEN`, write
-`bot-bottle.json`, run `./cli.py start`. One of those is
+`bot-bottle.json`, run `bot-bottle start`. One of those is
 "author a JSON manifest." Polished tools in this category let
 users skip that step on day one. The fix is an `init` subcommand
 that drops a working `bot-bottle.json` with a default `coder`
@@ -131,7 +131,7 @@ The minimum-viable workflow, no bot-bottle code changes:
 3. SSH in.
 4. `git clone` bot-bottle on the VM, drop a manifest in place,
   inject `BOT_BOTTLE_CLAUDE_OAUTH_TOKEN` via the provider's secrets path.
-5. `./cli.py start <agent>` — the existing launcher handles the rest.
+5. `bot-bottle start <agent>` — the existing launcher handles the rest.
 6. On exit: destroy the VM. No host artifacts persist.

 For the "VPN pivot" failure mode, see
@@ -0,0 +1,305 @@
+# 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` **service state** | per-user: `~/Library/Application Support/com.apple.container/` (`container system start`) | ✅ | ❌ removed with home |
+| **Homebrew** (if used for `container`/python) | `/opt/homebrew` | ❌ | ✅ **stays** |
+| Rosetta 2 (needed for image builds) | system | ❌ | ✅ **stays** |
+
+The bold rows are the crux: **deleting the throwaway user does not uninstall
+the Apple Container runtime, Homebrew, or Rosetta.** A VM, by contrast, wipes
+100% of the above by definition — that's its entire advantage for this task.
+
+The service row is the exception, and a live harness run corrected it: the
+Apple `container` service is **per-user**, not a host-wide launchd service.
+`container system status` reports an `appRoot` under
+`~/Library/Application Support/com.apple.container/`, and a freshly created
+account sees `container system service: NOT running` even while the creating
+admin's is running. That cuts both ways — the state is genuinely removed with
+the home, so the reset is *more* complete than this table first claimed, but
+it also means **no brand-new user can run a bottle until they run
+`container system start` once**. `doctor` correctly fails until they do, which
+is why `test` judges backend readiness separately from install correctness.
+
+## 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.
+
+There are two one-shot cycles, because "does the installer work" and "can a new
+user actually run a bottle" are different questions:
+
+```sh
+sudo ./scripts/macos-install-test.sh test        # up → run → status → down
+sudo ./scripts/macos-install-test.sh test-ready  # ... + prereqs before status
+```
+
+`test` models a macOS system **without** the prerequisites set up for this user
+— which is the default state of every new account, since the `container`
+service is per-user. It asserts the install is sound and *reports* backend
+readiness without failing on it, because install.sh provides no backend and so
+cannot regress one.
+
+`test-ready` models a system **with** them, then demands doctor go fully green,
+backend included. Both variants pass as of this writing.
+
+### The per-user prerequisite is two steps, not one
+
+Running it revealed that "set up the backend for this account" is more than
+starting a service:
+
+1. **`container system start`** — the service is per-user. The run confirms it
+   directly: the throwaway account's `appRoot` is
+   `/Users/bbtest/Library/Application Support/com.apple.container/`, its own,
+   and starting it left the admin's service untouched.
+2. **A guest kernel**, which also lives in that per-user app root. A fresh
+   account has none, so `container system start` prompts to download one —
+   and *only* prompts, since the flags default to asking. Headless callers
+   must pass `--enable-kernel-install` or the command dies on
+   `failed to read user input`.
+
+Neither step is done by `bot-bottle backend setup --backend=macos-container`,
+which only checks and then tells you to run `container system start` yourself.
+So a new account's real path to a working backend is:
+`container system start --enable-kernel-install`.
+
+The harness must also enter the user's launchd domain via
+`launchctl asuser <uid>` to do any of this. `container system start` registers
+`com.apple.container.apiserver` as a per-user launchd agent and talks to it
+over XPC; from plain `sudo -u` the caller is still in root's bootstrap
+namespace, the lookup crosses domains, and the apiserver answers
+`invalidState: "unauthorized request"` even though the agent started fine.
+
+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,14 +8,20 @@
 #   pipx install bot-bottle        # from a checkout or a published index
 #   uv tool install bot-bottle
 #
-# This script is a thin bootstrapper: it checks prerequisites, installs the
-# package with pipx (falling back to pip --user), creates the config dir, and
-# runs `bot-bottle doctor`. It is idempotent (safe to re-run) and never uses
-# sudo. It does NOT install Docker or a VM backend for you — `doctor` reports
-# what's missing after install.
+# 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)
 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

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

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

-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"
+# 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
 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
@@ -51,30 +137,6 @@ 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 \
@@ -84,32 +146,50 @@ mkdir -p \

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

+BIN_DIR="${HOME}/.local/bin"
+
 if command -v pipx >/dev/null 2>&1; then
-    say "installing with pipx"
-    pipx install --force "${PACKAGE_SPEC}"
+    # --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}"
 else
-    say "pipx not found; installing with 'python3 -m pip install --user'"
-    python3 -m pip install --user --upgrade "${PACKAGE_SPEC}"
+    # 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"
 fi

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

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

 # --- verify ------------------------------------------------------------------
@@ -9,7 +9,7 @@
 #
 # Why a pool + one-time setup: creating a TAP and assigning it an IP
 # needs CAP_NET_ADMIN. Pre-creating user-owned, pre-addressed TAPs
-# means `./cli.py start` never needs root. The nft table is static
+# means `bot-bottle start` never needs root. The nft table is static
 # (keyed on the `bbfc*` interface wildcard), so it covers every slot
 # without per-launch changes.
 #
@@ -0,0 +1,531 @@
+#!/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 test-ready  # ... with prereqs satisfied
+#   sudo ./scripts/macos-install-test.sh up          # create the throwaway user
+#   sudo ./scripts/macos-install-test.sh run         # run install.sh (+doctor) as it
+#   sudo ./scripts/macos-install-test.sh prereqs     # start the per-user backend svc
+#        ./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`
+#
+# TWO TEST VARIANTS, because "does the installer work" and "can a new user
+# actually run a bottle" are different questions with different answers:
+#
+#   test        A macOS system WITHOUT the prerequisites set up for this user —
+#               the default state of any brand-new account, since the Apple
+#               `container` service is per-user. Asserts the INSTALL is sound
+#               (entry point present, doctor runs without crashing, python and
+#               config check out). Backend readiness is reported, not required:
+#               install.sh does not provide a backend and cannot regress one,
+#               so failing on it would make this permanently red.
+#
+#   test-ready  A macOS system WITH the prerequisites satisfied — it starts the
+#               per-user `container` service (and installs its guest kernel)
+#               for the throwaway user first, then demands doctor go fully
+#               green, backend included. This is the end-to-end claim: a new
+#               user can actually run a bottle. Note it downloads a guest
+#               kernel per run, because the previous run's went with the
+#               deleted home; BB_TEST_KERNEL_INSTALL=0 skips that.
+#
+# Both refuse to start if the account already exists (a reused home is not a
+# clean install), and both tear the account down on the way out however they
+# exit, so a failed run never leaves an orphan behind. install.sh itself exits
+# 0 when doctor reports unmet prerequisites, so either variant 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
+#   BB_TEST_REQUIRE_BACKEND  1=`test` also fails when no backend is ready
+#   BB_TEST_KERNEL_INSTALL   0=`test-ready` skips the guest-kernel download
+#   BB_TEST_REPO_URL     https repo the throwaway user clones (default: this one)
+#   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}"
+# https, not the ssh `origin`: the throwaway user has no key of ours.
+BB_TEST_REPO_URL="${BB_TEST_REPO_URL:-https://gitea.dideric.is/didericis/bot-bottle.git}"
+
+_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; }
+
+user_uid() {
+    dscl . -read "/Users/$USER_NAME" UniqueID 2>/dev/null | awk '{print $2}'
+}
+
+# Whether we can enter the target user's launchd domain.
+#
+# This matters more than it sounds. `container system start` registers
+# com.apple.container.apiserver as a per-USER launchd agent and then talks to
+# it over XPC. Under plain `sudo -u` the caller is still in root's bootstrap
+# namespace, so the lookup crosses domains and the apiserver answers
+#     invalidState: "unauthorized request"
+# even though it launched fine. `launchctl asuser <uid>` puts the whole
+# invocation in that user's domain, which is also what a real user gets from
+# Terminal — so it is the more faithful way to run *everything* here, not just
+# the service start. Falls back to plain sudo when unavailable, since a
+# never-logged-in account may have no bootstrappable domain at all.
+_SESSION_OK=""
+user_session_available() {
+    if [ -z "$_SESSION_OK" ]; then
+        local uid
+        uid="$(user_uid)"
+        if [ -n "$uid" ] && launchctl asuser "$uid" true >/dev/null 2>&1; then
+            _SESSION_OK=1
+        else
+            _SESSION_OK=0
+        fi
+    fi
+    [ "$_SESSION_OK" = "1" ]
+}
+
+# Run a shell snippet as the throwaway user in a fresh login shell.
+#
+# The snippet goes in on stdin, never as an argument. `sudo -i` joins its argv
+# into a single string and hands that to the login shell's -c, so quoting in an
+# argument is not preserved and a newline ends the command outright ("sh: -c:
+# line 1: syntax error: unexpected end of file"). Feeding `sh -s` from stdin
+# sidesteps the joining entirely and lets snippets be multi-line.
+run_as_user() {
+    if user_session_available; then
+        printf '%s\n' "$1" | launchctl asuser "$(user_uid)" sudo -u "$USER_NAME" -i sh -s
+    else
+        printf '%s\n' "$1" | sudo -u "$USER_NAME" -i sh -s
+    fi
+}
+
+# `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's own exit code conflates two unrelated things: whether the install
+# works, and whether this user has a backend ready to run a bottle. Those need
+# different verdicts here. install.sh explicitly does not install a backend,
+# and the Apple `container` service is per-USER — its state lives in
+# ~/Library/Application Support/com.apple.container — so a brand-new account
+# never has one running, no matter how correct the install is. Failing on that
+# would leave `test` permanently red for something the installer cannot fix
+# and cannot regress. So: assert the install, report the backend.
+# BB_TEST_REQUIRE_BACKEND=1 makes backend readiness fatal too.
+doctor_as_user() {
+    local out rc=0 bad=0
+    out="$(mktemp "${TMPDIR:-/tmp}/bb-doctor.XXXXXX")"
+    # 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 bot-bottle "$HOME/.local/bin/bot-bottle" "$HOME/.bot-bottle/venv/bin/bot-bottle"; do
+            if command -v "$bb" >/dev/null 2>&1; then
+                case "$bb" in
+                    bot-bottle) : ;;
+                    *) echo "  (not on PATH — running $bb directly, as install.sh advises)" ;;
+                esac
+                exec "$bb" doctor
+            fi
+        done
+        echo "  no bot-bottle entry point found for this user" >&2
+        exit 1
+    ' >"$out" 2>&1 || rc=$?
+    cat "$out"
+
+    # An unhandled exception is always an install/product defect, never an
+    # environment fact — this is exactly how the PermissionError on `ip` showed
+    # up, and doctor's non-zero exit alone would not have distinguished it.
+    if grep -q 'Traceback (most recent call last)' "$out"; then
+        echo "  doctor crashed (traceback above) — a defect, not a missing prerequisite" >&2
+        bad=1
+    fi
+    grep -qE '^ok: +python:' "$out" \
+        || { echo "  doctor never reported a usable python" >&2; bad=1; }
+    grep -qE '^ok: +config:' "$out" \
+        || { echo "  doctor never reported a usable config dir" >&2; bad=1; }
+    if [ "$rc" -ne 0 ] && ! grep -qE '^(fail|warn): +backend' "$out"; then
+        echo "  doctor failed for something other than backend readiness" >&2
+        bad=1
+    fi
+
+    local backend_ready=1
+    grep -qE '^fail: +backend' "$out" && backend_ready=0
+    rm -f "$out"
+
+    [ "$bad" -eq 0 ] || return 1
+    if [ "$backend_ready" -eq 0 ]; then
+        if [ "${BB_TEST_REQUIRE_BACKEND:-0}" = "1" ]; then
+            echo "  no backend is ready and BB_TEST_REQUIRE_BACKEND=1" >&2
+            return 1
+        fi
+        echo "  note: install is sound; no backend ready for this user."
+        echo "        Expected on a fresh account — the Apple 'container' service is"
+        echo "        per-user and needs one 'container system start'. Set"
+        echo "        BB_TEST_REQUIRE_BACKEND=1 to treat this as a failure."
+    fi
+    return 0
+}
+
+# --- 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
+}
+
+# The package spec to install. install.sh's own default is the repo's DEFAULT
+# BRANCH, which would mean piping this checkout's installer into the throwaway
+# user and then installing main's code — verifying the PR's install.sh against
+# a package that doesn't contain the PR. Pin to the branch under test instead.
+#
+# The branch has to be pushed: the throwaway user clones over https and cannot
+# read this checkout (mode-700 home, and no SSH key for the ssh remote), so
+# what it gets is whatever the remote has. Say so when that differs from here.
+resolve_install_spec() {
+    if [ -n "${BOT_BOTTLE_INSTALL_SPEC:-}" ]; then
+        echo "$BOT_BOTTLE_INSTALL_SPEC"
+        return 0
+    fi
+    local branch
+    branch="$(git -C "$_REPO_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null)" || branch=""
+    if [ -z "$branch" ] || [ "$branch" = "HEAD" ]; then
+        echo "note: not on a named branch; installing the repo default" >&2
+        echo "git+${BB_TEST_REPO_URL}"
+        return 0
+    fi
+    if [ -n "$(git -C "$_REPO_ROOT" status --porcelain 2>/dev/null)" ]; then
+        echo "warning: working tree is dirty — the throwaway user installs" >&2
+        echo "         $branch as pushed, not what is on disk here." >&2
+    elif ! git -C "$_REPO_ROOT" diff --quiet "@{upstream}" 2>/dev/null; then
+        echo "warning: $branch differs from its upstream — push first, or the" >&2
+        echo "         throwaway user installs stale code." >&2
+    fi
+    echo "git+${BB_TEST_REPO_URL}@${branch}"
+}
+
+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
+    spec="$(resolve_install_spec)"
+
+    echo "== installing bot-bottle as $USER_NAME =="
+    echo "== spec: $spec =="
+    if [ -n "${BB_TEST_INSTALL_URL:-}" ]; then
+        run_as_user "BOT_BOTTLE_INSTALL_SPEC='$spec' curl -fsSL '$BB_TEST_INSTALL_URL' | 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.
+        #
+        # The spec is prepended to the stream as an export rather than passed
+        # as an argument, for the same argv-joining reason as run_as_user.
+        {
+            printf "export BOT_BOTTLE_INSTALL_SPEC='%s'\n" "$spec"
+            cat "$_REPO_ROOT/install.sh"
+        } | sudo -u "$USER_NAME" -i sh -s
+    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."
+}
+
+# Satisfy the throwaway user's backend prerequisites.
+#
+# `bot-bottle backend setup --backend=macos-container` deliberately does NOT do
+# this: it only checks, then tells you to run `container system start` yourself
+# (see backend/macos_container/setup.py — "no privileged host setup required").
+# So the harness runs the command the product asks for, as the user who needs
+# it, which is the whole prerequisite for the macOS backend given the CLI is
+# already installed host-wide.
+cmd_prereqs() {
+    require_macos
+    require_root prereqs
+    user_exists || { echo "error: $USER_NAME does not exist" >&2; return 1; }
+    command -v container >/dev/null 2>&1 || {
+        echo "error: the Apple 'container' CLI is not on PATH. It is a HOST" >&2
+        echo "  prerequisite this harness does not install; see the header." >&2
+        return 1
+    }
+    echo "starting the per-user Apple 'container' service for $USER_NAME"
+    user_session_available || {
+        echo "warning: no launchd session for $USER_NAME; the service start is" >&2
+        echo "  likely to fail with 'unauthorized request'. See user_session_available." >&2
+    }
+    # The kernel flag is not optional for a headless run. `container system
+    # start` PROMPTS for the default Linux kernel when neither flag is given
+    # ("default: prompt user"), and a throwaway account has no kernel because
+    # it lives in the per-user app root — so the prompt always fires here and
+    # dies on "failed to read user input" with no TTY.
+    #
+    # Enabling it is also the honest choice for what this variant claims: the
+    # backend cannot actually run a bottle without a guest kernel. The cost is
+    # that every test-ready run downloads one afresh, since the previous run's
+    # copy went with the deleted home. BB_TEST_KERNEL_INSTALL=0 skips the
+    # download when you only care that the service comes up.
+    local kernel_flag=--enable-kernel-install
+    [ "${BB_TEST_KERNEL_INSTALL:-1}" = "0" ] && kernel_flag=--disable-kernel-install
+    echo "  ($kernel_flag)"
+    run_as_user "container system start $kernel_flag" || {
+        echo "error: 'container system start' failed for $USER_NAME" >&2
+        echo "  invalidState/\"unauthorized request\" means the CLI could not reach" >&2
+        echo "    its per-user apiserver over XPC — a never-GUI-logged-in account may" >&2
+        echo "    have no usable launchd domain; log into $USER_NAME once to get one." >&2
+        echo "  A download failure means the guest kernel could not be fetched; retry" >&2
+        echo "    with network, or BB_TEST_KERNEL_INSTALL=0 to skip it." >&2
+        return 1
+    }
+    run_as_user 'container system status' || {
+        echo "error: the service is still not running for $USER_NAME" >&2
+        return 1
+    }
+}
+
+# Teardown half of the test cycles, installed as an EXIT trap the moment the
+# account exists so 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 "== [$_STEPS/$_STEPS] down: SKIPPED (BB_TEST_KEEP=1) =="
+        echo "   $USER_NAME is still around; remove it with: sudo $0 down"
+        exit "$rc"
+    fi
+    echo
+    echo "== [$_STEPS/$_STEPS] down =="
+    cmd_down || rc=1
+    if [ "$rc" -eq 0 ]; then
+        echo
+        echo "PASS: $_PASS_CLAIM"
+    else
+        echo
+        echo "FAIL: see above (the throwaway account was torn down regardless)." >&2
+    fi
+    exit "$rc"
+}
+
+# The two variants differ only in whether the backend prerequisites get
+# satisfied before doctor runs, which is exactly the question each one asks:
+#
+#   test        a brand-new user on a machine where nothing has been set up for
+#               them. Asserts the INSTALL is sound; backend readiness is
+#               reported, not required, because install.sh does not provide a
+#               backend and cannot regress one.
+#   test-ready  the same user with the documented prerequisites satisfied.
+#               Asserts doctor goes fully green, backend included — the
+#               end-to-end "a new user can actually run a bottle" claim.
+_test_cycle() {
+    local with_prereqs="$1"
+    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/$_STEPS] up =="
+    cmd_up
+    trap _test_teardown EXIT INT TERM
+
+    echo
+    echo "== [2/$_STEPS] run =="
+    cmd_run
+
+    if [ "$with_prereqs" = 1 ]; then
+        echo
+        echo "== [3/$_STEPS] prereqs =="
+        cmd_prereqs || {
+            echo "error: could not satisfy the backend prerequisites (see above)." >&2
+            return 1
+        }
+    fi
+
+    echo
+    echo "== [$((_STEPS - 1))/$_STEPS] 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_test() {
+    _STEPS=4
+    _PASS_CLAIM="a brand-new user can install bot-bottle; the install is sound."
+    _test_cycle 0
+}
+
+cmd_test_ready() {
+    _STEPS=5
+    _PASS_CLAIM="a brand-new user with the prerequisites met passes doctor outright."
+    # With the prerequisites satisfied there is no excuse for an unready
+    # backend, so this variant demands the thing `test` only reports.
+    BB_TEST_REQUIRE_BACKEND=1
+    _test_cycle 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 ;;
+    test-ready) cmd_test_ready ;;
+    up) cmd_up ;;
+    run) cmd_run ;;
+    prereqs) cmd_prereqs ;;
+    status) cmd_status ;;
+    down) cmd_down ;;
+    deep-reset) cmd_deep_reset ;;
+    *) echo "usage: $0 {test|test-ready|up|run|prereqs|status|down|deep-reset}" >&2 ; exit 2 ;;
+esac
@@ -95,7 +95,7 @@ BOT_BOTTLE_RUN_CANARIES=1 python -m scripts.unittest_gate \
   ```
 4. Skip guards live in `tests._backend` and gate on the backend's own
   readiness check, `bot_bottle.backend.has_backend` — the same probe
-   behind `./cli.py backend status`:
+   behind `bot-bottle backend status`:
   - Backend-agnostic tests (go through `get_bottle_backend()`) decorate
     the class with `@skip_unless_selected_backend_available()` — the test
     runs against whichever backend `BOT_BOTTLE_BACKEND` selects and skips
@@ -105,7 +105,7 @@ BOT_BOTTLE_RUN_CANARIES=1 python -m scripts.unittest_gate \
     `backend.docker.*`, …) decorate with `@skip_unless_backend("docker")`
     so they no-op under a run targeting a different backend.

-   Each CI integration job runs `./cli.py backend status --backend=<name>`
+   Each CI integration job runs `bot-bottle backend status --backend=<name>`
   as a preflight, which prints a clear per-check summary and exits non-zero
   when the backend is missing — so absent infrastructure fails the job
   instead of hiding among per-test `unittest.skip` lines.
@@ -2,7 +2,7 @@

 Each integration test targets the backend named by ``BOT_BOTTLE_BACKEND``
 (default ``docker``) and gates on that backend's full readiness check —
-``is_backend_ready()`` (equivalent to ``./cli.py backend status``), not just
+``is_backend_ready()`` (equivalent to ``bot-bottle backend status``), not just
 a binary-on-PATH probe. When the backend is not ready, diagnostic output is
 printed during test discovery so the operator sees a concrete reason for each
 skip.
@@ -1,7 +1,7 @@
 """Tests for the backend-aware skip guards in ``tests/_backend.py``.

 The guards delegate their readiness check to
-``bot_bottle.backend.is_backend_ready`` (the probe behind ``./cli.py backend
+``bot_bottle.backend.is_backend_ready`` (the probe behind ``bot-bottle backend
 status``); here that probe is mocked so the unit job asserts the
 selection/skip logic without either backend present on the runner.
 """
@@ -1,6 +1,6 @@
 """Unit: the generic `backend` CLI command.

-`./cli.py backend {setup,status} [--backend=NAME]` resolves a backend
+`bot-bottle backend {setup,status} [--backend=NAME]` resolves a backend
 and dispatches to its `setup()` / `status()` classmethods — no
 backend-specific commands. Also covers the docker backend's own
 setup/status logic (the firecracker path is exercised by
@@ -44,6 +44,17 @@ 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(
@@ -56,6 +56,21 @@ 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 sysconfig
+import re
 import unittest
 from pathlib import Path

@@ -17,6 +17,22 @@ 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):
@@ -32,20 +48,45 @@ class TestInstallScript(unittest.TestCase):
        self.assertIn("set -eu", self.text)

    def test_never_uses_sudo(self):
-        # Only executable lines matter; the header comment may mention sudo.
-        code = [
-            ln for ln in self.text.splitlines()
-            if ln.strip() and not ln.lstrip().startswith("#")
-        ]
-        self.assertNotIn("sudo", "\n".join(code))
+        # 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))

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

-    def test_installs_via_pipx_with_pip_fallback(self):
+    def test_installs_via_pipx_with_venv_fallback(self):
        self.assertIn("pipx install", self.text)
-        self.assertIn("pip install --user", 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)

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

-    def test_checks_pip_usable_before_fallback(self):
-        self.assertIn("python3 -m pip --version", self.text)
+    def test_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_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_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_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_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_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_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_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()
@@ -158,8 +158,11 @@ resolver #2
            f"registry:5000/agent:sha256-{'a' * 64}",
            pinned,
        )
+        # The tag source is the name:tag ref, not the image ID: Apple
+        # Container's `image tag` rejects a bare 64-byte hex string as a
+        # reference. The second image_id call is what keeps this fail-closed.
        run.assert_called_once_with(
-            ["container", "image", "tag", image, pinned],
+            ["container", "image", "tag", "registry:5000/agent:latest", pinned],
            capture_output=True,
            text=True,
            check=False,
@@ -169,6 +172,31 @@ resolver #2
            [call.args for call in inspect.call_args_list],
        )

+    def test_pinned_local_image_ref_accepts_bare_hex_image_id(self):
+        # `container image inspect` reports "id" without the sha256: prefix.
+        image = "b" * 64
+        completed = util.subprocess.CompletedProcess(
+            args=[], returncode=0, stdout="", stderr="",
+        )
+        with patch.object(util, "image_id", return_value=image), \
+             patch.object(util.subprocess, "run", return_value=completed) as run:
+            pinned = util.pinned_local_image_ref("agent:latest")
+        self.assertEqual(f"agent:sha256-{'b' * 64}", pinned)
+        self.assertEqual(
+            ["container", "image", "tag", "agent:latest", pinned],
+            run.call_args.args[0],
+        )
+
+    def test_pinned_local_image_ref_dies_when_tag_moved_mid_flight(self):
+        completed = util.subprocess.CompletedProcess(
+            args=[], returncode=0, stdout="", stderr="",
+        )
+        with patch.object(
+            util, "image_id", side_effect=["c" * 64, "d" * 64],
+        ), patch.object(util.subprocess, "run", return_value=completed), \
+             self.assertRaises(SystemExit):
+            util.pinned_local_image_ref("agent:latest")
+
    def test_commit_container_execs_tar_and_builds_image(self):
        # stderr is bytes because subprocess.run uses stderr=PIPE without text=True
        completed = util.subprocess.CompletedProcess(
@@ -151,6 +151,31 @@ class TestReprovisionGateway(unittest.TestCase):
                self.c.reprovision_gateway("b1", "key")


+class TestUpdateAgentSecret(unittest.TestCase):
+    def setUp(self) -> None:
+        self.c = OrchestratorClient("http://orch:8080")
+
+    def test_success_posts_single_secret(self) -> None:
+        with patch(_URLOPEN, return_value=_resp(200, {"updated": True})) as opened:
+            self.assertTrue(self.c.update_agent_secret("b1", "A", "fresh", "key"))
+        request = opened.call_args.args[0]
+        self.assertEqual("POST", request.get_method())
+        self.assertTrue(request.full_url.endswith("/bottles/b1/secret"))
+        self.assertEqual(
+            {"name": "A", "value": "fresh", "env_var_secret": "key"},
+            json.loads(request.data),
+        )
+
+    def test_unknown_bottle_is_false(self) -> None:
+        with patch(_URLOPEN, side_effect=_http_error(404)):
+            self.assertFalse(self.c.update_agent_secret("b1", "A", "v", "key"))
+
+    def test_other_status_raises(self) -> None:
+        with patch(_URLOPEN, side_effect=_http_error(400)):
+            with self.assertRaises(OrchestratorClientError):
+                self.c.update_agent_secret("b1", "A", "v", "key")
+
+
 class TestHealthAndPolicy(unittest.TestCase):
    def setUp(self) -> None:
        self.c = OrchestratorClient("http://orch:8080")
@@ -199,6 +199,20 @@ class TestAgentSecrets(unittest.TestCase):
        got = self.store.get_agent_secrets("bottle-1")
        self.assertEqual({"K": "new", "K2": "v2"}, got)

+    def test_store_agent_secret_upserts_one_key_leaving_others(self) -> None:
+        self.store.store_agent_secrets("bottle-1", {"K": "v1", "K2": "v2"})
+        self.store.store_agent_secret("bottle-1", "K", "v1-new")  # update existing
+        self.store.store_agent_secret("bottle-1", "K3", "v3")     # insert new
+        self.assertEqual(
+            {"K": "v1-new", "K2": "v2", "K3": "v3"},
+            self.store.get_agent_secrets("bottle-1"),
+        )
+
+    def test_store_agent_secret_does_not_duplicate_rows(self) -> None:
+        self.store.store_agent_secret("bottle-1", "K", "v1")
+        self.store.store_agent_secret("bottle-1", "K", "v2")
+        self.assertEqual({"K": "v2"}, self.store.get_agent_secrets("bottle-1"))
+
    def test_delete_removes_secrets(self) -> None:
        self.store.store_agent_secrets("bottle-1", {"K": "v"})
        self.store.delete_agent_secrets("bottle-1")
@@ -125,6 +125,47 @@ class TestDispatch(unittest.TestCase):
            {"EGRESS_TOKEN_0": "upstream-secret"}, self.orch.tokens_for(bottle_id),
        )

+    def test_update_agent_secret_in_place(self) -> None:
+        key = base64.urlsafe_b64encode(b"unit-test-key").rstrip(b"=").decode()
+        status, payload = dispatch(
+            self.orch, "POST", "/bottles", _body({
+                "source_ip": "10.243.0.21",
+                "tokens": {"A": "old", "B": "keep"},
+                "env_var_secret": key,
+            }),
+        )
+        self.assertEqual(201, status)
+        bottle_id = payload["bottle_id"]
+        assert isinstance(bottle_id, str)
+        status, response = dispatch(
+            self.orch, "POST", f"/bottles/{bottle_id}/secret",
+            _body({"name": "A", "value": "fresh", "env_var_secret": key}),
+        )
+        self.assertEqual((200, {"updated": True}), (status, response))
+        self.assertEqual({"A": "fresh", "B": "keep"}, self.orch.tokens_for(bottle_id))
+
+    def test_update_agent_secret_validates_and_unknown_bottle(self) -> None:
+        status, _ = dispatch(self.orch, "POST", "/bottles/b1/secret", b"not-json")
+        self.assertEqual(400, status)
+        status, _ = dispatch(
+            self.orch, "POST", "/bottles/b1/secret", _body({"name": "A"}),
+        )
+        self.assertEqual(400, status)  # value + env_var_secret missing
+        status, _ = dispatch(
+            self.orch, "POST", "/bottles/ghost/secret",
+            _body({"name": "A", "value": "v", "env_var_secret": "k"}),
+        )
+        self.assertEqual(404, status)
+
+    def test_update_agent_secret_is_cli_only(self) -> None:
+        # A data-plane (`gateway`) caller must not set a bottle's tokens.
+        status, _ = dispatch(
+            self.orch, "POST", "/bottles/b1/secret",
+            _body({"name": "A", "value": "v", "env_var_secret": "k"}),
+            role=ROLE_GATEWAY,
+        )
+        self.assertEqual(403, status)
+
    def test_reprovision_validates_request_and_missing_rows(self) -> None:
        status, _ = dispatch(
            self.orch, "POST", "/bottles/b1/reprovision_gateway", b"not-json",
@@ -103,6 +103,25 @@ class TestOrchestrator(unittest.TestCase):
        self.assertTrue(self.orch.reprovision_from_secret(rec.bottle_id, key))
        self.assertEqual({"EGRESS_TOKEN_0": "secret"}, self.orch.tokens_for(rec.bottle_id))

+    def test_update_agent_secret_refreshes_one_token_in_place(self) -> None:
+        key = new_env_var_secret()
+        rec = self.orch.launch_bottle(
+            "10.243.0.20", tokens={"A": "old-a", "B": "keep-b"}, env_var_secret=key,
+        )
+        self.assertTrue(self.orch.update_agent_secret(rec.bottle_id, "A", "new-a", key))
+        # In memory: A refreshed, B left untouched.
+        self.assertEqual({"A": "new-a", "B": "keep-b"}, self.orch.tokens_for(rec.bottle_id))
+        # At rest: the whole set stays decryptable with the SAME env_var_secret,
+        # so a later reprovision restores the refreshed value (not the launch one).
+        self.orch._tokens.clear()
+        self.assertTrue(self.orch.reprovision_from_secret(rec.bottle_id, key))
+        self.assertEqual({"A": "new-a", "B": "keep-b"}, self.orch.tokens_for(rec.bottle_id))
+
+    def test_update_agent_secret_unknown_bottle_is_false(self) -> None:
+        self.assertFalse(
+            self.orch.update_agent_secret("ghost", "A", "v", new_env_var_secret())
+        )
+
    def test_reprovision_rejects_missing_rows_and_wrong_key(self) -> None:
        self.assertFalse(self.orch.reprovision_from_secret("missing", new_env_var_secret()))
        key = "AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE"