gui: one shared dbus session bus for the gui session (#1906)

docs/gotchas.md

@@ -270,6 +270,19 @@ connects to the compositor at `127.0.0.1:<vnc_port>`.
   wayland client sharing the `/run/gui/wayland-0` socket). Wayland
   clients in the agent's config (e.g. bitburner electron) must run as the
   same user with `XDG_RUNTIME_DIR=/run/gui`.
+- **One shared D-Bus session bus (`gui-dbus.service`)**: a single
+  persistent `dbus-daemon --session` bound at `/run/gui/bus`, run as the
+  agent user, ordered `before weston.service` (it shares the same
+  `RuntimeDirectory=gui`, creating the dir first). Chromium/electron via
+  ozone refuse to map an `xdg_toplevel` without a reachable session bus
+  ("Failed to connect to the bus" → binds `xdg_wm_base` then destroys it
+  = invisible window even though CDP works). The fix is **not** to wrap
+  each client in its own `dbus-run-session` (a private throwaway bus per
+  process — that's a *separate* session, defeating the one-session
+  model); it's this one shared bus, whose address is exported as
+  `DBUS_SESSION_BUS_ADDRESS=unix:path=/run/gui/bus` via
+  `systemd.globalEnvironment` so weston, the harness and every GUI client
+  inherit it.
 - **Fixed Wayland socket name (`--socket=wayland-0`)**: weston is
   launched with `--socket=wayland-0` so the socket path is
   deterministic. `harness-base.nix` exports `WAYLAND_DISPLAY=wayland-0`