sergio/takana

Estado: gnome-shell corre 5 minutos sobre DRM real sin una sola JS ERROR, y la
captura del framebuffer muestra la consola del kernel en negro. Mutter nunca
presentó un frame.

La pista del log de KMS es concreta: el plano primario 33 de virtio-gpu 'has no
advertised formats' y sólo hay 'Queue mode set' — ningún page flip. Tres hipótesis
de una variable cada una, la primera es quitar MUTTER_DEBUG_FORCE_KMS_MODE=simple,
que se heredó de la campaña KDE (donde el que fallaba con atomic era kwin).

Queda además escrito CÓMO validar con pantalla sin humano delante: screendump por
el monitor de QEMU + PPM→PNG. Aplicar esa regla es lo que destapó este muro — el
serial decía 'sesión viva'.

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

diff --git a/docs/runbooks/gnome-qemu-desktop.md b/docs/runbooks/gnome-qemu-desktop.md
index 5f11a4b4..57bdf0ee 100644
--- a/docs/runbooks/gnome-qemu-desktop.md
+++ b/docs/runbooks/gnome-qemu-desktop.md
@@ -12,10 +12,9 @@ Using Wayland display name 'wayland-0'
 == gnome-qemu :: compositor OK (wayland-0) — el shell ES el display server
 ```
 
-Lo único que queda para tener escritorio es la **capa JS**: el shell sale con código 1 en
-`JS ERROR: Requiring AccountsService, version 1.0: Typelib file … not found`. Ya no hay ningún
-cuelgue ni ningún SIGSEGV: los tres muros anteriores están cerrados, cada uno por medición y no por
-conjetura.
+**Y la capa JS también está cerrada**: gnome-shell corre cinco minutos seguidos sin una sola
+`JS ERROR`. Lo que falta es que PINTE — la pantalla sigue en negro. Ni cuelgues ni SIGSEGV: los
+cuatro muros anteriores están cerrados, cada uno por medición y no por conjetura.
 
 Hermano de [`kde-qemu-desktop.md`](kde-qemu-desktop.md), del que reusa el andamiaje: la base
 `work/metal-rootfs`, la inyección de mesa-llvmpipe/LLVM/musl, el truco del console-getty y el propio
@@ -25,7 +24,7 @@ Hermano de [`kde-qemu-desktop.md`](kde-qemu-desktop.md), del que reusa el andami
 
 ```sh
 cd ~/hammer
-bash scripts/gnome/hydrate-gnome.sh          # cierre de gnome-shell → work/gnome-rootfs (108/108)
+bash scripts/gnome/hydrate-gnome.sh          # cierre de gnome-shell + las raíces de RUNTIME → work/gnome-rootfs
 bash scripts/gnome/qemu-desktop-image.sh     # funde base+gnome, parchea, → work/hammer-gnome-qemu.img
 IMG=work/hammer-gnome-qemu.img SERIAL=work/gnome-qemu-serial.log MON=work/gnome-monitor.sock \
   TIMEOUT=150 DISP=none bash scripts/kde/run-qemu-desktop.sh
@@ -33,8 +32,9 @@ grep -a "gnome-qemu ::" work/gnome-qemu-serial.log | awk '!seen[$0]++'
 ```
 
 `DISP=gtk` para ver la ventana (necesita `DISPLAY=:0 GDK_BACKEND=x11`). **Regla heredada de KDE:
-validar escritorios con PANTALLA, nunca sólo por serial** — pero hoy no hace falta, porque no llega
-a pintar.
+validar escritorios con PANTALLA, nunca sólo por serial** — y sin humano delante se cumple con el
+`screendump` del monitor de QEMU, ver abajo. Aplicarla es lo que destapó el muro de hoy: el serial
+decía «sesión viva» y la pantalla estaba negra.
 
 ## Sacar el core y el backtrace
 
@@ -48,12 +48,52 @@ gdb -batch -q -ex "set sysroot $PWD/work/gnome-qemu-rootfs" \
     -ex "core-file /tmp/core.gnome-shell" -ex "bt 25" work/gnome-qemu-rootfs/usr/bin/gnome-shell
 ```
 
-## EL MURO DE HOY — los typelibs de runtime de la capa JS
+## EL MURO DE HOY — la sesión VIVE pero la pantalla está NEGRA
 
-No es un cuelgue ni un crash: el compositor sube, expone `wayland-0`, y el shell sale con código 1
-porque a `imports.gi.*` le falta un typelib. Cada vez que se cierra uno, aparece el siguiente.
+```
+== gnome-qemu :: compositor OK (wayland-0) — el shell ES el display server
+== gnome-qemu :: STATUS +15s … +315s: gnome-shell=2      ← cinco minutos, sin una sola JS ERROR
+```
+
+La capa JS está cerrada: gnome-shell arranca entero y se queda corriendo. Pero la captura del
+framebuffer (`screendump` por el monitor de QEMU) muestra **la consola del kernel, en negro** — el
+último `[ 0.813456] arje-zero:` del boot. O sea que mutter nunca presentó un frame al CRTC.
+
+**Validar con captura, no con serial.** Es la regla heredada de KDE ([[metal-dual-desktop-en-curso]])
+y acá se cumple sin humano delante:
+
+```sh
+printf 'screendump /tmp/gnome.ppm\n' | socat - UNIX-CONNECT:work/gnome-monitor.sock
+python3 -c "from PIL import Image; Image.open('/tmp/gnome.ppm').save('/tmp/gnome.png')"
+```
+
+La pista está en el log de KMS, y es concreta:
+
+```
+KMS: Adding primary plane 33 (/dev/dri/card0)
+KMS:   Plane has no advertised formats          ← virtio-gpu sin 3D no publica IN_FORMATS
+KMS: Queue mode set                              ← ×3, y nunca hay page flip ni scanout
+```
+
+Hipótesis por orden de costo, todas de una sola variable:
+1. **Quitar `MUTTER_DEBUG_FORCE_KMS_MODE=simple`** de `gnome-start-qemu.sh`. Ese forzado se heredó de
+   la campaña KDE, donde kwin fallaba con atomic; mutter puede comportarse distinto, y el modo
+   legacy es justo el que no sabe qué hacer con un plano sin formatos publicados.
+2. Encender 3D en el virtio-gpu de QEMU (`virtio-vga-gl` + virgl) y sacar `GBM_ALWAYS_SOFTWARE`.
+3. Mirar si `MUTTER_DEBUG_SEND_KMS_MODIFIERS=0` sigue haciendo falta ahora que hay scanout real.
+
+Lo demás del log son avisos, no muros: falta un tema de cursor, colord no arranca (el helper setuid
+no tiene los permisos) y `org.gnome.settings-daemon.peripherals.touchscreen` no existe porque
+gnome-settings-daemon está aparcada — eso rompe quick-settings, no la sesión.
+
+## CÓMO SE CERRÓ LA CAPA JS (2026-07-29)
+
+Era el muro anterior, y quedó cerrado. Vale la pena dejar cómo, porque el método es reusable.
+
+El síntoma era: el compositor sube, expone `wayland-0`, y el shell sale con código 1 porque a
+`imports.gi.*` le falta un typelib. Cada vez que se cerraba uno, aparecía el siguiente.
 
-**Y ESA ITERACIÓN ES INNECESARIA — la lista está declarada en el propio shell.**
+**Y ESA ITERACIÓN ERA INNECESARIA — la lista está declarada en el propio shell.**
 `js/misc/dependencies.js` enumera EXACTAMENTE lo que el shell exige al arrancar. Cruzada contra el
 rootfs hidratado, la frontera completa es de **siete typelibs**, de cinco recetas nuevas y una a
 rehacer (medido, no estimado):