browser: teardown runtimes on shutdown and avoid default warmup container

- add manager/provider shutdown lifecycle to remove dedicated browser containers on service stop

- make sandbox warmup preflight-only for scoped runtimes to avoid spawning default-scope container

- add regression tests for warmup and shutdown behavior

Co-Authored-By: GPT-5 Codex <codex@openai.com>

Author: dcramer

src/ash/browser/manager.py

@@ -92,6 +92,23 @@ async def warmup_default_provider(self) -> None:
             extra={"browser.provider": provider_key},
         )
 
+    async def shutdown(self) -> None:
+        """Best-effort shutdown for provider runtimes during service teardown."""
+        for provider_key, provider in self._providers.items():
+            shutdown = getattr(provider, "shutdown", None)
+            if not callable(shutdown):
+                continue
+            try:
+                await shutdown()
+            except Exception as e:
+                logger.warning(
+                    "browser_runtime_shutdown_failed",
+                    extra={
+                        "browser.provider": provider_key,
+                        "error.message": str(e),
+                    },
+                )
+
     def _action_timeout_seconds(self, action: str) -> float:
         base = self._clamp_timeout_seconds(float(self._config.browser.timeout_seconds))
         if action == "session.start":

src/ash/browser/providers/sandbox.py

@@ -162,8 +162,33 @@ async def close_session(self, *, provider_session_id: str | None) -> None:
         return None
 
     async def warmup(self) -> None:
-        """Boot and verify warm browser runtime ahead of first user action."""
-        await self._ensure_runtime(scope_hash=self._scope_hash(None))
+        """Warmup preflight for scoped dedicated runtime.
+
+        Dedicated runtime containers are keyed by effective user scope, which is
+        unknown at process startup. Warmup therefore validates that the browser
+        image is available but does not start a default container.
+        """
+        inspect_image = await self._execute_host_command(
+            ["docker", "image", "inspect", self._container_image],
+            timeout_seconds=15,
+        )
+        if not inspect_image.success:
+            raise ValueError(
+                "sandbox_browser_launch_failed: missing_browser_image:"
+                f"{self._container_image}"
+            )
+
+    async def shutdown(self) -> None:
+        """Best-effort runtime shutdown for service lifecycle teardown."""
+        async with self._runtime_lock:
+            self._sessions.clear()
+            self._session_targets.clear()
+            runtime = self._runtime
+            self._runtime = None
+            self._active_scope_hash = None
+            if runtime is None:
+                return
+            await self._kill_runtime(runtime)
 
     async def goto(
         self,

src/ash/integrations/browser.py

@@ -65,14 +65,21 @@ async def on_startup(self, context: IntegrationContext) -> None:
         )
 
     async def on_shutdown(self, context: IntegrationContext) -> None:
-        _ = context
         if self._warmup_task is None:
+            pass
+        else:
+            if not self._warmup_task.done():
+                self._warmup_task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await self._warmup_task
+            self._warmup_task = None
+
+        manager = getattr(context.components, "browser_manager", None)
+        if manager is None:
             return
-        if not self._warmup_task.done():
-            self._warmup_task.cancel()
-            with contextlib.suppress(asyncio.CancelledError):
-                await self._warmup_task
-        self._warmup_task = None
+        shutdown = getattr(manager, "shutdown", None)
+        if callable(shutdown):
+            await shutdown()
 
     def augment_prompt_context(
         self,

tests/test_browser.py

@@ -113,10 +113,14 @@ class _FakeWarmupProvider(_FakeProvider):
 
     def __init__(self) -> None:
         self.warmup_calls = 0
+        self.shutdown_calls = 0
 
     async def warmup(self) -> None:
         self.warmup_calls += 1
 
+    async def shutdown(self) -> None:
+        self.shutdown_calls += 1
+
 
 class _FailingRuntimeProvider(_FakeProvider):
     async def start_session(
@@ -540,6 +544,17 @@ async def test_browser_manager_warmup_default_provider(tmp_path) -> None:
     assert provider.warmup_calls == 1
 
 
+@pytest.mark.asyncio
+async def test_browser_manager_shutdown_calls_provider_shutdown(tmp_path) -> None:
+    store = BrowserStore(tmp_path / "browser")
+    provider = _FakeWarmupProvider()
+    manager = BrowserManager(
+        config=_config(), store=store, providers={"sandbox": provider}
+    )
+    await manager.shutdown()
+    assert provider.shutdown_calls == 1
+
+
 @pytest.mark.asyncio
 async def test_create_browser_manager_omits_kernel_when_unconfigured(
     tmp_path, monkeypatch: pytest.MonkeyPatch

tests/test_browser_sandbox_provider.py

@@ -182,6 +182,19 @@ async def _bridge_timeout(
         )
 
 
+@pytest.mark.asyncio
+async def test_sandbox_provider_warmup_does_not_start_default_container() -> None:
+    stub = _HostDockerStub()
+    provider = SandboxBrowserProvider()
+    provider._execute_host_command = stub.run  # type: ignore[assignment]
+
+    await provider.warmup()
+
+    assert any(args[:3] == ["docker", "image", "inspect"] for args in stub.calls)
+    assert not any(args[:2] == ["docker", "create"] for args in stub.calls)
+    assert not any(args[:2] == ["docker", "start"] for args in stub.calls)
+
+
 async def _noop_wait(*, runtime: Any) -> None:
     _ = runtime
 

tests/test_integrations_builtin.py

@@ -167,10 +167,14 @@ async def test_browser_integration_owns_manager_tool_and_warmup(monkeypatch) ->
     class _FakeManager:
         def __init__(self) -> None:
             self.warmup_calls = 0
+            self.shutdown_calls = 0
 
         async def warmup_default_provider(self) -> None:
             self.warmup_calls += 1
 
+        async def shutdown(self) -> None:
+            self.shutdown_calls += 1
+
     fake_manager = _FakeManager()
     monkeypatch.setattr(
         "ash.browser.create_browser_manager",
@@ -184,6 +188,8 @@ async def warmup_default_provider(self) -> None:
     await integration.on_startup(context)
     await asyncio.sleep(0)
     assert fake_manager.warmup_calls == 1
+    await integration.on_shutdown(context)
+    assert fake_manager.shutdown_calls == 1
 
 
 @pytest.mark.asyncio