fix(sidecar_init): log after spawn in start_all to close SIGTERM race

`start_all()` was logging "starting {name}" before appending the
process to `self.procs`, so a SIGTERM arriving between the log write
and the append would call `request_shutdown()` with the new daemon
absent from `self.procs` and therefore never forwarded SIGTERM.
Moving the log after the append eliminates the window.

Signal handlers are also moved before `sup.start_all()` in `main()` so
they are registered before any child is spawned; previously there was a
window where SIGTERM used the default handler (silent process death) if
it arrived between `start_all()` returning and `signal.signal()`.

`TestMainEndToEnd._run` is updated to use a reader thread and a
`wait_for_output` synchronisation barrier instead of a fixed sleep, so
`test_sigterm_clean_shutdown` does not race against slow CI startup time.

bot_bottle/__init__.py

@@ -1 +1,11 @@
 """bot-bottle: Python implementation of the agent container launcher."""
+
+from .bottle import BottleError, destroy, freeze, resume_headless, start_headless
+
+__all__ = [
+    "BottleError",
+    "destroy",
+    "freeze",
+    "resume_headless",
+    "start_headless",
+]

bot_bottle/api.py

@@ -0,0 +1,14 @@
+"""Compatibility wrapper for the public bottle runner API.
+
+The implementation lives in :mod:`bot_bottle.bottle.runner`.
+"""
+
+from .bottle.runner import BottleError, destroy, freeze, resume_headless, start_headless
+
+__all__ = [
+    "BottleError",
+    "destroy",
+    "freeze",
+    "resume_headless",
+    "start_headless",
+]

bot_bottle/backend/__init__.py

@@ -36,10 +36,10 @@ import os
 import shlex
 import sys
 from abc import ABC, abstractmethod
-from contextlib import AbstractContextManager, contextmanager
+from contextlib import AbstractContextManager
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Generator, Generic, Sequence, TypeVar
+from typing import Any, Generic, Sequence, TypeVar
 
 from ..agent_provider import AgentProvisionPlan, get_provider, build_agent_provision_plan
 from ..egress import EgressPlan
@@ -78,9 +78,11 @@ class BottleSpec:
     # True when launched via --headless (no TTY, no interactive prompts).
     # The git-gate host-key preflight uses this to error rather than prompt.
     headless: bool = False
-    # Image startup policy. "fresh" preserves the normal build path;
+    # Forge sidecar env vars (PRD forge-native-integration, chunk 1).
-    # "cached" reuses the current local image/artifact without rebuilding.
+    # Passed by the orchestrator at launch time; the forge sidecar reads
-    image_policy: str = "fresh"
+    # them to connect to Gitea. Empty for non-forge runs. The agent
+    # process itself does not receive these.
+    forge_env: dict[str, str] = field(default_factory=dict)
 
 
 @dataclass(frozen=True)
@@ -435,25 +437,8 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
         prompt file, Dockerfile path, and guest home all live on
         `agent_provision_plan` — the source of truth."""
 
-    @contextmanager
-    def launch(
-        self, plan: PlanT, *, skip_stale: bool = False
-    ) -> Generator[Bottle, None, None]:
-        """Template: optionally check for stale cached images, then delegate
-        to `_launch_impl`. Pass `skip_stale=True` to bypass the stale check
-        (used by the interactive CLI after the operator confirms)."""
-        if not skip_stale:
-            self._image_stale_checks(plan)
-        with self._launch_impl(plan) as bottle:
-            yield bottle
-
-    def _image_stale_checks(self, plan: PlanT) -> None:
-        """Raise StaleImageError if any cached image used by this plan is stale.
-        No-op default; backends override to call the shared `check_stale*`
-        helpers on their image/artifact timestamps."""
-
     @abstractmethod
-    def _launch_impl(self, plan: PlanT) -> AbstractContextManager[Bottle]:
+    def launch(self, plan: PlanT) -> AbstractContextManager[Bottle]:
         """Build/run the bottle and yield a handle; tear down on exit."""
 
     def provision(self, plan: PlanT, bottle: "Bottle") -> str | None:

bot_bottle/backend/docker/backend.py

@@ -85,11 +85,8 @@ class DockerBottleBackend(BottleBackend["DockerBottlePlan", "DockerBottleCleanup
             stage_dir=stage_dir,
         )
 
-    def _image_stale_checks(self, plan: DockerBottlePlan) -> None:
-        _launch.stale_checks(plan)
-
     @contextmanager
-    def _launch_impl(self, plan: DockerBottlePlan) -> Generator[DockerBottle, None, None]:
+    def launch(self, plan: DockerBottlePlan) -> Generator[DockerBottle, None, None]:
         with _launch.launch(plan, provision=self.provision) as bottle:
             yield bottle
 

bot_bottle/backend/docker/cleanup.py

@@ -31,7 +31,7 @@ from ... import supervise as _supervise
 from ...log import info, warn
 from . import util as docker_mod
 from .bottle_cleanup_plan import DockerBottleCleanupPlan
-from ...bottle_state import bottle_state_dir, is_preserved
+from ...bottle.state import bottle_state_dir, is_preserved
 from .compose import COMPOSE_PROJECT_PREFIX, list_compose_projects
 
 

bot_bottle/backend/docker/compose.py

@@ -180,6 +180,10 @@ def _sidecar_bundle_service(plan: DockerBottlePlan) -> dict[str, Any]:
 
     service: dict[str, Any] = {
         "image": SIDECAR_BUNDLE_IMAGE,
+        "build": {
+            "context": _REPO_DIR,
+            "dockerfile": SIDECAR_BUNDLE_DOCKERFILE,
+        },
         "container_name": sidecar_bundle_container_name(plan.slug),
         "networks": {
             "internal": {"aliases": internal_aliases},
@@ -188,11 +192,6 @@ def _sidecar_bundle_service(plan: DockerBottlePlan) -> dict[str, Any]:
         "environment": env,
         "volumes": volumes,
     }
-    if plan.spec.image_policy != "cached":
-        service["build"] = {
-            "context": _REPO_DIR,
-            "dockerfile": SIDECAR_BUNDLE_DOCKERFILE,
-        }
     return service
 
 

bot_bottle/backend/docker/enumerate.py

@@ -15,7 +15,7 @@ from __future__ import annotations
 import subprocess
 
 from .. import ActiveAgent
-from ...bottle_state import read_metadata
+from ...bottle.state import read_metadata
 from .compose import compose_project_name, list_active_slugs
 
 

bot_bottle/backend/docker/launch.py

@@ -41,13 +41,12 @@ from ...git_gate import (
     provision_git_gate_dynamic_keys,
     revoke_git_gate_provisioned_keys,
 )
-from ...image_cache import check_stale
+from ...log import info, warn
-from ...log import die, info, warn
 from . import network as network_mod
 from . import util as docker_mod
 from .bottle import DockerBottle
 from .bottle_plan import DockerBottlePlan
-from ...bottle_state import (
+from ...bottle.state import (
     bottle_state_dir,
     egress_state_dir,
     git_gate_state_dir,
@@ -64,7 +63,6 @@ from .compose import (
     write_compose_file,
 )
 from .egress import egress_tls_init
-from .sidecar_bundle import SIDECAR_BUNDLE_IMAGE
 
 
 # Where the repo root lives, for `docker build` context. Computed once.
@@ -102,26 +100,12 @@ def launch(
         # Dockerfile. Sidecar images get built lazily by `docker compose
         # up` via the renderer's `build:` directives.
         committed = read_committed_image(plan.slug)
-        cached_policy = plan.spec.image_policy == "cached"
         if committed and docker_mod.image_exists(committed):
             info(f"using committed image {committed!r}")
             plan = dataclasses.replace(
                 plan,
                 agent_provision=dataclasses.replace(plan.agent_provision, image=committed),
             )
-        elif cached_policy:
-            if not docker_mod.image_exists(plan.image):
-                die(
-                    f"cached agent image {plan.image!r} not found; "
-                    "run without --cached-images to build it"
-                )
-            if not docker_mod.image_exists(SIDECAR_BUNDLE_IMAGE):
-                die(
-                    f"cached sidecar image {SIDECAR_BUNDLE_IMAGE!r} not found; "
-                    "run without --cached-images to build it"
-                )
-            info(f"using cached agent image {plan.image!r}")
-            info(f"using cached sidecar image {SIDECAR_BUNDLE_IMAGE!r}")
         else:
             docker_mod.build_image(
                 plan.image, _REPO_DIR,
@@ -223,21 +207,3 @@ def launch(
         yield bottle
     finally:
         teardown()
-
-
-def stale_checks(plan: DockerBottlePlan) -> None:
-    """Raise StaleImageError if a cached image is older than the configured
-    threshold. Only runs when image_policy is 'cached'. Called by the backend
-    class's _image_stale_checks before _launch_impl starts any resources."""
-    if plan.spec.image_policy != "cached":
-        return
-    committed = read_committed_image(plan.slug)
-    if committed and docker_mod.image_exists(committed):
-        check_stale(f"agent image {committed!r}", docker_mod.image_created_at(committed))
-        return
-    for label, ref in [
-        ("agent image", plan.image),
-        ("sidecar image", SIDECAR_BUNDLE_IMAGE),
-    ]:
-        if docker_mod.image_exists(ref):
-            check_stale(f"{label} {ref!r}", docker_mod.image_created_at(ref))

bot_bottle/backend/docker/util.py

@@ -4,7 +4,6 @@ existence, and building images."""
 
 from __future__ import annotations
 
-from datetime import datetime, timezone
 import re
 import shutil
 import subprocess
@@ -187,45 +186,6 @@ def image_id(ref: str) -> str:
     return r.stdout.strip()
 
 
-def image_created_at(ref: str) -> datetime:
-    """Return Docker's image Created timestamp as an aware UTC datetime."""
-    r = subprocess.run(
-        ["docker", "image", "inspect", "--format", "{{.Created}}", ref],
-        capture_output=True,
-        text=True,
-        check=False,
-    )
-    if r.returncode != 0:
-        die(
-            f"docker image inspect for {ref!r} failed: "
-            f"{(r.stderr or '').strip() or '<no stderr>'}"
-        )
-    raw = r.stdout.strip()
-    try:
-        return _parse_docker_timestamp(raw)
-    except ValueError:
-        die(f"docker image inspect for {ref!r} returned invalid Created timestamp: {raw!r}")
-
-
-def _parse_docker_timestamp(raw: str) -> datetime:
-    text = raw.strip()
-    if text.endswith("Z"):
-        text = text[:-1] + "+00:00"
-    dot = text.find(".")
-    if dot != -1:
-        tz_plus = text.find("+", dot)
-        tz_minus = text.find("-", dot)
-        tz_candidates = [pos for pos in (tz_plus, tz_minus) if pos != -1]
-        if tz_candidates:
-            tz_pos = min(tz_candidates)
-            frac = text[dot + 1:tz_pos]
-            text = text[:dot + 1] + frac[:6].ljust(6, "0") + text[tz_pos:]
-    dt = datetime.fromisoformat(text)
-    if dt.tzinfo is None:
-        dt = dt.replace(tzinfo=timezone.utc)
-    return dt.astimezone(timezone.utc)
-
-
 def save(ref: str, output: str) -> None:
     """`docker save REF -o OUTPUT`. Writes a tarball of the image
     layers + manifest to the host path. Used by smolmachines

bot_bottle/backend/egress_apply.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from pathlib import Path
 
-from ..bottle_state import egress_state_dir
+from ..bottle.state import egress_state_dir
 from ..egress import EGRESS_ROUTES_FILENAME
 from ..egress_addon_core import LOG_OFF, load_config
 

bot_bottle/backend/freeze.py

@@ -16,7 +16,7 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 
 from . import ActiveAgent
-from ..bottle_state import mark_preserved, write_committed_image
+from ..bottle.state import mark_preserved, write_committed_image
 from ..log import die, info
 
 
@@ -66,7 +66,7 @@ class Freezer(ABC):
 
     def commit_slug(self, slug: str) -> None:
         """Convenience entry for cmd_commit when only a slug is available."""
-        from ..bottle_state import read_metadata
+        from ..bottle.state import read_metadata
         metadata = read_metadata(slug)
         agent = ActiveAgent(
             backend_name=self.backend_name,

bot_bottle/backend/macos_container/backend.py

@@ -67,11 +67,8 @@ class MacosContainerBottleBackend(
             stage_dir=stage_dir,
         )
 
-    def _image_stale_checks(self, plan: MacosContainerBottlePlan) -> None:
-        _launch.stale_checks(plan)
-
     @contextmanager
-    def _launch_impl(
+    def launch(
         self, plan: MacosContainerBottlePlan
     ) -> Generator[MacosContainerBottle, None, None]:
         with _launch.launch(plan, provision=self.provision) as bottle:

bot_bottle/backend/macos_container/enumerate.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import subprocess
 
-from ...bottle_state import read_metadata
+from ...bottle.state import read_metadata
 from .. import ActiveAgent
 
 _PREFIX = "bot-bottle-"

bot_bottle/backend/macos_container/launch.py

@@ -17,7 +17,7 @@ from contextlib import ExitStack, contextmanager
 from pathlib import Path
 from typing import Callable, Generator
 
-from ...bottle_state import (
+from ...bottle.state import (
     egress_state_dir,
     git_gate_state_dir,
     read_committed_image,
@@ -32,7 +32,6 @@ from ...git_gate import (
     provision_git_gate_dynamic_keys,
     revoke_git_gate_provisioned_keys,
 )
-from ...image_cache import check_stale
 from ...log import die, info, warn
 from ...supervise import DB_PATH_IN_CONTAINER, SUPERVISE_PORT
 from ...util import expand_tilde
@@ -150,53 +149,29 @@ def _mint_certs(plan: MacosContainerBottlePlan) -> MacosContainerBottlePlan:
 
 
 def _build_images(plan: MacosContainerBottlePlan) -> MacosContainerBottlePlan:
-    cached = plan.spec.image_policy == "cached"
+    container_mod.build_image(
+        SIDECAR_BUNDLE_IMAGE,
+        _REPO_DIR,
+        dockerfile=SIDECAR_BUNDLE_DOCKERFILE,
+    )
     committed = read_committed_image(plan.slug)
     if committed and container_mod.image_exists(committed):
         info(f"using committed image {committed!r}")
-        if not cached:
-            container_mod.build_image(SIDECAR_BUNDLE_IMAGE, _REPO_DIR, dockerfile=SIDECAR_BUNDLE_DOCKERFILE)
         return dataclasses.replace(
             plan,
-            agent_provision=dataclasses.replace(plan.agent_provision, image=committed),
+            agent_provision=dataclasses.replace(
+                plan.agent_provision,
+                image=committed,
+            ),
         )
-    if cached:
+    container_mod.build_image(
-        if not container_mod.image_exists(plan.image):
+        plan.image,
-            die(
+        _REPO_DIR,
-                f"cached agent image {plan.image!r} not found; "
+        dockerfile=plan.dockerfile_path,
-                "run without --cached-images to build it"
+    )
-            )
-        if not container_mod.image_exists(SIDECAR_BUNDLE_IMAGE):
-            die(
-                f"cached sidecar image {SIDECAR_BUNDLE_IMAGE!r} not found; "
-                "run without --cached-images to build it"
-            )
-        info(f"using cached agent image {plan.image!r}")
-        info(f"using cached sidecar image {SIDECAR_BUNDLE_IMAGE!r}")
-        return plan
-    container_mod.build_image(SIDECAR_BUNDLE_IMAGE, _REPO_DIR, dockerfile=SIDECAR_BUNDLE_DOCKERFILE)
-    container_mod.build_image(plan.image, _REPO_DIR, dockerfile=plan.dockerfile_path)
     return plan
 
 
-def stale_checks(plan: MacosContainerBottlePlan) -> None:
-    """Raise StaleImageError if a cached image is older than the configured
-    threshold. Only runs when image_policy is 'cached'. Called by the backend
-    class's _image_stale_checks before _launch_impl starts any resources."""
-    if plan.spec.image_policy != "cached":
-        return
-    committed = read_committed_image(plan.slug)
-    if committed and container_mod.image_exists(committed):
-        check_stale(f"agent image {committed!r}", container_mod.image_created_at(committed))
-        return
-    for label, ref in [
-        ("agent image", plan.image),
-        ("sidecar image", SIDECAR_BUNDLE_IMAGE),
-    ]:
-        if container_mod.image_exists(ref):
-            check_stale(f"{label} {ref!r}", container_mod.image_created_at(ref))
-
-
 def _create_networks(
     internal_network: str,
     egress_network: str,

bot_bottle/backend/macos_container/util.py

@@ -10,7 +10,6 @@ import shutil
 import subprocess
 import tempfile
 import time
-from datetime import datetime, timezone
 from typing import Iterable
 
 from ...log import die, info
@@ -459,39 +458,6 @@ def image_id(ref: str) -> str:
     raise AssertionError("unreachable")
 
 
-def image_created_at(ref: str) -> datetime:
-    """Return the image creation timestamp as an aware UTC datetime.
-
-    Parses the `created` field from `container image inspect` JSON output."""
-    result = subprocess.run(
-        [_CONTAINER, "image", "inspect", ref],
-        capture_output=True,
-        text=True,
-        check=False,
-    )
-    if result.returncode != 0:
-        die(
-            f"container image inspect for {ref!r} failed: "
-            f"{(result.stderr or '').strip() or '<no stderr>'}"
-        )
-    try:
-        data = json.loads(result.stdout or "{}")
-    except json.JSONDecodeError as exc:
-        die(f"container image inspect for {ref!r} returned malformed JSON: {exc}")
-    if isinstance(data, list) and data:
-        data = data[0]
-    if isinstance(data, dict):
-        value = data.get("created") or data.get("Created")
-        if isinstance(value, str) and value:
-            try:
-                ts = value.rstrip("Z")
-                return datetime.fromisoformat(ts).replace(tzinfo=timezone.utc)
-            except ValueError:
-                pass
-    die(f"container image inspect for {ref!r} did not include a creation timestamp")
-    raise AssertionError("unreachable")
-
-
 def save(ref: str, output: str) -> None:
     subprocess.run([_CONTAINER, "image", "save", ref, "-o", output], check=True)
 

bot_bottle/backend/resolve_common.py

@@ -15,7 +15,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from ..agent_provider import AgentProvisionPlan
-from ..bottle_state import (
+from ..bottle.state import (
     BottleMetadata,
     agent_state_dir,
     bottle_identity,

bot_bottle/backend/smolmachines/backend.py

@@ -77,11 +77,8 @@ class SmolmachinesBottleBackend(
             stage_dir=stage_dir,
         )
 
-    def _image_stale_checks(self, plan: SmolmachinesBottlePlan) -> None:
-        _launch.stale_checks(plan)
-
     @contextmanager
-    def _launch_impl(
+    def launch(
         self, plan: SmolmachinesBottlePlan
     ) -> Generator[SmolmachinesBottle, None, None]:
         with _launch.launch(plan, provision=self.provision) as bottle:

bot_bottle/backend/smolmachines/egress_apply.py

@@ -1,51 +1,20 @@
 """Egress apply for the smolmachines backend.
 
-The smolmachines sidecar bundle runs as a sidecar smolVM. Route-file
+The smolmachines sidecar bundle runs as a host-side Docker container,
-inspection and reload signalling therefore go through ``smolvm machine
+so egress signalling is identical to the docker backend.
-exec`` instead of Docker.
 """
 
 from __future__ import annotations
 
-from ...egress import EGRESS_ROUTES_IN_CONTAINER
+from ..docker.egress_apply import (  # noqa: F401
-from ...log import warn
+    DockerEgressApplicator,
-from ..egress_apply import EgressApplicator, EgressApplyError
+    EgressApplyError,
-from . import sidecar_bundle as _bundle
+    applicator,
-from . import smolvm as _smolvm
+    fetch_current_routes,
-
+)
-
-def fetch_current_routes(slug: str) -> str:
-    machine = _bundle.bundle_machine_name(slug)
-    result = _smolvm.machine_exec(machine, ["cat", EGRESS_ROUTES_IN_CONTAINER])
-    if result.returncode != 0:
-        raise EgressApplyError(
-            f"could not read routes.yaml from {machine}: "
-            f"{(result.stderr or '').strip() or 'sidecar VM not running?'}"
-        )
-    return result.stdout
-
-
-class SmolmachinesEgressApplicator(EgressApplicator):
-    def _signal_bundle_reload(self, slug: str) -> None:
-        machine = _bundle.bundle_machine_name(slug)
-        result = _smolvm.machine_exec(machine, ["sh", "-c", "kill -HUP 1"])
-        if result.returncode != 0:
-            last_error = (result.stderr or "").strip() or (result.stdout or "").strip()
-            warn(
-                f"egress: routes updated on disk for {slug}, but bundle reload failed: "
-                f"{last_error or 'smolvm exec failed'}"
-            )
-            raise EgressApplyError(
-                f"could not reload egress bundle {machine}: "
-                f"{last_error or 'smolvm exec failed'}"
-            )
-
-
-applicator = SmolmachinesEgressApplicator()
-
 
 __all__ = [
-    "SmolmachinesEgressApplicator",
+    "DockerEgressApplicator",
     "EgressApplyError",
     "applicator",
     "fetch_current_routes",

bot_bottle/backend/smolmachines/enumerate.py

@@ -23,7 +23,7 @@ import json
 import subprocess
 
 from .. import ActiveAgent
-from ...bottle_state import read_metadata
+from ...bottle.state import read_metadata
 from . import sidecar_bundle as _bundle
 
 
@@ -31,7 +31,6 @@ from . import sidecar_bundle as _bundle
 # matching the bundle container name pattern. We use the prefix
 # both as a filter and to strip back to the slug.
 _VM_NAME_PREFIX = "bot-bottle-"
-_SIDECAR_VM_PREFIX = _bundle.bundle_machine_name("")
 
 
 def enumerate_active() -> list[ActiveAgent]:
@@ -55,11 +54,7 @@ def enumerate_active() -> list[ActiveAgent]:
     for m in machines:
         name = m.get("name") or ""
         state = m.get("state") or ""
-        if (
+        if state != "running" or not name.startswith(_VM_NAME_PREFIX):
-            state != "running"
-            or not name.startswith(_VM_NAME_PREFIX)
-            or name.startswith(_SIDECAR_VM_PREFIX)
-        ):
             continue
         slug = name[len(_VM_NAME_PREFIX):]
         metadata = read_metadata(slug)

bot_bottle/backend/smolmachines/freezer.py

@@ -18,7 +18,7 @@ from ..freeze import Freezer
 from ..docker import util as docker_mod
 from .local_registry import crane_push_tarball, ephemeral_registry
 from .smolvm import machine_cp, machine_exec, pack_create
-from ...bottle_state import bottle_state_dir
+from ...bottle.state import bottle_state_dir
 from ...log import die, info
 
 

bot_bottle/backend/smolmachines/launch.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 
 import dataclasses
 import os
+import platform
 from contextlib import ExitStack, contextmanager
 from pathlib import Path
 from typing import Callable, Generator
@@ -45,15 +46,13 @@ from ...git_gate import (
     provision_git_gate_dynamic_keys,
     revoke_git_gate_provisioned_keys,
 )
-from ...image_cache import check_stale_path
+from ...log import info, warn
-from ...log import die, info, warn
+from ...bottle.state import (
-from ...bottle_state import (
     egress_state_dir,
     git_gate_state_dir,
     read_committed_image,
 )
 from . import loopback_alias as _loopback
-from . import port_forward as _forward
 from . import sidecar_bundle as _bundle
 from . import smolvm as _smolvm
 from .bottle import SmolmachinesBottle
@@ -93,8 +92,9 @@ def launch(
     try:
         loopback_ip, network = _allocate_resources(plan, stack)
         plan = _mint_certs(plan)
-        proxy_host = loopback_ip
+        proxy_host = _proxy_host(plan, loopback_ip)
         plan = _start_bundle(plan, network, proxy_host, stack)
+        plan = _discover_urls(plan, proxy_host)
 
         agent_from_path = _agent_from_path(plan)
 
@@ -144,17 +144,19 @@ def _allocate_resources(
     plan: SmolmachinesBottlePlan,
     stack: ExitStack,
 ) -> tuple[str, str]:
-    """Reserve a per-bottle host address.
+    """Reserve a loopback alias and create the per-bottle docker bridge.
 
-    The per-bottle address scopes TSI's allowlist to this bottle's
+    The per-bottle alias scopes TSI's allowlist to this bottle's
-    forwarder-published ports so the agent can't reach other bottles'
+    published ports so the agent can't reach other bottles' or host
-    or host services. The returned network name remains in the bundle
+    services' ports on loopback. On macOS `ensure_pool` first
-    spec for compatibility with older helper tests; no Docker sidecar
+    sudo-aliases the pool on `lo0`; on Linux that's a no-op since
-    container is launched."""
+    all of 127.0.0.0/8 is already loopback, but the per-bottle
-    del stack
+    allocation runs on both."""
     _loopback.ensure_pool()
     loopback_ip = _loopback.allocate(plan.slug)
     network = _bundle.bundle_network_name(plan.slug)
+    _bundle.create_bundle_network(network, plan.bundle_subnet, plan.bundle_gateway)
+    stack.callback(_bundle.remove_bundle_network, network)
     return loopback_ip, network
 
 
@@ -177,43 +179,15 @@ def _start_bundle(
     proxy_host: str,
     stack: ExitStack,
 ) -> SmolmachinesBottlePlan:
-    """Build the BundleLaunchSpec, start the sidecar VM, wrap its raw
+    """Build the BundleLaunchSpec, resolve token env, start the
-    smolVM-published loopback ports with per-bottle forwarders, stamp
+    sidecar bundle container, and register teardown."""
-    agent URLs from those forwarder ports, and register teardown."""
     plan = _provision_git_gate_keys(plan)
     bundle_spec = _bundle_launch_spec(plan, network, proxy_host)
     token_env = _resolve_token_env(plan, dict(os.environ))
-    if _image_policy(plan) == "cached":
+    _bundle.ensure_bundle_image(bundle_spec.image)
-        artifact = _cached_smolmachine(bundle_spec.image, label="sidecar")
+    _bundle.start_bundle(bundle_spec, env={**os.environ, **token_env})
-    else:
+    stack.callback(_bundle.stop_bundle, plan.slug)
-        artifact = _ensure_smolmachine(
+    return plan
-            bundle_spec.image,
-            dockerfile=_bundle.SIDECAR_BUNDLE_DOCKERFILE,
-        )
-    launch = _bundle.start_bundle_vm(
-        bundle_spec,
-        from_path=artifact,
-        host_env={**os.environ, **token_env},
-    )
-    stack.callback(_bundle.stop_bundle_vm, plan.slug)
-
-    forward_specs = tuple(
-        _forward.ForwardSpec(
-            label=_label_for_port(container_port),
-            listen_host=proxy_host,
-            listen_port=0,
-            target_host="127.0.0.1",
-            target_port=host_port,
-        )
-        for container_port, host_port in launch.raw_ports.items()
-    )
-    handle = _forward.start_forwarder(forward_specs)
-    stack.callback(_forward.stop_forwarder, handle)
-    published_ports = {
-        _port_for_label(spec.label): spec.listen_port
-        for spec in handle.forwards
-    }
-    return _discover_urls(plan, proxy_host, published_ports)
 
 
 def _provision_git_gate_keys(
@@ -232,27 +206,35 @@ def _provision_git_gate_keys(
 def _discover_urls(
     plan: SmolmachinesBottlePlan,
     proxy_host: str,
-    published_ports: dict[int, int],
 ) -> SmolmachinesBottlePlan:
-    """Stamp URLs + guest_env from per-bottle forwarder ports.
+    """Discover host-side ports for published container ports and
+    return the plan with URLs + guest_env stamped in.
 
-    `proxy_host` is the host IP that both TSI's allowlist and the
+    `proxy_host` is the host IP that both TSI's allowlist and
-    forwarder listeners are keyed to. The raw smolVM-published ports
+    docker's port-forward bindings are keyed to. On macOS it is the
-    are intentionally not advertised to the agent.
+    per-bottle loopback alias; on Linux it is the per-bottle bridge
+    gateway (see `_proxy_host`). The agent dials the published port
+    on this IP for all bundle-hosted services.
 
     NO_PROXY includes `proxy_host` so supervise + git-gate URLs
     bypass HTTPS_PROXY."""
-    agent_facing_host_port = published_ports[_EGRESS_PORT]
+    agent_facing_host_port = _bundle.bundle_host_port(
+        plan.slug, _EGRESS_PORT, host_ip=proxy_host,
+    )
     agent_proxy_url = f"http://{proxy_host}:{agent_facing_host_port}"
 
     agent_git_gate_host = ""
     if plan.git_gate_plan.upstreams:
-        git_gate_host_port = published_ports[_GIT_HTTP_PORT]
+        git_gate_host_port = _bundle.bundle_host_port(
+            plan.slug, _GIT_HTTP_PORT, host_ip=proxy_host,
+        )
         agent_git_gate_host = f"{proxy_host}:{git_gate_host_port}"
 
     agent_supervise_url = ""
     if plan.supervise_plan is not None:
-        supervise_host_port = published_ports[_SUPERVISE_PORT]
+        supervise_host_port = _bundle.bundle_host_port(
+            plan.slug, _SUPERVISE_PORT, host_ip=proxy_host,
+        )
         agent_supervise_url = f"http://{proxy_host}:{supervise_host_port}/"
 
     existing_no_proxy = plan.guest_env.get("NO_PROXY", "localhost,127.0.0.1")
@@ -291,13 +273,14 @@ def _launch_vm(
 ) -> None:
     """Create, patch, and start the smolvm VM; register teardown.
 
-    --allow-cidr is `proxy_host/32` — the per-bottle loopback alias.
+    --allow-cidr is `proxy_host/32` — the per-bottle loopback alias
-    This ensures the guest can only reach sidecar forwarders published
+    on macOS or the bridge gateway on Linux (see `_proxy_host`). This
-    on that IP, not host localhost or another bottle's alias.
+    ensures the guest can only reach bundle ports published on that IP,
-    force_allowlist confirms the allowlist persisted (patching smolvm
+    not the container IP directly. force_allowlist confirms the
-    0.8.0's silent-drop of --allow-cidr when combined with --from) and
+    allowlist persisted (patching smolvm 0.8.0's silent-drop of
-    fails closed if it can't. Smolfile isn't usable here — smolvm 0.8.0
+    --allow-cidr when combined with --from) and fails closed if it
-    makes --from and --smolfile mutually exclusive."""
+    can't. Smolfile isn't usable here — smolvm 0.8.0 makes --from
+    and --smolfile mutually exclusive."""
     tsi_cidr = f"{proxy_host}/32"
     _smolvm.machine_create(
         plan.machine_name,
@@ -344,26 +327,25 @@ def _init_vm(plan: SmolmachinesBottlePlan) -> None:
     _smolvm.wait_exec_ready(plan.machine_name)
 
 
-def _label_for_port(port: int) -> str:
+def _proxy_host(plan: SmolmachinesBottlePlan, loopback_ip: str) -> str:
-    if port == _EGRESS_PORT:
+    """Return the host IP for TSI's allowlist and docker port-forward bindings.
-        return "egress"
-    if port == _GIT_HTTP_PORT:
-        return "git-http"
-    if port == _SUPERVISE_PORT:
-        return "supervise"
-    return f"port-{port}"
 
+    On macOS, the per-bottle loopback alias (e.g. ``127.0.0.16``) works
+    because macOS's network stack lets TSI intercept 127.x.x.x connects
+    from the guest before they reach the host's own loopback.
 
-def _port_for_label(label: str) -> int:
+    On Linux, the guest kernel's LOCAL routing table routes all
-    if label == "egress":
+    ``127.0.0.0/8`` to the guest's own loopback — those packets never
-        return _EGRESS_PORT
+    reach eth0 and TSI never sees them. Using the per-bottle bridge
-    if label == "git-http":
+    gateway (e.g. ``192.168.N.1``) instead sidesteps the problem: it
-        return _GIT_HTTP_PORT
+    is not a loopback address, so the guest routes it via eth0 and TSI
-    if label == "supervise":
+    intercepts it normally. The TSI allowlist is ``gateway/32``, which
-        return _SUPERVISE_PORT
+    is distinct from the container IP (``192.168.N.2``), so the agent
-    if label.startswith("port-"):
+    still can't reach the egress daemon directly — TSI blocks any
-        return int(label.removeprefix("port-"))
+    connection to the container IP that isn't via the published port."""
-    raise ValueError(f"unknown sidecar forward label: {label}")
+    if platform.system() == "Linux":
+        return plan.bundle_gateway
+    return loopback_ip
 
 
 def _bundle_launch_spec(
@@ -473,9 +455,6 @@ def _agent_from_path(plan: SmolmachinesBottlePlan) -> Path:
             info(f"using committed smolmachine {str(committed_path)!r}")
             return committed_path
 
-    if _image_policy(plan) == "cached":
-        return _cached_smolmachine(plan.agent_image, label="agent")
-
     # Build the agent image and pack it into a `.smolmachine`
     # artifact (or hit the per-Dockerfile-digest cache). Runs here,
     # not in prepare, so the docker-build output doesn't garble the
@@ -486,60 +465,6 @@ def _agent_from_path(plan: SmolmachinesBottlePlan) -> Path:
     )
 
 
-def stale_checks(plan: SmolmachinesBottlePlan) -> None:
-    """Raise StaleImageError if a cached smolmachine artifact is older than the
-    configured threshold. Only runs when image_policy is 'cached'. Checks the
-    committed agent artifact first, then the cache-keyed agent and sidecar
-    artifacts. Called by the backend class's _image_stale_checks before any
-    resources are allocated."""
-    if _image_policy(plan) != "cached":
-        return
-    committed = read_committed_image(plan.slug)
-    if committed:
-        committed_path = Path(committed)
-        if committed_path.is_file():
-            check_stale_path("agent smolmachine artifact", committed_path)
-    elif docker_mod.image_exists(plan.agent_image):
-        digest = docker_mod.image_id(plan.agent_image).split(":", 1)[-1][:16]
-        artifact = _SMOLMACHINE_CACHE_DIR / f"{digest}.smolmachine.smolmachine"
-        if artifact.is_file():
-            check_stale_path("agent smolmachine artifact", artifact)
-    sidecar_image = _bundle.SIDECAR_BUNDLE_IMAGE
-    if docker_mod.image_exists(sidecar_image):
-        digest = docker_mod.image_id(sidecar_image).split(":", 1)[-1][:16]
-        sidecar_artifact = _SMOLMACHINE_CACHE_DIR / f"{digest}.smolmachine.smolmachine"
-        if sidecar_artifact.is_file():
-            check_stale_path("sidecar smolmachine artifact", sidecar_artifact)
-
-
-def _image_policy(plan: object) -> str:
-    spec = getattr(plan, "spec", None)
-    return str(getattr(spec, "image_policy", "fresh"))
-
-
-def _cached_smolmachine(image_ref: str, *, label: str) -> Path:
-    """Return the cached smolmachine artifact for the current local image.
-
-    This is intentionally buildless: it inspects the existing local Docker
-    image ID and looks for the artifact keyed by that ID. If either side is
-    missing, the caller must use the fresh path to build/pack it.
-    """
-    if not docker_mod.image_exists(image_ref):
-        die(
-            f"cached {label} image {image_ref!r} not found; "
-            "run without --cached-images to build it"
-        )
-    digest = docker_mod.image_id(image_ref).split(":", 1)[-1][:16]
-    sidecar = _SMOLMACHINE_CACHE_DIR / f"{digest}.smolmachine.smolmachine"
-    if not sidecar.is_file():
-        die(
-            f"cached {label} smolmachine artifact for {image_ref!r} not found; "
-            "run without --cached-images to build it"
-        )
-    info(f"using cached {label} smolmachine {str(sidecar)!r}")
-    return sidecar
-
-
 def _ensure_smolmachine(image_ref: str, *, dockerfile: str = "") -> Path:
     """Build the agent docker image and convert it into a
     `.smolmachine` artifact, caching the result under

bot_bottle/backend/smolmachines/port_forward.py

@@ -1,245 +0,0 @@
-"""Per-bottle TCP forwarder for smolmachines sidecar VMs.
-
-smolVM currently publishes guest ports on host loopback as
-``HOST:GUEST`` port pairs, without an address-scoped bind. The agent
-VM's TSI allowlist is IP-only, so bot-bottle exposes a second, stricter
-surface: listeners bound only to the bottle's allocated host address,
-forwarding to the raw smolVM-published loopback ports.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import selectors
-import signal
-import socket
-import subprocess
-import sys
-import threading
-from dataclasses import asdict, dataclass
-from typing import Any, Iterable, Sequence
-
-from ...log import die, warn
-
-
-_BUFFER_SIZE = 64 * 1024
-_LOOPBACK_TARGETS = {"127.0.0.1", "::1"}
-_FORBIDDEN_LISTEN_HOSTS = {"", "0.0.0.0", "::", "127.0.0.1", "::1"}
-
-
-@dataclass(frozen=True)
-class ForwardSpec:
-    label: str
-    listen_host: str
-    listen_port: int
-    target_host: str
-    target_port: int
-
-
-@dataclass(frozen=True)
-class ForwarderHandle:
-    process: Any
-    forwards: tuple[ForwardSpec, ...]
-
-
-def start_forwarder(specs: Sequence[ForwardSpec]) -> ForwarderHandle:
-    """Start one helper process for a bottle and wait until all
-    listeners are bound. ``listen_port`` may be 0; the returned specs
-    contain the kernel-assigned ports printed by the helper."""
-    if not specs:
-        return ForwarderHandle(process=_CompletedProcess(), forwards=())
-    _validate_specs(specs)
-    argv = [
-        sys.executable,
-        "-c",
-        "from bot_bottle.backend.smolmachines.port_forward import main; "
-        "raise SystemExit(main())",
-        "--spec-json",
-        json.dumps([asdict(s) for s in specs], separators=(",", ":")),
-    ]
-    proc = subprocess.Popen(
-        argv,
-        stdin=subprocess.DEVNULL,
-        stdout=subprocess.PIPE,
-        stderr=None,
-        text=True,
-        env=os.environ,
-    )
-    assert proc.stdout is not None
-    line = proc.stdout.readline()
-    proc.stdout.close()
-    if not line:
-        proc.terminate()
-        proc.wait(timeout=5)
-        die("smolmachines forwarder failed before reporting readiness")
-    try:
-        payload = json.loads(line)
-        bound = tuple(ForwardSpec(**item) for item in payload["forwards"])
-    except (KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
-        proc.terminate()
-        proc.wait(timeout=5)
-        die(f"smolmachines forwarder returned invalid readiness payload: {exc}")
-    return ForwarderHandle(process=proc, forwards=bound)
-
-
-def stop_forwarder(handle: ForwarderHandle) -> None:
-    proc = handle.process
-    if proc.poll() is not None:
-        return
-    proc.terminate()
-    try:
-        proc.wait(timeout=5)
-    except subprocess.TimeoutExpired:
-        proc.kill()
-        proc.wait(timeout=5)
-
-
-def _validate_specs(specs: Iterable[ForwardSpec]) -> None:
-    for spec in specs:
-        if spec.listen_host in _FORBIDDEN_LISTEN_HOSTS:
-            die(f"refusing unsafe smolmachines forwarder bind: {spec.listen_host!r}")
-        if spec.target_host not in _LOOPBACK_TARGETS:
-            die(f"refusing non-loopback smolmachines forwarder target: {spec.target_host!r}")
-        if not 0 <= spec.listen_port <= 65535:
-            die(f"invalid smolmachines forwarder listen port: {spec.listen_port}")
-        if not 1 <= spec.target_port <= 65535:
-            die(f"invalid smolmachines forwarder target port: {spec.target_port}")
-
-
-class _CompletedProcess:
-    """Popen-like no-op used when a bottle has no forwards."""
-
-    def poll(self) -> int:
-        return 0
-
-    def terminate(self) -> None:
-        return None
-
-    def kill(self) -> None:
-        return None
-
-    def wait(self, timeout: float | None = None) -> int:
-        del timeout
-        return 0
-
-
-class _Forwarder:
-    def __init__(self, specs: Sequence[ForwardSpec]):
-        _validate_specs(specs)
-        self.specs = tuple(specs)
-        self.selector = selectors.DefaultSelector()
-        self.stop_event = threading.Event()
-        self.listeners: list[tuple[socket.socket, ForwardSpec]] = []
-        self.bound: list[ForwardSpec] = []
-
-    def start(self) -> None:
-        for spec in self.specs:
-            listener = socket.create_server(
-                (spec.listen_host, spec.listen_port),
-                reuse_port=False,
-                backlog=64,
-            )
-            listener.setblocking(False)
-            host, port = listener.getsockname()[:2]
-            bound = ForwardSpec(
-                label=spec.label,
-                listen_host=str(host),
-                listen_port=int(port),
-                target_host=spec.target_host,
-                target_port=spec.target_port,
-            )
-            self.listeners.append((listener, bound))
-            self.bound.append(bound)
-            self.selector.register(listener, selectors.EVENT_READ, bound)
-
-    def serve(self) -> None:
-        while not self.stop_event.is_set():
-            try:
-                events = self.selector.select(timeout=0.25)
-            except OSError:
-                return
-            for key, _ in events:
-                listener = key.fileobj
-                if not isinstance(listener, socket.socket):
-                    continue
-                spec = key.data
-                try:
-                    client, _ = listener.accept()
-                except OSError:
-                    continue
-                threading.Thread(
-                    target=self._handle_client,
-                    args=(client, spec),
-                    daemon=True,
-                ).start()
-
-    def stop(self) -> None:
-        self.stop_event.set()
-        for listener, _ in self.listeners:
-            try:
-                self.selector.unregister(listener)
-            except Exception:  # noqa: BLE001 - best effort shutdown
-                pass
-            listener.close()
-        self.selector.close()
-
-    def _handle_client(self, client: socket.socket, spec: ForwardSpec) -> None:
-        with client:
-            try:
-                target = socket.create_connection((spec.target_host, spec.target_port))
-            except OSError as exc:
-                warn(f"smolmachines forwarder {spec.label}: target connect failed: {exc}")
-                return
-            with target:
-                left = threading.Thread(target=_pipe, args=(client, target), daemon=True)
-                right = threading.Thread(target=_pipe, args=(target, client), daemon=True)
-                left.start()
-                right.start()
-                left.join()
-                right.join()
-
-
-def _pipe(src: socket.socket, dst: socket.socket) -> None:
-    while True:
-        try:
-            data = src.recv(_BUFFER_SIZE)
-        except OSError:
-            break
-        if not data:
-            break
-        try:
-            dst.sendall(data)
-        except OSError:
-            break
-    try:
-        dst.shutdown(socket.SHUT_WR)
-    except OSError:
-        pass
-
-
-def main(argv: Sequence[str] | None = None) -> int:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--spec-json", required=True)
-    ns = parser.parse_args(argv)
-    specs = tuple(ForwardSpec(**item) for item in json.loads(ns.spec_json))
-    forwarder = _Forwarder(specs)
-
-    def request_stop(signum: int, _frame: object) -> None:
-        del signum
-        forwarder.stop()
-
-    signal.signal(signal.SIGTERM, request_stop)
-    signal.signal(signal.SIGINT, request_stop)
-    forwarder.start()
-    print(json.dumps({"forwards": [asdict(s) for s in forwarder.bound]}), flush=True)
-    try:
-        forwarder.serve()
-    finally:
-        forwarder.stop()
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

bot_bottle/backend/smolmachines/sidecar_bundle.py

@@ -23,8 +23,6 @@ Plans (EgressPlan, …) lands in chunk 2d."""
 
 from __future__ import annotations
 
-import os
-import socket
 import subprocess
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -36,7 +34,6 @@ from ..docker.sidecar_bundle import (
     SIDECAR_BUNDLE_DOCKERFILE,
     SIDECAR_BUNDLE_IMAGE,
 )
-from . import smolvm as _smolvm
 
 
 _REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)
@@ -57,11 +54,6 @@ def bundle_container_name(slug: str) -> str:
     return f"bot-bottle-sidecars-{slug}"
 
 
-def bundle_machine_name(slug: str) -> str:
-    """Sidecar smolVM machine name."""
-    return bundle_container_name(slug)
-
-
 @dataclass(frozen=True)
 class BundleLaunchSpec:
     """Everything `start_bundle` needs to bring up one bundle
@@ -100,11 +92,6 @@ class BundleLaunchSpec:
     publish_host_ip: str = "127.0.0.1"
 
 
-@dataclass(frozen=True)
-class BundleVmLaunch:
-    raw_ports: dict[int, int]
-
-
 def ensure_bundle_image(image: str = SIDECAR_BUNDLE_IMAGE) -> None:
     """Build the sidecar bundle image before `docker run`.
 
@@ -120,70 +107,6 @@ def ensure_bundle_image(image: str = SIDECAR_BUNDLE_IMAGE) -> None:
     )
 
 
-def allocate_raw_host_ports(container_ports: Sequence[int]) -> dict[int, int]:
-    """Reserve candidate host loopback ports for smolVM `-p HOST:GUEST`.
-
-    The sockets are closed before smolVM binds them, so this remains
-    best-effort. smolVM failing to bind a selected port is fatal in
-    the caller's launch path."""
-    out: dict[int, int] = {}
-    for container_port in container_ports:
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
-            sock.bind(("127.0.0.1", 0))
-            out[container_port] = int(sock.getsockname()[1])
-    return out
-
-
-def start_bundle_vm(
-    spec: BundleLaunchSpec,
-    *,
-    from_path: Path,
-    host_env: dict[str, str] | None = None,
-) -> BundleVmLaunch:
-    """Create and start the sidecar bundle as a smolVM.
-
-    smolVM's own published ports are raw host-loopback ports. The
-    launch flow wraps them with per-bottle address-bound forwarders
-    before exposing anything to the agent VM."""
-    raw_ports = allocate_raw_host_ports(spec.ports_to_publish)
-    effective_host_env = host_env if host_env is not None else os.environ
-    env: dict[str, str] = {"BOT_BOTTLE_SIDECAR_DAEMONS": spec.daemons_csv}
-    for entry in spec.environment:
-        name, sep, value = entry.partition("=")
-        if sep:
-            env[name] = value
-        elif entry in effective_host_env:
-            env[entry] = effective_host_env[entry]
-    name = bundle_machine_name(spec.slug)
-    _smolvm.machine_create(
-        name,
-        from_path=from_path,
-        net=True,
-        env=env,
-        volumes=spec.volumes,
-        ports=tuple(
-            (host_port, guest_port)
-            for guest_port, host_port in raw_ports.items()
-        ),
-    )
-    _smolvm.machine_start(name)
-    _smolvm.wait_exec_ready(name)
-    return BundleVmLaunch(raw_ports=raw_ports)
-
-
-def stop_bundle_vm(slug: str) -> None:
-    """Best-effort sidecar VM teardown."""
-    name = bundle_machine_name(slug)
-    try:
-        _smolvm.machine_stop(name)
-    except _smolvm.SmolvmError as exc:
-        warn(f"smolvm machine stop {name} failed: {exc}")
-    try:
-        _smolvm.machine_delete(name)
-    except _smolvm.SmolvmError as exc:
-        warn(f"smolvm machine delete {name} failed: {exc}")
-
-
 def create_bundle_network(network_name: str, subnet: str, gateway: str) -> None:
     """`docker network create` with an explicit subnet + gateway
     so the bundle's `--ip` lands on the address the Smolfile's

bot_bottle/backend/smolmachines/smolvm.py

@@ -113,11 +113,8 @@ def machine_create(
     *,
     image: str | None = None,
     from_path: Path | None = None,
-    net: bool = False,
     allow_cidrs: Sequence[str] = (),
     env: Mapping[str, str] | None = None,
-    ports: Sequence[tuple[int, int]] = (),
-    volumes: Sequence[tuple[str, str, bool]] = (),
 ) -> None:
     """`smolvm machine create --name NAME [--image IMG | --from PATH]
     [--allow-cidr CIDR ...] [-e K=V ...]`. NAME is passed as
@@ -134,24 +131,19 @@ def machine_create(
     no-pull-at-start property. The flag form gives the same
     result without the Smolfile complication.
 
-    `--net` is sent explicitly when `net=True` or `allow_cidrs` is
+    `--net` is sent explicitly when `allow_cidrs` is non-empty.
-    non-empty. `--allow-cidr` implies `--net` per the CLI help, but
+    `--allow-cidr` implies `--net` per the CLI help, but sending
-    sending `--net` explicitly is harmless and ensures the guest has
+    `--net` explicitly is harmless and ensures the guest has
     network access even if that implication changes across versions."""
     args: list[str] = ["machine", "create", "--name", name]
     if image is not None:
         args += ["--image", image]
     if from_path is not None:
         args += ["--from", str(from_path)]
-    if net or allow_cidrs:
+    if allow_cidrs:
         args.append("--net")
     for cidr in allow_cidrs:
         args += ["--allow-cidr", cidr]
-    for host_port, guest_port in ports:
-        args += ["-p", f"{host_port}:{guest_port}"]
-    for host_path, guest_path, read_only in volumes:
-        suffix = ":ro" if read_only else ""
-        args += ["-v", f"{host_path}:{guest_path}{suffix}"]
     if env:
         for k, v in env.items():
             args += ["-e", f"{k}={v}"]

bot_bottle/bottle/__init__.py

@@ -0,0 +1,11 @@
+"""Bottle lifecycle primitives."""
+
+from .runner import BottleError, destroy, freeze, resume_headless, start_headless
+
+__all__ = [
+    "BottleError",
+    "destroy",
+    "freeze",
+    "resume_headless",
+    "start_headless",
+]

bot_bottle/bottle/runner.py

@@ -0,0 +1,258 @@
+"""Public Python API for programmatic bottle orchestration.
+
+Stable surface for bot-bottle-orchestrator (and other Python callers) to
+drive bottles without invoking the CLI as a subprocess.  Every function
+converts ``Die`` and non-zero agent exit codes to ``BottleError`` so
+callers use exception handling rather than inspecting return values.
+
+The Protocol the orchestrator's ``BottleRunner`` targets looks like::
+
+    class BottleRunner(Protocol):
+        def start(self, agent: str, *, prompt: str, ...) -> str: ...
+        def resume(self, slug: str, *, prompt: str) -> None: ...
+        def freeze(self, slug: str) -> None: ...
+        def destroy(self, slug: str) -> None: ...
+
+A ``SubprocessBottleRunner`` calls ``./cli.py`` for each operation.  A
+``ProgrammaticBottleRunner`` calls these functions directly; the Protocol
+call sites in ``lifecycle.py`` are unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence, cast
+
+from ..backend import BottleSpec
+from ..backend.freeze import CommitCancelled, get_freezer
+from .state import cleanup_state, clear_preserve_marker, read_metadata
+from ..cli._common import USER_CWD
+from ..cli.start import _launch_bottle, _peek_agent_bottle, _uniquify_label_headless
+from ..log import Die
+from ..manifest import ManifestError, ManifestIndex
+
+
+class BottleError(Exception):
+    """Raised when a bottle operation fails.
+
+    ``exit_code`` carries the agent process's exit code when the failure is
+    a non-zero agent exit; 1 for all other failure modes (missing state,
+    backend errors, etc.)."""
+
+    def __init__(self, message: str, *, exit_code: int = 1) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+def start_headless(
+    agent_name: str,
+    *,
+    prompt: str,
+    bottles: Sequence[str] | None = None,
+    label: str | None = None,
+    color: str | None = None,
+    backend_name: str | None = None,
+    copy_cwd: bool = False,
+    forge_env: dict[str, str] | None = None,
+    user_cwd: str | None = None,
+) -> str:
+    """Launch a new bottle headlessly.  Returns the bottle slug.
+
+    ``forge_env`` is passed through to the forge sidecar (not the agent)
+    when the bottle is forge-targeted; it carries the credentials and
+    context the sidecar needs to call the forge API.
+
+    Raises ``BottleError`` on configuration errors or if the agent exits
+    non-zero.  The returned slug can be passed to ``freeze()``,
+    ``resume_headless()``, or ``destroy()`` for subsequent lifecycle
+    operations."""
+    cwd = user_cwd or USER_CWD
+    try:
+        manifest = ManifestIndex.resolve(cwd)
+        manifest.require_agent(agent_name)
+    except (Die, ManifestError) as exc:
+        raise BottleError(str(exc)) from exc
+
+    if bottles:
+        bottle_names: tuple[str, ...] = tuple(bottles)
+    else:
+        default_bottle = _peek_agent_bottle(manifest, agent_name)
+        if not default_bottle:
+            raise BottleError(
+                f"agent '{agent_name}' has no default bottle; "
+                f"pass bottles=[...]"
+            )
+        bottle_names = (default_bottle,)
+
+    spec = BottleSpec(
+        manifest=manifest,
+        agent_name=agent_name,
+        copy_cwd=copy_cwd,
+        user_cwd=cwd,
+        label=_uniquify_label_headless(label or agent_name),
+        color=color or "",
+        bottle_names=bottle_names,
+        forge_env=dict(forge_env) if forge_env else {},
+    )
+    try:
+        slug, exit_code = _launch_bottle(
+            spec,
+            dry_run=False,
+            backend_name=backend_name,
+            assume_yes=True,
+            headless_prompt_text=prompt,
+        )
+    except Die as exc:
+        raise BottleError(exc.message, exit_code=cast(int, exc.code)) from exc
+    if exit_code != 0:
+        raise BottleError(
+            f"agent exited {exit_code} (slug={slug!r})", exit_code=exit_code
+        )
+    return slug
+
+
+def resume_headless(
+    slug: str,
+    *,
+    prompt: str,
+    backend_name: str | None = None,
+    forge_env: dict[str, str] | None = None,
+) -> None:
+    """Resume a frozen bottle headlessly with ``prompt``.
+
+    ``forge_env`` re-supplies forge context for the new session (the
+    sidecar is relaunched alongside the agent on resume).
+
+    Raises ``BottleError`` on missing state, backend errors, or non-zero
+    agent exit."""
+    metadata = read_metadata(slug)
+    if metadata is None:
+        raise BottleError(
+            f"no state recorded for slug {slug!r}; "
+            f"check ~/.bot-bottle/state/ or call start_headless() to create a new bottle"
+        )
+
+    try:
+        manifest = ManifestIndex.resolve(metadata.cwd or USER_CWD)
+        manifest.require_agent(metadata.agent_name)
+    except (Die, ManifestError) as exc:
+        raise BottleError(str(exc)) from exc
+
+    spec = BottleSpec(
+        manifest=manifest,
+        agent_name=metadata.agent_name,
+        copy_cwd=metadata.copy_cwd,
+        user_cwd=metadata.cwd or USER_CWD,
+        identity=metadata.identity,
+        bottle_names=tuple(metadata.bottle_names),
+        forge_env=dict(forge_env) if forge_env else {},
+    )
+    try:
+        _, exit_code = _launch_bottle(
+            spec,
+            dry_run=False,
+            backend_name=backend_name or metadata.backend or None,
+            assume_yes=True,
+            headless_prompt_text=prompt,
+        )
+    except Die as exc:
+        raise BottleError(exc.message, exit_code=cast(int, exc.code)) from exc
+    if exit_code != 0:
+        raise BottleError(
+            f"agent exited {exit_code} resuming {slug!r}", exit_code=exit_code
+        )
+
+
+def freeze(slug: str, *, backend_name: str | None = None) -> None:
+    """Freeze the named bottle to a resumable artifact.
+
+    Reads the bottle's backend from its metadata when ``backend_name`` is
+    not supplied.  Raises ``BottleError`` if the freeze fails."""
+    metadata = read_metadata(slug)
+    resolved_backend = backend_name or (metadata.backend if metadata else "") or "docker"
+    try:
+        get_freezer(resolved_backend).commit_slug(slug)
+    except CommitCancelled as exc:
+        raise BottleError(f"freeze cancelled for {slug!r}") from exc
+    except Die as exc:
+        raise BottleError(exc.message, exit_code=cast(int, exc.code)) from exc
+
+
+def destroy(slug: str, *, backend_name: str | None = None) -> None:
+    """Destroy the named bottle, removing all resources and state.
+
+    Brings down any running resources for ``slug``, then removes the
+    per-bottle state directory.  Idempotent: a slug with no running
+    resources or no state directory is not an error."""
+    metadata = read_metadata(slug)
+    resolved_backend = backend_name or (metadata.backend if metadata else "") or "docker"
+    try:
+        if resolved_backend == "docker":
+            _destroy_docker(slug)
+        elif resolved_backend == "smolmachines":
+            _destroy_smolmachines(slug)
+        # macos-container: the container is torn down inside the launch
+        # context manager; no persistent VM survives, so nothing extra is
+        # needed at destroy time beyond the state-dir removal below.
+    except Die as exc:
+        raise BottleError(exc.message, exit_code=cast(int, exc.code)) from exc
+    clear_preserve_marker(slug)
+    cleanup_state(slug)
+
+
+# --- backend-specific helpers -----------------------------------------------
+
+
+def _destroy_docker(slug: str) -> None:
+    """Best-effort ``docker compose down`` for a Docker bottle.
+
+    No-op when the compose file is absent — the project was already
+    brought down (normal for a frozen bottle) or was never created."""
+    from ..backend.docker.compose import (
+        compose_down,
+        compose_file_path,
+        compose_project_name,
+    )
+    from .state import bottle_state_dir
+
+    state_dir = bottle_state_dir(slug)
+    compose_file = compose_file_path(state_dir)
+    if compose_file.exists():
+        compose_down(compose_project_name(slug), compose_file)
+
+
+def _destroy_smolmachines(slug: str) -> None:
+    """Best-effort stop + delete for a smolmachines bottle.
+
+    Both steps are best-effort: a machine that is already gone does not
+    cause an error; partial failures are logged as warnings."""
+    import subprocess
+
+    from ..log import warn
+
+    machine = f"bot-bottle-{slug}"
+    subprocess.run(
+        ["smolvm", "machine", "stop", "--name", machine],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        check=False,
+    )
+    r = subprocess.run(
+        ["smolvm", "machine", "delete", "-f", machine],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if r.returncode != 0:
+        warn(
+            f"smolvm machine delete -f {machine!r} failed "
+            f"(may already be gone): {(r.stderr or '').strip()}"
+        )
+
+
+__all__ = [
+    "BottleError",
+    "destroy",
+    "freeze",
+    "resume_headless",
+    "start_headless",
+]

bot_bottle/bottle/state.py

@@ -0,0 +1,364 @@
+"""Per-bottle persistent state.
+
+Holds optional per-bottle Dockerfile overrides, the transcript snapshot
+the state-preservation helper saves before teardown, and the launch metadata that lets
+`cli.py resume <identity>` reconstruct a bottle's spec. State
+lives at:
+
+    ~/.bot-bottle/state/<identity>/
+        metadata.json     — agent_name + cwd + started_at (for resume)
+        Dockerfile        — per-bottle override (absent → use repo's)
+        transcript/       — last snapshotted agent state (best-effort)
+
+When the per-bottle Dockerfile is present, the launch step builds
+the agent image with a per-bottle tag (bot-bottle-rebuilt-<id>)
+from this file rather than the repo's. The build context is still
+the repo root so the Dockerfile can COPY bot_bottle source files
+the same way the original does.
+
+Identity model:
+- Every `cli.py start <agent>` mints a fresh identity via
+  `bottle_identity(agent_name)`: slug-prefix for readability plus a
+  5-char random suffix for parallel-safe uniqueness. The metadata
+  written at launch time pins (agent_name, cwd) to that identity.
+- `cli.py resume <identity>` reads the metadata and re-launches a
+  bottle pinned to the same identity, picking up any per-bottle
+  Dockerfile and transcript snapshot.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import secrets
+import string
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+from .. import supervise as _supervise
+
+
+# Directory layout: ~/.bot-bottle/state/<identity>/...
+_STATE_SUBDIR = "state"
+_PER_BOTTLE_DOCKERFILE_NAME = "Dockerfile"
+_COMMITTED_IMAGE_NAME = "committed-image"
+_TRANSCRIPT_SUBDIR = "transcript"
+# Per-sidecar scratch subdirs. PRD 0018 chunk 2: bind-mount sources
+# live here so chunk 3's `docker compose up` can find them at stable
+# paths. Each sidecar's `prepare()` writes config + CAs into its own
+# subdir; the launch step is unchanged today (still `docker cp`).
+_EGRESS_SUBDIR = "egress"
+_GIT_GATE_SUBDIR = "git-gate"
+_SUPERVISE_SUBDIR = "supervise"
+_AGENT_SUBDIR = "agent"
+_METADATA_NAME = "metadata.json"
+# Live-config dir bind-mounted into the supervise sidecar (read-only).
+# Host's apply paths keep these files fresh so supervise's
+# `list-egress-routes` MCP tool returns the current state —
+# not a snapshot from launch time.
+_LIVE_CONFIG_SUBDIR = "live-config"
+LIVE_CONFIG_ROUTES_NAME = "routes.yaml"
+LIVE_CONFIG_ALLOWLIST_NAME = "allowlist"
+# Empty marker file. Session preservation writes it before teardown so
+# cli.py's session-end cleanup knows to preserve the state dir for
+# `cli.py resume <identity>`. Absent = clean up.
+_PRESERVE_MARKER = ".preserve"
+
+# 5 chars of base36 alphabet ≈ 60M combinations. Plenty for human
+# operators starting bottles by hand; collision-free in practice.
+_RANDOM_SUFFIX_LEN = 5
+_SUFFIX_ALPHABET = string.ascii_lowercase + string.digits
+
+
+def bottle_identity(agent_name: str) -> str:
+    """Mint a fresh per-launch bottle identity. The slug-prefix is
+    `slugify(agent_name)` for readability; the suffix is 5 random
+    base36 chars so two simultaneous `start <agent>` invocations
+    don't collide on container/network names.
+
+    Every call produces a different identity (non-deterministic).
+    To continue an existing bottle's state, use the recorded
+    identity from BottleMetadata via `cli.py resume <identity>`,
+    not this function."""
+    from ..backend.docker import util as docker_mod
+    slug = docker_mod.slugify(agent_name)
+    suffix = "".join(secrets.choice(_SUFFIX_ALPHABET) for _ in range(_RANDOM_SUFFIX_LEN))
+    return f"{slug}-{suffix}"
+
+
+@dataclass(frozen=True)
+class BottleMetadata:
+    """Persistent record of how a bottle was launched, written at
+    start time and read by `cli.py resume`. Lives at
+    ~/.bot-bottle/state/<identity>/metadata.json."""
+
+    identity: str
+    agent_name: str
+    cwd: str           # empty string when --cwd was not passed
+    copy_cwd: bool
+    started_at: str    # ISO 8601 UTC
+    # PRD 0018 chunk 3: derivable from identity via
+    # `compose_project_name(identity)`, but persisted explicitly so
+    # dashboard / cleanup / resume tooling can read it without
+    # importing the compose module. Empty string for state dirs
+    # written before chunk 3 (resume / inspect should fall back to
+    # deriving from identity in that case).
+    compose_project: str = ""
+    # PRD 0040: backend name ("docker" or "smolmachines"). Empty string
+    # for state dirs written before PRD 0040; callers default to "docker"
+    # for backward compatibility.
+    backend: str = ""
+    label: str = ""
+    color: str = ""
+    # Ordered bottle names selected at launch (issue #269). Empty tuple
+    # for state dirs written before this change; resume falls back to
+    # the agent's `bottle:` field in that case.
+    bottle_names: tuple[str, ...] = ()
+
+
+def metadata_path(identity: str) -> Path:
+    return bottle_state_dir(identity) / _METADATA_NAME
+
+
+def write_metadata(metadata: BottleMetadata) -> Path:
+    """Persist `metadata` to ~/.bot-bottle/state/<identity>/metadata.json.
+    Mode 0o644 — no secrets, just (agent_name, cwd, timestamp)."""
+    path = metadata_path(metadata.identity)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(dataclasses.asdict(metadata), indent=2) + "\n")
+    path.chmod(0o644)
+    return path
+
+
+def read_metadata(identity: str) -> BottleMetadata | None:
+    """Return the metadata for `identity`, or None if no state has
+    been recorded for it. Used by `cli.py resume` to reconstruct
+    the launch spec."""
+    path = metadata_path(identity)
+    if not path.is_file():
+        return None
+    raw = json.loads(path.read_text())
+    if not isinstance(raw, dict):
+        return None
+    raw_typed = cast(dict[str, object], raw)
+    raw_bottle_names = raw_typed.get("bottle_names", [])
+    bottle_names: tuple[str, ...] = ()
+    if isinstance(raw_bottle_names, list):
+        bottle_names = tuple(str(n) for n in raw_bottle_names if isinstance(n, str))
+    return BottleMetadata(
+        identity=str(raw_typed.get("identity", identity)),
+        agent_name=str(raw_typed.get("agent_name", "")),
+        cwd=str(raw_typed.get("cwd", "")),
+        copy_cwd=bool(raw_typed.get("copy_cwd", False)),
+        started_at=str(raw_typed.get("started_at", "")),
+        compose_project=str(raw_typed.get("compose_project", "")),
+        backend=str(raw_typed.get("backend", "")),
+        label=str(raw_typed.get("label", "")),
+        color=str(raw_typed.get("color", "")),
+        bottle_names=bottle_names,
+    )
+
+
+def bottle_state_dir(identity: str) -> Path:
+    """Per-bottle state directory on the host. Created lazily by the
+    write helpers; readers tolerate its absence."""
+    return _supervise.bot_bottle_root() / _STATE_SUBDIR / identity
+
+
+def per_bottle_dockerfile_path(identity: str) -> Path:
+    return bottle_state_dir(identity) / _PER_BOTTLE_DOCKERFILE_NAME
+
+
+def per_bottle_dockerfile(identity: str) -> str | None:
+    """Return the per-bottle Dockerfile content if present, else
+    None. None means: use the provider or manifest Dockerfile."""
+    p = per_bottle_dockerfile_path(identity)
+    if p.is_file():
+        return p.read_text()
+    return None
+
+
+def write_per_bottle_dockerfile(identity: str, content: str) -> Path:
+    p = per_bottle_dockerfile_path(identity)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(content)
+    p.chmod(0o644)
+    return p
+
+
+def committed_image_path(identity: str) -> Path:
+    return bottle_state_dir(identity) / _COMMITTED_IMAGE_NAME
+
+
+def write_committed_image(identity: str, image_tag: str) -> Path:
+    """Persist the committed image tag for `identity`. The next
+    `cli.py resume <identity>` will boot from this image instead of
+    rebuilding from the Dockerfile."""
+    path = committed_image_path(identity)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(image_tag.strip() + "\n")
+    path.chmod(0o644)
+    return path
+
+
+def read_committed_image(identity: str) -> str | None:
+    """Return the committed image tag for `identity`, or None if no
+    commit has been recorded. Used by the Docker launch step to skip
+    the Dockerfile build when a committed snapshot exists."""
+    path = committed_image_path(identity)
+    if not path.is_file():
+        return None
+    tag = path.read_text().strip()
+    return tag or None
+
+
+def per_bottle_image_tag(identity: str) -> str:
+    """Image tag for a rebuilt bottle. Distinct from the base
+    bot-bottle-claude:latest so per-bottle rebuilds don't collide in
+    the docker image cache."""
+    return f"bot-bottle-rebuilt-{identity}:latest"
+
+
+def live_config_dir(identity: str) -> Path:
+    """Per-bottle live-config dir. Bind-mounted read-only into the
+    supervise sidecar; the host's apply paths refresh the files on
+    every operator approval so the agent's `list-*` MCP tools always
+    return current state."""
+    return bottle_state_dir(identity) / _LIVE_CONFIG_SUBDIR
+
+
+def live_routes_path(identity: str) -> Path:
+    return live_config_dir(identity) / LIVE_CONFIG_ROUTES_NAME
+
+
+def live_allowlist_path(identity: str) -> Path:
+    return live_config_dir(identity) / LIVE_CONFIG_ALLOWLIST_NAME
+
+
+def write_live_config(
+    identity: str, *, routes: str = "", allowlist: str = "",
+) -> Path:
+    """Initialise (or refresh) the live-config dir. Empty-string args
+    leave the existing file alone (caller passes only what it knows).
+    Returns the live-config dir path."""
+    d = live_config_dir(identity)
+    d.mkdir(parents=True, exist_ok=True)
+    if routes:
+        p = live_routes_path(identity)
+        p.write_text(routes)
+        p.chmod(0o644)
+    if allowlist:
+        p = live_allowlist_path(identity)
+        p.write_text(allowlist)
+        p.chmod(0o644)
+    return d
+
+
+def transcript_snapshot_dir(identity: str) -> Path:
+    """Where agent session snapshots are kept for resume flows."""
+    return bottle_state_dir(identity) / _TRANSCRIPT_SUBDIR
+
+
+# --- Per-sidecar scratch subdirs (PRD 0018 chunk 2) ------------------------
+#
+# Each sidecar gets its own subdir under the bottle's state dir for
+# bind-mount sources (config, CAs, hooks, etc.). Prepare-time writes
+# land here; the state dir's normal cleanup (`cleanup_state`) reaps
+# them along with everything else when the bottle session ends and
+# nothing requested preservation.
+
+
+def egress_state_dir(identity: str) -> Path:
+    """State subdir for the egress sidecar: routes.yaml + the
+    per-bottle mitmproxy CA. Bind-mount source from chunk 3 onward."""
+    return bottle_state_dir(identity) / _EGRESS_SUBDIR
+
+
+def git_gate_state_dir(identity: str) -> Path:
+    """State subdir for the git-gate sidecar: entrypoint + hooks +
+    per-upstream known_hosts. Bind-mount source from chunk 3
+    onward."""
+    return bottle_state_dir(identity) / _GIT_GATE_SUBDIR
+
+
+def supervise_state_dir(identity: str) -> Path:
+    """State subdir reserved for supervise sidecar bind-mount sources.
+    The queue dir is intentionally NOT under here — it lives at
+    ~/.bot-bottle/queue/<slug>/ alongside the audit logs, so it
+    survives state-dir cleanup."""
+    return bottle_state_dir(identity) / _SUPERVISE_SUBDIR
+
+
+def agent_state_dir(identity: str) -> Path:
+    """State subdir for the agent's prepare-time scratch files: the
+    env file (docker --env-file source) and the prompt file."""
+    return bottle_state_dir(identity) / _AGENT_SUBDIR
+
+
+# --- Preserve-on-close marker ----------------------------------------------
+
+
+def preserve_marker_path(identity: str) -> Path:
+    return bottle_state_dir(identity) / _PRESERVE_MARKER
+
+
+def mark_preserved(identity: str) -> Path:
+    """Mark this bottle's state for preservation across session
+    teardown so cli.py's session-end cleanup leaves the state dir
+    intact for a subsequent `cli.py resume`."""
+    path = preserve_marker_path(identity)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.touch()
+    return path
+
+
+def is_preserved(identity: str) -> bool:
+    return preserve_marker_path(identity).exists()
+
+
+def clear_preserve_marker(identity: str) -> None:
+    """Idempotent removal. Called at fresh launch (start or resume)
+    so a marker left from a prior preserved session doesn't keep
+    state alive past the next normal session-end."""
+    try:
+        preserve_marker_path(identity).unlink()
+    except FileNotFoundError:
+        pass
+
+
+def cleanup_state(identity: str) -> None:
+    """Remove the per-bottle state dir entirely. Called by cli.py
+    when a bottle session ends and is_preserved(identity) is False.
+    Idempotent — missing dir is success."""
+    import shutil
+    state_dir = bottle_state_dir(identity)
+    if state_dir.is_dir():
+        shutil.rmtree(state_dir, ignore_errors=True)
+
+
+__all__ = [
+    "BottleMetadata",
+    "agent_state_dir",
+    "bottle_identity",
+    "bottle_state_dir",
+    "cleanup_state",
+    "clear_preserve_marker",
+    "committed_image_path",
+    "egress_state_dir",
+    "git_gate_state_dir",
+    "is_preserved",
+    "mark_preserved",
+    "metadata_path",
+    "per_bottle_dockerfile",
+    "per_bottle_dockerfile_path",
+    "per_bottle_image_tag",
+    "preserve_marker_path",
+    "read_committed_image",
+    "read_metadata",
+    "supervise_state_dir",
+    "transcript_snapshot_dir",
+    "write_committed_image",
+    "write_metadata",
+    "write_per_bottle_dockerfile",
+]

bot_bottle/bottle_state.py

@@ -1,363 +1,6 @@
-"""Per-bottle persistent state.
+"""Compatibility wrapper for per-bottle persistent state.
 
-Holds optional per-bottle Dockerfile overrides, the transcript snapshot
+The implementation lives in :mod:`bot_bottle.bottle.state`.
-the state-preservation helper saves before teardown, and the launch metadata that lets
-`cli.py resume <identity>` reconstruct a bottle's spec. State
-lives at:
-
-    ~/.bot-bottle/state/<identity>/
-        metadata.json     — agent_name + cwd + started_at (for resume)
-        Dockerfile        — per-bottle override (absent → use repo's)
-        transcript/       — last snapshotted agent state (best-effort)
-
-When the per-bottle Dockerfile is present, the launch step builds
-the agent image with a per-bottle tag (bot-bottle-rebuilt-<id>)
-from this file rather than the repo's. The build context is still
-the repo root so the Dockerfile can COPY bot_bottle source files
-the same way the original does.
-
-Identity model:
-- Every `cli.py start <agent>` mints a fresh identity via
-  `bottle_identity(agent_name)`: slug-prefix for readability plus a
-  5-char random suffix for parallel-safe uniqueness. The metadata
-  written at launch time pins (agent_name, cwd) to that identity.
-- `cli.py resume <identity>` reads the metadata and re-launches a
-  bottle pinned to the same identity, picking up any per-bottle
-  Dockerfile and transcript snapshot.
 """
 
-from __future__ import annotations
+from .bottle.state import *  # noqa: F403
-
-import dataclasses
-import json
-import secrets
-import string
-from dataclasses import dataclass
-from pathlib import Path
-from typing import cast
-
-from . import supervise as _supervise
-
-
-# Directory layout: ~/.bot-bottle/state/<identity>/...
-_STATE_SUBDIR = "state"
-_PER_BOTTLE_DOCKERFILE_NAME = "Dockerfile"
-_COMMITTED_IMAGE_NAME = "committed-image"
-_TRANSCRIPT_SUBDIR = "transcript"
-# Per-sidecar scratch subdirs. PRD 0018 chunk 2: bind-mount sources
-# live here so chunk 3's `docker compose up` can find them at stable
-# paths. Each sidecar's `prepare()` writes config + CAs into its own
-# subdir; the launch step is unchanged today (still `docker cp`).
-_EGRESS_SUBDIR = "egress"
-_GIT_GATE_SUBDIR = "git-gate"
-_SUPERVISE_SUBDIR = "supervise"
-_AGENT_SUBDIR = "agent"
-_METADATA_NAME = "metadata.json"
-# Live-config dir bind-mounted into the supervise sidecar (read-only).
-# Host's apply paths keep these files fresh so supervise's
-# `list-egress-routes` MCP tool returns the current state —
-# not a snapshot from launch time.
-_LIVE_CONFIG_SUBDIR = "live-config"
-LIVE_CONFIG_ROUTES_NAME = "routes.yaml"
-LIVE_CONFIG_ALLOWLIST_NAME = "allowlist"
-# Empty marker file. Session preservation writes it before teardown so
-# cli.py's session-end cleanup knows to preserve the state dir for
-# `cli.py resume <identity>`. Absent = clean up.
-_PRESERVE_MARKER = ".preserve"
-
-# 5 chars of base36 alphabet ≈ 60M combinations. Plenty for human
-# operators starting bottles by hand; collision-free in practice.
-_RANDOM_SUFFIX_LEN = 5
-_SUFFIX_ALPHABET = string.ascii_lowercase + string.digits
-
-
-def bottle_identity(agent_name: str) -> str:
-    """Mint a fresh per-launch bottle identity. The slug-prefix is
-    `slugify(agent_name)` for readability; the suffix is 5 random
-    base36 chars so two simultaneous `start <agent>` invocations
-    don't collide on container/network names.
-
-    Every call produces a different identity (non-deterministic).
-    To continue an existing bottle's state, use the recorded
-    identity from BottleMetadata via `cli.py resume <identity>`,
-    not this function."""
-    from .backend.docker import util as docker_mod
-    slug = docker_mod.slugify(agent_name)
-    suffix = "".join(secrets.choice(_SUFFIX_ALPHABET) for _ in range(_RANDOM_SUFFIX_LEN))
-    return f"{slug}-{suffix}"
-
-
-@dataclass(frozen=True)
-class BottleMetadata:
-    """Persistent record of how a bottle was launched, written at
-    start time and read by `cli.py resume`. Lives at
-    ~/.bot-bottle/state/<identity>/metadata.json."""
-
-    identity: str
-    agent_name: str
-    cwd: str           # empty string when --cwd was not passed
-    copy_cwd: bool
-    started_at: str    # ISO 8601 UTC
-    # PRD 0018 chunk 3: derivable from identity via
-    # `compose_project_name(identity)`, but persisted explicitly so
-    # dashboard / cleanup / resume tooling can read it without
-    # importing the compose module. Empty string for state dirs
-    # written before chunk 3 (resume / inspect should fall back to
-    # deriving from identity in that case).
-    compose_project: str = ""
-    # PRD 0040: backend name ("docker" or "smolmachines"). Empty string
-    # for state dirs written before PRD 0040; callers default to "docker"
-    # for backward compatibility.
-    backend: str = ""
-    label: str = ""
-    color: str = ""
-    # Ordered bottle names selected at launch (issue #269). Empty tuple
-    # for state dirs written before this change; resume falls back to
-    # the agent's `bottle:` field in that case.
-    bottle_names: tuple[str, ...] = ()
-
-
-def metadata_path(identity: str) -> Path:
-    return bottle_state_dir(identity) / _METADATA_NAME
-
-
-def write_metadata(metadata: BottleMetadata) -> Path:
-    """Persist `metadata` to ~/.bot-bottle/state/<identity>/metadata.json.
-    Mode 0o644 — no secrets, just (agent_name, cwd, timestamp)."""
-    path = metadata_path(metadata.identity)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(dataclasses.asdict(metadata), indent=2) + "\n")
-    path.chmod(0o644)
-    return path
-
-
-def read_metadata(identity: str) -> BottleMetadata | None:
-    """Return the metadata for `identity`, or None if no state has
-    been recorded for it. Used by `cli.py resume` to reconstruct
-    the launch spec."""
-    path = metadata_path(identity)
-    if not path.is_file():
-        return None
-    raw = json.loads(path.read_text())
-    if not isinstance(raw, dict):
-        return None
-    raw_typed = cast(dict[str, object], raw)
-    raw_bottle_names = raw_typed.get("bottle_names", [])
-    bottle_names: tuple[str, ...] = ()
-    if isinstance(raw_bottle_names, list):
-        bottle_names = tuple(str(n) for n in raw_bottle_names if isinstance(n, str))
-    return BottleMetadata(
-        identity=str(raw_typed.get("identity", identity)),
-        agent_name=str(raw_typed.get("agent_name", "")),
-        cwd=str(raw_typed.get("cwd", "")),
-        copy_cwd=bool(raw_typed.get("copy_cwd", False)),
-        started_at=str(raw_typed.get("started_at", "")),
-        compose_project=str(raw_typed.get("compose_project", "")),
-        backend=str(raw_typed.get("backend", "")),
-        label=str(raw_typed.get("label", "")),
-        color=str(raw_typed.get("color", "")),
-        bottle_names=bottle_names,
-    )
-
-
-def bottle_state_dir(identity: str) -> Path:
-    """Per-bottle state directory on the host. Created lazily by the
-    write helpers; readers tolerate its absence."""
-    return _supervise.bot_bottle_root() / _STATE_SUBDIR / identity
-
-
-def per_bottle_dockerfile_path(identity: str) -> Path:
-    return bottle_state_dir(identity) / _PER_BOTTLE_DOCKERFILE_NAME
-
-
-def per_bottle_dockerfile(identity: str) -> str | None:
-    """Return the per-bottle Dockerfile content if present, else
-    None. None means: use the provider or manifest Dockerfile."""
-    p = per_bottle_dockerfile_path(identity)
-    if p.is_file():
-        return p.read_text()
-    return None
-
-
-def write_per_bottle_dockerfile(identity: str, content: str) -> Path:
-    p = per_bottle_dockerfile_path(identity)
-    p.parent.mkdir(parents=True, exist_ok=True)
-    p.write_text(content)
-    p.chmod(0o644)
-    return p
-
-
-def committed_image_path(identity: str) -> Path:
-    return bottle_state_dir(identity) / _COMMITTED_IMAGE_NAME
-
-
-def write_committed_image(identity: str, image_tag: str) -> Path:
-    """Persist the committed image tag for `identity`. The next
-    `cli.py resume <identity>` will boot from this image instead of
-    rebuilding from the Dockerfile."""
-    path = committed_image_path(identity)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(image_tag.strip() + "\n")
-    path.chmod(0o644)
-    return path
-
-
-def read_committed_image(identity: str) -> str | None:
-    """Return the committed image tag for `identity`, or None if no
-    commit has been recorded. Used by the Docker launch step to skip
-    the Dockerfile build when a committed snapshot exists."""
-    path = committed_image_path(identity)
-    if not path.is_file():
-        return None
-    tag = path.read_text().strip()
-    return tag or None
-
-
-def per_bottle_image_tag(identity: str) -> str:
-    """Image tag for a rebuilt bottle. Distinct from the base
-    bot-bottle-claude:latest so per-bottle rebuilds don't collide in
-    the docker image cache."""
-    return f"bot-bottle-rebuilt-{identity}:latest"
-
-
-def live_config_dir(identity: str) -> Path:
-    """Per-bottle live-config dir. Bind-mounted read-only into the
-    supervise sidecar; the host's apply paths refresh the files on
-    every operator approval so the agent's `list-*` MCP tools always
-    return current state."""
-    return bottle_state_dir(identity) / _LIVE_CONFIG_SUBDIR
-
-
-def live_routes_path(identity: str) -> Path:
-    return live_config_dir(identity) / LIVE_CONFIG_ROUTES_NAME
-
-
-def live_allowlist_path(identity: str) -> Path:
-    return live_config_dir(identity) / LIVE_CONFIG_ALLOWLIST_NAME
-
-
-def write_live_config(
-    identity: str, *, routes: str = "", allowlist: str = "",
-) -> Path:
-    """Initialise (or refresh) the live-config dir. Empty-string args
-    leave the existing file alone (caller passes only what it knows).
-    Returns the live-config dir path."""
-    d = live_config_dir(identity)
-    d.mkdir(parents=True, exist_ok=True)
-    if routes:
-        p = live_routes_path(identity)
-        p.write_text(routes)
-        p.chmod(0o644)
-    if allowlist:
-        p = live_allowlist_path(identity)
-        p.write_text(allowlist)
-        p.chmod(0o644)
-    return d
-
-
-def transcript_snapshot_dir(identity: str) -> Path:
-    """Where agent session snapshots are kept for resume flows."""
-    return bottle_state_dir(identity) / _TRANSCRIPT_SUBDIR
-
-
-# --- Per-sidecar scratch subdirs (PRD 0018 chunk 2) ------------------------
-#
-# Each sidecar gets its own subdir under the bottle's state dir for
-# bind-mount sources (config, CAs, hooks, etc.). Prepare-time writes
-# land here; the state dir's normal cleanup (`cleanup_state`) reaps
-# them along with everything else when the bottle session ends and
-# nothing requested preservation.
-
-
-def egress_state_dir(identity: str) -> Path:
-    """State subdir for the egress sidecar: routes.yaml + the
-    per-bottle mitmproxy CA. Bind-mount source from chunk 3 onward."""
-    return bottle_state_dir(identity) / _EGRESS_SUBDIR
-
-
-def git_gate_state_dir(identity: str) -> Path:
-    """State subdir for the git-gate sidecar: entrypoint + hooks +
-    per-upstream known_hosts. Bind-mount source from chunk 3
-    onward."""
-    return bottle_state_dir(identity) / _GIT_GATE_SUBDIR
-
-
-def supervise_state_dir(identity: str) -> Path:
-    """State subdir reserved for supervise sidecar bind-mount sources.
-    Runtime queue/audit rows live in the host-level bot-bottle SQLite
-    database, so they survive state-dir cleanup."""
-    return bottle_state_dir(identity) / _SUPERVISE_SUBDIR
-
-
-def agent_state_dir(identity: str) -> Path:
-    """State subdir for the agent's prepare-time scratch files: the
-    env file (docker --env-file source) and the prompt file."""
-    return bottle_state_dir(identity) / _AGENT_SUBDIR
-
-
-# --- Preserve-on-close marker ----------------------------------------------
-
-
-def preserve_marker_path(identity: str) -> Path:
-    return bottle_state_dir(identity) / _PRESERVE_MARKER
-
-
-def mark_preserved(identity: str) -> Path:
-    """Mark this bottle's state for preservation across session
-    teardown so cli.py's session-end cleanup leaves the state dir
-    intact for a subsequent `cli.py resume`."""
-    path = preserve_marker_path(identity)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.touch()
-    return path
-
-
-def is_preserved(identity: str) -> bool:
-    return preserve_marker_path(identity).exists()
-
-
-def clear_preserve_marker(identity: str) -> None:
-    """Idempotent removal. Called at fresh launch (start or resume)
-    so a marker left from a prior preserved session doesn't keep
-    state alive past the next normal session-end."""
-    try:
-        preserve_marker_path(identity).unlink()
-    except FileNotFoundError:
-        pass
-
-
-def cleanup_state(identity: str) -> None:
-    """Remove the per-bottle state dir entirely. Called by cli.py
-    when a bottle session ends and is_preserved(identity) is False.
-    Idempotent — missing dir is success."""
-    import shutil
-    state_dir = bottle_state_dir(identity)
-    if state_dir.is_dir():
-        shutil.rmtree(state_dir, ignore_errors=True)
-
-
-__all__ = [
-    "BottleMetadata",
-    "agent_state_dir",
-    "bottle_identity",
-    "bottle_state_dir",
-    "cleanup_state",
-    "clear_preserve_marker",
-    "committed_image_path",
-    "egress_state_dir",
-    "git_gate_state_dir",
-    "is_preserved",
-    "mark_preserved",
-    "metadata_path",
-    "per_bottle_dockerfile",
-    "per_bottle_dockerfile_path",
-    "per_bottle_image_tag",
-    "preserve_marker_path",
-    "read_committed_image",
-    "read_metadata",
-    "supervise_state_dir",
-    "transcript_snapshot_dir",
-    "write_committed_image",
-    "write_metadata",
-    "write_per_bottle_dockerfile",
-]

bot_bottle/cli/commit.py

@@ -14,7 +14,7 @@ import argparse
 
 from ..backend import enumerate_active_agents
 from ..backend.freeze import CommitCancelled, get_freezer
-from ..bottle_state import read_metadata
+from ..bottle.state import read_metadata
 from ..log import die
 from ._common import PROG
 from . import tui

bot_bottle/cli/resume.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 import argparse
 
 from ..backend import BottleSpec
-from ..bottle_state import read_metadata
+from ..bottle.state import read_metadata
 from ..log import die
 from ..manifest import ManifestIndex
 from ._common import PROG, USER_CWD
@@ -27,12 +27,34 @@ from .start import _launch_bottle
 def cmd_resume(argv: list[str]) -> int:
     parser = argparse.ArgumentParser(prog=f"{PROG} resume", add_help=True)
     parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument(
+        "--headless",
+        action="store_true",
+        help=(
+            "non-interactive rehydrate: deliver --prompt to the agent and "
+            "skip the y/N preflight. For orchestrators / the freeze-rehydrate "
+            "loop."
+        ),
+    )
+    parser.add_argument(
+        "--prompt",
+        default=None,
+        help="follow-up prompt delivered to the agent (required with --headless)",
+    )
     parser.add_argument(
         "identity",
         help="bottle identity from a prior `start` (see its session-end output)",
     )
     args = parser.parse_args(argv)
 
+    if args.prompt and not args.headless:
+        die("--prompt is only valid with --headless")
+    if args.headless and not args.prompt:
+        die(
+            "--headless requires --prompt: "
+            "./cli.py resume <identity> --headless --prompt 'Address the review'"
+        )
+
     metadata = read_metadata(args.identity)
     if metadata is None:
         die(
@@ -52,8 +74,11 @@ def cmd_resume(argv: list[str]) -> int:
         bottle_names=tuple(metadata.bottle_names),
     )
     backend_name = metadata.backend or None
-    return _launch_bottle(
+    _, rc = _launch_bottle(
         spec,
         dry_run=args.dry_run,
         backend_name=backend_name,
+        assume_yes=args.headless,
+        headless_prompt_text=args.prompt or "",
     )
+    return rc

bot_bottle/cli/start.py

@@ -31,12 +31,11 @@ from ..backend import (
 )
 from ..backend.docker import util as docker_mod
 from ..backend.docker.bottle_plan import DockerBottlePlan
-from ..bottle_state import (
+from ..bottle.state import (
     cleanup_state,
     is_preserved,
     mark_preserved,
 )
-from ..image_cache import StaleImageError
 from ..log import info, die
 from ..manifest import Manifest, ManifestIndex
 from ._common import PROG, USER_CWD, read_tty_line
@@ -64,14 +63,6 @@ def cmd_start(argv: list[str]) -> int:
             "skip all prompts. For orchestrators, CI, and webhooks."
         ),
     )
-    parser.add_argument(
-        "--cached-images",
-        action="store_true",
-        help=(
-            "quickstart with existing local agent and sidecar images; "
-            "only valid with --headless"
-        ),
-    )
     parser.add_argument(
         "--bottle",
         action="append",
@@ -104,8 +95,6 @@ def cmd_start(argv: list[str]) -> int:
         help="agent name defined in bot-bottle.json (omit to pick interactively)",
     )
     args = parser.parse_args(argv)
-    if args.cached_images and not args.headless:
-        die("--cached-images is only supported with --headless")
 
     dry_run = args.dry_run or os.environ.get("BOT_BOTTLE_DRY_RUN") == "1"
 
@@ -153,10 +142,6 @@ def cmd_start(argv: list[str]) -> int:
     label, color = tui.name_color_modal(default_label=agent_name)
     label, color = _resolve_unique_label(label, color)
 
-    image_policy = _select_image_policy()
-    if image_policy is None:
-        return 0
-
     spec = BottleSpec(
         manifest=manifest,
         agent_name=agent_name,
@@ -165,13 +150,13 @@ def cmd_start(argv: list[str]) -> int:
         label=label,
         color=color,
         bottle_names=bottle_names,
-        image_policy=image_policy,
     )
-    return _launch_bottle(
+    _, rc = _launch_bottle(
         spec,
         dry_run=dry_run,
         backend_name=backend_name,
     )
+    return rc
 
 
 # --- Headless launch -----------------------------------------------------
@@ -226,15 +211,15 @@ def _start_headless(
         color=args.color or "",
         bottle_names=bottle_names,
         headless=True,
-        image_policy="cached" if args.cached_images else "fresh",
     )
-    return _launch_bottle(
+    _, rc = _launch_bottle(
         spec,
         dry_run=dry_run,
         backend_name=backend_name,
         assume_yes=True,
         headless_prompt_text=prompt,
     )
+    return rc
 
 
 def _uniquify_label_headless(label: str) -> str:
@@ -407,13 +392,6 @@ def _text_prompt_yes() -> bool:
     return reply in ("y", "Y", "yes", "YES")
 
 
-def _select_image_policy() -> str | None:
-    return tui.filter_select(
-        ["fresh", "cached"],
-        title="Select image startup mode",
-    )
-
-
 def _text_render_preflight():
     def _render(plan: DockerBottlePlan, backend_name: str) -> None:
         print(file=sys.stderr)
@@ -530,11 +508,16 @@ def _launch_bottle(
     backend_name: str | None = None,
     assume_yes: bool = False,
     headless_prompt_text: str = "",
-) -> int:
+) -> tuple[str, int]:
     """Shared launch core for `start` and `resume`. Builds the plan,
     prints / dry-runs / prompts as appropriate, brings the bottle up,
     attaches claude, and prints the resume hint on session end.
 
+    Returns ``(slug, exit_code)`` where ``slug`` is the bottle identity
+    (empty string when the launch was aborted before a slug was minted)
+    and ``exit_code`` is the agent process's exit code (0 on clean exit
+    or when launch was aborted before the agent ran).
+
     `assume_yes` skips the interactive y/N confirmation (headless /
     orchestrator launches), where there is no human at the prompt.
 
@@ -543,6 +526,7 @@ def _launch_bottle(
     agent receives the initial task without interactive input."""
     stage_dir = Path(tempfile.mkdtemp(prefix="bot-bottle-stage."))
     identity = ""
+    exit_code = 0
     try:
         plan, identity = prepare_with_preflight(
             spec,
@@ -553,42 +537,34 @@ def _launch_bottle(
             backend_name=backend_name,
         )
         if plan is None:
-            return 0
+            return identity, 0
 
         backend = get_bottle_backend(backend_name)
-        skip_stale = False
+        with backend.launch(plan) as bottle:
-        while True:
+            agent_provider_template = getattr(plan, "agent_provider_template", "claude")
-            try:
+            extra_args: tuple[str, ...] = ()
-                with backend.launch(plan, skip_stale=skip_stale) as bottle:
+            if headless_prompt_text:
-                    agent_provider_template = getattr(plan, "agent_provider_template", "claude")
+                extra_args = tuple(
-                    extra_args: tuple[str, ...] = ()
+                    get_provider(agent_provider_template).headless_prompt(
-                    if headless_prompt_text:
+                        headless_prompt_text
-                        extra_args = tuple(
-                            get_provider(agent_provider_template).headless_prompt(
-                                headless_prompt_text
-                            )
-                        )
-                    exit_code = attach_agent(
-                        bottle,
-                        agent_provider_template=agent_provider_template,
-                        startup_args=plan.agent_provision.startup_args + extra_args,
                     )
-                    info(
+                )
-                        f"session ended (exit {exit_code}); "
+            exit_code = attach_agent(
-                        f"container {bottle.name} will be removed"
+                bottle,
-                    )
+                agent_provider_template=agent_provider_template,
-                    if agent_provider_template == "claude":
+                startup_args=plan.agent_provision.startup_args + extra_args,
-                        capture_claude_session_state(identity, exit_code)
+            )
-                break
+            info(
-            except StaleImageError as exc:
+                f"session ended (exit {exit_code}); "
-                if assume_yes:
+                f"container {bottle.name} will be removed"
-                    die(str(exc))
+            )
-                sys.stderr.write(f"bot-bottle: {exc}\nLaunch anyway? [y/N] ")
+            # While the container is still alive: always snapshot the
-                sys.stderr.flush()
+            # transcript and — if the agent exited non-zero — mark
-                if read_tty_line() not in ("y", "Y", "yes", "YES"):
+            # the state for preservation. This picks up crashes /
-                    break
+            # Ctrl-Cs / OOM kills before cleanup removes the state dir.
-                skip_stale = True
+            if agent_provider_template == "claude":
-        return 0
+                capture_claude_session_state(identity, exit_code)
+        return identity, exit_code
     finally:
         # PRD 0018 chunk 2: prepare now writes the bottle's bind-mount
         # sources under state/<slug>/. If we never reached the

bot_bottle/cli/supervise.py

@@ -20,7 +20,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from .. import supervise as _supervise
-from ..bottle_state import read_metadata
+from ..bottle.state import read_metadata
 from ..backend.docker.egress_apply import (
     EgressApplyError,
     applicator as _docker_applicator,

bot_bottle/config_store.py

@@ -1,71 +0,0 @@
-"""SQLite-backed bot-bottle configuration store."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-try:
-    from .db_store import DbStore
-    from .migrations import TableMigrations
-    from .supervise_types import host_db_path
-except ImportError:
-    from db_store import DbStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
-    from migrations import TableMigrations  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
-    from supervise_types import host_db_path  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
-
-
-DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS = 1
-
-
-class ConfigStore(DbStore):
-    """SQLite configuration for host-side bot-bottle settings."""
-
-    def __init__(self, db_path: Path | None = None) -> None:
-        migrations = TableMigrations("config_store", [
-            # v1 — host-side bot-bottle settings
-            """
-            CREATE TABLE IF NOT EXISTS bot_bottle_config (
-                id INTEGER PRIMARY KEY CHECK (id = 1),
-                cached_image_stale_warning_days INTEGER NOT NULL DEFAULT 1
-            )
-            """,
-        ])
-        super().__init__(db_path or host_db_path(), migrations)
-
-    def cached_image_stale_warning_days(self) -> int:
-        if not self.db_path.is_file():
-            return DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS
-        with self._connect() as conn:
-            row = conn.execute(
-                """
-                SELECT cached_image_stale_warning_days
-                FROM bot_bottle_config
-                WHERE id = 1
-                """,
-            ).fetchone()
-        if row is None:
-            return DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS
-        try:
-            return int(row["cached_image_stale_warning_days"])
-        except (TypeError, ValueError):
-            return DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS
-
-    def set_cached_image_stale_warning_days(self, days: int) -> Path:
-        with self._connect() as conn:
-            conn.execute(
-                """
-                INSERT INTO bot_bottle_config (id, cached_image_stale_warning_days)
-                VALUES (1, ?)
-                ON CONFLICT(id) DO UPDATE SET
-                    cached_image_stale_warning_days = excluded.cached_image_stale_warning_days
-                """,
-                (days,),
-            )
-        self._chmod()
-        return self.db_path
-
-
-__all__ = [
-    "DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS",
-    "ConfigStore",
-]

bot_bottle/contrib/forge/base.py

@@ -0,0 +1,165 @@
+"""Forge abstraction (PRD forge-native-integration, chunk 3).
+
+The `Forge` abstract class is the provider-agnostic surface a forge
+sidecar dispatches to: read issues/comments, post comments, edit
+descriptions, and the membership / PR lookups the orchestrator needs.
+Each forge (Gitea first) implements it; the sidecar protocol and the
+agent prompt stay forge-agnostic.
+
+`signal_done` is deliberately *not* a `Forge` method — completion is a
+sidecar concept relayed to the orchestrator over a queue dir, not a
+forge API operation.
+
+`ScopedForge` enforces the PRD's **read-anywhere / write-scoped** model:
+reads pass through to any issue/PR for context; writes are rejected
+unless the target is the assigned issue or one of its PRs. This bounds
+the blast radius of a prompt-injected agent below repo-wide API-key
+permissions.
+"""
+
+from __future__ import annotations
+
+import abc
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Issue:
+    """A forge issue (not a PR — see `PullRequest`)."""
+
+    number: int
+    title: str
+    body: str
+    state: str  # "open" | "closed"
+
+
+@dataclass(frozen=True)
+class PullRequest:
+    """A forge pull request. Kept distinct from `Issue` even though some
+    forges model PRs as issues on the wire: the domain objects carry
+    different data (a PR has merge state) and are read through different
+    methods (`read_pr` vs `read_issue`)."""
+
+    number: int
+    title: str
+    body: str
+    state: str  # "open" | "closed"
+    merged: bool
+
+
+@dataclass(frozen=True)
+class Comment:
+    id: int
+    user: str  # login of the comment author
+    body: str
+
+
+class ForgeScopeError(PermissionError):
+    """Raised by `ScopedForge` when a write targets an issue/PR outside
+    the assigned scope."""
+
+
+class Forge(abc.ABC):
+    """Provider-agnostic forge operations. Implementations wrap a
+    per-provider HTTP client and translate to `Issue` / `Comment`."""
+
+    @abc.abstractmethod
+    def read_issue(self, number: int) -> Issue:
+        """Read an issue body (read-anywhere)."""
+
+    @abc.abstractmethod
+    def read_pr(self, number: int) -> PullRequest:
+        """Read a pull request, including its merge state (read-anywhere)."""
+
+    @abc.abstractmethod
+    def read_comments(self, number: int) -> list[Comment]:
+        """Read a thread's comments (read-anywhere)."""
+
+    @abc.abstractmethod
+    def post_comment(self, number: int, body: str) -> None:
+        """Post a comment to an issue or PR (write-scoped)."""
+
+    @abc.abstractmethod
+    def update_description(self, number: int, body: str) -> None:
+        """Replace an issue or PR body (write-scoped)."""
+
+    @abc.abstractmethod
+    def is_org_member(self, org: str, username: str) -> bool:
+        """Whether `username` is a member of `org`."""
+
+    @abc.abstractmethod
+    def get_pr_for_issue(self, number: int) -> int | None:
+        """The PR number linked to an issue, or None when there is none."""
+
+    @abc.abstractmethod
+    def is_pr_open(self, number: int) -> bool:
+        """Whether the given PR is still open."""
+
+
+class ScopedForge(Forge):
+    """Read-anywhere / write-scoped wrapper around a concrete `Forge`.
+
+    `post_comment` and `update_description` are rejected with
+    `ForgeScopeError` unless the target number is the assigned issue or
+    one of the assigned PRs. Every other method delegates unchanged, so
+    reads, membership checks, and PR lookups work against any number for
+    context.
+
+    The writable set is fixed at construction. The sidecar reconstructs
+    a `ScopedForge` when a PR is discovered (`get_pr_for_issue`) so the
+    new PR becomes writable; this class does not mutate its own scope.
+    """
+
+    def __init__(
+        self,
+        inner: Forge,
+        *,
+        assigned_issue: int,
+        assigned_prs: Iterable[int] = (),
+    ) -> None:
+        self._inner = inner
+        self._assigned_issue = assigned_issue
+        self._writable = {assigned_issue, *assigned_prs}
+
+    @property
+    def writable(self) -> frozenset[int]:
+        return frozenset(self._writable)
+
+    def _check_write(self, number: int) -> None:
+        if number not in self._writable:
+            allowed = ", ".join(str(n) for n in sorted(self._writable))
+            raise ForgeScopeError(
+                f"write to #{number} denied: out of assigned scope "
+                f"(writable: {allowed})"
+            )
+
+    # --- read-anywhere: pass through --------------------------------------
+
+    def read_issue(self, number: int) -> Issue:
+        return self._inner.read_issue(number)
+
+    def read_pr(self, number: int) -> PullRequest:
+        return self._inner.read_pr(number)
+
+    def read_comments(self, number: int) -> list[Comment]:
+        return self._inner.read_comments(number)
+
+    def is_org_member(self, org: str, username: str) -> bool:
+        return self._inner.is_org_member(org, username)
+
+    def get_pr_for_issue(self, number: int) -> int | None:
+        return self._inner.get_pr_for_issue(number)
+
+    def is_pr_open(self, number: int) -> bool:
+        return self._inner.is_pr_open(number)
+
+    # --- write-scoped: check then delegate --------------------------------
+
+    def post_comment(self, number: int, body: str) -> None:
+        self._check_write(number)
+        self._inner.post_comment(number, body)
+
+    def update_description(self, number: int, body: str) -> None:
+        self._check_write(number)
+        self._inner.update_description(number, body)

bot_bottle/contrib/gitea/client.py

@@ -0,0 +1,174 @@
+"""Gitea HTTP client + `GiteaForge` (PRD forge-native-integration, chunk 3).
+
+`GiteaClient` is the thin stdlib-only HTTP transport (mirrors
+`deploy_key_provisioner.py`: `urllib.request`, bounded timeouts,
+structured error bodies). `GiteaForge` adapts it to the provider-agnostic
+`Forge` surface.
+
+Unlike the option-2 design, the token is held here (the sidecar process
+owns it) and passed to the client directly — there is no agent-side
+cred-proxy route, because the agent never makes forge calls. The HTTP
+client is the one piece shared with `GiteaDeployKeyProvisioner`; the two
+are deliberately *not* unified behind a common abstract base (see the
+deferral note in the PRD).
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+from ..forge.base import Comment, Forge, Issue, PullRequest
+
+# Bound every Gitea call: a hung instance must not stall the sidecar.
+_API_TIMEOUT_SECS = 30
+
+
+class GiteaClient:
+    """Thin authenticated HTTP client for one repo's Gitea API.
+
+    `api_url` is the API base *including* `/api/v1` (matching the
+    `FORGE_GITEA_API` env var), e.g. `https://gitea.example.com/api/v1`.
+    """
+
+    def __init__(self, *, api_url: str, owner: str, repo: str, token: str) -> None:
+        self._api_url = api_url.rstrip("/")
+        self._owner = owner
+        self._repo = repo
+        self._token = token
+
+    # --- low-level request -------------------------------------------------
+
+    def _request(
+        self, method: str, path: str, *, body: dict[str, Any] | None = None
+    ) -> tuple[int, Any]:
+        """Issue an authenticated request. Returns `(status, parsed_json)`;
+        parsed_json is None when the response has no body. Raises
+        `RuntimeError` on any non-2xx except where callers special-case
+        the HTTPError themselves (membership 404)."""
+        url = f"{self._api_url}{path}"
+        data = json.dumps(body).encode() if body is not None else None
+        headers = {"Authorization": f"token {self._token}"}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        with urllib.request.urlopen(req, timeout=_API_TIMEOUT_SECS) as resp:
+            raw = resp.read()
+            parsed = json.loads(raw) if raw else None
+            return resp.status, parsed
+
+    def _repo_path(self, suffix: str) -> str:
+        return f"/repos/{self._owner}/{self._repo}{suffix}"
+
+    # --- operations --------------------------------------------------------
+
+    def is_org_member(self, org: str, username: str) -> bool:
+        """GET /orgs/{org}/members/{username}: 2xx → member, 404 → not.
+        Other errors propagate so a misconfigured token fails loudly."""
+        url = f"{self._api_url}/orgs/{org}/members/{username}"
+        req = urllib.request.Request(
+            url, headers={"Authorization": f"token {self._token}"}, method="GET"
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=_API_TIMEOUT_SECS):
+                return True
+        except urllib.error.HTTPError as exc:
+            if exc.code == 404:
+                return False
+            raise RuntimeError(
+                f"org membership check failed for {org}/{username}: "
+                f"HTTP {exc.code} — {_read_error_body(exc)}"
+            ) from exc
+
+    def get_issue(self, number: int) -> dict[str, Any]:
+        _status, body = self._request("GET", self._repo_path(f"/issues/{number}"))
+        return body or {}
+
+    def get_comments(self, number: int) -> list[dict[str, Any]]:
+        _status, body = self._request(
+            "GET", self._repo_path(f"/issues/{number}/comments")
+        )
+        return body or []
+
+    def post_comment(self, number: int, body: str) -> None:
+        self._request(
+            "POST",
+            self._repo_path(f"/issues/{number}/comments"),
+            body={"body": body},
+        )
+
+    def patch_issue_body(self, number: int, body: str) -> None:
+        self._request(
+            "PATCH", self._repo_path(f"/issues/{number}"), body={"body": body}
+        )
+
+    def get_pull(self, number: int) -> dict[str, Any]:
+        _status, body = self._request("GET", self._repo_path(f"/pulls/{number}"))
+        return body or {}
+
+
+class GiteaForge(Forge):
+    """`Forge` over a `GiteaClient`."""
+
+    def __init__(self, client: GiteaClient) -> None:
+        self._client = client
+
+    def read_issue(self, number: int) -> Issue:
+        raw = self._client.get_issue(number)
+        return Issue(
+            number=int(raw.get("number", number)),
+            title=str(raw.get("title", "")),
+            body=str(raw.get("body", "") or ""),
+            state=str(raw.get("state", "")),
+        )
+
+    def read_pr(self, number: int) -> PullRequest:
+        raw = self._client.get_pull(number)
+        return PullRequest(
+            number=int(raw.get("number", number)),
+            title=str(raw.get("title", "")),
+            body=str(raw.get("body", "") or ""),
+            state=str(raw.get("state", "")),
+            merged=bool(raw.get("merged", False)),
+        )
+
+    def read_comments(self, number: int) -> list[Comment]:
+        return [
+            Comment(
+                id=int(c.get("id", 0)),
+                user=str((c.get("user") or {}).get("login", "")),
+                body=str(c.get("body", "") or ""),
+            )
+            for c in self._client.get_comments(number)
+        ]
+
+    def post_comment(self, number: int, body: str) -> None:
+        self._client.post_comment(number, body)
+
+    def update_description(self, number: int, body: str) -> None:
+        self._client.patch_issue_body(number, body)
+
+    def is_org_member(self, org: str, username: str) -> bool:
+        return self._client.is_org_member(org, username)
+
+    def get_pr_for_issue(self, number: int) -> int | None:
+        """Gitea models a PR as an issue with the same number, exposing a
+        `pull_request` object on the issue. When the queried number is
+        itself a PR, return it; otherwise None. (The orchestrator tracks
+        the issue→PR mapping in forge state for the cross-number case.)"""
+        raw = self._client.get_issue(number)
+        if raw.get("pull_request"):
+            return int(raw.get("number", number))
+        return None
+
+    def is_pr_open(self, number: int) -> bool:
+        return self.read_pr(number).state == "open"
+
+
+def _read_error_body(exc: urllib.error.HTTPError) -> str:
+    try:
+        return exc.read().decode("utf-8", errors="replace")
+    except Exception:  # pylint: disable=broad-exception-caught
+        return ""

bot_bottle/contrib/gitea/forge_state.py

@@ -0,0 +1,171 @@
+"""Forge state persistence (PRD forge-native-integration, chunk 2).
+
+The orchestrator tracks one record per forge-targeted issue so it can
+map an incoming webhook back to the bottle handling it, drive the
+freeze / rehydrate loop, and run the watchdog.
+
+State is stored in a local SQLite database in `~/.bot-bottle/`. Access
+goes through the thin `ForgeStateStore` CRUD interface so the backing
+store (location or engine) can be swapped without touching callers;
+`SqliteForgeStateStore` is the first implementation.
+"""
+
+from __future__ import annotations
+
+import abc
+import json
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ...supervise import bot_bottle_root
+
+_DB_FILENAME = "bot-bottle.db"
+
+# Lifecycle: a bottle is launched (running), frozen on the done signal,
+# and destroyed when the PR closes.
+STATUS_RUNNING = "running"
+STATUS_FROZEN = "frozen"
+STATUS_DESTROYED = "destroyed"
+
+
+@dataclass
+class ForgeState:
+    """One forge-targeted issue's bottle lifecycle record."""
+
+    owner: str
+    repo: str
+    issue_number: int
+    slug: str
+    agent_name: str
+    bottle_names: list[str] = field(default_factory=list)
+    backend_name: str = ""
+    agent_git_user: str = ""
+    pr_number: int | None = None
+    status: str = STATUS_RUNNING
+    last_checkin_at: str = ""
+
+
+class ForgeStateStore(abc.ABC):
+    """Thin CRUD surface over forge state. Implementations back it with a
+    concrete store; callers depend only on this interface so the storage
+    location/engine is swappable."""
+
+    @abc.abstractmethod
+    def upsert(self, state: ForgeState) -> None:
+        """Insert or replace the record keyed by (owner, repo, issue)."""
+
+    @abc.abstractmethod
+    def get(self, owner: str, repo: str, issue_number: int) -> ForgeState | None:
+        """Fetch one record, or None when absent."""
+
+    @abc.abstractmethod
+    def delete(self, owner: str, repo: str, issue_number: int) -> None:
+        """Remove a record. Missing is success (idempotent)."""
+
+    @abc.abstractmethod
+    def all(self) -> list[ForgeState]:
+        """Every record, for the status table and the watchdog sweep."""
+
+
+def default_db_path() -> Path:
+    return bot_bottle_root() / _DB_FILENAME
+
+
+class SqliteForgeStateStore(ForgeStateStore):
+    """SQLite-backed `ForgeStateStore`. The database lives at
+    `~/.bot-bottle/bot-bottle.db` by default; pass `db_path` to point at
+    a different location (tests, alternate homes)."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        self._db_path = db_path or default_db_path()
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        with self._connect() as conn:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS forge_state (
+                    owner           TEXT    NOT NULL,
+                    repo            TEXT    NOT NULL,
+                    issue_number    INTEGER NOT NULL,
+                    slug            TEXT    NOT NULL,
+                    agent_name      TEXT    NOT NULL,
+                    bottle_names    TEXT    NOT NULL,
+                    backend_name    TEXT    NOT NULL,
+                    agent_git_user  TEXT    NOT NULL,
+                    pr_number       INTEGER,
+                    status          TEXT    NOT NULL,
+                    last_checkin_at TEXT    NOT NULL,
+                    PRIMARY KEY (owner, repo, issue_number)
+                )
+                """
+            )
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._db_path)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def upsert(self, state: ForgeState) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO forge_state (
+                    owner, repo, issue_number, slug, agent_name,
+                    bottle_names, backend_name, agent_git_user,
+                    pr_number, status, last_checkin_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    state.owner,
+                    state.repo,
+                    state.issue_number,
+                    state.slug,
+                    state.agent_name,
+                    json.dumps(state.bottle_names),
+                    state.backend_name,
+                    state.agent_git_user,
+                    state.pr_number,
+                    state.status,
+                    state.last_checkin_at,
+                ),
+            )
+
+    def get(self, owner: str, repo: str, issue_number: int) -> ForgeState | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT * FROM forge_state "
+                "WHERE owner = ? AND repo = ? AND issue_number = ?",
+                (owner, repo, issue_number),
+            ).fetchone()
+        return _row_to_state(row) if row is not None else None
+
+    def delete(self, owner: str, repo: str, issue_number: int) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                "DELETE FROM forge_state "
+                "WHERE owner = ? AND repo = ? AND issue_number = ?",
+                (owner, repo, issue_number),
+            )
+
+    def all(self) -> list[ForgeState]:
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT * FROM forge_state ORDER BY owner, repo, issue_number"
+            ).fetchall()
+        return [_row_to_state(row) for row in rows]
+
+
+def _row_to_state(row: sqlite3.Row) -> ForgeState:
+    return ForgeState(
+        owner=row["owner"],
+        repo=row["repo"],
+        issue_number=row["issue_number"],
+        slug=row["slug"],
+        agent_name=row["agent_name"],
+        bottle_names=json.loads(row["bottle_names"]),
+        backend_name=row["backend_name"],
+        agent_git_user=row["agent_git_user"],
+        pr_number=row["pr_number"],
+        status=row["status"],
+        last_checkin_at=row["last_checkin_at"],
+    )

bot_bottle/image_cache.py

@@ -1,42 +0,0 @@
-"""Shared helpers for cached-image quickstart stale checks."""
-
-from __future__ import annotations
-
-from datetime import datetime, timezone
-from pathlib import Path
-
-try:
-    from .config_store import ConfigStore
-except ImportError:
-    from config_store import ConfigStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
-
-
-class StaleImageError(Exception):
-    """Raised when a cached image or artifact exceeds the configured staleness
-    threshold. Callers can catch this to prompt interactively; headless paths
-    let it propagate as a fatal error."""
-
-
-def check_stale(label: str, created_at: datetime) -> None:
-    """Raise StaleImageError if `created_at` is older than the configured
-    stale-warning threshold. Negative threshold disables the check."""
-    threshold_days = ConfigStore().cached_image_stale_warning_days()
-    if threshold_days < 0:
-        return
-    now = datetime.now(timezone.utc)
-    created = created_at.astimezone(timezone.utc)
-    age = now - created
-    if age.total_seconds() <= threshold_days * 86400:
-        return
-    raise StaleImageError(
-        f"cached {label} is {age.days} day(s) old; "
-        "quickstart does not verify it matches the current Dockerfile/context"
-    )
-
-
-def check_stale_path(label: str, path: Path) -> None:
-    """Raise StaleImageError if `path`'s mtime exceeds the staleness threshold."""
-    check_stale(label, datetime.fromtimestamp(path.stat().st_mtime, tz=timezone.utc))
-
-
-__all__ = ["StaleImageError", "check_stale", "check_stale_path"]

bot_bottle/sidecar_init.py

@@ -167,8 +167,8 @@ class _Supervisor:
 
     def start_all(self) -> None:
         for spec in self.specs:
-            _log(f"starting {spec.name}")
             self.procs.append((spec, _spawn(spec)))
+            _log(f"starting {spec.name}")
 
     def request_shutdown(self, reason: str) -> None:
         if self.shutdown_at is not None:
@@ -353,8 +353,6 @@ def main(argv: Sequence[str] | None = None) -> int:
         return 0
 
     sup = _Supervisor(specs)
-    sup.start_all()
-
     signal.signal(signal.SIGTERM, lambda *_: sup.request_shutdown("SIGTERM"))  # type: ignore
     signal.signal(signal.SIGINT, lambda *_: sup.request_shutdown("SIGINT"))  # type: ignore
     # SIGHUP reload path: egress_apply.py runs `docker kill
@@ -362,6 +360,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     # delivers SIGHUP to PID 1 (this supervisor); forward it to
     # mitmdump so it reloads its addon.
     signal.signal(signal.SIGHUP, lambda *_: sup.forward_signal(signal.SIGHUP, "egress"))  # type: ignore
+    sup.start_all()
 
     while not sup.tick():
         time.sleep(_POLL_INTERVAL)

bot_bottle/store_manager.py

@@ -6,11 +6,9 @@ from pathlib import Path
 
 try:
     from .audit_store import AuditStore
-    from .config_store import ConfigStore
     from .queue_store import QueueStore
 except ImportError:
     from audit_store import AuditStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
-    from config_store import ConfigStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
     from queue_store import QueueStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
 
 _instance: StoreManager | None = None
@@ -52,13 +50,11 @@ class StoreManager:
         return (
             QueueStore("", self.db_path).is_migrated()
             and AuditStore(self.db_path).is_migrated()
-            and ConfigStore(self.db_path).is_migrated()
         )
 
     def migrate(self) -> None:
         QueueStore("", self.db_path).migrate()
         AuditStore(self.db_path).migrate()
-        ConfigStore(self.db_path).migrate()
 
 
 __all__ = ["StoreManager"]

docs/prds/prd-new-forge-native-integration.md

@@ -0,0 +1,439 @@
+# PRD prd-new: Forge native integration
+
+- **Status:** Draft
+- **Author:** claude
+- **Created:** 2026-06-29
+- **Issue:** #317
+
+## Summary
+
+Add a webhook-driven orchestration layer that lets Gitea issues and PR comments
+drive bot-bottle sessions end-to-end with no operator in the loop for the happy
+path. An issue assigned to a member of the configured agent org and labelled
+with an agent name triggers a headless bottle launch; the bottle processes the
+issue, opens a PR, and interacts with the forge through a **forge sidecar** —
+the agent never touches the Gitea API or its credentials directly. The agent
+calls `signal_done(status, summary)` on the sidecar when a work unit is
+complete; the sidecar relays that to the orchestrator over a queue dir (the same
+pattern as the supervise sidecar), so completion is an unambiguous in-band
+signal rather than a comment the orchestrator has to parse. The orchestrator
+freezes the bottle. Subsequent PR comments rehydrate the frozen bottle. The
+bottle is destroyed when the PR closes.
+
+The forge sidecar is backed by a `Forge` abstract class with per-provider
+implementations (Gitea first), so the agent's prompts and the sidecar protocol
+stay forge-agnostic. The sidecar logs forge operations semantically ("read PR
+description", "posted comment", "signalled done"), giving richer provenance than
+post-hoc egress-byte parsing, and enforces a **read-anywhere / write-scoped**
+permission model: the agent may read for context but may only write to the
+issue and PRs it was assigned.
+
+Run provenance is exposed through a **provenance API** (the sidecar's structured
+operation log plus the run's metadata), not posted back into the forge. We do
+not surface a provenance footer in the PR — the audit record lives behind the
+API where it can be retained and queried, rather than as an editable comment.
+
+The separation of concerns across the two layers: bot-bottle owns the headless
+launch primitives, the forge sidecar + `Forge` abstraction, and forge state.
+`bot-bottle-orchestrator` (separate binary) owns the webhook listener, bottle
+lifecycle loop, and monitoring dashboard; it calls into bot-bottle via
+`./cli.py orchestrate`, a thin wrapper command. This PRD covers bot-bottle's
+side of that contract.
+
+## Problem
+
+Today an operator must open the TUI, select an agent and bottle, confirm the
+preflight, and type prompts interactively. This blocks "issue → PR" automation
+and produces no durable audit record of what the agent did. The security model
+already provides the right isolation and egress controls, and `start --headless`
+(#315) already gives `bot-bottle-orchestrator` a non-interactive launch path.
+The missing pieces are a headless `resume` counterpart for rehydrating frozen
+bottles, a forge-interaction surface the agent uses to read context, post
+comments, and signal completion, and the provenance trail that makes the audit
+story legible to reviewers on every PR.
+
+That forge-interaction surface could be built two ways: (2) give the agent the
+Gitea API directly with cred-proxy injecting the token, or (3) put a forge
+sidecar between the agent and the forge. This PRD takes **option 3**. The
+deciding factors: a sidecar `signal_done` call is an unambiguous completion
+signal where comment-parsing is a correctness risk that surfaces in production;
+the sidecar produces a semantic audit trail rather than HTTP bytes, which is
+load-bearing for provenance (the stated product priority); and the sidecar can
+enforce scope tighter than repo-wide API-key permissions, reducing blast radius
+for a prompt-injected agent. The costs — a second sidecar process per forge run,
+a new failure mode if it crashes, and per-forge implementation cost — are
+accepted as the price of those properties.
+
+## Goals / Success Criteria
+
+1. Headless launch already exists: `./cli.py start <agent> --headless --prompt`
+   (#315) runs non-interactively with no TUI selectors or y/N preflight. This
+   PRD builds on it rather than re-introducing it. The remaining gap is a
+   matching headless `resume` path (`./cli.py resume --headless`), since
+   rehydrating a frozen bottle for a new prompt is required by the freeze /
+   rehydrate loop and `resume` has no non-interactive entry point today.
+2. An issue assigned to a member of the configured org (`FORGE_ORG`, default
+   `bot-bottle`) and labelled `bot-bottle:<agent-name>` is the trigger
+   convention. Org membership is verified via the Gitea API at event time.
+3. Forge-targeted bottles run a **forge sidecar** that exposes a small,
+   forge-agnostic API (comment/issue/PR CRUD plus `signal_done`) over the same
+   queue-dir + HTTP/JSON-RPC machinery as the supervise sidecar. The agent calls
+   the sidecar; it never sees the forge token or forge-specific endpoints.
+4. The sidecar is backed by a `Forge` abstract class. Gitea is the first
+   concrete implementation; adding a forge means a new subclass, not changes to
+   the agent prompt or sidecar protocol. The sidecar enforces a read-anywhere /
+   write-scoped model: writes are limited to the assigned issue and its PRs;
+   reads are unrestricted for context.
+5. The agent calls `signal_done(status, summary)` on the sidecar when a work
+   unit is complete; the sidecar relays it to the orchestrator over a queue dir.
+   This is the done signal — no comment parsing. A watchdog timeout
+   (configurable, default 30 min) causes the orchestrator to treat the run as
+   done-without-self-report if the agent exits without signalling.
+6. Run provenance (agent name, bottle name(s), slug, timing, exit code,
+   gitleaks result, egress summary, and the sidecar's semantic operation log)
+   is available through a provenance API. It is **not** surfaced as a PR footer
+   or any other forge comment.
+7. Forge state (issue → slug, status) is persisted in a local SQLite database
+   under `~/.bot-bottle/` and survives orchestrator restarts.
+8. `./cli.py orchestrate status` lists active forge-managed bottles and their
+   issue/PR URLs.
+9. Unit tests cover: label parsing, org-membership check path, forge state
+   store CRUD (SQLite), headless launch arg construction, forge env var
+   injection, sidecar request dispatch through the `Forge` abstraction,
+   write-scope enforcement (reject writes outside the assigned issue/PRs), and
+   `signal_done` queue relay.
+
+## Non-goals
+
+- Webhook signature verification (HMAC-SHA256). Added as a follow-up.
+- The `bot-bottle-orchestrator` binary itself — this PRD covers bot-bottle's
+  side of the interface only. The orchestrator is a separate project.
+- GitHub or GitLab support.
+- Multiple simultaneous forge bottles per issue.
+- Automatic retry on agent error exit.
+- Bottle destruction on issue close (PR close only; issue close is ambiguous).
+- Concurrent multi-issue handling (one blocking run per orchestrator process).
+- A monitoring dashboard (orchestrator-side concern).
+- Folding `DeployKeyProvisioner` into the `Forge` abstraction. Deploy-key
+  provisioning runs at bottle-provision time on the host; the forge sidecar runs
+  inside the bottle at agent time. The two have different lifecycles and actors,
+  so coupling them into one class is deferred to a follow-up. This PRD only
+  shares the Gitea HTTP client between them.
+
+## Design
+
+### Targeting convention
+
+An issue is forge-targeted when **both** hold:
+
+- At least one assignee is a member of the Gitea org named by `FORGE_ORG`
+  (default `bot-bottle`). Checked via `GET /api/v1/orgs/{org}/members/{user}`.
+- At least one label has the prefix `bot-bottle:`. The suffix names the agent
+  manifest, e.g. `bot-bottle:implementer` → agent `implementer`.
+
+`FORGE_ORG` is read at orchestrate-command startup. It is not embedded in
+manifests or state files; the orchestrator stamps its value into log output for
+auditability.
+
+An optional label `bot-bottle-bottle:<name>` overrides bottle selection. When
+absent the agent's default bottle is used.
+
+### `./cli.py orchestrate` — the thin wrapper
+
+```
+./cli.py orchestrate start  --agent AGENT [--bottle BOTTLE ...] --prompt PROMPT
+                            [--label LABEL] [--backend BACKEND]
+./cli.py orchestrate resume --slug SLUG --prompt PROMPT [--backend BACKEND]
+./cli.py orchestrate status
+```
+
+`orchestrate start` is a thin shim over the already-shipped `start --headless`
+(#315): it forwards agent / bottle / label / prompt and adds the forge-specific
+wiring (`forge_env`, sidecar launch). It does not re-implement headless launch.
+The caller (`bot-bottle-orchestrator`) manages freeze, state, and the forge
+sidecar's done signal around it.
+
+`orchestrate resume` is the shim over the new `resume --headless` (below).
+
+`orchestrate status` prints the forge state table.
+
+### Headless primitives — what exists vs. what's new
+
+Headless **start** already shipped in #315 and this PRD reuses it as-is:
+
+- `./cli.py start <agent> --headless --prompt TEXT` — no TUI selectors, no y/N
+  preflight. Internally `_start_headless()` calls the shared `_launch_bottle()`
+  with `assume_yes=True` and `headless_prompt_text=prompt`.
+- The prompt is delivered through `AgentProvider.headless_prompt(prompt)` —
+  claude `-p`, codex positional, pi `-p`. The orchestrator does **not** hand-roll
+  agent args; it relies on this provider abstraction. (An earlier draft proposed
+  `start_headless` / `attach_agent_headless` helpers that constructed
+  `--no-interactive`/`-p` directly — those are dropped as redundant with, and
+  divergent from, what #315 merged.)
+
+Two additions are needed on top of #315:
+
+**1. A `forge_env` hook on the headless launch path.** The orchestrator needs to
+pass forge context + token through to the forge sidecar launched alongside the
+agent. This is a parameter threaded into `_launch_bottle` (the same core
+`start --headless` already uses), not a parallel launch function. The agent
+process itself does not receive the token.
+
+**2. `resume --headless`** — new in `bot_bottle/cli/resume.py`, mirroring the
+`--headless` flag on `start`:
+
+```
+./cli.py resume <slug> --headless --prompt TEXT
+```
+
+It rehydrates a frozen bottle and runs one headless prompt via the same
+`assume_yes` + `headless_prompt` path, returning the agent's exit code. `resume`
+has no non-interactive entry point today, so this is genuinely new work rather
+than a rename of an existing helper.
+
+### Forge sidecar
+
+Forge-targeted bottles run a forge sidecar alongside the agent, mirroring the
+supervise sidecar: a per-bottle process that exposes an HTTP/JSON-RPC endpoint
+over a Unix socket and relays events to the orchestrator through a queue dir.
+The agent calls the sidecar; the sidecar holds the forge token and makes the
+actual forge API calls. The agent never receives the credential and never sees a
+forge-specific endpoint — swapping Gitea for another forge does not change the
+agent prompt or the sidecar protocol.
+
+The sidecar is configured at launch from the forge context (owner, repo, issue,
+PR) and the token, supplied by the orchestrator — not baked into the agent
+manifest. Because the sidecar owns the token, forge traffic does not need a
+cred-proxy egress route on the agent; the agent's egress policy is unchanged by
+forge targeting.
+
+**Sidecar protocol** (forge-agnostic; each method maps to a `Forge` call):
+
+| Method | Scope | Purpose |
+|---|---|---|
+| `read_issue(number)` | read-anywhere | Read an issue body for context |
+| `read_pr(number)` | read-anywhere | Read a PR (incl. merge state) for context |
+| `read_comments(number)` | read-anywhere | Read a thread for context |
+| `post_comment(number, body)` | write-scoped | Post to the assigned issue/PR |
+| `update_description(number, body)` | write-scoped | Edit the assigned issue/PR body |
+| `signal_done(status, summary)` | — | Relay completion to the orchestrator |
+
+Issues and PRs are distinct domain objects (`Issue` vs `PullRequest`) read
+through distinct methods; a PR carries merge state an issue does not.
+
+**Scope enforcement** is read-anywhere / write-scoped: read methods accept any
+issue/PR number for context; write methods are rejected unless the target is the
+assigned issue or one of its PRs. This is tighter than Gitea's repo-wide API-key
+permissions and bounds the blast radius of a prompt-injected agent. Rejections
+are logged semantically (operation, target, reason) so the audit trail records
+attempted out-of-scope writes, not just allowed ones.
+
+**Semantic audit**: every sidecar call is logged as a structured operation
+("read PR #318 description", "posted comment to #317", "signalled done:
+success") rather than as opaque HTTP bytes. This log feeds provenance directly,
+with no post-hoc egress-log parsing.
+
+### `Forge` abstraction — `bot_bottle/contrib/forge/`
+
+The sidecar dispatches to a `Forge` abstract class. Each provider implements the
+operations behind the sidecar protocol:
+
+```python
+class Forge(abc.ABC):
+    @abc.abstractmethod
+    def read_issue(self, number: int) -> Issue: ...
+    @abc.abstractmethod
+    def read_pr(self, number: int) -> PullRequest: ...
+    @abc.abstractmethod
+    def read_comments(self, number: int) -> list[Comment]: ...
+    @abc.abstractmethod
+    def post_comment(self, number: int, body: str) -> None: ...
+    @abc.abstractmethod
+    def update_description(self, number: int, body: str) -> None: ...
+    @abc.abstractmethod
+    def is_org_member(self, org: str, username: str) -> bool: ...
+    @abc.abstractmethod
+    def get_pr_for_issue(self, number: int) -> int | None: ...
+    @abc.abstractmethod
+    def is_pr_open(self, number: int) -> bool: ...
+```
+
+`Issue` and `PullRequest` are separate frozen dataclasses — a PR adds `merged`.
+`ScopedForge` wraps a concrete `Forge` to enforce the read-anywhere /
+write-scoped model (`post_comment` / `update_description` raise `ForgeScopeError`
+outside the assigned issue and PRs).
+
+`GiteaForge` is the first and only concrete implementation in this PRD. It wraps
+the Gitea HTTP client (below). Adding GitHub or GitLab later is a new subclass;
+the sidecar, protocol, and agent prompt are untouched.
+
+> **Deferred:** `DeployKeyProvisioner` is *not* folded into `Forge` here.
+> Deploy-key provisioning runs on the host at provision time; the sidecar runs
+> in the bottle at agent time. They have different lifecycles and actors, so a
+> shared abstract base would couple two unrelated auth contexts. For now they
+> only share the Gitea HTTP client; a later PRD can revisit unification.
+
+### Forge env vars
+
+The orchestrator passes forge context to the **sidecar** (not the agent) at
+launch. The agent does not need owner/repo/issue env vars to construct API
+calls, since it only names issue/PR numbers to the sidecar:
+
+| Var | Example | Purpose |
+|---|---|---|
+| `FORGE_GITEA_API` | `https://gitea.dideric.is/api/v1` | Base URL the sidecar calls |
+| `FORGE_OWNER` | `didericis` | Repo owner |
+| `FORGE_REPO` | `bot-bottle` | Repo name |
+| `FORGE_ISSUE_NUMBER` | `317` | Assigned issue (defines write scope) |
+| `FORGE_PR_NUMBER` | `318` | Assigned PR (empty until PR exists) |
+
+The agent's forge-specific prompt instructs it to call `signal_done` on the
+sidecar when a work unit is complete, and to use the sidecar for any
+comment/description writes. The instruction is forge-agnostic and is part of the
+forge prompt overlay, not the base agent manifest, so non-forge runs are
+unaffected.
+
+### Done signal and watchdog
+
+The agent calls `signal_done(status, summary)` on the sidecar when it finishes a
+work unit. The sidecar writes the event to its queue dir; the orchestrator reads
+it and:
+
+1. Reads the forge state for `(owner, repo, issue_number)`.
+2. If `status == "running"`, treats the event as the done signal: freezes the
+   bottle and sets `status = "frozen"`. Provenance is recorded via the
+   provenance API — no comment is posted to the forge.
+
+Because completion is an explicit `signal_done` call, the orchestrator does not
+parse comment text to detect "done", and intermediate comments the agent posts
+mid-run cannot be mistaken for completion.
+
+**Watchdog**: the orchestrator tracks `last_checkin_at` in forge state, updated
+on each sidecar event. A background thread wakes every minute. If
+`now - last_checkin_at > FORGE_WATCHDOG_TIMEOUT` (default 30 min, configurable
+via env) and `status == "running"`, the orchestrator treats the run as
+done-without-self-report and freezes the bottle, flagging the run as incomplete
+in the provenance record.
+
+**Sidecar-death failure mode**: if the forge sidecar crashes mid-run the agent
+loses forge access while the bottle is otherwise healthy. The orchestrator
+detects a dead sidecar (socket/queue gone) the same way it detects a stalled
+agent and falls back to the watchdog path.
+
+### Forge state — `bot_bottle/contrib/gitea/forge_state.py`
+
+State is stored in a local SQLite database at `~/.bot-bottle/bot-bottle.db`.
+Access goes through a thin CRUD interface, `ForgeStateStore`, so the storage
+location/engine can be swapped without touching callers. `SqliteForgeStateStore`
+is the first implementation.
+
+The `forge_state` table is keyed by `(owner, repo, issue_number)` and carries:
+`slug`, `agent_name`, `bottle_names` (JSON), `backend_name`, `agent_git_user`,
+`pr_number` (nullable), `status`, `last_checkin_at`.
+
+`status`: `"running"` | `"frozen"` | `"destroyed"`.
+
+Store interface:
+
+```python
+class ForgeStateStore(abc.ABC):
+    def upsert(self, state: ForgeState) -> None: ...
+    def get(self, owner: str, repo: str, issue_number: int) -> ForgeState | None: ...
+    def delete(self, owner: str, repo: str, issue_number: int) -> None: ...
+    def all(self) -> list[ForgeState]: ...
+
+class SqliteForgeStateStore(ForgeStateStore):
+    def __init__(self, db_path: Path | None = None) -> None: ...
+```
+
+`upsert` uses `INSERT OR REPLACE` so a re-run for the same issue overwrites in
+place. The schema is created on first open.
+
+### Provenance API
+
+Run provenance — agent, bottle(s), slug, timing, exit code, gitleaks result,
+egress summary, watchdog-fired flag, and the sidecar's semantic operation log —
+is exposed through a **provenance API**, not posted into the forge. There is no
+provenance footer or run-summary comment.
+
+The rationale (per the monetization positioning): a PR comment is mutable by any
+maintainer, unsigned, and per-PR, so it is worthless as an audit record and
+invites false trust. The authoritative record therefore lives behind the API,
+where it can be retained, queried, and (eventually) signed. Whether any
+projection of it ever appears in the forge is a separate, out-of-scope decision;
+this PR does not build one.
+
+The API surface itself (schema, transport, signing, retention) is **out of scope
+for this PRD** and belongs with the orchestrator / control-plane work. bot-bottle
+here only produces the raw material: the sidecar's semantic operation log and the
+run metadata the orchestrator collects.
+
+### Gitea HTTP client — `bot_bottle/contrib/gitea/client.py`
+
+`GiteaForge` (and the existing `GiteaDeployKeyProvisioner`) share one thin HTTP
+client. Unlike the option-2 design, the token is held by the sidecar process and
+passed to the client directly — there is no agent-side cred-proxy route to
+inject it, because the agent never makes forge calls.
+
+```python
+class GiteaClient:
+    def __init__(self, *, api_url: str, owner: str, repo: str, token: str) -> None: ...
+    def is_org_member(self, org: str, username: str) -> bool: ...
+    def get_issue(self, number: int) -> dict: ...
+    def get_comments(self, number: int) -> list[dict]: ...
+    def post_comment(self, number: int, body: str) -> None: ...
+    def patch_issue_body(self, number: int, body: str) -> None: ...
+    def get_pull(self, number: int) -> dict: ...
+```
+
+`GiteaForge` adapts this client to the `Forge` surface (mapping raw JSON to
+`Issue` / `PullRequest` / `Comment`). Sharing only the HTTP client (not an
+abstract base) is the deliberate boundary between the sidecar and the deploy-key
+provisioner — see the deferral note under the `Forge` abstraction.
+
+### Implementation chunks
+
+1. **Headless additions on top of #315** — thread a `forge_env` parameter into
+   the existing `_launch_bottle` core (the one `start --headless` already uses);
+   add a `--headless` path to `cli/resume.py` reusing `assume_yes` +
+   `headless_prompt`. No new `start_headless`/`attach_agent_headless` helpers.
+   Tests: `forge_env` reaches the sidecar/`guest_env`; `resume --headless` skips
+   the TUI and y/N preflight and returns the agent exit code.
+
+2. **Forge state** — `contrib/gitea/forge_state.py`: `ForgeState` dataclass,
+   `ForgeStateStore` CRUD interface, `SqliteForgeStateStore`. Tests: round-trip,
+   missing → None, `INSERT OR REPLACE` upsert, delete idempotent, `all()`
+   ordering, persistence across store instances.
+
+3. **`Forge` abstraction + Gitea client** — `contrib/forge/base.py` (`Forge`
+   ABC, `ScopedForge`, `Issue` / `PullRequest` / `Comment`) and
+   `contrib/gitea/client.py` + `GiteaForge`: `is_org_member`, `read_issue`,
+   `read_pr`, `read_comments`, `post_comment`, `update_description`,
+   `get_pr_for_issue`, `is_pr_open`. Tests: mock `urllib.request.urlopen`,
+   assert payloads and 404-as-false for membership; `ScopedForge` write-scope
+   enforcement.
+
+4. **Forge sidecar** — sidecar process exposing the protocol over a Unix socket,
+   queue-dir relay, write-scope enforcement, semantic op log, `signal_done`.
+   Reuses the supervise sidecar bundle machinery. Tests: dispatch each method to
+   the `Forge`, reject out-of-scope writes, `signal_done` writes a queue event,
+   scope-rejection is logged.
+
+5. **`./cli.py orchestrate`** — `cli/orchestrate.py` with `start`, `resume`,
+   `status` subcommands wired into `cli.py`; `start` launches the forge sidecar
+   alongside the agent for forge-targeted runs. Tests: arg parsing, `start`
+   delegates to `start --headless`, `resume` delegates to `resume --headless`.
+
+## Provenance
+
+Run provenance is captured (sidecar semantic operation log + run metadata) and
+exposed through a provenance API. It is deliberately **not** surfaced in the
+forge — no footer, no run-summary comment. A mutable, unsigned PR comment is not
+an audit record; the authoritative record lives behind the API where it can be
+retained and signed. The `watchdog_fired` flag marks runs where the agent did
+not self-report completion so consumers of the API know the record may be
+incomplete.
+
+The provenance API's schema, transport, signing, and retention are out of scope
+for this PRD (control-plane work); bot-bottle here produces the raw material
+only.

docs/prds/prd-new-smolmachines-sidecar-vm.md

@@ -1,115 +0,0 @@
-# PRD prd-new: smolmachines sidecar VM
-
-- **Status:** Active
-- **Author:** codex
-- **Created:** 2026-07-09
-- **Issue:** #332
-
-## Summary
-
-Run the smolmachines backend's trusted sidecar bundle as its own smolVM instead
-of a Docker container. A bottle then consists of an agent VM plus a sidecar VM,
-with the agent VM's TSI allowlist limited to the per-bottle agent-facing
-sidecar surface.
-
-## Problem
-
-The smolmachines backend currently runs the agent in smolVM but keeps
-egress/git-gate/supervise in a Docker sidecar bundle. That hybrid launch path
-keeps Docker in the trusted runtime path and leaves smolmachines with a
-different isolation boundary than its agent VM design suggests.
-
-The existing Docker sidecar path also uses Docker port publishing to bind only
-agent-facing services to the per-bottle host address. TSI is IP-only, so the
-smolVM replacement must preserve that scoping: publishing sidecar services on
-generic host localhost would let the agent reach unrelated host services or
-other bottle sidecars if those services share the allowed address.
-
-## Goals / Success Criteria
-
-1. `BOT_BOTTLE_BACKEND=smolmachines ./cli.py start <agent>` runs with both the
-   agent and sidecar as smolVMs.
-2. The smolmachines launch path no longer uses `docker run` for the sidecar
-   bundle.
-3. Agent-facing egress, git-gate, and supervise endpoints are exposed only
-   through the bottle's own published sidecar surface.
-4. Internal sidecar-only ports are not reachable from the agent VM.
-5. The agent VM TSI allowlist remains fail-closed and limited to the per-bottle
-   address.
-6. Sidecar config, secrets, and state are delivered to the sidecar VM without
-   exposing provider or forge credentials to the agent VM.
-7. Teardown removes both VMs and any host-side published port state.
-
-## Non-goals
-
-- Rewriting the egress, git-gate, or supervise daemons.
-- Changing the Docker backend's sidecar bundle behavior.
-- Replacing the existing agent image build and pack pipeline except where shared
-  helper extraction is needed for sidecar image packing.
-- Weakening the current smolmachines TSI allowlist checks.
-
-## Design
-
-The sidecar VM continues to use the existing sidecar bundle image and
-`/app/sidecar_init.py` supervisor. The launch flow builds the sidecar image,
-packs it into a `.smolmachine` artifact, creates a per-bottle sidecar VM from
-that artifact, passes the same daemon-selection environment the Docker bundle
-uses today, mounts or copies the same daemon-private config/state inputs, starts
-the sidecar VM, wraps the sidecar VM's raw smolVM-published ports with a local
-per-bottle forwarder, then starts the agent VM with
-`--allow-cidr <per-bottle-address>/32`.
-
-smolVM currently exposes guest ports as `HOST:GUEST` port pairs bound on host
-loopback. It does not expose an address-scoped bind like
-`127.0.0.16:<port>:9099`. Because TSI is IP-only, bot-bottle must not advertise
-those raw loopback ports directly to the agent. Instead, bot-bottle runs one
-small stdlib Python TCP forwarder process per bottle:
-
-```text
-agent VM
-  -> TSI allows only <bottle-address>/32
-  -> bot-bottle forwarder bound to <bottle-address>:<random-port>
-  -> raw smolVM-published sidecar port on 127.0.0.1:<raw-port>
-  -> sidecar VM service
-```
-
-Agent-facing URLs are stamped from the forwarder ports, never the raw smolVM
-ports:
-
-- `HTTP_PROXY` / `HTTPS_PROXY` point at the published egress proxy port.
-- `GIT_GATE_URL` points at the published git HTTP port when git-gate is enabled.
-- `MCP_SUPERVISE_URL` points at the published supervise port when supervise is
-  enabled.
-
-Internal sidecar-only services stay bound inside the sidecar VM and are not
-published.
-
-### Forwarder constraints
-
-- Reject wildcard listener binds (`0.0.0.0`, `::`) and generic localhost
-  listener binds (`127.0.0.1`, `::1`) for agent-facing forwards.
-- Accept only fixed loopback targets selected by launch; the client cannot
-  choose or influence the forwarding target.
-- Forward bytes transparently without parsing HTTP, CONNECT, TLS, Git, or MCP.
-- Log lifecycle and endpoint metadata only; never log payload bytes.
-- Create forwards only for egress, git HTTP when enabled, and supervise when
-  enabled.
-- Fail closed if any listener cannot bind exactly the requested per-bottle
-  address.
-
-## Implementation chunks
-
-1. Extract the existing image-to-smolmachine pack helper so agent and sidecar
-   artifacts share the same cache and registry path.
-2. Add a strict stdlib host TCP forwarder for per-bottle address-bound
-   forwarding to raw smolVM-published sidecar ports.
-3. Add a sidecar VM launch spec and lifecycle helpers: pack, create, start,
-   publish/discover ports, stop, delete.
-4. Switch smolmachines launch from Docker sidecar bundle lifecycle to sidecar VM
-   plus forwarder lifecycle.
-5. Update egress apply / reload paths for the sidecar VM supervisor.
-6. Add unit tests for argv shape, URL stamping, teardown, and fail-closed
-   behavior.
-7. Add or update integration coverage for agent-to-sidecar reachability, host
-   localhost denial, other-bottle alias denial, internal port denial, and
-   teardown cleanup.

docs/research/landscape-containerized-claude.md

@@ -1,14 +1,20 @@
-# Landscape: containerized Claude Code agent tools
+# Landscape: containerized AI coding agent tools
 
 Research into whether bot-bottle is redundant with existing projects, and
 whether it's worth publishing.
 
 ## Summary
 
-The "Claude Code in Docker" space is active but not saturated. bot-bottle
+The "AI coding agents in isolated sandboxes" space is active but not saturated.
-occupies a distinct position: no surveyed project combines all five of its
+bot-bottle occupies a distinct position: no surveyed project combines all five
-defining features. Publishing is likely worthwhile, with the main risk being
+of its defining features. Publishing is likely worthwhile, with the main risk
-claudebox expanding to absorb the same niche.
+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
 
@@ -43,28 +49,78 @@ manifest merge.
   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.
 
 ## What no found project does
 
 None combine:
-1. Named-agent JSON manifest with per-agent env resolution (prompt / host-forward / literal)
+1. Named-agent manifest with per-agent env resolution (prompt / host-forward / literal), supporting multiple providers (Claude Code, Codex, Pi, arbitrary plugins)
-2. Claude Code skills directory injection
+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 Claude Code sessions with distinct personas/tooling):
+users running parallel AI coding agent sessions with distinct personas/tooling):
 
-- The Python-stdlib-first, low-dependency design — competitors are npm-based or
+- The Python-stdlib-first, low-dependency design — competitors are npm-based,
-  Kubernetes-native.
+  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. The space is moving fast
+Main risk: claudebox adds manifest/agent config; SuperHQ is moving fast on the
-enough that publishing sooner is better if establishing prior art matters.
+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.
@@ -73,4 +129,4 @@ HN "Show HN" would do most of the work.
 
 - GitHub search cannot surface private or very new repos comprehensively.
 - Counts (stars, forks) were not confirmed for every project.
-- Research conducted 2026-05-07; the space moves fast.
+- Initial research conducted 2026-05-07; SuperHQ entry added 2026-07-09; the space moves fast.

scripts/critical-modules.txt

@@ -22,4 +22,4 @@ bot_bottle/git_gate_provision.py
 bot_bottle/git_http_backend.py
 bot_bottle/supervise.py
 bot_bottle/yaml_subset.py
-bot_bottle/bottle_state.py
+bot_bottle/bottle/state.py

tests/integration/test_sandbox_escape.py

@@ -30,7 +30,7 @@ import unittest
 from pathlib import Path
 
 from bot_bottle.backend import BottleSpec, get_bottle_backend
-from bot_bottle.bottle_state import cleanup_state
+from bot_bottle.bottle.state import cleanup_state
 from bot_bottle.manifest import ManifestIndex
 from tests._docker import skip_unless_docker
 

tests/unit/test_api.py

@@ -0,0 +1,400 @@
+"""Unit: bot_bottle public Python API (bot_bottle/__init__.py surface).
+
+Covers start_headless, resume_headless, freeze, and destroy — the four
+operations the bot-bottle-orchestrator's ProgrammaticBottleRunner uses.
+All I/O is stubbed so no container is created.
+"""
+
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from bot_bottle import BottleError, destroy, freeze, resume_headless, start_headless
+from bot_bottle.log import Die
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_manifest(agent_name: str = "implementer", bottle_name: str = "claude"):
+    manifest = MagicMock()
+    manifest.agents = {agent_name: MagicMock(bottle=bottle_name)}
+    manifest.all_agent_names = [agent_name]
+    manifest.all_bottle_names = [bottle_name]
+    manifest.home_md = None  # eager mode — _peek_agent_bottle uses agents dict
+    manifest.require_agent = MagicMock(return_value=None)
+    return manifest
+
+
+def _metadata(
+    slug: str = "implementer-abc12",
+    agent_name: str = "implementer",
+    backend: str = "docker",
+):
+    md = MagicMock()
+    md.identity = slug
+    md.agent_name = agent_name
+    md.cwd = "/repo"
+    md.copy_cwd = False
+    md.bottle_names = ["claude"]
+    md.backend = backend
+    return md
+
+
+# ---------------------------------------------------------------------------
+# start_headless
+# ---------------------------------------------------------------------------
+
+
+class TestCompatibilityImports(unittest.TestCase):
+    def test_legacy_api_module_reexports_public_runner_api(self):
+        from bot_bottle import api
+        from bot_bottle.bottle import runner
+
+        self.assertIs(api.BottleError, runner.BottleError)
+        self.assertIs(api.start_headless, runner.start_headless)
+
+
+class TestStartHeadless(unittest.TestCase):
+    def setUp(self) -> None:
+        self._manifest = _make_manifest()
+        patch("bot_bottle.bottle.runner.ManifestIndex.resolve", return_value=self._manifest).start()
+        self._launch = patch(
+            "bot_bottle.bottle.runner._launch_bottle", return_value=("implementer-abc12", 0)
+        ).start()
+        patch(
+            "bot_bottle.bottle.runner._uniquify_label_headless", side_effect=str
+        ).start()
+        self.addCleanup(patch.stopall)
+
+    def _spec(self):
+        self._launch.assert_called_once()
+        return self._launch.call_args[0][0]
+
+    def test_returns_slug_on_success(self):
+        slug = start_headless("implementer", prompt="Do it")
+        self.assertEqual("implementer-abc12", slug)
+
+    def test_passes_assume_yes_and_prompt(self):
+        start_headless("implementer", prompt="Do it")
+        kwargs = self._launch.call_args[1]
+        self.assertTrue(kwargs["assume_yes"])
+        self.assertEqual("Do it", kwargs["headless_prompt_text"])
+
+    def test_explicit_bottles_forwarded(self):
+        start_headless("implementer", prompt="Do it", bottles=["dev", "claude"])
+        self.assertEqual(("dev", "claude"), self._spec().bottle_names)
+
+    def test_default_bottle_resolved_from_manifest(self):
+        start_headless("implementer", prompt="Do it")
+        self.assertEqual(("claude",), self._spec().bottle_names)
+
+    def test_forge_env_on_spec(self):
+        env = {"FORGE_GITEA_API": "https://gitea.example.com/api/v1", "FORGE_OWNER": "acme"}
+        start_headless("implementer", prompt="Do it", forge_env=env)
+        self.assertEqual(env, self._spec().forge_env)
+
+    def test_no_forge_env_defaults_to_empty_dict(self):
+        start_headless("implementer", prompt="Do it")
+        self.assertEqual({}, self._spec().forge_env)
+
+    def test_nonzero_exit_raises_bottle_error(self):
+        self._launch.return_value = ("implementer-abc12", 1)
+        with self.assertRaises(BottleError) as ctx:
+            start_headless("implementer", prompt="Do it")
+        self.assertEqual(1, ctx.exception.exit_code)
+
+    def test_no_default_bottle_raises_bottle_error(self):
+        manifest = _make_manifest(bottle_name="")
+        with patch("bot_bottle.bottle.runner.ManifestIndex.resolve", return_value=manifest):
+            with self.assertRaises(BottleError):
+                start_headless("implementer", prompt="Do it")
+        self._launch.assert_not_called()
+
+    def test_manifest_error_in_resolve_raises_bottle_error(self):
+        from bot_bottle.manifest import ManifestError
+        patch(
+            "bot_bottle.bottle.runner.ManifestIndex.resolve", side_effect=ManifestError("bad")
+        ).start()
+        with self.assertRaises(BottleError):
+            start_headless("implementer", prompt="Do it")
+        self._launch.assert_not_called()
+
+    def test_die_from_launch_bottle_raises_bottle_error(self):
+        self._launch.side_effect = Die(3, "backend exploded")
+        with self.assertRaises(BottleError) as ctx:
+            start_headless("implementer", prompt="Do it")
+        self.assertEqual(3, ctx.exception.exit_code)
+
+    def test_backend_name_forwarded(self):
+        start_headless("implementer", prompt="Do it", backend_name="docker")
+        self.assertEqual("docker", self._launch.call_args[1]["backend_name"])
+
+    def test_label_forwarded_to_spec(self):
+        start_headless("implementer", prompt="Do it", label="nightly")
+        self.assertEqual("nightly", self._spec().label)
+
+    def test_color_forwarded_to_spec(self):
+        start_headless("implementer", prompt="Do it", color="green")
+        self.assertEqual("green", self._spec().color)
+
+
+# ---------------------------------------------------------------------------
+# resume_headless
+# ---------------------------------------------------------------------------
+
+
+class TestResumeHeadless(unittest.TestCase):
+    def setUp(self) -> None:
+        self._md = _metadata()
+        patch("bot_bottle.bottle.runner.read_metadata", return_value=self._md).start()
+        manifest = _make_manifest()
+        patch("bot_bottle.bottle.runner.ManifestIndex.resolve", return_value=manifest).start()
+        self._launch = patch(
+            "bot_bottle.bottle.runner._launch_bottle", return_value=("implementer-abc12", 0)
+        ).start()
+        self.addCleanup(patch.stopall)
+
+    def _spec(self):
+        self._launch.assert_called_once()
+        return self._launch.call_args[0][0]
+
+    def test_passes_assume_yes_and_prompt(self):
+        resume_headless("implementer-abc12", prompt="Address review")
+        kwargs = self._launch.call_args[1]
+        self.assertTrue(kwargs["assume_yes"])
+        self.assertEqual("Address review", kwargs["headless_prompt_text"])
+
+    def test_identity_set_on_spec(self):
+        resume_headless("implementer-abc12", prompt="Prompt")
+        self.assertEqual("implementer-abc12", self._spec().identity)
+
+    def test_forge_env_on_spec(self):
+        env = {"FORGE_ISSUE_NUMBER": "42"}
+        resume_headless("implementer-abc12", prompt="Prompt", forge_env=env)
+        self.assertEqual(env, self._spec().forge_env)
+
+    def test_missing_state_raises_bottle_error(self):
+        with patch("bot_bottle.bottle.runner.read_metadata", return_value=None):
+            with self.assertRaises(BottleError):
+                resume_headless("no-such-abc12", prompt="Prompt")
+        self._launch.assert_not_called()
+
+    def test_nonzero_exit_raises_bottle_error(self):
+        self._launch.return_value = ("implementer-abc12", 2)
+        with self.assertRaises(BottleError) as ctx:
+            resume_headless("implementer-abc12", prompt="Prompt")
+        self.assertEqual(2, ctx.exception.exit_code)
+
+    def test_manifest_error_in_resolve_raises_bottle_error(self):
+        from bot_bottle.manifest import ManifestError
+        patch(
+            "bot_bottle.bottle.runner.ManifestIndex.resolve", side_effect=ManifestError("bad")
+        ).start()
+        with self.assertRaises(BottleError):
+            resume_headless("implementer-abc12", prompt="Prompt")
+        self._launch.assert_not_called()
+
+    def test_die_from_launch_bottle_raises_bottle_error(self):
+        self._launch.side_effect = Die(5, "resume failed")
+        with self.assertRaises(BottleError) as ctx:
+            resume_headless("implementer-abc12", prompt="Prompt")
+        self.assertEqual(5, ctx.exception.exit_code)
+
+    def test_backend_from_metadata_when_not_supplied(self):
+        resume_headless("implementer-abc12", prompt="Prompt")
+        self.assertEqual("docker", self._launch.call_args[1]["backend_name"])
+
+    def test_explicit_backend_overrides_metadata(self):
+        resume_headless(
+            "implementer-abc12", prompt="Prompt", backend_name="smolmachines"
+        )
+        self.assertEqual("smolmachines", self._launch.call_args[1]["backend_name"])
+
+
+# ---------------------------------------------------------------------------
+# freeze
+# ---------------------------------------------------------------------------
+
+
+class TestFreeze(unittest.TestCase):
+    def setUp(self) -> None:
+        patch("bot_bottle.bottle.runner.read_metadata", return_value=_metadata()).start()
+        self._freezer = MagicMock()
+        self._get_freezer = patch(
+            "bot_bottle.bottle.runner.get_freezer", return_value=self._freezer
+        ).start()
+        self.addCleanup(patch.stopall)
+
+    def test_calls_commit_slug(self):
+        freeze("implementer-abc12")
+        self._freezer.commit_slug.assert_called_once_with("implementer-abc12")
+
+    def test_backend_from_metadata_when_not_supplied(self):
+        freeze("implementer-abc12")
+        self._get_freezer.assert_called_once_with("docker")
+
+    def test_explicit_backend_used(self):
+        freeze("implementer-abc12", backend_name="smolmachines")
+        self._get_freezer.assert_called_once_with("smolmachines")
+
+    def test_commit_cancelled_raises_bottle_error(self):
+        from bot_bottle.backend.freeze import CommitCancelled
+        self._freezer.commit_slug.side_effect = CommitCancelled("declined")
+        with self.assertRaises(BottleError):
+            freeze("implementer-abc12")
+
+    def test_die_from_freezer_raises_bottle_error(self):
+        self._freezer.commit_slug.side_effect = Die(2, "commit exploded")
+        with self.assertRaises(BottleError) as ctx:
+            freeze("implementer-abc12")
+        self.assertEqual(2, ctx.exception.exit_code)
+
+
+# ---------------------------------------------------------------------------
+# destroy
+# ---------------------------------------------------------------------------
+
+
+class TestDestroy(unittest.TestCase):
+    def setUp(self) -> None:
+        patch("bot_bottle.bottle.runner.read_metadata", return_value=_metadata()).start()
+        self._dd = patch("bot_bottle.bottle.runner._destroy_docker").start()
+        patch("bot_bottle.bottle.runner.clear_preserve_marker").start()
+        self._cleanup = patch("bot_bottle.bottle.runner.cleanup_state").start()
+        self.addCleanup(patch.stopall)
+
+    def test_docker_backend_calls_destroy_docker(self):
+        destroy("implementer-abc12")
+        self._dd.assert_called_once_with("implementer-abc12")
+
+    def test_state_dir_always_cleaned(self):
+        destroy("implementer-abc12")
+        self._cleanup.assert_called_once_with("implementer-abc12")
+
+    def test_smolmachines_backend_calls_destroy_smolmachines(self):
+        patch(
+            "bot_bottle.bottle.runner.read_metadata",
+            return_value=_metadata(backend="smolmachines"),
+        ).start()
+        ds = patch("bot_bottle.bottle.runner._destroy_smolmachines").start()
+        destroy("implementer-abc12")
+        ds.assert_called_once_with("implementer-abc12")
+        self._dd.assert_not_called()
+
+    def test_other_backend_skips_docker_and_smolmachines(self):
+        patch(
+            "bot_bottle.bottle.runner.read_metadata",
+            return_value=_metadata(backend="macos-container"),
+        ).start()
+        ds = patch("bot_bottle.bottle.runner._destroy_smolmachines").start()
+        destroy("implementer-abc12")
+        self._dd.assert_not_called()
+        ds.assert_not_called()
+        self._cleanup.assert_called_once_with("implementer-abc12")
+
+    def test_missing_metadata_defaults_to_docker(self):
+        patch("bot_bottle.bottle.runner.read_metadata", return_value=None).start()
+        destroy("no-state-abc12")
+        self._dd.assert_called_once_with("no-state-abc12")
+
+    def test_explicit_backend_overrides_metadata(self):
+        ds = patch("bot_bottle.bottle.runner._destroy_smolmachines").start()
+        destroy("implementer-abc12", backend_name="smolmachines")
+        ds.assert_called_once_with("implementer-abc12")
+        self._dd.assert_not_called()
+
+    def test_die_from_backend_raises_bottle_error(self):
+        self._dd.side_effect = Die(1, "compose failed")
+        with self.assertRaises(BottleError):
+            destroy("implementer-abc12")
+
+
+# ---------------------------------------------------------------------------
+# _destroy_docker (helper)
+# ---------------------------------------------------------------------------
+
+
+class TestDestroyDocker(unittest.TestCase):
+    def setUp(self) -> None:
+        self._compose_down = patch(
+            "bot_bottle.backend.docker.compose.compose_down"
+        ).start()
+        self._compose_project_name = patch(
+            "bot_bottle.backend.docker.compose.compose_project_name",
+            return_value="bb-proj",
+        ).start()
+        self._state_dir = patch(
+            "bot_bottle.bottle.state.bottle_state_dir",
+            return_value=Path("/fake/state"),
+        ).start()
+        self.addCleanup(patch.stopall)
+
+    def _run(self, exists: bool) -> None:
+        fake_file = MagicMock()
+        fake_file.exists.return_value = exists
+        with patch(
+            "bot_bottle.backend.docker.compose.compose_file_path",
+            return_value=fake_file,
+        ):
+            from bot_bottle.bottle.runner import _destroy_docker
+            _destroy_docker("slug-1")
+
+    def test_calls_compose_down_when_file_exists(self) -> None:
+        self._run(exists=True)
+        self._compose_down.assert_called_once()
+
+    def test_noop_when_compose_file_absent(self) -> None:
+        self._run(exists=False)
+        self._compose_down.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# _destroy_smolmachines (helper)
+# ---------------------------------------------------------------------------
+
+
+class TestDestroySmolmachines(unittest.TestCase):
+    def setUp(self) -> None:
+        self._run = patch("subprocess.run").start()
+        self._run.return_value = MagicMock(returncode=0, stderr="", stdout="")
+        self.addCleanup(patch.stopall)
+
+    def _call(self) -> None:
+        from bot_bottle.bottle.runner import _destroy_smolmachines
+        _destroy_smolmachines("slug-7")
+
+    def test_issues_stop_then_delete(self) -> None:
+        self._call()
+        self.assertEqual(2, self._run.call_count)
+        first_argv = self._run.call_args_list[0][0][0]
+        self.assertIn("stop", first_argv)
+        second_argv = self._run.call_args_list[1][0][0]
+        self.assertIn("delete", second_argv)
+
+    def test_nonzero_delete_does_not_raise(self) -> None:
+        self._run.side_effect = [
+            MagicMock(returncode=0),
+            MagicMock(returncode=1, stderr="not found", stdout=""),
+        ]
+        self._call()  # must not raise
+
+
+# ---------------------------------------------------------------------------
+# public surface exported from bot_bottle.__init__
+# ---------------------------------------------------------------------------
+
+
+class TestPublicSurface(unittest.TestCase):
+    def test_importable_from_package(self):
+        import bot_bottle
+        for name in ("BottleError", "start_headless", "resume_headless", "freeze", "destroy"):
+            self.assertTrue(hasattr(bot_bottle, name), f"missing: {name}")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_bottle_state.py

@@ -8,7 +8,7 @@ from pathlib import Path
 
 from bot_bottle import supervise
 from bot_bottle import bottle_state
-from bot_bottle.bottle_state import (
+from bot_bottle.bottle.state import (
     BottleMetadata,
     read_metadata,
     write_metadata,
@@ -31,6 +31,15 @@ class _FakeHomeMixin:
         self._tmp.cleanup()
 
 
+class TestCompatibilityImports(unittest.TestCase):
+    def test_legacy_bottle_state_module_reexports_state_api(self):
+        from bot_bottle import bottle_state as legacy
+        from bot_bottle.bottle import state
+
+        self.assertIs(legacy.BottleMetadata, state.BottleMetadata)
+        self.assertIs(legacy.read_metadata, state.read_metadata)
+
+
 class TestPerBottleDockerfile(_FakeHomeMixin, unittest.TestCase):
     def setUp(self):
         self._setup_fake_home()

tests/unit/test_cli_resume_headless.py

@@ -0,0 +1,75 @@
+"""Unit: `cli.py resume --headless` non-interactive rehydrate path.
+
+The freeze / rehydrate loop needs a non-interactive `resume`: deliver a
+follow-up prompt and skip the y/N preflight, reusing the same launch
+core (`assume_yes` + `headless_prompt_text`) as `start --headless`.
+"""
+
+from __future__ import annotations
+
+import unittest
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import bot_bottle.cli.resume as resume_mod
+from bot_bottle.log import Die
+
+
+def _metadata():
+    md = MagicMock()
+    md.agent_name = "implementer"
+    md.copy_cwd = False
+    md.cwd = "/repo"
+    md.identity = "implementer-abc12"
+    md.bottle_names = ["claude"]
+    md.backend = "docker"
+    return md
+
+
+class ResumeHeadlessTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self._launch = patch.object(
+            resume_mod, "_launch_bottle", return_value=("implementer-abc12", 0)
+        ).start()
+        patch.object(
+            resume_mod, "read_metadata", return_value=_metadata()
+        ).start()
+        manifest = MagicMock()
+        manifest.require_agent = MagicMock(return_value=None)
+        patch.object(
+            resume_mod.ManifestIndex, "resolve", return_value=manifest
+        ).start()
+        self.addCleanup(patch.stopall)
+
+    def _launch_kwargs(self) -> dict[str, Any]:
+        self._launch.assert_called_once()
+        return dict(self._launch.call_args.kwargs)
+
+    def test_headless_passes_assume_yes_and_prompt(self):
+        rc = resume_mod.cmd_resume(
+            ["implementer-abc12", "--headless", "--prompt", "Address the review"]
+        )
+        self.assertEqual(0, rc)
+        kwargs = self._launch_kwargs()
+        self.assertTrue(kwargs["assume_yes"])
+        self.assertEqual("Address the review", kwargs["headless_prompt_text"])
+
+    def test_interactive_resume_unchanged(self):
+        resume_mod.cmd_resume(["implementer-abc12"])
+        kwargs = self._launch_kwargs()
+        self.assertFalse(kwargs["assume_yes"])
+        self.assertEqual("", kwargs["headless_prompt_text"])
+
+    def test_headless_without_prompt_errors(self):
+        with self.assertRaises(Die):
+            resume_mod.cmd_resume(["implementer-abc12", "--headless"])
+        self._launch.assert_not_called()
+
+    def test_prompt_without_headless_errors(self):
+        with self.assertRaises(Die):
+            resume_mod.cmd_resume(["implementer-abc12", "--prompt", "hi"])
+        self._launch.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_cli_start_headless.py

@@ -57,7 +57,7 @@ class TestCmdStartHeadless(unittest.TestCase):
             return_value=self._manifest,
         ).start()
         self._launch_mock = patch(
-            "bot_bottle.cli.start._launch_bottle", return_value=0
+            "bot_bottle.cli.start._launch_bottle", return_value=("", 0)
         ).start()
         # No bottles running by default → no label collision.
         patch(
@@ -184,18 +184,6 @@ class TestCmdStartHeadless(unittest.TestCase):
         )
         self.assertEqual("docker", self._launch_mock.call_args[1]["backend_name"])
 
-    def test_cached_images_sets_cached_policy(self):
-        start_mod.cmd_start(
-            ["--headless", "--cached-images", "researcher", "--bottle", "claude",
-             "--prompt", "Do it"]
-        )
-        self.assertEqual("cached", self._spec().image_policy)
-
-    def test_cached_images_requires_headless(self):
-        with self.assertRaises(Die):
-            start_mod.cmd_start(["--cached-images", "researcher"])
-        self._launch_mock.assert_not_called()
-
 
 class TestPrepareWithPreflight(unittest.TestCase):
     """prepare_with_preflight calls render_preflight with the plan and backend name."""

tests/unit/test_cli_start_selector.py

@@ -45,7 +45,7 @@ class TestCmdStartSelector(unittest.TestCase):
 
         self._launch_patch = patch(
             "bot_bottle.cli.start._launch_bottle",
-            return_value=0,
+            return_value=("", 0),
         )
         self._launch_mock = self._launch_patch.start()
 
@@ -57,12 +57,6 @@ class TestCmdStartSelector(unittest.TestCase):
         self._bottle_picker_mock = self._bottle_picker_patch.start()
         self._bottle_picker_mock.return_value = ["claude"]  # default: one bottle selected
 
-        self._image_policy_patch = patch(
-            "bot_bottle.cli.start._select_image_policy",
-            return_value="fresh",
-        )
-        self._image_policy_patch.start()
-
         self._env_patch = patch.dict(os.environ, {}, clear=False)
         self._env_patch.start()
         os.environ.pop("BOT_BOTTLE_BACKEND", None)
@@ -72,7 +66,6 @@ class TestCmdStartSelector(unittest.TestCase):
         self._launch_patch.stop()
         self._agent_picker_patch.stop()
         self._bottle_picker_patch.stop()
-        self._image_policy_patch.stop()
         self._env_patch.stop()
 
     # ------------------------------------------------------------------
@@ -131,19 +124,6 @@ class TestCmdStartSelector(unittest.TestCase):
         spec = self._launch_mock.call_args[0][0]
         self.assertEqual(("claude", "dev"), spec.bottle_names)
 
-    def test_image_policy_forwarded_to_spec(self):
-        with patch("bot_bottle.cli.start._select_image_policy", return_value="cached"):
-            start_mod.cmd_start(["researcher"])
-        self._launch_mock.assert_called_once()
-        spec = self._launch_mock.call_args[0][0]
-        self.assertEqual("cached", spec.image_policy)
-
-    def test_image_policy_cancel_returns_0(self):
-        with patch("bot_bottle.cli.start._select_image_policy", return_value=None):
-            rc = start_mod.cmd_start(["researcher"])
-        self.assertEqual(0, rc)
-        self._launch_mock.assert_not_called()
-
     def test_empty_bottle_selection_forwarded(self):
         self._bottle_picker_mock.return_value = []
         start_mod.cmd_start(["researcher"])
@@ -231,11 +211,10 @@ class TestCmdStartLabelCollision(unittest.TestCase):
         self._manifest = _make_manifest(["researcher"], ["claude"])
         patch("bot_bottle.cli.start.ManifestIndex.resolve", return_value=self._manifest).start()
         self._launch_mock = patch(
-            "bot_bottle.cli.start._launch_bottle", return_value=0,
+            "bot_bottle.cli.start._launch_bottle", return_value=("", 0),
         ).start()
         # Stub the bottle picker to always return a selection.
         patch.object(tui_mod, "filter_multiselect", return_value=["claude"]).start()
-        patch("bot_bottle.cli.start._select_image_policy", return_value="fresh").start()
         self.addCleanup(patch.stopall)
 
     def test_no_collision_proceeds_without_reprompt(self):

tests/unit/test_cli_start_stale.py

@@ -1,164 +0,0 @@
-"""Unit: _launch_bottle StaleImageError handling.
-
-Exercises the while-True / try-except loop around backend.launch:
-  - headless mode → die on stale
-  - interactive mode, user declines → stop without launching
-  - interactive mode, user confirms → retry with skip_stale=True
-"""
-
-from __future__ import annotations
-
-import io
-import tempfile
-import unittest
-from types import SimpleNamespace
-from typing import Any, cast
-from unittest.mock import MagicMock, patch
-
-from bot_bottle.image_cache import StaleImageError
-from bot_bottle.log import Die
-
-
-def _fake_plan() -> Any:
-    provision = SimpleNamespace(startup_args=())
-    return cast(Any, SimpleNamespace(
-        agent_provision=provision,
-        agent_provider_template="claude",
-        slug="dev-abc",
-    ))
-
-
-def _stale_cm() -> MagicMock:
-    """Return a context-manager mock whose __enter__ raises StaleImageError."""
-    cm = MagicMock()
-    cm.__enter__ = MagicMock(side_effect=StaleImageError("image is 5 day(s) old"))
-    cm.__exit__ = MagicMock(return_value=False)
-    return cm
-
-
-def _ok_cm(bottle: Any) -> MagicMock:
-    """Return a context-manager mock that yields `bottle`."""
-    cm = MagicMock()
-    cm.__enter__ = MagicMock(return_value=bottle)
-    cm.__exit__ = MagicMock(return_value=False)
-    return cm
-
-
-class TestLaunchBottleStaleHandling(unittest.TestCase):
-    def setUp(self) -> None:
-        self._tmp = tempfile.mkdtemp(prefix="cli-stale-test.")
-
-    def _spec(self) -> Any:
-        from bot_bottle.backend import BottleSpec
-        from bot_bottle.manifest import ManifestIndex
-        idx = ManifestIndex.from_json_obj({
-            "bottles": {"dev": {}},
-            "agents": {"demo": {"skills": [], "prompt": "", "bottle": "dev"}},
-        })
-        return BottleSpec(
-            manifest=idx,
-            agent_name="demo",
-            copy_cwd=False,
-            user_cwd=self._tmp,
-            identity="dev-abc",
-        )
-
-    def _run_launch(self, **patch_kwargs: Any) -> int:
-        import bot_bottle.cli.start as start_mod
-        spec = self._spec()
-        with patch.object(start_mod, "prepare_with_preflight",
-                          return_value=(_fake_plan(), "dev-abc")), \
-             patch.object(start_mod, "settle_state"), \
-             patch.object(start_mod, "info"):
-            return start_mod._launch_bottle(
-                spec,
-                dry_run=False,
-                backend_name="docker",
-                **patch_kwargs,
-            )
-
-    def test_headless_stale_calls_die(self) -> None:
-        """In headless mode (assume_yes=True), a StaleImageError must call die()."""
-        import bot_bottle.cli.start as start_mod
-
-        backend_mock = MagicMock()
-        backend_mock.launch.return_value = _stale_cm()
-
-        with patch.object(start_mod, "get_bottle_backend", return_value=backend_mock), \
-             patch.object(start_mod, "die", side_effect=Die()):
-            with self.assertRaises(Die):
-                self._run_launch(assume_yes=True)
-
-    def test_interactive_user_declines_stops_loop(self) -> None:
-        """Interactive user answering 'n' → loop exits without a second launch."""
-        import bot_bottle.cli.start as start_mod
-
-        backend_mock = MagicMock()
-        backend_mock.launch.return_value = _stale_cm()
-
-        with patch.object(start_mod, "get_bottle_backend", return_value=backend_mock), \
-             patch.object(start_mod, "read_tty_line", return_value="n"), \
-             patch("sys.stderr", new_callable=io.StringIO):
-            rc = self._run_launch(assume_yes=False)
-
-        self.assertEqual(0, rc)
-        # launch was called once (stale), then the user declined → no second call.
-        backend_mock.launch.assert_called_once()
-
-    def test_interactive_user_confirms_retries_with_skip_stale(self) -> None:
-        """Interactive user answering 'y' → second launch with skip_stale=True."""
-        import bot_bottle.cli.start as start_mod
-
-        bottle_mock = MagicMock()
-        bottle_mock.name = "dev-abc"
-
-        def launch_side_effect(plan: Any, *, skip_stale: bool = False) -> Any:
-            if not skip_stale:
-                return _stale_cm()
-            return _ok_cm(bottle_mock)
-
-        backend_mock = MagicMock()
-        backend_mock.launch.side_effect = launch_side_effect
-
-        with patch.object(start_mod, "get_bottle_backend", return_value=backend_mock), \
-             patch.object(start_mod, "read_tty_line", return_value="y"), \
-             patch.object(start_mod, "attach_agent", return_value=0), \
-             patch.object(start_mod, "capture_claude_session_state"), \
-             patch("sys.stderr", new_callable=io.StringIO):
-            rc = self._run_launch(assume_yes=False)
-
-        self.assertEqual(0, rc)
-        # First call: skip_stale=False → stale. Second call: skip_stale=True → ok.
-        self.assertEqual(2, backend_mock.launch.call_count)
-        calls = backend_mock.launch.call_args_list
-        self.assertFalse(calls[0].kwargs.get("skip_stale", False))
-        self.assertTrue(calls[1].kwargs.get("skip_stale", False))
-
-    def test_interactive_yes_uppercase_also_accepted(self) -> None:
-        """'Y' or 'YES' should also be accepted as confirmation."""
-        import bot_bottle.cli.start as start_mod
-
-        bottle_mock = MagicMock()
-        bottle_mock.name = "dev-abc"
-
-        def launch_side_effect(plan: Any, *, skip_stale: bool = False) -> Any:
-            if not skip_stale:
-                return _stale_cm()
-            return _ok_cm(bottle_mock)
-
-        backend_mock = MagicMock()
-        backend_mock.launch.side_effect = launch_side_effect
-
-        with patch.object(start_mod, "get_bottle_backend", return_value=backend_mock), \
-             patch.object(start_mod, "read_tty_line", return_value="YES"), \
-             patch.object(start_mod, "attach_agent", return_value=0), \
-             patch.object(start_mod, "capture_claude_session_state"), \
-             patch("sys.stderr", new_callable=io.StringIO):
-            rc = self._run_launch(assume_yes=False)
-
-        self.assertEqual(0, rc)
-        self.assertEqual(2, backend_mock.launch.call_count)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/test_compose.py

@@ -118,7 +118,6 @@ def _plan(
     with_egress: bool = False,
     supervise: bool = False,
     canary: bool = False,
-    image_policy: str = "fresh",
 ) -> DockerBottlePlan:
     """Build a fully-resolved DockerBottlePlan. Toggles cover the
     matrix the renderer's conditional-service logic branches on."""
@@ -149,7 +148,6 @@ def _plan(
         agent_name="demo",
         copy_cwd=False,
         user_cwd="/tmp/x",
-        image_policy=image_policy,
     )
     return DockerBottlePlan(
         spec=spec,
@@ -267,8 +265,7 @@ class TestAgentAlwaysPresent(unittest.TestCase):
     def test_agent_depends_only_on_sidecars(self):
         # Bundle shape: the init supervisor owns intra-bundle daemon
         # ordering, so the agent waits on the bundle container alone.
-        cases: list[dict[str, Any]] = [{}, {"with_git": True, "with_egress": True, "supervise": True}]
+        for kwargs in [{}, {"with_git": True, "with_egress": True, "supervise": True}]:
-        for kwargs in cases:
             with self.subTest(**kwargs):
                 s = bottle_plan_to_compose(_plan(**kwargs))["services"]["agent"]
                 self.assertEqual(["sidecars"], s["depends_on"])
@@ -303,11 +300,6 @@ class TestSidecarBundleShape(unittest.TestCase):
         self.assertEqual("bot-bottle-sidecars:latest", sc["image"])
         self.assertEqual("Dockerfile.sidecars", sc["build"]["dockerfile"])
 
-    def test_cached_policy_omits_bundle_build(self):
-        sc = self._render(image_policy="cached")["services"]["sidecars"]
-        self.assertEqual("bot-bottle-sidecars:latest", sc["image"])
-        self.assertNotIn("build", sc)
-
     def test_bundle_container_name_uses_sidecars_prefix(self):
         sc = self._render()["services"]["sidecars"]
         self.assertEqual(f"bot-bottle-sidecars-{SLUG}", sc["container_name"])

tests/unit/test_config_store.py

@@ -1,86 +0,0 @@
-"""Unit tests for the host-side configuration store."""
-
-from __future__ import annotations
-
-import sqlite3
-import tempfile
-import unittest
-from pathlib import Path
-
-from bot_bottle.config_store import (
-    DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS,
-    ConfigStore,
-)
-from bot_bottle.store_manager import StoreManager
-
-
-class TestConfigStore(unittest.TestCase):
-    def test_cached_image_warning_days_defaults_to_one(self) -> None:
-        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
-            store = ConfigStore(Path(tmp) / "bot-bottle.db")
-            store.migrate()
-            self.assertEqual(
-                DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS,
-                store.cached_image_stale_warning_days(),
-            )
-
-    def test_cached_image_warning_days_reads_value(self) -> None:
-        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
-            store = ConfigStore(Path(tmp) / "bot-bottle.db")
-            store.migrate()
-            store.set_cached_image_stale_warning_days(7)
-            self.assertEqual(7, store.cached_image_stale_warning_days())
-
-    def test_config_schema_uses_explicit_settings_columns(self) -> None:
-        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
-            store = ConfigStore(Path(tmp) / "bot-bottle.db")
-            store.migrate()
-            with sqlite3.connect(store.db_path) as conn:
-                conn.row_factory = sqlite3.Row
-                columns = [
-                    row["name"]
-                    for row in conn.execute("PRAGMA table_info(bot_bottle_config)")
-                ]
-            self.assertEqual([
-                "id",
-                "cached_image_stale_warning_days",
-            ], columns)
-
-    def test_store_manager_includes_config_store(self) -> None:
-        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
-            db = Path(tmp) / "bot-bottle.db"
-            manager = StoreManager(db)
-            self.assertFalse(manager.is_migrated())
-            manager.migrate()
-            self.assertTrue(manager.is_migrated())
-
-    def test_cached_image_warning_days_returns_default_when_db_missing(self) -> None:
-        # When the db file doesn't exist yet (parent exists, file doesn't),
-        # the store returns the default without touching the file.
-        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
-            store = ConfigStore(Path(tmp) / "missing.db")
-            self.assertEqual(
-                DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS,
-                store.cached_image_stale_warning_days(),
-            )
-
-    def test_cached_image_warning_days_returns_default_on_null_value(self) -> None:
-        # If the row exists but the value is NULL (or not castable to int),
-        # the store falls back to the default.
-        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
-            db_path = Path(tmp) / "bot-bottle.db"
-            store = ConfigStore(db_path)
-            store.migrate()
-            # Write a NULL value directly.
-            with sqlite3.connect(db_path) as conn:
-                conn.execute(
-                    "UPDATE bot_bottle_config SET cached_image_stale_warning_days = NULL WHERE id = 1"
-                )
-            self.assertEqual(
-                DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS,
-                store.cached_image_stale_warning_days(),
-            )
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/test_contrib_forge_base.py

@@ -0,0 +1,107 @@
+"""Unit: Forge abstraction + ScopedForge (PRD forge-native-integration)."""
+
+from __future__ import annotations
+
+import unittest
+
+from bot_bottle.contrib.forge.base import (
+    Comment,
+    Forge,
+    ForgeScopeError,
+    Issue,
+    PullRequest,
+    ScopedForge,
+)
+
+
+class _RecordingForge(Forge):
+    """In-memory fake that records writes."""
+
+    def __init__(self) -> None:
+        self.comments: list[tuple[int, str]] = []
+        self.descriptions: list[tuple[int, str]] = []
+
+    def read_issue(self, number: int) -> Issue:
+        return Issue(number=number, title="t", body="b", state="open")
+
+    def read_pr(self, number: int) -> PullRequest:
+        return PullRequest(
+            number=number, title="pr", body="b", state="open", merged=False
+        )
+
+    def read_comments(self, number: int) -> list[Comment]:
+        return [Comment(id=1, user="alice", body="hi")]
+
+    def post_comment(self, number: int, body: str) -> None:
+        self.comments.append((number, body))
+
+    def update_description(self, number: int, body: str) -> None:
+        self.descriptions.append((number, body))
+
+    def is_org_member(self, org: str, username: str) -> bool:
+        return username == "member"
+
+    def get_pr_for_issue(self, number: int) -> int | None:
+        return 99 if number == 17 else None
+
+    def is_pr_open(self, number: int) -> bool:
+        return True
+
+
+class TestScopedForgeReads(unittest.TestCase):
+    def setUp(self) -> None:
+        self.inner = _RecordingForge()
+        self.scoped = ScopedForge(self.inner, assigned_issue=17, assigned_prs=[42])
+
+    def test_reads_pass_through_to_any_number(self):
+        # A number well outside the writable scope still reads fine.
+        self.assertEqual(123, self.scoped.read_issue(123).number)
+        self.assertEqual("alice", self.scoped.read_comments(500)[0].user)
+
+    def test_read_pr_passes_through(self):
+        pr = self.scoped.read_pr(999)
+        self.assertIsInstance(pr, PullRequest)
+        self.assertEqual(999, pr.number)
+        self.assertFalse(pr.merged)
+
+    def test_membership_and_pr_lookups_delegate(self):
+        self.assertTrue(self.scoped.is_org_member("bot-bottle", "member"))
+        self.assertFalse(self.scoped.is_org_member("bot-bottle", "stranger"))
+        self.assertEqual(99, self.scoped.get_pr_for_issue(17))
+        self.assertTrue(self.scoped.is_pr_open(8000))
+
+
+class TestScopedForgeWrites(unittest.TestCase):
+    def setUp(self) -> None:
+        self.inner = _RecordingForge()
+        self.scoped = ScopedForge(self.inner, assigned_issue=17, assigned_prs=[42])
+
+    def test_writable_set_is_issue_plus_prs(self):
+        self.assertEqual(frozenset({17, 42}), self.scoped.writable)
+
+    def test_write_to_assigned_issue_allowed(self):
+        self.scoped.post_comment(17, "done")
+        self.assertEqual([(17, "done")], self.inner.comments)
+
+    def test_write_to_assigned_pr_allowed(self):
+        self.scoped.update_description(42, "new body")
+        self.assertEqual([(42, "new body")], self.inner.descriptions)
+
+    def test_comment_outside_scope_rejected(self):
+        with self.assertRaises(ForgeScopeError) as ctx:
+            self.scoped.post_comment(500, "spam")
+        self.assertIn("500", str(ctx.exception))
+        self.assertEqual([], self.inner.comments)
+
+    def test_description_outside_scope_rejected(self):
+        with self.assertRaises(ForgeScopeError):
+            self.scoped.update_description(500, "tamper")
+        self.assertEqual([], self.inner.descriptions)
+
+    def test_scope_error_is_permission_error(self):
+        # Sidecars can catch the stdlib base type.
+        self.assertIn(PermissionError, ForgeScopeError.__mro__)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_contrib_gitea_client.py

@@ -0,0 +1,145 @@
+"""Unit: GiteaClient + GiteaForge (PRD forge-native-integration)."""
+
+from __future__ import annotations
+
+import json
+import unittest
+import urllib.error
+from io import BytesIO
+from unittest.mock import MagicMock, patch
+
+from bot_bottle.contrib.gitea.client import GiteaClient, GiteaForge
+
+
+def _client() -> GiteaClient:
+    return GiteaClient(
+        api_url="https://gitea.example.com/api/v1",
+        owner="didericis",
+        repo="bot-bottle",
+        token="test-token",
+    )
+
+
+def _resp(body: object, status: int = 200) -> MagicMock:
+    resp = MagicMock()
+    resp.read.return_value = json.dumps(body).encode() if body is not None else b""
+    resp.status = status
+    resp.__enter__ = lambda s: s  # type: ignore
+    resp.__exit__ = MagicMock(return_value=False)
+    return resp
+
+
+def _http_error(code: int, body: str = "") -> urllib.error.HTTPError:
+    return urllib.error.HTTPError(
+        url="http://x", code=code, msg="err", hdrs=None,  # type: ignore[arg-type]
+        fp=BytesIO(body.encode()),
+    )
+
+
+_URLOPEN = "bot_bottle.contrib.gitea.client.urllib.request.urlopen"
+
+
+class TestOrgMembership(unittest.TestCase):
+    def test_member_returns_true_on_2xx(self):
+        with patch(_URLOPEN, return_value=_resp(None, 204)) as m:
+            self.assertTrue(_client().is_org_member("bot-bottle", "alice"))
+        req = m.call_args.args[0]
+        self.assertIn("/orgs/bot-bottle/members/alice", req.full_url)
+
+    def test_nonmember_returns_false_on_404(self):
+        with patch(_URLOPEN, side_effect=_http_error(404)):
+            self.assertFalse(_client().is_org_member("bot-bottle", "stranger"))
+
+    def test_other_http_error_raises(self):
+        with patch(_URLOPEN, side_effect=_http_error(403, "forbidden")):
+            with self.assertRaises(RuntimeError) as ctx:
+                _client().is_org_member("bot-bottle", "alice")
+        self.assertIn("403", str(ctx.exception))
+
+
+class TestForgeReads(unittest.TestCase):
+    def test_read_issue_maps_fields(self):
+        raw = {"number": 17, "title": "Bug", "body": "broken", "state": "open"}
+        with patch(_URLOPEN, return_value=_resp(raw)) as m:
+            issue = GiteaForge(_client()).read_issue(17)
+        self.assertEqual((17, "Bug", "broken", "open"),
+                         (issue.number, issue.title, issue.body, issue.state))
+        self.assertIn("/repos/didericis/bot-bottle/issues/17",
+                      m.call_args.args[0].full_url)
+
+    def test_read_issue_tolerates_null_body(self):
+        raw = {"number": 17, "title": "T", "body": None, "state": "open"}
+        with patch(_URLOPEN, return_value=_resp(raw)):
+            self.assertEqual("", GiteaForge(_client()).read_issue(17).body)
+
+    def test_read_comments_maps_user_login(self):
+        raw = [
+            {"id": 1, "user": {"login": "alice"}, "body": "hi"},
+            {"id": 2, "user": {"login": "bob"}, "body": "yo"},
+        ]
+        with patch(_URLOPEN, return_value=_resp(raw)):
+            comments = GiteaForge(_client()).read_comments(17)
+        self.assertEqual(["alice", "bob"], [c.user for c in comments])
+        self.assertEqual([1, 2], [c.id for c in comments])
+
+
+class TestForgeWrites(unittest.TestCase):
+    def test_post_comment_payload_and_url(self):
+        with patch(_URLOPEN, return_value=_resp(None, 201)) as m:
+            GiteaForge(_client()).post_comment(17, "done ✓")
+        req = m.call_args.args[0]
+        self.assertEqual("POST", req.method)
+        self.assertIn("/repos/didericis/bot-bottle/issues/17/comments", req.full_url)
+        self.assertEqual("done ✓", json.loads(req.data)["body"])
+
+    def test_update_description_patches_issue(self):
+        with patch(_URLOPEN, return_value=_resp(None, 200)) as m:
+            GiteaForge(_client()).update_description(17, "edited")
+        req = m.call_args.args[0]
+        self.assertEqual("PATCH", req.method)
+        self.assertTrue(req.full_url.endswith("/issues/17"))
+        self.assertEqual("edited", json.loads(req.data)["body"])
+
+    def test_auth_header_sent(self):
+        with patch(_URLOPEN, return_value=_resp(None, 201)) as m:
+            GiteaForge(_client()).post_comment(17, "x")
+        self.assertEqual("token test-token",
+                         m.call_args.args[0].headers["Authorization"])
+
+
+class TestPRHelpers(unittest.TestCase):
+    def test_get_pr_for_issue_returns_number_when_issue_is_pr(self):
+        raw = {"number": 18, "pull_request": {"merged": False}}
+        with patch(_URLOPEN, return_value=_resp(raw)):
+            self.assertEqual(18, GiteaForge(_client()).get_pr_for_issue(18))
+
+    def test_get_pr_for_issue_none_for_plain_issue(self):
+        raw = {"number": 17, "pull_request": None}
+        with patch(_URLOPEN, return_value=_resp(raw)):
+            self.assertIsNone(GiteaForge(_client()).get_pr_for_issue(17))
+
+    def test_is_pr_open_true_when_state_open(self):
+        with patch(_URLOPEN, return_value=_resp({"state": "open"})):
+            self.assertTrue(GiteaForge(_client()).is_pr_open(18))
+
+    def test_is_pr_open_false_when_closed(self):
+        with patch(_URLOPEN, return_value=_resp({"state": "closed"})):
+            self.assertFalse(GiteaForge(_client()).is_pr_open(18))
+
+    def test_read_pr_maps_fields_including_merged(self):
+        raw = {"number": 18, "title": "Fix", "body": "patch",
+               "state": "closed", "merged": True}
+        with patch(_URLOPEN, return_value=_resp(raw)) as m:
+            pr = GiteaForge(_client()).read_pr(18)
+        self.assertEqual((18, "Fix", "patch", "closed", True),
+                         (pr.number, pr.title, pr.body, pr.state, pr.merged))
+        self.assertIn("/repos/didericis/bot-bottle/pulls/18",
+                      m.call_args.args[0].full_url)
+
+    def test_read_pr_merged_defaults_false(self):
+        with patch(_URLOPEN, return_value=_resp({"number": 18, "state": "open"})):
+            self.assertFalse(GiteaForge(_client()).read_pr(18).merged)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_contrib_gitea_forge_state.py

@@ -0,0 +1,99 @@
+"""Unit: SQLite forge state store (PRD forge-native-integration)."""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from dataclasses import replace
+from pathlib import Path
+
+from bot_bottle.contrib.gitea.forge_state import (
+    STATUS_FROZEN,
+    STATUS_RUNNING,
+    ForgeState,
+    SqliteForgeStateStore,
+)
+
+
+def _state(**over: object) -> ForgeState:
+    base = ForgeState(
+        owner="didericis",
+        repo="bot-bottle",
+        issue_number=17,
+        slug="implementer-abc12",
+        agent_name="implementer",
+        bottle_names=["claude"],
+        backend_name="docker",
+        agent_git_user="didericis-claude",
+        pr_number=42,
+        status=STATUS_FROZEN,
+        last_checkin_at="2026-06-29T12:04:12-04:00",
+    )
+    return replace(base, **over)
+
+
+class ForgeStateStoreTest(unittest.TestCase):
+    def setUp(self) -> None:
+        tmp = Path(self.enterContext(tempfile.TemporaryDirectory()))  # pylint: disable=consider-using-with
+        self.store = SqliteForgeStateStore(tmp / "sub" / "bot-bottle.db")
+
+    def test_round_trip(self):
+        self.store.upsert(_state())
+        self.assertEqual(_state(), self.store.get("didericis", "bot-bottle", 17))
+
+    def test_missing_returns_none(self):
+        self.assertIsNone(self.store.get("nobody", "nope", 1))
+
+    def test_creates_db_parent_dirs(self):
+        # setUp pointed at a non-existent 'sub/' dir; init must create it.
+        self.assertIsNone(self.store.get("x", "y", 1))  # no raise
+
+    def test_upsert_replaces(self):
+        self.store.upsert(_state(status=STATUS_RUNNING))
+        self.store.upsert(_state(status=STATUS_FROZEN))
+        got = self.store.get("didericis", "bot-bottle", 17)
+        assert got is not None
+        self.assertEqual(STATUS_FROZEN, got.status)
+        # Still one row, not two.
+        self.assertEqual(1, len(self.store.all()))
+
+    def test_delete_is_idempotent(self):
+        self.store.upsert(_state())
+        self.store.delete("didericis", "bot-bottle", 17)
+        self.store.delete("didericis", "bot-bottle", 17)  # no raise
+        self.assertIsNone(self.store.get("didericis", "bot-bottle", 17))
+
+    def test_all_lists_across_repos_sorted(self):
+        self.store.upsert(_state(issue_number=18, slug="other"))
+        self.store.upsert(_state(issue_number=17))
+        self.store.upsert(_state(owner="acme", repo="widget", issue_number=3))
+        states = self.store.all()
+        self.assertEqual(3, len(states))
+        self.assertEqual(
+            [("acme", 3), ("didericis", 17), ("didericis", 18)],
+            [(s.owner, s.issue_number) for s in states],
+        )
+
+    def test_all_empty(self):
+        self.assertEqual([], self.store.all())
+
+    def test_bottle_names_list_preserved(self):
+        self.store.upsert(_state(bottle_names=["claude", "dev"]))
+        got = self.store.get("didericis", "bot-bottle", 17)
+        assert got is not None
+        self.assertEqual(["claude", "dev"], got.bottle_names)
+
+    def test_pr_number_nullable(self):
+        self.store.upsert(_state(pr_number=None))
+        got = self.store.get("didericis", "bot-bottle", 17)
+        assert got is not None
+        self.assertIsNone(got.pr_number)
+
+    def test_persists_across_store_instances(self):
+        self.store.upsert(_state())
+        reopened = SqliteForgeStateStore(self.store._db_path)  # pylint: disable=protected-access
+        self.assertEqual(_state(), reopened.get("didericis", "bot-bottle", 17))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_docker_launch_committed_image.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import contextlib
-import dataclasses
 import io
 import tempfile
 import unittest
@@ -17,7 +16,6 @@ from bot_bottle.backend.docker import launch as launch_mod
 from bot_bottle.backend.docker.bottle_plan import DockerBottlePlan
 from bot_bottle.egress import EgressPlan
 from bot_bottle.git_gate import GitGatePlan
-from bot_bottle.log import Die
 from bot_bottle.manifest import ManifestIndex
 
 
@@ -182,24 +180,6 @@ class TestLaunchCommittedImage(unittest.TestCase):
         built = self._run_launch(plan, committed_tag=None)
         self.assertEqual([_DEFAULT_IMAGE], built)
 
-    def test_cached_images_skip_build_when_present(self) -> None:
-        base = _plan(self._tmp)
-        plan = dataclasses.replace(
-            base,
-            spec=dataclasses.replace(base.spec, image_policy="cached"),
-        )
-        built = self._run_launch(plan, committed_tag=None, image_present=True)
-        self.assertEqual([], built)
-
-    def test_cached_images_die_when_agent_missing(self) -> None:
-        base = _plan(self._tmp)
-        plan = dataclasses.replace(
-            base,
-            spec=dataclasses.replace(base.spec, image_policy="cached"),
-        )
-        with self.assertRaises(Die):
-            self._run_launch(plan, committed_tag=None, image_present=False)
-
     def test_falls_back_to_build_when_committed_image_missing_from_daemon(self) -> None:
         plan = _plan(self._tmp)
         built = self._run_launch(

tests/unit/test_docker_util_image.py

@@ -9,7 +9,6 @@ from __future__ import annotations
 
 import subprocess
 import unittest
-from datetime import timezone
 from unittest.mock import patch
 
 from bot_bottle.backend.docker import util as docker_mod
@@ -55,51 +54,6 @@ class TestImageId(unittest.TestCase):
             self.assertIn("missing:tag", die.call_args.args[0])
 
 
-class TestImageCreatedAt(unittest.TestCase):
-    def test_parses_docker_timestamp_with_nanoseconds(self):
-        with patch.object(
-            docker_mod.subprocess, "run",
-            return_value=_ok(stdout="2026-07-06T15:33:47.123456789Z\n"),
-        ) as run:
-            created = docker_mod.image_created_at("bot-bottle-claude:latest")
-        self.assertEqual(2026, created.year)
-        self.assertEqual(123456, created.microsecond)
-        self.assertEqual(timezone.utc, created.tzinfo)
-        self.assertEqual(
-            ["docker", "image", "inspect", "--format", "{{.Created}}", "bot-bottle-claude:latest"],
-            run.call_args.args[0],
-        )
-
-    def test_dies_on_inspect_failure(self):
-        with patch.object(
-            docker_mod.subprocess, "run", return_value=_fail("No such image"),
-        ), patch.object(
-            docker_mod, "die", side_effect=SystemExit("die"),
-        ) as die:
-            with self.assertRaises(SystemExit):
-                docker_mod.image_created_at("missing:tag")
-        die.assert_called_once()
-        self.assertIn("missing:tag", die.call_args.args[0])
-
-    def test_dies_on_invalid_timestamp(self):
-        with patch.object(
-            docker_mod.subprocess, "run",
-            return_value=_ok(stdout="not-a-timestamp\n"),
-        ), patch.object(
-            docker_mod, "die", side_effect=SystemExit("die"),
-        ) as die:
-            with self.assertRaises(SystemExit):
-                docker_mod.image_created_at("some:tag")
-        die.assert_called_once()
-        self.assertIn("some:tag", die.call_args.args[0])
-
-    def test_parse_docker_timestamp_no_tzinfo_defaults_to_utc(self):
-        # A bare datetime with no tz offset should be treated as UTC.
-        dt = docker_mod._parse_docker_timestamp("2024-05-01T10:00:00.000000")
-        self.assertIsNotNone(dt.tzinfo)
-        self.assertEqual(timezone.utc, dt.tzinfo)
-
-
 class TestSave(unittest.TestCase):
     def test_save_runs_docker_save(self):
         with patch.object(

tests/unit/test_image_cache.py

@@ -1,81 +0,0 @@
-"""Unit: image_cache.py — check_stale / check_stale_path."""
-
-from __future__ import annotations
-
-import tempfile
-import unittest
-from datetime import datetime, timedelta, timezone
-from pathlib import Path
-from unittest.mock import patch
-
-from bot_bottle.image_cache import StaleImageError, check_stale, check_stale_path
-
-
-class TestCheckStale(unittest.TestCase):
-    def _run(self, threshold: int, age_days: float) -> None:
-        created = datetime.now(tz=timezone.utc) - timedelta(days=age_days)
-        with patch("bot_bottle.image_cache.ConfigStore") as cs:
-            cs.return_value.cached_image_stale_warning_days.return_value = threshold
-            check_stale("test image", created)
-
-    def test_negative_threshold_never_raises(self):
-        # Threshold < 0 means the check is disabled — always passes.
-        self._run(threshold=-1, age_days=9999)
-
-    def test_zero_threshold_raises_immediately(self):
-        # threshold=0 means any image is stale the moment it exists.
-        with self.assertRaises(StaleImageError):
-            self._run(threshold=0, age_days=0.1)
-
-    def test_within_threshold_does_not_raise(self):
-        # Age well under threshold — should pass silently.
-        self._run(threshold=7, age_days=2)
-
-    def test_at_threshold_does_not_raise(self):
-        # Exactly at the boundary is fine (<=, not <).
-        self._run(threshold=1, age_days=0.9999)
-
-    def test_exceeds_threshold_raises(self):
-        created = datetime.now(tz=timezone.utc) - timedelta(days=3)
-        with patch("bot_bottle.image_cache.ConfigStore") as cs:
-            cs.return_value.cached_image_stale_warning_days.return_value = 1
-            with self.assertRaises(StaleImageError) as ctx:
-                check_stale("agent image 'bot-bottle:latest'", created)
-        self.assertIn("agent image", str(ctx.exception))
-        self.assertIn("day(s) old", str(ctx.exception))
-
-    def test_naive_datetime_treated_as_utc(self):
-        # check_stale calls .astimezone(utc) on the input; naive datetimes
-        # that would be interpreted as local time should still work.
-        # We can't control the local tz in a unit test, so just ensure
-        # no exception is thrown for a very recent naive datetime.
-        naive_now = datetime(2099, 1, 1)  # far future, always "fresh"
-        with patch("bot_bottle.image_cache.ConfigStore") as cs:
-            cs.return_value.cached_image_stale_warning_days.return_value = 1
-            # Should not raise — the image is brand new.
-            check_stale("test image", naive_now)
-
-
-class TestCheckStalePath(unittest.TestCase):
-    def test_delegates_to_check_stale_with_mtime(self):
-        with tempfile.NamedTemporaryFile() as f:
-            path = Path(f.name)
-            with patch("bot_bottle.image_cache.check_stale") as mock_check:
-                check_stale_path("some artifact", path)
-            mock_check.assert_called_once()
-            label, dt = mock_check.call_args.args
-            self.assertEqual("some artifact", label)
-            self.assertIsInstance(dt, datetime)
-            self.assertIsNotNone(dt.tzinfo)
-
-    def test_raises_stale_for_old_file(self):
-        with tempfile.NamedTemporaryFile() as f:
-            path = Path(f.name)
-            with patch("bot_bottle.image_cache.ConfigStore") as cs:
-                cs.return_value.cached_image_stale_warning_days.return_value = 0
-                with self.assertRaises(StaleImageError):
-                    check_stale_path("cached artifact", path)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/test_macos_container_launch.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import dataclasses
 import unittest
 import tempfile
 from pathlib import Path
@@ -16,7 +15,6 @@ from bot_bottle.backend.macos_container import launch
 from bot_bottle.backend.macos_container.bottle_plan import MacosContainerBottlePlan
 from bot_bottle.egress import EgressPlan
 from bot_bottle.git_gate import GitGatePlan
-from bot_bottle.log import Die
 from bot_bottle.manifest import ManifestIndex
 
 _MANIFEST = ManifestIndex.from_json_obj({
@@ -83,7 +81,7 @@ def _plan(
         provisioned_env={"CODEX_HOME": "/run/codex-home"},
     )
     return cast(MacosContainerBottlePlan, SimpleNamespace(
-        spec=SimpleNamespace(image_policy="fresh"),
+        spec=SimpleNamespace(),
         manifest=_MANIFEST,
         stage_dir=stage_dir,
         slug="dev-abc",
@@ -294,7 +292,7 @@ class TestMacosContainerLaunchArgv(unittest.TestCase):
 
 def _build_plan(stage_dir: Path) -> MacosContainerBottlePlan:
     return MacosContainerBottlePlan(
-        spec=cast(BottleSpec, SimpleNamespace(image_policy="fresh")),
+        spec=cast(BottleSpec, SimpleNamespace()),
         manifest=_MANIFEST,
         stage_dir=stage_dir,
         git_gate_plan=cast(GitGatePlan, SimpleNamespace(upstreams=())),
@@ -367,82 +365,5 @@ class TestMacosContainerLaunchCommittedImage(unittest.TestCase):
         self.assertEqual("bot-bottle-agent:latest", calls[1][0])
 
 
-class TestMacosContainerLaunchCachedImages(unittest.TestCase):
-    def setUp(self):
-        self._tmp = tempfile.TemporaryDirectory()
-        self.stage_dir = Path(self._tmp.name)
-
-    def tearDown(self):
-        self._tmp.cleanup()
-
-    def _cached_plan(self) -> MacosContainerBottlePlan:
-        return dataclasses.replace(
-            _build_plan(self.stage_dir),
-            spec=cast(BottleSpec, SimpleNamespace(image_policy="cached")),
-        )
-
-    def test_cached_mode_dies_when_agent_image_missing(self) -> None:
-        plan = self._cached_plan()
-
-        def image_exists(ref: str) -> bool:  # pylint: disable=unused-argument
-            return False  # Nothing cached.
-
-        with patch.object(
-            launch, "read_committed_image", return_value="",
-        ), patch.object(
-            launch.container_mod, "image_exists", side_effect=image_exists,
-        ), patch.object(
-            launch, "die", side_effect=Die(),
-        ):
-            with self.assertRaises(Die):
-                launch._build_images(plan)
-
-    def test_cached_mode_dies_when_sidecar_image_missing(self) -> None:
-        plan = self._cached_plan()
-
-        def image_exists(ref: str) -> bool:
-            return ref == plan.image  # Agent present; sidecar missing.
-
-        with patch.object(
-            launch, "read_committed_image", return_value="",
-        ), patch.object(
-            launch.container_mod, "image_exists", side_effect=image_exists,
-        ), patch.object(
-            launch, "die", side_effect=Die(),
-        ):
-            with self.assertRaises(Die):
-                launch._build_images(plan)
-
-    def test_cached_mode_both_present_returns_unchanged_plan(self) -> None:
-        plan = self._cached_plan()
-        with patch.object(
-            launch, "read_committed_image", return_value="",
-        ), patch.object(
-            launch.container_mod, "image_exists", return_value=True,
-        ), patch.object(
-            launch.container_mod, "build_image",
-        ) as build, patch.object(launch, "info"):
-            result = launch._build_images(plan)
-
-        build.assert_not_called()
-        self.assertEqual(plan.image, result.image)
-
-    def test_committed_image_plus_cached_skips_sidecar_build(self) -> None:
-        plan = self._cached_plan()
-        with patch.object(
-            launch, "read_committed_image",
-            return_value="bot-bottle-committed-dev-abc:latest",
-        ), patch.object(
-            launch.container_mod, "image_exists", return_value=True,
-        ), patch.object(
-            launch.container_mod, "build_image",
-        ) as build, patch.object(launch, "info"):
-            result = launch._build_images(plan)
-
-        # In cached mode with a committed image, no builds should fire.
-        build.assert_not_called()
-        self.assertEqual("bot-bottle-committed-dev-abc:latest", result.image)
-
-
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_macos_container_util.py

@@ -273,71 +273,5 @@ resolver #2
             )
 
 
-class TestMacosContainerImageCreatedAt(unittest.TestCase):
-    def _ok(self, stdout: str) -> "util.subprocess.CompletedProcess":  # type: ignore
-        return util.subprocess.CompletedProcess(
-            args=[], returncode=0, stdout=stdout, stderr="",
-        )
-
-    def _fail(self, stderr: str = "no such image") -> "util.subprocess.CompletedProcess":  # type: ignore
-        return util.subprocess.CompletedProcess(
-            args=[], returncode=1, stdout="", stderr=stderr,
-        )
-
-    def test_parses_iso_timestamp_from_dict(self):
-        payload = '[{"created": "2025-06-01T12:00:00"}]'
-        with patch.object(util.subprocess, "run", return_value=self._ok(payload)):
-            dt = util.image_created_at("bot-bottle-agent:latest")
-        self.assertEqual(2025, dt.year)
-        self.assertEqual(6, dt.month)
-        self.assertEqual(1, dt.day)
-
-    def test_accepts_list_or_dict_input(self):
-        # Container CLI may return a list; we take the first element.
-        payload = '[{"created": "2024-01-15T08:30:00"}]'
-        with patch.object(util.subprocess, "run", return_value=self._ok(payload)):
-            dt = util.image_created_at("some-image:latest")
-        self.assertEqual(2024, dt.year)
-
-    def test_accepts_uppercase_Created_field(self):
-        payload = '[{"Created": "2024-03-20T10:00:00"}]'
-        with patch.object(util.subprocess, "run", return_value=self._ok(payload)):
-            dt = util.image_created_at("some-image:latest")
-        self.assertEqual(2024, dt.year)
-        self.assertEqual(3, dt.month)
-
-    def test_dies_on_nonzero_returncode(self):
-        with patch.object(util.subprocess, "run", return_value=self._fail("not found")), \
-             patch.object(util, "die", side_effect=SystemExit("die")) as die:
-            with self.assertRaises(SystemExit):
-                util.image_created_at("missing:tag")
-        die.assert_called_once()
-        self.assertIn("missing:tag", die.call_args.args[0])
-
-    def test_dies_on_malformed_json(self):
-        with patch.object(util.subprocess, "run", return_value=self._ok("not-json {")), \
-             patch.object(util, "die", side_effect=SystemExit("die")) as die:
-            with self.assertRaises(SystemExit):
-                util.image_created_at("some:tag")
-        die.assert_called_once()
-
-    def test_dies_when_no_created_field(self):
-        payload = '[{"id": "sha256:abc123"}]'
-        with patch.object(util.subprocess, "run", return_value=self._ok(payload)), \
-             patch.object(util, "die", side_effect=SystemExit("die")) as die:
-            with self.assertRaises(SystemExit):
-                util.image_created_at("some:tag")
-        die.assert_called_once()
-        self.assertIn("creation timestamp", die.call_args.args[0])
-
-    def test_dies_on_invalid_timestamp_format(self):
-        payload = '[{"created": "not-a-date"}]'
-        with patch.object(util.subprocess, "run", return_value=self._ok(payload)), \
-             patch.object(util, "die", side_effect=SystemExit("die")) as die:
-            with self.assertRaises(SystemExit):
-                util.image_created_at("some:tag")
-        die.assert_called_once()
-
-
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_sidecar_init.py

@@ -12,6 +12,7 @@ import os
 import signal
 import subprocess
 import sys
+import threading
 import time
 import unittest
 import warnings
@@ -476,6 +477,7 @@ class TestMainEndToEnd(unittest.TestCase):
 
     def _run(self, daemons_csv: str, send_signal: int | None,
              wait_before_signal: float = 0.4,
+             wait_for_output: tuple[str, ...] = (),
              overall_timeout: float = 6.0) -> tuple[int, str]:
         """Spawn sidecar_init.main() in a child process with the
         DAEMONS list patched to harmless `sleep 30` commands.
@@ -496,19 +498,53 @@ class TestMainEndToEnd(unittest.TestCase):
             stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
             env=env,
         )
+        collected: list[bytes] = []
+        ready = threading.Event()
+        need: set[str] = set(wait_for_output)
+
+        def _drain() -> None:
+            assert proc.stdout is not None
+            for raw in iter(proc.stdout.readline, b""):
+                collected.append(raw)
+                if need:
+                    text = raw.decode("utf-8", errors="replace")
+                    need.difference_update(p for p in list(need) if p in text)
+                    if not need:
+                        ready.set()
+            ready.set()  # also fires on EOF so the main thread isn't stuck
+
+        reader = threading.Thread(target=_drain, daemon=True)
+        reader.start()
+
         try:
             if send_signal is not None:
-                time.sleep(wait_before_signal)
+                if wait_for_output:
+                    # Wait until all expected lines have appeared, then
+                    # signal.  This eliminates the fixed-sleep race where
+                    # SIGTERM arrives before the subprocess installs its
+                    # handler on a slow CI runner.
+                    if not ready.wait(timeout=overall_timeout):
+                        proc.kill()
+                        reader.join(timeout=2.0)
+                        self.fail("timed out waiting for expected output lines")
+                else:
+                    time.sleep(wait_before_signal)
                 proc.send_signal(send_signal)
-            out_b, _ = proc.communicate(timeout=overall_timeout)
+            proc.wait(timeout=overall_timeout)
         except subprocess.TimeoutExpired:
             proc.kill()
-            out_b, _ = proc.communicate()
+            proc.wait()
+            reader.join(timeout=2.0)
             self.fail("sidecar_init main() did not exit before timeout")
-        return proc.returncode, out_b.decode("utf-8", errors="replace")
+
+        reader.join(timeout=2.0)
+        return proc.returncode, b"".join(collected).decode("utf-8", errors="replace")
 
     def test_sigterm_clean_shutdown(self):
-        rc, out = self._run("alpha,beta", signal.SIGTERM)
+        rc, out = self._run(
+            "alpha,beta", signal.SIGTERM,
+            wait_for_output=("starting alpha", "starting beta"),
+        )
         self.assertIn("starting alpha", out)
         self.assertIn("starting beta", out)
         self.assertIn("forwarding SIGTERM", out)

tests/unit/test_smolmachines_egress_apply.py

@@ -1,58 +0,0 @@
-from __future__ import annotations
-
-import unittest
-from unittest.mock import patch
-
-from bot_bottle.backend.egress_apply import EgressApplyError
-from bot_bottle.backend.smolmachines import egress_apply
-from bot_bottle.backend.smolmachines.smolvm import SmolvmRunResult
-
-
-class TestFetchCurrentRoutes(unittest.TestCase):
-    def test_reads_routes_from_sidecar_vm(self):
-        with patch.object(
-            egress_apply._smolvm,
-            "machine_exec",
-            return_value=SmolvmRunResult(0, "routes", ""),
-        ) as exec_:
-            self.assertEqual("routes", egress_apply.fetch_current_routes("dev-abc"))
-        exec_.assert_called_once_with(
-            "bot-bottle-sidecars-dev-abc",
-            ["cat", "/etc/egress/routes.yaml"],
-        )
-
-    def test_read_failure_raises_apply_error(self):
-        with patch.object(
-            egress_apply._smolvm,
-            "machine_exec",
-            return_value=SmolvmRunResult(1, "", "nope"),
-        ):
-            with self.assertRaises(EgressApplyError):
-                egress_apply.fetch_current_routes("dev-abc")
-
-
-class TestReload(unittest.TestCase):
-    def test_sends_hup_to_sidecar_init(self):
-        with patch.object(
-            egress_apply._smolvm,
-            "machine_exec",
-            return_value=SmolvmRunResult(0, "", ""),
-        ) as exec_:
-            egress_apply.SmolmachinesEgressApplicator()._signal_bundle_reload("dev-abc")
-        exec_.assert_called_once_with(
-            "bot-bottle-sidecars-dev-abc",
-            ["sh", "-c", "kill -HUP 1"],
-        )
-
-    def test_reload_failure_raises_apply_error(self):
-        with patch.object(
-            egress_apply._smolvm,
-            "machine_exec",
-            return_value=SmolvmRunResult(1, "", "nope"),
-        ):
-            with self.assertRaises(EgressApplyError):
-                egress_apply.SmolmachinesEgressApplicator()._signal_bundle_reload("dev-abc")
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/test_smolmachines_enumerate.py

@@ -1,66 +0,0 @@
-"""Unit: smolmachines active-agent enumeration."""
-
-from __future__ import annotations
-
-import json
-import subprocess
-import unittest
-from unittest.mock import patch
-
-from bot_bottle.backend.smolmachines import enumerate as _enumerate
-
-
-def _completed(
-    stdout: str,
-    returncode: int = 0,
-) -> subprocess.CompletedProcess:  # type: ignore[type-arg]
-    return subprocess.CompletedProcess(
-        args=[],
-        returncode=returncode,
-        stdout=stdout,
-        stderr="",
-    )
-
-
-class TestEnumerateActive(unittest.TestCase):
-    def test_skips_sidecar_vms(self):
-        machines = [
-            {"name": "bot-bottle-demo-abc12", "state": "running"},
-            {"name": "bot-bottle-sidecars-demo-abc12", "state": "running"},
-            {"name": "bot-bottle-stopped-xyz", "state": "stopped"},
-            {"name": "other", "state": "running"},
-        ]
-
-        class _Metadata:
-            agent_name = "demo"
-            started_at = "2026-07-09T00:00:00Z"
-            label = "Demo"
-            color = "green"
-
-        with patch(
-            "bot_bottle.backend.smolmachines.enumerate.subprocess.run",
-            return_value=_completed(json.dumps(machines)),
-        ), patch(
-            "bot_bottle.backend.smolmachines.enumerate._query_bundle_services",
-            return_value={"demo-abc12": ("egress",)},
-        ), patch(
-            "bot_bottle.backend.smolmachines.enumerate.read_metadata",
-            return_value=_Metadata(),
-        ) as read_metadata:
-            active = _enumerate.enumerate_active()
-
-        self.assertEqual(1, len(active))
-        self.assertEqual("demo-abc12", active[0].slug)
-        self.assertEqual(("egress",), active[0].services)
-        read_metadata.assert_called_once_with("demo-abc12")
-
-    def test_invalid_smolvm_output_returns_empty(self):
-        with patch(
-            "bot_bottle.backend.smolmachines.enumerate.subprocess.run",
-            return_value=_completed("not json"),
-        ):
-            self.assertEqual([], _enumerate.enumerate_active())
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/test_smolmachines_launch_image.py

@@ -187,54 +187,6 @@ class TestAgentFromPath(unittest.TestCase):
             dockerfile="/repo/Dockerfile",
         )
 
-    def test_cached_policy_uses_existing_artifact_without_build(self):
-        with tempfile.TemporaryDirectory(prefix="cached-smolmachine.") as tmp:
-            digest = "abcdef0123456789"
-            artifact = Path(tmp) / f"{digest}.smolmachine.smolmachine"
-            artifact.write_text("")
-            plan = SimpleNamespace(
-                slug="dev-abc12",
-                agent_image="bot-bottle-claude:latest",
-                spec=SimpleNamespace(image_policy="cached"),
-            )
-            with patch.object(
-                _launch_mod, "_SMOLMACHINE_CACHE_DIR", Path(tmp),
-            ), patch.object(
-                _launch_mod, "read_committed_image", return_value="",
-            ), patch.object(
-                _launch_mod.docker_mod, "image_exists", return_value=True,
-            ), patch.object(
-                _launch_mod.docker_mod, "image_id",
-                return_value=f"sha256:{digest}fffffffffffffffff",
-            ), patch.object(
-                _launch_mod, "_ensure_smolmachine",
-            ) as ensure:
-                result = _launch_mod._agent_from_path(cast(Any, plan))
-
-        self.assertEqual(artifact, result)
-        ensure.assert_not_called()
-
-    def test_cached_policy_dies_when_artifact_missing(self):
-        with tempfile.TemporaryDirectory(prefix="cached-smolmachine.") as tmp:
-            plan = SimpleNamespace(
-                slug="dev-abc12",
-                agent_image="bot-bottle-claude:latest",
-                spec=SimpleNamespace(image_policy="cached"),
-            )
-            with patch.object(
-                _launch_mod, "_SMOLMACHINE_CACHE_DIR", Path(tmp),
-            ), patch.object(
-                _launch_mod, "read_committed_image", return_value="",
-            ), patch.object(
-                _launch_mod.docker_mod, "image_exists", return_value=True,
-            ), patch.object(
-                _launch_mod.docker_mod, "image_id",
-                return_value="sha256:abcdef0123456789fffffffffffffffff",
-            ):
-                from bot_bottle.log import Die
-                with self.assertRaises(Die):
-                    _launch_mod._agent_from_path(cast(Any, plan))
-
 
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_smolmachines_port_forward.py

@@ -1,325 +0,0 @@
-from __future__ import annotations
-
-import json
-import socket
-import subprocess
-import threading
-import unittest
-from unittest.mock import MagicMock, patch
-
-from bot_bottle.backend.smolmachines.port_forward import (
-    ForwardSpec,
-    ForwarderHandle,
-    _CompletedProcess,
-    _Forwarder,
-    _pipe,
-    main,
-    start_forwarder,
-    stop_forwarder,
-)
-
-
-def _echo_server() -> tuple[socket.socket, int]:
-    listener = socket.create_server(("127.0.0.1", 0))
-    port = int(listener.getsockname()[1])
-
-    def run() -> None:
-        with listener:
-            conn, _ = listener.accept()
-            with conn:
-                while True:
-                    data = conn.recv(65536)
-                    if not data:
-                        return
-                    conn.sendall(data)
-
-    threading.Thread(target=run, daemon=True).start()
-    return listener, port
-
-
-class TestForwarderValidation(unittest.TestCase):
-    def test_empty_specs_returns_noop_handle(self):
-        handle = start_forwarder(())
-
-        self.assertEqual((), handle.forwards)
-        self.assertEqual(0, handle.process.poll())
-        stop_forwarder(handle)
-
-    def test_rejects_generic_localhost_listener(self):
-        with self.assertRaises(SystemExit):
-            start_forwarder((
-                ForwardSpec(
-                    label="egress",
-                    listen_host="127.0.0.1",
-                    listen_port=0,
-                    target_host="127.0.0.1",
-                    target_port=9099,
-                ),
-            ))
-
-    def test_rejects_wildcard_listener(self):
-        with self.assertRaises(SystemExit):
-            start_forwarder((
-                ForwardSpec(
-                    label="egress",
-                    listen_host="0.0.0.0",
-                    listen_port=0,
-                    target_host="127.0.0.1",
-                    target_port=9099,
-                ),
-            ))
-
-    def test_rejects_non_loopback_target(self):
-        with self.assertRaises(SystemExit):
-            start_forwarder((
-                ForwardSpec(
-                    label="egress",
-                    listen_host="127.0.0.16",
-                    listen_port=0,
-                    target_host="192.0.2.10",
-                    target_port=9099,
-                ),
-            ))
-
-    def test_rejects_invalid_ports(self):
-        with self.assertRaises(SystemExit):
-            start_forwarder((
-                ForwardSpec("bad-listen", "127.0.0.2", 70000, "127.0.0.1", 9099),
-            ))
-        with self.assertRaises(SystemExit):
-            start_forwarder((
-                ForwardSpec("bad-target", "127.0.0.2", 0, "127.0.0.1", 0),
-            ))
-
-    def test_completed_process_methods_are_noops(self):
-        proc = _CompletedProcess()
-
-        proc.terminate()
-        proc.kill()
-
-        self.assertEqual(0, proc.poll())
-        self.assertEqual(0, proc.wait(timeout=1))
-
-
-class _FakeStdout:
-    def __init__(self, line: str):
-        self.line = line
-        self.closed = False
-
-    def readline(self) -> str:
-        return self.line
-
-    def close(self) -> None:
-        self.closed = True
-
-
-class TestForwarderProcess(unittest.TestCase):
-    def test_start_parses_ready_payload(self):
-        payload = {
-            "forwards": [{
-                "label": "egress",
-                "listen_host": "127.0.0.2",
-                "listen_port": 61000,
-                "target_host": "127.0.0.1",
-                "target_port": 55000,
-            }],
-        }
-        proc = MagicMock()
-        proc.stdout = _FakeStdout(json.dumps(payload) + "\n")
-
-        with patch(
-            "bot_bottle.backend.smolmachines.port_forward.subprocess.Popen",
-            return_value=proc,
-        ) as popen:
-            handle = start_forwarder((
-                ForwardSpec("egress", "127.0.0.2", 0, "127.0.0.1", 55000),
-            ))
-
-        self.assertIs(proc, handle.process)
-        self.assertEqual(61000, handle.forwards[0].listen_port)
-        self.assertTrue(proc.stdout.closed)
-        argv = popen.call_args.args[0]
-        self.assertIn("--spec-json", argv)
-
-    def test_start_dies_when_helper_exits_before_ready(self):
-        proc = MagicMock()
-        proc.stdout = _FakeStdout("")
-
-        with patch(
-            "bot_bottle.backend.smolmachines.port_forward.subprocess.Popen",
-            return_value=proc,
-        ):
-            with self.assertRaises(SystemExit):
-                start_forwarder((
-                    ForwardSpec("egress", "127.0.0.2", 0, "127.0.0.1", 55000),
-                ))
-
-        proc.terminate.assert_called_once()
-        proc.wait.assert_called_once_with(timeout=5)
-
-    def test_start_dies_on_invalid_ready_payload(self):
-        proc = MagicMock()
-        proc.stdout = _FakeStdout('{"wrong": []}\n')
-
-        with patch(
-            "bot_bottle.backend.smolmachines.port_forward.subprocess.Popen",
-            return_value=proc,
-        ):
-            with self.assertRaises(SystemExit):
-                start_forwarder((
-                    ForwardSpec("egress", "127.0.0.2", 0, "127.0.0.1", 55000),
-                ))
-
-        proc.terminate.assert_called_once()
-        proc.wait.assert_called_once_with(timeout=5)
-
-    def test_stop_kills_process_after_timeout(self):
-        proc = MagicMock()
-        proc.poll.return_value = None
-        proc.wait.side_effect = [subprocess.TimeoutExpired("cmd", 5), 0]
-
-        stop_forwarder(ForwarderHandle(process=proc, forwards=()))
-
-        proc.terminate.assert_called_once()
-        proc.kill.assert_called_once()
-        self.assertEqual(2, proc.wait.call_count)
-
-
-class TestForwarding(unittest.TestCase):
-    def test_forwards_bytes_both_directions(self):
-        try:
-            probe = socket.create_server(("127.0.0.2", 0))
-        except OSError:
-            self.skipTest("127.0.0.2 is not bindable on this host")
-        else:
-            probe.close()
-        _listener, target_port = _echo_server()
-        handle = start_forwarder((
-            ForwardSpec(
-                label="egress",
-                listen_host="127.0.0.2",
-                listen_port=0,
-                target_host="127.0.0.1",
-                target_port=target_port,
-            ),
-        ))
-        try:
-            bound = handle.forwards[0]
-            with socket.create_connection((bound.listen_host, bound.listen_port)) as sock:
-                sock.sendall(b"hello")
-                self.assertEqual(b"hello", sock.recv(5))
-        finally:
-            stop_forwarder(handle)
-
-
-class TestForwarderInProcess(unittest.TestCase):
-    def test_forwarder_serves_and_stops_in_process(self):
-        _listener, target_port = _echo_server()
-        forwarder = _Forwarder((
-            ForwardSpec("egress", "127.0.0.2", 0, "127.0.0.1", target_port),
-        ))
-        forwarder.start()
-        thread = threading.Thread(target=forwarder.serve, daemon=True)
-        thread.start()
-        try:
-            bound = forwarder.bound[0]
-            with socket.create_connection((bound.listen_host, bound.listen_port)) as sock:
-                sock.sendall(b"ping")
-                self.assertEqual(b"ping", sock.recv(4))
-        finally:
-            forwarder.stop()
-            thread.join(timeout=2)
-
-        self.assertFalse(thread.is_alive())
-
-    def test_forwarder_logs_target_connect_failure(self):
-        forwarder = _Forwarder((
-            ForwardSpec("egress", "127.0.0.2", 0, "127.0.0.1", 1),
-        ))
-        forwarder.start()
-        thread = threading.Thread(target=forwarder.serve, daemon=True)
-        thread.start()
-        try:
-            bound = forwarder.bound[0]
-            with patch("bot_bottle.backend.smolmachines.port_forward.warn") as warn:
-                with socket.create_connection((bound.listen_host, bound.listen_port)):
-                    pass
-                for _ in range(100):
-                    if warn.called:
-                        break
-                    threading.Event().wait(0.01)
-            self.assertTrue(warn.called)
-        finally:
-            forwarder.stop()
-            thread.join(timeout=2)
-
-    def test_pipe_stops_when_recv_fails(self):
-        src, dst = socket.socketpair()
-        src.close()
-        try:
-            _pipe(src, dst)
-        finally:
-            dst.close()
-
-    def test_pipe_stops_when_send_fails(self):
-        src, src_peer = socket.socketpair()
-        _dst_peer, dst = socket.socketpair()
-        dst.close()
-        try:
-            src_peer.sendall(b"hello")
-            src_peer.shutdown(socket.SHUT_WR)
-            _pipe(src, dst)
-        finally:
-            src.close()
-            src_peer.close()
-            _dst_peer.close()
-
-
-class TestMain(unittest.TestCase):
-    def test_main_starts_serves_and_stops_forwarder(self):
-        calls: list[str] = []
-        handlers = []
-
-        class FakeForwarder:
-            def __init__(self, specs):  # type: ignore[no-untyped-def]
-                self.specs = specs
-                self.bound = specs
-
-            def start(self) -> None:
-                calls.append("start")
-
-            def serve(self) -> None:
-                calls.append("serve")
-
-            def stop(self) -> None:
-                calls.append("stop")
-
-        def record_signal(_signum, handler):  # type: ignore[no-untyped-def]
-            handlers.append(handler)
-
-        spec = ForwardSpec("egress", "127.0.0.2", 0, "127.0.0.1", 9099)
-        with patch(
-            "bot_bottle.backend.smolmachines.port_forward._Forwarder",
-            FakeForwarder,
-        ), patch(
-            "bot_bottle.backend.smolmachines.port_forward.signal.signal",
-            side_effect=record_signal,
-        ), patch("builtins.print") as print_mock:
-            self.assertEqual(
-                0,
-                main(("--spec-json", json.dumps([{
-                    "label": spec.label,
-                    "listen_host": spec.listen_host,
-                    "listen_port": spec.listen_port,
-                    "target_host": spec.target_host,
-                    "target_port": spec.target_port,
-                }]))),
-            )
-            handlers[0](15, None)
-
-        self.assertEqual(["start", "serve", "stop", "stop"], calls)
-        self.assertIn("forwards", print_mock.call_args.args[0])
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/test_smolmachines_provision.py

@@ -9,7 +9,6 @@ from __future__ import annotations
 import subprocess
 import tempfile
 import unittest
-from contextlib import ExitStack
 from dataclasses import replace
 from pathlib import Path
 from unittest.mock import MagicMock, patch
@@ -28,7 +27,6 @@ from bot_bottle.backend.smolmachines.bottle_plan import (
     SmolmachinesBottlePlan,
 )
 from bot_bottle.backend.smolmachines import launch as _launch
-from bot_bottle.backend.smolmachines import port_forward as _forward
 from bot_bottle.backend.smolmachines.launch import _bundle_launch_spec
 from bot_bottle.backend.util import AGENT_CA_PATH
 from bot_bottle.egress import EgressPlan, EgressRoute
@@ -434,7 +432,12 @@ class TestBundleLaunchSpec(unittest.TestCase):
 
     def test_canary_env_visible_to_smolvm_guest(self):
         plan = _plan(canary=True)
-        stamped = _launch._discover_urls(plan, "127.0.0.16", {9099: 65000})
+        with patch.object(
+            _launch._bundle,
+            "bundle_host_port",
+            return_value="65000",
+        ):
+            stamped = _launch._discover_urls(plan, "127.0.0.16")
 
         self.assertEqual(
             "fake-canary-value",
@@ -503,111 +506,23 @@ class TestProvisionGitUser(unittest.TestCase):
         self.assertIn("bot@example.com", calls[0][0])
 
 
-class TestLaunchResourceWiring(unittest.TestCase):
+class TestProxyHost(unittest.TestCase):
-    def test_allocate_resources_uses_loopback_alias_and_bundle_name(self):
+    """_proxy_host returns the bridge gateway on Linux and the loopback
+    alias on other platforms."""
+
+    def test_linux_returns_bundle_gateway(self):
         plan = _plan()
-        with patch(
+        with patch("bot_bottle.backend.smolmachines.launch.platform.system",
-            "bot_bottle.backend.smolmachines.launch._loopback.ensure_pool",
+                   return_value="Linux"):
-        ) as ensure_pool, patch(
+            result = _launch._proxy_host(plan, "127.0.0.16")
-            "bot_bottle.backend.smolmachines.launch._loopback.allocate",
+        self.assertEqual(plan.bundle_gateway, result)
-            return_value="127.0.0.16",
-        ) as allocate:
-            loopback_ip, network = _launch._allocate_resources(plan, ExitStack())
 
-        ensure_pool.assert_called_once_with()
+    def test_non_linux_returns_loopback(self):
-        allocate.assert_called_once_with("demo-abc12")
-        self.assertEqual("127.0.0.16", loopback_ip)
-        self.assertEqual("bot-bottle-bundle-demo-abc12", network)
-
-    def test_start_bundle_wraps_raw_vm_ports_with_forwarder_ports(self):
-        plan = _plan(supervise=True)
-        plan = replace(
-            plan,
-            git_gate_plan=replace(
-                plan.git_gate_plan,
-                upstreams=(GitGateUpstream(
-                    name="bot-bottle",
-                    upstream_url="ssh://git@host/repo.git",
-                    upstream_host="host",
-                    upstream_port="22",
-                    identity_file="/tmp/key",
-                    known_host_key="",
-                ),),
-            ),
-        )
-        stack = MagicMock(spec=ExitStack)
-        raw_launch = MagicMock(raw_ports={9099: 55001, 9420: 55002, 9100: 55003})
-        handle = _forward.ForwarderHandle(
-            process=MagicMock(),
-            forwards=(
-                _forward.ForwardSpec("egress", "127.0.0.16", 65001, "127.0.0.1", 55001),
-                _forward.ForwardSpec("git-http", "127.0.0.16", 65002, "127.0.0.1", 55002),
-                _forward.ForwardSpec("supervise", "127.0.0.16", 65003, "127.0.0.1", 55003),
-            ),
-        )
-
-        with patch(
-            "bot_bottle.backend.smolmachines.launch._provision_git_gate_keys",
-            return_value=plan,
-        ), patch(
-            "bot_bottle.backend.smolmachines.launch._ensure_smolmachine",
-            return_value=Path("/cache/sidecar.smolmachine"),
-        ) as ensure, patch(
-            "bot_bottle.backend.smolmachines.launch._bundle.start_bundle_vm",
-            return_value=raw_launch,
-        ) as start_vm, patch(
-            "bot_bottle.backend.smolmachines.launch._forward.start_forwarder",
-            return_value=handle,
-        ) as start_forwarder:
-            stamped = _launch._start_bundle(plan, "net", "127.0.0.16", stack)
-
-        ensure.assert_called_once()
-        start_vm.assert_called_once()
-        self.assertEqual(Path("/cache/sidecar.smolmachine"), start_vm.call_args.kwargs["from_path"])
-        specs = start_forwarder.call_args.args[0]
-        self.assertEqual(
-            (
-                _forward.ForwardSpec("egress", "127.0.0.16", 0, "127.0.0.1", 55001),
-                _forward.ForwardSpec("git-http", "127.0.0.16", 0, "127.0.0.1", 55002),
-                _forward.ForwardSpec("supervise", "127.0.0.16", 0, "127.0.0.1", 55003),
-            ),
-            specs,
-        )
-        self.assertEqual("http://127.0.0.16:65001", stamped.agent_proxy_url)
-        self.assertEqual("127.0.0.16:65002", stamped.agent_git_gate_host)
-        self.assertEqual("http://127.0.0.16:65003/", stamped.agent_supervise_url)
-        self.assertEqual(2, stack.callback.call_count)
-
-    def test_init_vm_repairs_ownership_then_waits_for_exec(self):
         plan = _plan()
-        with patch(
+        with patch("bot_bottle.backend.smolmachines.launch.platform.system",
-            "bot_bottle.backend.smolmachines.launch._smolvm.machine_exec",
+                   return_value="Darwin"):
-        ) as machine_exec, patch(
+            result = _launch._proxy_host(plan, "127.0.0.16")
-            "bot_bottle.backend.smolmachines.launch._smolvm.wait_exec_ready",
+        self.assertEqual("127.0.0.16", result)
-        ) as wait_exec_ready:
-            _launch._init_vm(plan)
-
-        machine_exec.assert_called_once()
-        argv = machine_exec.call_args.args[1]
-        self.assertEqual(["sh", "-c"], argv[:2])
-        self.assertIn("chown -R node:node /home/node", argv[2])
-        wait_exec_ready.assert_called_once_with(plan.machine_name)
-
-
-class TestPortLabels(unittest.TestCase):
-    def test_known_and_dynamic_port_labels_round_trip(self):
-        for port, label in (
-            (9099, "egress"),
-            (9420, "git-http"),
-            (9100, "supervise"),
-            (12345, "port-12345"),
-        ):
-            self.assertEqual(label, _launch._label_for_port(port))
-            self.assertEqual(port, _launch._port_for_label(label))
-
-    def test_unknown_label_is_rejected(self):
-        with self.assertRaises(ValueError):
-            _launch._port_for_label("sidecar")
 
 
 class TestDiscoverUrls(unittest.TestCase):
@@ -629,20 +544,14 @@ class TestDiscoverUrls(unittest.TestCase):
                 ),),
             ),
         )
-        stamped = _launch._discover_urls(
+        with patch.object(_launch._bundle, "bundle_host_port", return_value="9420"):
-            plan,
+            stamped = _launch._discover_urls(plan, "127.0.0.16")
-            "127.0.0.16",
+        self.assertEqual("127.0.0.16:9420", stamped.agent_git_gate_host)
-            {9099: 65000, 9420: 65001},
-        )
-        self.assertEqual("127.0.0.16:65001", stamped.agent_git_gate_host)
 
     def test_supervise_url_set_when_supervise_present(self):
         plan = _plan(supervise=True)
-        stamped = _launch._discover_urls(
+        with patch.object(_launch._bundle, "bundle_host_port", return_value="55556"):
-            plan,
+            stamped = _launch._discover_urls(plan, "127.0.0.16")
-            "127.0.0.16",
-            {9099: 65000, 9100: 55556},
-        )
         self.assertEqual("http://127.0.0.16:55556/", stamped.agent_supervise_url)
 
 

tests/unit/test_smolmachines_sidecar_bundle.py

@@ -14,16 +14,13 @@ from unittest.mock import patch
 
 from bot_bottle.backend.smolmachines.sidecar_bundle import (
     BundleLaunchSpec,
-    allocate_raw_host_ports,
     bundle_container_name,
     bundle_network_name,
     create_bundle_network,
     ensure_bundle_image,
-    start_bundle_vm,
     remove_bundle_network,
     start_bundle,
     stop_bundle,
-    stop_bundle_vm,
 )
 
 
@@ -203,66 +200,6 @@ class TestEnsureBundleImage(unittest.TestCase):
         self.assertEqual("Dockerfile.sidecars", kwargs["dockerfile"])
 
 
-class TestStartBundleVm(unittest.TestCase):
-    def test_allocate_raw_host_ports_returns_bindable_ports(self):
-        raw_ports = allocate_raw_host_ports((9099, 9420))
-
-        self.assertEqual({9099, 9420}, set(raw_ports))
-        for host_port in raw_ports.values():
-            self.assertIsInstance(host_port, int)
-            self.assertGreater(host_port, 0)
-        self.assertNotEqual(raw_ports[9099], raw_ports[9420])
-
-    def test_creates_sidecar_vm_with_ports_volumes_and_env(self):
-        calls: list[tuple[str, tuple[object, ...], dict[str, object]]] = []
-
-        def record(name):  # type: ignore
-            def inner(*args, **kwargs):  # type: ignore
-                calls.append((name, args, kwargs))
-            return inner
-
-        with patch(
-            "bot_bottle.backend.smolmachines.sidecar_bundle.allocate_raw_host_ports",
-            return_value={9099: 55001, 9420: 55002},
-        ), patch(
-            "bot_bottle.backend.smolmachines.sidecar_bundle._smolvm.machine_create",
-            side_effect=record("create"),
-        ), patch(
-            "bot_bottle.backend.smolmachines.sidecar_bundle._smolvm.machine_start",
-            side_effect=record("start"),
-        ), patch(
-            "bot_bottle.backend.smolmachines.sidecar_bundle._smolvm.wait_exec_ready",
-            side_effect=record("wait"),
-        ):
-            launch = start_bundle_vm(
-                _spec(
-                    daemons_csv="egress,git-http",
-                    environment=("FOO=bar", "TOKEN"),
-                    volumes=(("/host/routes", "/etc/egress", True),),
-                    ports_to_publish=(9099, 9420),
-                ),
-                from_path=Path("/cache/sidecar.smolmachine"),
-                host_env={"TOKEN": "secret"},
-            )
-
-        self.assertEqual({9099: 55001, 9420: 55002}, launch.raw_ports)
-        create = calls[0]
-        self.assertEqual("create", create[0])
-        self.assertEqual(("bot-bottle-sidecars-demo-abc12",), create[1])
-        self.assertEqual(Path("/cache/sidecar.smolmachine"), create[2]["from_path"])
-        self.assertTrue(create[2]["net"])
-        self.assertEqual(((55001, 9099), (55002, 9420)), create[2]["ports"])
-        self.assertEqual((("/host/routes", "/etc/egress", True),), create[2]["volumes"])
-        self.assertEqual(
-            {
-                "BOT_BOTTLE_SIDECAR_DAEMONS": "egress,git-http",
-                "FOO": "bar",
-                "TOKEN": "secret",
-            },
-            create[2]["env"],
-        )
-
-
 class TestStopBundle(unittest.TestCase):
     def _patch_run(self, **kwargs):  # type: ignore
         return patch(
@@ -285,38 +222,5 @@ class TestStopBundle(unittest.TestCase):
             stop_bundle("demo-abc12")  # no raise
 
 
-class TestStopBundleVm(unittest.TestCase):
-    def test_stops_then_deletes_sidecar_vm(self):
-        with patch(
-            "bot_bottle.backend.smolmachines.sidecar_bundle._smolvm.machine_stop",
-        ) as stop, patch(
-            "bot_bottle.backend.smolmachines.sidecar_bundle._smolvm.machine_delete",
-        ) as delete:
-            stop_bundle_vm("demo-abc12")
-        stop.assert_called_once_with("bot-bottle-sidecars-demo-abc12")
-        delete.assert_called_once_with("bot-bottle-sidecars-demo-abc12")
-
-    def test_stop_and_delete_errors_are_warnings(self):
-        from bot_bottle.backend.smolmachines.smolvm import SmolvmError
-        result = subprocess.CompletedProcess(
-            args=[],
-            returncode=1,
-            stdout="",
-            stderr="failed",
-        )
-        with patch(
-            "bot_bottle.backend.smolmachines.sidecar_bundle._smolvm.machine_stop",
-            side_effect=SmolvmError(["smolvm", "machine", "stop"], result),
-        ), patch(
-            "bot_bottle.backend.smolmachines.sidecar_bundle._smolvm.machine_delete",
-            side_effect=SmolvmError(["smolvm", "machine", "delete"], result),
-        ), patch(
-            "bot_bottle.backend.smolmachines.sidecar_bundle.warn",
-        ) as warn:
-            stop_bundle_vm("demo-abc12")
-
-        self.assertEqual(2, warn.call_count)
-
-
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_smolmachines_smolvm.py

@@ -106,22 +106,6 @@ class TestArgvShapes(unittest.TestCase):
         self.assertIn("--name", argv)
         self.assertIn("agent-xyz", argv)
 
-    def test_machine_create_with_net_ports_and_volumes(self):
-        with self._patch_run() as m:
-            machine_create(
-                "sidecar-xyz",
-                from_path=Path("/stage/sidecar.smolmachine"),
-                net=True,
-                ports=((55000, 9099),),
-                volumes=(("/host/routes", "/etc/egress", True),),
-            )
-        argv = m.call_args.args[0]
-        self.assertIn("--net", argv)
-        self.assertIn("-p", argv)
-        self.assertIn("55000:9099", argv)
-        self.assertIn("-v", argv)
-        self.assertIn("/host/routes:/etc/egress:ro", argv)
-
     def test_machine_create_omits_net_when_no_allow_cidrs(self):
         with self._patch_run() as m:
             machine_create("agent-xyz", from_path=Path("/x.smolmachine"))

tests/unit/test_stale_checks.py

@@ -1,302 +0,0 @@
-"""Unit: stale-image check functions across backends, and the
-BottleBackend.launch template method (skip_stale flag).
-
-No real images or containers are used — all Docker/container/smolmachine
-calls are mocked at the module boundary."""
-
-from __future__ import annotations
-
-import tempfile
-import unittest
-from pathlib import Path
-from types import SimpleNamespace
-from typing import Any, cast
-from unittest.mock import MagicMock, patch
-
-
-def _bottle_cm(bottle: Any) -> MagicMock:
-    """Return a mock context manager that yields `bottle`."""
-    cm = MagicMock()
-    cm.__enter__ = MagicMock(return_value=bottle)
-    cm.__exit__ = MagicMock(return_value=False)
-    return cm
-
-
-# ---------------------------------------------------------------------------
-# BottleBackend.launch template — _image_stale_checks + skip_stale
-# ---------------------------------------------------------------------------
-
-class TestBottleBackendLaunchTemplate(unittest.TestCase):
-    """Verify the concrete launch() method on BottleBackend calls
-    _image_stale_checks unless skip_stale=True, then delegates to _launch_impl."""
-
-    def _make_backend(self) -> Any:
-        from bot_bottle.backend.docker.backend import DockerBottleBackend
-        return DockerBottleBackend()
-
-    def test_stale_checks_called_by_default(self) -> None:
-        backend = self._make_backend()
-        plan = cast(Any, SimpleNamespace())
-        bottle = MagicMock()
-        with patch.object(
-            backend, "_image_stale_checks",
-        ) as stale_mock, patch.object(
-            backend, "_launch_impl",
-            return_value=_bottle_cm(bottle),
-        ):
-            with backend.launch(plan):
-                pass
-        stale_mock.assert_called_once_with(plan)
-
-    def test_skip_stale_bypasses_stale_checks(self) -> None:
-        backend = self._make_backend()
-        plan = cast(Any, SimpleNamespace())
-        bottle = MagicMock()
-        with patch.object(
-            backend, "_image_stale_checks",
-        ) as stale_mock, patch.object(
-            backend, "_launch_impl",
-            return_value=_bottle_cm(bottle),
-        ):
-            with backend.launch(plan, skip_stale=True):
-                pass
-        stale_mock.assert_not_called()
-
-    def test_noop_default_image_stale_checks(self) -> None:
-        from bot_bottle.backend.docker.backend import DockerBottleBackend
-        from bot_bottle.backend import BottleBackend
-        backend = DockerBottleBackend()
-        # Call the base-class _image_stale_checks directly to verify it's a no-op.
-        BottleBackend._image_stale_checks(backend, cast(Any, SimpleNamespace()))  # type: ignore[arg-type]
-
-
-# ---------------------------------------------------------------------------
-# Docker backend stale_checks
-# ---------------------------------------------------------------------------
-
-class TestDockerStaleChecks(unittest.TestCase):
-    def _plan(self, policy: str = "cached", slug: str = "dev-abc") -> Any:
-        spec = SimpleNamespace(image_policy=policy)
-        provision = SimpleNamespace(image="bot-bottle-agent:latest")
-        return cast(Any, SimpleNamespace(
-            spec=spec,
-            slug=slug,
-            image="bot-bottle-agent:latest",
-            agent_provision=provision,
-        ))
-
-    def test_fresh_policy_is_noop(self) -> None:
-        from bot_bottle.backend.docker import launch as mod
-        with patch.object(mod, "read_committed_image") as rci, \
-             patch.object(mod, "check_stale") as cs:
-            mod.stale_checks(self._plan("fresh"))
-        rci.assert_not_called()
-        cs.assert_not_called()
-
-    def test_committed_image_present_checks_only_committed(self) -> None:
-        from bot_bottle.backend.docker import launch as mod
-        from datetime import datetime, timezone
-        ts = datetime(2025, 1, 1, tzinfo=timezone.utc)
-        with patch.object(mod, "read_committed_image", return_value="committed:latest"), \
-             patch.object(mod.docker_mod, "image_exists", return_value=True), \
-             patch.object(mod.docker_mod, "image_created_at", return_value=ts), \
-             patch.object(mod, "check_stale") as cs:
-            mod.stale_checks(self._plan())
-        cs.assert_called_once()
-        self.assertIn("committed:latest", cs.call_args.args[0])
-
-    def test_no_committed_image_checks_agent_and_sidecar(self) -> None:
-        from bot_bottle.backend.docker import launch as mod
-        from datetime import datetime, timezone
-        ts = datetime(2025, 1, 1, tzinfo=timezone.utc)
-        with patch.object(mod, "read_committed_image", return_value=""), \
-             patch.object(mod.docker_mod, "image_exists", return_value=True), \
-             patch.object(mod.docker_mod, "image_created_at", return_value=ts), \
-             patch.object(mod, "check_stale") as cs:
-            mod.stale_checks(self._plan())
-        # Should have been called for both agent and sidecar images.
-        self.assertEqual(2, cs.call_count)
-
-    def test_image_not_present_skips_check(self) -> None:
-        from bot_bottle.backend.docker import launch as mod
-        with patch.object(mod, "read_committed_image", return_value=""), \
-             patch.object(mod.docker_mod, "image_exists", return_value=False), \
-             patch.object(mod, "check_stale") as cs:
-            mod.stale_checks(self._plan())
-        cs.assert_not_called()
-
-    def test_only_sidecar_missing_checks_only_agent(self) -> None:
-        from bot_bottle.backend.docker import launch as mod
-        from datetime import datetime, timezone
-        ts = datetime(2025, 1, 1, tzinfo=timezone.utc)
-        plan = self._plan()
-
-        def image_exists(ref: str) -> bool:
-            return ref == plan.image  # Only agent present; sidecar missing.
-
-        with patch.object(mod, "read_committed_image", return_value=""), \
-             patch.object(mod.docker_mod, "image_exists", side_effect=image_exists), \
-             patch.object(mod.docker_mod, "image_created_at", return_value=ts), \
-             patch.object(mod, "check_stale") as cs:
-            mod.stale_checks(plan)
-        self.assertEqual(1, cs.call_count)
-        self.assertIn(plan.image, cs.call_args.args[0])
-
-    def test_backend_image_stale_checks_delegates(self) -> None:
-        from bot_bottle.backend.docker.backend import DockerBottleBackend
-        from bot_bottle.backend.docker import launch as mod
-        backend = DockerBottleBackend()
-        plan = self._plan()
-        with patch.object(mod, "stale_checks") as sc:
-            backend._image_stale_checks(plan)  # type: ignore[arg-type]
-        sc.assert_called_once_with(plan)
-
-
-# ---------------------------------------------------------------------------
-# smolmachines backend stale_checks
-# ---------------------------------------------------------------------------
-
-class TestSmolmachinesStaleChecks(unittest.TestCase):
-    def _plan(self, policy: str = "cached") -> Any:
-        return cast(Any, SimpleNamespace(
-            spec=SimpleNamespace(image_policy=policy),
-            slug="dev-abc",
-            agent_image="bot-bottle-claude:latest",
-        ))
-
-    def test_fresh_policy_is_noop(self) -> None:
-        from bot_bottle.backend.smolmachines import launch as mod
-        with patch.object(mod, "read_committed_image") as rci, \
-             patch.object(mod, "check_stale_path") as csp:
-            mod.stale_checks(self._plan("fresh"))
-        rci.assert_not_called()
-        csp.assert_not_called()
-
-    def test_committed_artifact_found_checks_it(self) -> None:
-        from bot_bottle.backend.smolmachines import launch as mod
-        with tempfile.NamedTemporaryFile(suffix=".smolmachine") as f:
-            committed_path = f.name
-            with patch.object(mod, "read_committed_image", return_value=committed_path), \
-                 patch.object(mod.docker_mod, "image_exists", return_value=False), \
-                 patch.object(mod, "check_stale_path") as csp:
-                mod.stale_checks(self._plan())
-        csp.assert_called_once()
-        self.assertIn("agent smolmachine", csp.call_args.args[0])
-
-    def test_no_committed_agent_artifact_in_cache_is_checked(self) -> None:
-        from bot_bottle.backend.smolmachines import launch as mod
-        digest = "abcdef0123456789"
-        with tempfile.TemporaryDirectory() as tmp:
-            artifact = Path(tmp) / f"{digest}.smolmachine.smolmachine"
-            artifact.write_text("")
-            with patch.object(mod, "_SMOLMACHINE_CACHE_DIR", Path(tmp)), \
-                 patch.object(mod, "read_committed_image", return_value=""), \
-                 patch.object(mod.docker_mod, "image_exists", return_value=True), \
-                 patch.object(
-                     mod.docker_mod, "image_id",
-                     return_value=f"sha256:{digest}ffffffffffffffff",
-                 ), \
-                 patch.object(mod, "check_stale_path") as csp:
-                mod.stale_checks(self._plan())
-        # At least the agent artifact check ran.
-        self.assertGreaterEqual(csp.call_count, 1)
-
-    def test_sidecar_artifact_in_cache_is_checked(self) -> None:
-        from bot_bottle.backend.smolmachines import launch as mod
-        sidecar_digest = "fedcba9876543210"
-        with tempfile.TemporaryDirectory() as tmp:
-            sidecar_artifact = (
-                Path(tmp) / f"{sidecar_digest}.smolmachine.smolmachine"
-            )
-            sidecar_artifact.write_text("")
-
-            def image_exists(ref: str) -> bool:  # pylint: disable=unused-argument
-                return True
-
-            def image_id(ref: str) -> str:
-                if ref == mod._bundle.SIDECAR_BUNDLE_IMAGE:  # type: ignore[attr-defined]
-                    return f"sha256:{sidecar_digest}ffffffff"
-                return "sha256:0000000000000000ffffffff"
-
-            with patch.object(mod, "_SMOLMACHINE_CACHE_DIR", Path(tmp)), \
-                 patch.object(mod, "read_committed_image", return_value=""), \
-                 patch.object(mod.docker_mod, "image_exists", side_effect=image_exists), \
-                 patch.object(mod.docker_mod, "image_id", side_effect=image_id), \
-                 patch.object(mod, "check_stale_path") as csp:
-                mod.stale_checks(self._plan())
-        sidecar_calls = [c for c in csp.call_args_list if "sidecar" in c.args[0]]
-        self.assertGreaterEqual(len(sidecar_calls), 1)
-
-    def test_backend_image_stale_checks_delegates(self) -> None:
-        from bot_bottle.backend.smolmachines.backend import SmolmachinesBottleBackend
-        from bot_bottle.backend.smolmachines import launch as mod
-        backend = SmolmachinesBottleBackend()
-        plan = self._plan()
-        with patch.object(mod, "stale_checks") as sc:
-            backend._image_stale_checks(plan)  # type: ignore[arg-type]
-        sc.assert_called_once_with(plan)
-
-
-# ---------------------------------------------------------------------------
-# macOS container backend stale_checks
-# ---------------------------------------------------------------------------
-
-class TestMacosContainerStaleChecks(unittest.TestCase):
-    def _plan(self, policy: str = "cached", slug: str = "dev-abc") -> Any:
-        return cast(Any, SimpleNamespace(
-            spec=SimpleNamespace(image_policy=policy),
-            slug=slug,
-            image="bot-bottle-agent:latest",
-        ))
-
-    def test_fresh_policy_is_noop(self) -> None:
-        from bot_bottle.backend.macos_container import launch as mod
-        with patch.object(mod, "read_committed_image") as rci, \
-             patch.object(mod, "check_stale") as cs:
-            mod.stale_checks(self._plan("fresh"))
-        rci.assert_not_called()
-        cs.assert_not_called()
-
-    def test_committed_image_present_checks_only_committed(self) -> None:
-        from bot_bottle.backend.macos_container import launch as mod
-        from datetime import datetime, timezone
-        ts = datetime(2025, 1, 1, tzinfo=timezone.utc)
-        with patch.object(mod, "read_committed_image", return_value="committed:latest"), \
-             patch.object(mod.container_mod, "image_exists", return_value=True), \
-             patch.object(mod.container_mod, "image_created_at", return_value=ts), \
-             patch.object(mod, "check_stale") as cs:
-            mod.stale_checks(self._plan())
-        cs.assert_called_once()
-        self.assertIn("committed:latest", cs.call_args.args[0])
-
-    def test_no_committed_image_checks_agent_and_sidecar(self) -> None:
-        from bot_bottle.backend.macos_container import launch as mod
-        from datetime import datetime, timezone
-        ts = datetime(2025, 1, 1, tzinfo=timezone.utc)
-        with patch.object(mod, "read_committed_image", return_value=""), \
-             patch.object(mod.container_mod, "image_exists", return_value=True), \
-             patch.object(mod.container_mod, "image_created_at", return_value=ts), \
-             patch.object(mod, "check_stale") as cs:
-            mod.stale_checks(self._plan())
-        self.assertEqual(2, cs.call_count)
-
-    def test_image_not_present_skips_check(self) -> None:
-        from bot_bottle.backend.macos_container import launch as mod
-        with patch.object(mod, "read_committed_image", return_value=""), \
-             patch.object(mod.container_mod, "image_exists", return_value=False), \
-             patch.object(mod, "check_stale") as cs:
-            mod.stale_checks(self._plan())
-        cs.assert_not_called()
-
-    def test_backend_image_stale_checks_delegates(self) -> None:
-        from bot_bottle.backend.macos_container.backend import MacosContainerBottleBackend
-        from bot_bottle.backend.macos_container import launch as mod
-        backend = MacosContainerBottleBackend()
-        plan = self._plan()
-        with patch.object(mod, "stale_checks") as sc:
-            backend._image_stale_checks(plan)  # type: ignore[arg-type]
-        sc.assert_called_once_with(plan)
-
-
-if __name__ == "__main__":
-    unittest.main()