sergio/takana

Documenta el diagnóstico completo: la AUSENCIA del `EXT4-fs mounted` como prueba de
que el root nunca se montó, la carrera contra la enumeración USB (invisible en QEMU
porque virtio está desde el instante cero), y la ceguera del /dev/console = serial.

La lección que generaliza: CADA capa del arranque tiene que escribir a /dev/tty0. Se
arregló la capa post-switch_root en el viaje de KDE y el initramfs quedó ciego; tapar
una sola capa garantiza que la siguiente vuelva a caer.

Incluye el comando para reproducir metal desde el laptop (qemu-xhci + usb-storage +
-serial null) y la evidencia en pantalla.

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

diff --git a/docs/evidencia/cosmic-metal-boot-usb-pivote-2026-08-05.png b/docs/evidencia/cosmic-metal-boot-usb-pivote-2026-08-05.png
new file mode 100644
index 00000000..acfbe140
Binary files /dev/null and b/docs/evidencia/cosmic-metal-boot-usb-pivote-2026-08-05.png differ
diff --git a/docs/runbooks/cosmic-desktop.md b/docs/runbooks/cosmic-desktop.md
index cdc1d7cb..89268abc 100644
--- a/docs/runbooks/cosmic-desktop.md
+++ b/docs/runbooks/cosmic-desktop.md
@@ -1224,12 +1224,63 @@ pasaba en QEMU. Si `Start` devuelve `Response: 0` y la sonda imprime `✓✓ HAY
 frente cierra. Si vuelve a colgarse en `Start`, mirar `/tmp/cosmic-session.log`: si **ya no** aparece
 `Erroneous EGL call`, entonces la causa era otra y el diagnóstico de hoy estaba incompleto.
 
+### 🩺 1er viaje físico: se congelaba en el USB, y NO estaba colgado (2026-08-05)
+
+Booteando en **otra máquina**, la pantalla llegaba hasta esto y se quedaba ahí:
+
+```
+GPT: Use Parted to correct GPT errors      ← inofensivo: el backup GPT no está al final del USB
+sdc: sdc1 sdc2 sdc3 sdc4
+sd 6:0:0:0: [sdc] Attached SCSI removable disk
+```
+
+**La prueba de qué pasaba es una AUSENCIA**: con `ignore_loglevel` en el cmdline, montar una ext4
+imprime `EXT4-fs (sdc2): mounted filesystem` en pantalla sí o sí. No aparecía ⇒ el root nunca se
+montó ⇒ el fallo estaba en el initramfs de pivote, no en el kernel ni en el escritorio.
+
+Dos causas encadenadas, y la segunda es la que hizo perder el viaje:
+
+1. **CARRERA contra la enumeración USB.** El `rdinit` arranca apenas se desempaqueta el initramfs,
+   pero el bus USB enumera **asíncrono** y tarda segundos (reset de hub, *settling* de 1 s por
+   dispositivo, scan SCSI). El pivote reintentaba `findfs LABEL=hammer-root` 5 veces con 1 s. En esa
+   máquina el disco es `sd 6:0:0:0` —séptimo host SCSI— y no llegó a tiempo. **En QEMU el disco es
+   virtio y está desde el instante cero, así que esta carrera NO SE PUEDE VER en validación**: hay
+   que arrancar la imagen como `usb-storage` para reproducirla. Es el `rootwait` que no podemos usar,
+   porque el descubrimiento es por LABEL y no hay `root=` en el cmdline. Ahora espera **60 s**.
+
+2. **CEGUERA.** El cmdline horneado es `console=tty0 console=ttyS0,115200 …` y el kernel hace
+   `/dev/console` = la **última** `console=` ⇒ el serial. El `exec sh` de rescate del pivote nacía en
+   un puerto serie que esa máquina no tiene: pantalla muerta, indistinguible de un kernel colgado.
+   **Es el MISMO bug que costó el 1er viaje de KDE, una capa más temprano**: allá se arregló para
+   *después* del `switch_root` (el `tty1-getty`) y se dio el caso por cerrado, pero el initramfs
+   seguía ciego. Ahora el log del pivote y el marcador `HAMMER-EFI-INIT-OK` van también a
+   **`/dev/tty0`**, y el rescate abre un shell en **tty1** listando los bloques visibles.
+
+**La lección general** (vale para toda imagen booteable, no sólo COSMIC): *cada* capa del arranque
+tiene que escribir a `/dev/tty0`, no al `console` heredado. Arreglar una sola capa deja el agujero
+tapado y la siguiente vuelve a caer.
+
+Reproducir el escenario de metal sin salir del laptop:
+
+```sh
+qemu-system-x86_64 -m 4096 -enable-kvm -cpu host -display none -vga std -serial null \
+  -drive if=pflash,unit=0,format=raw,readonly=on,file=/usr/share/edk2/x64/OVMF_CODE.4m.fd \
+  -drive if=pflash,unit=1,format=raw,file=work/.efi-vars-usbtest.fd \
+  -drive if=none,id=usbstick,format=raw,file=work/hammer-cosmic-metal.img \
+  -device qemu-xhci,id=xhci -device usb-storage,bus=xhci.0,drive=usbstick \
+  -qmp unix:/tmp/qmp.sock,server,nowait     # el veredicto es el screendump, no el log
+```
+
+De paso: el rebuild avisa `! sin hammer musl` ⇒ **el CLI `hammer` no está en la imagen** y
+`hammer boot menu` nunca corre. Igual lleva `timeout 15`, porque corre ANTES del `exec` de arje-zero
+y colgarse ahí deja un arranque sin PID1 ni pantalla — el `|| true` protege del fallo, no del bloqueo.
+
 ### Qué mirar si la pantalla queda negra
 
 Es el fallo que ya nos pasó una vez y tiene una causa aburrida. En orden de probabilidad:
 
-1. **No es un cuelgue, es el prompt invisible.** Ya está arreglado (`tty1-getty`), pero si vuelve:
-   los printk van a las dos consolas y el shell a una sola.
+1. **No es un cuelgue, es el prompt invisible.** Ya está arreglado (`tty1-getty` + el log del pivote
+   a `tty0`), pero si vuelve: los printk van a las dos consolas y el userspace a una sola.
 2. **`ls /usr/lib/dri`** — si sólo hay `iris_dri.so` y la GPU no es Intel, no hay GL. Esta imagen es
    Intel-only a propósito; para otra máquina va la imagen dual de KDE.
 3. **`cosmic-comp` sin DRM master**: `dmesg | grep -i drm` y `ls -l /dev/dri/card0`. Sin `seatd` o