test: replace /bin/sleep with portable Python sleep in test_gateway_init

/bin/sleep does not exist at FHS paths on NixOS (the KVM self-hosted runner's OS). All 13 FileNotFoundError failures in TestSupervisor were caused by _DaemonSpec tuples spawning /bin/sleep directly. Replace with a module-level _SLEEP_30/_SLEEP_60 tuple using sys.executable so the supervisor tests run on any platform. Also fix TestMainEndToEnd._run() and remove the now-unnecessary setUpClass guard.
fix(tests): mock name_color_modal in test_cli_start_selector setUp
2026-07-18 22:08:43 -04:00 · 2026-07-18 22:08:43 -04:00 · 2026-07-18 22:08:43 -04:00 · 2026-07-18 22:08:43 -04:00 · 2026-07-18 22:08:43 -04:00 · 2026-07-18 22:08:43 -04:00
57 changed files with 569 additions and 1996 deletions
@@ -1,10 +1,6 @@
 [run]
 branch = True
 source = .
-# Store paths relative to the project root so .coverage.* files produced on
-# different runners (ubuntu-latest vs self-hosted KVM) can be combined by the
-# coverage job without a [paths] remapping section.
-relative_files = True

 [report]
 # Coverage policy: see docs/decisions/0004-coverage-policy.md.
@@ -9,12 +9,10 @@
 #   tests/canaries/     — upstream regression canaries; run on a separate
 #                         schedule (see canaries.yml), not here
 #
-# Each test job runs once under coverage and uploads a small .coverage.*
-# artifact. The `coverage` job combines them — no test reruns, no KVM
-# dependency on that job. For main-branch pushes only, the tested rootfs
-# and matching dropbear are uploaded so `publish-infra` can publish the
-# byte-identical artifact that was tested. PRs avoid the ~194 MB rootfs
-# transfer entirely.
+# Integration tests run once per backend in separate jobs. Each job sets
+# BOT_BOTTLE_BACKEND explicitly so the test suite uses the right backend.
+# Backends that aren't available on the runner fail the preflight step
+# rather than silently skipping inside the test output.

 name: test

@@ -27,18 +25,12 @@ on:
      - '.gitea/workflows/**.yml'
      - 'scripts/**'
      - 'README.md'
-      # Dockerfiles and pyproject.toml are baked into the infra rootfs; a
-      # change here alters what the integration/coverage jobs build locally.
-      - 'Dockerfile*'
-      - 'pyproject.toml'
  pull_request:
    paths:
      - '**.py'
      - '.gitea/workflows/**.yml'
      - 'scripts/**'
      - 'README.md'
-      - 'Dockerfile*'
-      - 'pyproject.toml'
  workflow_dispatch:

 jobs:
@@ -56,17 +48,11 @@ jobs:
      - name: Install dev requirements
        run: python3 -m pip install --break-system-packages -r requirements-dev.txt

-      - name: Run unit tests with coverage
-        run: python3 -m coverage run --data-file=.coverage.unit -m unittest discover -t . -s tests/unit -v
+      - name: Run unit tests
+        run: python3 -m coverage run -m unittest discover -t . -s tests/unit -v

      - name: Report unit coverage
-        run: python3 -m coverage report --data-file=.coverage.unit -m
-
-      - name: Upload unit coverage artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: coverage-unit
-          path: ${{ github.workspace }}/.coverage.unit
+        run: python3 -m coverage report -m

  integration-docker:
    runs-on: ubuntu-latest
@@ -76,9 +62,6 @@ jobs:

      # No actions/setup-python (see the note in the `unit` job); the
      # container's system Python 3.12 runs the stdlib test suite directly.
-      - name: Install coverage
-        run: python3 -m pip install --break-system-packages coverage
-
      - name: Show environment
        run: |
          python3 --version
@@ -88,16 +71,10 @@ jobs:
            echo "docker not on PATH — integration tests will skip"
          fi

-      - name: Run integration tests (docker) with coverage
+      - name: Run integration tests (docker)
        env:
          BOT_BOTTLE_BACKEND: docker
-        run: python3 -m coverage run --data-file=.coverage.docker -m unittest discover -t . -s tests/integration -v
-
-      - name: Upload docker coverage artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: coverage-docker
-          path: ${{ github.workspace }}/.coverage.docker
+        run: python3 -m unittest discover -t . -s tests/integration -v

  # Integration tests against the Firecracker backend. Runs on a self-hosted
  # KVM runner (label `kvm`) where /dev/kvm and the TAP/nft pool are available.
@@ -106,16 +83,8 @@ jobs:
  # PRs don't execute untrusted code on the privileged runner.
  #
  # Runner prerequisites (provision once; see README "Firecracker on Linux"):
-  # `firecracker` on PATH, `/dev/kvm` accessible, cached kernel +
-  # static dropbear at /var/cache/bot-bottle-fc/dropbear, and the pool as a
-  # persistent systemd unit.
-  #
-  # The infra candidate is built here directly (no artifact download) to
-  # eliminate the ~70 s ubuntu-latest upload + ~83 s combined download that
-  # the old build-infra → integration-firecracker + coverage chain incurred.
-  # For main-branch pushes the tested rootfs and matching dropbear are
-  # uploaded so publish-infra can publish the byte-identical artifact; PRs
-  # skip those uploads entirely.
+  # `firecracker` on PATH, `/dev/kvm` accessible, Docker, cached kernel +
+  # static dropbear, and the pool as a persistent systemd unit.
  integration-firecracker:
    runs-on: [self-hosted, kvm]
    if: >-
@@ -136,58 +105,34 @@ jobs:
          # range overlap; it prints the exact `backend setup` fix.
          python3 cli.py backend status --backend=firecracker

-      - name: Build infra candidate from this checkout
-        env:
-          BOT_BOTTLE_FC_DROPBEAR: /var/cache/bot-bottle-fc/dropbear
-        run: python3 -m bot_bottle.backend.firecracker.publish_infra --output infra-candidate
-
-      - name: Replace the persistent infra VM with the candidate
-        run: python3 -c 'from bot_bottle.backend.firecracker import infra_vm; infra_vm.stop()'
-
-      # No dev-requirements install: `coverage` is already provided by the
-      # self-hosted runner's Nix python env, and that env has no `pip`
-      # module to install into anyway.
-      - name: Run integration tests (firecracker) with coverage
+      # No dev-requirements install: the integration suite runs on stdlib
+      # `unittest` (pylint/pyright are lint.yml's concern, not this job's),
+      # and the self-hosted runner's Nix python env has no `pip` module
+      # (`python3 -m pip` → "No module named pip"). Nothing to install.
+      - name: Run integration tests (firecracker)
        env:
          BOT_BOTTLE_BACKEND: firecracker
-          BOT_BOTTLE_INFRA_ARTIFACT_DIR: ${{ github.workspace }}/infra-candidate
-        run: python3 -m coverage run --data-file=.coverage.firecracker -m unittest discover -t . -s tests/integration -v
+        run: python3 -m unittest discover -t . -s tests/integration -v

-      - name: Upload firecracker coverage artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: coverage-firecracker
-          path: ${{ github.workspace }}/.coverage.firecracker
-
-      # Only upload the large rootfs artifact on main-branch pushes;
-      # PRs avoid the ~194 MB transfer. publish-infra only runs on main
-      # and downloads these to publish the byte-identical tested rootfs.
-      - name: Upload tested rootfs (main branch only)
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: actions/upload-artifact@v3
-        with:
-          name: infra-candidate
-          path: infra-candidate/
-
-      - name: Upload dropbear for publish verification (main branch only)
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: actions/upload-artifact@v3
-        with:
-          name: firecracker-inputs
-          path: /var/cache/bot-bottle-fc/dropbear
-
-  # Combined coverage gate: aggregates .coverage.* artifacts uploaded by each
-  # test job, then runs the diff-coverage gate (new/changed lines >= 90%).
+  # Combined unit+integration coverage + the diff-coverage gate (the hard
+  # gate: new/changed lines >= 90%). See docs/decisions/0004-coverage-policy.md.
  #
-  # Runs on ubuntu-latest — no KVM needed, no test reruns. Coverage files use
-  # relative_files = True (.coveragerc) so they combine cleanly across runners.
+  # This runs on a self-hosted KVM runner (label `kvm`), NOT ubuntu-latest,
+  # because the Firecracker backend's subprocess/VM orchestration
+  # (launch/boot/SSH/isolation-probe) is covered by the integration suite,
+  # and that suite needs `/dev/kvm` + the provisioned TAP/nft pool — which a
+  # container-based runner doesn't have. On such a runner the firecracker
+  # integration test skips and its ~230 orchestration lines read as
+  # uncovered, so the gate can't pass there.
  #
-  # Restricted to the same events as integration-firecracker: it depends on
-  # that job's coverage artifact and skips for fork PRs alongside it.
+  # Restricted to the same events as integration-firecracker (same-repo PRs,
+  # push, workflow_dispatch) for the same security reason.
+  #
+  # See #414 for the planned follow-up: artifact-based coverage combination
+  # (run tests once in their respective jobs, combine .coverage files here).
  coverage:
-    needs: [unit, integration-docker, integration-firecracker]
    timeout-minutes: 15
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, kvm]
    if: >-
      github.event_name == 'push' ||
      github.event_name == 'workflow_dispatch' ||
@@ -199,62 +144,23 @@ jobs:
        with:
          fetch-depth: 0

-      - name: Install coverage
-        run: python3 -m pip install --break-system-packages coverage
-
-      - name: Download unit coverage artifact
-        uses: actions/download-artifact@v3
-        with:
-          name: coverage-unit
-          path: ${{ github.workspace }}
-
-      - name: Download docker coverage artifact
-        uses: actions/download-artifact@v3
-        with:
-          name: coverage-docker
-          path: ${{ github.workspace }}
-
-      - name: Download firecracker coverage artifact
-        uses: actions/download-artifact@v3
-        with:
-          name: coverage-firecracker
-          path: ${{ github.workspace }}
+      - name: Preflight — Firecracker host is ready
+        run: |
+          command -v firecracker >/dev/null || {
+            echo "firecracker not on PATH — provision the runner (README: Firecracker on Linux)"; exit 1; }
+          test -e /dev/kvm || { echo "/dev/kvm missing — KVM not available on this runner"; exit 1; }
+          # `backend status` exits non-zero unless the TAP pool is up + no
+          # range overlap; it prints the exact `backend setup` fix.
+          python3 cli.py backend status --backend=firecracker

+      # No dev-requirements install: `coverage` is already provided by the
+      # self-hosted runner's Nix python env, and that env has no `pip`
+      # module to install into anyway. `scripts/coverage.sh` +
+      # `diff_coverage.py` need only `coverage` (not pylint/pyright).
      - name: Combined coverage (unit + integration, incl. firecracker)
-        run: PYTHON=python3 bash scripts/coverage.sh aggregate critical
+        run: PYTHON=python3 bash scripts/coverage.sh critical

      - name: Diff-coverage gate (changed lines >= 90%)
        run: |
          git fetch --no-tags origin main:refs/remotes/origin/main
          python3 scripts/diff_coverage.py --base origin/main --min 90
-
-  publish-infra:
-    needs: [unit, integration-docker, integration-firecracker, coverage]
-    runs-on: ubuntu-latest
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    steps:
-      - name: Checkout the tested revision
-        uses: actions/checkout@v4
-
-      - name: Download the tested rootfs
-        uses: actions/download-artifact@v3
-        with:
-          name: infra-candidate
-          path: infra-candidate
-
-      # publish_infra re-derives the version from the checkout to confirm the
-      # bundle matches before uploading, and the version hashes the dropbear
-      # bytes. Download the SAME dropbear integration-firecracker used, or
-      # the recheck computes a "<missing>"-dropbear version and rejects the
-      # candidate.
-      - name: Download the staged dropbear (matches build's version)
-        uses: actions/download-artifact@v3
-        with:
-          name: firecracker-inputs
-          path: firecracker-inputs
-
-      - name: Publish the tested candidate
-        env:
-          BOT_BOTTLE_INFRA_ARTIFACT_TOKEN: ${{ secrets.BOT_BOTTLE_INFRA_ARTIFACT_TOKEN }}
-          BOT_BOTTLE_FC_DROPBEAR: ${{ github.workspace }}/firecracker-inputs/dropbear
-        run: python3 -m bot_bottle.backend.firecracker.publish_infra --publish-dir infra-candidate
@@ -98,9 +98,6 @@ RUN pip install --no-cache-dir /src/

 # mitmdump -s requires a file path, not a module. Write a one-line shim that
 # re-exports `addons` from the installed package; mitmdump finds it there.
-# WORKDIR here also creates /app so the shim + COPYs below can write into it
-# (nothing created /app before this point).
-WORKDIR /app
 RUN printf 'from bot_bottle.egress_addon import addons\n' > /app/egress_addon.py
 COPY bot_bottle/egress_entrypoint.sh /app/egress-entrypoint.sh
 RUN chmod +x /app/egress-entrypoint.sh
@@ -120,6 +117,8 @@ RUN mkdir -p \
 # subset the bottle uses.
 EXPOSE 8888 9099 9418 9420 9100

+WORKDIR /app
+
 # PID 1 is the supervisor. It owns signal handling and exit-code
 # propagation; no `exec` chain in the entrypoint itself.
 ENTRYPOINT ["python3", "-m", "bot_bottle.gateway_init"]
@@ -90,7 +90,7 @@ BOT_BOTTLE_BACKEND=firecracker ./cli.py start <agent>

 > **NixOS:** enable `virtualisation.docker`, ensure the KVM module is loaded (`boot.kernelModules = [ "kvm-intel" ];` or `kvm-amd`), and add your user to the `kvm` and `docker` groups. For the network pool, consume the flake module — `imports = [ inputs.bot-bottle.nixosModules.firecracker-netpool ]; services.bot-bottle-firecracker = { enable = true; owner = "you"; };` — then `nixos-rebuild switch` (imperative nft/TAP rules don't survive a rebuild; channel users can `imports = [ <bot-bottle>/nix/firecracker-netpool.nix ]`). `firecracker` isn't in nixpkgs by default as a user binary — install the release binary (pin the version) and put it on `PATH`.

-> **CI:** the coverage gate (`.gitea/workflows/test.yml` → `coverage` job) runs on a self-hosted runner labelled `kvm`, because the Firecracker backend's VM/SSH orchestration is exercised only by the integration suite, which needs `/dev/kvm` + the provisioned pool (a container runner would skip it and read as uncovered). Provision that runner exactly like a normal Firecracker host — `firecracker` on `PATH`, `/dev/kvm`, the cached guest kernel + static dropbear, and the pool installed as the persistent systemd unit — then register it with the `kvm` label. A Docker-capable hosted job builds the candidate once; KVM tests boot those exact bytes, and a successful main run publishes them. The unit/lint jobs still run on `ubuntu-latest`.
+> **CI:** the coverage gate (`.gitea/workflows/test.yml` → `coverage` job) runs on a self-hosted runner labelled `kvm`, because the Firecracker backend's VM/SSH orchestration is exercised only by the integration suite, which needs `/dev/kvm` + the provisioned pool (a container runner would skip it and read as uncovered). Provision that runner exactly like a normal Firecracker host — `firecracker` on `PATH`, `/dev/kvm`, Docker, the cached guest kernel + static dropbear, and the pool installed as the persistent systemd unit — then register it with the `kvm` label. The unit/lint jobs still run on `ubuntu-latest`.

 ```sh
 ./cli.py start <agent>   # builds the image on first run, drops you into claude
@@ -45,8 +45,7 @@ from typing import TYPE_CHECKING, Any, Generic, Sequence, TypeVar
 from ..agent_provider import AgentProvisionPlan, get_provider, build_agent_provision_plan
 from ..egress import EgressPlan
 from ..git_gate import GitGatePlan
-from ..log import die, info, warn
-from ..util import read_tty_line
+from ..log import die, info
 from ..manifest import Manifest, ManifestIndex
 from ..supervise import SupervisePlan
 from ..util import expand_tilde
@@ -649,26 +648,19 @@ def __getattr__(name: str) -> Any:

 def get_bottle_backend(
    name: str | None = None,
-    *,
-    prompt: bool = True,
 ) -> BottleBackend[Any, Any]:
    """Resolve the bottle backend.

    `name` precedence:
-      1. explicit arg (e.g. resume passes the recorded backend name)
+      1. explicit arg (CLI `--backend=<name>` passes through here)
      2. BOT_BOTTLE_BACKEND env var
-      3. auto-selection: VM backend first, docker fallback with prompt
-
-    `prompt` controls whether auto-selection may block on an interactive
-    [i/d/q] prompt when falling back to docker. Pass `prompt=False` in
-    non-interactive contexts (headless launches, CI) so the call dies
-    with an actionable message instead of hanging.
+      3. `macos-container` on compatible macOS hosts
+      4. `firecracker` on KVM-capable Linux hosts
+      5. default `docker`

    Dies with a pointer at the known backends if the chosen name
    isn't implemented."""
-    resolved = name or os.environ.get("BOT_BOTTLE_BACKEND")
-    if resolved is None:
-        resolved = _auto_select_backend(prompt=prompt)
+    resolved = name or os.environ.get("BOT_BOTTLE_BACKEND") or _default_backend_name()
    backends = _get_backends()
    if resolved not in backends:
        known = ", ".join(sorted(backends))
@@ -676,35 +668,7 @@ def get_bottle_backend(
    return backends[resolved]


-def _platform_vm_suggestion() -> str:
-    """Platform-appropriate VM backend name for install suggestions."""
-    return "macos-container" if sys.platform == "darwin" else "firecracker"
-
-
-def _print_vm_install_instructions() -> None:
-    """Print platform-appropriate VM backend install instructions to stderr."""
-    vm = _platform_vm_suggestion()
-    if vm == "macos-container":
-        info("Install Apple Container: https://github.com/apple/container/releases")
-        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")
-
-
-def _auto_select_backend(prompt: bool = True) -> str:
-    """Tier-1 / tier-2 backend auto-selection.
-
-    Tier 1: VM backend — macos-container on macOS when Apple Container is
-    installed; firecracker on KVM-capable Linux even before the binary is
-    present (its preflight prints an install pointer).
-
-    Tier 2: docker, with a security warning and an interactive prompt.
-    When `prompt=False` (headless / CI), dies with an actionable message
-    instead of blocking on a TTY read. When docker is also absent, prints
-    VM install instructions and exits.
-    """
-    # --- Tier 1: VM backend -----------------------------------------
+def _default_backend_name() -> str:
    if has_backend("macos-container"):
        return "macos-container"
    # A KVM-capable Linux host defaults to firecracker even when the
@@ -714,37 +678,7 @@ def _auto_select_backend(prompt: bool = True) -> str:
    from .firecracker import FirecrackerBottleBackend
    if FirecrackerBottleBackend.is_host_capable():
        return "firecracker"
-
-    # --- Tier 2: docker fallback ------------------------------------
-    if not has_backend("docker"):
-        info("No backend available on this host.")
-        _print_vm_install_instructions()
-        die("no backend available; install a VM backend and re-run")
-
-    vm = _platform_vm_suggestion()
-    warn(
-        "docker is less secure than VM backends — "
-        "containers share the host kernel."
-    )
-    if not prompt:
-        die(
-            f"no VM backend available; set BOT_BOTTLE_BACKEND=docker to proceed "
-            f"with docker, or install the {vm!r} backend."
-        )
-    sys.stderr.write(
-        f"bot-bottle: For better isolation, install the {vm!r} backend.\n"
-        f"  [i] show {vm} install instructions and exit\n"
-        "  [d] use docker anyway\n"
-        "  [q] quit\n"
-        "bot-bottle: choice [i/d/q]: "
-    )
-    sys.stderr.flush()
-    reply = read_tty_line().strip().lower()
-    if reply == "d":
-        return "docker"
-    if reply == "i":
-        _print_vm_install_instructions()
-    die("not proceeding with docker; install a VM backend or set BOT_BOTTLE_BACKEND=docker")
+    return "docker"


 def known_backend_names() -> tuple[str, ...]:
@@ -38,39 +38,25 @@ _BUILD_TIMEOUT_SECONDS = 900.0


 def _dockerfile_hash(dockerfile: Path) -> str:
-    """The Dockerfile's content hash. The shipped agent Dockerfiles COPY
-    nothing from the build context (see .dockerignore), so their content fully
-    determines the built image; a Dockerfile that adds COPY will want the
+    """Cache key: the Dockerfile's content. The shipped agent Dockerfiles
+    COPY nothing from the build context (see .dockerignore), so their content
+    fully determines the image; a Dockerfile that adds COPY will want the
    context folded in here too."""
    return hashlib.sha256(dockerfile.read_bytes()).hexdigest()[:16]


-def _rootfs_digest(dockerfile: Path) -> str:
-    """Cache key for the built AND boot-injected agent rootfs. Two inputs
-    determine the on-disk rootfs: the Dockerfile (the image) and the guest init
-    injected into it (`util._GUEST_INIT`). Folding the init in means a fix to
-    it — e.g. making /tmp world-writable — busts the cache instead of silently
-    reusing a stale rootfs built with the old init."""
-    h = hashlib.sha256()
-    h.update(_dockerfile_hash(dockerfile).encode())
-    h.update(b"\0")
-    h.update(util._GUEST_INIT.encode())
-    return h.hexdigest()[:16]
-
-
 def build_agent_rootfs_dir(
    dockerfile: Path, *, image_tag: str, smoke_test: tuple[str, ...] = (),
 ) -> Path:
    """Build `dockerfile` in the infra VM (buildah, no host docker), export its
    rootfs, inject the guest boot bits, and return the cached base dir — the
-    same shape `util.build_rootfs_ext4` consumes. Cached by Dockerfile content
-    + injected guest init, so a repeat launch skips the rebuild but an init or
-    Dockerfile change rebuilds.
+    same shape `util.build_rootfs_ext4` consumes. Cached by Dockerfile content,
+    so a repeat launch skips the rebuild.

    `smoke_test` (the provider's declared argv, e.g. `("claude","--version")`)
    is run in the freshly built image before export, catching an npm
    silent-failure image at build time rather than at first agent use."""
-    digest = _rootfs_digest(dockerfile)
+    digest = _dockerfile_hash(dockerfile)
    base = util.cache_dir() / "rootfs" / f"agent-{digest}"
    if (base / ".bb-ready").is_file():
        info(f"using cached agent rootfs {base.name}")
@@ -85,11 +85,6 @@ def infra_artifact_version(init_script: str, *, repo_root: Path = _REPO_ROOT) ->
        h.update(name.encode())
        h.update(b"\0")
        h.update((repo_root / name).read_bytes())
-    h.update(b"pyproject.toml\0")
-    h.update((repo_root / "pyproject.toml").read_bytes())
-    h.update(b"dropbear\0")
-    dropbear = util.dropbear_path()
-    h.update(dropbear.read_bytes() if dropbear.is_file() else b"<missing>")
    h.update(b"init\0")
    h.update(init_script.encode())
    return h.hexdigest()[:16]
@@ -116,7 +111,6 @@ def artifact_url(version: str, filename: str) -> str:

 _GZ_NAME = "rootfs.ext4.gz"
 _SHA_NAME = "rootfs.ext4.gz.sha256"
-_CANDIDATE_DIR_ENV = "BOT_BOTTLE_INFRA_ARTIFACT_DIR"


 def _cache_root(version: str) -> Path:
@@ -166,33 +160,6 @@ def ensure_artifact_gz(version: str) -> Path:
    """The verified, cached `rootfs.ext4.gz` for `version` — downloading it (and
    its `.sha256`) once, then reusing it. Fail-closed on a checksum mismatch:
    the partial is removed and we die rather than boot an unverified rootfs."""
-    candidate_dir = os.environ.get(_CANDIDATE_DIR_ENV, "").strip()
-    if candidate_dir:
-        root = Path(candidate_dir)
-        version_file = root / "version.txt"
-        # Guard the read so a missing version.txt is a clean error, not a raw
-        # FileNotFoundError.
-        if not version_file.is_file():
-            die(f"infra candidate bundle is incomplete: {root}")
-        declared = version_file.read_text(encoding="utf-8").strip()
-        if declared != version:
-            die(
-                f"infra candidate version mismatch: expected {version}, "
-                f"bundle contains {declared or '<empty>'}"
-            )
-        gz = root / _GZ_NAME
-        sha = root / _SHA_NAME
-        if not gz.is_file() or not sha.is_file():
-            die(f"infra candidate bundle is incomplete: {root}")
-        expected = sha.read_text().split()[0].strip().lower()
-        actual = _sha256_file(gz)
-        if actual != expected:
-            die(
-                f"infra candidate checksum mismatch for {version}:\n"
-                f"    expected {expected}\n    actual   {actual}"
-            )
-        return gz
-
    root = _cache_root(version)
    root.mkdir(parents=True, exist_ok=True)
    gz = root / _GZ_NAME
@@ -161,23 +161,20 @@ def ensure_running() -> InfraVm:
    slot = netpool.orch_slot()
    url = f"http://{slot.guest_ip}:{CONTROL_PLANE_PORT}"
    key = _infra_dir() / "id_ed25519"
-    want = _expected_version()
-    if _adoptable(key, url, want):
+    if key.exists() and _health_ok(url):
        info(f"adopting running infra VM at {url}")
        return InfraVm(guest_ip=slot.guest_ip, private_key=key)

    with _singleton_lock():
        # Re-check under the lock: another launcher may have booted it while
        # we waited for the lock (double-checked, so we adopt not re-boot).
-        if _adoptable(key, url, want):
+        if key.exists() and _health_ok(url):
            info(f"adopting running infra VM at {url}")
            return InfraVm(guest_ip=slot.guest_ip, private_key=key)
-        # Clear a stale/hung/OUTDATED VM holding the link before booting fresh.
-        stop()
+        stop()  # clear a stale/hung VM holding the link before booting fresh
        ensure_built()
        infra = boot()
        wait_for_health(infra)
-        _record_booted_version(want)
        return infra


@@ -196,15 +193,9 @@ def _singleton_lock() -> Generator[None, None, None]:


 def stop() -> None:
-    """Stop the infra VM singleton (idempotent — absent is success). Reaps the
-    recorded VMM AND any orphaned firecracker still bound to the infra config —
-    the PID file drifts after crashes / out-of-band kills, and a survivor would
-    hold the orchestrator TAP so the next boot dies with "tap … Resource busy".
-    Drops the version marker so a stopped VM is never treated as adoptable."""
+    """Stop the infra VM singleton (idempotent — absent is success)."""
    _kill_pidfile()
-    _kill_infra_firecrackers()
    _pid_file().unlink(missing_ok=True)
-    _version_file().unlink(missing_ok=True)


 def boot() -> InfraVm:
@@ -247,36 +238,6 @@ def _pid_file() -> Path:
    return _infra_dir() / "vm.pid"


-def _version_file() -> Path:
-    """Records the infra-artifact version the *running* VM booted from, so a
-    later launcher can tell whether the singleton it found is the current code.
-    Without it, a healthy VM built from an older image gets adopted forever and
-    the new code never boots — every infra change would need an out-of-band
-    kill to dislodge the stale VM (and races whatever launched next)."""
-    return _infra_dir() / "booted-version"
-
-
-def _expected_version() -> str:
-    return infra_artifact.infra_artifact_version(_infra_init())
-
-
-def _adoptable(key: Path, url: str, want: str) -> bool:
-    """Adopt a running infra VM only if it booted from the CURRENT version and
-    its control plane is healthy. A missing/mismatched marker means a prior
-    launcher booted an older infra image — reboot rather than reuse stale code."""
-    if not key.exists():
-        return False
-    try:
-        booted = _version_file().read_text(encoding="utf-8").strip()
-    except OSError:
-        return False
-    return booted == want and _health_ok(url)
-
-
-def _record_booted_version(version: str) -> None:
-    _version_file().write_text(version + "\n", encoding="utf-8")
-
-
 # The registry "volume": a host-side ext4 file attached to the infra VM as a
 # second virtio-block device (guest /dev/vdb), mounted at the control plane's
 # DB dir. It outlives the ephemeral rootfs, so the bottle registry survives an
@@ -348,28 +309,6 @@ def _kill_pidfile() -> None:
        pass


-def _kill_infra_firecrackers(proc_root: Path = Path("/proc")) -> None:
-    """SIGKILL any firecracker VMM whose `--config-file` is this host's infra
-    config, independent of the PID file — reaps orphans it lost track of so the
-    orchestrator TAP is free to rebind. Scoped to the infra config path, so the
-    interactive pool's agent/infra VMs (other config paths) are untouched."""
-    cfg = str(_infra_dir() / "config.json")
-    for entry in proc_root.iterdir():
-        if not entry.name.isdigit():
-            continue
-        try:
-            if (entry / "comm").read_text().strip() != "firecracker":
-                continue
-            args = (entry / "cmdline").read_bytes().split(b"\0")
-        except OSError:
-            continue  # process vanished / not ours
-        if any(a.decode("utf-8", "replace") == cfg for a in args):
-            try:
-                os.kill(int(entry.name), signal.SIGKILL)
-            except (OSError, ValueError):
-                pass
-
-
 def _health_ok(url: str) -> bool:
    try:
        with urllib.request.urlopen(f"{url}/health", timeout=1.0) as resp:
@@ -494,7 +433,7 @@ BOT_BOTTLE_ROOT=/var/lib/bot-bottle python3 -m bot_bottle.orchestrator \\
 BOT_BOTTLE_GATEWAY_DAEMONS=egress,git-http,supervise \\
 BOT_BOTTLE_ORCHESTRATOR_URL=http://127.0.0.1:{CONTROL_PLANE_PORT} \\
 SUPERVISE_DB_PATH=/var/lib/bot-bottle/db/bot-bottle.db \\
-    python3 -m bot_bottle.gateway_init &
+    python3 /app/gateway_init.py &

 # Reap as PID 1; children are backgrounded, so `wait` blocks.
 while : ; do wait ; done
@@ -11,8 +11,7 @@ The `<version>` is `infra_artifact.infra_artifact_version(...)`, the content
 hash of the rootfs inputs, so a launch host at the same code checkout resolves
 the exact artifact this produced.

-  python3 -m bot_bottle.backend.firecracker.publish_infra --output DIR
-  python3 -m bot_bottle.backend.firecracker.publish_infra --publish-dir DIR
+  python3 -m bot_bottle.backend.firecracker.publish_infra [--dry-run] [--force]

 Auth: a token with `write:package` on the target owner, from
 `BOT_BOTTLE_INFRA_ARTIFACT_TOKEN`.
@@ -25,6 +24,7 @@ import gzip
 import hashlib
 import shutil
 import sys
+import tempfile
 import urllib.error
 import urllib.request
 from pathlib import Path
@@ -131,79 +131,36 @@ def build_artifact(out_dir: Path) -> tuple[str, Path, Path]:
    return version, gz, sha


-def _publish_bundle(root: Path, token: str) -> str:
-    version_file = root / "version.txt"
-    # Guard the read so a missing version.txt is a clean error, not a raw
-    # FileNotFoundError.
-    if not version_file.is_file():
-        raise SystemExit(f"incomplete artifact bundle: {root}")
-    version = version_file.read_text(encoding="utf-8").strip()
-    expected = infra_artifact.infra_artifact_version(infra_vm._infra_init())
-    if version != expected:
-        raise SystemExit(
-            f"artifact bundle version {version!r} does not match checkout {expected!r}"
-        )
-    gz = root / "rootfs.ext4.gz"
-    sha = root / "rootfs.ext4.gz.sha256"
-    if not gz.is_file() or not sha.is_file():
-        raise SystemExit(f"incomplete artifact bundle: {root}")
-    expected_sha = sha.read_text().split()[0].strip().lower()
-    if _sha256(gz) != expected_sha:
-        raise SystemExit("artifact bundle checksum mismatch")
-
-    gz_url = infra_artifact.artifact_url(version, gz.name)
-    sha_url = infra_artifact.artifact_url(version, sha.name)
-    about_url = infra_artifact.artifact_url(version, _ABOUT_NAME)
-
-    # Publishing is idempotent. If this exact complete artifact is already
-    # present, a test-only main commit is a no-op. Otherwise clear any partial
-    # upload left by an interrupted prior attempt and upload the complete set.
-    try:
-        with urllib.request.urlopen(infra_artifact._open(sha_url)) as resp:
-            remote_sha = resp.read().decode("utf-8").split()[0].strip().lower()
-    except urllib.error.HTTPError as e:
-        if e.code != 404:
-            raise SystemExit(f"checking existing artifact failed (HTTP {e.code})")
-        remote_sha = ""
-    except urllib.error.URLError as e:
-        raise SystemExit(f"registry unreachable: {sha_url} ({e.reason})")
-    if remote_sha == expected_sha:
-        print(f"infra rootfs {version} already published")
-        return version
-
-    for url in (gz_url, sha_url, about_url):
-        _delete(url, token)
-    _put(gz_url, gz, token)
-    _put(sha_url, sha.read_bytes(), token)
-    _put(about_url, _ABOUT_TEXT.encode(), token)
-    return version
-
-
 def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        prog="publish_infra", description="Build + publish the infra rootfs artifact.")
-    mode = parser.add_mutually_exclusive_group(required=True)
-    mode.add_argument("--output", type=Path,
-                      help="build a candidate bundle in DIR without publishing")
-    mode.add_argument("--publish-dir", type=Path,
-                      help="publish an already-built and tested candidate bundle")
+    parser.add_argument("--dry-run", action="store_true",
+                        help="build the artifact but do not upload")
+    parser.add_argument("--force", action="store_true",
+                        help="overwrite an already-published artifact of this version")
    args = parser.parse_args(argv)

    _, _, token = infra_artifact._config()
-    if args.publish_dir is not None and not token:
+    if not args.dry_run and not token:
        raise SystemExit(
            "no publish token: set BOT_BOTTLE_INFRA_ARTIFACT_TOKEN to a token "
            "with write:package")

-    if args.output is not None:
-        args.output.mkdir(parents=True, exist_ok=True)
-        version, _gz, _sha = build_artifact(args.output)
-        (args.output / "version.txt").write_text(version + "\n", encoding="utf-8")
-        print(f"built infra rootfs candidate {version}")
-        return 0
-
-    assert args.publish_dir is not None
-    version = _publish_bundle(args.publish_dir, token)
+    with tempfile.TemporaryDirectory(prefix="bb-publish-infra.") as tmp:
+        version, gz, sha = build_artifact(Path(tmp))
+        gz_url = infra_artifact.artifact_url(version, gz.name)
+        sha_url = infra_artifact.artifact_url(version, sha.name)
+        about_url = infra_artifact.artifact_url(version, _ABOUT_NAME)
+        if args.dry_run:
+            print(f"dry-run: would upload -> {gz_url}")
+            return 0
+        if args.force:
+            _delete(gz_url, token)
+            _delete(sha_url, token)
+            _delete(about_url, token)
+        _put(gz_url, gz, token)  # streamed from disk (hundreds of MB)
+        _put(sha_url, sha.read_bytes(), token)  # tiny, in-memory is fine
+        _put(about_url, _ABOUT_TEXT.encode(), token)  # package description
    print(f"published infra rootfs {version}")
    return 0

@@ -88,7 +88,7 @@ def require_firecracker() -> None:
    booting a VM without it."""
    if not is_linux():
        die("firecracker backend is only supported on Linux (KVM). "
-            "On macOS use the macos-container backend.")
+            "On macOS use --backend=macos-container.")
    if shutil.which("firecracker") is None:
        info("Firecracker is required but was not found on PATH.")
        info("Install: https://github.com/firecracker-microvm/firecracker/releases")
@@ -368,11 +368,6 @@ mount -t devtmpfs dev /dev 2>/dev/null
 mkdir -p /dev/pts && mount -t devpts devpts /dev/pts 2>/dev/null
 mount -o remount,rw / 2>/dev/null

-# /tmp must be world-writable + sticky. The rootless rootfs build can land
-# it 0755/root-owned, leaving the agent (uid 1000 node) unable to create
-# scratch dirs there — git worktrees, build temp, `git init /tmp/...`, etc.
-mkdir -p /tmp && chmod 1777 /tmp
-
 # Install the per-bottle SSH pubkey from the kernel cmdline.
 KEY=$(sed -n 's/.*bb_pubkey=\([^ ]*\).*/\1/p' /proc/cmdline | base64 -d 2>/dev/null)
 if [ -n "$KEY" ]; then
@@ -68,14 +68,9 @@ class MacosContainerBottle(Bottle):
        # reaches the agent (PRD 0070): registration mints it *after* the
        # container exists — its source IP is the registration key and Apple
        # Container assigns that by DHCP — so it cannot be in the run-time env
-        # the way docker's compose spec does it.
-        #
-        # `container exec --env` does NOT override a run-time value — it
-        # appends, leaving duplicate entries in the agent's `environ` whose
-        # resolution is runtime-specific (Node last-wins, Rust first-wins). So
-        # nothing here may rely on superseding: the proxy vars are supplied
-        # *only* at exec time and are deliberately absent from the run-time
-        # env. See `launch._agent_env_entries`.
+        # the way docker's compose spec does it. `container exec --env` wins
+        # over the run-time value, so the token-bearing proxy URL set here
+        # supersedes the token-less one baked in at launch.
        self._exec_env = dict(exec_env or {})
        self._closed = False

@@ -8,11 +8,7 @@ from ...bottle_state import read_metadata
 from .. import ActiveAgent
 from .infra import INFRA_NAME

-# The name every agent container carries: `bot-bottle-<slug>`. Exported
-# because callers that act on a running bottle (gateway-host rewrites,
-# registry reconciliation) have to map an enumerated slug back to a
-# container name.
-CONTAINER_NAME_PREFIX = "bot-bottle-"
+_PREFIX = "bot-bottle-"
 # The shared per-host infra container carries the same prefix as agent
 # containers but is infrastructure, not a bottle — one control plane + gateway
 # serves every agent, so listing it as an agent would invent one per host.
@@ -30,9 +26,9 @@ def enumerate_active() -> list[ActiveAgent]:
        return []
    out: list[ActiveAgent] = []
    for name in sorted(line.strip() for line in result.stdout.splitlines()):
-        if not name.startswith(CONTAINER_NAME_PREFIX) or name in _INFRA_NAMES:
+        if not name.startswith(_PREFIX) or name in _INFRA_NAMES:
            continue
-        slug = name[len(CONTAINER_NAME_PREFIX):]
+        slug = name[len(_PREFIX):]
        metadata = read_metadata(slug)
        out.append(ActiveAgent(
            backend_name="macos-container",
@@ -1,96 +0,0 @@
-"""Stable gateway name for macOS agents, via each bottle's `/etc/hosts`.
-
-The shared gateway's address is assigned by vmnet's DHCP and changes whenever
-the infra container is recreated — a source-hash bump, an image upgrade, a
-crash. Every agent-facing URL (egress proxy, git-http, supervise) embeds that
-address, and the proxy URL reaches the agent as **process environment** at
-`container exec` time. A running process's `environ` cannot be rewritten from
-outside, so a moved gateway used to strand every running bottle permanently:
-not degraded, unreachable, until the bottle was relaunched and its session
-thrown away.
-
-So the agent never learns the address. It is given a stable *name*
-(`GATEWAY_HOSTNAME`) in every URL, resolved through its own `/etc/hosts`.
-Unlike `environ`, that is a file — it can be rewritten inside a container that
-is already running, so a gateway that comes back at a new address is picked up
-by live bottles instead of orphaning them.
-
-Apple Container 1.0 offers no container-name DNS on a user network (the only
-nameserver an agent sees is vmnet's, which does not know container names) and
-`container run` has no `--add-host`, so the entry is written by exec after the
-container starts.
-
-Writing it needs root, and the agent runs as `node`: the agent therefore
-cannot repoint its own gateway name, while the host (which drives `container
-exec --user root`) can. That asymmetry is deliberate — keep it.
-"""
-
-from __future__ import annotations
-
-from ...log import warn
-from . import util as container_mod
-from .enumerate import CONTAINER_NAME_PREFIX, enumerate_active
-
-# The name every agent-facing gateway URL uses. Must not collide with a real
-# DNS name the agent might resolve; it is bottle-local by construction.
-GATEWAY_HOSTNAME = "bot-bottle-gateway"
-
-# Marker so the rewrite is idempotent and only ever touches our own line —
-# the rest of /etc/hosts (localhost, the container's own name) is preserved.
-_MARKER = "# bot-bottle gateway"
-
-
-def _rewrite_script(gateway_ip: str) -> str:
-    """A shell one-liner that replaces our managed line in `/etc/hosts`.
-
-    Rewrites in place via a temp file + `cat` rather than `mv`, so the file
-    keeps its original inode, ownership, and mode — a bind-mounted or
-    pre-created `/etc/hosts` must not be replaced by a root-owned 0644 copy
-    that the runtime then refuses to update.
-    """
-    return (
-        "set -e; "
-        f"grep -v '{_MARKER}' /etc/hosts > /tmp/.bb-hosts || true; "
-        f"printf '%s %s %s\\n' '{gateway_ip}' '{GATEWAY_HOSTNAME}' "
-        f"'{_MARKER}' >> /tmp/.bb-hosts; "
-        "cat /tmp/.bb-hosts > /etc/hosts; "
-        "rm -f /tmp/.bb-hosts"
-    )
-
-
-def set_gateway_host(container_name: str, gateway_ip: str) -> None:
-    """Point `GATEWAY_HOSTNAME` at `gateway_ip` inside one running container.
-
-    Must run before the agent is exec'd: the agent's proxy URL names the
-    gateway, so the entry has to exist for its first connection. Idempotent —
-    re-running with the same address is a no-op in effect.
-    """
-    container_mod.exec_container_as_root(
-        container_name, ["sh", "-c", _rewrite_script(gateway_ip)],
-    )
-
-
-def refresh_gateway_host(gateway_ip: str) -> list[str]:
-    """Re-point every running bottle at the current gateway address.
-
-    Called once the shared gateway is known to be up, so a bottle stranded by
-    an earlier gateway restart re-attaches instead of needing a relaunch.
-    Returns the containers updated.
-
-    Best-effort per bottle: one container that refuses the write (already
-    exiting, say) must not stop the others from being repaired, and must not
-    fail the launch that triggered the sweep.
-    """
-    updated: list[str] = []
-    for agent in enumerate_active():
-        name = f"{CONTAINER_NAME_PREFIX}{agent.slug}"
-        try:
-            set_gateway_host(name, gateway_ip)
-            updated.append(name)
-        # One bad bottle must not stop the sweep, so this is deliberately broad.
-        except Exception as e:  # noqa: BLE001  # pylint: disable=broad-exception-caught
-            warn(f"could not re-point {name} at the gateway: {e}")
-    return updated
-
-
-__all__ = ["GATEWAY_HOSTNAME", "set_gateway_host", "refresh_gateway_host"]
@@ -101,7 +101,7 @@ def _init_script(port: int) -> str:
        # Gateway data plane, multi-tenant against the local control plane.
        f"( cd /app && BOT_BOTTLE_GATEWAY_DAEMONS={_GATEWAY_DAEMONS} "
        f"BOT_BOTTLE_ORCHESTRATOR_URL=http://127.0.0.1:{port} "
-        f"SUPERVISE_DB_PATH={_DB_PATH_IN_CONTAINER} python3 -m bot_bottle.gateway_init ) &\n"
+        f"SUPERVISE_DB_PATH={_DB_PATH_IN_CONTAINER} python3 /app/gateway_init.py ) &\n"
        "while : ; do wait ; done\n"
    )

@@ -59,11 +59,6 @@ from ..docker.egress import EGRESS_PORT
 from ..util import AGENT_CA_BUNDLE, AGENT_CA_PATH
 from . import util as container_mod
 from .bottle import MacosContainerBottle
-from .gateway_hosts import (
-    GATEWAY_HOSTNAME,
-    refresh_gateway_host,
-    set_gateway_host,
-)
 from .bottle_plan import MacosContainerBottlePlan
 from .consolidated_launch import (
    GatewayEndpoint,
@@ -105,11 +100,6 @@ def launch(
        # Step 1: the per-host singletons. Must precede the agent run — its
        # proxy env needs the gateway's address at `container run` time.
        endpoint = ensure_gateway()
-        # The gateway's address may have changed since these bottles launched
-        # (any infra recreate re-runs DHCP). They name the gateway rather than
-        # address it, so re-pointing /etc/hosts re-attaches them in place
-        # instead of leaving them stranded until relaunch.
-        refresh_gateway_host(endpoint.gateway_ip)

        # Step 2: mint this bottle's deploy keys, then point it at the SHARED
        # gateway's CA + git-http/supervise ports.
@@ -127,9 +117,6 @@ def launch(
        # attribution key; `--cap-drop CAP_NET_RAW` at run is what makes it
        # unforgeable. Poll: `container run --detach` can return before vmnet's
        # DHCP has assigned the address.
-        # Resolve the gateway name before anything execs: every agent-facing
-        # URL uses it, so the entry must exist for the first connection.
-        set_gateway_host(plan.container_name, endpoint.gateway_ip)
        source_ip = container_mod.wait_container_ipv4_on_network(
            plan.container_name, endpoint.network,
        )
@@ -244,20 +231,13 @@ def _stamp_agent_urls(
 ) -> MacosContainerBottlePlan:
    """Point the agent's git-gate insteadOf rewrites + supervise MCP at the
    shared gateway's ports. Both bypass the egress proxy (NO_PROXY covers the
-    gateway name).
-
-    Addressed by `GATEWAY_HOSTNAME`, never by IP: these URLs are baked into
-    the agent's gitconfig and MCP config at provision time, so an address here
-    would strand the bottle the moment the gateway moved. The name is resolved
-    per connection through `/etc/hosts`, which stays rewritable while the
-    bottle runs."""
-    del endpoint  # addressed by name; the address reaches the bottle via /etc/hosts
+    gateway address)."""
    git_gate_url = (
-        f"http://{GATEWAY_HOSTNAME}:{_GIT_HTTP_PORT}"
+        f"http://{endpoint.gateway_ip}:{_GIT_HTTP_PORT}"
        if plan.git_gate_plan.upstreams else ""
    )
    supervise_url = (
-        f"http://{GATEWAY_HOSTNAME}:{SUPERVISE_PORT}/"
+        f"http://{endpoint.gateway_ip}:{SUPERVISE_PORT}/"
        if plan.supervise_plan is not None else ""
    )
    return dataclasses.replace(
@@ -267,43 +247,30 @@ def _stamp_agent_urls(
    )


-def _proxy_url(identity_token: str = "") -> str:
+def _proxy_url(gateway_ip: str, identity_token: str = "") -> str:
    """The agent's egress proxy URL. The identity token rides as proxy
    credentials — the gateway reads Proxy-Authorization, resolves the
    (source_ip, token) pair against the control plane, and strips it before
-    upstream. Without a valid pair `/resolve` denies the request (#366).
-
-    Names the gateway rather than addressing it: this URL reaches the agent as
-    process environment, which cannot be rewritten once the agent is running,
-    so an address baked here is unfixable if the gateway moves."""
+    upstream. Without a valid pair `/resolve` denies the request (#366)."""
    cred = f"bottle:{identity_token}@" if identity_token else ""
-    return f"http://{cred}{GATEWAY_HOSTNAME}:{EGRESS_PORT}"
+    return f"http://{cred}{gateway_ip}:{EGRESS_PORT}"


-def _no_proxy() -> str:
+def _no_proxy(gateway_ip: str) -> str:
    # git-http + supervise live on the gateway and must NOT go through the
-    # egress proxy — the agent reaches them directly by name. Deliberately
-    # address-free: NO_PROXY is baked into the run-time env and is therefore
-    # just as unfixable as the proxy URL if the gateway moves.
-    return f"localhost,127.0.0.1,{GATEWAY_HOSTNAME}"
+    # egress proxy — the agent reaches them directly by its address.
+    return f"localhost,127.0.0.1,{gateway_ip}"


 def _identity_proxy_env(
    endpoint: GatewayEndpoint, identity_token: str,
 ) -> dict[str, str]:
-    """The token-bearing proxy env applied at `container exec` — the only way
-    to get the token in, since it does not exist until after the container
-    runs (registration keys on the DHCP-assigned address).
-
-    This is the *sole* source of `*_PROXY` for the agent. It deliberately does
-    not rely on overriding a run-time value: `container exec --env` appends
-    rather than replaces, so a run-time `HTTPS_PROXY` would survive alongside
-    this one and first-wins runtimes would read the wrong entry. See
-    `_agent_env_entries`."""
+    """The token-bearing proxy env applied at `container exec`. It supersedes
+    the token-less run-time value (exec `--env` wins), which is the only way to
+    get the token in: it does not exist until after the container runs."""
    if not identity_token:
        return {}
-    del endpoint  # the gateway is named, not addressed
-    url = _proxy_url(identity_token)
+    url = _proxy_url(endpoint.gateway_ip, identity_token)
    return {
        "HTTPS_PROXY": url, "HTTP_PROXY": url,
        "https_proxy": url, "http_proxy": url,
@@ -350,23 +317,16 @@ def _agent_run_argv(
 def _agent_env_entries(
    plan: MacosContainerBottlePlan, endpoint: GatewayEndpoint,
 ) -> tuple[str, ...]:
-    # No `*_PROXY` here on purpose. The token-bearing URL is applied at
-    # `container exec` (`_identity_proxy_env`), and Apple's `container exec
-    # --env` **appends** to the run-time environment rather than replacing it:
-    # setting a token-less value here leaves two `HTTPS_PROXY` entries in the
-    # agent's `environ`, token-less first. Which one a runtime reads is then
-    # pure luck — Node takes the last (and worked), Rust's `std::env::var`
-    # takes the first, so Codex proxied without its identity token and
-    # `/resolve` fail-closed on every request.
-    #
-    # A token-less proxy URL has no legitimate consumer anyway: the init
-    # process is `sleep` and everything that egresses arrives via exec. Its
-    # only value was a tidy 403 for unattributed callers, which is not worth
-    # silently dropping attribution for. Without it a process that egresses
-    # before the exec-time env still fails closed — the agent network is
-    # host-only, so there is no route off it except the gateway.
-    no_proxy = _no_proxy()
+    # Token-less at run time — the token does not exist yet (see
+    # `_identity_proxy_env`). Anything egressing before the exec-time override
+    # is denied by `/resolve`, which is the safe direction.
+    proxy_url = _proxy_url(endpoint.gateway_ip)
+    no_proxy = _no_proxy(endpoint.gateway_ip)
    env = [
+        f"HTTPS_PROXY={proxy_url}",
+        f"HTTP_PROXY={proxy_url}",
+        f"https_proxy={proxy_url}",
+        f"http_proxy={proxy_url}",
        f"NO_PROXY={no_proxy}",
        f"no_proxy={no_proxy}",
        f"NODE_EXTRA_CA_CERTS={AGENT_CA_PATH}",
@@ -360,21 +360,6 @@ def exec_container(name: str, argv: list[str]) -> None:
        )


-def exec_container_as_root(name: str, argv: list[str]) -> None:
-    """`exec_container`, but as uid 0 inside the container.
-
-    For host-driven maintenance the agent itself must not be able to perform —
-    rewriting `/etc/hosts` to point the gateway name at an address. The agent
-    runs as `node`, so it cannot repoint its own gateway; the host can.
-    """
-    result = _run_container_op([_CONTAINER, "exec", "--user", "root", name, *argv])
-    if result.returncode != 0:
-        die(
-            f"container exec (root) in {name} failed: "
-            f"{(result.stderr or '').strip() or '<no stderr>'}"
-        )
-
-
 def _run_container_op(cmd: list[str]) -> subprocess.CompletedProcess[str]:
    result = subprocess.run(
        cmd,
@@ -3,10 +3,18 @@
 from __future__ import annotations

 import os
+import sys
 from pathlib import Path

-from ..util import read_tty_line as read_tty_line
-
 PROG = "cli.py"
 USER_CWD = os.getcwd()
 REPO_DIR = str(Path(__file__).resolve().parent.parent.parent)
+
+
+def read_tty_line() -> str:
+    """Mirror `IFS= read -r REPLY </dev/tty`. Falls back to stdin."""
+    try:
+        with open("/dev/tty", "r", encoding="utf-8") as tty:
+            return tty.readline().rstrip("\n")
+    except OSError:
+        return sys.stdin.readline().rstrip("\n")
@@ -21,20 +21,16 @@ from __future__ import annotations

 import sys

-from ..backend import get_bottle_backend, has_backend, known_backend_names
+from ..backend import get_bottle_backend, known_backend_names
 from ..log import info
 from ._common import read_tty_line


 def cmd_cleanup(_argv: list[str]) -> int:
    # Order: stable backend iteration so the y/N output is
-    # deterministic across runs. Skip backends whose runtime
-    # isn't available on this host so e.g. macos-container
-    # doesn't error on Linux.
+    # deterministic across runs.
    plans = [
-        (name, get_bottle_backend(name))
-        for name in known_backend_names()
-        if has_backend(name)
+        (name, get_bottle_backend(name)) for name in known_backend_names()
    ]
    prepared = [(name, b, b.prepare_cleanup()) for name, b in plans]

@@ -27,6 +27,7 @@ from ..backend import (
    BottleSpec,
    enumerate_active_agents,
    get_bottle_backend,
+    known_backend_names,
 )
 from ..backend.docker import util as docker_mod
 from ..backend.docker.bottle_plan import DockerBottlePlan
@@ -56,6 +57,15 @@ def cmd_start(argv: list[str]) -> int:
            "into a cached layer."
        ),
    )
+    parser.add_argument(
+        "--backend",
+        choices=known_backend_names(),
+        default=None,
+        help=(
+            "backend to launch the bottle on (default: $BOT_BOTTLE_BACKEND "
+            "or host auto-selection). Overrides the env var when set."
+        ),
+    )
    parser.add_argument(
        "--headless",
        action="store_true",
@@ -105,10 +115,11 @@ def cmd_start(argv: list[str]) -> int:
        os.environ["BOT_BOTTLE_NO_CACHE"] = "1"

    manifest = ManifestIndex.resolve(USER_CWD)
+    backend_name: str | None = args.backend

    if args.headless:
        return _start_headless(
-            manifest, args, dry_run=dry_run
+            manifest, args, dry_run=dry_run, backend_name=backend_name
        )

    agent_name: str | None = args.name
@@ -159,6 +170,7 @@ def cmd_start(argv: list[str]) -> int:
    return _launch_bottle(
        spec,
        dry_run=dry_run,
+        backend_name=backend_name,
    )


@@ -170,6 +182,7 @@ def _start_headless(
    args: argparse.Namespace,
    *,
    dry_run: bool,
+    backend_name: str | None,
 ) -> int:
    """Non-interactive launch path for orchestrators / CI / webhooks.

@@ -217,6 +230,7 @@ def _start_headless(
    return _launch_bottle(
        spec,
        dry_run=dry_run,
+        backend_name=backend_name,
        assume_yes=True,
        headless_prompt_text=prompt,
    )
@@ -254,18 +268,15 @@ def prepare_with_preflight(
    injected callable, prompt y/N via the injected callable.

    `backend_name` selects which backend prepares the plan
-    (`None` → `$BOT_BOTTLE_BACKEND` → host auto-selection).
-
-    When `spec.headless` is True the docker-fallback prompt is suppressed:
-    auto-selection dies with an actionable message rather than blocking
-    on a TTY read (which would hang CI, webhook dispatch, and orchestrators).
+    (`None` → `$BOT_BOTTLE_BACKEND` → host auto-selection). The CLI
+    passes whatever `--backend` resolved to.

    Returns `(plan, identity)`. `plan` is None on dry-run or
    operator-N, but `identity` is set as soon as `backend.prepare`
    returns so callers can reap the prepare-time state dir via
    `settle_state(identity)` in their finally — exactly the existing
    semantics."""
-    backend = get_bottle_backend(backend_name, prompt=not spec.headless)
+    backend = get_bottle_backend(backend_name)
    plan = backend.prepare(spec, stage_dir=stage_dir)
    identity = _identity_from_plan(plan)

@@ -7,7 +7,6 @@ from __future__ import annotations

 import ipaddress
 import os
-import sys


 def is_ip_literal(value: str) -> bool:
@@ -18,15 +17,6 @@ def is_ip_literal(value: str) -> bool:
    return True


-def read_tty_line() -> str:
-    """Mirror `IFS= read -r REPLY </dev/tty`. Falls back to stdin."""
-    try:
-        with open("/dev/tty", "r", encoding="utf-8") as tty:
-            return tty.readline().rstrip("\n")
-    except OSError:
-        return sys.stdin.readline().rstrip("\n")
-
-
 def expand_tilde(path: str) -> str:
    """Expand a leading '~' to $HOME. Leaves paths without a leading
    tilde unchanged. Falls back to the empty string if $HOME is unset
@@ -1,6 +1,6 @@
 # PRD 0023: smolmachines bottle backend

-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.

 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis
@@ -1,6 +1,6 @@
 # PRD 0032: Decompose smolmachines launch and harden bringup sequencing

-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.

 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis-claude
@@ -1,6 +1,6 @@
 # PRD 0038: smolmachines Env Contract and Secret-Safe Injection

-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.

 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis-codex
@@ -1,6 +1,6 @@
 # PRD 0039: smolmachines Capability-Block Remediation

-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.

 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis-codex
@@ -1,6 +1,6 @@
 # PRD 0042: smolmachines Cross-Backend Parity Tests

-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.

 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis-codex
@@ -1,6 +1,6 @@
 # PRD 0057: Promote smolmachines to default backend; convert Docker to example-only

-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.

 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis
@@ -1,6 +1,6 @@
 # PRD 0068: smolmachines backend on Linux

-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.

 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** Claude
@@ -1,110 +0,0 @@
-# PRD prd-new: CI artifact-based coverage and local Firecracker candidate flow
-
- **Status:** Active
- **Author:** Claude
- **Created:** 2026-07-21
- **Issue:** #446
-
-## Summary
-
-Restructure the CI test pipeline to run each test suite exactly once, upload
-small `.coverage.*` artifacts, and combine them in a lightweight aggregation
-job. Move the infra build onto the KVM runner so the ~194 MB rootfs never
-crosses the network for PRs. On main-branch pushes, publish the byte-identical
-rootfs that was tested.
-
-## Motivation
-
-The prior pipeline had two redundant costs:
-
-1. **Duplicate artifact transfers.** `build-infra` (ubuntu-latest) built and
-   uploaded the ~194 MB rootfs; `integration-firecracker` downloaded it; the
-   `coverage` job downloaded it a second time. Combined download overhead: ~83
-   seconds per run, plus the ~70-second upload.
-
-2. **Duplicate test execution.** `integration-firecracker` ran the Firecracker
-   integration suite; `coverage` ran the entire unit + integration suite again
-   on the same KVM runner to collect coverage data. Every line of Firecracker
-   code was tested twice per CI run.
-
-## Goals
-
- Each test suite (unit, integration-docker, integration-firecracker) executes
-  exactly once per workflow run.
- PRs incur no large artifact transfers — the rootfs stays on the KVM runner.
- Main-branch pushes publish a byte-for-byte identical rootfs to the one that
-  passed the integration tests.
- Concurrent workflow runs cannot cross-publish candidates (naturally enforced
-  by Gitea Actions' per-run artifact scoping).
- Failed or cancelled runs block publication (enforced by the `needs:` chain on
-  `publish-infra`).
-
-## Non-goals
-
- Changing test semantics or the coverage policy (ADR 0004).
- Removing the KVM runner guard on `integration-firecracker` and `coverage`.
- Changing how `publish_infra.py` builds or uploads the rootfs.
-
-## Design
-
-### Job graph
-
-```
-unit ──────────────────────────────────┐
-integration-docker ────────────────────┤──► coverage ──► publish-infra (main only)
-integration-firecracker (KVM) ─────────┘
-```
-
-### `unit`
-
-Unchanged except: `coverage run` writes `--data-file=.coverage.unit`; the file
-is uploaded as the `coverage-unit` artifact.
-
-### `integration-docker`
-
-Adds a `coverage` install step. `coverage run` writes `--data-file=.coverage.docker`;
-the file is uploaded as `coverage-docker`.
-
-### `integration-firecracker` (KVM runner)
-
-Replaces the old `stage-firecracker-inputs` → `build-infra` → download chain:
-
-1. Builds the infra candidate locally with
-   `BOT_BOTTLE_FC_DROPBEAR=/var/cache/bot-bottle-fc/dropbear`.
-2. Boots the candidate and runs integration tests with coverage, writing
-   `.coverage.firecracker`.
-3. Uploads the small `coverage-firecracker` artifact unconditionally.
-4. On main-branch pushes only, uploads the rootfs as `infra-candidate` and the
-   dropbear as `firecracker-inputs` so `publish-infra` can verify and publish
-   the byte-identical artifact.
-
-### `coverage`
-
-Moves from a KVM runner to `ubuntu-latest`. No tests are re-executed:
-
-1. Downloads `coverage-unit`, `coverage-docker`, and `coverage-firecracker`.
-2. Runs `scripts/coverage.sh aggregate critical`, which calls
-   `coverage combine` then `coverage report`.
-3. Runs the diff-coverage gate (`scripts/diff_coverage.py`).
-
-Coverage files use `relative_files = True` (`.coveragerc`) so they combine
-cleanly across runners with different absolute workspace paths.
-
-### `publish-infra`
-
-Depends on all four predecessor jobs (unchanged gate). Downloads `infra-candidate`
-and `firecracker-inputs` that were uploaded by `integration-firecracker` on
-main — the same byte sequence that passed the integration tests.
-
-### Eliminated jobs
-
- `stage-firecracker-inputs`: existed only to copy the dropbear to ubuntu-latest
-  for `build-infra`. No longer needed.
- `build-infra`: the infra candidate is now built on the KVM runner in
-  `integration-firecracker`.
-
-### Script changes
-
-`scripts/coverage.sh` gains an `aggregate` mode (`coverage.sh aggregate [critical]`)
-that combines pre-existing `.coverage.*` files instead of re-running tests.
-The existing run mode (`coverage.sh [critical]`) is preserved for local dev.
@@ -1,16 +1,16 @@
 # Landscape: AI-agent sandbox tools

-Survey of AI-agent sandbox and containment projects — including local
-coding-agent wrappers, agent-agnostic runtimes, hosted platforms, and
-governance layers — contrasted with bot-bottle's design. The original
-Claude-Code-specific containerizer survey was folded into this note on
-2026-07-20 so there is one landscape and one positioning verdict.
+A broader survey than [`landscape-containerized-claude.md`](landscape-containerized-claude.md),
+which focused on Claude-Code-specific containerizers. This one covers
+general AI-agent sandbox / containment projects — some Claude-specific,
+some agent-agnostic, some hosted SaaS — and contrasts them with
+bot-bottle's design.

 Research conducted 2026-05-11. CubeSandbox added 2026-07-18 (see its
 per-project note and the addendum at the end). Also updated 2026-07-18:
 bot-bottle no longer uses **pipelock** — outbound DLP is now bot-bottle's
 own (deliberately simple) egress scanner (a mitmproxy addon with custom
-detectors, PRD 0017 / 0052), and git-push secret scanning is handled by
+detectors, PRD 0017 / 0053), and git-push secret scanning is handled by
 **gitleaks** in the git-gate. "pipelock" below has been replaced with the
 current mechanism; it survives only in older PRDs as history.

@@ -20,24 +20,12 @@ Passport); an **Agent-tailored policy** row added to the comparison table;
 a separate Governance layers section added for AGT and OAP. See the
 second addendum at the end.

-Updated 2026-07-20: the borrowable-ideas status was reconciled with the
-current implementation. In-flight credential injection and the microVM
-backends have shipped, while per-use SSH confirmation was superseded by
-keeping git credentials out of the agent entirely.
-
-Also updated 2026-07-20: **E2B and Daytona added as first-class entries.**
-Earlier revisions mentioned E2B only as the API and lifecycle model that
-CubeSandbox implements, and omitted Daytona entirely. That was a survey gap,
-not a principled scope exclusion: both are major hosted sandbox platforms and
-belong in this landscape even though they target platform builders rather than
-bot-bottle's local single-operator workflow.
-
 ## Summary

-The main table compares bot-bottle against fifteen isolation/sandbox tools.
-Governance/pre-action authorization and credential-only layers are covered
-separately because they don't provide VM or container isolation. None
-duplicate bot-bottle's combination of local
+Fifteen projects surveyed across two categories: isolation/sandbox tools
+and governance/pre-action authorization layers (the latter don't provide
+VM or container isolation but do per-agent policy enforcement at the
+tool-call level). None duplicate bot-bottle's combination of local
 VM-per-bottle isolation, a declarative per-role manifest, per-agent
 egress allowlist + outbound-content DLP, bottle/agent split, and the
 composable `extends:` policy model. Three clusters stand out:
@@ -46,9 +34,8 @@ composable `extends:` policy model. Three clusters stand out:
  single-user, thin wrappers over an existing OS primitive
  (`sandbox-exec`, Podman + Landlock).
 - **Different category (isolation)** — tilde.run (hosted SaaS), boxlite
-  and microsandbox (microVM libraries for platform builders), E2B and Daytona
-  (hosted sandbox platforms), CubeSandbox (self-hosted multi-tenant microVM
-  service), endo-familiar
+  and microsandbox (microVM libraries for platform builders), CubeSandbox
+  (self-hosted multi-tenant microVM service), endo-familiar
  (capability-security paradigm, no OS isolation).
 - **New: governance/pre-action layers** — Microsoft AGT and Open Agent
  Passport (OAP): framework-embedded tool-call interceptors with
@@ -65,17 +52,15 @@ ergonomic enough that microVMs are **now bot-bottle's default backend**
 only as a legacy fallback for CI / hosts without KVM or Apple Container.
 That discussion has since shipped, not just been theorized.

-**The one that matters most for positioning is CubeSandbox** — it ships
-bot-bottle's bundle of default-deny egress allowlisting, full audit logs, and
-in-flight credential custody *combined with* per-sandbox microVM isolation,
+**The one that matters most for positioning is CubeSandbox** — it is the
+first surveyed project to ship bot-bottle's would-be wedge (default-deny
+egress allowlist + full audit logs + in-flight credential custody so keys
+never enter the sandbox) *combined with* per-sandbox microVM isolation,
 open-source under Apache 2.0, with Tencent Cloud behind it and 10.4k
 stars. It's a self-hosted multi-tenant service for platform builders, not
 a single-user declarative tool, so it doesn't collide head-on — but it
 narrows the "nobody else bundles egress custody + credential injection"
-claim that the monetization positioning leans on. Daytona now also offers
-domain/CIDR firewall policy plus in-flight header credential substitution and
-response scrubbing, although its higher tiers are not default-deny and its
-production platform is proprietary. See the addendum.
+claim that the monetization positioning leans on. See the addendum.

 ## Per-project notes

@@ -112,8 +97,7 @@ production platform is proprietary. See the addendum.

 ### agent-safehouse
 - **Source**: https://agent-safehouse.dev/ ; https://github.com/eugene1g/agent-safehouse
- **HN launch**: [#47301085](https://news.ycombinator.com/item?id=47301085) (March 12 2026) — 823 points
- **License**: Apache 2.0 (~1,781 stars at launch)
+- **License**: Apache 2.0 (~1,400 stars)
 - **Isolation**: macOS `sandbox-exec` (Seatbelt) profiles — kernel-level
  syscall interception, no container.
 - **Locality**: Local, macOS only.
@@ -123,16 +107,6 @@ production platform is proprietary. See the addendum.
 - **Config**: Shell functions or custom `sandbox-exec` profile files;
  LLM-assisted profile generation supported.
 - **Network policy**: Not addressed.
- **Notable from HN thread**: Creator acknowledged the project is "just a
-  policy-generator for `sandbox-exec` — no dependencies, no daemons, no
-  subscription; I did put in many hours to identify the minimum required
-  permissions for agents to continue working." Simon Willison noted that
-  evaluating whether a sandboxing tool actually works as intended is hard.
-  Top community sentiment: *"I honestly think that sandboxing is currently
-  THE major challenge that needs to be solved for the tech to fully realise
-  its potential."* The macOS Docker gap (Docker for Mac runs inside a Linux
-  VM, so `sandbox-exec` is the only native primitive for bare-metal macOS
-  processes) was the stated motivation.
 - **Maturity**: Active through March 2026.

 ### matchlock
@@ -215,80 +189,6 @@ production platform is proprietary. See the addendum.
  also supported.
 - **Maturity**: Active through April 2026.

-### E2B *(added 2026-07-20)*
-
- **Source**: https://github.com/e2b-dev/e2b ; https://e2b.dev/docs
- **License**: Apache 2.0 (~12.4k stars); commercial hosted service with
-  self-hosting/BYOC support.
- **Isolation**: Firecracker microVM per sandbox.
- **Locality**: Cloud-hosted by default; self-hosting uses Terraform on AWS or
-  GCP (with other targets documented as works in progress).
- **Agent integration**: LLM-agnostic Python and JavaScript/TypeScript SDKs;
-  code-interpreter and desktop-sandbox products. Platform primitive rather
-  than a coding-agent wrapper.
- **Config**: Programmatic SDK/API plus templates. Network configuration
-  supports internet on/off, outbound allow/deny rules, and a custom egress
-  proxy.
- **Network policy**: Configurable per sandbox, but not documented as
-  default-deny and no built-in outbound-content DLP is documented.
- **Credentials**: Environment variables passed to the sandbox are explicitly
-  not private at the OS level. No built-in in-flight application-credential
-  injection is documented.
- **Persistence**: Full memory + filesystem pause/resume, snapshots, and
-  auto-resume. Continuous runtime is tier-limited, while paused sandboxes are
-  retained indefinitely.
- **Maturity**: Established hosted platform and the API compatibility target
-  used by CubeSandbox.
-
-### Daytona *(added 2026-07-20)*
-
- **Source**: https://github.com/daytonaio/daytona ;
-  https://www.daytona.io/docs/
- **License**: Current production platform is proprietary. The former AGPL
-  repository remains public but is no longer maintained after Daytona moved
-  production development closed-source in June 2026.
- **Isolation**: Hosted container sandboxes by default, with separate Linux
-  and Windows VM sandbox classes for dedicated-OS workloads. Each sandbox has
-  its own filesystem and network stack; VM-only features include memory
-  pause/resume and forking.
- **Locality**: Hosted multi-tenant service, with dedicated/custom regions and
-  customer runners available.
- **Agent integration**: LLM/framework-agnostic SDKs (Python, TypeScript, Go,
-  Ruby, Java), API, and CLI; official agent-framework guides. Platform
-  primitive rather than a local coding-agent wrapper.
- **Config**: Programmatic per-sandbox image/snapshot, resources, lifecycle,
-  firewall, and secrets.
- **Network policy**: Per-sandbox IPv4/domain allowlists and block-all mode,
-  subordinate to organization/tier policy. Full internet access is the
-  default on higher tiers, so it is configurable rather than uniformly
-  default-deny.
- **Credentials**: First-class secret manager with the same phantom-token
-  pattern as bot-bottle: the sandbox environment gets an opaque placeholder,
-  an HTTPS proxy substitutes the real secret in headers only for allowed
-  hosts, and responses are scrubbed back to the placeholder.
- **Persistence**: Persistent filesystem for stopped container sandboxes;
-  memory + filesystem pause/resume for VM sandboxes; snapshots and configurable
-  auto-stop.
- **Maturity**: Production commercial platform. Notable April 2026 credential
-  exposure was patched; the June 2026 closed-source transition materially
-  changes its transparency/self-hosting posture.
-
-### Other hosted runtimes carried forward from the earlier survey
-
- **Northflank Sandboxes** — hosted or customer-cloud, microVM-backed
-  containers with SDK-managed lifecycle, optional persistent volumes, and
-  sub-second claimed boot. This is a platform primitive for untrusted code and
-  agents, not a local agent wrapper or role-policy layer.
- **Cloudflare Sandbox SDK** — Workers/Durable Objects API over VM-isolated
-  Linux containers for command, file, process, and service execution. It is a
-  hosted TypeScript platform primitive; application authentication,
-  authorization, and credential-proxy patterns remain the integrator's job.
-
-Both belong to the same “build your agent platform on this runtime” category as
-E2B and Daytona. They were named but not analyzed in depth by the original
-Claude-specific note, so they remain outside the main comparison table rather
-than being presented with false precision.
-
 ### CubeSandbox *(added 2026-07-18)*
 - **Source**: https://github.com/TencentCloud/CubeSandbox ;
  HN launch https://news.ycombinator.com/item?id=47863430
@@ -405,92 +305,6 @@ than being presented with false precision.
  preview — APIs may change.
 - **Maturity**: Early research preview.

-## Claude-specific wrappers and developer environments
-
-These projects were the focus of the original containerized-Claude survey.
-They remain useful comparisons for local developer experience, but most are
-templates or wrappers rather than policy-bearing sandbox platforms, so they
-are grouped here instead of widening the main table further.
-
-### claudebox
-
- **Source**: https://github.com/RchGrav/claudebox
- **Isolation**: Docker, with per-project images, authentication state, and
-  configuration.
- **Agent integration**: Claude Code wrapper with 15+ preconfigured language
-  and task profiles.
- **Network policy**: Per-project firewall allowlists.
- **Closest overlap**: local one-command developer workflow and project-scoped
-  network policy.
- **Difference**: profiles describe development toolchains, not named agent
-  roles. There is no bottle/agent split, composable role manifest, provider
-  plugin layer, or outbound-content DLP.
-
-### Spritz / claude-code-sandbox
-
- **Source**: https://github.com/textcortex/claude-code-sandbox (archived;
-  points to its successor, Spritz).
- **Isolation**: The original project ran Claude Code in local Docker with
-  bypass permissions; Spritz moved toward Kubernetes-native multi-agent
-  infrastructure.
- **Difference**: the successor targets cluster orchestration rather than a
-  low-dependency local launcher. It is architecturally closer to hosted or
-  Kubernetes platform runtimes than to bot-bottle's single-operator CLI.
-
-### Trail of Bits claude-code-devcontainer
-
- **Source**: https://github.com/trailofbits/claude-code-devcontainer
- **Isolation**: A Docker devcontainer that exposes only project files and is
-  designed to run Claude Code with `bypassPermissions` for security audits and
-  untrusted-code review.
- **Difference**: a hardened, reusable environment definition rather than an
-  agent launcher or fleet. It has no named-role manifest, per-role credential
-  custody, supervision plane, or multi-backend abstraction.
-
-### Smaller wrappers and official templates
-
-Projects such as `arezi/claude-sandbox`, `nkrefman/claude-sandbox`, and
-`VishalJ99/claude-docker`, plus Docker/Anthropic devcontainer templates, prove
-there is steady demand for “Claude in a container.” They are deliberately
-small launch/build configurations. They compete on setup simplicity, not on
-role-aware policy, credential custody, persistent supervision, or a fleet
-model, and are better treated as a product category than as individual rows.
-
-### SuperHQ
-
- **Source**: https://superhq.ai/
- **Isolation**: Apple-Silicon desktop application using local microVMs via
-  Virtualization.framework/libkrun-era components.
- **Agent integration**: Claude Code, Codex, and Pi in a GUI, with mobile
-  remote access.
- **Credentials and review**: host-side auth gateway injects credentials on
-  the wire; a temporary overlay stages writes for diff-and-accept review.
- **Closest overlap**: local microVM isolation, multi-provider launching, and
-  credential custody for security-minded individual developers.
- **Difference**: GUI desktop product on Apple Silicon rather than a
-  cross-platform declarative CLI/fleet layer. The July 2026 snapshot in the
-  original survey recorded a user request for per-run tool-call and network
-  audit logging; treat that as point-in-time rather than a permanent gap.
-
-## Credential gateway without isolation
-
-### OneCLI
-
-[OneCLI](https://onecli.sh/) is a framework-agnostic identity gateway rather
-than a sandbox. Its phantom-token design gives the agent a placeholder and
-substitutes the encrypted real credential at the network layer. It therefore
-matches bot-bottle closely on secret custody, and is more portable because it
-can sit in front of agents launched by anything, but it supplies no container
-or VM boundary, filesystem isolation, role manifest, or egress-content DLP.
-
-The positioning consequence from the earlier survey still holds: secret
-custody alone is not unique. bot-bottle's relevant combination is local
-isolation + default-deny egress + payload DLP + declarative roles + credential
-custody. OneCLI's managed tier also places custody with a third party, whereas
-bot-bottle keeps it within operator-controlled infrastructure. See
-[`agent-credential-proxy-landscape.md`](agent-credential-proxy-landscape.md)
-for the detailed build-versus-adopt analysis.
-
 ## Governance / pre-action authorization layers

 These two tools don't provide VM or filesystem isolation; they intercept
@@ -546,19 +360,19 @@ them.

 *Isolation/sandbox tools only. AGT and OAP are governance layers — see their per-project notes above.*

-| Axis | bot-bottle | endo-familiar | litterbox | agent-safehouse | matchlock | tilde.run | boxlite | microsandbox | smolmachines | E2B | Daytona | CubeSandbox | Cleanroom | container-use | Docker sbx | Anthropic srt |
-|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
-| Isolation | MicroVM per bottle default (Firecracker/KVM on Linux, Apple Container on macOS) + own egress DLP scanner; Docker legacy fallback, gVisor there if present | Object-capability (no OS isolation) | Podman + opt. Landlock | macOS `sandbox-exec` | MicroVM (Firecracker / Virt.fw) | Hosted container (unverified) | MicroVM (KVM / Hypervisor.fw) | MicroVM (libkrun) | MicroVM (libkrun / KVM) | Firecracker microVM | Container or Linux/Windows VM class | MicroVM (RustVMM / KVM) | MicroVM (Firecracker / Virt.fw) | Docker container + git worktree | MicroVM (proprietary) | OS-level (Seatbelt / bubblewrap / WFP) — no container |
-| Local vs hosted | Local | Local | Local (Linux) | Local (macOS) | Local | Hosted SaaS | Local | Local | Local | Hosted; self-host/BYOC available | Hosted; dedicated/custom regions | Self-hosted (server/cluster) | Self-hosted server | Local | Local | Local |
-| Open source | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | MIT | No | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | Production closed-source; legacy AGPL repo unmaintained | Apache 2.0 | Apache 2.0 | Apache 2.0 | Proprietary | Apache 2.0 (experimental) |
-| Agent target | Claude Code, Codex, Pi, and provider plugins | Generic (demo) | Generic | Multi-agent wrapper | Generic (+ Claude/OpenAI SDKs) | Claude focus | Generic | Claude + Cursor (MCP/Skills) | Generic (AGENTS.md) | LLM-agnostic platform builders | LLM-agnostic platform builders | E2B-compatible (platform builders) | CI / generic process | Claude Code, Cursor, Windsurf (MCP) | Claude Code, Codex, Gemini CLI, Copilot, Kiro | Claude Code (and any process) |
-| Network policy | Default-deny via own egress scanner + per-bottle allowlist + content DLP + gitleaks on git push | Capability model only | Limited | Not addressed | Default-deny + allowlist + secret-injecting proxy | Default-deny + logging | Per-VM net (unverified) | Not documented | Off by default + allowlist | Per-sandbox allow/deny rules and custom egress proxy; internet configurable | Per-sandbox CIDR/domain allowlist or block-all; tier policy; secret-injecting proxy | Default-deny allowlist + instant egress block + audit logs + per-sandbox tokens (eBPF) + credential vault | Default-deny + per-repo host allowlist (cleanroom.yaml) | Not addressed | Default-deny; Open / Balanced / Locked Down presets; live TUI network panel | Proxy-based allowlist/denylist (HTTP + SOCKS5); custom proxy supported |
-| Parallel agents | Yes (one bottle per agent) | n/a | Not addressed | One at a time | Multiple VMs | Yes (dashboard) | SDK-level | SDK-level | Architectural | Yes (platform service) | Yes (platform service) | Yes (2,000+/host claimed) | Yes (server model) | Yes (per-agent containers + worktrees) | Yes | Yes |
-| Long-running posture | Persistent by default (named, supervised) | n/a (demo) | Session (up while in use) | Per-invocation | Ephemeral VM per run | Per-run (versioned) | Ephemeral + snapshot/fork | Ephemeral / on-demand | Named persistent by default | Runtime tier limits + indefinite pause/resume | Persistent filesystem; VM pause/resume; configurable auto-stop | Ephemeral + auto pause/resume | Per-run + suspend/resume | Per-agent container (ephemeral) | Per-session; branch mode creates git worktree in .sbx/ | Per-invocation |
-| DX: run Claude yolo-style | One command → interactive yolo Claude (`start <agent>`, `--dangerously-skip-permissions` default) | n/a (lib demo) | Wizard + build, then run claude inside (Linux only) | One-command wrapper (`safehouse claude --dangerously-skip-permissions`) | CLI: run a cmd in a VM (not a Claude wrapper) | Hosted (`tilde exec`), not local-native | SDK code required (build the run yourself) | CLI/MCP: sandbox-as-a-tool for the agent, not a wrapper around it | SSH into a named machine, run claude there | SDK/CLI sandbox; wire the agent yourself | SDK/CLI sandbox; wire the agent yourself | Stand up a cluster + drive via E2B SDK | CI-oriented, not a Claude wrapper | MCP server: `claude mcp add container-use -- container-use stdio` | One command: `sbx` wraps claude with `--dangerously-skip-permissions` default | Library/wrapper, not a standalone CLI |
-| Config | YAML-in-Markdown manifests (bottles + agents) | Programmatic refs | CLI wizard | Profile files / shell fns | CLI / SDK | DSL + CLI + SDK | SDK | CLI / SDK / MCP | TOML Smolfile | SDK/API + templates | SDK/API/CLI + images/snapshots | E2B-compatible SDK | cleanroom.yaml in repo | None (no policy config) | Preset levels at launch | Programmatic per-invocation (allow/deny lists) |
-| Agent-tailored policy | Yes — bottle/agent split; declarative per-role egress + credentials; composable via `extends:` | Partial — capability model scopes per-agent, but no declarative role manifest | No | Partial — per-agent profile files (Seatbelt); no egress | No | Yes — per-agent DSL RBAC (allow/deny/approve per action/repo/agent) | No | No | No | No — per-sandbox SDK config | No — per-sandbox SDK config | No — per-sandbox SDK config, not role-scoped | Partial — per-repo cleanroom.yaml, not per-role | No | No — network presets only | No |
-| Maturity | Active July 2026 | Research (2022+) | Early (~66 ⭐) | Active (~1.8k ⭐) | Experimental (~574 ⭐) | Private preview | YC, ~4.7k ⭐ | YC, ~6k ⭐, beta | ~3.1k ⭐ | Established hosted platform, ~12.4k ⭐ | Production commercial; closed-source since June 2026 | Tencent, prod, ~10.4k ⭐ | Active (Buildkite product) | Early development | GA 2026 | Early research preview |
+| Axis | bot-bottle | endo-familiar | litterbox | agent-safehouse | matchlock | tilde.run | boxlite | microsandbox | smolmachines | CubeSandbox | Cleanroom | container-use | Docker sbx | Anthropic srt |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| Isolation | MicroVM per bottle default (Firecracker/KVM on Linux, Apple Container on macOS) + own egress DLP scanner; Docker legacy fallback, gVisor there if present | Object-capability (no OS isolation) | Podman + opt. Landlock | macOS `sandbox-exec` | MicroVM (Firecracker / Virt.fw) | Hosted container (unverified) | MicroVM (KVM / Hypervisor.fw) | MicroVM (libkrun) | MicroVM (libkrun / KVM) | MicroVM (RustVMM / KVM) | MicroVM (Firecracker / Virt.fw) | Docker container + git worktree | MicroVM (proprietary) | OS-level (Seatbelt / bubblewrap / WFP) — no container |
+| Local vs hosted | Local | Local | Local (Linux) | Local (macOS) | Local | Hosted SaaS | Local | Local | Local | Self-hosted (server/cluster) | Self-hosted server | Local | Local | Local |
+| Open source | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | MIT | No | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | Proprietary | Apache 2.0 (experimental) |
+| Agent target | Claude Code | Generic (demo) | Generic | Multi-agent wrapper | Generic (+ Claude/OpenAI SDKs) | Claude focus | Generic | Claude + Cursor (MCP/Skills) | Generic (AGENTS.md) | E2B-compatible (platform builders) | CI / generic process | Claude Code, Cursor, Windsurf (MCP) | Claude Code, Codex, Gemini CLI, Copilot, Kiro | Claude Code (and any process) |
+| Network policy | Default-deny via own egress scanner + per-bottle allowlist + content DLP + gitleaks on git push | Capability model only | Limited | Not addressed | Default-deny + allowlist + secret-injecting proxy | Default-deny + logging | Per-VM net (unverified) | Not documented | Off by default + allowlist | Default-deny allowlist + instant egress block + audit logs + per-sandbox tokens (eBPF) + credential vault | Default-deny + per-repo host allowlist (cleanroom.yaml) | Not addressed | Default-deny; Open / Balanced / Locked Down presets; live TUI network panel | Proxy-based allowlist/denylist (HTTP + SOCKS5); custom proxy supported |
+| Parallel agents | Yes (one bottle per agent) | n/a | Not addressed | One at a time | Multiple VMs | Yes (dashboard) | SDK-level | SDK-level | Architectural | Yes (2,000+/host claimed) | Yes (server model) | Yes (per-agent containers + worktrees) | Yes | Yes |
+| Long-running posture | Persistent by default (named, supervised) | n/a (demo) | Session (up while in use) | Per-invocation | Ephemeral VM per run | Per-run (versioned) | Ephemeral + snapshot/fork | Ephemeral / on-demand | Named persistent by default | Ephemeral + auto pause/resume | Per-run + suspend/resume | Per-agent container (ephemeral) | Per-session; branch mode creates git worktree in .sbx/ | Per-invocation |
+| DX: run Claude yolo-style | One command → interactive yolo Claude (`start <agent>`, `--dangerously-skip-permissions` default) | n/a (lib demo) | Wizard + build, then run claude inside (Linux only) | One-command wrapper (`safehouse claude --dangerously-skip-permissions`) | CLI: run a cmd in a VM (not a Claude wrapper) | Hosted (`tilde exec`), not local-native | SDK code required (build the run yourself) | CLI/MCP: sandbox-as-a-tool for the agent, not a wrapper around it | SSH into a named machine, run claude there | Stand up a cluster + drive via E2B SDK | CI-oriented, not a Claude wrapper | MCP server: `claude mcp add container-use -- container-use stdio` | One command: `sbx` wraps claude with `--dangerously-skip-permissions` default | Library/wrapper, not a standalone CLI |
+| Config | JSON manifest (bottles + agents) | Programmatic refs | CLI wizard | Profile files / shell fns | CLI / SDK | DSL + CLI + SDK | SDK | CLI / SDK / MCP | TOML Smolfile | E2B-compatible SDK | cleanroom.yaml in repo | None (no policy config) | Preset levels at launch | Programmatic per-invocation (allow/deny lists) |
+| Agent-tailored policy | Yes — bottle/agent split; declarative per-role egress + credentials; composable via `extends:` | Partial — capability model scopes per-agent, but no declarative role manifest | No | Partial — per-agent profile files (Seatbelt); no egress | No | Yes — per-agent DSL RBAC (allow/deny/approve per action/repo/agent) | No | No | No | No — per-sandbox SDK config, not role-scoped | Partial — per-repo cleanroom.yaml, not per-role | No | No — network presets only | No |
+| Maturity | Active July 2026 | Research (2022+) | Early (~66 ⭐) | Active (~1.4k ⭐) | Experimental (~574 ⭐) | Private preview | YC, ~4.7k ⭐ | YC, ~6k ⭐, beta | ~3.1k ⭐ | Tencent, prod, ~10.4k ⭐ | Active (Buildkite product) | Early development | GA 2026 | Early research preview |

 ## What's closest, what's different

@@ -571,9 +385,7 @@ keeping Docker only as a legacy fallback; agent-safehouse uses
 `sandbox-exec`; litterbox uses Podman + Landlock. matchlock and
 smolmachines are close on *both* the policy side (default-deny net,
 per-host allowlist) and — now that bot-bottle has moved off
-containers-by-default — the microVM isolation primitive. Note: Apple
-Container 1.0 stable shipped June 9 2026 (frozen CLI and APIs), which
-makes the macOS backend stable surface area rather than a moving target.
+containers-by-default — the microVM isolation primitive.

 **New closest on agent-tailored policy.** Two governance tools are the
 direct competitors on the "coarse-grained sandbox" axis. **tilde.run**
@@ -608,81 +420,47 @@ alternative.

 **Solving a different problem.** tilde.run is hosted SaaS for team /
 production agent pipelines with data-versioned rollback — explicitly
-opposite to bot-bottle's "infrastructure I control" goal. E2B and Daytona
-are hosted sandbox platforms, while boxlite, microsandbox, and CubeSandbox
-are infrastructure libraries/services aimed at platform builders embedding
-sandboxes into agent frameworks; they
+opposite to bot-bottle's "infrastructure I control" goal. boxlite,
+microsandbox, and CubeSandbox are infrastructure libraries/services aimed
+at platform builders embedding sandboxes into agent frameworks; they
 would be a *backend* bot-bottle could call, not a competitor to its
 manifest layer. endo-familiar is in a different paradigm entirely:
 capability passing rather than kernel boundaries.

 ## Borrowable ideas

-### Already shipped or otherwise addressed
-
+What bot-bottle already has that the survey suggested as
+differentiators:
 - Default-deny egress with a per-agent allowlist (own egress scanner).
 - DLP scanning of outbound traffic.
 - Bottle / agent split (manifest layer above the isolation primitive).
 - gVisor auto-detection on Linux.
- **In-flight secret injection** (suggested by matchlock) — **shipped.**
-  Real provider and git-host tokens are held outside the agent and injected
-  by the egress gateway on matching routes. The agent receives only proxy
-  URLs and, where a client requires a credential-shaped value, a placeholder;
-  `GITEA_TOKEN` and equivalent real tokens do not appear in the agent's
-  environment.
- **MicroVM backend** — **shipped.** MicroVMs are now the default:
-  Firecracker on KVM Linux and Apple Container on macOS. Docker is the legacy
-  fallback.
- **Per-use SSH key confirmation** (suggested by litterbox) — **addressed by
-  stronger credential custody instead.** The agent does not hold the upstream
-  git SSH key or an SSH-agent socket: git-gate holds the credential and gates
-  git operations. A confirmation wrapper inside the agent would therefore
-  protect a credential that is no longer there. Operator approval at the gate
-  remains the appropriate control point for any future per-use confirmation.

-### Still worth considering
+Ideas worth considering, without abandoning the Python-stdlib-first /
+local, single-operator stance:

- **Live network activity in the supervisor TUI** (from Docker sbx): show
-  allowed and blocked connections and let the operator propose policy changes
-  from the existing supervision surface.
- **Tamper-evident audit records** (from OAP): sign and hash-chain egress and
-  supervision decisions for compliance-sensitive deployments.
- **Behaviour-informed policy downgrade** (from Microsoft AGT): use repeated
-  DLP alerts or supervision holds as a signal to narrow policy or request
-  closer review. This needs a carefully specified trust model before it can be
-  more than a heuristic.
+1. **Per-use SSH key confirmation** (from litterbox). Even with
+   KnownHostKey pinning and the egress DLP scanner, a wrapper SSH agent that
+   prompts on each key use (e.g. via `osascript` / `notify-send`) would
+   catch an agent doing something off-policy with a key it legitimately
+   holds. Pure-stdlib, no new deps.
+2. **In-flight secret injection** (from matchlock). The egress scanner
+   already does allowlisting and DLP; teaching it to *inject* tokens at
+   proxy time so e.g. `GITEA_TOKEN` never appears in the container's
+   env would close the "agent reads its own env and exfiltrates" path.
+   Fits the existing egress-proxy architecture.
+3. **MicroVM backend** — ~~on the radar~~ **shipped since this survey.**
+   microVMs are now bot-bottle's default (Firecracker on KVM Linux, Apple
+   Container on macOS); Docker is the legacy fallback. The libkrun / Apple
+   Virtualization.framework ergonomics that microsandbox, smolmachines,
+   and matchlock demonstrated turned out to be enough to make it the
+   default rather than an opt-in.

 Not worth borrowing: the SDK-first programmatic API style of boxlite /
 microsandbox (cuts against the declarative-manifest stance), and the
 hosted-SaaS dashboard model of tilde.run (cuts against the
 "infrastructure I control" goal).

-## Publishing and positioning verdict
-
-Publishing remains worthwhile, but the defensible claim is the combination,
-not any single primitive. Credential custody is matched by OneCLI, matchlock,
-Daytona, Docker sbx, and CubeSandbox; local one-command isolation is matched by
-agent-safehouse and Docker sbx; hosted microVM execution is a crowded platform
-category.
-
-bot-bottle remains unusual in combining:
-
- local, operator-controlled execution with persistent named bottles;
- one declarative role layer across Claude Code, Codex, Pi, and provider
-  plugins;
- composable agent/bottle manifests, skills, and system prompts;
- Firecracker/Apple Container isolation with a Docker fallback;
- default-deny per-role egress, payload DLP, and git-push secret scanning;
- credentials injected outside the agent process; and
- supervision and audit state suited to long-running parallel agents.
-
-The practical wedge is “as easy as native yolo, with declarative role policy
-and self-hosted custody,” including scoped access to private LAN/Tailnet
-services that cloud-first runtimes cannot provide without additional network
-plumbing. The main competitive risks are a local wrapper such as claudebox or
-Docker sbx growing a role-manifest layer, and GUI products such as SuperHQ
-adding equivalent policy and audit depth.
-
 ## Caveats

 - Star counts and last-commit dates are point-in-time snapshots.
@@ -699,8 +477,7 @@ adding equivalent policy and audit depth.

 CubeSandbox (Tencent Cloud, Apache 2.0, ~10.4k stars, HN launch
 [#47863430](https://news.ycombinator.com/item?id=47863430)) is the first
-open-source, self-hostable project in this survey to combine, in one stack,
-the main primitives
+project in this survey to combine, in one open-source stack, everything
 bot-bottle treated as its differentiator:

 - **Egress custody (connection level)** — default-deny domain allowlist
@@ -768,7 +545,7 @@ instead of per-action prompts. On this axis the field splits cleanly:
  network egress; bot-bottle adds VM-grade isolation, egress DLP, and
  persistent/parallel bottles across macOS + Linux.
 - **Libraries / services** (you build the run yourself): boxlite,
-  microsandbox, CubeSandbox, E2B, Daytona. These hand you an SDK or a cluster and
+  microsandbox, CubeSandbox, E2B. These hand you an SDK or a cluster and
  expect you to wire the agent in — powerful for platform builders,
  heavyweight for "just run Claude on my laptop." microsandbox's MCP/Skills
  angle is *sandbox-as-a-tool the agent calls*, which is the inverse of
@@ -776,11 +553,10 @@ instead of per-action prompts. On this axis the field splits cleanly:
 - **In between:** litterbox (wizard + build, Linux only), smolmachines
  (SSH into a named machine), matchlock (run a command in a VM).

-So DX is a genuine bot-bottle differentiator. agent-safehouse matches the
-one-command wrapper with weaker isolation and no egress story; Docker sbx now
-matches it at microVM strength but remains proprietary and preset-based. "As
-easy as native yolo, with declarative role policy" is the narrower defensible
-one-liner.
+So DX is a genuine bot-bottle differentiator, and the only project that
+matches it (agent-safehouse) does so with materially weaker isolation and
+no egress story. "As easy as native yolo, but actually sandboxed" is a
+defensible one-liner.

 Why it still doesn't collide head-on:

@@ -788,8 +564,7 @@ Why it still doesn't collide head-on:
   builders* (drop-in E2B replacement, SDK-driven, 2,000 sandboxes on a
   box). bot-bottle is a *single-operator, declarative-manifest tool for
   the infrastructure I run*. Different buyer, different ergonomics — no
-   declarative role manifest, no bottle/agent split, no "one command on my
-   laptop."
+   JSON manifest, no bottle/agent split, no "one command on my laptop."
 2. **Backend, not competitor.** Like boxlite/microsandbox, CubeSandbox is
   something bot-bottle could sit *on top of* — a `"runtime": "microvm"`
   or `"runtime": "cubesandbox"` backend under the manifest layer — while
@@ -800,8 +575,7 @@ Why it matters anyway:

 - The "nobody else bundles connection-level egress allowlist + audit +
  in-flight credential custody" line is **no longer true for the
-  primitive** — CubeSandbox ships the open-source/self-hosted combination,
-  and Daytona ships a proprietary firewall + credential-substitution variant.
+  primitive** — a well-funded, 10k-star open-source project now ships it.
  But **content DLP on authorized channels is still not matched** (see
  above), and neither is the *layer above* the primitive (declarative
  manifest, cross-vendor orchestration, operator UX, the
@@ -812,8 +586,8 @@ Why it matters anyway:
  that in mind.
 - Worth a closer look at **how** CubeSandbox does credential injection
  and per-sandbox egress tokens (eBPF virtual switch vs. bot-bottle's
-  mitmproxy egress proxy) when hardening bot-bottle's now-shipped
-  credential-custody implementation.
+  mitmproxy egress proxy) before the next iteration of bot-bottle's
+  in-flight-secret feature — see borrowable idea #2 above.

 ## Addendum 2026-07-18 (second pass) — agent-tailored policy landscape

@@ -852,7 +626,7 @@ whether a permitted action is consistent with the agent's actual task.
 See `hn-agent-safety-discourse-july-2026.md` for the blast-radius
 analysis.

-**Open ideas from new tools (also summarized above):**
+**Borrowable from new tools:**

 - **Microsoft AGT's trust-score decay** — privilege that reflects
  observed behaviour rather than static provisioning. Applied to
@@ -43,18 +43,6 @@ surveyed what developers were actually deploying: "containers or YOLO"
 dominated. The honest community mood was that most teams hadn't solved
 this and were shipping anyway.

-The March 12 launch of **Agent Safehouse**
-([#47301085](https://news.ycombinator.com/item?id=47301085), 823 points)
-crystallised the community framing: a zero-dep `sandbox-exec` wrapper for
-macOS that attracted the top comment *"I honestly think that sandboxing is
-currently THE major challenge that needs to be solved for the tech to fully
-realise its potential."* The creator's own framing — "no dependencies, no
-daemons, no subscription; the simplicity is the feature" — and Simon
-Willison's observation that evaluating whether a sandboxing tool works as
-intended is itself hard, both prefigure the June–July shift in tone. See
-[`agent-sandbox-landscape.md`](agent-sandbox-landscape.md) for a full
-per-project breakdown.
-
 ## The June–July attack cascade

 Six attack patterns broke in quick succession. Together they form the
@@ -0,0 +1,182 @@
+# Landscape: containerized AI coding agent tools
+
+Research into whether bot-bottle is redundant with existing projects, and
+whether it's worth publishing.
+
+## Summary
+
+The "AI coding agents in isolated sandboxes" space is active but not saturated.
+bot-bottle occupies a distinct position: no surveyed project combines all five
+of its defining features. Publishing is likely worthwhile, with the main risk
+being claudebox expanding to absorb the same niche.
+
+**Updated 2026-07-09:** bot-bottle now supports three isolation backends
+(Docker, Apple `container`, smolmachines/libkrun microVMs) and three built-in
+agent providers (Claude Code, OpenAI Codex, Pi) with an open plugin system for
+arbitrary providers. This meaningfully strengthens the differentiation against
+all surveyed competitors.
+
+## Closest competitor: claudebox
+
+[RchGrav/claudebox](https://github.com/RchGrav/claudebox) is the most
+feature-complete analog. It runs Claude Code in Docker with per-project
+isolated images, 15+ pre-configured dev-language profiles, and per-project
+network firewall allowlists. Actively maintained with multiple forks.
+
+What it lacks: manifest-driven named agents, per-agent env resolution modes
+(prompt / host-forward / literal), skill directory injection, per-agent system
+prompts, SSH-agent forwarding without copying private keys, home+project
+manifest merge.
+
+## Other surveyed projects
+
+- **textcortex/claude-code-sandbox → spritz** — evolved toward
+  Kubernetes-native multi-agent infra; not stdlib-first or local-Docker.
+  Original sandbox repo is archived.
+- **trailofbits/claude-code-devcontainer** — devcontainer config for security
+  audits; not a general agent launcher.
+- **Several small solo repos** (arezi/claude-sandbox, nkrefman/claude-sandbox,
+  VishalJ99/claude-docker) — lightweight Docker wrappers with no multi-agent
+  config layer.
+- **Docker's official sandbox templates** — launch-and-run Dockerfiles plus an
+  npm-based runtime; not a manifest-driven fleet manager.
+
+## Adjacent (different model)
+
+- **dagger/container-use** (mid-2025) — exposes an MCP server so the *agent*
+  spins up its own containers with Git worktrees. Inverted model vs. bot-bottle
+  (agent controls container rather than being launched into one by a manifest).
+  Still marked early-development.
+- **E2B, Northflank, Cloudflare Sandbox SDK** — cloud-hosted SaaS sandbox
+  runtimes; fundamentally different architecture.
+- **superhq.ai / SuperHQ** (v0.4.4, April 2026) — macOS desktop app (Rust/GPUI)
+  that runs Claude Code, Codex, and Pi inside microVMs via Apple's
+  Virtualization.framework (their own shuru-sdk / libkrun). Auth gateway
+  injects API keys on the wire so the sandbox never sees them; tmpfs overlay
+  stages agent writes for diff-and-accept review; mobile remote access via
+  remote.superhq.ai. Early alpha, free on launch, Apple Silicon only.
+
+  Overlap: both projects cover agent isolation, credential proxying, and
+  multi-provider support (Claude Code / Codex / Pi). Differences: SuperHQ is a
+  GUI desktop app with no manifest layer; bot-bottle is a CLI fleet manager with
+  named agents, skills injection, per-agent system prompts, and cross-platform
+  backends (Docker, Apple `container`, smolmachines). SuperHQ's microVM
+  isolation story is now partially matched by bot-bottle's `macos_container` and
+  smolmachines backends. Worth watching — it targets the same security-minded
+  power-user audience and moves fast.
+
+  **Known gap in SuperHQ (user-requested, as of 2026-07-09):** A named user
+  (Brian Cheong, Founder, Dunialabs.io) explicitly called out the absence of
+  per-run audit logging: tool calls and network egress. Bot-bottle covers both:
+  network egress is logged by pipelock/mitmproxy, and per-run op-log/audit state
+  is persisted to SQLite.
+
+- **OneCLI** ([onecli.sh](https://onecli.sh/)) — YC-backed, GA, open-source
+  (Apache-2.0, Rust) "identity gateway for AI agents": a credential/secret
+  broker that holds API keys and OAuth tokens out of the agent's reach and
+  injects them at the network layer (phantom-token — the agent sees a
+  placeholder, the gateway swaps in the real, AES-256-GCM-encrypted credential
+  at request time). Framework-agnostic and drop-in for any HTTP-calling agent,
+  50+ app integrations, plus a hosted cloud tier with a per-agent dashboard and
+  audit logs. Full technical breakdown in
+  [`agent-credential-proxy-landscape.md`](agent-credential-proxy-landscape.md).
+
+  **How close a competitor:** near-exact on the *single axis of agent secret
+  custody* — the exact thing bot-bottle sells as "the agent never sees real
+  credentials, even via `printenv`." OneCLI does that one job well, is mature
+  and funded, and is *more portable* (it sits in front of anything; bot-bottle
+  only helps agents launched through bot-bottle). Takeaway: bot-bottle should
+  stop treating secret custody as a *unique* differentiator. But OneCLI is
+  **not** a competitor to bot-bottle's actual product — it does no agent
+  sandboxing (containers/microVMs), no fleet/manifest layer, no named agents /
+  skills / per-agent system prompts, no multi-provider launching, no egress
+  firewall.
+
+  **Our edge:** (1) *Isolation is the product, not a proxy.* OneCLI keeps the
+  key out of reach at the network layer, but the agent itself still runs
+  unsandboxed — a hijacked agent behind OneCLI has full run of its host and can
+  exfil captured data through any allowed host. bot-bottle runs the agent inside
+  a kernel/VM-enforced sandbox, injects credentials across that same
+  out-of-process boundary, *and* clamps egress with pipelock — defense in depth
+  vs. a single network layer. (2) *Fleet + manifest model* with named agents,
+  skills, per-agent system prompts, multi-provider and multi-backend — OneCLI
+  has no equivalent. (3) *Trust posture:* OneCLI's managed tier reintroduces a
+  third-party credential custodian, whereas bot-bottle's OSS-runtime +
+  paid-control-plane split keeps custody inside the operator's own boundary —
+  the stronger story for the security-minded self-hoster. (4) *Runs inside your
+  network boundary — local/internal reach.* Because bot-bottle executes the
+  agent on your own host (homelab, corporate LAN, a Tailnet) and egress is a
+  manifest field, giving an agent *scoped* access to **internal** resources — a
+  private Gitea, a LAN database, a Tailscale node — is just another egress-route
+  line, not a networking project (the same move an operator already makes to
+  reach their Tailscale services). OneCLI's OSS core can self-host too, but it's
+  a credential *broker* for outbound API calls, not an agent runtime, and its
+  managed tier + 50+ integrations are oriented at public SaaS — it doesn't put
+  the agent behind your firewall for you. This is a reach advantage, distinct
+  from the isolation ones above, and it's a wedge cloud-first agent products
+  (Devin, Copilot Workspace, OneCLI Cloud) structurally can't match. **Tactical
+  read:**
+  adopt OneCLI's OSS core for the credential slice if building is undesirable
+  (it's mature now); don't build atop its managed tier (competitor, not
+  dependency); re-position bot-bottle on isolation + fleet + self-hosted custody
+  rather than "we hide your secrets."
+
+## What no found project does
+
+None combine:
+1. Named-agent manifest with per-agent env resolution (prompt / host-forward / literal), supporting multiple providers (Claude Code, Codex, Pi, arbitrary plugins)
+2. Skills directory injection
+3. Per-agent system prompts
+4. SSH-agent key forwarding without copying private keys into the container
+5. Home + project manifest merge
+6. Pluggable isolation backends: Docker (Linux/macOS), Apple `container` (macOS microVMs), smolmachines/libkrun microVMs
+7. Per-run audit log: network egress via pipelock/mitmproxy + op-log persisted to SQLite
+
+**In-flight directions (not yet shipped):**
+
+- **Forge-native dispatch (issue #317):** Gitea webhook → orchestrator spins up a bottle
+  with the issue body as prompt → agent works → bottle freezes awaiting review comment →
+  rehydrates on comment → tears down on PR close. The issue-to-PR lifecycle concept is not
+  novel (Devin, Copilot Workspace, SWE-agent all do this as cloud services); what's
+  distinct is doing it self-hosted, manifest-driven, inside bot-bottle's isolation
+  primitives.
+- **Paid web control plane (issue #327):** Browser-based multi-host agent launch and
+  monitoring; account-scoped bottle and agent definitions; secret custody (encrypted at
+  rest, injected into the sidecar at launch, never exposed to the agent or returned by any
+  read API). Monetization model: OSS runtime free, control plane paid — a standard split
+  (HashiCorp, Grafana) applied to a self-hosted agent sandbox. The principled secret
+  custody model (agent never sees real credentials, even via printenv) is more rigorous
+  than most surveyed tools but not unprecedented.
+
+## Publishing verdict
+
+Worth publishing. Differentiators that matter to the target audience (power
+users running parallel AI coding agent sessions with distinct personas/tooling):
+
+- The Python-stdlib-first, low-dependency design — competitors are npm-based,
+  Rust/GUI, or Kubernetes-native.
+- Named agents with distinct skills and system prompts, not just language profiles.
+- Multi-backend isolation: Docker, Apple `container` microVMs, and
+  smolmachines/libkrun — single manifest works across all three.
+- Multi-provider: Claude Code, Codex, Pi, plus an open plugin system for
+  arbitrary providers.
+- SSH forwarding without key copying.
+- Per-run audit log (tool calls + network egress) — an explicitly requested gap
+  in SuperHQ as of 2026-07-09.
+- Forge-native dispatch and a paid control plane (in flight) bring bot-bottle
+  into the same product category as cloud services like Devin and Copilot
+  Workspace — but self-hosted, with stronger isolation guarantees and a
+  manifest-driven fleet model those services don't have.
+
+Main risk: claudebox adds manifest/agent config; SuperHQ is moving fast on the
+GUI / microVM side. The space is moving fast enough that publishing sooner is
+better if establishing prior art matters.
+
+Discovery will be slow without active promotion; an Anthropic Discord post or
+HN "Show HN" would do most of the work.
+
+## Caveats
+
+- GitHub search cannot surface private or very new repos comprehensively.
+- Counts (stars, forks) were not confirmed for every project.
+- Initial research conducted 2026-05-07; SuperHQ entry added 2026-07-09; the space moves fast.
@@ -1,6 +1,6 @@
 # smolmachines as a VM backend for bot-bottle

-> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/agent-sandbox-landscape.md`.
+> **Superseded (2026-07-11).** The smolmachines backend was removed — Linux now uses the Firecracker backend, macOS uses macos-container. Kept as a historical record; see the removal commit `c07ebca` and `docs/research/landscape-containerized-claude.md`.

 Evaluation of whether [smolmachines](https://smolmachines.com/) would
 simplify the macOS agent-VM-isolation work spelled out in
@@ -1,6 +1,6 @@
 [build-system]
 requires = ["setuptools>=68"]
-build-backend = "setuptools.build_meta"
+build-backend = "setuptools.backends.legacy:build"

 [project]
 name = "bot-bottle"
@@ -1,19 +1,15 @@
 #!/usr/bin/env bash
 # Combined unit + integration coverage (see docs/decisions/0004-coverage-policy.md).
 #
-# Two modes:
+# Runs the unit suite, then appends the integration suite (which skips
+# cleanly when Docker / the backend CLIs are unavailable), and prints one
+# combined report. The integration suite is what scores the subprocess /
+# backend orchestration modules, so the number here is the policy's
+# yardstick — not the unit-only badge.
 #
-#   scripts/coverage.sh [critical]
-#     Run mode (default, for local dev): executes the unit suite then the
-#     integration suite under coverage and prints a combined report.
-#
-#   scripts/coverage.sh aggregate [critical]
-#     Aggregate mode (used by CI): combines pre-existing .coverage.* files
-#     produced by individual test jobs and prints a combined report. No tests
-#     are re-executed; no KVM or Docker dependency.
-#
-# Pass "critical" as the last argument in either mode to also report just the
-# critical modules (ADR 0004 target: 90%).
+# Usage:
+#   scripts/coverage.sh            # combined report
+#   scripts/coverage.sh critical   # also report just the critical modules
 set -euo pipefail

 cd "$(dirname "$0")/.."
@@ -25,22 +21,6 @@ PY="${PYTHON:-python3}"
 # README "core coverage" badge can't drift; comma-join it for --include.
 CRITICAL=$(grep -vE '^[[:space:]]*(#|$)' scripts/critical-modules.txt | paste -sd, -)

-if [ "${1:-}" = "aggregate" ]; then
-    # Aggregate mode: combine .coverage.* artifacts already in the workspace.
-    echo "== combining coverage artifacts ==" >&2
-    "$PY" -m coverage combine
-
-    echo "== combined report ==" >&2
-    "$PY" -m coverage report -m
-
-    if [ "${2:-}" = "critical" ]; then
-        echo "== critical modules (ADR 0004 target: 90%) ==" >&2
-        "$PY" -m coverage report --include="$CRITICAL"
-    fi
-    exit 0
-fi
-
-# Run mode (default): execute both suites under coverage in this process.
 rm -f .coverage

 echo "== unit ==" >&2
@@ -48,7 +28,6 @@ echo "== unit ==" >&2

 echo "== integration (firecracker; skips docker tests) ==" >&2
 BOT_BOTTLE_BACKEND=firecracker SKIP_DOCKER_TESTS=1 \
-    BOT_BOTTLE_INFRA_ARTIFACT_DIR="${BOT_BOTTLE_CI_INFRA_ARTIFACT_DIR:-}" \
    "$PY" -m coverage run --append -m unittest discover -t . -s tests/integration

 echo "== combined report ==" >&2
@@ -1,23 +0,0 @@
-"""Resolved paths to system binaries used by subprocess-based tests.
-
-NixOS and other non-FHS hosts don't populate ``/bin`` (there is no
-``/bin/sleep``), so tests that spawn real short-lived helper processes
-must resolve the binary from ``PATH`` rather than hardcoding an FHS path.
-Import the resolved constant (e.g. ``SLEEP``) instead of writing
-``/bin/sleep`` inline.
-"""
-
-from __future__ import annotations
-
-import shutil
-
-
-def resolve(name: str, fallback: str) -> str:
-    """Absolute path to ``name`` from ``PATH``; ``fallback`` on FHS hosts
-    where the binary isn't on ``PATH`` but lives at a known ``/bin`` path."""
-    return shutil.which(name) or fallback
-
-
-# Real ``sleep`` binary. ``/bin/sleep`` is absent on NixOS; resolve from
-# PATH so subprocess tests run instead of erroring with FileNotFoundError.
-SLEEP = resolve("sleep", "/bin/sleep")
@@ -30,16 +30,3 @@ def docker_available() -> bool:

 def skip_unless_docker(reason: str = "docker unreachable"):
    return unittest.skipUnless(docker_available(), reason)
-
-
-def skip_unless_docker_or_firecracker(
-    reason: str = "neither Docker nor Firecracker selected",
-):
-    """Skip a backend-agnostic test unless one supported backend can run.
-
-    Firecracker does not require the host Docker daemon. The KVM coverage job
-    deliberately sets ``SKIP_DOCKER_TESTS`` to exclude Docker-only integration
-    classes while still exercising this path.
-    """
-    firecracker_selected = os.environ.get("BOT_BOTTLE_BACKEND") == "firecracker"
-    return unittest.skipUnless(firecracker_selected or docker_available(), reason)
@@ -86,12 +86,13 @@ class TestGatewayImage(unittest.TestCase):
        self.assertIn("Mitmproxy", out)

    def test_python_imports_supervise_module(self):
-        # The supervise daemon is installed as part of the bot_bottle
-        # package (5ad3449), not as flat sibling modules under /app.
-        # Probe that the package imports resolve inside the image.
+        # The bundle's supervise daemon imports `supervise` as a
+        # same-directory sibling of `supervise_server`. Probe the
+        # import resolves with `python3 -c` from /app (the
+        # Dockerfile's WORKDIR).
        rc, out = self._run_in_image(
            "python3", "-c",
-            "from bot_bottle import supervise, supervise_server; print('ok')",
+            "import supervise; import supervise_server; print('ok')",
        )
        self.assertEqual(0, rc, msg=out)
        self.assertIn("ok", out)
@@ -31,7 +31,7 @@ from pathlib import Path
 from bot_bottle.backend import BottleSpec, get_bottle_backend
 from bot_bottle.bottle_state import cleanup_state
 from bot_bottle.manifest import ManifestIndex
-from tests._docker import skip_unless_docker_or_firecracker
+from tests._docker import skip_unless_docker


 # Secrets planted in the bottle env as literals (agents substitute via
@@ -67,7 +67,7 @@ _DUMMY_HOST_KEY = (
 )


-@skip_unless_docker_or_firecracker()
+@skip_unless_docker()
@unittest.skipIf(
    os.environ.get("GITEA_ACTIONS") == "true"
    and os.environ.get("BOT_BOTTLE_BACKEND") != "firecracker",
@@ -91,9 +91,11 @@ class TestSandboxEscape(unittest.TestCase):

    @classmethod
    def setUpClass(cls) -> None:
-        # Pin Docker when BOT_BOTTLE_BACKEND is unset to preserve the
-        # Docker-backed CI path. Firecracker uses its persistent infra VM for
-        # the shared gateway and therefore does not require host Docker.
+        # Docker is always required (the agent + companion containers run under it,
+        # and VM backends still use it for the gateway); the
+        # class-level @skip_unless_docker already covers that. Pin
+        # Docker when BOT_BOTTLE_BACKEND is unset to preserve the
+        # Docker-backed CI path.
        cls._backend_name = os.environ.get("BOT_BOTTLE_BACKEND", "docker")

        # Throwaway static key for the git-gate fixture. It need not
@@ -57,16 +57,14 @@ class TestGetBottleBackend(unittest.TestCase):
                return self._available

        # No macOS container and the host can't run firecracker (no
-        # KVM / not Linux) → docker fallback with a prompt. Simulate
-        # the user picking "d" (use docker anyway).
+        # KVM / not Linux) → docker is the last resort.
        with patch.dict(os.environ, {}, clear=True), \
             patch.object(backend_mod.FirecrackerBottleBackend,
                          "is_host_capable", classmethod(lambda cls: False)), \
             patch.object(backend_mod, "_backends", {
                 "macos-container": _FakeBackend("macos-container", False),
                 "docker": _FakeBackend("docker", True),
-             }), \
-             patch.object(backend_mod, "read_tty_line", return_value="d"):
+             }):
            b = get_bottle_backend()
        self.assertEqual("docker", b.name)

@@ -98,145 +96,6 @@ class TestGetBottleBackend(unittest.TestCase):
            with self.assertRaises(SystemExit):
                get_bottle_backend("nonexistent")

-    def test_no_backend_available_dies(self):
-        # No VM and no docker → print install instructions and die.
-        class _FakeBackend:
-            def __init__(self, name: str, available: bool) -> None:
-                self.name = name
-                self._available = available
-
-            def is_available(self) -> bool:
-                return self._available
-
-        with patch.dict(os.environ, {}, clear=True), \
-             patch.object(backend_mod.FirecrackerBottleBackend,
-                          "is_host_capable", classmethod(lambda cls: False)), \
-             patch.object(backend_mod, "_backends", {
-                 "macos-container": _FakeBackend("macos-container", False),
-                 "docker": _FakeBackend("docker", False),
-             }), \
-             patch.object(backend_mod, "die", side_effect=SystemExit("die")):
-            with self.assertRaises(SystemExit):
-                get_bottle_backend()
-
-    def test_docker_fallback_user_quits(self):
-        # VM unavailable, docker available, user picks "q" → die.
-        class _FakeBackend:
-            def __init__(self, name: str, available: bool) -> None:
-                self.name = name
-                self._available = available
-
-            def is_available(self) -> bool:
-                return self._available
-
-        with patch.dict(os.environ, {}, clear=True), \
-             patch.object(backend_mod.FirecrackerBottleBackend,
-                          "is_host_capable", classmethod(lambda cls: False)), \
-             patch.object(backend_mod, "_backends", {
-                 "macos-container": _FakeBackend("macos-container", False),
-                 "docker": _FakeBackend("docker", True),
-             }), \
-             patch.object(backend_mod, "read_tty_line", return_value="q"), \
-             patch.object(backend_mod, "die", side_effect=SystemExit("die")):
-            with self.assertRaises(SystemExit):
-                get_bottle_backend()
-
-
-    def test_docker_fallback_non_interactive_dies(self):
-        # prompt=False: headless/CI contexts must not block on a TTY read.
-        class _FakeBackend:
-            def __init__(self, name: str, available: bool) -> None:
-                self.name = name
-                self._available = available
-
-            def is_available(self) -> bool:
-                return self._available
-
-        with patch.dict(os.environ, {}, clear=True), \
-             patch.object(backend_mod.FirecrackerBottleBackend,
-                          "is_host_capable", classmethod(lambda cls: False)), \
-             patch.object(backend_mod, "_backends", {
-                 "macos-container": _FakeBackend("macos-container", False),
-                 "docker": _FakeBackend("docker", True),
-             }), \
-             patch.object(backend_mod, "die", side_effect=SystemExit("die")):
-            with self.assertRaises(SystemExit):
-                get_bottle_backend(prompt=False)
-
-    def test_docker_fallback_user_picks_install(self):
-        # User picks [i] → print install instructions then die.
-        class _FakeBackend:
-            def __init__(self, name: str, available: bool) -> None:
-                self.name = name
-                self._available = available
-
-            def is_available(self) -> bool:
-                return self._available
-
-        with patch.dict(os.environ, {}, clear=True), \
-             patch.object(backend_mod.FirecrackerBottleBackend,
-                          "is_host_capable", classmethod(lambda cls: False)), \
-             patch.object(backend_mod, "_backends", {
-                 "macos-container": _FakeBackend("macos-container", False),
-                 "docker": _FakeBackend("docker", True),
-             }), \
-             patch.object(backend_mod, "read_tty_line", return_value="i"), \
-             patch.object(backend_mod, "_print_vm_install_instructions") as mock_inst, \
-             patch.object(backend_mod, "die", side_effect=SystemExit("die")):
-            with self.assertRaises(SystemExit):
-                get_bottle_backend()
-        mock_inst.assert_called_once()
-
-
-class TestReadTtyLine(unittest.TestCase):
-    """Unit tests for the shared read_tty_line helper in bot_bottle.util."""
-
-    def test_reads_from_dev_tty(self):
-        from unittest.mock import mock_open
-        from bot_bottle.util import read_tty_line
-
-        m = mock_open(read_data="hello\n")
-        with patch("builtins.open", m):
-            result = read_tty_line()
-        self.assertEqual("hello", result)
-        m.assert_called_once_with("/dev/tty", "r", encoding="utf-8")
-
-    def test_falls_back_to_stdin_on_oserror(self):
-        import io
-        from bot_bottle.util import read_tty_line
-        import sys as _sys
-
-        with patch("builtins.open", side_effect=OSError("no tty")), \
-             patch.object(_sys, "stdin", io.StringIO("world\n")):
-            result = read_tty_line()
-        self.assertEqual("world", result)
-
-
-class TestPrintVmInstallInstructions(unittest.TestCase):
-    """Unit tests for _print_vm_install_instructions platform branches."""
-
-    def test_linux_prints_firecracker_instructions(self):
-        from bot_bottle.backend import _print_vm_install_instructions
-
-        with patch.object(backend_mod, "_platform_vm_suggestion",
-                          return_value="firecracker"), \
-             patch.object(backend_mod, "info") as mock_info:
-            _print_vm_install_instructions()
-
-        messages = [str(c[0][0]) for c in mock_info.call_args_list]
-        self.assertTrue(any("Firecracker" in m for m in messages))
-
-    def test_macos_prints_apple_container_instructions(self):
-        from bot_bottle.backend import _print_vm_install_instructions
-
-        with patch.object(backend_mod, "_platform_vm_suggestion",
-                          return_value="macos-container"), \
-             patch.object(backend_mod, "info") as mock_info:
-            _print_vm_install_instructions()
-
-        messages = [str(c[0][0]) for c in mock_info.call_args_list]
-        self.assertTrue(any("Apple Container" in m for m in messages))
-

 class TestKnownBackendNames(unittest.TestCase):
    def test_returns_backends_sorted(self):
@@ -215,18 +215,6 @@ class TestDockerSetupStatus(unittest.TestCase):
        with patch.object(dk.shutil, "which", return_value=None):
            self.assertFalse(dk._daemon_reachable())

-    def test_daemon_reachable_true_when_daemon_responds(self):
-        with patch.object(dk.shutil, "which", return_value="/usr/bin/docker"), \
-             patch.object(dk.subprocess, "run",
-                          return_value=subprocess.CompletedProcess([], 0)):
-            self.assertTrue(dk._daemon_reachable())
-
-    def test_daemon_reachable_false_on_timeout(self):
-        with patch.object(dk.shutil, "which", return_value="/usr/bin/docker"), \
-             patch.object(dk.subprocess, "run",
-                          side_effect=subprocess.TimeoutExpired(["docker", "info"], 5)):
-            self.assertFalse(dk._daemon_reachable())
-
    def test_status_reports_missing_docker(self):
        with patch.object(dk.shutil, "which", return_value=None):
            rc, out = _cap(dk.status)
@@ -1,10 +1,8 @@
-"""Unit: `cli.py cleanup` walks every available backend.
+"""Unit: `cli.py cleanup` walks every backend (issue follow-up).

-Asserts cmd_cleanup queries each available backend's `prepare_cleanup`,
-combines the y/N output, and runs each backend's `cleanup` when the
-operator confirms. Unavailable backends (e.g. macos-container on Linux)
-are skipped so that `cleanup` never errors on a platform where a backend
-is not installed. Mocks the backends and stdin."""
+Asserts cmd_cleanup queries each backend's `prepare_cleanup`,
+combines the y/N output, and runs each backend's `cleanup` when
+the operator confirms.  Mocks the backends and stdin."""

 from __future__ import annotations

@@ -23,7 +21,7 @@ def _make_backend(empty: bool = True):


 class TestCmdCleanup(unittest.TestCase):
-    def test_iterates_every_available_backend(self):
+    def test_iterates_every_backend(self):
        docker, docker_plan = _make_backend(empty=False)
        fc, fc_plan = _make_backend(empty=False)
        backends_by_name = {"docker": docker, "firecracker": fc}
@@ -34,8 +32,6 @@ class TestCmdCleanup(unittest.TestCase):
        ), patch.object(
            cmd, "get_bottle_backend",
            side_effect=lambda name: backends_by_name[name],  # type: ignore
-        ), patch.object(
-            cmd, "has_backend", return_value=True,
        ), patch.object(
            cmd, "_prompt_yes", return_value=True,
        ):
@@ -46,32 +42,6 @@ class TestCmdCleanup(unittest.TestCase):
        docker.cleanup.assert_called_once_with(docker_plan)
        fc.cleanup.assert_called_once_with(fc_plan)

-    def test_skips_unavailable_backends(self):
-        # macos-container is not available on Linux — must be silently skipped.
-        docker, docker_plan = _make_backend(empty=False)
-        macos = MagicMock()
-        backends_by_name = {"docker": docker}
-
-        def _has(name: str) -> bool:
-            return name == "docker"
-
-        with patch.object(
-            cmd, "known_backend_names",
-            return_value=("docker", "macos-container"),
-        ), patch.object(
-            cmd, "get_bottle_backend",
-            side_effect=lambda name: backends_by_name[name],  # type: ignore
-        ), patch.object(
-            cmd, "has_backend", side_effect=_has,
-        ), patch.object(
-            cmd, "_prompt_yes", return_value=True,
-        ):
-            self.assertEqual(0, cmd.cmd_cleanup([]))
-
-        docker.prepare_cleanup.assert_called_once()
-        docker.cleanup.assert_called_once_with(docker_plan)
-        macos.prepare_cleanup.assert_not_called()
-
    def test_short_circuits_when_all_empty(self):
        docker, _ = _make_backend(empty=True)
        fc, _ = _make_backend(empty=True)
@@ -83,8 +53,6 @@ class TestCmdCleanup(unittest.TestCase):
        ), patch.object(
            cmd, "get_bottle_backend",
            side_effect=lambda name: backends_by_name[name],  # type: ignore
-        ), patch.object(
-            cmd, "has_backend", return_value=True,
        ), patch.object(
            cmd, "_prompt_yes",
        ) as prompt:
@@ -104,8 +72,6 @@ class TestCmdCleanup(unittest.TestCase):
        ), patch.object(
            cmd, "get_bottle_backend",
            side_effect=lambda name: backends_by_name[name],  # type: ignore
-        ), patch.object(
-            cmd, "has_backend", return_value=True,
        ), patch.object(
            cmd, "_prompt_yes", return_value=False,
        ):
@@ -126,8 +92,6 @@ class TestCmdCleanup(unittest.TestCase):
        ), patch.object(
            cmd, "get_bottle_backend",
            side_effect=lambda name: backends_by_name[name],  # type: ignore
-        ), patch.object(
-            cmd, "has_backend", return_value=True,
        ), patch.object(
            cmd, "_prompt_yes", return_value=True,
        ):
@@ -1,29 +1,61 @@
-"""Unit: backend resolution priority — explicit name > env var.
+"""Unit: `cli.py start --backend=<name>` flag (issue #77).

-The `--backend` flag has been removed from `cli.py start`; backend
-selection is driven by BOT_BOTTLE_BACKEND or auto-selection only.
-`get_bottle_backend` still accepts an explicit name so that `resume`
-(which records the backend from a prior session) and the `backend`
-sub-command can pass one directly."""
+Asserts that the flag wins over the env var, that the env var is
+the fallback, and that the choices are pulled from the backend
+registry (so adding a backend lights up in argparse without code
+edits)."""

 from __future__ import annotations

+import argparse
 import os
 import unittest
 from unittest.mock import patch


-class TestBackendResolutionPriority(unittest.TestCase):
-    def test_explicit_name_overrides_env_var(self):
+from bot_bottle.backend import known_backend_names
+
+
+class TestStartBackendFlag(unittest.TestCase):
+    """The flag is wired by `cmd_start`'s argparse and threaded
+    through `prepare_with_preflight(backend_name=...)`. Rather than
+    drive the whole start flow (which builds containers), we test
+    the argparse shape and the resolution function separately."""
+
+    def _build_parser(self):
+        # Mirror the parser definition from `cmd_start` so this
+        # test doesn't have to invoke the full command.
+        parser = argparse.ArgumentParser(prog="cb start")
+        parser.add_argument(
+            "--backend",
+            choices=known_backend_names(),
+            default=None,
+        )
+        parser.add_argument("name")
+        return parser
+
+    def test_flag_recognized(self):
+        args = self._build_parser().parse_args(["--backend=firecracker", "researcher"])
+        self.assertEqual("firecracker", args.backend)
+        self.assertEqual("researcher", args.name)
+
+    def test_flag_default_none_means_env_or_default_backend(self):
+        args = self._build_parser().parse_args(["researcher"])
+        self.assertIsNone(args.backend)
+
+    def test_invalid_backend_rejected_by_argparse(self):
+        parser = self._build_parser()
+        with self.assertRaises(SystemExit):
+            parser.parse_args(["--backend=garbage", "researcher"])
+
+    def test_resolution_priority_explicit_over_env(self):
+        # Independent assertion that get_bottle_backend (where
+        # `--backend` ultimately threads to) prefers the explicit
+        # name over BOT_BOTTLE_BACKEND.
        from bot_bottle.backend import get_bottle_backend
        with patch.dict(os.environ, {"BOT_BOTTLE_BACKEND": "firecracker"}):
            self.assertEqual("docker", get_bottle_backend("docker").name)

-    def test_env_var_used_when_no_explicit_name(self):
-        from bot_bottle.backend import get_bottle_backend
-        with patch.dict(os.environ, {"BOT_BOTTLE_BACKEND": "firecracker"}):
-            self.assertEqual("firecracker", get_bottle_backend().name)
-

 if __name__ == "__main__":
    unittest.main()
@@ -175,6 +175,14 @@ class TestCmdStartHeadless(unittest.TestCase):
            )
        self.assertEqual("researcher-2", self._spec().label)

+    # -- backend wiring ------------------------------------------------
+
+    def test_backend_flag_forwarded(self):
+        start_mod.cmd_start(
+            ["--headless", "--backend=docker", "researcher", "--bottle", "claude",
+             "--prompt", "Do it"]
+        )
+        self.assertEqual("docker", self._launch_mock.call_args[1]["backend_name"])


 class TestPrepareWithPreflight(unittest.TestCase):
@@ -82,7 +82,7 @@ class TestCmdStartSelector(unittest.TestCase):
    # ------------------------------------------------------------------

    def test_explicit_agent_skips_agent_picker(self):
-        rc = start_mod.cmd_start(["researcher"])
+        rc = start_mod.cmd_start(["--backend=docker", "researcher"])
        self.assertEqual(0, rc)
        self._agent_picker_mock.assert_not_called()
        self._bottle_picker_mock.assert_called_once()
@@ -100,7 +100,7 @@ class TestCmdStartSelector(unittest.TestCase):

    def test_agent_absent_shows_agent_picker(self):
        self._agent_picker_mock.return_value = "researcher"
-        rc = start_mod.cmd_start([])
+        rc = start_mod.cmd_start(["--backend=docker"])
        self.assertEqual(0, rc)
        self._agent_picker_mock.assert_called_once()
        call_kwargs = self._agent_picker_mock.call_args
@@ -111,7 +111,7 @@ class TestCmdStartSelector(unittest.TestCase):

    def test_agent_picker_cancel_skips_bottle_picker(self):
        self._agent_picker_mock.return_value = None
-        rc = start_mod.cmd_start([])
+        rc = start_mod.cmd_start(["--backend=docker"])
        self.assertEqual(0, rc)
        self._bottle_picker_mock.assert_not_called()
        self._launch_mock.assert_not_called()
@@ -168,6 +168,16 @@ class TestCmdStartSelector(unittest.TestCase):
    # Backend wiring
    # ------------------------------------------------------------------

+    def test_explicit_backend_forwarded(self):
+        start_mod.cmd_start(["--backend=docker", "researcher"])
+        _, kwargs = self._launch_mock.call_args
+        self.assertEqual("docker", kwargs["backend_name"])
+
+    def test_absent_backend_uses_default(self):
+        start_mod.cmd_start(["researcher"])
+        _, kwargs = self._launch_mock.call_args
+        self.assertIsNone(kwargs["backend_name"])
+
    def test_bot_bottle_backend_env_skips_backend_picker(self):
        os.environ["BOT_BOTTLE_BACKEND"] = "docker"
        try:
@@ -1,58 +0,0 @@
-"""Unit: DbStore._connection() context manager and is_migrated()."""
-
-from __future__ import annotations
-
-import sqlite3
-import tempfile
-import unittest
-from pathlib import Path
-
-from bot_bottle.db_store import DbStore
-from bot_bottle.migrations import TableMigrations
-
-
-def _store(tmp: Path) -> DbStore:
-    migrations = TableMigrations("test", ["CREATE TABLE items (id INTEGER PRIMARY KEY)"])
-    return DbStore(tmp / "test.db", migrations)
-
-
-class TestDbStoreIsMigrated(unittest.TestCase):
-    def test_returns_false_when_db_absent(self):
-        with tempfile.TemporaryDirectory() as d:
-            store = _store(Path(d))
-            self.assertFalse(store.is_migrated())
-
-    def test_returns_false_when_schema_versions_missing(self):
-        # DB file exists but has no schema_versions table → OperationalError → False.
-        with tempfile.TemporaryDirectory() as d:
-            store = _store(Path(d))
-            conn = sqlite3.connect(store.db_path)
-            conn.close()
-            self.assertFalse(store.is_migrated())
-
-    def test_returns_true_after_migrate(self):
-        with tempfile.TemporaryDirectory() as d:
-            store = _store(Path(d))
-            store.migrate()
-            self.assertTrue(store.is_migrated())
-
-    def test_returns_false_when_behind(self):
-        with tempfile.TemporaryDirectory() as d:
-            migrations = TableMigrations(
-                "test",
-                [
-                    "CREATE TABLE items (id INTEGER PRIMARY KEY)",
-                    "ALTER TABLE items ADD COLUMN name TEXT",
-                ],
-            )
-            store = DbStore(Path(d) / "test.db", migrations)
-            # Apply only the first migration manually.
-            conn = sqlite3.connect(store.db_path)
-            with conn:
-                TableMigrations("test", [migrations.migrations[0]]).apply(conn)
-            conn.close()
-            self.assertFalse(store.is_migrated())
-
-
-if __name__ == "__main__":
-    unittest.main()
@@ -1,35 +0,0 @@
-"""Tests for integration-test backend selection helpers."""
-
-from __future__ import annotations
-
-import os
-import unittest
-from unittest.mock import patch
-
-from tests._docker import skip_unless_docker_or_firecracker
-
-
-class TestSkipUnlessDockerOrFirecracker(unittest.TestCase):
-    def test_firecracker_runs_when_docker_tests_are_disabled(self):
-        with patch.dict(
-            os.environ,
-            {"BOT_BOTTLE_BACKEND": "firecracker", "SKIP_DOCKER_TESTS": "1"},
-            clear=True,
-        ):
-            decorated = skip_unless_docker_or_firecracker()(type("Case", (), {}))
-
-        self.assertFalse(getattr(decorated, "__unittest_skip__", False))
-
-    def test_non_firecracker_still_skips_when_docker_tests_are_disabled(self):
-        with patch.dict(
-            os.environ,
-            {"BOT_BOTTLE_BACKEND": "docker", "SKIP_DOCKER_TESTS": "1"},
-            clear=True,
-        ):
-            decorated = skip_unless_docker_or_firecracker()(type("Case", (), {}))
-
-        self.assertTrue(getattr(decorated, "__unittest_skip__", False))
-
-
-if __name__ == "__main__":
-    unittest.main()
@@ -35,12 +35,9 @@ class TestNetpoolSlots(unittest.TestCase):
    def test_slot_ip_math_31_pairs(self):
        with patch.dict(os.environ, {"BOT_BOTTLE_FC_IP_BASE": "100.64.0.0"}):
            s0, s1 = netpool.slot(0), netpool.slot(1)
-        # Iface names track netpool's (env-driven) prefix — the KVM CI runner
-        # overrides it for its isolated pool, so don't hardcode "bbfc".
-        pfx = netpool.IFACE_PREFIX
-        self.assertEqual((f"{pfx}0", "100.64.0.0", "100.64.0.1"),
+        self.assertEqual(("bbfc0", "100.64.0.0", "100.64.0.1"),
                         (s0.iface, s0.host_ip, s0.guest_ip))
-        self.assertEqual((f"{pfx}1", "100.64.0.2", "100.64.0.3"),
+        self.assertEqual(("bbfc1", "100.64.0.2", "100.64.0.3"),
                         (s1.iface, s1.host_ip, s1.guest_ip))

    def test_guest_cidr_is_31(self):
@@ -183,14 +180,11 @@ class TestNetpoolOverlap(unittest.TestCase):
        self.assertEqual("tailscale0", conflicts[0].dev)

    def test_ignores_own_taps_and_default(self):
-        # The "own tap" route uses netpool's (env-driven) iface name, so the
-        # test still exercises the self-ignore path on the KVM CI runner, whose
-        # BOT_BOTTLE_FC_IFACE_PREFIX differs from the default.
        with patch.dict(os.environ, {"BOT_BOTTLE_FC_IP_BASE": "10.243.0.0",
                                     "BOT_BOTTLE_FC_POOL_SIZE": "8"}), \
             self._routes([
                 {"dst": "default", "dev": "enp4s0"},
-                 {"dst": "10.243.0.0/31", "dev": netpool.slot(0).iface},
+                 {"dst": "10.243.0.0/31", "dev": "bbfc0"},
                 {"dst": "192.168.1.0/24", "dev": "enp4s0"},
             ]):
            self.assertEqual([], netpool.overlapping_routes())
@@ -209,7 +203,7 @@ class TestNetpoolAllocation(unittest.TestCase):
            # over (and here, exhaust the pool).
            slot, lock = netpool.allocate("first")
            self.addCleanup(lock.close)
-            self.assertEqual(netpool.slot(0).iface, slot.iface)
+            self.assertEqual("bbfc0", slot.iface)
            with patch.object(netpool, "die",
                              side_effect=SystemExit("exhausted")):
                with self.assertRaises(SystemExit):
@@ -329,14 +323,9 @@ class TestNetpoolDefaultsSingleSource(unittest.TestCase):
        with patch.dict(os.environ, {}, clear=True):
            self.assertEqual(int(d["BOT_BOTTLE_FC_POOL_SIZE"]), netpool.pool_size())
            self.assertEqual(d["BOT_BOTTLE_FC_IP_BASE"], netpool.ip_base())
-        # The module's *defaults* come from the same shared file. Assert the
-        # parsed defaults (not IFACE_PREFIX/NFT_TABLE, which layer a live env
-        # override on top — the KVM CI runner sets those for its isolated pool,
-        # which would otherwise mask this single-source check).
-        self.assertEqual(d["BOT_BOTTLE_FC_IFACE_PREFIX"],
-                         netpool._DEFAULTS["BOT_BOTTLE_FC_IFACE_PREFIX"])
-        self.assertEqual(d["BOT_BOTTLE_FC_NFT_TABLE"],
-                         netpool._DEFAULTS["BOT_BOTTLE_FC_NFT_TABLE"])
+        # Module constants resolve through the same shared file.
+        self.assertEqual(d["BOT_BOTTLE_FC_IFACE_PREFIX"], netpool.IFACE_PREFIX)
+        self.assertEqual(d["BOT_BOTTLE_FC_NFT_TABLE"], netpool.NFT_TABLE)

    def test_env_var_overrides_the_shared_default(self):
        with patch.dict(os.environ, {"BOT_BOTTLE_FC_IP_BASE": "10.99.0.0"}):
@@ -63,12 +63,9 @@ class TestNetpoolProbes(unittest.TestCase):
        self.assertEqual(2, ok.call_count)

    def test_missing_taps(self):
-        # Derive the expected iface from netpool's (env-driven) config rather
-        # than hardcoding "bbfc1": the KVM CI runner sets BOT_BOTTLE_FC_* for
-        # its isolated pool, so the prefix there is not the default.
        with patch.dict("os.environ", {"BOT_BOTTLE_FC_POOL_SIZE": "2"}), \
             patch.object(netpool, "tap_present", side_effect=[True, False]):
-            self.assertEqual([netpool.slot(1).iface], netpool.missing_taps())
+            self.assertEqual(["bbfc1"], netpool.missing_taps())

    def test_orch_slot_is_top_of_ip_base_16(self):
        # Dedicated orchestrator link: /31 at the top of the IP_BASE /16,
@@ -24,7 +24,7 @@ class TestBuildAgentRootfsDir(unittest.TestCase):
        self.addCleanup(self._tmp.cleanup)

    def test_cache_hit_skips_rebuild(self):
-        digest = image_builder._rootfs_digest(self.dockerfile)
+        digest = image_builder._dockerfile_hash(self.dockerfile)
        base = self.cache / "rootfs" / f"agent-{digest}"
        base.mkdir(parents=True)
        (base / ".bb-ready").write_text("ok\n")
@@ -55,17 +55,6 @@ class TestBuildAgentRootfsDir(unittest.TestCase):
            image_builder._dockerfile_hash(other),
        )

-    def test_rootfs_digest_tracks_dockerfile_and_init(self):
-        # Same Dockerfile, different injected init -> different rootfs key, so
-        # an init fix (e.g. /tmp perms) rebuilds instead of reusing a stale
-        # rootfs; different Dockerfiles also differ.
-        base = image_builder._rootfs_digest(self.dockerfile)
-        with patch.object(image_builder.util, "_GUEST_INIT", "#!/bin/sh\n# changed\n"):
-            self.assertNotEqual(base, image_builder._rootfs_digest(self.dockerfile))
-        other = self.cache / "Dockerfile2"
-        other.write_text("FROM python:3.12-slim\n")
-        self.assertNotEqual(base, image_builder._rootfs_digest(other))
-

 class TestSmokeTest(unittest.TestCase):
    def test_empty_argv_is_noop(self):
@@ -38,9 +38,7 @@ class TestBuildInfraRootfs(unittest.TestCase):
        # and exports PATH so gateway_init's subprocess daemons find python3.
        init = build.call_args.kwargs["init_script"]
        self.assertIn("bot_bottle.orchestrator", init)
-        # Gateway launches via the installed package (there is no
-        # /app/gateway_init.py file since the daemons moved into bot_bottle).
-        self.assertIn("bot_bottle.gateway_init", init)
+        self.assertIn("gateway_init.py", init)
        self.assertIn("export PATH=", init)
        # Persistent registry volume mounted at the DB dir before the CP starts.
        self.assertIn("/dev/vdb", init)
@@ -100,11 +98,7 @@ class TestRegistryVolume(unittest.TestCase):
 class TestEnsureBuilt(unittest.TestCase):
    def test_default_pulls_artifact_without_docker(self):
        # PRD 0069 Stage 2: the launch host pulls the prebuilt rootfs; no Docker.
-        # Pin BOT_BOTTLE_INFRA_BUILD off: the coverage CI job exports it =local
-        # for the integration suite, and that ambient value would otherwise send
-        # this default-path test down the local Docker-build branch.
-        with patch.dict(os.environ, {"BOT_BOTTLE_INFRA_BUILD": ""}), \
-                patch.object(infra_vm.docker_mod, "build_image") as build, \
+        with patch.object(infra_vm.docker_mod, "build_image") as build, \
                patch.object(infra_vm.infra_artifact, "ensure_artifact_gz") as pull:
            infra_vm.ensure_built()
        build.assert_not_called()
@@ -144,58 +138,27 @@ class TestWaitForHealth(unittest.TestCase):


 class TestEnsureRunningSingleton(unittest.TestCase):
-    def test_adopts_when_healthy_and_version_matches(self):
-        # Healthy control plane + existing key + matching version marker
-        # -> adopt (no boot), vm=None.
-        import tempfile
-        with tempfile.TemporaryDirectory() as td:
-            d = Path(td)
-            (d / "id_ed25519").write_text("k")
-            (d / "booted-version").write_text("v-current\n")
-            with patch.object(infra_vm, "_infra_dir", return_value=d), \
-                 patch.object(infra_vm, "_expected_version", return_value="v-current"), \
-                 patch.object(infra_vm, "_health_ok", return_value=True), \
-                 patch.object(infra_vm, "boot") as boot:
-                infra = infra_vm.ensure_running()
+    def test_adopts_when_healthy(self):
+        # A healthy control plane + existing key -> adopt (no boot), vm=None.
+        with patch.object(infra_vm, "_health_ok", return_value=True), \
+             patch.object(infra_vm, "_infra_dir") as d, \
+             patch.object(infra_vm, "boot") as boot:
+            keydir = MagicMock()
+            (keydir / "id_ed25519").exists.return_value = True
+            d.return_value = keydir
+            infra = infra_vm.ensure_running()
        boot.assert_not_called()
        self.assertIsNone(infra.vm)

-    def test_reboots_when_version_stale(self):
-        # Healthy control plane but the running VM booted an OLDER image
-        # (marker mismatch) -> reboot rather than adopt stale code.
-        import tempfile
-        with tempfile.TemporaryDirectory() as td:
-            d = Path(td)
-            (d / "id_ed25519").write_text("k")
-            (d / "booted-version").write_text("v-old\n")
-            with patch.object(infra_vm, "_infra_dir", return_value=d), \
-                 patch.object(infra_vm, "_expected_version", return_value="v-current"), \
-                 patch.object(infra_vm, "_health_ok", return_value=True), \
-                 patch.object(infra_vm, "stop") as stop, \
-                 patch.object(infra_vm, "ensure_built"), \
-                 patch.object(infra_vm, "wait_for_health"), \
-                 patch.object(infra_vm, "boot") as boot:
-                boot.return_value = infra_vm.InfraVm(
-                    guest_ip="10.243.255.1", private_key=Path("/k"), vm=MagicMock())
-                infra_vm.ensure_running()
-            stop.assert_called_once()      # dislodge the outdated VM
-            boot.assert_called_once()
-            # The fresh boot records the current version for the next launcher.
-            self.assertEqual("v-current\n", (d / "booted-version").read_text())
-
    def test_boots_when_unhealthy(self):
-        import tempfile
-        with tempfile.TemporaryDirectory() as td:
-            with patch.object(infra_vm, "_infra_dir", return_value=Path(td)), \
-                 patch.object(infra_vm, "_expected_version", return_value="v-current"), \
-                 patch.object(infra_vm, "_health_ok", return_value=False), \
-                 patch.object(infra_vm, "stop") as stop, \
-                 patch.object(infra_vm, "ensure_built") as built, \
-                 patch.object(infra_vm, "boot") as boot, \
-                 patch.object(infra_vm, "wait_for_health") as wait:
-                boot.return_value = infra_vm.InfraVm(
-                    guest_ip="10.243.255.1", private_key=Path("/k"), vm=MagicMock())
-                infra_vm.ensure_running()
+        with patch.object(infra_vm, "_health_ok", return_value=False), \
+             patch.object(infra_vm, "stop") as stop, \
+             patch.object(infra_vm, "ensure_built") as built, \
+             patch.object(infra_vm, "boot") as boot, \
+             patch.object(infra_vm, "wait_for_health") as wait:
+            boot.return_value = infra_vm.InfraVm(
+                guest_ip="10.243.255.1", private_key=Path("/k"), vm=MagicMock())
+            infra_vm.ensure_running()
        stop.assert_called_once()      # clear a stale VM first
        built.assert_called_once()
        boot.assert_called_once()
@@ -222,74 +185,5 @@ class TestKillPidfile(unittest.TestCase):
            kill.assert_not_called()


-class TestAdoptable(unittest.TestCase):
-    def _dir(self, td: str, *, key: bool = True, version: str | None = None) -> Path:
-        d = Path(td)
-        if key:
-            (d / "id_ed25519").write_text("k")
-        if version is not None:
-            (d / "booted-version").write_text(version + "\n")
-        return d
-
-    def test_true_when_key_version_and_health(self):
-        import tempfile
-        with tempfile.TemporaryDirectory() as td:
-            d = self._dir(td, version="v1")
-            with patch.object(infra_vm, "_infra_dir", return_value=d), \
-                 patch.object(infra_vm, "_health_ok", return_value=True):
-                self.assertTrue(infra_vm._adoptable(d / "id_ed25519", "u", "v1"))
-
-    def test_false_when_key_missing(self):
-        import tempfile
-        with tempfile.TemporaryDirectory() as td:
-            d = self._dir(td, key=False, version="v1")
-            with patch.object(infra_vm, "_infra_dir", return_value=d):
-                self.assertFalse(infra_vm._adoptable(d / "id_ed25519", "u", "v1"))
-
-    def test_false_when_no_version_marker(self):
-        import tempfile
-        with tempfile.TemporaryDirectory() as td:
-            d = self._dir(td)  # key present, no booted-version
-            with patch.object(infra_vm, "_infra_dir", return_value=d):
-                self.assertFalse(infra_vm._adoptable(d / "id_ed25519", "u", "v1"))
-
-    def test_false_when_version_mismatch(self):
-        import tempfile
-        with tempfile.TemporaryDirectory() as td:
-            d = self._dir(td, version="v-old")
-            with patch.object(infra_vm, "_infra_dir", return_value=d), \
-                 patch.object(infra_vm, "_health_ok", return_value=True):
-                self.assertFalse(infra_vm._adoptable(d / "id_ed25519", "u", "v1"))
-
-
-class TestKillInfraFirecrackers(unittest.TestCase):
-    def _fake_proc(self, root: Path, pid: int, comm: str, cmdline: list[str]) -> None:
-        p = root / str(pid)
-        p.mkdir()
-        (p / "comm").write_text(comm + "\n")
-        (p / "cmdline").write_bytes(b"\0".join(a.encode() for a in cmdline) + b"\0")
-
-    def test_kills_only_matching_infra_firecracker(self):
-        import tempfile
-        with tempfile.TemporaryDirectory() as td, \
-             tempfile.TemporaryDirectory() as proc:
-            infra_dir = Path(td)
-            cfg = str(infra_dir / "config.json")
-            root = Path(proc)
-            # target: firecracker bound to the infra config -> killed
-            self._fake_proc(root, 111, "firecracker",
-                            ["firecracker", "--no-api", "--config-file", cfg])
-            # a firecracker for a different (interactive) VM -> spared
-            self._fake_proc(root, 222, "firecracker",
-                            ["firecracker", "--config-file", "/home/u/other.json"])
-            # a non-firecracker process on the same config path -> spared
-            self._fake_proc(root, 333, "python3", ["python3", cfg])
-            (root / "not-a-pid").mkdir()
-            with patch.object(infra_vm, "_infra_dir", return_value=infra_dir), \
-                 patch.object(infra_vm.os, "kill") as kill:
-                infra_vm._kill_infra_firecrackers(proc_root=root)
-            kill.assert_called_once_with(111, infra_vm.signal.SIGKILL)
-
-
 if __name__ == "__main__":
    unittest.main()
@@ -2,9 +2,8 @@

 Tests both the helper functions in `bot_bottle.gateway_init`
 and the supervisor's end-to-end signal / exit-code behavior. The
-end-to-end tests use real subprocesses (`sleep`, `/bin/sh -c '...'`) —
-short-lived, no docker required — so they run under `tests/unit/`
-rather than `tests/integration/`."""
+end-to-end tests use real subprocesses — short-lived, no docker required
+— so they run under `tests/unit/` rather than `tests/integration/`."""

 from __future__ import annotations

@@ -15,7 +14,6 @@ import sys
 import time
 import unittest
 import warnings
-from pathlib import Path
 from unittest.mock import patch

 from bot_bottle.gateway_init import (
@@ -25,7 +23,11 @@ from bot_bottle.gateway_init import (
    _env_for_daemon,
    _selected_daemons,
 )
-from tests._bin import SLEEP
+
+# /bin/sleep does not exist on FHS-free systems (e.g. NixOS). Use a
+# portable Python one-liner so supervisor tests run on any platform.
+_SLEEP_30 = (sys.executable, "-c", "import time; time.sleep(30)")
+_SLEEP_60 = (sys.executable, "-c", "import time; time.sleep(60)")


 class TestEnvForDaemon(unittest.TestCase):
@@ -183,7 +185,7 @@ class TestSupervisor(unittest.TestCase):
        # up and the supervisor never set shutdown_at.
        specs = [
            _DaemonSpec("crasher", ("/bin/sh", "-c", "exit 1")),
-            _DaemonSpec("longrun", (SLEEP, "30")),
+            _DaemonSpec("longrun", _SLEEP_30),
        ]
        sup = _Supervisor(specs)
        sup.start_all()
@@ -215,7 +217,7 @@ class TestSupervisor(unittest.TestCase):
        # signal-killed longrun's negative returncode.
        specs = [
            _DaemonSpec("crasher", ("/bin/sh", "-c", "exit 1")),
-            _DaemonSpec("longrun", (SLEEP, "30")),
+            _DaemonSpec("longrun", _SLEEP_30),
        ]
        sup = _Supervisor(specs)
        sup.start_all()
@@ -260,7 +262,7 @@ class TestSupervisor(unittest.TestCase):
        )
        specs = [
            _DaemonSpec("egress", sighup_marker),
-            _DaemonSpec("other",  (SLEEP, "30")),
+            _DaemonSpec("other",  _SLEEP_30),
        ]
        sup = _Supervisor(specs)
        sup.start_all()
@@ -283,7 +285,7 @@ class TestSupervisor(unittest.TestCase):
        self._drive(sup)

    def test_forward_signal_unknown_daemon_no_op(self):
-        specs = [_DaemonSpec("a", (SLEEP, "30"))]
+        specs = [_DaemonSpec("a", _SLEEP_30)]
        sup = _Supervisor(specs)
        sup.start_all()
        delivered = sup.forward_signal(signal.SIGHUP, "ghost")
@@ -295,8 +297,8 @@ class TestSupervisor(unittest.TestCase):
        # Restart one daemon; the other (supervise, the MCP server
        # in production) must remain untouched.
        specs = [
-            _DaemonSpec("git-gate", (SLEEP, "30")),
-            _DaemonSpec("supervise", (SLEEP, "30")),
+            _DaemonSpec("git-gate", _SLEEP_30),
+            _DaemonSpec("supervise", _SLEEP_30),
        ]
        sup = _Supervisor(specs)
        sup.start_all()
@@ -320,8 +322,8 @@ class TestSupervisor(unittest.TestCase):

    def test_request_restart_is_drained_by_tick(self):
        specs = [
-            _DaemonSpec("git-gate", (SLEEP, "30")),
-            _DaemonSpec("supervise", (SLEEP, "30")),
+            _DaemonSpec("git-gate", _SLEEP_30),
+            _DaemonSpec("supervise", _SLEEP_30),
        ]
        sup = _Supervisor(specs)
        sup.start_all()
@@ -344,7 +346,7 @@ class TestSupervisor(unittest.TestCase):
        self._drive(sup)

    def test_repeated_restart_requests_coalesce(self):
-        specs = [_DaemonSpec("git-gate", (SLEEP, "30"))]
+        specs = [_DaemonSpec("git-gate", _SLEEP_30)]
        sup = _Supervisor(specs)
        sup.start_all()
        time.sleep(0.1)
@@ -367,7 +369,7 @@ class TestSupervisor(unittest.TestCase):
        self._drive(sup)

    def test_request_restart_unknown_daemon_no_op(self):
-        specs = [_DaemonSpec("a", (SLEEP, "30"))]
+        specs = [_DaemonSpec("a", _SLEEP_30)]
        sup = _Supervisor(specs)
        sup.start_all()
        ok = sup.request_restart("ghost")
@@ -377,7 +379,7 @@ class TestSupervisor(unittest.TestCase):
        self._drive(sup)

    def test_restart_unknown_daemon_no_op(self):
-        specs = [_DaemonSpec("a", (SLEEP, "30"))]
+        specs = [_DaemonSpec("a", _SLEEP_30)]
        sup = _Supervisor(specs)
        sup.start_all()
        ok = sup.restart_daemon("ghost")
@@ -386,7 +388,7 @@ class TestSupervisor(unittest.TestCase):
        self._drive(sup)

    def test_restart_during_shutdown_is_no_op(self):
-        specs = [_DaemonSpec("git-gate", (SLEEP, "30"))]
+        specs = [_DaemonSpec("git-gate", _SLEEP_30)]
        sup = _Supervisor(specs)
        sup.start_all()
        sup.request_shutdown(reason="test")
@@ -396,7 +398,7 @@ class TestSupervisor(unittest.TestCase):
        self._drive(sup)

    def test_pending_restart_dropped_during_shutdown(self):
-        specs = [_DaemonSpec("git-gate", (SLEEP, "30"))]
+        specs = [_DaemonSpec("git-gate", _SLEEP_30)]
        sup = _Supervisor(specs)
        sup.start_all()
        time.sleep(0.1)
@@ -414,8 +416,8 @@ class TestSupervisor(unittest.TestCase):
        # both should receive SIGTERM and exit. Signal-only
        # shutdown clamps to a zero supervisor exit code.
        specs = [
-            _DaemonSpec("a", (SLEEP, "60")),
-            _DaemonSpec("b", (SLEEP, "60")),
+            _DaemonSpec("a", _SLEEP_60),
+            _DaemonSpec("b", _SLEEP_60),
        ]
        sup = _Supervisor(specs)
        sup.start_all()
@@ -450,7 +452,7 @@ class TestSupervisor(unittest.TestCase):
        self.assertEqual(0, rc)

    def test_idempotent_shutdown_requests(self):
-        specs = [_DaemonSpec("a", (SLEEP, "60"))]
+        specs = [_DaemonSpec("a", _SLEEP_60)]
        sup = _Supervisor(specs)
        sup.start_all()
        time.sleep(0.1)
@@ -466,28 +468,22 @@ class TestSupervisor(unittest.TestCase):

 class TestMainEndToEnd(unittest.TestCase):
    """Run gateway_init.py as a real subprocess to cover the
-    signal-handler installation path. Skipped on platforms
-    without /bin/sleep + /bin/sh."""
-
-    @classmethod
-    def setUpClass(cls):
-        for p in ("/bin/sh", SLEEP):
-            if not Path(p).exists():
-                raise unittest.SkipTest(f"missing {p}")
+    signal-handler installation path."""

    def _run(self, daemons_csv: str, send_signal: int | None,
             wait_before_signal: float = 0.4,
             overall_timeout: float = 6.0) -> tuple[int, str]:
        """Spawn gateway_init.main() in a child process with the
-        DAEMONS list patched to harmless `sleep 30` commands.
+        DAEMONS list patched to harmless long-sleep commands.
        Returns (returncode, captured stdout)."""

        helper = (
            "import os, runpy, sys\n"
            "from bot_bottle import gateway_init as si\n"
+            "sleep_cmd = (sys.executable, '-c', 'import time; time.sleep(30)')\n"
            "si._DAEMONS = (\n"
-            f"  si._DaemonSpec('alpha', ({SLEEP!r},'30')),\n"
-            f"  si._DaemonSpec('beta',  ({SLEEP!r},'30')),\n"
+            "  si._DaemonSpec('alpha', sleep_cmd),\n"
+            "  si._DaemonSpec('beta',  sleep_cmd),\n"
            ")\n"
            "sys.exit(si.main([]))\n"
        )
@@ -50,12 +50,7 @@ class _CacheMixin(unittest.TestCase):
        self._env = mock.patch.dict(
            os.environ,
            {"BOT_BOTTLE_FC_CACHE": self._tmp.name,
-             "BOT_BOTTLE_INFRA_ARTIFACT_TOKEN": "",
-             # Pin the candidate-dir override off: the coverage CI job exports a
-             # candidate dir for the integration suite, and an ambient value
-             # would send these registry-pull tests down the local-bundle path.
-             # Cases that exercise the candidate path set it explicitly.
-             "BOT_BOTTLE_INFRA_ARTIFACT_DIR": ""},
+             "BOT_BOTTLE_INFRA_ARTIFACT_TOKEN": ""},
            clear=False,
        )
        self._env.start()
@@ -98,31 +93,6 @@ class TestVersionInputs(unittest.TestCase):
        (pkg / "netpool.defaults.env").write_text("FOO=1\n")
        for name in ("Dockerfile.orchestrator", "Dockerfile.gateway", "Dockerfile.infra"):
            (root / name).write_text(f"FROM scratch  # {name}\n")
-        (root / "pyproject.toml").write_text("[project]\nname = 'bot-bottle'\n")
-
-    def test_pyproject_toml_change_bumps_version(self) -> None:
-        with tempfile.TemporaryDirectory() as d:
-            root = Path(d)
-            self._fake_repo(root)
-            before = ia.infra_artifact_version("init", repo_root=root)
-            (root / "pyproject.toml").write_text(
-                "[project]\nname = 'bot-bottle'\ndependencies = ['httpx']\n")
-            after = ia.infra_artifact_version("init", repo_root=root)
-        self.assertNotEqual(before, after)
-
-    def test_dropbear_change_bumps_version(self) -> None:
-        with tempfile.TemporaryDirectory() as d:
-            root = Path(d)
-            self._fake_repo(root)
-            dropbear = root / "dropbear"
-            dropbear.write_bytes(b"dropbear-v1")
-            with mock.patch.dict(os.environ, {
-                "BOT_BOTTLE_FC_DROPBEAR": str(dropbear),
-            }):
-                before = ia.infra_artifact_version("init", repo_root=root)
-                dropbear.write_bytes(b"dropbear-v2")
-                after = ia.infra_artifact_version("init", repo_root=root)
-        self.assertNotEqual(before, after)

    def test_non_python_file_change_bumps_version(self) -> None:
        with tempfile.TemporaryDirectory() as d:
@@ -148,58 +118,6 @@ class TestVersionInputs(unittest.TestCase):


 class TestEnsureArtifact(_CacheMixin):
-    def test_uses_verified_ci_candidate_without_network(self) -> None:
-        version = "deadbeef00000000"
-        gz = _gz(b"candidate ext4")
-        with tempfile.TemporaryDirectory() as d:
-            root = Path(d)
-            (root / "version.txt").write_text(version + "\n")
-            (root / "rootfs.ext4.gz").write_bytes(gz)
-            digest = hashlib.sha256(gz).hexdigest()
-            (root / "rootfs.ext4.gz.sha256").write_text(
-                f"{digest}  rootfs.ext4.gz\n")
-            with mock.patch.dict(os.environ, {
-                "BOT_BOTTLE_INFRA_ARTIFACT_DIR": str(root),
-            }), mock.patch.object(ia.urllib.request, "urlopen") as net:
-                path = ia.ensure_artifact_gz(version)
-            self.assertEqual(root / "rootfs.ext4.gz", path)
-            net.assert_not_called()
-
-    def test_rejects_candidate_for_another_version(self) -> None:
-        with tempfile.TemporaryDirectory() as d:
-            root = Path(d)
-            (root / "version.txt").write_text("wrong\n")
-            with mock.patch.dict(os.environ, {
-                "BOT_BOTTLE_INFRA_ARTIFACT_DIR": str(root),
-            }):
-                with self.assertRaises(Die) as ctx:
-                    ia.ensure_artifact_gz("expected")
-            self.assertIn("version mismatch", str(ctx.exception.message))
-
-    def test_rejects_incomplete_candidate(self) -> None:
-        with tempfile.TemporaryDirectory() as d:
-            root = Path(d)
-            (root / "version.txt").write_text("v1\n")
-            with mock.patch.dict(os.environ, {
-                "BOT_BOTTLE_INFRA_ARTIFACT_DIR": str(root),
-            }):
-                with self.assertRaises(Die) as ctx:
-                    ia.ensure_artifact_gz("v1")
-            self.assertIn("incomplete", str(ctx.exception.message))
-
-    def test_rejects_candidate_checksum_mismatch(self) -> None:
-        with tempfile.TemporaryDirectory() as d:
-            root = Path(d)
-            (root / "version.txt").write_text("v1\n")
-            (root / "rootfs.ext4.gz").write_bytes(b"bad")
-            (root / "rootfs.ext4.gz.sha256").write_text("0" * 64 + "  rootfs.ext4.gz\n")
-            with mock.patch.dict(os.environ, {
-                "BOT_BOTTLE_INFRA_ARTIFACT_DIR": str(root),
-            }):
-                with self.assertRaises(Die) as ctx:
-                    ia.ensure_artifact_gz("v1")
-            self.assertIn("checksum mismatch", str(ctx.exception.message))
-
    def test_downloads_verifies_and_caches(self) -> None:
        version = "deadbeef00000000"
        gz = _gz(b"fake ext4 bytes")
@@ -17,10 +17,10 @@ from unittest.mock import patch
 from bot_bottle.backend.macos_container.bottle import MacosContainerBottle
 from bot_bottle.backend.macos_container.bottle_plan import MacosContainerBottlePlan
 from bot_bottle.backend.macos_container.consolidated_launch import GatewayEndpoint
-from bot_bottle.backend.macos_container.gateway_hosts import GATEWAY_HOSTNAME
 from bot_bottle.backend.macos_container.launch import (
    _agent_run_argv,
    _identity_proxy_env,
+    _proxy_url,
 )
 from bot_bottle.manifest import ManifestIndex

@@ -104,38 +104,19 @@ class TestAgentRunArgv(unittest.TestCase):
        read back after start."""
        self.assertNotIn("--ip", self.argv)

-    def test_run_time_env_sets_no_proxy_vars_at_all(self) -> None:
-        """Regression: the proxy vars must exist *only* in the exec-time env.
-
-        `container exec --env` appends rather than replaces, so a token-less
-        `HTTPS_PROXY` here would survive next to the token-bearing one and
-        leave two entries in the agent's `environ`. Resolution is then
-        runtime-specific — Node reads the last, Rust's `std::env::var` reads
-        the first — so Codex proxied without its identity token and every
-        request fail-closed at `/resolve`.
-        """
-        for entry in self.argv:
-            self.assertFalse(
-                entry.upper().startswith(("HTTP_PROXY=", "HTTPS_PROXY=")),
-                f"run-time env must not set a proxy var, got {entry!r}",
-            )
-
-    def test_run_time_env_carries_no_identity_token(self) -> None:
-        """The token is minted by registration, which happens after this run,
-        so it cannot be here under any name."""
-        self.assertNotIn("bottle:", " ".join(self.argv))
+    def test_run_time_proxy_carries_no_identity_token(self) -> None:
+        """The token is minted by registration, which happens after this run —
+        so it cannot be here. `/resolve` denies the token-less pair (#366),
+        which is the safe direction; the real value arrives at exec time."""
+        joined = " ".join(self.argv)
+        self.assertIn(f"HTTP_PROXY={_proxy_url('192.168.128.3')}", joined)
+        self.assertNotIn("bottle:", joined)

    def test_gateway_bypasses_the_proxy(self) -> None:
        """git-http + supervise live on the gateway and must be reached
        directly, not through its own egress proxy."""
        entry = next(a for a in self.argv if a.startswith("NO_PROXY="))
-        self.assertIn(GATEWAY_HOSTNAME, entry)
-
-    def test_no_proxy_names_the_gateway_and_never_addresses_it(self) -> None:
-        """NO_PROXY is baked into the run-time env, so an address here is as
-        unfixable as the proxy URL if the gateway moves."""
-        entry = next(a for a in self.argv if a.startswith("NO_PROXY="))
-        self.assertNotIn("192.168.128.3", entry)
+        self.assertIn("192.168.128.3", entry)

    def test_forwarded_secrets_stay_off_argv(self) -> None:
        """Bare name → inherited from the run process env, so the value never
@@ -153,7 +134,7 @@ class TestIdentityTokenDelivery(unittest.TestCase):
    def test_exec_env_carries_the_token_as_proxy_credentials(self) -> None:
        env = _identity_proxy_env(_endpoint(), "s3cret")
        self.assertEqual(
-            f"http://bottle:s3cret@{GATEWAY_HOSTNAME}:9099", env["HTTP_PROXY"],
+            "http://bottle:s3cret@192.168.128.3:9099", env["HTTP_PROXY"],
        )
        self.assertEqual(env["HTTP_PROXY"], env["https_proxy"])

@@ -221,7 +202,7 @@ class TestPlanIdentityToken(unittest.TestCase):
        self.assertIn("HTTP_PROXY", argv)
        self.assertNotIn("s3cret", " ".join(argv))
        self.assertEqual(
-            f"http://bottle:s3cret@{GATEWAY_HOSTNAME}:9099", kwargs["env"]["HTTP_PROXY"],
+            "http://bottle:s3cret@192.168.128.3:9099", kwargs["env"]["HTTP_PROXY"],
        )


@@ -272,30 +272,6 @@ resolver #2
                ),
            )

-    def test_exec_container_as_root_selects_root_user(self):
-        completed = util.subprocess.CompletedProcess(
-            args=[], returncode=0, stdout="", stderr="",
-        )
-        with patch.object(util, "_run_container_op", return_value=completed) as run:
-            util.exec_container_as_root("bot-bottle-demo", ["true"])
-
-        run.assert_called_once_with([
-            "container", "exec", "--user", "root", "bot-bottle-demo", "true",
-        ])
-
-    def test_exec_container_as_root_reports_failure(self):
-        failed = util.subprocess.CompletedProcess(
-            args=[], returncode=1, stdout="", stderr="permission denied\n",
-        )
-        with patch.object(util, "_run_container_op", return_value=failed), \
-             patch.object(util, "die", side_effect=SystemExit("die")) as die:
-            with self.assertRaises(SystemExit):
-                util.exec_container_as_root("bot-bottle-demo", ["true"])
-
-        die.assert_called_once_with(
-            "container exec (root) in bot-bottle-demo failed: permission denied",
-        )
-

 def _completed(stdout: str, returncode: int = 0):
    return util.subprocess.CompletedProcess(args=[], returncode=returncode, stdout=stdout, stderr="")
@@ -1,140 +0,0 @@
-"""Unit: stable gateway name via each bottle's /etc/hosts (issue #443).
-
-The gateway's address moves whenever the infra container is recreated. Agents
-name it instead of addressing it, and the name resolves through `/etc/hosts` —
-a file, so it stays rewritable while the bottle runs, unlike the `environ` the
-proxy URL is delivered in.
-"""
-
-from __future__ import annotations
-
-import unittest
-from types import SimpleNamespace
-from unittest.mock import patch
-
-from bot_bottle.backend.macos_container.gateway_hosts import (
-    GATEWAY_HOSTNAME,
-    refresh_gateway_host,
-    set_gateway_host,
-)
-
-_MOD = "bot_bottle.backend.macos_container.gateway_hosts"
-
-
-class TestSetGatewayHost(unittest.TestCase):
-    def _script(self, exec_root: object) -> str:
-        argv = exec_root.call_args.args[1]  # type: ignore[attr-defined]
-        self.assertEqual(["sh", "-c"], argv[:2])
-        return argv[2]
-
-    def test_writes_the_address_against_the_stable_name(self) -> None:
-        with patch(f"{_MOD}.container_mod.exec_container_as_root") as ex:
-            set_gateway_host("bot-bottle-demo", "192.168.128.19")
-        self.assertEqual("bot-bottle-demo", ex.call_args.args[0])
-        script = self._script(ex)
-        self.assertIn("192.168.128.19", script)
-        self.assertIn(GATEWAY_HOSTNAME, script)
-
-    def test_runs_as_root_so_the_agent_cannot_repoint_itself(self) -> None:
-        """The agent runs as `node`. If it could rewrite /etc/hosts it could
-        aim its own gateway name elsewhere, so the write must go through the
-        root-only helper."""
-        with patch(f"{_MOD}.container_mod.exec_container_as_root") as ex:
-            set_gateway_host("bot-bottle-demo", "10.0.0.1")
-        ex.assert_called_once()
-
-    def test_is_idempotent_by_removing_its_own_line_first(self) -> None:
-        """Re-pointing must replace the managed entry, not append a second one
-        — two entries for the same name would resolve by luck of ordering."""
-        with patch(f"{_MOD}.container_mod.exec_container_as_root") as ex:
-            set_gateway_host("bot-bottle-demo", "10.0.0.1")
-        self.assertIn("grep -v", self._script(ex))
-
-    def test_preserves_the_rest_of_the_hosts_file(self) -> None:
-        """localhost and the container's own name must survive the rewrite."""
-        with patch(f"{_MOD}.container_mod.exec_container_as_root") as ex:
-            set_gateway_host("bot-bottle-demo", "10.0.0.1")
-        script = self._script(ex)
-        # Filter-and-append, never a truncating write of just our line.
-        self.assertIn("/etc/hosts >", script)
-        self.assertIn(">> /tmp/.bb-hosts", script)
-
-    def test_keeps_the_original_inode(self) -> None:
-        """`cat >` rather than `mv`: a pre-created /etc/hosts must keep its
-        ownership and mode, not be replaced by a root-owned copy."""
-        script = None
-        with patch(f"{_MOD}.container_mod.exec_container_as_root") as ex:
-            set_gateway_host("bot-bottle-demo", "10.0.0.1")
-            script = self._script(ex)
-        self.assertIn("cat /tmp/.bb-hosts > /etc/hosts", script)
-        self.assertNotIn("mv ", script)
-
-
-class TestRefreshGatewayHost(unittest.TestCase):
-    """The re-attach sweep: bottles stranded by an earlier gateway restart get
-    re-pointed in place instead of needing a relaunch."""
-
-    def _agents(self, *slugs: str) -> list[SimpleNamespace]:
-        return [SimpleNamespace(slug=s) for s in slugs]
-
-    def test_repoints_every_running_bottle(self) -> None:
-        with patch(f"{_MOD}.enumerate_active", return_value=self._agents("a", "b")), \
-                patch(f"{_MOD}.set_gateway_host") as setter:
-            updated = refresh_gateway_host("192.168.128.19")
-        self.assertEqual(["bot-bottle-a", "bot-bottle-b"], updated)
-        self.assertEqual(
-            [("bot-bottle-a", "192.168.128.19"), ("bot-bottle-b", "192.168.128.19")],
-            [c.args for c in setter.call_args_list],
-        )
-
-    def test_one_failing_bottle_does_not_stop_the_sweep(self) -> None:
-        """A container that is already exiting must not block the repair of
-        its neighbours, nor fail the launch that triggered the sweep."""
-        def _flaky(name: str, _ip: str) -> None:
-            if name == "bot-bottle-a":
-                raise RuntimeError("container is exiting")
-
-        with patch(f"{_MOD}.enumerate_active", return_value=self._agents("a", "b")), \
-                patch(f"{_MOD}.set_gateway_host", side_effect=_flaky), \
-                patch(f"{_MOD}.warn") as warn:
-            updated = refresh_gateway_host("10.0.0.1")
-        self.assertEqual(["bot-bottle-b"], updated)
-        warn.assert_called_once()
-
-    def test_no_running_bottles_is_a_clean_no_op(self) -> None:
-        with patch(f"{_MOD}.enumerate_active", return_value=[]), \
-                patch(f"{_MOD}.set_gateway_host") as setter:
-            self.assertEqual([], refresh_gateway_host("10.0.0.1"))
-        setter.assert_not_called()
-
-
-
-class TestLaunchWiring(unittest.TestCase):
-    """Ordering matters: the name must resolve before anything execs, and the
-    stranded-bottle sweep must run once the gateway is known to be up."""
-
-    def test_launch_sets_the_host_entry_before_reading_the_source_ip(self) -> None:
-        """The agent's every URL names the gateway, so the entry has to exist
-        before the first connection — which means before the agent execs."""
-        import inspect
-
-        from bot_bottle.backend.macos_container import launch
-
-        src = inspect.getsource(launch)
-        set_at = src.index("set_gateway_host(plan.container_name")
-        exec_at = src.index("wait_container_ipv4_on_network")
-        self.assertLess(set_at, exec_at)
-
-    def test_launch_refreshes_stranded_bottles_after_ensure_gateway(self) -> None:
-        import inspect
-
-        from bot_bottle.backend.macos_container import launch
-
-        src = inspect.getsource(launch)
-        ensure_at = src.index("endpoint = ensure_gateway()")
-        refresh_at = src.index("refresh_gateway_host(endpoint.gateway_ip)")
-        self.assertLess(ensure_at, refresh_at)
-
-
-if __name__ == "__main__":
-    unittest.main()
@@ -46,9 +46,7 @@ class TestInfraRun(unittest.TestCase):
        argv = self._run_container(MacosInfraService(repo_root=Path("/r")))
        script = argv[-1]
        self.assertIn("bot_bottle.orchestrator", script)
-        # Gateway launches via the installed package (there is no
-        # /app/gateway_init.py file since the daemons moved into bot_bottle).
-        self.assertIn("bot_bottle.gateway_init", script)
+        self.assertIn("gateway_init.py", script)
        self.assertIn("127.0.0.1", script)  # they reach each other on loopback

    def test_db_is_a_container_only_volume(self) -> None:
@@ -6,11 +6,8 @@ read it into memory. Network is mocked; no Docker, no real build.

 from __future__ import annotations

-import hashlib
-from email.message import Message
 import tempfile
 import unittest
-import urllib.error
 import urllib.request
 from pathlib import Path
 from unittest import mock
@@ -61,99 +58,5 @@ class TestPut(unittest.TestCase):
        self.assertEqual(b"abc123  rootfs\n", captured[0].data)


-class TestPublishBundle(unittest.TestCase):
-    def _bundle(self, root: Path, version: str) -> None:
-        payload = b"candidate"
-        (root / "version.txt").write_text(version + "\n")
-        (root / "rootfs.ext4.gz").write_bytes(payload)
-        digest = hashlib.sha256(payload).hexdigest()
-        (root / "rootfs.ext4.gz.sha256").write_text(
-            f"{digest}  rootfs.ext4.gz\n")
-
-    def test_existing_identical_artifact_is_success(self) -> None:
-        with tempfile.TemporaryDirectory() as d:
-            root = Path(d)
-            self._bundle(root, "v1")
-            sha = (root / "rootfs.ext4.gz.sha256").read_bytes()
-            response = mock.MagicMock()
-            response.__enter__.return_value.read.return_value = sha
-            with mock.patch.object(
-                pub.infra_artifact, "infra_artifact_version", return_value="v1"
-            ), mock.patch.object(
-                pub.urllib.request, "urlopen", return_value=response
-            ), mock.patch.object(pub, "_put") as put:
-                self.assertEqual("v1", pub._publish_bundle(root, "token"))
-            put.assert_not_called()
-
-    def test_partial_artifact_is_replaced(self) -> None:
-        with tempfile.TemporaryDirectory() as d:
-            root = Path(d)
-            self._bundle(root, "v1")
-            missing = urllib.error.HTTPError("u", 404, "missing", Message(), None)
-            with mock.patch.object(
-                pub.infra_artifact, "infra_artifact_version", return_value="v1"
-            ), mock.patch.object(
-                pub.urllib.request, "urlopen", side_effect=missing
-            ), mock.patch.object(pub, "_delete") as delete, \
-                    mock.patch.object(pub, "_put") as put:
-                pub._publish_bundle(root, "token")
-            self.assertEqual(3, delete.call_count)
-            self.assertEqual(3, put.call_count)
-
-    def test_rejects_bundle_for_different_checkout(self) -> None:
-        with tempfile.TemporaryDirectory() as d:
-            root = Path(d)
-            self._bundle(root, "old")
-            with mock.patch.object(
-                pub.infra_artifact, "infra_artifact_version", return_value="new"
-            ):
-                with self.assertRaises(SystemExit) as ctx:
-                    pub._publish_bundle(root, "token")
-            self.assertIn("does not match checkout", str(ctx.exception))
-
-    def test_rejects_bad_bundle_checksum(self) -> None:
-        with tempfile.TemporaryDirectory() as d:
-            root = Path(d)
-            self._bundle(root, "v1")
-            (root / "rootfs.ext4.gz").write_bytes(b"tampered")
-            with mock.patch.object(
-                pub.infra_artifact, "infra_artifact_version", return_value="v1"
-            ):
-                with self.assertRaises(SystemExit) as ctx:
-                    pub._publish_bundle(root, "token")
-            self.assertIn("checksum mismatch", str(ctx.exception))
-
-    def test_registry_lookup_failure_is_reported(self) -> None:
-        with tempfile.TemporaryDirectory() as d:
-            root = Path(d)
-            self._bundle(root, "v1")
-            failure = urllib.error.URLError("offline")
-            with mock.patch.object(
-                pub.infra_artifact, "infra_artifact_version", return_value="v1"
-            ), mock.patch.object(pub.urllib.request, "urlopen", side_effect=failure):
-                with self.assertRaises(SystemExit) as ctx:
-                    pub._publish_bundle(root, "token")
-            self.assertIn("registry unreachable", str(ctx.exception))
-
-
-class TestMain(unittest.TestCase):
-    def test_output_builds_candidate_and_records_version(self) -> None:
-        with tempfile.TemporaryDirectory() as d:
-            root = Path(d) / "candidate"
-            with mock.patch.object(
-                pub, "build_artifact", return_value=("v1", root / "g", root / "s")
-            ) as build:
-                self.assertEqual(0, pub.main(["--output", str(root)]))
-            build.assert_called_once_with(root)
-            self.assertEqual("v1\n", (root / "version.txt").read_text())
-
-    def test_publish_dir_publishes_existing_candidate(self) -> None:
-        with tempfile.TemporaryDirectory() as d, \
-                mock.patch.object(pub.infra_artifact, "_config", return_value=("", "", "t")), \
-                mock.patch.object(pub, "_publish_bundle", return_value="v1") as publish:
-            self.assertEqual(0, pub.main(["--publish-dir", d]))
-            publish.assert_called_once_with(Path(d), "t")
-
-
 if __name__ == "__main__":
    unittest.main()
Author	SHA1	Message	Date
didericis-claude	9e75fce7cf	test: replace /bin/sleep with portable Python sleep in test_gateway_init test / integration-firecracker (pull_request) Successful in 17s Details test / integration-docker (pull_request) Successful in 18s Details test / coverage (pull_request) Failing after 33s Details lint / lint (push) Successful in 54s Details test / unit (pull_request) Successful in 1m34s Details tracker-policy-pr / check-pr (pull_request) Failing after 11m24s Details /bin/sleep does not exist at FHS paths on NixOS (the KVM self-hosted runner's OS). All 13 FileNotFoundError failures in TestSupervisor were caused by _DaemonSpec tuples spawning /bin/sleep directly. Replace with a module-level _SLEEP_30/_SLEEP_60 tuple using sys.executable so the supervisor tests run on any platform. Also fix TestMainEndToEnd._run() and remove the now-unnecessary setUpClass guard.	2026-07-18 22:08:43 -04:00
didericis-claude	2738b0fe6c	fix(tests): mock name_color_modal in test_cli_start_selector setUp On a self-hosted KVM runner the process has a real controlling terminal so name_color_modal successfully opens /dev/tty and enters a curses loop waiting for keyboard input, hanging the test indefinitely. Docker containers (ubuntu-latest runners) don't have a real /dev/tty, causing an OSError that triggers the existing fallback — this is why the hang was invisible in ubuntu-latest CI. Also add timeout=5 to _daemon_reachable() to match the same defensive fix already applied to docker_available() in tests/_docker.py. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-07-18 22:08:43 -04:00
didericis-claude	d1d5e635ea	fix(coverage): skip docker integration tests on the KVM runner Docker integration tests are already covered by the integration-docker job on ubuntu-latest. On the KVM runner the Firecracker TAP/nftables pool conflicts with Docker networking, causing those tests to hang and the coverage job to never complete. Add SKIP_DOCKER_TESTS env-var support to docker_available() and set it for the integration phase of coverage.sh so only Firecracker integration tests run there.	2026-07-18 22:08:43 -04:00
didericis-claude	1b24d72745	ci: fix tracker-policy-pr trigger — synchronize not synchronized Gitea fires the pull_request push event as 'synchronize' (GitHub spec), not 'synchronized'. The typo meant the workflow only ran on opened/ edited/reopened, leaving the required check yellow with no details link after every commit push.	2026-07-18 22:08:43 -04:00
didericis-claude	bc8894469b	fix(tests): add 5-second timeout to docker_available() to prevent hang on KVM runner On the self-hosted KVM runner Docker is on PATH but the daemon socket is unreachable (firewalled/dropped). subprocess.run(["docker", "info"]) with no timeout hangs indefinitely on a dropped connection, stalling the coverage job for hours — one hang per @skip_unless_docker()-decorated class, ~8 per integration suite run. Add timeout=5 with a TimeoutExpired → False fallback so the check resolves quickly to "unreachable" rather than blocking.	2026-07-18 22:08:43 -04:00
didericis-codex	54589b1cc2	ci: scope firecracker backend to integration coverage	2026-07-18 22:08:43 -04:00
didericis-claude	58e450e61f	fix(db): close SQLite connections explicitly to suppress ResourceWarning on Python 3.13 `sqlite3.Connection.__exit__` only commits/rolls back a transaction — it does not close the connection. Python 3.13 (the Nix env on the KVM runner) emits `ResourceWarning: unclosed database` for every connection GC'd without an explicit close, producing noisy output in the coverage job. Add `DbStore._connection()`, a `contextmanager` that calls `self._connect()`, wraps it in the existing transaction context manager, and closes the connection in a `finally` block. Change all `with self._connect() as conn:` call sites in `db_store.py`, `audit_store.py`, `queue_store.py`, and `orchestrator/registry.py` to `with self._connection() as conn:`. `_connect()` remains as the per-subclass hook (RegistryStore overrides it to set `busy_timeout`); `_connection()` delegates to `self._connect()` so the override is respected.	2026-07-18 22:08:43 -04:00
didericis	bca4713304	ci: drop dev-requirements pip install on the self-hosted KVM runner The self-hosted runner's Nix python env has no `pip` module, so `python3 -m pip install -r requirements-dev.txt` failed with "No module named pip" in both firecracker jobs. Neither job needs that install: - integration-firecracker runs the stdlib `unittest` suite (no deps); - coverage needs only `coverage`, which the runner's Nix python env already ships (7.12.0) — verified `coverage run`/`coverage json` work. pylint/pyright are lint.yml's concern, not test.yml's. The ubuntu-latest `unit` job keeps its `--break-system-packages` install unchanged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S1qRZTJC6qgBsUSjNrBdkX	2026-07-18 22:08:43 -04:00
didericis-claude	8ce78555dc	ci(test): split integration into per-backend jobs Add separate `integration-docker` and `integration-firecracker` jobs, each with an explicit BOT_BOTTLE_BACKEND env var, so the backend used is visible in CI output and skipped backends surface as a distinct job rather than silent unittest.skip lines. - integration-docker: ubuntu-latest, BOT_BOTTLE_BACKEND=docker - integration-firecracker: [self-hosted, kvm], BOT_BOTTLE_BACKEND=firecracker, same-repo PRs + push + workflow_dispatch only (untrusted fork PRs do not execute on the privileged KVM runner) - coverage: same same-repo restriction; refs #414 for the planned follow-up that moves coverage to ubuntu-latest via artifact combination Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-07-18 22:08:43 -04:00
didericis-claude	fee0a66007	test(integration): lift GITEA_ACTIONS skip for Firecracker backend The sandbox-escape test was unconditionally skipped when GITEA_ACTIONS=true, which prevented Firecracker orchestration coverage from being measured even when BOT_BOTTLE_BACKEND=firecracker is set on the KVM runner. Narrow the skip to: GITEA_ACTIONS=true AND BOT_BOTTLE_BACKEND != firecracker. When BOT_BOTTLE_BACKEND=firecracker the test is explicitly opted in to run on the self-hosted KVM runner where the required /dev/kvm + TAP pool exist. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-07-18 22:08:43 -04:00
didericis-claude	ea41d306d8	ci(coverage): address review findings from PR #349 - Finding 1: set BOT_BOTTLE_BACKEND=firecracker on the coverage step so the integration suite actually exercises the Firecracker orchestration paths rather than defaulting to Docker - Finding 2: restrict the coverage job to push+workflow_dispatch only; PR-controlled code no longer executes on the privileged KVM runner automatically — maintainers trigger workflow_dispatch for trusted PRs - Finding 3: expand path filters to include workflow files, scripts, and README so changes to CI configuration trigger the workflow itself Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-07-18 22:08:43 -04:00
didericis-claude	17daa1c4f7	ci(coverage): install dev requirements on the KVM runner The self-hosted KVM runner is a persistent machine, so --break-system-packages is inappropriate. Use --user instead so coverage (and pyright/pylint for future jobs) land in ~/.local and survive between runs without touching the system Python. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-07-18 22:08:43 -04:00
didericis	acf9fb4d46	ci(coverage): run the diff-coverage gate on a self-hosted KVM runner Re-land the coverage gate deferred from #343. The Firecracker VM/SSH orchestration (~230 lines) is only exercised by the integration suite, which needs /dev/kvm + the provisioned TAP/nft pool — a container runner skips it and those lines read uncovered, so the 90% diff gate can't pass on ubuntu-latest. Move the `coverage` job to a self-hosted `kvm` runner with a firecracker-readiness preflight (binary + /dev/kvm + `backend status`) so the integration test actually runs. Unit/lint stay on ubuntu-latest. README documents the runner prerequisites. Depends on a registered self-hosted runner labelled `kvm`; until one is provisioned this gate will not run. See PRD 0069 / #348. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WBMWTEtQdJ4W5UrWuLHCck	2026-07-18 22:08:43 -04:00