chore(ci): add xvfb to Linux deps, increase E2E timeouts, document Linux CI gotchas

Author: liam-russell

.github/copilot-instructions.md

@@ -290,6 +290,44 @@ The project uses **electron** - a local MCP tool for inspecting and debugging th
 
 ---
 
+## CI / Linux E2E pipeline debugging
+
+### Architecture constraints on Apple Silicon
+
+Full E2E simulation on Apple Silicon (arm64 Mac) is **not feasible** locally:
+
+- `act` with arm64 catthehacker images: wdio downloads an x86_64 Chromedriver → `rosetta error: failed to open elf at /lib64/ld-linux-x86-64.so.2`
+- `act --container-architecture linux/amd64` (QEMU): act injects its own arm64 node into the amd64 container → `node: executable file not found in $PATH`
+- Native arm64 Docker containers: Electron runs, but Chromedriver is always fetched as x86_64
+
+**Definitive validation requires pushing to GitHub and letting the real `ubuntu-latest` (x86_64) runners execute the E2E suite.**
+
+### Known Linux CI gotchas
+
+- **D-Bus deadlock**: `autoUpdater.checkForUpdates()` in `electron-updater` makes a blocking D-Bus IPC call on Linux when the system D-Bus daemon is running (always present on `ubuntu-latest`). In E2E mode, this deadlocks the Electron main process before the renderer loads. **Fix**: guard `startUpdateCheck()` with `if (!isE2EMode)` in `app/src/main/index.ts`. The `isE2EMode` flag is set when `process.argv.includes('--sproutgit-e2e')`, which wdio passes when launching Electron.
+- **Headless display**: Electron requires a display server on Linux. Wrap the E2E command with `xvfb-run --auto-servernum --server-args="-screen 0 1280x800x24"` and ensure `xvfb` is installed in the apt-get step.
+- **Sandbox**: pass `--no-sandbox --disable-setuid-sandbox` to Electron in CI (already in `wdio.conf.ts`).
+
+### Proving a Linux-specific hang locally (arm64 Docker)
+
+To confirm whether a code path causes a main-process freeze on Linux with D-Bus present, use the cached `sproutgit-dbus-proof-arm64:latest` Docker image:
+
+```bash
+# Build the app inside the container, start Xvfb + D-Bus, run Electron for 5s,
+# and check whether the renderer emitted any log lines.
+docker run --rm \
+  -v "$(pwd):/src:ro" \
+  -v "/tmp/your-proof.sh:/proof.sh:ro" \
+  sproutgit-dbus-proof-arm64:latest \
+  bash /proof.sh
+```
+
+Key detection heuristic: after 5 seconds, if no `[renderer]` lines appear in the Electron log, the main process is frozen (D-Bus deadlock). If `[renderer]` lines appear, the app is alive.
+
+The image already has: ubuntu 24.04, Node 22, pnpm, xvfb, dbus, all Electron system deps. Rebuild it with `docker build -t sproutgit-dbus-proof-arm64:latest .` from a Dockerfile that installs those deps if it becomes stale.
+
+---
+
 ## Common pitfalls
 
 - **Don't import from `old/`** — it's the Tauri/SvelteKit source for reference only.

.github/workflows/ci.yml

@@ -180,6 +180,7 @@ jobs:
         run: |
           sudo apt-get update -q
           sudo apt-get install -y -q \
+            xvfb \
             libgbm1 libnss3 libatk1.0-0 libatk-bridge2.0-0 \
             libdrm2 libxkbcommon0 libxdamage1 libxrandr2 libxfixes3 \
             libxcomposite1 libxcursor1 libxi6 libxss1 libxtst6 \

e2e/wdio.conf.ts

@@ -55,10 +55,14 @@ export const config: WebdriverIO.Config = {
   logLevel: 'info',
   bail: 0,
 
-  // Default timeout for waitForDisplayed / expect assertions (5s baseline).
-  waitforTimeout: 15_000,
-
-  connectionRetryTimeout: 20_000,
+  // On Linux the renderer can be slow to initialise (QEMU emulation on CI or
+  // amd64 runners without hardware GPU acceleration). Use 4× the base timeout
+  // so QEMU-based Docker runs and real CI both stay reliable.
+  // On macOS/Windows native builds the app renders in <2s so the limit is
+  // never reached for passing tests.
+  waitforTimeout: process.platform === 'linux' ? 60_000 : 15_000,
+
+  connectionRetryTimeout: process.platform === 'linux' ? 60_000 : 20_000,
   connectionRetryCount: 3,
 
   services: ['electron'],
@@ -70,7 +74,8 @@ export const config: WebdriverIO.Config = {
     ui: 'bdd',
     // Safety-net timeout per test; individual element waits are capped by waitforTimeout.
     // Screenshot pipeline runs 5 shots × 2 themes and can take up to 2 minutes.
-    timeout: process.env['CAPTURE_SCREENSHOTS'] ? 120_000 : 30_000,
+    // Linux gets 4× headroom for QEMU emulation (Docker) and CPU-limited CI runners.
+    timeout: process.env['CAPTURE_SCREENSHOTS'] ? 120_000 : process.platform === 'linux' ? 120_000 : 30_000,
   },
 
   // Always build the Electron app before running tests so the test binary is