fix(browser): apply gemini-web provider proxy and start Xvfb for headed zai-web (#15076)

[diegosouzapw]

Refs #15076
Refs #15300

Root cause

• fix(providers): gemini-web: Playwright Chromium ignores configured provider proxy — Gemini unreachable from geo-blocked regions #15076: GeminiWebExecutor opened browser.newContext({ userAgent }) without ever calling resolvePlaywrightProxy, so the proxy configured for gemini-web never reached Chromium.
• fix(providers): zai-web fails with 502 "browserType.launch" on v3.8.51 (latest-web, Docker), multiple accounts tested #15300: zai-web needs a headed Chromium (Z.ai CAPTCHA rejects headless) but the Docker -web image has no X server and nothing sets DISPLAY, so chromium.launch died with a bare browserType.launch ... closed 502 for every account.

Fix

• gemini-web.ts: resolve the provider proxy per context (resolvePlaywrightProxy("gemini-web")) and pass it to newContext only when one exists, so the shared leased browser needs no invalidation.
• New open-sse/services/virtualDisplay.ts: on Linux with no DISPLAY/WAYLAND_DISPLAY, a headed launch starts one private Xvfb per process (spawn, args array, no shell, -displayfd picks a free display), reuses it, and kills it in shutdownPool. browserPool.ts passes env.DISPLAY to the headed launch. Hosts that already have a display are untouched.
• browserExecutableCheck.ts: new isMissingDisplay(); zai-web.ts maps it to an actionable 503 + X-Omni-Fallback-Hint: connection_cooldown (same class as [BUG] Z.ai web error #13232) instead of a bare 502.
• Dockerfile runner-web: installs xvfb explicitly.
• Existing webpack-create-require-warning.test.ts: added ./virtualDisplay.ts to the isolated-compile externals (same reason as ./obscura.ts); no assertion changed.

Scope cuts (follow-ups)

For #15076 the plan-file also lists request-proxy-context resolution, edge-relay (vercel/deno/cloudflare) 503 rejection and SOCKS5-with-auth handling (from closed PR #15249). Not included here: this PR covers the provider/global registry proxy that the issue reports, reusing the existing resolvePlaywrightProxy idiom.

Tests (TDD)

• tests/unit/issue-15076-gemini-web-proxy.test.ts RED on base: configured proxy never reached Playwright: {"launchOptions":[{"headless":true}],"contextOptions":[{"userAgent":...}]} -> GREEN.
• tests/unit/zai-web-headed-no-display-15300.test.ts RED on base: STATUS 502 ... browserType.launch: Target page, context or browser has been closed -> GREEN: STATUS 503 HINT connection_cooldown.
• tests/unit/virtual-display-15300.test.ts (fake spawn): no Xvfb when a display exists, single reused Xvfb, typed error when the binary is missing, isMissingDisplay matching.
• Existing browserPool/gemini-web/zai-web tests (30 files) pass; zai-web-stream-error-boundary fails identically on the unfixed base (504 !== 502), pre-existing.

Gates

typecheck:core, check:open-sse-typecheck, eslint (with suppressions), prettier, check-file-size, check-complexity, check-cognitive-complexity: all OK.

Live check needed

The Docker -web image change (xvfb install + automatic Xvfb) needs a rebuild and a live zai-web request on the VPS; not verifiable in this sandbox (no Xvfb locally).

⚠️ base-red inherited: #15306 — unit/integration suite timeouts, vitest audit.test.ts, package-artifact, tarball boot-smoke, ai-attribution range (not caused by this PR)

[github-actions]

CI Coverage Report

• Coverage job: skipped
• PR test policy: success

Coverage artifact was not available for this run.