fix(macos-container): launch gateway as a module, not /app/gateway_init.py

The macOS infra container's init script still spawned the supervisor as `python3 /app/gateway_init.py`. 5ad3449 moved bot_bottle from flat files under /app into a pip-installed package, so that file no longer exists: the supervisor never started, mitmdump never generated its CA, and the launch failed downstream with a misleading "gateway CA not available" error pointing at TLS rather than at the supervisor. This is the same defect 127ba49 fixed for the firecracker backend. It survived on macOS because CI has no Apple Container runner — the KVM runner added in c193b04 covers firecracker, and ubuntu-latest covers docker, but nothing exercises macos_container. test_macos_infra asserted the substring "gateway_init.py", which the broken path satisfied; it now asserts the module form, matching the assertion 127ba49 already made in test_firecracker_infra_vm. Verified end to end on the macos-container backend: image builds, CA is generated, agent registers, and a headless bottle runs a prompt. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
test(gateway-image): probe package imports, not pre-refactor flat modules
2026-07-20 14:37:09 -04:00 · 2026-07-20 13:40:14 -04:00 · 2026-07-20 14:36:40 +00:00 · 2026-07-20 13:51:52 +00:00 · 2026-07-20 02:07:08 -04:00 · 2026-07-19 22:42:54 +00:00
42 changed files with 1523 additions and 375 deletions
@@ -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
@@ -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"]
@@ -90,7 +90,7 @@ BOT_BOTTLE_BACKEND=firecracker ./cli.py start <agent>

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

-> **CI:** the coverage gate (`.gitea/workflows/test.yml` → `coverage` job) runs on a self-hosted runner labelled `kvm`, because the Firecracker backend's VM/SSH orchestration is exercised only by the integration suite, which needs `/dev/kvm` + the provisioned pool (a container runner would skip it and read as uncovered). Provision that runner exactly like a normal Firecracker host — `firecracker` on `PATH`, `/dev/kvm`, 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
@@ -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}")
@@ -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
@@ -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
@@ -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

@@ -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
@@ -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"
    )

@@ -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",
@@ -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))
@@ -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",
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.)
@@ -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
@@ -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
@@ -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.
@@ -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
@@ -1,6 +1,6 @@
 [build-system]
 requires = ["setuptools>=68"]
-build-backend = "setuptools.backends.legacy:build"
+build-backend = "setuptools.build_meta"

 [project]
 name = "bot-bottle"
@@ -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
@@ -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")
@@ -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)
@@ -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)
@@ -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
@@ -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)
@@ -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()
@@ -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()
@@ -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"}):
@@ -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,
@@ -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):
@@ -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()
@@ -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"
        )
@@ -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")
@@ -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:
@@ -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()
@@ -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()