Default the x11 headless desktop to GNOME (Openbox still opt-in)

Bare Openbox rendered only a blank slate root — usable but not the
desktop wanted. Make the X11/NVENC capture path render a full GNOME
session by default, with Openbox available via HEADLESS_DESKTOP=openbox
for minimal/low-power hosts.

- files/headless-desktop-gnome.service: full Ubuntu GNOME session forced
  onto the X11 path (XDG_SESSION_TYPE=x11, no dbus-run-session so it
  shares the systemd user bus). Renamed the Openbox unit to
  headless-desktop-openbox.service.
- lib/headless.sh: HEADLESS_DESKTOP (default gnome) selects the unit
  template + the packages to install (gnome-session/gnome-shell vs
  openbox/xsetroot).
- install.sh: step message + usage document HEADLESS_DESKTOP.
- status.sh: the :0 desktop check now reports which desktop is running
  (reads _NET_WM_NAME off the supporting-wm-check window, e.g.
  "GNOME Shell").
- docs: TROUBLESHOOTING §13 + FOLLOWUPS P3 updated for the GNOME default
  and the openbox toggle.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

lib/headless.sh

@@ -48,30 +48,52 @@ capture_backend_is_x11() {
 
 HEADLESS_DESKTOP_UNIT="headless-desktop.service"
 
-# Pull the lightweight WM (Openbox) we drive on :0, plus xsetroot for the
-# solid-background touch. Idempotent — pkg_install skips what's present.
+# Which desktop to render on the headless Xorg :0. Default is a full GNOME
+# session (the familiar Ubuntu desktop). Set HEADLESS_DESKTOP=openbox for a
+# lightweight bare WM instead — lower overhead, better for a truly minimal or
+# low-power host, but no panel/launcher out of the box (right-click menu only).
+: "${HEADLESS_DESKTOP:=gnome}"
+
+# Install the packages the chosen desktop needs. Idempotent — pkg_install
+# skips what's already present.
 ensure_headless_desktop_packages() {
-  command -v openbox-session >/dev/null 2>&1 || pkg_install openbox
-  if ! command -v xsetroot >/dev/null 2>&1; then
-    case "$DISTRO" in
-      debian) pkg_install x11-xserver-utils ;;
-      arch)   pkg_install xorg-xsetroot ;;
-    esac
-  fi
+  case "$HEADLESS_DESKTOP" in
+    gnome)
+      case "$DISTRO" in
+        debian) pkg_install gnome-session gnome-shell ubuntu-session ;;
+        arch)   pkg_install gnome-shell gnome-session ;;
+      esac
+      ;;
+    openbox)
+      command -v openbox-session >/dev/null 2>&1 || pkg_install openbox
+      # xsetroot paints a solid root so the bare desktop is visibly non-black.
+      if ! command -v xsetroot >/dev/null 2>&1; then
+        case "$DISTRO" in
+          debian) pkg_install x11-xserver-utils ;;
+          arch)   pkg_install xorg-xsetroot ;;
+        esac
+      fi
+      ;;
+    *)
+      err "Unknown HEADLESS_DESKTOP='$HEADLESS_DESKTOP' (expected: gnome | openbox)"
+      return 1
+      ;;
+  esac
 }
 
-# Install + enable the Openbox session that renders onto the headless Xorg
-# display (:0), so the X11/NVENC capture path has something to show instead of
-# a black root window. Idempotent: safe to re-run. Bound to xorg-headless.service
+# Install + enable a desktop session that renders onto the headless Xorg
+# display (:0), so the X11/NVENC capture path shows a real desktop instead of a
+# black root window. Picks the GNOME or Openbox unit template per
+# $HEADLESS_DESKTOP. Idempotent: safe to re-run. Bound to xorg-headless.service
 # and to default.target (the lingering-user manager reaches it without a login).
 install_headless_desktop() {
-  local src="$SCRIPT_DIR/files/headless-desktop.service"
+  local src="$SCRIPT_DIR/files/headless-desktop-${HEADLESS_DESKTOP}.service"
   if [[ ! -f "$src" ]]; then
-    err "Desktop unit source missing: $src"
+    err "Desktop unit source missing: $src (HEADLESS_DESKTOP=$HEADLESS_DESKTOP)"
     return 1
   fi
 
-  ensure_headless_desktop_packages
+  ensure_headless_desktop_packages || return 1
 
   local unit_dir="$HOME/.config/systemd/user"
   mkdir -p "$unit_dir"
@@ -82,7 +104,7 @@ install_headless_desktop() {
   # headless box with no session yet, fall back to enable-only so it comes up
   # on next boot via default.target.
   if systemctl --user enable --now "$HEADLESS_DESKTOP_UNIT" >/dev/null 2>&1; then
-    ok "Enabled $HEADLESS_DESKTOP_UNIT (Openbox session on :0)"
+    ok "Enabled $HEADLESS_DESKTOP_UNIT ($HEADLESS_DESKTOP session on :0)"
   else
     systemctl --user enable "$HEADLESS_DESKTOP_UNIT" >/dev/null 2>&1 || true
     warn "Installed $HEADLESS_DESKTOP_UNIT but couldn't start it now — it will start on next login/boot."