feat(infra): pull artifacts pinned by package release

bot_bottle/backend/docker/gateway.py

@@ -89,6 +89,10 @@ class DockerGateway(Gateway):
         when no dockerfile is configured (a pre-pulled image). BOT_BOTTLE_NO_CACHE
         forces a full rebuild (parity with `start --no-cache`)."""
         if self._dockerfile is None:
+            proc = run_docker(["docker", "pull", self.image_ref])
+            if proc.returncode != 0:
+                raise GatewayError(
+                    f"gateway image pull failed: {proc.stderr.strip()}")
             return
         context = self._build_context or resources.build_root()
         argv = ["docker", "build", "-t", self.image_ref,

bot_bottle/backend/docker/infra.py

@@ -34,6 +34,7 @@ from .orchestrator import (
     ORCHESTRATOR_NETWORK,
 )
 from ... import resources
+from ... import release_manifest
 from ...gateway import (
     GATEWAY_IMAGE,
     GATEWAY_NAME,
@@ -90,6 +91,14 @@ class DockerInfraService(InfraService):
         self._orchestrator_name = orchestrator_name
         self._orchestrator_label = orchestrator_label
         self._gateway_name = gateway_name
+        resolved_orchestrator, orchestrator_local = release_manifest.oci_image(
+            "orchestrator", orchestrator_image)
+        resolved_gateway, gateway_local = release_manifest.oci_image(
+            "gateway", gateway_image)
+        self.orchestrator_image = resolved_orchestrator
+        self.gateway_image = resolved_gateway
+        self._orchestrator_local = orchestrator_local
+        self._gateway_local = gateway_local
 
     def orchestrator(self) -> DockerOrchestrator:
         """The control-plane service. Cheap to reconstruct — `ensure_built`
@@ -104,6 +113,8 @@ class DockerInfraService(InfraService):
             repo_root=self._repo_root,
             host_root=self._host_root,
             root_mount_source=self._root_mount_source,
+            dockerfile=(
+                "Dockerfile.orchestrator" if self._orchestrator_local else None),
         )
 
     def gateway(self) -> DockerGateway:
@@ -119,6 +130,7 @@ class DockerInfraService(InfraService):
             control_network=self.control_network,
             build_context=self._repo_root,
             ca_mount_source=self._gateway_ca_mount_source,
+            dockerfile="Dockerfile.gateway" if self._gateway_local else None,
         )
 
     def ensure_running(
@@ -132,8 +144,8 @@ class DockerInfraService(InfraService):
         gateway = self.gateway()
         # Build both images (cache-aware; a no-op when nothing changed) before
         # bringing either plane up.
-        orchestrator.ensure_built()
-        gateway.ensure_built()
+        orchestrator.ensure_available()
+        gateway.ensure_available()
 
         orchestrator.ensure_running(startup_timeout=startup_timeout)
 

bot_bottle/backend/docker/orchestrator.py

@@ -125,6 +125,10 @@ class DockerOrchestrator(Orchestrator):
         no-op when nothing changed). No-op when no dockerfile is configured (a
         pre-pulled image). BOT_BOTTLE_NO_CACHE forces a full rebuild."""
         if self._dockerfile is None:
+            proc = run_docker(["docker", "pull", self.image_ref])
+            if proc.returncode != 0:
+                raise GatewayError(
+                    f"orchestrator image pull failed: {proc.stderr.strip()}")
             return
         argv = ["docker", "build", "-t", self.image_ref,
                 "-f", str(self._repo_root / self._dockerfile),

bot_bottle/backend/firecracker/infra.py

@@ -61,7 +61,7 @@ class FirecrackerInfraService(InfraService):
                 return url
             # Clear stale/hung/OUTDATED VMs holding either link before booting fresh.
             infra_vm.stop()
-            infra_vm.ensure_built()
+            infra_vm.ensure_available()
             # Orchestrator first — the gateway daemons reach the control plane at
             # startup. Each service owns its own boot; the orchestrator (which
             # holds the signing key) mints the role-scoped `gateway` JWT for the

bot_bottle/backend/firecracker/infra_artifact.py

@@ -195,7 +195,9 @@ def _sha256_file(path: Path) -> str:
     return h.hexdigest()
 
 
-def ensure_artifact_gz(version: str, *, role: str) -> Path:
+def ensure_artifact_gz(
+    version: str, *, role: str, expected_sha256: str | None = None,
+) -> Path:
     """The verified, cached `rootfs.ext4.gz` for `role` at `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
@@ -222,6 +224,11 @@ def ensure_artifact_gz(version: str, *, role: str) -> Path:
         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()
+        if expected_sha256 is not None and expected != expected_sha256:
+            die(
+                f"infra candidate packaged checksum mismatch ({role}) for {version}:\n"
+                f"    packaged {expected_sha256}\n    candidate {expected}"
+            )
         actual = _sha256_file(gz)
         if actual != expected:
             die(
@@ -235,7 +242,13 @@ def ensure_artifact_gz(version: str, *, role: str) -> Path:
     gz = root / _GZ_NAME
     ok = root / ".verified"
     if gz.is_file() and ok.is_file():
-        return gz
+        actual = _sha256_file(gz)
+        recorded = ok.read_text(encoding="utf-8").strip()
+        wanted = expected_sha256 or recorded
+        if actual == recorded == wanted:
+            return gz
+        gz.unlink(missing_ok=True)
+        ok.unlink(missing_ok=True)
 
     info(f"pulling infra rootfs artifact {_package(role)}/{version}")
     _download(artifact_url(version, _GZ_NAME, role=role), gz)
@@ -243,6 +256,14 @@ def ensure_artifact_gz(version: str, *, role: str) -> Path:
     _download(artifact_url(version, _SHA_NAME, role=role), sha)
 
     expected = sha.read_text().split()[0].strip().lower()
+    if expected_sha256 is not None and expected != expected_sha256:
+        gz.unlink(missing_ok=True)
+        sha.unlink(missing_ok=True)
+        die(
+            f"infra artifact published checksum mismatch ({role}) for {version}:\n"
+            f"    packaged  {expected_sha256}\n"
+            f"    published {expected}"
+        )
     actual = _sha256_file(gz)
     if actual != expected:
         gz.unlink(missing_ok=True)
@@ -253,15 +274,22 @@ def ensure_artifact_gz(version: str, *, role: str) -> Path:
             f"    actual   {actual}\n"
             f"    refusing to boot an unverified rootfs."
         )
-    ok.write_text("ok\n")
+    ok.write_text(actual + "\n")
     return gz
 
 
-def materialize_ext4(version: str, dest: Path, *, role: str) -> None:
+def materialize_ext4(
+    version: str,
+    dest: Path,
+    *,
+    role: str,
+    expected_sha256: str | None = None,
+) -> None:
     """Ensure the verified `role` artifact is cached, then gunzip it to `dest` —
     a fresh, writable per-boot rootfs (the VM mutates it; the cached `.gz` stays
     pristine). Atomic via a `.part` sibling."""
-    gz = ensure_artifact_gz(version, role=role)
+    gz = ensure_artifact_gz(
+        version, role=role, expected_sha256=expected_sha256)
     tmp = dest.with_suffix(dest.suffix + ".part")
     info(f"expanding {role} infra rootfs -> {dest}")
     with gzip.open(gz, "rb") as src, open(tmp, "wb") as out:

bot_bottle/backend/firecracker/infra_vm.py

@@ -43,6 +43,7 @@ from pathlib import Path
 from typing import Generator
 
 from ... import resources
+from ... import release_manifest
 from ...log import die, info
 from ..docker import util as docker_mod
 from . import firecracker_vm, infra_artifact, netpool, util
@@ -108,6 +109,18 @@ def _role_version(role: str) -> str:
     return infra_artifact.infra_artifact_version(role_init(role), role)
 
 
+def _role_release(role: str) -> tuple[str, str | None]:
+    manifest = release_manifest.packaged_manifest()
+    if manifest is None or release_manifest.local_build_requested():
+        return _role_version(role), None
+    artifact = (
+        manifest.firecracker_orchestrator
+        if role == "orchestrator"
+        else manifest.firecracker_gateway
+    )
+    return artifact.version, artifact.sha256
+
+
 def ensure_built() -> None:
     """Ensure both infra rootfs artifacts are available before boot.
 
@@ -117,11 +130,16 @@ def ensure_built() -> None:
     `BOT_BOTTLE_INFRA_BUILD=local` instead builds the images from source with
     host Docker (the orchestrator-fc image is `FROM` the orchestrator image, so
     it must exist first) — for iterating on the Dockerfiles."""
-    if infra_artifact.local_build_requested():
+    if release_manifest.local_build_requested():
         build_infra_images_with_docker()
         return
     for role in infra_artifact.ROLES:
-        infra_artifact.ensure_artifact_gz(_role_version(role), role=role)
+        version, expected = _role_release(role)
+        infra_artifact.ensure_artifact_gz(
+            version, role=role, expected_sha256=expected)
+
+
+ensure_available = ensure_built
 
 
 def build_infra_images_with_docker() -> None:
@@ -214,7 +232,9 @@ def boot_vm(
     else:
         # Prebuilt artifact already carries the role's build slack; expand it to
         # a fresh writable rootfs for this boot.
-        infra_artifact.materialize_ext4(_role_version(role), rootfs, role=role)
+        version, expected = _role_release(role)
+        infra_artifact.materialize_ext4(
+            version, rootfs, role=role, expected_sha256=expected)
     private_key, pubkey = _stable_keypair()
 
     info(f"booting {role} VM on {slot.iface} (guest {slot.guest_ip})")
@@ -264,7 +284,8 @@ def _version_file() -> Path:
 def expected_version() -> str:
     """The combined marker for the running pair: both per-plane artifact
     versions, so a change to either rootfs dislodges the adopted pair."""
-    return " ".join(f"{role}={_role_version(role)}" for role in infra_artifact.ROLES)
+    return " ".join(
+        f"{role}={_role_release(role)[0]}" for role in infra_artifact.ROLES)
 
 
 def adoptable(key: Path, url: str, want: str) -> bool:

bot_bottle/backend/macos_container/gateway.py

@@ -84,6 +84,7 @@ class MacosGateway(Gateway):
         egress_network: str = GATEWAY_EGRESS_NETWORK,
         control_network: str = CONTROL_NETWORK,
         repo_root: Path | None = None,
+        local_build: bool = True,
     ) -> None:
         self.image_ref = image_ref
         self.name = name
@@ -93,6 +94,7 @@ class MacosGateway(Gateway):
         # Build context: the repo root in a checkout, a staged copy from the
         # installed wheel otherwise (bot_bottle.resources).
         self._repo_root = repo_root if repo_root is not None else resources.build_root()
+        self._local_build = local_build
         # Set by `connect_to_orchestrator`: the URL the daemons resolve policy
         # against + the pre-minted `gateway` token they present. The gateway
         # never mints, so it never holds the signing key (#469).
@@ -101,8 +103,11 @@ class MacosGateway(Gateway):
 
     def ensure_built(self) -> None:
         """Build the data-plane image from `Dockerfile.gateway`."""
-        container_mod.build_image(
-            self.image_ref, str(self._repo_root), dockerfile="Dockerfile.gateway")
+        if self._local_build:
+            container_mod.build_image(
+                self.image_ref, str(self._repo_root), dockerfile="Dockerfile.gateway")
+        else:
+            container_mod.pull_image(self.image_ref)
 
     def connect_to_orchestrator(self, orchestrator_url: str, gateway_token: str) -> None:
         """Bind the gateway to this orchestrator and (re)start it, dual-homed on

bot_bottle/backend/macos_container/infra.py

@@ -25,6 +25,7 @@ from __future__ import annotations
 from pathlib import Path
 
 from ... import resources
+from ... import release_manifest
 from ...orchestrator.lifecycle import (
     DEFAULT_PORT,
     DEFAULT_STARTUP_TIMEOUT_SECONDS,
@@ -86,6 +87,14 @@ class MacosInfraService(InfraService):
         self._orchestrator_name = orchestrator_name
         self._gateway_name = gateway_name
         self._db_volume = db_volume
+        resolved_orchestrator, orchestrator_local = release_manifest.oci_image(
+            "orchestrator", orchestrator_image)
+        resolved_gateway, gateway_local = release_manifest.oci_image(
+            "gateway", gateway_image)
+        self.orchestrator_image = resolved_orchestrator
+        self.gateway_image = resolved_gateway
+        self._orchestrator_local = orchestrator_local
+        self._gateway_local = gateway_local
 
     def orchestrator(self) -> MacosOrchestrator:
         """The control-plane service on the host-only control network. Cheap to
@@ -98,6 +107,7 @@ class MacosInfraService(InfraService):
             control_network=self.control_network,
             repo_root=self._repo_root,
             db_volume=self._db_volume,
+            local_build=self._orchestrator_local,
         )
 
     def gateway(self) -> MacosGateway:
@@ -112,6 +122,7 @@ class MacosInfraService(InfraService):
             egress_network=self.egress_network,
             control_network=self.control_network,
             repo_root=self._repo_root,
+            local_build=self._gateway_local,
         )
 
     def ensure_running(
@@ -127,8 +138,8 @@ class MacosInfraService(InfraService):
 
         orchestrator = self.orchestrator()
         gateway = self.gateway()
-        orchestrator.ensure_built()
-        gateway.ensure_built()
+        orchestrator.ensure_available()
+        gateway.ensure_available()
 
         orchestrator.ensure_running(startup_timeout=startup_timeout)
 

bot_bottle/backend/macos_container/orchestrator.py

@@ -63,6 +63,7 @@ class MacosOrchestrator(Orchestrator):
         control_network: str = CONTROL_NETWORK,
         repo_root: Path | None = None,
         db_volume: str = ORCHESTRATOR_DB_VOLUME,
+        local_build: bool = True,
     ) -> None:
         self.image_ref = image_ref
         self.name = name
@@ -73,6 +74,7 @@ class MacosOrchestrator(Orchestrator):
         # staged copy from the installed wheel otherwise (bot_bottle.resources).
         self._repo_root = repo_root if repo_root is not None else resources.build_root()
         self._db_volume = db_volume
+        self._local_build = local_build
 
     def url(self) -> str:
         """The orchestrator's control-network address (host CLI + registration),
@@ -114,8 +116,12 @@ class MacosOrchestrator(Orchestrator):
         """Build the control-plane image. The source is bind-mounted so a code
         change takes effect without a rebuild; the image still carries the
         package for its entrypoint."""
-        container_mod.build_image(
-            self.image_ref, str(self._repo_root), dockerfile="Dockerfile.orchestrator")
+        if self._local_build:
+            container_mod.build_image(
+                self.image_ref, str(self._repo_root),
+                dockerfile="Dockerfile.orchestrator")
+        else:
+            container_mod.pull_image(self.image_ref)
 
     def ensure_running(
         self, *, startup_timeout: float = DEFAULT_STARTUP_TIMEOUT_SECONDS,
@@ -146,11 +152,6 @@ class MacosOrchestrator(Orchestrator):
             "--dns", container_mod.dns_server(),
             # Container-only DB volume: exactly one kernel writes bot-bottle.db.
             "--volume", f"{self._db_volume}:{_DB_ROOT_IN_CONTAINER}",
-            # Live control-plane source (a code change takes effect on relaunch).
-            "--mount",
-            container_mod.bind_mount_spec(
-                str(self._repo_root), _SRC_IN_CONTAINER, readonly=True),
-            "--env", f"PYTHONPATH={_SRC_IN_CONTAINER}",
             "--env", f"BOT_BOTTLE_ROOT={_DB_ROOT_IN_CONTAINER}",
             # Detect a real control-plane code change and recreate.
             "--env", f"BOT_BOTTLE_SOURCE_HASH={current_hash}",
@@ -161,6 +162,14 @@ class MacosOrchestrator(Orchestrator):
             # Dockerfile.orchestrator ENTRYPOINT is `-m bot_bottle.orchestrator`.
             "--host", "0.0.0.0", "--port", str(self.port), "--broker", "stub",
         ]
+        if self._local_build:
+            image_index = argv.index(self.image_ref)
+            argv[image_index:image_index] = [
+                "--mount",
+                container_mod.bind_mount_spec(
+                    str(self._repo_root), _SRC_IN_CONTAINER, readonly=True),
+                "--env", f"PYTHONPATH={_SRC_IN_CONTAINER}",
+            ]
         result = container_mod.run_container_argv(
             argv, env={**os.environ, ORCHESTRATOR_TOKEN_ENV: _signing_key})
         if result.returncode != 0:

bot_bottle/backend/macos_container/util.py

@@ -101,6 +101,19 @@ def build_image(
     subprocess.run(args, check=True)
 
 
+def pull_image(ref: str) -> None:
+    """Acquire an immutable OCI reference through Apple Container."""
+    result = subprocess.run(
+        [_CONTAINER, "image", "pull", ref],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip()
+        raise RuntimeError(f"container image pull failed for {ref}: {detail}")
+
+
 def verify_agent_image(image: str, argv: tuple[str, ...]) -> None:
     """Run `argv` inside a throwaway container of a freshly built agent
     image and die loudly if it fails, instead of shipping an image