[switchyard] Provision shared browsers with the selected egress mode and actionable setup errors

[jhgaylor]

Make Shared browser → Open browser provision and run Chromium using the project's selected network mode, and report the actual reason when setup cannot finish.

Related dependencies:

• Persist an explicit direct-egress opt-in across shared-machine attach and resume BinaryBourbon/fountain#1638 — persistent direct-egress opt-in.
• [switchyard] Expose persistent project internet-access settings #44 — Switchyard project controls.
• Chromium install fails on broker-enabled Sprites with default-deny networking BinaryBourbon/fountain#1633 — supported broker access for persistent browser services when enforcement remains enabled.

Observed failure and manual recovery

On the production Expo project, Node and npm were present, but the install ran through ordinary Sprite exec without proxy settings. The broker-only machine policy blocked DNS for npm. The UI only reported that Node/npm or Chromium libraries might be missing.

After allowing the exact package download hosts, playwright-core@1.63.0 and Chromium downloaded. A real sandboxed launch then exposed a second failure: missing libglib-2.0.so.0. Installing Playwright's Linux dependencies fixed launch. A disposable page rendered and produced a screenshot, and the production shared-browser session reached ready with no error. Broader external browsing still required the owner's separate direct-egress approval.

Required behavior

• Check effective project egress before setup. Direct mode uses the supported persisted policy; broker-enforced mode uses the supported provisioning/service integration from Fountain #1633.
• If the required broker service capability is unavailable, say so explicitly. Do not silently widen network access or borrow a conversation's expiring proxy token.
• Ensure npm/Chromium downloads have the selected mode's connectivity and certificate trust. Configure Chromium itself for authenticated proxy access when needed; installer environment variables alone do not establish browser connectivity.
• For the brokered path, service access must survive conversations ending and handle renewal, restart, and revocation with the browser's lifecycle.
• Check Node/npm and Linux dependencies separately. Provide an idempotent, supported way to install the missing dependencies with the machine's authorized package privileges; cache the pinned runtime.
• Preserve bounded, sanitized stage diagnostics: DNS/egress failure, registry/download failure, missing library, sandbox launch failure, and service readiness failure. Keep credentials and raw proxy URLs out of user-visible errors.
• Preserve the persistent profile and checkpoints across setup retries and service restarts. Do not declare ready until Chromium actually launches with its sandbox enabled.

Acceptance

• A fresh supported Sprite can complete setup and open the shared browser without manually installing packages or editing its policy outside the supported configuration flow.
• Verify a rendered page through the actual Switchyard UI and navigate to external HTTPS using the selected mode.
• Stop/reopen the browser and end/open conversations without losing profile state or service connectivity.
• Direct-mode verification must survive a new conversation attachment; brokered verification must retain broker-only enforcement.
• Negative tests distinguish blocked egress, missing proxy support, missing system libraries, and launch failures; retries are idempotent and diagnostics contain no secrets.
• Record live evidence for both supported modes. The current successful manual recovery proves direct-mode installation/launch only.

Relevant code: apps/switchyard/server/browsers.ts, server/sprites.ts, runner/scripts/browser-worker.cjs, the shared browser UI, and docs/shared-browser.md.