chore(tasks): file a post-rebuild probe for the Emacs frame backend

A first-frame error on a PGTK daemon lands the session on XWayland with no visible failure, and the post-rebuild pass has no check that would notice. The task records the 2026-08-24 instance and the fail-closed probe design that exposes it.

1 files changed, 54 insertions, 0 deletions

diff --git a/todo.org b/todo.org
index cf8d242..063aadb 100644
--- a/todo.org
+++ b/todo.org
@@ -45,6 +45,60 @@ below):
   input-side-spec.org (DRAFT, four decisions open).
 
 * Archsetup Open Work
+** TODO [#C] post-rebuild-check: probe that Emacs frames come up Wayland-native :feature:emacs:velox:solo:quick:
+:PROPERTIES:
+:CREATED: [2026-08-25 Tue]
+:LAST_REVIEWED: 2026-08-25
+:END:
+On 2026-08-24, the first Emacs 31.1 start on velox opened its first frame on
+XWayland (=:0=) with the pgtk "unsupported under X" dialog, while every later
+frame went to =wayland-1=. The cause was in the Emacs config (a startup buffer
+sweep killed =*Warnings*= while 31.1's warnings.el held it for a deferred
+display, so the first =make-frame= failed and emacsclient fell back to
+=$DISPLAY=); fixed in =.emacs.d= the same night. The trap generalizes: any
+first-frame error on a PGTK daemon silently lands the session on X, and nothing
+in the post-rebuild pass would notice.
+
+Design, under the script's fail-closed contract (a probe that cannot run
+reports a finding, never a pass):
+- Bound every =emacsclient= call with =timeout=, as the =systemctl= calls are.
+  A daemon stuck in a prompt is a finding, not a hang.
+- No daemon (=emacsclient= cannot connect): a visible finding, "not checked:
+  no Emacs daemon, start Emacs and re-run". Emacs is started on demand here,
+  so this is the common state right after a rebuild, and the line is the point.
+- Daemon up but no GUI frame yet: never skip, and never call
+  =pgtk-backend-display-class= with no frame (it errors with "Frames are not
+  in use"). Request one invisible frame through a waiting client in the
+  background, =timeout 20 emacsclient -c -F '((visibility . nil) (name .
+  "prc-probe"))'=, so the probe walks the same first-frame path that failed on
+  2026-08-24. Then wait, bounded (poll for a frame named =prc-probe= for up to
+  the same 20 s), before inspecting: the =-e= must not run before the =-c=
+  has connected. Zero pgtk frames after the request is a finding in its own
+  right, because a frame request that produced nothing is the first-frame
+  failure this check hunts. Delete the probe frame after reading.
+- Inspect every pgtk frame, not the selected display, and only pgtk frames:
+  a tty client frame (=emacsclient -t= in tmux) carries =$DISPLAY= as its
+  display parameter and its terminal is not a display, so it would both trip
+  the =:0= rule and make =pgtk-backend-display-class= error.
+  #+begin_src sh
+  emacsclient -e '(mapcar (lambda (f) (list (frame-parameter f (quote display)) (pgtk-backend-display-class (frame-terminal f)))) (seq-filter (lambda (f) (eq (framep f) (quote pgtk))) (frame-list)))'
+  #+end_src
+  Expected: at least one entry, every display equal to =$WAYLAND_DISPLAY=,
+  every class =GdkWaylandDisplay=. An empty list, a =:0= entry, or a
+  =GdkX11Display= is a finding. A build without =pgtk-backend-display-class=
+  is a finding too: the installer installs =emacs-wayland=.
+- Limit, stated in the check's output: it sees live frames only. A first X
+  frame that was already closed is invisible, so this reports the machine's
+  current state, not its history. The invisible probe frame is created and
+  never mapped, so it exercises =make-frame= (where 2026-08-24 failed), not
+  the window-show path.
+
+Tests alongside the other checks, one per state: no daemon, no frame (probe
+frame requested and waited for), probe frame never appears, Wayland-only, a
+=:0= frame present, a tty client frame present alongside Wayland frames, hung
+daemon, an =*ERROR*= reply from =emacsclient -e= (exit 1, a finding), non-pgtk
+build.
+
 ** TODO [#B] Timeline spine test picks the wrong "next" event off Denver :bug:dotfiles:test:
 :PROPERTIES:
 :CREATED: [2026-08-24 Mon]