fix(install): skip browser download when system chromium exists

[helix4u]

What does this PR do?

Fixes a Linux installer failure mode where Hermes can get stuck during Playwright's managed Chromium install even though a usable system Chrome/Chromium is already present.

On unsupported Arch-family distributions such as CachyOS, Playwright can download its Ubuntu fallback Chrome-for-Testing archive and then hang during the explicit npx playwright install chromium step. Because that happens before setup_path, config template creation, and the setup wizard, the user is left with a partially installed Hermes checkout even though the core Python environment has already been created.

This change makes browser setup best-effort instead of allowing the managed Playwright browser download to block the whole install. The installer now detects an existing system browser first, skips the Playwright download when one is found, and persists AGENT_BROWSER_EXECUTABLE_PATH into ~/.hermes/.env so browser tools use that system binary. Remaining Playwright install paths are timeout-guarded.

Related Issue

Fixes #

Support thread: CachyOS installer hangs after Downloading Chrome for Testing ... 100% while /usr/bin/chromium is already installed.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• scripts/install.sh
  • Detects existing system Chrome/Chromium binaries before attempting Playwright's managed browser download.
  • Includes plain chromium, which is the common Arch/CachyOS command name.
  • Skips npx playwright install chromium when a system browser is found.
  • Writes AGENT_BROWSER_EXECUTABLE_PATH=<system browser> into ~/.hermes/.env unless the user already configured it.
  • Wraps explicit Playwright browser install calls with a 10-minute timeout where timeout is available.
  • Routes CachyOS and other common Arch-family distro IDs through the Arch dependency branch.
• tools/browser_tool.py
  • Treats plain chromium on PATH as a valid local browser.
• tests/test_install_sh_browser_install.py
  • Adds regression coverage for system-browser skip behavior, env persistence, and timeout-wrapped Playwright installs.
• tests/tools/test_browser_chromium_check.py
  • Adds runtime coverage for plain chromium on PATH.

How to Test

1. On a CachyOS/Arch-family system with Chromium installed at /usr/bin/chromium, run the installer.
2. Confirm the installer reports the system browser and skips the Playwright browser download instead of hanging at Chrome-for-Testing download/extraction.
3. Confirm ~/.hermes/.env contains AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium.
4. Run targeted tests: pytest tests/tools/test_browser_chromium_check.py tests/test_install_sh_browser_install.py.
5. Optional full suite: scripts/run_tests.sh -n 3.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: WSL/Linux targeted tests; support repro validated on CachyOS by the affected user with the system-Chromium bypass

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

For New Skills

N/A

Screenshots / Logs

Targeted checks before opening PR:

bash -n scripts/install.sh

pytest tests/tools/test_browser_chromium_check.py tests/test_install_sh_browser_install.py

Result: 13 passed in 2.54s

Full suite attempt after opening PR:

scripts/run_tests.sh -n 3

Result: failed, 47 failed, 22434 passed, 59 skipped, 231 warnings, 19 errors in 1083.46s (0:18:03).

The full-suite failures are broad and appear outside this PR's installer/browser-detection test coverage. The named failures include LSP client lifecycle tests, cron/script timeout tests, config mutation tests, process/interrupt/zombie cleanup tests, and browser supervisor errors. Full log is available locally at /tmp/hermes_full_suite_n3.log from the run machine.