feat(macos): replace rootless Docker spike with rootless podman

Podman avoids the CAP_SYS_ADMIN requirement that makes rootless Docker
impossible here: with no subordinate UID range configured it falls back
to a single-UID self-mapping, which an unprivileged process may write
itself, so newuidmap is never invoked. The image build therefore strips
/etc/subuid and /etc/subgid entries rather than adding them.

The agent-facing surface is unchanged — docker and docker compose talk
to podman's Docker-compatible API socket.

Two device nodes need relaxing as root inside the bottle (0666 on
/dev/fuse and /dev/net/tun); both already exist and neither needs a
capability the bottle lacks, unlike CAP_SYS_ADMIN.

Verified live on macOS 26 / Apple Container 1.0.0: service starts with
zero added capabilities, compose pulls and serves from the workspace on
a published port, and a nested container cannot reach the network
outside the egress path.

Known limitation, not yet addressed: the agent base image is Debian
bookworm, whose podman 4.3.1 swallows container exit codes through the
compat API (docker run returns 0 regardless). podman 5.4.2 on trixie
fixes it; the base bump is a separate PR. The acceptance test asserts
on an in-band marker rather than an exit code so it cannot false-pass
in the meantime.

Nested containers give no isolation from the agent itself — root inside
one is the agent user outside it. They are a build/test convenience;
the bottle remains the security boundary.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GnMp8SUGH57hZX7192Rv2F

.gitea/workflows/test.yml

@@ -25,15 +25,68 @@ 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:
+  stage-firecracker-inputs:
+    runs-on: [self-hosted, kvm]
+    # Same guard as the other KVM-runner jobs: don't spin the privileged
+    # runner for fork PRs (this only copies a non-secret static binary, but
+    # keep the posture consistent — build-infra/integration/coverage all
+    # depend on it, so gating here gates the whole Firecracker chain).
+    if: >-
+      github.event_name == 'push' ||
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'pull_request' &&
+       github.event.pull_request.head.repo.full_name == github.repository)
+    steps:
+      - name: Stage the provisioned static dropbear
+        run: |
+          mkdir -p firecracker-inputs
+          cp /var/cache/bot-bottle-fc/dropbear firecracker-inputs/dropbear
+
+      - name: Upload Firecracker build inputs
+        uses: actions/upload-artifact@v3
+        with:
+          name: firecracker-inputs
+          path: firecracker-inputs/
+
+  build-infra:
+    needs: stage-firecracker-inputs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download Firecracker build inputs
+        uses: actions/download-artifact@v3
+        with:
+          name: firecracker-inputs
+          path: firecracker-inputs
+
+      - name: Build infra candidate from this checkout
+        env:
+          BOT_BOTTLE_FC_DROPBEAR: ${{ github.workspace }}/firecracker-inputs/dropbear
+        run: python3 -m bot_bottle.backend.firecracker.publish_infra --output infra-candidate
+
+      - name: Upload infra candidate
+        uses: actions/upload-artifact@v3
+        with:
+          name: infra-candidate
+          path: infra-candidate/
+
   unit:
     runs-on: ubuntu-latest
     steps:
@@ -83,9 +136,10 @@ 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, Docker, cached kernel +
+  # `firecracker` on PATH, `/dev/kvm` accessible, cached kernel +
   # static dropbear, and the pool as a persistent systemd unit.
   integration-firecracker:
+    needs: build-infra
     runs-on: [self-hosted, kvm]
     if: >-
       github.event_name == 'push' ||
@@ -105,6 +159,15 @@ jobs:
           # range overlap; it prints the exact `backend setup` fix.
           python3 cli.py backend status --backend=firecracker
 
+      - name: Download the candidate built from this checkout
+        uses: actions/download-artifact@v3
+        with:
+          name: infra-candidate
+          path: 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: 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
@@ -112,6 +175,7 @@ jobs:
       - name: Run integration tests (firecracker)
         env:
           BOT_BOTTLE_BACKEND: firecracker
+          BOT_BOTTLE_INFRA_ARTIFACT_DIR: ${{ github.workspace }}/infra-candidate
         run: python3 -m unittest discover -t . -s tests/integration -v
 
   # Combined unit+integration coverage + the diff-coverage gate (the hard
@@ -130,7 +194,12 @@ jobs:
   #
   # See #414 for the planned follow-up: artifact-based coverage combination
   # (run tests once in their respective jobs, combine .coverage files here).
+  #
+  # build-infra creates one candidate from the checkout. This job boots that
+  # same candidate after integration-firecracker has exercised it; the main
+  # push path publishes the identical bytes only after every required job.
   coverage:
+    needs: [build-infra, integration-firecracker]
     timeout-minutes: 15
     runs-on: [self-hosted, kvm]
     if: >-
@@ -153,14 +222,52 @@ jobs:
           # range overlap; it prints the exact `backend setup` fix.
           python3 cli.py backend status --backend=firecracker
 
+      - name: Download the candidate already exercised by integration
+        uses: actions/download-artifact@v3
+        with:
+          name: infra-candidate
+          path: infra-candidate
+
       # 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)
+        env:
+          BOT_BOTTLE_CI_INFRA_ARTIFACT_DIR: ${{ github.workspace }}/infra-candidate
         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: [stage-firecracker-inputs, build-infra, 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 candidate
+        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. Stage the SAME dropbear build-infra used, or the recheck
+      # computes a "<missing>"-dropbear version and rejects the candidate.
+      - name: Download the staged dropbear (matches build-infra'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

Dockerfile.gateway

@@ -98,6 +98,9 @@ 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
@@ -117,8 +120,6 @@ 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"]

README.md

@@ -75,6 +75,22 @@ On compatible macOS hosts, the default backend requires Apple's `container` CLI
 
 Use `BOT_BOTTLE_BACKEND=docker ./cli.py start <agent>` on hosts where neither Apple Container nor KVM is available and Docker is the desired backend.
 
+> **Experimental containers-in-bottle spike (#392):** a bottle may set
+> `docker_access: true`. On the macOS backend this starts a guest-local,
+> rootless **podman** service after the bottle is registered, exposing its
+> Docker-compatible API socket — the agent still uses `docker` and `docker
+> compose`. It does not mount Docker Desktop's socket or add outer VM
+> capabilities. Rootless Docker was tried first and does not work here at
+> all: Apple Container's capability bounding set omits `CAP_SYS_ADMIN`,
+> which the kernel requires to write a multi-range `uid_map`. See
+> [`docs/research/rootless-docker-in-apple-container-spike.md`](docs/research/rootless-docker-in-apple-container-spike.md).
+>
+> The tradeoff to understand before enabling it: podman avoids that
+> requirement by falling back to a single-UID mapping, so nested containers
+> provide **no isolation from the agent itself** — `root` inside a nested
+> container is the agent user outside it. Nested containers are a build/test
+> convenience, not a security boundary. The bottle remains the boundary.
+
 ### Firecracker on Linux
 
 On Linux, a KVM-capable host defaults to the Firecracker backend. It needs:
@@ -90,7 +106,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`, 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`.
+> **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`.
 
 ```sh
 ./cli.py start <agent>   # builds the image on first run, drops you into claude

bot_bottle/backend/__init__.py

@@ -45,7 +45,8 @@ 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
+from ..log import die, info, warn
+from ..util import read_tty_line
 from ..manifest import Manifest, ManifestIndex
 from ..supervise import SupervisePlan
 from ..util import expand_tilde
@@ -648,19 +649,26 @@ 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 (CLI `--backend=<name>` passes through here)
+      1. explicit arg (e.g. resume passes the recorded backend name)
       2. BOT_BOTTLE_BACKEND env var
-      3. `macos-container` on compatible macOS hosts
-      4. `firecracker` on KVM-capable Linux hosts
-      5. default `docker`
+      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.
 
     Dies with a pointer at the known backends if the chosen name
     isn't implemented."""
-    resolved = name or os.environ.get("BOT_BOTTLE_BACKEND") or _default_backend_name()
+    resolved = name or os.environ.get("BOT_BOTTLE_BACKEND")
+    if resolved is None:
+        resolved = _auto_select_backend(prompt=prompt)
     backends = _get_backends()
     if resolved not in backends:
         known = ", ".join(sorted(backends))
@@ -668,7 +676,35 @@ def get_bottle_backend(
     return backends[resolved]
 
 
-def _default_backend_name() -> str:
+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 -----------------------------------------
     if has_backend("macos-container"):
         return "macos-container"
     # A KVM-capable Linux host defaults to firecracker even when the
@@ -678,7 +714,37 @@ def _default_backend_name() -> str:
     from .firecracker import FirecrackerBottleBackend
     if FirecrackerBottleBackend.is_host_capable():
         return "firecracker"
-    return "docker"
+
+    # --- 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")
 
 
 def known_backend_names() -> tuple[str, ...]:

bot_bottle/backend/docker/consolidated_launch.py

@@ -142,11 +142,19 @@ def launch_consolidated(
 
 
 def teardown_consolidated(
-    bottle_id: str, *, orchestrator_url: str, gateway_name: str = GATEWAY_NAME,
+    bottle_id: str,
+    *,
+    orchestrator_url: str,
+    gateway_name: str = GATEWAY_NAME,
+    timeout: float | None = None,
 ) -> None:
     """Deregister the bottle and remove its git-gate state from the gateway.
     Both steps are idempotent so this is safe from a cleanup trap."""
-    OrchestratorClient(orchestrator_url).teardown_bottle(bottle_id)
+    from ...orchestrator.config_store import DEFAULT_TEARDOWN_TIMEOUT_SECONDS
+    OrchestratorClient(
+        orchestrator_url,
+        timeout=timeout if timeout is not None else DEFAULT_TEARDOWN_TIMEOUT_SECONDS,
+    ).teardown_bottle(bottle_id)
     deprovision_git_gate(DockerGatewayTransport(gateway_name), bottle_id)
 
 

bot_bottle/backend/docker/launch.py

@@ -62,6 +62,7 @@ from .compose import (
     write_compose_file,
 )
 from .consolidated_compose import consolidated_agent_compose
+from ...orchestrator.config_store import resolve_teardown_timeout
 from .consolidated_launch import launch_consolidated, teardown_consolidated
 from ...orchestrator.gateway import DockerGateway
 
@@ -133,11 +134,14 @@ def launch(
         token_values = egress_resolve_token_values(
             plan.egress_plan.token_env_map, effective_env,
         )
+        teardown_timeout = resolve_teardown_timeout()
         ctx = launch_consolidated(
             plan.egress_plan, git_gate_plan, image_ref=plan.image, tokens=token_values,
         )
         stack.callback(
-            teardown_consolidated, ctx.bottle_id, orchestrator_url=ctx.orchestrator_url,
+            teardown_consolidated, ctx.bottle_id,
+            orchestrator_url=ctx.orchestrator_url,
+            timeout=teardown_timeout,
         )
 
         # Step 4: install the SHARED gateway CA into the agent (replaces the

bot_bottle/backend/firecracker/consolidated_launch.py

@@ -91,12 +91,18 @@ def launch_consolidated(
     )
 
 
-def teardown_consolidated(bottle_id: str, *, orchestrator_url: str) -> None:
+def teardown_consolidated(
+    bottle_id: str, *, orchestrator_url: str, timeout: float | None = None,
+) -> None:
     """Deregister the bottle and remove its git-gate state from the gateway
     VM. Both steps are idempotent so this is safe from a cleanup trap. Does
     NOT stop the infra VM — it's a persistent per-host singleton shared by
     every bottle."""
-    OrchestratorClient(orchestrator_url).teardown_bottle(bottle_id)
+    from ...orchestrator.config_store import DEFAULT_TEARDOWN_TIMEOUT_SECONDS
+    OrchestratorClient(
+        orchestrator_url,
+        timeout=timeout if timeout is not None else DEFAULT_TEARDOWN_TIMEOUT_SECONDS,
+    ).teardown_bottle(bottle_id)
     deprovision_git_gate(infra_vm.gateway_transport(), bottle_id)
 
 

bot_bottle/backend/firecracker/image_builder.py

@@ -38,25 +38,39 @@ _BUILD_TIMEOUT_SECONDS = 900.0
 
 
 def _dockerfile_hash(dockerfile: Path) -> str:
-    """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
+    """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
     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,
-    so a repeat launch skips the rebuild.
+    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.
 
     `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 = _dockerfile_hash(dockerfile)
+    digest = _rootfs_digest(dockerfile)
     base = util.cache_dir() / "rootfs" / f"agent-{digest}"
     if (base / ".bb-ready").is_file():
         info(f"using cached agent rootfs {base.name}")

bot_bottle/backend/firecracker/infra_artifact.py

@@ -85,6 +85,11 @@ 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]
@@ -111,6 +116,7 @@ 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:
@@ -160,6 +166,33 @@ 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

bot_bottle/backend/firecracker/infra_vm.py

@@ -161,20 +161,23 @@ def ensure_running() -> InfraVm:
     slot = netpool.orch_slot()
     url = f"http://{slot.guest_ip}:{CONTROL_PLANE_PORT}"
     key = _infra_dir() / "id_ed25519"
-    if key.exists() and _health_ok(url):
+    want = _expected_version()
+    if _adoptable(key, url, want):
         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 key.exists() and _health_ok(url):
+        if _adoptable(key, url, want):
             info(f"adopting running infra VM at {url}")
             return InfraVm(guest_ip=slot.guest_ip, private_key=key)
-        stop()  # clear a stale/hung VM holding the link before booting fresh
+        # Clear a stale/hung/OUTDATED VM holding the link before booting fresh.
+        stop()
         ensure_built()
         infra = boot()
         wait_for_health(infra)
+        _record_booted_version(want)
         return infra
 
 
@@ -193,9 +196,15 @@ def _singleton_lock() -> Generator[None, None, None]:
 
 
 def stop() -> None:
-    """Stop the infra VM singleton (idempotent — absent is success)."""
+    """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."""
     _kill_pidfile()
+    _kill_infra_firecrackers()
     _pid_file().unlink(missing_ok=True)
+    _version_file().unlink(missing_ok=True)
 
 
 def boot() -> InfraVm:
@@ -238,6 +247,36 @@ 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
@@ -309,6 +348,28 @@ 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:
@@ -433,7 +494,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 /app/gateway_init.py &
+    python3 -m bot_bottle.gateway_init &
 
 # Reap as PID 1; children are backgrounded, so `wait` blocks.
 while : ; do wait ; done

bot_bottle/backend/firecracker/launch.py

@@ -52,6 +52,7 @@ from ..util import AGENT_CA_BUNDLE, AGENT_CA_PATH
 from . import firecracker_vm, image_builder, isolation_probe, netpool, util
 from .bottle import FirecrackerBottle
 from .bottle_plan import FirecrackerBottlePlan
+from ...orchestrator.config_store import resolve_teardown_timeout
 from .consolidated_launch import (
     launch_consolidated,
     teardown_consolidated,
@@ -112,6 +113,7 @@ def launch(
         token_values = egress_resolve_token_values(
             plan.egress_plan.token_env_map, effective_env,
         )
+        teardown_timeout = resolve_teardown_timeout()
         ctx = launch_consolidated(
             plan.egress_plan, git_gate_plan,
             guest_ip=slot.guest_ip,
@@ -121,6 +123,7 @@ def launch(
         stack.callback(
             teardown_consolidated, ctx.bottle_id,
             orchestrator_url=ctx.orchestrator_url,
+            timeout=teardown_timeout,
         )
 
         # Step 5: install the SHARED gateway CA (replaces the per-bottle CA).

bot_bottle/backend/firecracker/publish_infra.py

@@ -11,7 +11,8 @@ 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 [--dry-run] [--force]
+  python3 -m bot_bottle.backend.firecracker.publish_infra --output DIR
+  python3 -m bot_bottle.backend.firecracker.publish_infra --publish-dir DIR
 
 Auth: a token with `write:package` on the target owner, from
 `BOT_BOTTLE_INFRA_ARTIFACT_TOKEN`.
@@ -24,7 +25,6 @@ import gzip
 import hashlib
 import shutil
 import sys
-import tempfile
 import urllib.error
 import urllib.request
 from pathlib import Path
@@ -131,36 +131,79 @@ 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.")
-    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")
+    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")
     args = parser.parse_args(argv)
 
     _, _, token = infra_artifact._config()
-    if not args.dry_run and not token:
+    if args.publish_dir is not None and not token:
         raise SystemExit(
             "no publish token: set BOT_BOTTLE_INFRA_ARTIFACT_TOKEN to a token "
             "with write:package")
 
-    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
+    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)
     print(f"published infra rootfs {version}")
     return 0
 

bot_bottle/backend/firecracker/util.py

@@ -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 --backend=macos-container.")
+            "On macOS use the macos-container backend.")
     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,6 +368,11 @@ 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

bot_bottle/backend/macos_container/bottle.py

@@ -68,9 +68,14 @@ 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` wins
-        # over the run-time value, so the token-bearing proxy URL set here
-        # supersedes the token-less one baked in at launch.
+        # 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`.
         self._exec_env = dict(exec_env or {})
         self._closed = False
 

bot_bottle/backend/macos_container/bottle_plan.py

@@ -20,6 +20,7 @@ class MacosContainerBottlePlan(BottlePlan):
     # bottle is registered. See launch.py's stamp for why it lives here and not
     # only in the exec-time proxy env.
     identity_token: str = ""
+    docker_access: bool = False
 
     @property
     def container_name(self) -> str:

bot_bottle/backend/macos_container/consolidated_launch.py

@@ -36,9 +36,12 @@ from dataclasses import dataclass
 
 from ...egress import EgressPlan
 from ...git_gate import GitGatePlan
-from ...orchestrator.client import OrchestratorClient
+from ...log import info
+from ...orchestrator.client import OrchestratorClient, OrchestratorClientError
 from ...orchestrator.registration import registration_inputs
 from ..docker.gateway_provision import deprovision_git_gate, provision_git_gate
+from . import util as container_mod
+from .enumerate import CONTAINER_NAME_PREFIX, EnumerationError, enumerate_active
 from .gateway import GATEWAY_NETWORK
 from .gateway_provision import AppleGatewayTransport
 from .infra import MacosInfraService, OrchestratorStartError
@@ -89,6 +92,32 @@ def ensure_gateway(
     )
 
 
+def live_source_ips(network: str) -> list[str]:
+    """Every running agent container's address on `network`.
+
+    The reconciliation input: the orchestrator lives inside the infra
+    container and cannot enumerate the host's containers, so the host has to
+    tell it which bottles are actually up. Containers that have not been
+    assigned an address yet contribute nothing — the reap's grace window, not
+    this list, is what protects an in-flight launch.
+
+    Raises `EnumerationError` when the live set cannot be determined
+    authoritatively: either the container listing fails or any individual
+    inspect fails. Callers must skip reconciliation in that case to avoid
+    unregistering healthy bottles."""
+    ips: list[str] = []
+    for agent in enumerate_active():
+        name = f"{CONTAINER_NAME_PREFIX}{agent.slug}"
+        ip = container_mod.inspect_container_network_ip(name, network)
+        if ip is None:
+            raise EnumerationError(
+                f"container inspect {name!r} failed; live set is not authoritative"
+            )
+        if ip:
+            ips.append(ip)
+    return ips
+
+
 def register_agent(
     egress_plan: EgressPlan,
     git_gate_plan: GitGatePlan,
@@ -103,6 +132,16 @@ def register_agent(
     container — it is the attribution key the gateway resolves policy by.
     Raises on failure; the caller tears down."""
     client = OrchestratorClient(endpoint.orchestrator_url)
+    # Self-heal before registering: a launcher that died hard (SIGKILL, closed
+    # terminal, host sleep) never ran its teardown callback, leaving an active
+    # row with no container. vmnet recycles addresses, so such a row can
+    # collide with this bottle's — and `by_source_ip` fail-closes on ambiguity,
+    # which would resolve no policy at all and deny every host. Best-effort: a
+    # reconciliation failure must not block an otherwise-fine launch.
+    try:
+        client.reconcile(live_source_ips(endpoint.network))
+    except (OrchestratorClientError, EnumerationError) as e:
+        info(f"registry reconciliation skipped: {e}")
     inputs = registration_inputs(egress_plan)
     reg = client.register_bottle(
         source_ip, image_ref=image_ref, policy=inputs.policy,
@@ -124,11 +163,17 @@ def register_agent(
     )
 
 
-def teardown_consolidated(bottle_id: str, *, orchestrator_url: str) -> None:
+def teardown_consolidated(
+    bottle_id: str, *, orchestrator_url: str, timeout: float | None = None,
+) -> None:
     """Deregister the bottle and remove its git-gate state from the gateway.
     Both steps are idempotent so this is safe from a cleanup trap. Does NOT
     stop the gateway — it's a persistent per-host singleton."""
-    OrchestratorClient(orchestrator_url).teardown_bottle(bottle_id)
+    from ...orchestrator.config_store import DEFAULT_TEARDOWN_TIMEOUT_SECONDS
+    OrchestratorClient(
+        orchestrator_url,
+        timeout=timeout if timeout is not None else DEFAULT_TEARDOWN_TIMEOUT_SECONDS,
+    ).teardown_bottle(bottle_id)
     deprovision_git_gate(AppleGatewayTransport(), bottle_id)
 
 
@@ -136,6 +181,7 @@ __all__ = [
     "GatewayEndpoint",
     "LaunchContext",
     "ensure_gateway",
+    "live_source_ips",
     "register_agent",
     "teardown_consolidated",
     "ConsolidatedLaunchError",

bot_bottle/backend/macos_container/enumerate.py

@@ -8,13 +8,21 @@ from ...bottle_state import read_metadata
 from .. import ActiveAgent
 from .infra import INFRA_NAME
 
-_PREFIX = "bot-bottle-"
+# 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-"
 # 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.
 _INFRA_NAMES = frozenset({INFRA_NAME})
 
 
+class EnumerationError(RuntimeError):
+    """container list failed; the resulting live set is not authoritative."""
+
+
 def enumerate_active() -> list[ActiveAgent]:
     result = subprocess.run(
         ["container", "list", "--quiet"],
@@ -23,12 +31,15 @@ def enumerate_active() -> list[ActiveAgent]:
         check=False,
     )
     if result.returncode != 0:
-        return []
+        raise EnumerationError(
+            f"container list failed: "
+            f"{(result.stderr or '').strip() or '<no stderr>'}"
+        )
     out: list[ActiveAgent] = []
     for name in sorted(line.strip() for line in result.stdout.splitlines()):
-        if not name.startswith(_PREFIX) or name in _INFRA_NAMES:
+        if not name.startswith(CONTAINER_NAME_PREFIX) or name in _INFRA_NAMES:
             continue
-        slug = name[len(_PREFIX):]
+        slug = name[len(CONTAINER_NAME_PREFIX):]
         metadata = read_metadata(slug)
         out.append(ActiveAgent(
             backend_name="macos-container",

bot_bottle/backend/macos_container/gateway_hosts.py

@@ -0,0 +1,96 @@
+"""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"]

bot_bottle/backend/macos_container/infra.py

@@ -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 /app/gateway_init.py ) &\n"
+        f"SUPERVISE_DB_PATH={_DB_PATH_IN_CONTAINER} python3 -m bot_bottle.gateway_init ) &\n"
         "while : ; do wait ; done\n"
     )
 

bot_bottle/backend/macos_container/launch.py

@@ -59,7 +59,14 @@ 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 . import rootless_podman
 from .bottle_plan import MacosContainerBottlePlan
+from ...orchestrator.config_store import resolve_teardown_timeout
 from .consolidated_launch import (
     GatewayEndpoint,
     ensure_gateway,
@@ -100,6 +107,11 @@ 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.
@@ -117,6 +129,9 @@ 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,
         )
@@ -129,6 +144,7 @@ def launch(
         token_values = egress_resolve_token_values(
             plan.egress_plan.token_env_map, effective_env,
         )
+        teardown_timeout = resolve_teardown_timeout()
         ctx = register_agent(
             plan.egress_plan,
             plan.git_gate_plan,
@@ -140,6 +156,7 @@ def launch(
         stack.callback(
             teardown_consolidated, ctx.bottle_id,
             orchestrator_url=ctx.orchestrator_url,
+            timeout=teardown_timeout,
         )
         info(
             f"agent {plan.container_name} registered "
@@ -155,6 +172,10 @@ def launch(
         # token above, so — unlike the run-time env — the plan CAN carry it.
         plan = dataclasses.replace(plan, identity_token=ctx.identity_token)
 
+        exec_env = {
+            **_identity_proxy_env(endpoint, ctx.identity_token),
+            **rootless_podman.guest_env(plan.docker_access),
+        }
         bottle = MacosContainerBottle(
             plan.container_name,
             teardown,
@@ -168,10 +189,16 @@ def launch(
             ),
             terminal_color=plan.spec.color,
             agent_workdir=plan.workspace_plan.workdir,
-            exec_env=_identity_proxy_env(endpoint, ctx.identity_token),
+            exec_env=exec_env,
         )
         bottle.prompt_path = provision(plan, bottle)
 
+        if plan.docker_access:
+            rootless_podman.prepare_guest_devices(
+                plan.container_name, container_mod.exec_container_as_root,
+            )
+            rootless_podman.start(bottle)
+
         yield bottle
     finally:
         teardown()
@@ -183,15 +210,22 @@ def _build_images(plan: MacosContainerBottlePlan) -> MacosContainerBottlePlan:
     committed = read_committed_image(plan.slug)
     if committed and container_mod.image_exists(committed):
         info(f"using committed image {committed!r}")
-        return dataclasses.replace(
+        plan = dataclasses.replace(
             plan,
             agent_provision=dataclasses.replace(
                 plan.agent_provision, image=committed,
             ),
         )
-    container_mod.build_image(
-        plan.image, _REPO_DIR, dockerfile=plan.dockerfile_path,
-    )
+    else:
+        container_mod.build_image(
+            plan.image, _REPO_DIR, dockerfile=plan.dockerfile_path,
+        )
+    if plan.docker_access:
+        image = rootless_podman.build_image(plan.image, container_mod.build_image)
+        plan = dataclasses.replace(
+            plan,
+            agent_provision=dataclasses.replace(plan.agent_provision, image=image),
+        )
     return plan
 
 
@@ -231,13 +265,20 @@ 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 address)."""
+    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
     git_gate_url = (
-        f"http://{endpoint.gateway_ip}:{_GIT_HTTP_PORT}"
+        f"http://{GATEWAY_HOSTNAME}:{_GIT_HTTP_PORT}"
         if plan.git_gate_plan.upstreams else ""
     )
     supervise_url = (
-        f"http://{endpoint.gateway_ip}:{SUPERVISE_PORT}/"
+        f"http://{GATEWAY_HOSTNAME}:{SUPERVISE_PORT}/"
         if plan.supervise_plan is not None else ""
     )
     return dataclasses.replace(
@@ -247,30 +288,43 @@ def _stamp_agent_urls(
     )
 
 
-def _proxy_url(gateway_ip: str, identity_token: str = "") -> str:
+def _proxy_url(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)."""
+    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."""
     cred = f"bottle:{identity_token}@" if identity_token else ""
-    return f"http://{cred}{gateway_ip}:{EGRESS_PORT}"
+    return f"http://{cred}{GATEWAY_HOSTNAME}:{EGRESS_PORT}"
 
 
-def _no_proxy(gateway_ip: str) -> str:
+def _no_proxy() -> str:
     # git-http + supervise live on the gateway and must NOT go through the
-    # egress proxy — the agent reaches them directly by its address.
-    return f"localhost,127.0.0.1,{gateway_ip}"
+    # 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}"
 
 
 def _identity_proxy_env(
     endpoint: GatewayEndpoint, identity_token: str,
 ) -> dict[str, str]:
-    """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."""
+    """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`."""
     if not identity_token:
         return {}
-    url = _proxy_url(endpoint.gateway_ip, identity_token)
+    del endpoint  # the gateway is named, not addressed
+    url = _proxy_url(identity_token)
     return {
         "HTTPS_PROXY": url, "HTTP_PROXY": url,
         "https_proxy": url, "http_proxy": url,
@@ -317,16 +371,23 @@ def _agent_run_argv(
 def _agent_env_entries(
     plan: MacosContainerBottlePlan, endpoint: GatewayEndpoint,
 ) -> tuple[str, ...]:
-    # 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)
+    # 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()
     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}",

bot_bottle/backend/macos_container/resolve_plan.py

@@ -44,4 +44,5 @@ def resolve_plan(
         egress_plan=egress_plan,
         supervise_plan=supervise_plan,
         agent_provision=agent_provision_plan,
+        docker_access=manifest.bottle.docker_access,
     )

bot_bottle/backend/macos_container/rootless-podman-init.sh

@@ -0,0 +1,89 @@
+#!/bin/sh
+set -eu
+
+uid="$(id -u)"
+if [ "$uid" -eq 0 ]; then
+    echo "refusing to run rootless podman as root" >&2
+    exit 1
+fi
+
+for command in podman docker fuse-overlayfs slirp4netns; do
+    command -v "$command" >/dev/null 2>&1 || {
+        echo "missing rootless podman prerequisite: $command" >&2
+        exit 1
+    }
+done
+
+# The inverse of the rootless-Docker check, and the whole point of the podman
+# variant: a subordinate range would push podman onto newuidmap, which cannot
+# write a multi-range uid_map without CAP_SYS_ADMIN in this guest.  An empty
+# range keeps it on the single-UID self-mapping an unprivileged process may
+# write itself.
+if grep -q "^$(id -un):" /etc/subuid 2>/dev/null; then
+    echo "unexpected subordinate UID range for $(id -un): podman would" >&2
+    echo "require CAP_SYS_ADMIN via newuidmap in this guest" >&2
+    exit 1
+fi
+
+for device in /dev/fuse /dev/net/tun; do
+    [ -r "$device" ] && [ -w "$device" ] || {
+        echo "device $device is not readable/writable by $(id -un)" >&2
+        exit 1
+    }
+done
+
+export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/tmp/bot-bottle-podman-run}"
+config="$HOME/.config/containers"
+mkdir -p "$XDG_RUNTIME_DIR" "$config"
+chmod 700 "$XDG_RUNTIME_DIR"
+
+# ignore_chown_errors is required, not incidental: with a single-UID mapping
+# there is no second UID for image layers to be chowned to, so layers that
+# record other owners would otherwise fail to extract.
+cat > "$config/storage.conf" <<'CONF'
+[storage]
+driver="overlay"
+[storage.options.overlay]
+mount_program="/usr/bin/fuse-overlayfs"
+ignore_chown_errors="true"
+CONF
+
+# No cgroup delegation reaches this guest, so asking podman to manage cgroups
+# fails; events_logger=file avoids the journald socket that is equally absent.
+cat > "$config/containers.conf" <<'CONF'
+[containers]
+cgroups="disabled"
+[engine]
+cgroup_manager="cgroupfs"
+events_logger="file"
+CONF
+
+# Registry pulls egress through the bottle's proxy like everything else. The
+# token-bearing proxy URL is already in the agent's environment; persisting it
+# inside this disposable VM does not broaden its authority.
+python3 - <<'PY'
+import json
+import os
+from pathlib import Path
+
+proxy = os.environ.get("HTTPS_PROXY") or os.environ.get("https_proxy", "")
+no_proxy = os.environ.get("NO_PROXY") or os.environ.get("no_proxy", "")
+config = {"proxies": {"default": {
+    "httpProxy": proxy,
+    "httpsProxy": proxy,
+    "noProxy": no_proxy,
+}}}
+path = Path.home() / ".docker" / "config.json"
+path.parent.mkdir(parents=True, exist_ok=True)
+path.write_text(json.dumps(config), encoding="utf-8")
+path.chmod(0o600)
+PY
+
+if docker info >/dev/null 2>&1; then
+    exit 0
+fi
+
+log=/tmp/bot-bottle-rootless-podman.log
+nohup podman system service --time=0 \
+    "unix://$XDG_RUNTIME_DIR/podman.sock" \
+    >"$log" 2>&1 </dev/null &

bot_bottle/backend/macos_container/rootless_podman.py

@@ -0,0 +1,132 @@
+"""Experimental rootless podman bootstrap for Apple-container bottles.
+
+The service and every nested container remain inside the existing per-bottle
+VM.  This module refuses to compensate for missing prerequisites with outer
+capabilities, a privileged container, or a host Docker socket.
+
+Podman is used rather than rootless Docker for one specific reason: Apple
+Container's capability bounding set omits `CAP_SYS_ADMIN`, which the kernel
+requires to write a multi-range `uid_map` via `newuidmap`.  Rootless Docker
+has no path that avoids that write.  Podman does — with no subordinate UID
+range configured it falls back to a single-UID self-mapping, which an
+unprivileged process may write itself.  See
+`docs/research/rootless-docker-in-apple-container-spike.md`.
+
+That fallback is why `build_image` *removes* the agent user's `/etc/subuid`
+and `/etc/subgid` entries instead of adding them: their presence is precisely
+what would send podman down the `newuidmap` path that cannot work here.
+
+The agent still talks to `docker` and `docker compose`; those speak to
+podman's Docker-compatible API socket, so nothing in the agent's habits
+changes.
+"""
+
+from __future__ import annotations
+
+import shlex
+import shutil
+import tempfile
+import time
+from pathlib import Path
+from typing import Callable
+
+from ...log import die, info
+
+_INIT = "/usr/local/libexec/bot-bottle/rootless-podman-init"
+_RUNTIME_DIR = "/tmp/bot-bottle-podman-run"
+_SOCKET = f"{_RUNTIME_DIR}/podman.sock"
+_LOG = "/tmp/bot-bottle-rootless-podman.log"
+READY_RETRIES = 30
+
+# Apple Container creates both device nodes 0600 root:root, so the agent user
+# cannot open them: /dev/fuse blocks the fuse-overlayfs storage driver and
+# /dev/net/tun blocks slirp4netns, which rootless podman uses for the default
+# bridge network that stock compose files expect.  Relaxing the modes needs no
+# capability the bottle does not already hold — unlike CAP_SYS_ADMIN, which is
+# what killed the rootless-Docker approach.
+_GUEST_DEVICES = ("/dev/fuse", "/dev/net/tun")
+
+
+def build_image(
+    base_image: str,
+    build: Callable[..., None],
+) -> str:
+    """Layer spike-only tooling on an already-built provider image."""
+    image = f"{base_image}-rootless-podman"
+    init_script = Path(__file__).with_name("rootless-podman-init.sh")
+    with tempfile.TemporaryDirectory(prefix="bot-bottle-rootless-podman.") as tmp:
+        context = Path(tmp)
+        shutil.copy2(init_script, context / "rootless-podman-init.sh")
+        (context / "Dockerfile").write_text(
+            "FROM docker:28-cli AS docker_cli\n"
+            f"FROM {base_image}\n"
+            "USER root\n"
+            "COPY --from=docker_cli /usr/local/bin/docker /usr/local/bin/docker\n"
+            "COPY --from=docker_cli /usr/local/libexec/docker/cli-plugins/"
+            "docker-compose /usr/local/libexec/docker/cli-plugins/docker-compose\n"
+            "RUN apt-get update \\\n"
+            " && apt-get install -y --no-install-recommends podman "
+            "fuse-overlayfs slirp4netns uidmap \\\n"
+            " && rm -rf /var/lib/apt/lists/* \\\n"
+            # Deliberate: an empty subordinate range keeps podman on the
+            # single-UID mapping that needs no CAP_SYS_ADMIN.  Adding ranges
+            # here would reintroduce the newuidmap failure this spike exists
+            # to route around.
+            " && sed -i '/^node:/d' /etc/subuid /etc/subgid\n"
+            "COPY rootless-podman-init.sh "
+            "/usr/local/libexec/bot-bottle/rootless-podman-init\n"
+            "RUN chmod 0755 /usr/local/libexec/bot-bottle/rootless-podman-init\n"
+            "USER node\n",
+            encoding="utf-8",
+        )
+        build(image, str(context), dockerfile=str(context / "Dockerfile"))
+    return image
+
+
+def guest_env(enabled: bool) -> dict[str, str]:
+    """Environment consumed by the Docker CLI inside an enabled bottle."""
+    if not enabled:
+        return {}
+    return {
+        "DOCKER_HOST": f"unix://{_SOCKET}",
+        "XDG_RUNTIME_DIR": _RUNTIME_DIR,
+    }
+
+
+def prepare_guest_devices(container_name: str, exec_as_root: Callable[..., None]) -> None:
+    """Make /dev/fuse and /dev/net/tun openable by the agent user.
+
+    Runs as root inside the bottle because the agent must not be able to
+    re-mode device nodes itself.  No outer capability is involved.
+    """
+    exec_as_root(
+        container_name,
+        ["sh", "-c", f"chmod 0666 {' '.join(_GUEST_DEVICES)}"],
+    )
+
+
+def start(bottle: object) -> None:
+    """Start and verify the unprivileged service through the bottle exec API."""
+    info("starting experimental rootless podman service")
+    result = bottle.exec(shlex.quote(_INIT))  # type: ignore[attr-defined]
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip()
+        die(f"rootless podman bootstrap failed: {detail or '<no output>'}")
+
+    for _ in range(READY_RETRIES):
+        result = bottle.exec("docker info >/dev/null 2>&1")  # type: ignore[attr-defined]
+        if result.returncode == 0:
+            info("rootless podman service is ready")
+            return
+        time.sleep(0.2)
+
+    logs = bottle.exec(  # type: ignore[attr-defined]
+        f"tail -n 80 {_LOG} 2>/dev/null || true"
+    )
+    die(
+        "rootless podman did not become ready without additional outer "
+        f"privileges:\n{(logs.stdout or logs.stderr or '<no log>').strip()}"
+    )
+
+
+__all__ = ["build_image", "guest_env", "prepare_guest_devices", "start"]

bot_bottle/backend/macos_container/util.py

@@ -360,6 +360,21 @@ 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,
@@ -557,6 +572,41 @@ def try_container_ipv4_on_network(name: str, network: str) -> str:
     return ""
 
 
+def inspect_container_network_ip(name: str, network: str) -> str | None:
+    """IP of `name` on `network`, distinguishing inspect failure from "not yet".
+
+    Returns:
+      - the IP string when the container has one on `network`
+      - "" when inspect succeeds but no address is assigned yet (in-flight DHCP)
+      - None when the inspect command itself fails (authoritative list impossible)
+    """
+    result = subprocess.run(
+        [_CONTAINER, "inspect", name],
+        capture_output=True, text=True, check=False,
+    )
+    if result.returncode != 0:
+        return None
+    try:
+        data = json.loads(result.stdout or "[]")
+    except json.JSONDecodeError:
+        return None
+    if isinstance(data, list):
+        data = data[0] if data else {}
+    if not isinstance(data, dict):
+        return None
+    status = data.get("status")
+    networks = status.get("networks") if isinstance(status, dict) else None
+    if not isinstance(networks, list):
+        return ""
+    for entry in networks:
+        if not isinstance(entry, dict) or entry.get("network") != network:
+            continue
+        raw = entry.get("ipv4Address")
+        if isinstance(raw, str) and raw:
+            return raw.split("/", 1)[0]
+    return ""
+
+
 def wait_container_ipv4_on_network(
     name: str, network: str, *, timeout: float = 15.0, poll: float = 0.25,
 ) -> str:

bot_bottle/cli/_common.py

@@ -3,18 +3,10 @@
 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")

bot_bottle/cli/cleanup.py

@@ -21,16 +21,20 @@ from __future__ import annotations
 
 import sys
 
-from ..backend import get_bottle_backend, known_backend_names
+from ..backend import get_bottle_backend, has_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.
+    # deterministic across runs. Skip backends whose runtime
+    # isn't available on this host so e.g. macos-container
+    # doesn't error on Linux.
     plans = [
-        (name, get_bottle_backend(name)) for name in known_backend_names()
+        (name, get_bottle_backend(name))
+        for name in known_backend_names()
+        if has_backend(name)
     ]
     prepared = [(name, b, b.prepare_cleanup()) for name, b in plans]
 

bot_bottle/cli/start.py

@@ -27,7 +27,6 @@ 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
@@ -57,15 +56,6 @@ 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",
@@ -115,11 +105,10 @@ 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, backend_name=backend_name
+            manifest, args, dry_run=dry_run
         )
 
     agent_name: str | None = args.name
@@ -170,7 +159,6 @@ def cmd_start(argv: list[str]) -> int:
     return _launch_bottle(
         spec,
         dry_run=dry_run,
-        backend_name=backend_name,
     )
 
 
@@ -182,7 +170,6 @@ def _start_headless(
     args: argparse.Namespace,
     *,
     dry_run: bool,
-    backend_name: str | None,
 ) -> int:
     """Non-interactive launch path for orchestrators / CI / webhooks.
 
@@ -230,7 +217,6 @@ def _start_headless(
     return _launch_bottle(
         spec,
         dry_run=dry_run,
-        backend_name=backend_name,
         assume_yes=True,
         headless_prompt_text=prompt,
     )
@@ -268,15 +254,18 @@ 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). The CLI
-    passes whatever `--backend` resolved to.
+    (`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).
 
     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)
+    backend = get_bottle_backend(backend_name, prompt=not spec.headless)
     plan = backend.prepare(spec, stage_dir=stage_dir)
     identity = _identity_from_plan(plan)
 

bot_bottle/egress_addon.py

@@ -379,6 +379,7 @@ class EgressAddon:
             env,
             request_method=flow.request.method,
             request_headers=req_headers,
+            deny_reason=config.deny_reason,
         )
 
         if decision.action == "block":

bot_bottle/egress_addon_core.py

@@ -89,6 +89,14 @@ LOG_FULL = 2    # log block/warn events + full request and response bodies
 class Config:
     routes: tuple[Route, ...]
     log: int = LOG_OFF
+    # Why this Config is a deny-all, when it is one for a reason *other* than
+    # the bottle's own policy genuinely not listing the host. A deny-all is
+    # indistinguishable from "policy loaded, host not allowed" at the decision
+    # point — both are simply "no matching route" — so without this the
+    # operator sees `host X is not in the allowlist` and goes hunting for a
+    # missing route that was never the problem. Empty for a normally-parsed
+    # policy; `decide` prefers it over the allowlist wording when set.
+    deny_reason: str = ""
 
 
 @dataclass(frozen=True)
@@ -405,16 +413,40 @@ class PolicyResolverLike(typing.Protocol):
         ...
 
 
+# Deny-all explanations. Each names the *actual* failure so an operator isn't
+# sent looking for a missing egress route when the bottle never had a policy
+# to begin with — the failure mode that made a bricked registration read like
+# a misconfigured allowlist.
+DENY_UNATTRIBUTED = (
+    "egress: this request was not attributed to any bottle, so no egress "
+    "policy applies and every host is denied. Either the bottle's registry "
+    "row is missing/ambiguous (torn down, or another bottle claimed its "
+    "source IP), or the request carried no matching identity token — check "
+    "that the caller's proxy URL includes it. This is not an allowlist problem."
+)
+DENY_UNPARSEABLE = (
+    "egress: this bottle's egress policy could not be parsed, so it is being "
+    "treated as deny-all. Fix the bottle's egress.routes; every host is denied "
+    "until it loads."
+)
+DENY_RESOLVER_ERROR = (
+    "egress: the orchestrator could not be reached to resolve this bottle's "
+    "egress policy, so every host is denied (fail-closed). Check that the "
+    "control plane is up; this is not an allowlist problem."
+)
+
+
 def _config_from_policy(policy: "str | None") -> "Config":
     """Parse a resolved policy blob into a Config, fail-closed: None / empty /
     unparseable all become a deny-all Config (no routes → every request
-    blocked)."""
+    blocked). Each deny-all carries the reason it is one, so the block message
+    names the real fault instead of blaming the allowlist."""
     if not policy:
-        return Config(routes=())  # unattributed or empty → deny-all
+        return Config(routes=(), deny_reason=DENY_UNATTRIBUTED)
     try:
         return load_config(policy)
     except ValueError:
-        return Config(routes=())  # unparseable policy → deny
+        return Config(routes=(), deny_reason=DENY_UNPARSEABLE)
 
 
 def resolve_client_config(
@@ -428,7 +460,7 @@ def resolve_client_config(
     try:
         policy = resolver.resolve(client_ip, identity_token)
     except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
-        return Config(routes=())  # orchestrator unreachable/errored → deny
+        return Config(routes=(), deny_reason=DENY_RESOLVER_ERROR)
     return _config_from_policy(policy)
 
 
@@ -457,7 +489,7 @@ def resolve_client_context(
             client_ip, identity_token,
         )
     except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
-        return Config(routes=()), "", {}  # orchestrator unreachable/errored → deny
+        return Config(routes=(), deny_reason=DENY_RESOLVER_ERROR), "", {}
     return _config_from_policy(policy), (bottle_id or ""), tokens
 
 
@@ -572,12 +604,16 @@ def decide(
     *,
     request_method: str = "GET",
     request_headers: typing.Mapping[str, str] | None = None,
+    deny_reason: str = "",
 ) -> Decision:
+    """`deny_reason` is `Config.deny_reason`: when the deny-all came from a
+    missing/unparseable policy rather than the bottle's own allowlist, report
+    that instead of implying a route is merely absent."""
     route = match_route(routes, request_host)
     if route is None:
         return Decision(
             action="block",
-            reason=(
+            reason=deny_reason or (
                 f"egress: host {request_host!r} is not in the "
                 f"bottle's egress.routes allowlist. Declare a "
                 f"route for it or remove the request."
@@ -852,6 +888,9 @@ __all__ = [
     "is_git_push_request",
     "is_git_fetch_request",
     "load_config",
+    "DENY_UNATTRIBUTED",
+    "DENY_UNPARSEABLE",
+    "DENY_RESOLVER_ERROR",
     "resolve_client_config",
     "resolve_client_context",
     "PolicyResolverLike",

bot_bottle/manifest_bottle.py

@@ -44,6 +44,9 @@ class ManifestBottle:
     # daemon that exposes egress MCP tools to the agent. Set
     # `supervise: false` to skip the gateway.
     supervise: bool = True
+    # Experimental guest-local container engine (issue #392). Backends must
+    # implement this without granting access to a host/shared daemon.
+    docker_access: bool = False
 
     @classmethod
     def from_dict(cls, name: str, raw: object) -> "ManifestBottle":
@@ -123,7 +126,15 @@ class ManifestBottle:
                 f"(was {type(supervise_raw).__name__})"
             )
 
+        docker_access_raw = d.get("docker_access", False)
+        if not isinstance(docker_access_raw, bool):
+            raise ManifestError(
+                f"bottle '{name}' docker_access must be a boolean "
+                f"(was {type(docker_access_raw).__name__})"
+            )
+
         return cls(
             env=env, agent_provider=agent_provider, git=git,
             git_user=git_user, egress=egress, supervise=supervise_raw,
+            docker_access=docker_access_raw,
         )

bot_bottle/manifest_extends.py

@@ -54,6 +54,7 @@ def _merge_two_bottles_runtime(base: "ManifestBottle", override: "ManifestBottle
         git_user=merged_git_user,
         egress=merged_egress,
         supervise=override.supervise,
+        docker_access=override.docker_access,
     )
 
 
@@ -206,6 +207,7 @@ def _fold_two_bottles(
         git_user=merged_git_user,
         egress=merged_egress,
         supervise=later.supervise,
+        docker_access=later.docker_access,
     ), merged_repos_raw
 
 
@@ -266,6 +268,11 @@ def _merge_bottles(
     merged_supervise = (
         child.supervise if "supervise" in child_raw else parent.supervise
     )
+    merged_docker_access = (
+        child.docker_access
+        if "docker_access" in child_raw
+        else parent.docker_access
+    )
     validate_egress_routes(name, merged_egress.routes)
 
     return ManifestBottle(
@@ -275,6 +282,7 @@ def _merge_bottles(
         git_user=merged_git_user,
         egress=merged_egress,
         supervise=merged_supervise,
+        docker_access=merged_docker_access,
     )
 
 

bot_bottle/manifest_schema.py

@@ -16,7 +16,10 @@ _FILENAME_RX = re.compile(r"^[a-z][a-z0-9-]*$")
 # sets dies with a "did you mean" pointer: typos should not silently
 # ghost into an empty config.
 BOTTLE_KEYS = frozenset(
-    {"env", "extends", "agent_provider", "git-gate", "egress", "supervise"}
+    {
+        "env", "extends", "agent_provider", "git-gate", "egress", "supervise",
+        "docker_access",
+    }
 )
 AGENT_KEYS_REQUIRED: frozenset[str] = frozenset()
 AGENT_KEYS_OPTIONAL = frozenset({"bottle", "skills", "git-gate"})

bot_bottle/orchestrator/client.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 import json
 import urllib.error
 import urllib.request
+from collections.abc import Iterable
 from dataclasses import dataclass
 
 from ..paths import host_control_plane_token
@@ -147,6 +148,20 @@ class OrchestratorClient:
             raise OrchestratorClientError(f"teardown {bottle_id}: HTTP {status}")
         return True
 
+    def reconcile(
+        self, live_source_ips: Iterable[str], *, grace_seconds: float | None = None,
+    ) -> list[str]:
+        """Drop registry rows for bottles that are no longer running
+        (`POST /reconcile`), returning the reaped bottle ids. `live_source_ips`
+        is the caller's enumeration of its live bottles — the orchestrator
+        can't see the backend from inside the infra container."""
+        body: dict[str, object] = {"live_source_ips": list(live_source_ips)}
+        if grace_seconds is not None:
+            body["grace_seconds"] = grace_seconds
+        payload = self._ok("POST", "/reconcile", body)
+        reaped = payload.get("reaped")
+        return [r for r in reaped if isinstance(r, str)] if isinstance(reaped, list) else []
+
     def set_policy(self, bottle_id: str, policy: str) -> bool:
         """Live-reload a bottle's policy (`PUT /bottles/<id>/policy`). False on
         404 (unknown bottle)."""

bot_bottle/orchestrator/config_store.py

@@ -0,0 +1,107 @@
+"""Per-host orchestrator configuration store (settings in bot-bottle.db).
+
+Co-tenants the shared `bot-bottle.db` via the `DbStore` framework.  Settings
+are readable by the host launch path directly (no HTTP round-trip to the
+orchestrator), so they take effect even before the orchestrator is reachable.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from pathlib import Path
+
+from ..db_store import DbStore
+from ..migrations import TableMigrations
+from ..paths import host_db_path
+
+TEARDOWN_TIMEOUT_ENV = "BOT_BOTTLE_ORCHESTRATOR_TEARDOWN_TIMEOUT_SECONDS"
+DEFAULT_TEARDOWN_TIMEOUT_SECONDS = 30.0
+
+_MIGRATIONS = TableMigrations(
+    "orchestrator_config",
+    [
+        """
+        CREATE TABLE IF NOT EXISTS orchestrator_config (
+            id                       INTEGER PRIMARY KEY CHECK (id = 1),
+            teardown_timeout_seconds REAL
+        )
+        """,
+    ],
+)
+
+
+class OrchestratorConfigStore(DbStore):
+    """Orchestrator settings in the shared host DB."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        super().__init__(db_path or host_db_path(), _MIGRATIONS)
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = super()._connect()
+        conn.execute("PRAGMA busy_timeout=5000")
+        return conn
+
+    def get_teardown_timeout_seconds(self) -> float | None:
+        """Return the configured teardown timeout, or None if not set."""
+        try:
+            with self._connection() as conn:
+                row = conn.execute(
+                    "SELECT teardown_timeout_seconds FROM orchestrator_config WHERE id = 1"
+                ).fetchone()
+        except sqlite3.OperationalError:
+            return None
+        return row["teardown_timeout_seconds"] if row else None
+
+    def set_teardown_timeout_seconds(self, value: float) -> None:
+        """Persist the teardown timeout."""
+        with self._connection() as conn:
+            conn.execute(
+                "INSERT OR REPLACE INTO orchestrator_config"
+                " (id, teardown_timeout_seconds) VALUES (1, ?)",
+                (value,),
+            )
+        self._chmod()
+
+    def delete_teardown_timeout_seconds(self) -> bool:
+        """Clear the stored teardown timeout. Returns True if a value existed."""
+        with self._connection() as conn:
+            cur = conn.execute(
+                "UPDATE orchestrator_config SET teardown_timeout_seconds = NULL"
+                " WHERE id = 1 AND teardown_timeout_seconds IS NOT NULL"
+            )
+        return cur.rowcount > 0
+
+
+def resolve_teardown_timeout(db_path: Path | None = None) -> float:
+    """Return the teardown timeout to use, in priority order:
+
+    1. ``BOT_BOTTLE_ORCHESTRATOR_TEARDOWN_TIMEOUT_SECONDS`` env var
+    2. ``teardown_timeout_seconds`` in the orchestrator config DB
+    3. ``DEFAULT_TEARDOWN_TIMEOUT_SECONDS`` (30 s)
+    """
+    raw = os.environ.get(TEARDOWN_TIMEOUT_ENV, "").strip()
+    if raw:
+        try:
+            value = float(raw)
+            if value > 0:
+                return value
+        except ValueError:
+            pass
+
+    store = OrchestratorConfigStore(db_path)
+    if not store.is_migrated():
+        store.migrate()
+    db_value = store.get_teardown_timeout_seconds()
+    if db_value is not None and db_value > 0:
+        return db_value
+
+    return DEFAULT_TEARDOWN_TIMEOUT_SECONDS
+
+
+__all__ = [
+    "OrchestratorConfigStore",
+    "resolve_teardown_timeout",
+    "TEARDOWN_TIMEOUT_ENV",
+    "DEFAULT_TEARDOWN_TIMEOUT_SECONDS",
+]

bot_bottle/orchestrator/control_plane.py

@@ -13,6 +13,9 @@ vsock / unix-socket portability caveats):
     PUT    /bottles/<bottle_id>/policy -> 200 {"updated": true} | 404  (live reload)
                                          body: {"policy"}
     DELETE /bottles/<bottle_id>        -> 200 {"torn_down": true} | 404  (teardown)
+    POST   /reconcile                 -> 200 {"reaped": [bottle_id, ...]}
+                                         body: {"live_source_ips": [...],
+                                                ["grace_seconds"]}
     POST   /attribute                 -> 200 {"bottle_id"} | 403
     POST   /resolve                   -> 200 {"bottle_id","policy"} | 403
                                          body: {"source_ip","identity_token"}
@@ -141,6 +144,27 @@ def dispatch(  # pylint: disable=too-many-return-statements,too-many-branches
             return 200, {"torn_down": True}
         return 404, {"error": "no such bottle"}
 
+    if method == "POST" and route == "/reconcile":
+        # Host-driven self-heal: the caller enumerates its live bottles (only
+        # the host can see the backend) and the orchestrator drops rows for
+        # every other active bottle. Trusted-caller only — an agent that could
+        # reach this would be able to unregister its neighbours.
+        try:
+            data = _parse_json_object(body)
+        except ValueError as e:
+            return 400, {"error": f"invalid JSON: {e}"}
+        raw_ips = data.get("live_source_ips")
+        if not isinstance(raw_ips, list):
+            return 400, {"error": "live_source_ips (list of strings) is required"}
+        live = [ip for ip in raw_ips if isinstance(ip, str) and ip]
+        grace = data.get("grace_seconds")
+        kwargs = (
+            {"grace_seconds": float(grace)}
+            if isinstance(grace, (int, float)) and not isinstance(grace, bool)
+            else {}
+        )
+        return 200, {"reaped": orch.reconcile(live, **kwargs)}
+
     if method == "POST" and route == "/attribute":
         try:
             data = _parse_json_object(body)

bot_bottle/orchestrator/registry.py

@@ -32,6 +32,7 @@ import hmac
 import secrets
 import sqlite3
 import time
+from collections.abc import Iterable
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -42,6 +43,12 @@ from ..paths import host_db_path
 # 256 bits of urandom, URL-safe — unguessable per-bottle identity token.
 IDENTITY_TOKEN_BYTES = 32
 
+# How recently a row must have been registered to be exempt from
+# `reap_absent`. Covers the window between `container run` and the address
+# becoming visible to another launch's enumeration, so reconciliation never
+# reaps a bottle that is still coming up.
+DEFAULT_REAP_GRACE_SECONDS = 120.0
+
 
 def new_identity_token() -> str:
     """A fresh per-bottle identity token (PRD 0070 attribution defence)."""
@@ -225,6 +232,70 @@ class RegistryStore(DbStore):
             ).fetchall()
         return [_row_to_record(r) for r in rows]
 
+    def reap_absent(
+        self,
+        live_source_ips: Iterable[str],
+        *,
+        grace_seconds: float = DEFAULT_REAP_GRACE_SECONDS,
+        now: float | None = None,
+    ) -> list[BottleRecord]:
+        """Delete active rows whose source IP is not held by a live bottle.
+
+        A row only ever leaves the registry two ways: an explicit
+        `teardown_bottle` (the launcher's cleanup callback) or the supersede
+        sweep in `register`. Neither runs when the launching CLI dies hard —
+        SIGKILL, a closed terminal, a host sleep/crash — so the row outlives
+        its container. That orphan is not inert: source IPs are recycled by
+        the backend's DHCP, and `by_source_ip` fail-closes on ambiguity, so a
+        leftover row at a reused address can brick the *next* bottle that
+        lands on it (no policy resolved -> every host denied, reported to the
+        agent as "not in the allowlist"). Reconciling against the live set at
+        launch keeps the registry from accumulating those landmines.
+
+        Restores the invariant the data plane needs: **at most one active row
+        per live address, and none at all for a dead one.** Two cases, because
+        a dead bottle's address may already have been handed to a live one:
+
+          * no live bottle holds the address — every row there is an orphan;
+          * a live bottle holds it but several rows claim it — the newest
+            registration is authoritative and the rest are orphans, the same
+            rule `register`'s same-IP supersede sweep applies. Without this
+            second case a recycled address stays ambiguous, which is exactly
+            the state that resolves no policy.
+
+        `grace_seconds` protects an in-flight launch: registration happens
+        moments after `container run`, and a concurrent launch's address may
+        not be visible to the caller's enumeration yet. Rows younger than the
+        grace window are never reaped, so reconciliation can't race a bottle
+        that is still coming up. Returns the deleted records."""
+        live = {ip for ip in live_source_ips if ip}
+        cutoff = (time.time() if now is None else now) - grace_seconds
+        with self._connection() as conn:
+            rows = conn.execute(
+                "SELECT * FROM orchestrator_bottles WHERE state = 'active'",
+            ).fetchall()
+            by_ip: dict[str, list[BottleRecord]] = {}
+            for row in rows:
+                rec = _row_to_record(row)
+                by_ip.setdefault(rec.source_ip, []).append(rec)
+            candidates: list[BottleRecord] = []
+            for ip, recs in by_ip.items():
+                if ip not in live:
+                    candidates.extend(recs)
+                    continue
+                # Keep the newest claim on a live address; supersede the rest.
+                recs.sort(key=lambda r: r.created_at)
+                candidates.extend(recs[:-1])
+            doomed = [r for r in candidates if r.created_at <= cutoff]
+            for rec in doomed:
+                conn.execute(
+                    "DELETE FROM orchestrator_bottles WHERE bottle_id = ?",
+                    (rec.bottle_id,),
+                )
+        if doomed:
+            self._chmod()
+        return doomed
+
     def by_source_ip(self, source_ip: str) -> BottleRecord | None:
         """Network-layer attribution: the single active bottle at this source
         IP, or None if unknown or ambiguous (more than one — a
@@ -262,4 +333,5 @@ __all__ = [
     "new_identity_token",
     "default_db_path",
     "IDENTITY_TOKEN_BYTES",
+    "DEFAULT_REAP_GRACE_SECONDS",
 ]

bot_bottle/orchestrator/service.py

@@ -13,15 +13,20 @@ Launch lifecycle:
     and returns the record. If the broker rejects/fails, the registry entry
     is rolled back so a failed launch leaves no orphan.
   * `teardown_bottle` sends a signed teardown request, then deregisters.
+  * `reconcile` sweeps rows whose bottle is no longer running — the
+    self-heal for the teardown paths that never got to run (a hard-killed
+    launcher), since an orphan row at a recycled source IP bricks the next
+    bottle that lands on it.
 """
 
 from __future__ import annotations
 
 import json
+from collections.abc import Iterable
 from datetime import datetime, timezone
 
 from .broker import LaunchBroker, LaunchRequest, sign_request
-from .registry import BottleRecord, RegistryStore
+from .registry import DEFAULT_REAP_GRACE_SECONDS, BottleRecord, RegistryStore
 from .gateway import Gateway
 from ..supervise import (
     AuditEntry,
@@ -117,6 +122,30 @@ class Orchestrator:
         self._tokens.pop(bottle_id, None)
         return True
 
+    def reconcile(
+        self,
+        live_source_ips: Iterable[str],
+        *,
+        grace_seconds: float = DEFAULT_REAP_GRACE_SECONDS,
+    ) -> list[str]:
+        """Drop registry rows for bottles that are no longer running, and
+        forget their in-memory egress tokens. Returns the reaped bottle ids.
+
+        The caller supplies the live set because only the host can enumerate
+        its own containers — the orchestrator runs *inside* the infra
+        container and has no view of the backend. Deliberately does not
+        broker a teardown: the container is already gone, so there is nothing
+        to stop, and a broker error must not stop the sweep from clearing
+        the row that would otherwise brick the next bottle at that address.
+
+        See `RegistryStore.reap_absent` for why orphans accumulate and why
+        they are harmful rather than merely untidy."""
+        reaped = self.registry.reap_absent(
+            live_source_ips, grace_seconds=grace_seconds)
+        for rec in reaped:
+            self._tokens.pop(rec.bottle_id, None)
+        return [rec.bottle_id for rec in reaped]
+
     def tokens_for(self, bottle_id: str) -> dict[str, str]:
         """The bottle's in-memory egress auth tokens (env_name -> value), or
         empty. The gateway injects these per request; they are never

bot_bottle/supervise.py

@@ -47,6 +47,7 @@ from .supervise_types import (
     STATUS_MODIFIED,
     STATUS_REJECTED,
     TOOLS,
+    TOOL_CHECK_PROPOSAL,
     TOOL_EGRESS_ALLOW,
     TOOL_EGRESS_BLOCK,
     TOOL_EGRESS_TOKEN_ALLOW,
@@ -263,6 +264,7 @@ __all__ = [
     "TOOLS",
     "EGRESS_FORWARD_PROXY",
     "EGRESS_INTROSPECT_URL",
+    "TOOL_CHECK_PROPOSAL",
     "TOOL_EGRESS_ALLOW",
     "TOOL_EGRESS_BLOCK",
     "TOOL_GITLEAKS_ALLOW",

bot_bottle/supervise_server.py

@@ -2,14 +2,24 @@
 
 Per-bottle MCP server exposing tools the agent calls to propose egress
 config changes when stuck. The tools are `egress-allow`,
-`egress-block`, and `list-egress-routes`.
+`egress-block`, `list-egress-routes`, and `check-proposal`.
 
-Each queued tool call:
+Each queued proposal tool call:
 
   1. Validates the proposed file syntactically.
   2. Writes a Proposal to the host SQLite database.
-  3. Blocks polling for a matching Response row.
-  4. Returns the operator's `{status, notes}` to the agent.
+  3. Blocks polling for a matching Response row, up to a short grace
+     window (`SUPERVISE_RESPONSE_TIMEOUT_SECONDS`, default 30s).
+  4. On a decision within the window, returns the operator's
+     `{status, notes}`. On timeout, returns `status: pending` **with the
+     proposal id** and leaves the proposal queued — the flow is
+     non-blocking past the grace window (PRD prd-new / issue #412).
+
+`check-proposal` is the non-blocking companion: given a `proposal_id`
+returned by a `pending` response, it reports the current decision
+(`pending` | `approved` | `modified` | `rejected`) without re-proposing,
+so an approval made out-of-band (e.g. a web review console) can be resumed
+without holding an HTTP request open.
 
 One shared server fronts every bottle (PRD 0070) and attributes each
 proposal to the calling bottle by source IP, resolved from the orchestrator
@@ -22,7 +32,9 @@ Speaks MCP over HTTP+JSON-RPC. Methods handled:
   * `initialize`           — handshake; returns server info + caps.
   * `notifications/initialized` — ack-only.
   * `tools/list`           — returns the tool definitions.
-  * `tools/call`           — validates, queues, blocks, returns.
+  * `tools/call`           — validates, queues, waits out the grace
+                             window, returns (pending past it); or, for
+                             `check-proposal`, a non-blocking status poll.
 
 Everything else returns JSON-RPC error -32601 (method not found).
 
@@ -232,6 +244,31 @@ TOOL_DEFINITIONS: list[dict[str, object]] = [
         ),
         "inputSchema": _proposal_input_schema(),
     },
+    {
+        "name": _sv.TOOL_CHECK_PROPOSAL,
+        "description": (
+            "Poll a previously queued proposal for the operator's decision "
+            "WITHOUT blocking or re-proposing. Pass the `proposal_id` you "
+            "got back when an `egress-allow`/`egress-block` call returned "
+            "`status: pending`. Returns the current status: `pending` (no "
+            "decision yet — poll again later), `approved`, `modified`, "
+            "`rejected`, or `unknown` (no such queued proposal — wrong id, "
+            "or it was already resolved and read)."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "proposal_id": {
+                    "type": "string",
+                    "description": (
+                        "The proposal id from a `pending` response."
+                    ),
+                },
+            },
+            "required": ["proposal_id"],
+            "additionalProperties": False,
+        },
+    },
 ]
 
 
@@ -353,7 +390,7 @@ def handle_tools_call(
             deadline=deadline,
         )
     except TimeoutError:
-        text = format_pending_response_text(config.response_timeout_seconds)
+        text = format_pending_response_text(proposal.id, config.response_timeout_seconds)
         return {
             "content": [{"type": "text", "text": text}],
             "isError": False,
@@ -370,6 +407,54 @@ def handle_tools_call(
     }
 
 
+def handle_check_proposal(
+    params: dict[str, object],
+    config: ServerConfig,
+) -> dict[str, object]:
+    """Non-blocking poll of a queued proposal's decision, by id.
+
+    Never creates a Proposal (so `check-proposal` isn't in `TOOLS`); it only
+    reads the queue. Resolution order mirrors the synchronous path's terminal
+    step — a decided proposal is archived here exactly as `handle_tools_call`
+    archives it after `wait_for_response`, so `pending` proposals stay visible
+    to the operator until they're both decided *and* polled."""
+    args_raw = params.get("arguments", {})
+    if not isinstance(args_raw, dict):
+        raise _RpcClientError(ERR_INVALID_PARAMS, "tools/call 'arguments' must be an object")
+    proposal_id = args_raw.get("proposal_id")
+    if not isinstance(proposal_id, str) or not proposal_id.strip():
+        raise _RpcClientError(
+            ERR_INVALID_PARAMS,
+            "check-proposal: 'proposal_id' is required and must be a non-empty string",
+        )
+    proposal_id = proposal_id.strip()
+
+    try:
+        response = _sv.read_response(config.bottle_slug, proposal_id)
+    except FileNotFoundError:
+        # No decision yet — distinguish "still queued" from "unknown id".
+        try:
+            _sv.read_proposal(config.bottle_slug, proposal_id)
+        except FileNotFoundError:
+            return {
+                "content": [{"type": "text", "text": format_unknown_proposal_text(proposal_id)}],
+                "isError": True,
+            }
+        return {
+            "content": [{"type": "text", "text": format_still_pending_text(proposal_id)}],
+            "isError": False,
+        }
+
+    try:
+        _sv.archive_proposal(config.bottle_slug, proposal_id)
+    except OSError as e:
+        raise _RpcInternalError(f"failed to archive proposal: {e}") from e
+    return {
+        "content": [{"type": "text", "text": format_response_text(response)}],
+        "isError": response.status == _sv.STATUS_REJECTED,
+    }
+
+
 def format_response_text(response: "_sv.Response") -> str:
     """Pretty-print a Response for the tool's text content. The agent
     reads the text and decides whether to retry / give up / surface."""
@@ -382,12 +467,35 @@ def format_response_text(response: "_sv.Response") -> str:
     return "\n".join(lines)
 
 
-def format_pending_response_text(timeout_seconds: float) -> str:
+def format_pending_response_text(proposal_id: str, timeout_seconds: float) -> str:
+    """Grace-window timeout: the proposal stays queued, and the agent is
+    told the id so it can `check-proposal` instead of re-proposing."""
     return "\n".join([
         "status: pending",
+        f"proposal_id: {proposal_id}",
         (
-            "notes: operator response timed out after "
-            f"{timeout_seconds:g}s; proposal remains queued"
+            f"notes: no operator decision within {timeout_seconds:g}s; the "
+            "proposal remains queued. Poll it (do not re-propose) by calling "
+            f"`check-proposal` with proposal_id={proposal_id!r}."
+        ),
+    ])
+
+
+def format_still_pending_text(proposal_id: str) -> str:
+    return "\n".join([
+        "status: pending",
+        f"proposal_id: {proposal_id}",
+        "notes: still queued; no operator decision yet. Call `check-proposal` again later.",
+    ])
+
+
+def format_unknown_proposal_text(proposal_id: str) -> str:
+    return "\n".join([
+        "status: unknown",
+        f"proposal_id: {proposal_id}",
+        (
+            "notes: no queued proposal with this id for this bottle — the id "
+            "may be wrong, or the proposal was already resolved and read."
         ),
     ])
 
@@ -482,6 +590,11 @@ class MCPHandler(http.server.BaseHTTPRequestHandler):
             # — silently dropping base routes like api.anthropic.com on approval.
             if req.params.get("name") == _sv.TOOL_LIST_EGRESS_ROUTES:
                 return self._resolved_routes_payload()
+            # `check-proposal` is a non-blocking read of the calling bottle's
+            # own queue — attributed by source IP like a proposal, but it
+            # never queues or blocks.
+            if req.params.get("name") == _sv.TOOL_CHECK_PROPOSAL:
+                return handle_check_proposal(req.params, self._attributed_config(config))
             # Attribute the proposal to the source-IP-resolved bottle, so the one
             # shared server queues each bottle's proposal under its own slug.
             return handle_tools_call(req.params, self._attributed_config(config))

bot_bottle/supervise_types.py

@@ -20,6 +20,10 @@ TOOL_EGRESS_ALLOW = "egress-allow"
 TOOL_GITLEAKS_ALLOW = "gitleaks-allow"
 TOOL_EGRESS_TOKEN_ALLOW = "egress-token-allow"
 TOOL_LIST_EGRESS_ROUTES = "list-egress-routes"
+# Read-only agent tool: poll a queued proposal for the operator's decision
+# without blocking or re-proposing. It never becomes a `Proposal.tool` (no
+# queue record is created for it), so it is intentionally NOT in `TOOLS`.
+TOOL_CHECK_PROPOSAL = "check-proposal"
 TOOLS: tuple[str, ...] = (
     TOOL_EGRESS_ALLOW,
     TOOL_EGRESS_BLOCK,
@@ -156,6 +160,7 @@ __all__ = [
     "TOOLS",
     "TOOL_EGRESS_ALLOW",
     "TOOL_EGRESS_BLOCK",
+    "TOOL_CHECK_PROPOSAL",
     "TOOL_EGRESS_TOKEN_ALLOW",
     "TOOL_GITLEAKS_ALLOW",
     "TOOL_LIST_EGRESS_ROUTES",

bot_bottle/util.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import ipaddress
 import os
+import sys
 
 
 def is_ip_literal(value: str) -> bool:
@@ -17,6 +18,15 @@ 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

docs/prds/0023-smolmachines-backend.md

@@ -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/landscape-containerized-claude.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/agent-sandbox-landscape.md`.
 
 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis

docs/prds/0032-smolmachines-launch-decomposition.md

@@ -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/landscape-containerized-claude.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/agent-sandbox-landscape.md`.
 
 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis-claude

docs/prds/0038-smolmachines-env-contract.md

@@ -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/landscape-containerized-claude.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/agent-sandbox-landscape.md`.
 
 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis-codex

docs/prds/0039-smolmachines-capability-remediation.md

@@ -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/landscape-containerized-claude.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/agent-sandbox-landscape.md`.
 
 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis-codex

docs/prds/0042-smolmachines-parity-tests.md

@@ -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/landscape-containerized-claude.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/agent-sandbox-landscape.md`.
 
 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis-codex

docs/prds/0057-smolmachines-default.md

@@ -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/landscape-containerized-claude.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/agent-sandbox-landscape.md`.
 
 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** didericis

docs/prds/0068-smolmachines-linux.md

@@ -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/landscape-containerized-claude.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/agent-sandbox-landscape.md`.
 
 - **Status:** Superseded (2026-07-11) — was Active
 - **Author:** Claude

docs/prds/prd-new-nonblocking-supervise.md

@@ -0,0 +1,125 @@
+# PRD prd-new: Non-blocking supervise (async approval + proposal polling)
+
+- **Status:** Draft
+- **Author:** didericis
+- **Created:** 2026-07-18
+- **Issue:** #412
+
+## Summary
+
+The per-bottle supervise MCP server (`bot_bottle/supervise_server.py`)
+answers `tools/call` **synchronously**: it queues the agent's proposal and
+blocks the tool call polling for the operator's decision. On timeout it
+returns `status: pending` and leaves the proposal queued — but it hands the
+agent **no proposal id** and offers **no way to poll a specific pending
+proposal**, so the only way to learn the outcome is to re-propose (a
+duplicate).
+
+This PRD makes the MCP flow non-blocking and pollable, so an approval can
+happen out-of-band (a human taking minutes-to-hours in a review console)
+without holding an HTTP request open or wedging the agent:
+
+1. Include the `proposal_id` in the `pending` response.
+2. Add a `check-proposal` MCP tool: a non-blocking status lookup by
+   proposal id.
+3. Keep the short synchronous grace window for the common "operator is
+   right there" fast path.
+
+## Problem
+
+`handle_tools_call` → `_sv.wait_for_response(...)` blocks up to
+`SUPERVISE_RESPONSE_TIMEOUT_SECONDS` (default 30s). Two problems follow:
+
+- **Human latency ≠ tool-call latency.** A real review — rendered diff,
+  RBAC routing to an approver, someone tapping approve on their phone — is
+  minutes-to-hours. Holding the MCP request open that long is fragile
+  (proxy/keepalive timeouts, the mitmproxy egress hop, and the agent
+  harness's own tool-call timeout, which a long block can trip and stall
+  the whole turn).
+- **No resume path.** The pending fallback already exists, but without a
+  proposal id and a poll tool the agent can't reconnect to that specific
+  decision — it re-proposes, duplicating the queue entry.
+
+This is also the precondition for the planned web-console human-review
+flow (RBAC, audit retention, mobile) — see issue #412.
+
+**Safety note:** the MCP tools only *propose* policy changes; enforcement
+stays at the egress proxy and the git-gate. Returning early on `pending`
+therefore opens no hole — the agent still cannot egress or push anything
+unapproved.
+
+## Goals / success criteria
+
+- A `pending` MCP response carries the `proposal_id`.
+- An agent can call `check-proposal(proposal_id)` and get the current
+  state (`pending` | `approved` | `modified` | `rejected`) **without
+  blocking** and **without creating a new proposal**.
+- The synchronous fast path (operator approves within the grace window) is
+  unchanged: the first `tools/call` still returns the decision directly.
+- No change to enforcement, attribution (source-IP → bottle), or the
+  operator-side queue/response schema.
+
+## Non-goals
+
+- The git-gate `pre-receive` path (it is synchronous by nature and cannot
+  poll — its async variant is reject-fast + re-push; tracked as a
+  follow-up).
+- Backpressure / in-flight-proposal caps.
+- MCP server→client notifications (event-driven resume).
+- Any web-console UI (this PRD is the protocol groundwork it needs).
+
+## Design
+
+### `pending` response carries the id
+
+`handle_tools_call`'s timeout branch formats the pending text with the
+`proposal.id` and a pointer to `check-proposal`, so the agent knows what to
+poll.
+
+### `check-proposal` tool
+
+A new read-only MCP tool (`TOOL_CHECK_PROPOSAL = "check-proposal"`),
+attributed to the calling bottle by source IP exactly like the proposal
+tools. Input: `{ "proposal_id": string }`. Behavior:
+
+1. `read_response(slug, id)` →
+   - **found**: archive the proposal (same terminal step the synchronous
+     path takes) and return the decision via `format_response_text`;
+     `isError` iff rejected.
+2. **not found** → `read_proposal(slug, id)` →
+   - **found**: still queued → return `status: pending`.
+   - **not found**: unknown id, or already resolved-and-archived (e.g. a
+     second poll) → return `status: unknown`, `isError: true`.
+
+Both lookups already raise `FileNotFoundError` when absent
+(`queue_store.py`), so the handler needs no new store methods. `check-`
+`proposal` is the only path (besides the synchronous response) that
+archives, so a proposal that times out to `pending` stays visible to the
+operator until it is decided and then polled.
+
+### Grace window
+
+Left at the existing 30s default (`SUPERVISE_RESPONSE_TIMEOUT_SECONDS`),
+which doubles as the instant-approve fast path. Tuning it down is an
+operator setting, not a code change; noted for the console rollout.
+
+## Implementation chunks
+
+1. **(this PR)** `TOOL_CHECK_PROPOSAL` constant; `check-proposal` tool
+   definition + `handle_check_proposal`; dispatch wiring; `proposal_id` in
+   the pending text; unit tests. Files: `bot_bottle/supervise_types.py`,
+   `bot_bottle/supervise.py` (re-export), `bot_bottle/supervise_server.py`,
+   `tests/unit/test_supervise_server.py`.
+2. **(follow-up)** git-gate `pre-receive` reject-fast + re-push.
+3. **(follow-up)** per-bottle in-flight-proposal backpressure cap.
+4. **(follow-up)** MCP notifications for event-driven resume; web-console
+   review flow (RBAC, audit retention) on top.
+
+## Open questions
+
+- Should a resolved-but-unpolled proposal auto-archive after some TTL, or
+  only on poll? (Leaning: only on poll, so a decision is never lost to a
+  reaper before the agent sees it.)
+- Does the agent harness need an explicit "you have a pending proposal"
+  nudge, or is returning `pending` from the original call enough? (Deferred
+  to the notifications chunk.)

docs/research/agent-sandbox-landscape.md

@@ -1,16 +1,16 @@
 # Landscape: AI-agent sandbox tools
 
-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.
+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.
 
 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 / 0053), and git-push secret scanning is handled by
+detectors, PRD 0017 / 0052), 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,12 +20,24 @@ 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
 
-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
+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
 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:
@@ -34,8 +46,9 @@ 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), CubeSandbox
-  (self-hosted multi-tenant microVM service), endo-familiar
+  and microsandbox (microVM libraries for platform builders), E2B and Daytona
+  (hosted sandbox platforms), 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
@@ -52,15 +65,17 @@ 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 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,
+**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,
 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. See the addendum.
+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.
 
 ## Per-project notes
 
@@ -97,7 +112,8 @@ claim that the monetization positioning leans on. See the addendum.
 
 ### agent-safehouse
 - **Source**: https://agent-safehouse.dev/ ; https://github.com/eugene1g/agent-safehouse
-- **License**: Apache 2.0 (~1,400 stars)
+- **HN launch**: [#47301085](https://news.ycombinator.com/item?id=47301085) (March 12 2026) — 823 points
+- **License**: Apache 2.0 (~1,781 stars at launch)
 - **Isolation**: macOS `sandbox-exec` (Seatbelt) profiles — kernel-level
   syscall interception, no container.
 - **Locality**: Local, macOS only.
@@ -107,6 +123,16 @@ claim that the monetization positioning leans on. 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
@@ -189,6 +215,80 @@ claim that the monetization positioning leans on. 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
@@ -305,6 +405,92 @@ claim that the monetization positioning leans on. See the addendum.
   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
@@ -360,19 +546,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 | 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 |
+| 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 |
 
 ## What's closest, what's different
 
@@ -385,7 +571,9 @@ 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.
+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.
 
 **New closest on agent-tailored policy.** Two governance tools are the
 direct competitors on the "coarse-grained sandbox" axis. **tilde.run**
@@ -420,47 +608,81 @@ 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. 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. 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
 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
 
-What bot-bottle already has that the survey suggested as
-differentiators:
+### Already shipped or otherwise addressed
+
 - 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.
 
-Ideas worth considering, without abandoning the Python-stdlib-first /
-local, single-operator stance:
+### Still worth considering
 
-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.
+- **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.
 
 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.
@@ -477,7 +699,8 @@ hosted-SaaS dashboard model of tilde.run (cuts against the
 
 CubeSandbox (Tencent Cloud, Apache 2.0, ~10.4k stars, HN launch
 [#47863430](https://news.ycombinator.com/item?id=47863430)) is the first
-project in this survey to combine, in one open-source stack, everything
+open-source, self-hostable project in this survey to combine, in one stack,
+the main primitives
 bot-bottle treated as its differentiator:
 
 - **Egress custody (connection level)** — default-deny domain allowlist
@@ -545,7 +768,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. These hand you an SDK or a cluster and
+  microsandbox, CubeSandbox, E2B, Daytona. 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
@@ -553,10 +776,11 @@ 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, 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.
+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.
 
 Why it still doesn't collide head-on:
 
@@ -564,7 +788,8 @@ 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
-   JSON manifest, no bottle/agent split, no "one command on my laptop."
+   declarative role 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
@@ -575,7 +800,8 @@ 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** — a well-funded, 10k-star open-source project now ships it.
+  primitive** — CubeSandbox ships the open-source/self-hosted combination,
+  and Daytona ships a proprietary firewall + credential-substitution variant.
   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
@@ -586,8 +812,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) before the next iteration of bot-bottle's
-  in-flight-secret feature — see borrowable idea #2 above.
+  mitmproxy egress proxy) when hardening bot-bottle's now-shipped
+  credential-custody implementation.
 
 ## Addendum 2026-07-18 (second pass) — agent-tailored policy landscape
 
@@ -626,7 +852,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.
 
-**Borrowable from new tools:**
+**Open ideas from new tools (also summarized above):**
 
 - **Microsoft AGT's trust-score decay** — privilege that reflects
   observed behaviour rather than static provisioning. Applied to

docs/research/egress-proxy-oom-on-large-downloads.md

@@ -0,0 +1,86 @@
+# Egress proxy OOMs on large downloads
+
+Found on 2026-07-21 while running the rootless-podman spike
+(`docs/research/rootless-docker-in-apple-container-spike.md`). Recorded
+rather than fixed — the fix is a security-relevant decision, not a
+mechanical patch.
+
+## Summary
+
+A single large HTTPS download through the gateway kills the egress
+proxy. `mitmdump` buffers whole response bodies so the DLP detectors can
+scan them, grows past the gateway container's memory limit, and is
+OOM-killed by the cgroup. Nothing restarts it.
+
+Two properties make this worse than a failed download:
+
+- **The gateway is a per-host singleton.** Every bottle shares it, so
+  one bottle's download takes egress away from all of them.
+- **There is no restart on death.** The gateway supervisor is
+  `while : ; do wait ; done`; a killed daemon stays dead until the infra
+  container is recreated.
+
+So ordinary agent activity — pulling a container image, downloading a
+model or dataset, fetching a large tarball — is a denial of service
+against every other bottle on the host. No malice required, though it is
+trivially reachable on purpose.
+
+## Evidence
+
+Triggered by `docker compose up` pulling `quay.io/fedora/python-312`
+(two layers, ~82MB and ~83MB) inside a bottle. The pull itself
+succeeded; the *next* request failed:
+
+```
+initializing source docker://quay.io/fedora/python-312:latest:
+  pinging container registry quay.io: Get "https://quay.io/v2/":
+  proxyconnect tcp: dial tcp 192.168.128.39:9099: connect: connection refused
+```
+
+From the gateway's `dmesg`:
+
+```
+python3 invoked oom-killer: gfp_mask=0x100cca(GFP_HIGHUSER_MOVABLE), order=0
+oom-kill:constraint=CONSTRAINT_MEMCG,
+  oom_memcg=/container/bot-bottle-mac-infra,
+  task_memcg=/container/bot-bottle-mac-infra,task=mitmdump,pid=118
+Memory cgroup out of memory: Killed process 118 (mitmdump)
+  total-vm:1391936kB, anon-rss:997768kB
+```
+
+~1GB RSS against a 1024MB container. Note the amplification: ~165MB of
+layers produced ~1GB of resident memory, so the buffering is several
+copies deep (encoded body, decoded body, and the text conversion the
+regex detectors scan).
+
+Afterwards the gateway container was still running and healthy-looking —
+orchestrator, supervise, and git-http all alive — with no `mitmdump`
+process at all, and it stayed that way until the container was
+recreated. A liveness check on the container would not have caught this.
+
+## Reproduction
+
+1. Launch any bottle with an egress route to a host serving a large file.
+2. Download >~150MB over HTTPS through the proxy.
+3. `dmesg | grep -i oom` inside `bot-bottle-mac-infra`, and note that no
+   `mitmdump` process remains.
+
+Beware a false negative when checking: truncating the process listing
+(`cut -c1-45`) cuts before the binary name, because `mitmdump` runs as
+`/usr/local/bin/python3.12 /usr/local/bin/mitmdump …`.
+
+## Fix options, not yet chosen
+
+1. **Restart dead daemons.** Smallest change and strictly an
+   improvement: an OOM then degrades one download instead of removing
+   egress for every bottle. Does not stop the OOM.
+2. **Cap the scanned body size.** Above a threshold, stop buffering —
+   either skip the scan or stream it. This is the root-cause fix and a
+   security decision: a size threshold is exactly the hole an exfiltrator
+   would aim for, so "skip above N" trades a DoS for a covert channel.
+   Streaming with a bounded window keeps coverage, at more complexity.
+3. **Raise the gateway's memory limit.** Moves the threshold; does not
+   remove it.
+
+Worth noting that (1) and (2) are complementary — the restart gap is
+worth closing regardless of how the memory behaviour is resolved.

docs/research/hn-agent-safety-discourse-july-2026.md

@@ -43,6 +43,18 @@ 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

docs/research/landscape-containerized-claude.md

@@ -1,182 +0,0 @@
-# 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.

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

@@ -0,0 +1,353 @@
+# Rootless Docker inside Apple Container bottles
+
+Spike branch: `spike/rootless-docker-macos` (`a4d8461`)
+
+## Summary
+
+**Negative result.** Rootless Docker cannot run inside an Apple
+Container bottle without granting the bottle `CAP_SYS_ADMIN`. This is a
+kernel constraint on writing multi-range `uid_map`, not a packaging gap
+we can close with a better init script, a different base image, or more
+careful `/etc/subuid` handling.
+
+The spike was built on the premise — stated in
+`bot_bottle/backend/macos_container/rootless_docker.py` — that it would
+*"deliberately refuse to compensate for missing prerequisites with outer
+capabilities, a privileged container, or a host Docker socket."* That
+premise is exactly what the experiment falsified. The two ways forward
+are to abandon the premise (add `CAP_SYS_ADMIN` to the bottle, and with
+it most of the isolation the bottle exists to provide) or to abandon
+rootless Docker.
+
+Recommendation: abandon rootless Docker. Podman does not have this
+problem — see [Podman is not blocked by
+this](#podman-is-not-blocked-by-this) below.
+
+## Local environment
+
+Tested on 2026-07-21:
+
+```console
+$ sw_vers
+ProductName:		macOS
+ProductVersion:		26.5.1
+BuildVersion:		25F80
+
+$ container --version
+container CLI version 1.0.0 (build: release, commit: ee848e3)
+
+$ uname -a   # inside the bottle
+Linux ... 6.18.15 #1 SMP Tue Mar 17 01:36:53 UTC 2026 aarch64 GNU/Linux
+```
+
+## The failure
+
+`tests/integration/test_macos_rootless_docker_spike.py` builds the
+image, launches the bottle, and dies in `rootless_docker.start`:
+
+```
++ exec rootlesskit --net=slirp4netns --mtu=65520 ... dockerd-rootless.sh
+[rootlesskit:parent] error: failed to setup UID/GID map:
+  newuidmap 1100 [0 1000 1 1 100000 65536] failed:
+  newuidmap: write to uid_map failed: Operation not permitted
+```
+
+## Why it fails
+
+Every prerequisite you would normally suspect is present and correct in
+the guest:
+
+| Check | Result |
+| --- | --- |
+| `/usr/bin/newuidmap` | `-rwsr-xr-x root root` — setuid bit intact, survived the OCI export |
+| `/` mount options | `rw,relatime` — **not** `nosuid` |
+| `NoNewPrivs` | `0` |
+| `Seccomp` | `0`, no filters |
+| `/etc/subuid`, `/etc/subgid` | `node:100000:65536` in both |
+| user namespace | `user:[4026531837]`, identical to pid 1 — the *initial* userns |
+| `unshare -U -r true` | succeeds |
+| `/proc/sys/user/max_user_namespaces` | `4505` |
+
+The one thing that is missing is in the capability bounding set that
+Apple Container gives the container:
+
+```
+CapBnd: 00000000a80425fb
+= chown, dac_override, fowner, fsetid, kill, setgid, setuid, setpcap,
+  net_bind_service, net_raw, sys_chroot, mknod, audit_write, setfcap
+```
+
+No `CAP_SYS_ADMIN`. That is the whole story, and the chain is:
+
+1. The kernel's `map_write()` gates writing a `uid_map` on
+   `file_ns_capable(file, ns, CAP_SYS_ADMIN)` — capability over the
+   **new** user namespace, evaluated against the credentials that opened
+   `/proc/<pid>/uid_map`.
+2. `newuidmap` is setuid-root, so it runs with euid 0 — but its
+   capability sets are clamped by the bounding set, which has no
+   `CAP_SYS_ADMIN`.
+3. `cap_capable()` has a shortcut that grants *all* capabilities when
+   the caller's userns is the new namespace's parent **and**
+   `ns->owner == cred->euid`. It does not apply: the namespace was
+   created by `node` (uid 1000) while `newuidmap` runs as euid 0.
+4. So the check falls through to the effective-set test in the initial
+   userns, which fails. `EPERM`.
+
+Note that the single-line unprivileged path (`unshare -U -r`) works
+precisely because it does not go through `newuidmap` and does not need
+`CAP_SYS_ADMIN`. Only the multi-range subuid mapping that rootless
+Docker requires does.
+
+This is the same constraint that makes upstream's `dind-rootless` image
+require `--privileged`. It is not specific to Apple Container, except
+that Apple Container gives us no bounding set that includes
+`CAP_SYS_ADMIN` by default.
+
+## It does work with the capability — which is the point
+
+Adding the capability clears the failure immediately, and exposes one
+further, much smaller blocker: `/dev/net/tun` exists (the kernel has
+tun; `/proc/misc` lists `200 tun`) but Apple Container creates it
+`crw------- root root`, so uid 1000 cannot open it and `slirp4netns`
+fails with `open: Permission denied`. A `chmod 0666 /dev/net/tun` as
+root inside the bottle fixes that, and needs no capability beyond what
+the bottle already has.
+
+With both applied by hand, the daemon comes up completely:
+
+```console
+$ container run --rm -u root --cap-add CAP_SYS_ADMIN \
+    bot-bottle-claude:latest-rootless-docker sh -c '...'
+Server Version: 20.10.24+dfsg1
+Storage Driver: fuse-overlayfs
+Cgroup Driver: none
+Cgroup Version: 2
+API listen on /tmp/rt/docker.sock
+```
+
+So `rootless-docker-init.sh` and `rootless_docker.py` are *correct*.
+The spike did not fail on a bug. It failed on its own premise.
+
+Two secondary findings from that run, relevant if anyone revisits this:
+
+- Debian's `docker.io` package pins Docker **20.10** (EOL), not the 28.x
+  implied by the `docker:28-cli` compose plugin the image copies in.
+- `Cgroup Driver: none` — no resource limits on nested containers.
+
+## Why we should not just add the capability
+
+`CAP_SYS_ADMIN` is close to a superset of "root" in practical terms —
+mount, `pivot_root`, namespace manipulation, and a long tail of
+subsystem-specific powers. Granting it to the agent bottle would
+undercut the containment argument the rest of the backend is built
+around, including the deliberately narrow choices immediately adjacent
+to it in `launch.py` (`--cap-drop CAP_NET_RAW`, no `NET_ADMIN`, a
+host-only agent network). Trading all of that for nested `docker
+compose` is a bad exchange.
+
+## Podman is not blocked by this
+
+Sanity-checked on the same host, same kernel, same runtime, so the
+comparison is apples to apples:
+
+| Scenario | Result |
+| --- | --- |
+| Podman rootless, `/etc/subuid` populated | **Fails identically** — `newuidmap: write to uid_map failed: Operation not permitted` |
+| Podman rootless, no subuid ranges, `--network=host` | **Works**, no added capabilities |
+| Podman rootless, no subuid ranges, default netns, `/dev/net/tun` at `0600` | Fails — `slirp4netns: open("/dev/net/tun"): Permission denied` |
+| Podman rootless, no subuid ranges, default netns, `/dev/net/tun` at `0666` | **Works**, no added capabilities |
+
+The difference is that podman degrades gracefully when no subuid range
+is available: it falls back to a single-UID self-mapping, which an
+unprivileged process may write itself, so `newuidmap` is never invoked
+and `CAP_SYS_ADMIN` is never needed. Docker's rootless mode has no
+equivalent fallback.
+
+The cost of that fallback is real and should be weighed before building
+on it: with a single-UID mapping, every UID inside a nested container
+collapses onto the bottle's own uid 1000. There is no UID separation
+between the agent and anything it runs — `root` in a nested container is
+the agent user outside it. It also requires `ignore_chown_errors` on the
+storage driver. Whether that is acceptable depends on whether the bottle
+boundary (which is unchanged) or the nested-container boundary (which is
+effectively nil) is the one we are relying on.
+
+## What the podman spike then needed
+
+The podman implementation that replaced the Docker one on this branch
+turned up two more device-node blockers of the same shape as
+`/dev/net/tun` — Apple Container creates the node, but 0600 root:root:
+
+- **`/dev/fuse`** — blocks the `fuse-overlayfs` storage driver
+  (`fuse: failed to open /dev/fuse: Permission denied`). Without it the
+  only working driver is `vfs`, which copies whole layers per container.
+- **`/dev/net/tun`** — blocks `slirp4netns`, which rootless podman uses
+  for the default bridge network.
+
+Both are fixed by `chmod 0666` as root inside the bottle, which needs no
+capability the bottle does not already hold. This is categorically
+different from the `CAP_SYS_ADMIN` requirement: it is a permission on a
+node that already exists, not an outer privilege grant.
+
+One design note worth recording: the agent-facing surface stays `docker`
+and `docker compose`, pointed at podman's Docker-compatible API socket
+via `DOCKER_HOST`. Setting `netns="host"` in `containers.conf` does *not*
+propagate through that compat API — stock `docker run` and compose files
+request bridge networking explicitly — so slirp4netns (and therefore the
+`/dev/net/tun` chmod) is required for ordinary compose files to work at
+all. Host networking remains available per-workload via
+`--network=host`.
+
+Verified working in a bottle with zero added capabilities: fuse-overlayfs
+storage, the compat API socket, `docker run` on both bridge and host
+networking, and published ports.
+
+### Nested pulls collide with our own egress DLP
+
+The first live run got podman up and `docker compose` running, then
+failed on the image pull:
+
+```
+web Pulling
+initializing source docker://python:3.12-alpine: reading manifest ...
+StatusCode: 403, egress DLP: Generic Bearer JWT found in body
+```
+
+This is bot-bottle's own egress scanner, not a podman problem. The
+Docker registry auth flow carries a bearer JWT *by protocol*, and the
+`token_patterns` detector's `Generic Bearer JWT` rule
+(`Bearer\s+[A-Za-z0-9._\-]{50,}`) matches it on every pull. Any bottle
+that pulls images will hit this.
+
+The fix is per-route detector scoping, which the egress config already
+supports — drop `token_patterns` on the registry hosts and keep
+`known_secrets`:
+
+```json
+{"host": "registry-1.docker.io",
+ "dlp": {"outbound_detectors": ["known_secrets"]}}
+```
+
+That is the right trade rather than a grudging one: `known_secrets`
+matches the bottle's *actual* credential values, so real exfil through a
+registry host is still caught. `token_patterns` on a registry route only
+ever produces protocol noise.
+
+Worth generalising later: any manifest enabling `docker_access` needs
+this on its registry routes, so it probably belongs in a shared
+registry-route snippet rather than being copy-pasted per bottle.
+
+### And then registry auth collides with the Authorization strip
+
+With DLP scoped, the pull failed differently: `unauthorized:
+authentication required`. This one is architectural.
+
+`egress_addon.py` strips agent-set `Authorization` unconditionally
+before forwarding — deliberately, so an agent cannot smuggle a
+credential out in a header the DLP detectors don't recognise. A route
+may carry gateway-injected auth instead, but only from a *static* token
+in an env var (`auth_scheme` + `token_env`).
+
+Docker registry auth doesn't fit that shape. The client fetches a
+short-lived, per-repository-scope bearer token from `auth.docker.io` and
+presents it to `registry-1.docker.io`. There is no static token to
+inject, and the token the client legitimately obtained is stripped.
+
+Measured inside a bottle, by hand:
+
+| Step | Result |
+| --- | --- |
+| Fetch token from `auth.docker.io` | 200, 5409-byte token body |
+| Manifest request **with** that valid token | 401 |
+| Manifest request with **no** Authorization | 401 — identical |
+
+A valid token behaves exactly like sending none, which is direct
+evidence the header never arrives. Any nested-container workflow that
+pulls from a registry is blocked on this, so it is not a detail that can
+be deferred: pulling base images is most of what nested containers are
+for.
+
+### Registries that skip the token dance work today
+
+Not every registry needs the stripped header. Measured directly:
+
+| Registry | Manifest request with no `Authorization` |
+| --- | --- |
+| `quay.io` | 200 |
+| `mcr.microsoft.com` | 200 |
+| `registry.k8s.io` | 307 (redirect, no auth) |
+| `ghcr.io` | 401 |
+| `registry-1.docker.io` | 401 |
+
+So "just add the registry to the bottle config" genuinely works — for
+quay, MCR, registry.k8s.io, or any unauthenticated internal registry.
+Docker Hub and GHCR are the ones that need the strip resolved. The
+acceptance test uses quay for exactly this reason.
+
+Resolving it for Docker Hub means picking one of:
+
+1. **Per-route opt-in to preserve client Authorization.** Smallest
+   change. Note the compounding effect on exactly these routes: the DLP
+   scoping above already removed `token_patterns` there, so a
+   preserved-auth registry route is one where the agent may send bearer
+   tokens that neither the strip nor the pattern detector inspects.
+   `known_secrets` still applies, so the bottle's real credentials are
+   still caught.
+2. **A registry-aware gateway** that performs the token dance itself and
+   injects the result. Preserves the invariant fully; materially more
+   work, and it makes the gateway speak a specific registry protocol.
+3. **Pre-seed images at provision time** (host-side `container image
+   save` into podman storage), so bottles never pull at runtime.
+   Preserves the invariant, and limits nested containers to
+   pre-approved images — which fits the custody positioning, at the cost
+   of no ad-hoc `docker pull`.
+4. **Stop.** Nested containers are not supported on this backend.
+
+### Podman 4.3.1 silently swallows container exit codes
+
+Debian bookworm — which the current agent base image is built on —
+ships podman 4.3.1. Through its Docker-compatible API, `docker run`
+returns 0 no matter what the container did:
+
+| Command | podman 4.3.1 | podman 5.4.2 |
+| --- | --- | --- |
+| `docker run … sh -c 'exit 7'` (compat API) | **0** | 7 |
+| `docker run … sh -c 'exit 0'` (compat API) | 0 | 0 |
+| `podman run … sh -c 'exit 7'` (native) | 7 | 7 |
+
+This is worse than a broken feature: every failing command an agent runs
+via `docker run` reports success. A test suite, a build step, or a CI
+script inside a bottle would pass while failing. It also silently
+defeated the acceptance test's egress-containment assertion, which is
+why that assertion now checks an in-band marker rather than an exit
+code.
+
+Podman 5.4.2 (Debian trixie) fixes it, but needs two packages that
+bookworm's podman does not: `passt` (podman 5's default network tool)
+and `nftables` (netavark shells out to `nft`; without it every run fails
+with `unable to upgrade to tcp, received 500`). With both installed,
+exit codes propagate correctly and the compat API behaves.
+
+The open question this leaves is where podman 5 comes from, since the
+agent base is bookworm-based:
+
+1. **Move the agent images to Debian trixie.** Trixie is current stable.
+   Correct, and the blast radius is every bottle, not just this feature.
+2. **Drop the compat socket and use podman natively** (`podman-docker`
+   provides a `docker` shim; compose comes from `podman-compose`).
+   Native podman propagates exit codes correctly even on 4.3.1. Contained
+   to this feature, at the cost of `docker compose` becoming
+   `docker-compose`/`podman-compose`.
+3. **Ship bookworm's podman 4.3.1 with the compat socket** — not viable.
+   Silent false success is a correctness bug agents cannot see.
+
+## Recommendation
+
+1. Do not revive rootless Docker on this backend. This document is the
+   record of why.
+2. Nested containers, if wanted, come from podman under the
+   single-mapping constraint — with the explicit understanding that the
+   nested-container boundary carries no security weight. `root` in a
+   nested container is the agent user outside it.
+3. Nested containers are therefore a build/test convenience. The bottle
+   remains the security boundary, exactly as it was.

docs/research/smolmachines-as-vm-backend.md

@@ -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/landscape-containerized-claude.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/agent-sandbox-landscape.md`.
 
 Evaluation of whether [smolmachines](https://smolmachines.com/) would
 simplify the macOS agent-VM-isolation work spelled out in

pyproject.toml

@@ -1,6 +1,6 @@
 [build-system]
 requires = ["setuptools>=68"]
-build-backend = "setuptools.backends.legacy:build"
+build-backend = "setuptools.build_meta"
 
 [project]
 name = "bot-bottle"

scripts/coverage.sh

@@ -28,6 +28,7 @@ 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

tests/_bin.py

@@ -0,0 +1,23 @@
+"""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")

tests/_docker.py

@@ -30,3 +30,16 @@ 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)

tests/integration/test_gateway_image.py

@@ -86,13 +86,12 @@ class TestGatewayImage(unittest.TestCase):
         self.assertIn("Mitmproxy", out)
 
     def test_python_imports_supervise_module(self):
-        # 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).
+        # 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.
         rc, out = self._run_in_image(
             "python3", "-c",
-            "import supervise; import supervise_server; print('ok')",
+            "from bot_bottle import supervise, supervise_server; print('ok')",
         )
         self.assertEqual(0, rc, msg=out)
         self.assertIn("ok", out)

tests/integration/test_macos_rootless_podman_spike.py

@@ -0,0 +1,154 @@
+"""Live-Mac acceptance spike for guest-local rootless podman (issue #392).
+
+Run explicitly on an Apple Silicon/macOS 26 host:
+
+    BOT_BOTTLE_ROOTLESS_PODMAN_SPIKE=1 \
+      python3 -m unittest tests.integration.test_macos_rootless_podman_spike -v
+
+The opt-in is deliberate: ordinary Linux CI cannot execute Apple Container.
+
+Podman rather than Docker because Apple Container's capability bounding set
+omits CAP_SYS_ADMIN; see
+docs/research/rootless-docker-in-apple-container-spike.md.  The agent-facing
+surface is still `docker` and `docker compose`, which talk to podman's
+Docker-compatible API socket.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import tempfile
+import unittest
+from pathlib import Path
+
+from bot_bottle.backend import BottleSpec, get_bottle_backend
+from bot_bottle.manifest import ManifestIndex
+
+
+@unittest.skipUnless(
+    platform.system() == "Darwin"
+    and os.environ.get("BOT_BOTTLE_ROOTLESS_PODMAN_SPIKE") == "1",
+    "requires an explicit live-Mac rootless-podman spike run",
+)
+class TestMacosRootlessPodmanSpike(unittest.TestCase):
+    def test_compose_stays_inside_registered_bottle(self) -> None:
+        workspace = Path(tempfile.mkdtemp(prefix="rootless-podman-spike."))
+        stage = Path(tempfile.mkdtemp(prefix="rootless-podman-stage."))
+        try:
+            (workspace / "index.html").write_text("bottle-compose-ok\n")
+            (workspace / "compose.yaml").write_text(
+                "services:\n"
+                "  web:\n"
+                "    image: quay.io/prometheus/busybox\n"
+                "    working_dir: /workspace\n"
+                "    command: httpd -f -p 8000 -h /workspace\n"
+                "    volumes: ['.:/workspace']\n"
+                "    ports: ['18080:8000']\n",
+                encoding="utf-8",
+            )
+            manifest = ManifestIndex.from_json_obj({
+                "bottles": {"dev": {
+                    "docker_access": True,
+                    # A deliberately tiny image. Pulling a ~165MB one
+                    # OOM-kills the shared egress proxy, which buffers whole
+                    # response bodies to scan them — a real defect, but a
+                    # separate one from what this test covers. See the
+                    # research note.
+                    #
+                    # quay.io deliberately, not Docker Hub: the egress proxy
+                    # strips agent-set Authorization (so an agent cannot
+                    # smuggle a credential out in a header), and Docker Hub
+                    # requires a client-fetched, per-scope bearer token that
+                    # the strip therefore removes. quay serves manifests with
+                    # no Authorization at all, so a plain route is enough.
+                    #
+                    # token_patterns is still scoped off: registry traffic
+                    # carries bearer JWTs by protocol and trips the generic
+                    # rule. known_secrets stays on — it matches the bottle's
+                    # own credentials, which is the detector that catches
+                    # real exfil.
+                    "egress": {"routes": [
+                        {"host": "quay.io", "dlp": {
+                            "outbound_detectors": ["known_secrets"],
+                        }},
+                        {"host": "cdn01.quay.io", "dlp": {
+                            "outbound_detectors": ["known_secrets"],
+                        }},
+                    ]},
+                }},
+                "agents": {"spike": {
+                    "bottle": "dev", "skills": [], "prompt": "",
+                }},
+            })
+            spec = BottleSpec(
+                manifest=manifest,
+                agent_name="spike",
+                copy_cwd=True,
+                user_cwd=str(workspace),
+            )
+            backend = get_bottle_backend("macos-container")
+            plan = backend.prepare(spec, stage_dir=stage)
+            with backend.launch(plan) as bottle:
+                workdir = plan.workspace_plan.workdir
+                checks = (
+                    "docker info >/dev/null && docker compose version && "
+                    f"cd {workdir} && docker compose up -d --wait && "
+                    "curl --fail --silent http://127.0.0.1:18080/ | "
+                    "grep -q bottle-compose-ok"
+                )
+                result = bottle.exec(checks)
+                self.assertEqual(
+                    0, result.returncode,
+                    f"stdout={result.stdout!r}\nstderr={result.stderr!r}",
+                )
+                # podman's compat API reports rootlessness through its own
+                # native endpoint; the Docker-shaped SecurityOptions field does
+                # not carry it.
+                inspect = bottle.exec(
+                    "podman info --format '{{.Host.Security.Rootless}}'"
+                )
+                self.assertIn("true", inspect.stdout.lower())
+                self.assertEqual(
+                    0,
+                    bottle.exec(
+                        "test \"$(id -u)\" -ne 0"
+                    ).returncode,
+                    "the podman service must not be running as bottle root",
+                )
+                self.assertNotEqual(
+                    0,
+                    bottle.exec("test -S /var/run/docker.sock").returncode,
+                    "spike must never expose a host/rootful Docker socket",
+                )
+                # Asserted on an in-band marker, not on `docker run`'s exit
+                # code: podman 4.3.1's Docker-compat API swallows the
+                # container's status and returns 0 for everything, so an
+                # exit-code assertion here passes whether egress was blocked
+                # or wide open. That silent false pass is worse than no check
+                # at all, and it is exactly this check — the one proving a
+                # nested container cannot escape the egress path.
+                #
+                # busybox ships wget, so a failure here means egress was
+                # refused rather than the binary being absent.
+                direct = bottle.exec(
+                    "docker run --rm --env HTTP_PROXY= --env HTTPS_PROXY= "
+                    "--env http_proxy= --env https_proxy= "
+                    "quay.io/prometheus/busybox sh -c "
+                    "'wget -T 4 -qO- https://evil.example.com/ "
+                    "&& echo ESCAPED || echo CONTAINED'"
+                )
+                self.assertIn(
+                    "CONTAINED", direct.stdout,
+                    "an inner container obtained direct, unproxied egress: "
+                    f"stdout={direct.stdout!r} stderr={direct.stderr!r}",
+                )
+                self.assertNotIn("ESCAPED", direct.stdout)
+        finally:
+            shutil.rmtree(workspace, ignore_errors=True)
+            shutil.rmtree(stage, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/integration/test_sandbox_escape.py

@@ -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
+from tests._docker import skip_unless_docker_or_firecracker
 
 
 # Secrets planted in the bottle env as literals (agents substitute via
@@ -67,7 +67,7 @@ _DUMMY_HOST_KEY = (
 )
 
 
-@skip_unless_docker()
+@skip_unless_docker_or_firecracker()
 @unittest.skipIf(
     os.environ.get("GITEA_ACTIONS") == "true"
     and os.environ.get("BOT_BOTTLE_BACKEND") != "firecracker",
@@ -91,11 +91,9 @@ class TestSandboxEscape(unittest.TestCase):
 
     @classmethod
     def setUpClass(cls) -> None:
-        # 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.
+        # 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.
         cls._backend_name = os.environ.get("BOT_BOTTLE_BACKEND", "docker")
 
         # Throwaway static key for the git-gate fixture. It need not

tests/unit/test_backend_selection.py

@@ -57,14 +57,16 @@ class TestGetBottleBackend(unittest.TestCase):
                 return self._available
 
         # No macOS container and the host can't run firecracker (no
-        # KVM / not Linux) → docker is the last resort.
+        # KVM / not Linux) → docker fallback with a prompt. Simulate
+        # the user picking "d" (use docker anyway).
         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)
 
@@ -96,6 +98,145 @@ 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):

tests/unit/test_backend_setup.py

@@ -215,6 +215,18 @@ 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)

tests/unit/test_cli_cleanup_cross_backend.py

@@ -1,8 +1,10 @@
-"""Unit: `cli.py cleanup` walks every backend (issue follow-up).
+"""Unit: `cli.py cleanup` walks every available backend.
 
-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."""
+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."""
 
 from __future__ import annotations
 
@@ -21,7 +23,7 @@ def _make_backend(empty: bool = True):
 
 
 class TestCmdCleanup(unittest.TestCase):
-    def test_iterates_every_backend(self):
+    def test_iterates_every_available_backend(self):
         docker, docker_plan = _make_backend(empty=False)
         fc, fc_plan = _make_backend(empty=False)
         backends_by_name = {"docker": docker, "firecracker": fc}
@@ -32,6 +34,8 @@ 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,
         ):
@@ -42,6 +46,32 @@ 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)
@@ -53,6 +83,8 @@ 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:
@@ -72,6 +104,8 @@ 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,
         ):
@@ -92,6 +126,8 @@ 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,
         ):

tests/unit/test_cli_start_backend_flag.py

@@ -1,61 +1,29 @@
-"""Unit: `cli.py start --backend=<name>` flag (issue #77).
+"""Unit: backend resolution priority — explicit name > env var.
 
-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)."""
+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."""
 
 from __future__ import annotations
 
-import argparse
 import os
 import unittest
 from unittest.mock import patch
 
 
-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.
+class TestBackendResolutionPriority(unittest.TestCase):
+    def test_explicit_name_overrides_env_var(self):
         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()

tests/unit/test_cli_start_headless.py

@@ -175,14 +175,6 @@ 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):

tests/unit/test_cli_start_selector.py

@@ -82,7 +82,7 @@ class TestCmdStartSelector(unittest.TestCase):
     # ------------------------------------------------------------------
 
     def test_explicit_agent_skips_agent_picker(self):
-        rc = start_mod.cmd_start(["--backend=docker", "researcher"])
+        rc = start_mod.cmd_start(["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(["--backend=docker"])
+        rc = start_mod.cmd_start([])
         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(["--backend=docker"])
+        rc = start_mod.cmd_start([])
         self.assertEqual(0, rc)
         self._bottle_picker_mock.assert_not_called()
         self._launch_mock.assert_not_called()
@@ -168,16 +168,6 @@ 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:

tests/unit/test_db_store.py

@@ -0,0 +1,58 @@
+"""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()

tests/unit/test_docker_test_helpers.py

@@ -0,0 +1,35 @@
+"""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()

tests/unit/test_egress_multitenant.py

@@ -4,7 +4,14 @@ from __future__ import annotations
 
 import unittest
 
-from bot_bottle.egress_addon_core import resolve_client_config, resolve_client_context
+from bot_bottle.egress_addon_core import (
+    DENY_RESOLVER_ERROR,
+    DENY_UNATTRIBUTED,
+    DENY_UNPARSEABLE,
+    decide,
+    resolve_client_config,
+    resolve_client_context,
+)
 from bot_bottle.policy_resolver import PolicyResolveError
 
 
@@ -108,3 +115,55 @@ class TestResolveClientContext(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class TestDenyReasonNamesTheRealFault(unittest.TestCase):
+    """A deny-all must not masquerade as a missing allowlist entry.
+
+    Regression: an unregistered bottle resolves no policy, so *every* host is
+    denied — but the block message said `host X is not in the allowlist`,
+    which reads as a config problem and sends the operator hunting for a route
+    that was never missing. The structural reason wins over that wording.
+    """
+
+    def _reason(self, resolver: object, host: str = "chatgpt.com") -> str:
+        cfg = resolve_client_config(resolver, "10.243.0.1")  # type: ignore[arg-type]
+        return decide(cfg.routes, host, "/v1/x", {}, deny_reason=cfg.deny_reason).reason
+
+    def test_unattributed_says_unattributed_not_allowlist(self) -> None:
+        reason = self._reason(_FakeResolver(result=None))
+        self.assertEqual(DENY_UNATTRIBUTED, reason)
+        # The misleading claim is the one that must be gone: the host was
+        # never "not in the allowlist" — there was no allowlist at all.
+        self.assertNotIn("is not in the bottle's egress.routes allowlist", reason)
+        # Both causes must be named. `/resolve` fail-closes on a missing row
+        # *and* on a token mismatch, and the message pointing only at the row
+        # sent us hunting for a deregistered bottle that was registered fine.
+        self.assertIn("registry row", reason)
+        self.assertIn("identity token", reason)
+
+    def test_resolver_error_says_orchestrator_unreachable(self) -> None:
+        self.assertEqual(DENY_RESOLVER_ERROR, self._reason(_FakeResolver(raises=True)))
+
+    def test_unparseable_policy_says_so(self) -> None:
+        self.assertEqual(
+            DENY_UNPARSEABLE, self._reason(_FakeResolver(result="routes: notalist\n")))
+
+    def test_a_real_allowlist_miss_keeps_the_allowlist_wording(self) -> None:
+        """The message only changes for structural deny-alls — a loaded policy
+        that genuinely lacks the host still points at the allowlist."""
+        reason = self._reason(_FakeResolver(result='routes:\n  - host: "api.example.com"\n'))
+        self.assertIn("is not in the bottle's egress.routes allowlist", reason)
+        self.assertIn("chatgpt.com", reason)
+
+    def test_allowed_host_is_still_forwarded(self) -> None:
+        cfg = resolve_client_config(
+            _FakeResolver(result='routes:\n  - host: "api.example.com"\n'), "10.243.0.1")
+        decision = decide(
+            cfg.routes, "api.example.com", "/v1/x", {}, deny_reason=cfg.deny_reason)
+        self.assertEqual("forward", decision.action)
+
+    def test_a_parsed_policy_carries_no_deny_reason(self) -> None:
+        cfg = resolve_client_config(
+            _FakeResolver(result='routes:\n  - host: "api.example.com"\n'), "10.243.0.1")
+        self.assertEqual("", cfg.deny_reason)

tests/unit/test_firecracker_backend.py

@@ -35,9 +35,12 @@ 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)
-        self.assertEqual(("bbfc0", "100.64.0.0", "100.64.0.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"),
                          (s0.iface, s0.host_ip, s0.guest_ip))
-        self.assertEqual(("bbfc1", "100.64.0.2", "100.64.0.3"),
+        self.assertEqual((f"{pfx}1", "100.64.0.2", "100.64.0.3"),
                          (s1.iface, s1.host_ip, s1.guest_ip))
 
     def test_guest_cidr_is_31(self):
@@ -180,11 +183,14 @@ 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": "bbfc0"},
+                 {"dst": "10.243.0.0/31", "dev": netpool.slot(0).iface},
                  {"dst": "192.168.1.0/24", "dev": "enp4s0"},
              ]):
             self.assertEqual([], netpool.overlapping_routes())
@@ -203,7 +209,7 @@ class TestNetpoolAllocation(unittest.TestCase):
             # over (and here, exhaust the pool).
             slot, lock = netpool.allocate("first")
             self.addCleanup(lock.close)
-            self.assertEqual("bbfc0", slot.iface)
+            self.assertEqual(netpool.slot(0).iface, slot.iface)
             with patch.object(netpool, "die",
                               side_effect=SystemExit("exhausted")):
                 with self.assertRaises(SystemExit):
@@ -323,9 +329,14 @@ 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())
-        # 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)
+        # 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"])
 
     def test_env_var_overrides_the_shared_default(self):
         with patch.dict(os.environ, {"BOT_BOTTLE_FC_IP_BASE": "10.99.0.0"}):

tests/unit/test_firecracker_helpers.py

@@ -63,9 +63,12 @@ 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(["bbfc1"], netpool.missing_taps())
+            self.assertEqual([netpool.slot(1).iface], 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,

tests/unit/test_firecracker_image_builder.py

@@ -24,7 +24,7 @@ class TestBuildAgentRootfsDir(unittest.TestCase):
         self.addCleanup(self._tmp.cleanup)
 
     def test_cache_hit_skips_rebuild(self):
-        digest = image_builder._dockerfile_hash(self.dockerfile)
+        digest = image_builder._rootfs_digest(self.dockerfile)
         base = self.cache / "rootfs" / f"agent-{digest}"
         base.mkdir(parents=True)
         (base / ".bb-ready").write_text("ok\n")
@@ -55,6 +55,17 @@ 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):

tests/unit/test_firecracker_infra_vm.py

@@ -38,7 +38,9 @@ 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)
-        self.assertIn("gateway_init.py", 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("export PATH=", init)
         # Persistent registry volume mounted at the DB dir before the CP starts.
         self.assertIn("/dev/vdb", init)
@@ -98,7 +100,11 @@ 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.
-        with patch.object(infra_vm.docker_mod, "build_image") as build, \
+        # 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, \
                 patch.object(infra_vm.infra_artifact, "ensure_artifact_gz") as pull:
             infra_vm.ensure_built()
         build.assert_not_called()
@@ -138,27 +144,58 @@ class TestWaitForHealth(unittest.TestCase):
 
 
 class TestEnsureRunningSingleton(unittest.TestCase):
-    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()
+    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()
         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):
-        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()
+        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()
         stop.assert_called_once()      # clear a stale VM first
         built.assert_called_once()
         boot.assert_called_once()
@@ -185,5 +222,74 @@ 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()

tests/unit/test_gateway_init.py

@@ -2,8 +2,9 @@
 
 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 — short-lived, no docker required
-— so they run under `tests/unit/` rather than `tests/integration/`."""
+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/`."""
 
 from __future__ import annotations
 
@@ -14,6 +15,7 @@ import sys
 import time
 import unittest
 import warnings
+from pathlib import Path
 from unittest.mock import patch
 
 from bot_bottle.gateway_init import (
@@ -23,11 +25,7 @@ from bot_bottle.gateway_init import (
     _env_for_daemon,
     _selected_daemons,
 )
-
-# /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)")
+from tests._bin import SLEEP
 
 
 class TestEnvForDaemon(unittest.TestCase):
@@ -185,7 +183,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()
@@ -217,7 +215,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()
@@ -262,7 +260,7 @@ class TestSupervisor(unittest.TestCase):
         )
         specs = [
             _DaemonSpec("egress", sighup_marker),
-            _DaemonSpec("other",  _SLEEP_30),
+            _DaemonSpec("other",  (SLEEP, "30")),
         ]
         sup = _Supervisor(specs)
         sup.start_all()
@@ -285,7 +283,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")
@@ -297,8 +295,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()
@@ -322,8 +320,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()
@@ -346,7 +344,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)
@@ -369,7 +367,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")
@@ -379,7 +377,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")
@@ -388,7 +386,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")
@@ -398,7 +396,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)
@@ -416,8 +414,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()
@@ -452,7 +450,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)
@@ -468,22 +466,28 @@ class TestSupervisor(unittest.TestCase):
 
 class TestMainEndToEnd(unittest.TestCase):
     """Run gateway_init.py as a real subprocess to cover the
-    signal-handler installation path."""
+    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}")
 
     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 long-sleep commands.
+        DAEMONS list patched to harmless `sleep 30` 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"
-            "  si._DaemonSpec('alpha', sleep_cmd),\n"
-            "  si._DaemonSpec('beta',  sleep_cmd),\n"
+            f"  si._DaemonSpec('alpha', ({SLEEP!r},'30')),\n"
+            f"  si._DaemonSpec('beta',  ({SLEEP!r},'30')),\n"
             ")\n"
             "sys.exit(si.main([]))\n"
         )

tests/unit/test_infra_artifact.py

@@ -50,7 +50,12 @@ class _CacheMixin(unittest.TestCase):
         self._env = mock.patch.dict(
             os.environ,
             {"BOT_BOTTLE_FC_CACHE": self._tmp.name,
-             "BOT_BOTTLE_INFRA_ARTIFACT_TOKEN": ""},
+             "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": ""},
             clear=False,
         )
         self._env.start()
@@ -93,6 +98,31 @@ 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:
@@ -118,6 +148,58 @@ 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")

tests/unit/test_macos_consolidated_launch.py

@@ -87,7 +87,8 @@ class TestRegisterAgent(unittest.TestCase):
         *, source_ip: str = "192.168.128.9",
     ):
         with patch(f"{_MOD}.OrchestratorClient", return_value=client), \
-                patch(f"{_MOD}.provision_git_gate", provision or Mock()):
+                patch(f"{_MOD}.provision_git_gate", provision or Mock()), \
+                patch(f"{_MOD}.live_source_ips", return_value=[]):
             return register_agent(
                 _egress_plan(), _git_plan(),
                 source_ip=source_ip, endpoint=_endpoint(), image_ref="img:1",
@@ -134,3 +135,104 @@ class TestTeardown(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class TestLiveSourceIps(unittest.TestCase):
+    """The reconciliation input: the host enumerates its own bottles because
+    the orchestrator, inside the infra container, cannot see the backend."""
+
+    def _agents(self, *slugs: str) -> list[Mock]:
+        return [Mock(slug=s) for s in slugs]
+
+    def test_maps_slugs_to_container_addresses(self) -> None:
+        from bot_bottle.backend.macos_container.consolidated_launch import live_source_ips
+        with patch(f"{_MOD}.enumerate_active", return_value=self._agents("a", "b")), \
+                patch(f"{_MOD}.container_mod.inspect_container_network_ip",
+                      side_effect=["10.0.0.1", "10.0.0.2"]) as ip:
+            got = live_source_ips("net0")
+        self.assertEqual(["10.0.0.1", "10.0.0.2"], got)
+        self.assertEqual("bot-bottle-a", ip.call_args_list[0].args[0])
+
+    def test_containers_without_an_address_are_skipped(self) -> None:
+        """A container that hasn't been given a DHCP address yet contributes
+        nothing — the reap's grace window, not this list, protects it."""
+        from bot_bottle.backend.macos_container.consolidated_launch import live_source_ips
+        with patch(f"{_MOD}.enumerate_active", return_value=self._agents("a", "b")), \
+                patch(f"{_MOD}.container_mod.inspect_container_network_ip",
+                      side_effect=["", "10.0.0.2"]):
+            self.assertEqual(["10.0.0.2"], live_source_ips("net0"))
+
+    def test_container_list_failure_raises(self) -> None:
+        """If container list fails, the live set is not authoritative and
+        reconciliation must be skipped."""
+        from bot_bottle.backend.macos_container.consolidated_launch import live_source_ips
+        from bot_bottle.backend.macos_container.enumerate import EnumerationError
+        with patch(f"{_MOD}.enumerate_active",
+                   side_effect=EnumerationError("container list failed")):
+            with self.assertRaises(EnumerationError):
+                live_source_ips("net0")
+
+    def test_per_container_inspect_failure_raises(self) -> None:
+        """If any individual inspect fails, the live set is not authoritative."""
+        from bot_bottle.backend.macos_container.consolidated_launch import live_source_ips
+        from bot_bottle.backend.macos_container.enumerate import EnumerationError
+        with patch(f"{_MOD}.enumerate_active", return_value=self._agents("a", "b")), \
+                patch(f"{_MOD}.container_mod.inspect_container_network_ip",
+                      side_effect=["10.0.0.1", None]):
+            with self.assertRaises(EnumerationError):
+                live_source_ips("net0")
+
+
+class TestRegisterAgentReconciles(unittest.TestCase):
+    """Registration self-heals the registry first: an orphan row at a recycled
+    address makes attribution ambiguous, which resolves no policy at all and
+    denies every host for the bottle being launched."""
+
+    def _register(self, client: Mock) -> None:
+        with patch(f"{_MOD}.OrchestratorClient", return_value=client), \
+                patch(f"{_MOD}.provision_git_gate"), \
+                patch(f"{_MOD}.live_source_ips", return_value=["10.0.0.7"]):
+            register_agent(
+                _egress_plan(), _git_plan(),
+                source_ip="10.0.0.7", endpoint=_endpoint(),
+            )
+
+    def test_reconciles_before_registering(self) -> None:
+        client = _client()
+        calls: list[str] = []
+
+        def _reconcile(*_args: object, **_kwargs: object) -> list[str]:
+            calls.append("reconcile")
+            return []
+
+        def _register_bottle(*_args: object, **_kwargs: object) -> RegisteredBottle:
+            calls.append("register")
+            return RegisteredBottle("b1", "tok")
+
+        client.reconcile.side_effect = _reconcile
+        client.register_bottle.side_effect = _register_bottle
+        self._register(client)
+        self.assertEqual(["reconcile", "register"], calls)
+        client.reconcile.assert_called_once_with(["10.0.0.7"])
+
+    def test_a_reconcile_failure_does_not_block_the_launch(self) -> None:
+        from bot_bottle.orchestrator.client import OrchestratorClientError
+        client = _client()
+        client.reconcile.side_effect = OrchestratorClientError("unreachable")
+        self._register(client)
+        client.register_bottle.assert_called_once()
+
+    def test_enumeration_error_does_not_block_the_launch(self) -> None:
+        """A partial container listing must not abort the launch — skip
+        reconciliation and proceed, just as with an unreachable orchestrator."""
+        from bot_bottle.backend.macos_container.enumerate import EnumerationError
+        client = _client()
+        with patch(f"{_MOD}.OrchestratorClient", return_value=client), \
+                patch(f"{_MOD}.provision_git_gate"), \
+                patch(f"{_MOD}.live_source_ips",
+                      side_effect=EnumerationError("container list failed")):
+            register_agent(
+                _egress_plan(), _git_plan(),
+                source_ip="10.0.0.7", endpoint=_endpoint(),
+            )
+        client.register_bottle.assert_called_once()

tests/unit/test_macos_container_cleanup.py

@@ -66,8 +66,10 @@ class TestMacosContainerEnumerate(unittest.TestCase):
         agents = self._enumerate("bot-bottle-mac-infra\nbot-bottle-dev-abc\n")
         self.assertEqual(["dev-abc"], [a.slug for a in agents])
 
-    def test_empty_when_the_cli_fails(self):
-        self.assertEqual([], self._enumerate("", returncode=1))
+    def test_raises_when_the_cli_fails(self):
+        from bot_bottle.backend.macos_container.enumerate import EnumerationError
+        with self.assertRaises(EnumerationError):
+            self._enumerate("", returncode=1)
 
 
 if __name__ == "__main__":

tests/unit/test_macos_container_launch_wiring.py

@@ -17,11 +17,12 @@ 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.backend.macos_container.rootless_podman import guest_env
 from bot_bottle.manifest import ManifestIndex
 
 _BOTTLE = "bot_bottle.backend.macos_container.bottle"
@@ -76,6 +77,7 @@ def _plan(
         ),
         agent_git_gate_url=agent_git_gate_url,
         agent_supervise_url=agent_supervise_url,
+        docker_access=False,
     ))
 
 
@@ -104,19 +106,38 @@ class TestAgentRunArgv(unittest.TestCase):
         read back after start."""
         self.assertNotIn("--ip", 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_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_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("192.168.128.3", entry)
+        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)
 
     def test_forwarded_secrets_stay_off_argv(self) -> None:
         """Bare name → inherited from the run process env, so the value never
@@ -134,7 +155,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(
-            "http://bottle:s3cret@192.168.128.3:9099", env["HTTP_PROXY"],
+            f"http://bottle:s3cret@{GATEWAY_HOSTNAME}:9099", env["HTTP_PROXY"],
         )
         self.assertEqual(env["HTTP_PROXY"], env["https_proxy"])
 
@@ -159,6 +180,18 @@ class TestIdentityTokenDelivery(unittest.TestCase):
         self.assertNotIn("--env", argv)
 
 
+class TestRootlessPodmanEnvironment(unittest.TestCase):
+    def test_disabled_bottle_gets_no_docker_environment(self) -> None:
+        self.assertEqual({}, guest_env(False))
+
+    def test_enabled_bottle_uses_only_guest_local_socket(self) -> None:
+        env = guest_env(True)
+        self.assertEqual(
+            "unix:///tmp/bot-bottle-podman-run/podman.sock", env["DOCKER_HOST"],
+        )
+        self.assertNotIn("/var/run/docker.sock", " ".join(env.values()))
+
+
 class TestPlanIdentityToken(unittest.TestCase):
     """git-gate's gitconfig extraHeader and the supervise MCP --header read
     `getattr(plan, "identity_token", "")` at provision time and both bypass the
@@ -202,7 +235,7 @@ class TestPlanIdentityToken(unittest.TestCase):
         self.assertIn("HTTP_PROXY", argv)
         self.assertNotIn("s3cret", " ".join(argv))
         self.assertEqual(
-            "http://bottle:s3cret@192.168.128.3:9099", kwargs["env"]["HTTP_PROXY"],
+            f"http://bottle:s3cret@{GATEWAY_HOSTNAME}:9099", kwargs["env"]["HTTP_PROXY"],
         )
 
 

tests/unit/test_macos_container_util.py

@@ -272,6 +272,30 @@ 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="")
@@ -310,6 +334,50 @@ class TestInspectDigests(unittest.TestCase):
             self.assertEqual({}, util.container_env("x"))
 
 
+class TestInspectContainerNetworkIp(unittest.TestCase):
+    """inspect_container_network_ip must distinguish inspect failure (None)
+    from 'no DHCP address yet' (""), which is the invariant live_source_ips
+    relies on to skip reconciliation on partial snapshots."""
+
+    _NETWORK = "bot-bottle-mac-gateway"
+
+    def _inspect(self, stdout: str, returncode: int = 0) -> str | None:
+        cp = util.subprocess.CompletedProcess(
+            args=[], returncode=returncode, stdout=stdout, stderr="",
+        )
+        with patch.object(util.subprocess, "run", return_value=cp):
+            return util.inspect_container_network_ip("bot-bottle-abc", self._NETWORK)
+
+    def _entry(self, ip: str = "192.168.128.5") -> str:
+        return (
+            f'[{{"status":{{"networks":['
+            f'{{"network":"{self._NETWORK}","ipv4Address":"{ip}"}}'
+            f']}}}}]'
+        )
+
+    def test_returns_ip_when_inspect_succeeds(self) -> None:
+        self.assertEqual("192.168.128.5", self._inspect(self._entry()))
+
+    def test_strips_cidr_prefix(self) -> None:
+        self.assertEqual("192.168.128.5", self._inspect(self._entry("192.168.128.5/24")))
+
+    def test_returns_empty_string_when_no_address_assigned_yet(self) -> None:
+        no_ip = f'[{{"status":{{"networks":[{{"network":"{self._NETWORK}","ipv4Address":""}}]}}}}]'
+        self.assertEqual("", self._inspect(no_ip))
+
+    def test_returns_empty_string_when_network_list_absent(self) -> None:
+        self.assertEqual("", self._inspect('[{"status":{}}]'))
+
+    def test_returns_none_on_nonzero_exit(self) -> None:
+        self.assertIsNone(self._inspect("", returncode=1))
+
+    def test_returns_none_on_malformed_json(self) -> None:
+        self.assertIsNone(self._inspect("not-json"))
+
+    def test_returns_none_on_unexpected_json_shape(self) -> None:
+        self.assertIsNone(self._inspect("null"))
+
+
 class TestWaitContainerIpv4(unittest.TestCase):
     def test_returns_address_once_dhcp_assigns_it(self):
         with patch.object(util, "try_container_ipv4_on_network", side_effect=["", "", "192.168.128.4"]), \

tests/unit/test_macos_gateway_hosts.py

@@ -0,0 +1,140 @@
+"""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()

tests/unit/test_macos_infra.py

@@ -46,7 +46,9 @@ class TestInfraRun(unittest.TestCase):
         argv = self._run_container(MacosInfraService(repo_root=Path("/r")))
         script = argv[-1]
         self.assertIn("bot_bottle.orchestrator", script)
-        self.assertIn("gateway_init.py", 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("127.0.0.1", script)  # they reach each other on loopback
 
     def test_db_is_a_container_only_volume(self) -> None:

tests/unit/test_macos_rootless_podman.py

@@ -0,0 +1,147 @@
+"""Unit coverage for the fail-closed macOS rootless-podman spike."""
+
+from __future__ import annotations
+
+import unittest
+from dataclasses import dataclass
+from pathlib import Path
+from types import SimpleNamespace
+from typing import cast
+from unittest.mock import patch
+
+from bot_bottle.backend.macos_container import rootless_podman
+from bot_bottle.backend.macos_container import launch as launch_mod
+from bot_bottle.backend.macos_container.bottle_plan import MacosContainerBottlePlan
+
+
+class _Bottle:
+    def __init__(self, results: list[SimpleNamespace]) -> None:
+        self.results = results
+        self.commands: list[str] = []
+
+    def exec(self, command: str) -> SimpleNamespace:
+        self.commands.append(command)
+        return self.results.pop(0)
+
+
+def _result(returncode: int, *, stdout: str = "", stderr: str = "") -> SimpleNamespace:
+    return SimpleNamespace(returncode=returncode, stdout=stdout, stderr=stderr)
+
+
+@dataclass(frozen=True)
+class _AgentProvision:
+    image: str
+
+
+@dataclass(frozen=True)
+class _Plan:
+    slug: str
+    image: str
+    dockerfile_path: str
+    docker_access: bool
+    agent_provision: _AgentProvision
+
+
+class TestRootlessPodmanStart(unittest.TestCase):
+    def test_bootstraps_then_waits_for_guest_local_service(self) -> None:
+        bottle = _Bottle([_result(0), _result(1), _result(0)])
+        with patch.object(rootless_podman.time, "sleep"):
+            rootless_podman.start(bottle)
+        self.assertIn("rootless-podman-init", bottle.commands[0])
+        self.assertEqual(2, bottle.commands.count("docker info >/dev/null 2>&1"))
+
+    def test_bootstrap_failure_is_fatal_without_privilege_fallback(self) -> None:
+        bottle = _Bottle([_result(1, stderr="slirp4netns missing")])
+        with patch.object(rootless_podman, "die", side_effect=RuntimeError) as die:
+            with self.assertRaises(RuntimeError):
+                rootless_podman.start(bottle)
+        self.assertIn("slirp4netns missing", die.call_args.args[0])
+        self.assertEqual(1, len(bottle.commands))
+
+    def test_timeout_reports_guest_log(self) -> None:
+        bottle = _Bottle(
+            [_result(0)]
+            + [_result(1) for _ in range(rootless_podman.READY_RETRIES)]
+            + [_result(0, stdout="operation not permitted")]
+        )
+        with patch.object(rootless_podman.time, "sleep"), \
+             patch.object(rootless_podman, "die", side_effect=RuntimeError) as die:
+            with self.assertRaises(RuntimeError):
+                rootless_podman.start(bottle)
+        self.assertIn("operation not permitted", die.call_args.args[0])
+
+
+class TestRootlessPodmanDevices(unittest.TestCase):
+    def test_relaxes_only_the_two_blocked_device_nodes_as_root(self) -> None:
+        calls: list[tuple[str, list[str]]] = []
+        rootless_podman.prepare_guest_devices(
+            "bottle-1", lambda name, argv: calls.append((name, argv)),
+        )
+        self.assertEqual(1, len(calls))
+        name, argv = calls[0]
+        self.assertEqual("bottle-1", name)
+        self.assertIn("chmod 0666 /dev/fuse /dev/net/tun", argv[-1])
+
+
+class TestRootlessPodmanImage(unittest.TestCase):
+    def test_layers_tooling_without_changing_base_image(self) -> None:
+        calls: list[tuple[str, str, str]] = []
+
+        def build(image: str, context: str, *, dockerfile: str) -> None:
+            calls.append((image, context, dockerfile))
+            text = Path(dockerfile).read_text(encoding="utf-8")
+            self.assertIn("FROM agent:base", text)
+            self.assertIn("podman fuse-overlayfs slirp4netns uidmap", text)
+            self.assertIn("USER node", text)
+            self.assertTrue((Path(context) / "rootless-podman-init.sh").is_file())
+
+        image = rootless_podman.build_image("agent:base", build)
+        self.assertEqual("agent:base-rootless-podman", image)
+        self.assertEqual("agent:base-rootless-podman", calls[0][0])
+
+    def test_strips_subordinate_ranges_so_podman_avoids_newuidmap(self) -> None:
+        """The single-UID fallback is the entire reason podman works here.
+
+        A subordinate range would send podman down the newuidmap path, which
+        cannot write a multi-range uid_map without CAP_SYS_ADMIN in an Apple
+        Container guest — the failure that killed the rootless-Docker spike.
+        """
+        seen: list[str] = []
+
+        def build(image: str, context: str, *, dockerfile: str) -> None:
+            seen.append(Path(dockerfile).read_text(encoding="utf-8"))
+
+        rootless_podman.build_image("agent:base", build)
+        text = seen[0]
+        self.assertIn("sed -i '/^node:/d' /etc/subuid /etc/subgid", text)
+        self.assertNotIn("subuid", text.replace(
+            "sed -i '/^node:/d' /etc/subuid /etc/subgid", "",
+        ))
+
+    def test_launch_builds_base_then_rootless_variant(self) -> None:
+        plan = cast(MacosContainerBottlePlan, cast(object, _Plan(
+            slug="dev-abc",
+            image="agent:base",
+            dockerfile_path="/repo/Dockerfile",
+            docker_access=True,
+            agent_provision=_AgentProvision(image="agent:base"),
+        )))
+        with patch.object(launch_mod, "read_committed_image", return_value=None), \
+             patch.object(launch_mod.container_mod, "build_image") as build, \
+             patch.object(
+                 launch_mod.rootless_podman,
+                 "build_image",
+                 return_value="agent:base-rootless-podman",
+             ) as build_rootless:
+            result = launch_mod._build_images(plan)  # pylint: disable=protected-access
+
+        build.assert_called_once_with(
+            "agent:base", launch_mod._REPO_DIR,  # pylint: disable=protected-access
+            dockerfile="/repo/Dockerfile",
+        )
+        build_rootless.assert_called_once_with("agent:base", build)
+        self.assertEqual("agent:base-rootless-podman", result.agent_provision.image)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_manifest_bottle_merge.py

@@ -56,6 +56,12 @@ class TestMergeBottlesRuntime(unittest.TestCase):
         result = merge_bottles_runtime([base, override])
         self.assertFalse(result.supervise)
 
+    def test_docker_access_later_wins(self):
+        result = merge_bottles_runtime([
+            _bottle(docker_access=False), _bottle(docker_access=True),
+        ])
+        self.assertTrue(result.docker_access)
+
     def test_three_bottles_merged_left_to_right(self):
         b1 = _bottle(env={"A": "1", "B": "1", "C": "1"})
         b2 = _bottle(env={"B": "2", "C": "2"})

tests/unit/test_manifest_validation.py

@@ -44,13 +44,20 @@ class TestBottleValidation(unittest.TestCase):
         with self.assertRaises(ManifestError):
             ManifestBottle.from_dict("b", {"supervise": "yes"})
 
+    def test_docker_access_not_bool(self) -> None:
+        with self.assertRaises(ManifestError):
+            ManifestBottle.from_dict("b", {"docker_access": "yes"})
+
     def test_removed_runtime_field(self) -> None:
         with self.assertRaises(ManifestError):
             ManifestBottle.from_dict("b", {"runtime": "runsc"})
 
     def test_valid_minimal(self) -> None:
-        b = ManifestBottle.from_dict("b", {"supervise": False, "env": {"X": "1"}})
+        b = ManifestBottle.from_dict(
+            "b", {"supervise": False, "docker_access": True, "env": {"X": "1"}},
+        )
         self.assertFalse(b.supervise)
+        self.assertTrue(b.docker_access)
         self.assertEqual({"X": "1"}, dict(b.env))
 
 

tests/unit/test_orchestrator_client.py

@@ -104,3 +104,32 @@ class TestHealthAndPolicy(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class TestReconcile(unittest.TestCase):
+    def setUp(self) -> None:
+        self.c = OrchestratorClient("http://orch:8080")
+
+    def test_posts_live_ips_and_returns_reaped(self) -> None:
+        with patch(_URLOPEN, return_value=_resp(200, {"reaped": ["b1", "b2"]})) as m:
+            got = self.c.reconcile(["10.0.0.2", "10.0.0.3"])
+        self.assertEqual(["b1", "b2"], got)
+        sent = json.loads(m.call_args.args[0].data)
+        self.assertEqual(["10.0.0.2", "10.0.0.3"], sent["live_source_ips"])
+        self.assertNotIn("grace_seconds", sent)  # omitted -> server default
+
+    def test_grace_seconds_is_forwarded_when_given(self) -> None:
+        with patch(_URLOPEN, return_value=_resp(200, {"reaped": []})) as m:
+            self.c.reconcile([], grace_seconds=30)
+        self.assertEqual(30, json.loads(m.call_args.args[0].data)["grace_seconds"])
+
+    def test_malformed_reaped_is_tolerated(self) -> None:
+        with patch(_URLOPEN, return_value=_resp(200, {"reaped": ["ok", 5, None]})):
+            self.assertEqual(["ok"], self.c.reconcile([]))
+        with patch(_URLOPEN, return_value=_resp(200, {})):
+            self.assertEqual([], self.c.reconcile([]))
+
+    def test_error_status_raises(self) -> None:
+        with patch(_URLOPEN, side_effect=_http_error(500)):
+            with self.assertRaises(OrchestratorClientError):
+                self.c.reconcile([])

tests/unit/test_orchestrator_config_store.py

@@ -0,0 +1,147 @@
+"""Unit: OrchestratorConfigStore and resolve_teardown_timeout.
+
+Also verifies the lifecycle ordering invariant: resolve_teardown_timeout()
+must be called before launch_consolidated() / register_agent() so that a
+resolver failure cannot leave an orphaned registration with no teardown
+callback.
+"""
+
+from __future__ import annotations
+
+import inspect
+import os
+import tempfile
+import unittest
+from pathlib import Path
+from types import ModuleType
+
+from bot_bottle.orchestrator.config_store import (
+    DEFAULT_TEARDOWN_TIMEOUT_SECONDS,
+    TEARDOWN_TIMEOUT_ENV,
+    OrchestratorConfigStore,
+    resolve_teardown_timeout,
+)
+
+
+class TestOrchestratorConfigStore(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.db = Path(self._tmp.name) / "test.db"
+        self.store = OrchestratorConfigStore(self.db)
+        self.store.migrate()
+
+    def tearDown(self) -> None:
+        self._tmp.cleanup()
+
+    def test_get_returns_none_when_not_set(self) -> None:
+        self.assertIsNone(self.store.get_teardown_timeout_seconds())
+
+    def test_set_and_get_roundtrip(self) -> None:
+        self.store.set_teardown_timeout_seconds(42.5)
+        self.assertEqual(42.5, self.store.get_teardown_timeout_seconds())
+
+    def test_set_overwrites_existing_value(self) -> None:
+        self.store.set_teardown_timeout_seconds(10.0)
+        self.store.set_teardown_timeout_seconds(20.0)
+        self.assertEqual(20.0, self.store.get_teardown_timeout_seconds())
+
+    def test_delete_clears_value_and_returns_true(self) -> None:
+        self.store.set_teardown_timeout_seconds(30.0)
+        deleted = self.store.delete_teardown_timeout_seconds()
+        self.assertTrue(deleted)
+        self.assertIsNone(self.store.get_teardown_timeout_seconds())
+
+    def test_delete_absent_returns_false(self) -> None:
+        self.assertFalse(self.store.delete_teardown_timeout_seconds())
+
+    def test_is_migrated_true_after_migrate(self) -> None:
+        self.assertTrue(self.store.is_migrated())
+
+    def test_is_migrated_false_before_migrate(self) -> None:
+        store = OrchestratorConfigStore(Path(self._tmp.name) / "new.db")
+        self.assertFalse(store.is_migrated())
+
+
+class TestResolveTeardownTimeout(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.db = Path(self._tmp.name) / "cfg.db"
+
+    def tearDown(self) -> None:
+        self._tmp.cleanup()
+        os.environ.pop(TEARDOWN_TIMEOUT_ENV, None)
+
+    def test_returns_default_when_nothing_configured(self) -> None:
+        self.assertEqual(
+            DEFAULT_TEARDOWN_TIMEOUT_SECONDS,
+            resolve_teardown_timeout(self.db),
+        )
+
+    def test_env_var_overrides_default(self) -> None:
+        os.environ[TEARDOWN_TIMEOUT_ENV] = "99"
+        self.assertEqual(99.0, resolve_teardown_timeout(self.db))
+
+    def test_env_var_overrides_db_value(self) -> None:
+        store = OrchestratorConfigStore(self.db)
+        store.migrate()
+        store.set_teardown_timeout_seconds(55.0)
+        os.environ[TEARDOWN_TIMEOUT_ENV] = "77"
+        self.assertEqual(77.0, resolve_teardown_timeout(self.db))
+
+    def test_db_value_overrides_default(self) -> None:
+        store = OrchestratorConfigStore(self.db)
+        store.migrate()
+        store.set_teardown_timeout_seconds(42.0)
+        self.assertEqual(42.0, resolve_teardown_timeout(self.db))
+
+    def test_invalid_env_var_falls_through_to_default(self) -> None:
+        os.environ[TEARDOWN_TIMEOUT_ENV] = "not-a-number"
+        self.assertEqual(DEFAULT_TEARDOWN_TIMEOUT_SECONDS, resolve_teardown_timeout(self.db))
+
+    def test_non_positive_env_var_falls_through_to_default(self) -> None:
+        os.environ[TEARDOWN_TIMEOUT_ENV] = "0"
+        self.assertEqual(DEFAULT_TEARDOWN_TIMEOUT_SECONDS, resolve_teardown_timeout(self.db))
+
+    def test_non_positive_db_value_falls_through_to_default(self) -> None:
+        store = OrchestratorConfigStore(self.db)
+        store.migrate()
+        store.set_teardown_timeout_seconds(0.0)
+        self.assertEqual(DEFAULT_TEARDOWN_TIMEOUT_SECONDS, resolve_teardown_timeout(self.db))
+
+    def test_migrates_db_on_first_call(self) -> None:
+        result = resolve_teardown_timeout(self.db)
+        self.assertEqual(DEFAULT_TEARDOWN_TIMEOUT_SECONDS, result)
+        self.assertTrue(OrchestratorConfigStore(self.db).is_migrated())
+
+
+class TestTeardownTimeoutResolvedBeforeRegistration(unittest.TestCase):
+    """Ordering invariant: if resolve_teardown_timeout() raises, the bottle
+    must not yet be registered — no orphaned state can result."""
+
+    def _src(self, module: ModuleType) -> str:
+        return inspect.getsource(module)
+
+    def test_docker_resolves_timeout_before_launch_consolidated(self) -> None:
+        from bot_bottle.backend.docker import launch
+        src = self._src(launch)
+        resolve_at = src.index("teardown_timeout = resolve_teardown_timeout()")
+        launch_at = src.index("ctx = launch_consolidated(")
+        self.assertLess(resolve_at, launch_at)
+
+    def test_firecracker_resolves_timeout_before_launch_consolidated(self) -> None:
+        from bot_bottle.backend.firecracker import launch
+        src = self._src(launch)
+        resolve_at = src.index("teardown_timeout = resolve_teardown_timeout()")
+        launch_at = src.index("ctx = launch_consolidated(")
+        self.assertLess(resolve_at, launch_at)
+
+    def test_macos_resolves_timeout_before_register_agent(self) -> None:
+        from bot_bottle.backend.macos_container import launch
+        src = self._src(launch)
+        resolve_at = src.index("teardown_timeout = resolve_teardown_timeout()")
+        register_at = src.index("ctx = register_agent(")
+        self.assertLess(resolve_at, register_at)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_orchestrator_control_plane.py

@@ -8,11 +8,13 @@ from __future__ import annotations
 
 import json
 import secrets
+import sqlite3
 import tempfile
 import threading
 import unittest
 import urllib.error
 import urllib.request
+from contextlib import closing
 from pathlib import Path
 from unittest.mock import patch
 
@@ -264,6 +266,7 @@ class TestControlPlaneAuth(unittest.TestCase):
             ("POST", "/bottles", _body({"source_ip": "10.0.0.1"})),
             ("PUT", "/bottles/x/policy", _body({"policy": "routes: []"})),
             ("DELETE", "/bottles/x", b""),
+            ("POST", "/reconcile", _body({"live_source_ips": []})),
             ("POST", "/resolve", _body({"source_ip": "10.0.0.1", "identity_token": "t"})),
             ("POST", "/attribute", _body({"source_ip": "10.0.0.1", "identity_token": "t"})),
             ("GET", "/supervise/proposals", b""),
@@ -387,3 +390,56 @@ class TestDispatchSupervise(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class TestReconcileRoute(unittest.TestCase):
+    """`POST /reconcile` — the host tells the orchestrator which bottles are
+    actually up, since the orchestrator can't see the backend from inside the
+    infra container."""
+
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.orch = _orchestrator(Path(self._tmp.name) / "r.db")
+
+    def tearDown(self) -> None:
+        self._tmp.cleanup()
+
+    def _old(self, source_ip: str) -> str:
+        rec = self.orch.registry.register(source_ip)
+        with closing(sqlite3.connect(self.orch.registry.db_path)) as conn:
+            conn.execute(
+                "UPDATE orchestrator_bottles SET created_at = 0.0 WHERE bottle_id = ?",
+                (rec.bottle_id,))
+            conn.commit()
+        return rec.bottle_id
+
+    def test_reaps_absent_and_reports_ids(self) -> None:
+        dead = self._old("10.0.0.1")
+        alive = self._old("10.0.0.2")
+        status, payload = dispatch(
+            self.orch, "POST", "/reconcile", _body({"live_source_ips": ["10.0.0.2"]}))
+        self.assertEqual(200, status)
+        self.assertEqual([dead], payload["reaped"])
+        self.assertIsNone(self.orch.registry.get(dead))
+        self.assertIsNotNone(self.orch.registry.get(alive))
+
+    def test_missing_live_source_ips_is_400(self) -> None:
+        status, _ = dispatch(self.orch, "POST", "/reconcile", _body({}))
+        self.assertEqual(400, status)
+
+    def test_grace_seconds_is_honoured(self) -> None:
+        """A grace window wide enough to cover the row protects it."""
+        self.orch.registry.register("10.0.0.3")
+        status, payload = dispatch(
+            self.orch, "POST", "/reconcile",
+            _body({"live_source_ips": [], "grace_seconds": 3600}))
+        self.assertEqual(200, status)
+        self.assertEqual([], payload["reaped"])
+
+    def test_non_string_entries_are_ignored(self) -> None:
+        dead = self._old("10.0.0.4")
+        status, payload = dispatch(
+            self.orch, "POST", "/reconcile",
+            _body({"live_source_ips": [None, 7, "10.0.0.9"]}))
+        self.assertEqual(200, status)
+        self.assertEqual([dead], payload["reaped"])

tests/unit/test_orchestrator_registry.py

@@ -4,7 +4,9 @@ from __future__ import annotations
 
 import sqlite3
 import tempfile
+import time
 import unittest
+from contextlib import closing
 from pathlib import Path
 
 from bot_bottle.orchestrator.registry import (
@@ -169,3 +171,81 @@ class TestRegistryStore(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class TestReapAbsent(unittest.TestCase):
+    """`reap_absent` — the self-heal for rows whose bottle is gone.
+
+    An orphan is not merely untidy: source IPs get recycled, and
+    `by_source_ip` fail-closes on ambiguity, so a leftover row at a reused
+    address resolves *no* policy for the next bottle that lands there and
+    every host it asks for is denied.
+    """
+
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.db = Path(self._tmp.name) / "registry.db"
+        self.store = RegistryStore(self.db)
+        self.store.migrate()
+
+    def tearDown(self) -> None:
+        self._tmp.cleanup()
+
+    def _aged(self, source_ip: str, *, age: float) -> BottleRecord:
+        """Register a bottle and backdate it past the grace window."""
+        rec = self.store.register(source_ip)
+        with closing(sqlite3.connect(self.db)) as conn:
+            conn.execute(
+                "UPDATE orchestrator_bottles SET created_at = ? WHERE bottle_id = ?",
+                (time.time() - age, rec.bottle_id),
+            )
+            conn.commit()
+        return rec
+
+    def test_reaps_row_with_no_live_container(self) -> None:
+        gone = self._aged("10.243.0.9", age=600)
+        reaped = self.store.reap_absent([])
+        self.assertEqual([gone.bottle_id], [r.bottle_id for r in reaped])
+        self.assertIsNone(self.store.get(gone.bottle_id))
+
+    def test_keeps_row_whose_ip_is_live(self) -> None:
+        alive = self._aged("10.243.0.9", age=600)
+        self.assertEqual([], self.store.reap_absent(["10.243.0.9"]))
+        self.assertIsNotNone(self.store.get(alive.bottle_id))
+
+    def test_grace_window_protects_an_in_flight_launch(self) -> None:
+        """A bottle registered moments ago is never reaped, even though the
+        caller's enumeration didn't see its address yet."""
+        fresh = self.store.register("10.243.0.10")
+        self.assertEqual([], self.store.reap_absent([]))
+        self.assertIsNotNone(self.store.get(fresh.bottle_id))
+
+    def test_reaping_the_orphan_unbricks_the_reused_address(self) -> None:
+        """The regression this exists for: an orphan at an address that vmnet
+        later hands to a new bottle makes `by_source_ip` ambiguous, so the new
+        bottle resolves no policy at all."""
+        orphan = self._aged("10.243.0.11", age=600)
+        # A new bottle lands on the recycled address. Force the row in directly
+        # so `register`'s own supersede sweep doesn't mask the ambiguity.
+        with closing(sqlite3.connect(self.db)) as conn:
+            conn.execute(
+                "INSERT INTO orchestrator_bottles "
+                "(bottle_id, source_ip, identity_token, state, created_at, metadata, policy) "
+                "VALUES ('newbottle', '10.243.0.11', 'tok-new', 'active', ?, '', 'routes: []')",
+                (time.time(),),
+            )
+            conn.commit()
+        self.assertIsNone(self.store.by_source_ip("10.243.0.11"))  # bricked
+
+        reaped = self.store.reap_absent(["10.243.0.11"], grace_seconds=60)
+        self.assertEqual([orphan.bottle_id], [r.bottle_id for r in reaped])
+        rec = self.store.by_source_ip("10.243.0.11")
+        assert rec is not None
+        self.assertEqual("newbottle", rec.bottle_id)
+
+    def test_ignores_empty_ips_in_the_live_set(self) -> None:
+        gone = self._aged("10.243.0.12", age=600)
+        self.assertEqual(
+            [gone.bottle_id],
+            [r.bottle_id for r in self.store.reap_absent(["", "10.243.0.99"])],
+        )

tests/unit/test_orchestrator_service.py

@@ -4,8 +4,10 @@ from __future__ import annotations
 
 import json
 import secrets
+import sqlite3
 import tempfile
 import unittest
+from contextlib import closing
 from pathlib import Path
 from unittest.mock import patch
 
@@ -304,3 +306,55 @@ class TestOrchestratorSupervise(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class TestOrchestratorReconcile(unittest.TestCase):
+    """`reconcile` — drop rows for bottles that are no longer running."""
+
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.secret = secrets.token_bytes(16)
+        self.db = Path(self._tmp.name) / "r.db"
+        self.store = RegistryStore(self.db)
+        self.store.migrate()
+        self.broker = StubBroker(self.secret)
+        self.orch = Orchestrator(self.store, self.broker, self.secret)
+
+    def tearDown(self) -> None:
+        self._tmp.cleanup()
+
+    def _age_all(self, seconds: float) -> None:
+        """Backdate every row past the reap grace window."""
+        with closing(sqlite3.connect(self.db)) as conn:
+            conn.execute(
+                "UPDATE orchestrator_bottles SET created_at = created_at - ?", (seconds,))
+            conn.commit()
+
+    def test_reaps_dead_bottle_and_forgets_its_tokens(self) -> None:
+        dead = self.orch.launch_bottle("10.243.0.1", tokens={"EGRESS_TOKEN_0": "s3cret"})
+        live = self.orch.launch_bottle("10.243.0.2", tokens={"EGRESS_TOKEN_0": "keep"})
+        self._age_all(600)
+
+        self.assertEqual([dead.bottle_id], self.orch.reconcile(["10.243.0.2"]))
+        self.assertIsNone(self.store.get(dead.bottle_id))
+        self.assertIsNotNone(self.store.get(live.bottle_id))
+        # The in-memory egress credential goes with the row.
+        self.assertEqual({}, self.orch.tokens_for(dead.bottle_id))
+        self.assertEqual({"EGRESS_TOKEN_0": "keep"}, self.orch.tokens_for(live.bottle_id))
+
+    def test_reconcile_does_not_broker_a_teardown(self) -> None:
+        """The container is already gone — there is nothing to stop, and a
+        broker error must not stop the sweep clearing the row."""
+        self.orch.launch_bottle("10.243.0.1")
+        self._age_all(600)
+        self.broker.launched.clear()
+        self.orch.reconcile([])
+        self.assertEqual([], self.broker.torn_down)
+
+    def test_reconcile_keeps_everything_when_all_are_live(self) -> None:
+        a = self.orch.launch_bottle("10.243.0.1")
+        b = self.orch.launch_bottle("10.243.0.2")
+        self._age_all(600)
+        self.assertEqual([], self.orch.reconcile(["10.243.0.1", "10.243.0.2"]))
+        self.assertIsNotNone(self.store.get(a.bottle_id))
+        self.assertIsNotNone(self.store.get(b.bottle_id))

tests/unit/test_publish_infra.py

@@ -6,8 +6,11 @@ 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
@@ -58,5 +61,99 @@ 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()

tests/unit/test_supervise_server.py

@@ -32,7 +32,9 @@ from bot_bottle.supervise_server import (
     _RpcError,
     _RpcInternalError,
     _response_timeout_from_env,
+    format_pending_response_text,
     format_response_text,
+    handle_check_proposal,
     handle_initialize,
     handle_tools_call,
     handle_tools_list,
@@ -218,6 +220,7 @@ class TestHandleToolsList(unittest.TestCase):
                 _sv.TOOL_EGRESS_ALLOW,
                 _sv.TOOL_EGRESS_BLOCK,
                 _sv.TOOL_LIST_EGRESS_ROUTES,
+                _sv.TOOL_CHECK_PROPOSAL,
             ]),
             sorted(names),
         )
@@ -484,9 +487,10 @@ class TestFormatResponseText(unittest.TestCase):
 
 class TestFormatPendingResponseText(unittest.TestCase):
     def test_formats_timeout_message(self):
-        text = supervise_server.format_pending_response_text(12.5)
+        text = supervise_server.format_pending_response_text("prop-9", 12.5)
         self.assertIn("status: pending", text)
         self.assertIn("12.5s", text)
+        self.assertIn("proposal_id: prop-9", text)
 
 
 # --- End-to-end HTTP sanity ------------------------------------------------
@@ -685,5 +689,129 @@ class TestResolvedRoutesPayload(unittest.TestCase):
             _handler(None)._resolved_routes_payload()
 
 
+class TestNonBlockingSupervise(unittest.TestCase):
+    """PRD prd-new / issue #412: pending responses carry the proposal id, and
+    `check-proposal` polls a queued proposal without blocking or re-proposing."""
+
+    _ROUTES = "routes:\n  - host: example.com\n"
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory(prefix="supervise-nonblock-test.")
+        self._home_patch = use_bottle_root(Path(self._tmp.name) / ".bot-bottle")
+        self.config = ServerConfig(bottle_slug="dev")
+        _qs.QueueStore("dev").migrate()
+        _as.AuditStore().migrate()
+
+    def tearDown(self):
+        self._home_patch()
+        self._tmp.cleanup()
+
+    def _seed_proposal(self) -> "_sv.Proposal":
+        p = _sv.Proposal.new(
+            bottle_slug="dev",
+            tool=_sv.TOOL_EGRESS_ALLOW,
+            proposed_file=self._ROUTES,
+            justification="need example.com",
+            current_file_hash=_sv.sha256_hex(self._ROUTES),
+        )
+        _sv.write_proposal(p)
+        return p
+
+    def _check(self, proposal_id: str) -> dict[str, object]:
+        return handle_check_proposal({"arguments": {"proposal_id": proposal_id}}, self.config)
+
+    # --- pending response carries the id ---
+
+    def test_pending_text_includes_id_and_pointer(self):
+        text = format_pending_response_text("abc-123", 30.0)
+        self.assertIn("status: pending", text)
+        self.assertIn("proposal_id: abc-123", text)
+        self.assertIn("check-proposal", text)
+
+    def test_tools_call_timeout_returns_pending_with_id_and_stays_queued(self):
+        # No responder → the grace window expires → pending, not blocked forever.
+        result = handle_tools_call(
+            {
+                "name": _sv.TOOL_EGRESS_ALLOW,
+                "arguments": {"routes_yaml": self._ROUTES, "justification": "x"},
+            },
+            ServerConfig(bottle_slug="dev", response_timeout_seconds=0.05),
+        )
+        self.assertFalse(result["isError"])  # type: ignore[index]
+        text = result["content"][0]["text"]  # type: ignore[index]
+        self.assertIn("status: pending", text)
+        pending = _sv.list_pending_proposals("dev")
+        self.assertEqual(1, len(pending))  # still queued, not archived
+        self.assertIn(pending[0].id, text)  # agent got the id to poll
+
+    # --- check-proposal poll ---
+
+    def test_check_returns_approved_and_archives(self):
+        p = self._seed_proposal()
+        _sv.write_response("dev", _sv.Response(proposal_id=p.id, status=_sv.STATUS_APPROVED, notes="ok"))
+        result = self._check(p.id)
+        self.assertFalse(result["isError"])
+        text = result["content"][0]["text"]  # type: ignore[index]
+        self.assertIn("status: approved", text)
+        self.assertIn("notes: ok", text)
+        with self.assertRaises(FileNotFoundError):  # archived on read
+            _sv.read_proposal("dev", p.id)
+
+    def test_check_rejected_sets_isError(self):
+        p = self._seed_proposal()
+        _sv.write_response("dev", _sv.Response(proposal_id=p.id, status=_sv.STATUS_REJECTED, notes="no"))
+        result = self._check(p.id)
+        self.assertTrue(result["isError"])
+        self.assertIn("status: rejected", result["content"][0]["text"])  # type: ignore[index]
+
+    def test_check_pending_when_no_decision_yet(self):
+        p = self._seed_proposal()
+        result = self._check(p.id)
+        self.assertFalse(result["isError"])
+        text = result["content"][0]["text"]  # type: ignore[index]
+        self.assertIn("status: pending", text)
+        self.assertIn(p.id, text)
+        self.assertEqual(1, len(_sv.list_pending_proposals("dev")))  # not archived
+
+    def test_check_unknown_id_is_error(self):
+        result = self._check("no-such-proposal")
+        self.assertTrue(result["isError"])
+        self.assertIn("status: unknown", result["content"][0]["text"])  # type: ignore[index]
+
+    def test_check_missing_id_raises(self):
+        with self.assertRaises(_RpcClientError) as cm:
+            handle_check_proposal({"arguments": {}}, self.config)
+        self.assertEqual(ERR_INVALID_PARAMS, cm.exception.code)
+
+    def test_check_empty_id_raises(self):
+        with self.assertRaises(_RpcClientError) as cm:
+            handle_check_proposal({"arguments": {"proposal_id": "   "}}, self.config)
+        self.assertEqual(ERR_INVALID_PARAMS, cm.exception.code)
+
+    def test_check_arguments_must_be_object(self):
+        with self.assertRaises(_RpcClientError) as cm:
+            handle_check_proposal({"arguments": []}, self.config)
+        self.assertEqual(ERR_INVALID_PARAMS, cm.exception.code)
+
+    def test_full_nonblocking_round_trip(self):
+        # 1. tools/call times out → pending with id
+        result = handle_tools_call(
+            {
+                "name": _sv.TOOL_EGRESS_ALLOW,
+                "arguments": {"routes_yaml": self._ROUTES, "justification": "x"},
+            },
+            ServerConfig(bottle_slug="dev", response_timeout_seconds=0.05),
+        )
+        pid = _sv.list_pending_proposals("dev")[0].id
+        self.assertIn(pid, result["content"][0]["text"])  # type: ignore[index]
+        # 2. operator decides out-of-band
+        _sv.write_response("dev", _sv.Response(proposal_id=pid, status=_sv.STATUS_APPROVED, notes="ok"))
+        # 3. agent resumes by polling — no re-proposing
+        poll = self._check(pid)
+        self.assertFalse(poll["isError"])
+        self.assertIn("status: approved", poll["content"][0]["text"])  # type: ignore[index]
+        self.assertEqual([], _sv.list_pending_proposals("dev"))  # resolved + archived
+
+
 if __name__ == "__main__":
     unittest.main()