fix(stagehand): Inject --no-sandbox into Stagehand's Chromium launch when sandbox is disabled (#1906)

## Summary

The scheduled e2e tests for the Stagehand template have failed for
several days. After PR #1900 fixed the `OPENAI_API_KEY` propagation, the
next layer of failure surfaced — every Stagehand variant in [today's
run](https://github.com/apify/crawlee-python/actions/runs/26136278735)
failed identically on the Apify platform with:

```
stagehand.InternalServerError: Error code: 500 - {'success': False, 'message': 'connect ECONNREFUSED 127.0.0.1:<port>'}
```

## Root cause

Reproduced locally inside the `apify/actor-python-playwright:3.13`
image: Stagehand's `BrowserLaunchOptions` accepts a `chromium_sandbox`
field, but the field is **not propagated** to the underlying Chromium
launch. When the actor runs as root (which it does on Apify), Chromium
silently refuses to start because the setuid sandbox can't initialise —
and Stagehand's local SEA server then hits `ECONNREFUSED` when it tries
to connect to the missing Chromium CDP port. The regular
`PlaywrightCrawler` is unaffected because Playwright's Python binding
*does* translate `chromium_sandbox=False` into `--no-sandbox`.

## Fix

In `StagehandBrowserPlugin`, when the sandbox is disabled
(`config.disable_browser_sandbox=True`, which Apify auto-sets), append
`'--no-sandbox'` to `browser_launch_options['args']` as an explicit
workaround. Verified end-to-end in the same actor base image — the
crawler now completes requests successfully.

The `apify push` hang from the same scheduled run is a separate flake
and is addressed in #1905.

Author: vdusek

src/crawlee/browsers/_stagehand_browser_plugin.py

@@ -88,6 +88,15 @@ def __init__(
         if user_data_dir is not None:
             self._browser_launch_options['user_data_dir'] = str(user_data_dir)
 
+        # Stagehand's BrowserLaunchOptions accept `chromium_sandbox` but the field is not propagated
+        # to the underlying Chromium launch, so containers running as root hit ECONNREFUSED on the CDP port.
+        # Inject `--no-sandbox` explicitly when the sandbox is disabled.
+        if not self._browser_launch_options['chromium_sandbox']:
+            args = list(self._browser_launch_options.get('args') or [])
+            if '--no-sandbox' not in args:
+                args.append('--no-sandbox')
+            self._browser_launch_options['args'] = args
+
         # Parameters for AsyncStagehand.
         self._stagehand_init_params: dict[str, Any] = {
             'server': 'local' if is_local else 'remote',

tests/unit/browsers/test_stagehand_browser_plugin.py

@@ -64,6 +64,29 @@ def test_order_priority_of_implicit_options() -> None:
     assert plugin.browser_launch_options['viewport'] == {'width': 1280, 'height': 720}
 
 
+def test_no_sandbox_added_when_sandbox_disabled() -> None:
+    # The autouse fixture in conftest sets CRAWLEE_DISABLE_BROWSER_SANDBOX=true.
+    plugin = StagehandBrowserPlugin()
+
+    assert plugin.browser_launch_options['chromium_sandbox'] is False
+    assert '--no-sandbox' in plugin.browser_launch_options['args']
+
+
+def test_no_sandbox_not_added_when_sandbox_enabled(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv('CRAWLEE_DISABLE_BROWSER_SANDBOX', 'false')
+    plugin = StagehandBrowserPlugin()
+
+    assert plugin.browser_launch_options['chromium_sandbox'] is True
+    assert 'args' not in plugin.browser_launch_options
+
+
+def test_no_sandbox_not_duplicated_when_already_in_args() -> None:
+    plugin = StagehandBrowserPlugin(browser_launch_options={'args': ['--no-sandbox', '--disable-gpu']})
+
+    assert plugin.browser_launch_options['args'].count('--no-sandbox') == 1
+    assert '--disable-gpu' in plugin.browser_launch_options['args']
+
+
 def test_stagehand_options_defaults_when_not_provided() -> None:
     plugin = StagehandBrowserPlugin()