1# Runbook — COSMIC, el cuarto escritorio
2
3Estado al 2026-08-03: **LA SESIÓN COSMIC ARRANCA ENTERA.** `cosmic-session` —el camino de producción,
4no el andamio— levanta la cadena completa sobre el kernel de hammer y arje-zero como PID1:
5
6```
7cosmic-comp → cosmic-settings-daemon → cosmic-notifications → cosmic-panel
8            → cosmic-osd → cosmic-bg
9```
10
11Los que todavía no existen (`cosmic-app-library`, `cosmic-launcher`, `cosmic-workspaces`,
12`cosmic-greeter`) sólo dejan una línea de `error!` y **la sesión sigue viva** — que es exactamente lo
13que la tabla de `.expect` de más abajo predijo, verificado en vez de supuesto.
14
15![sesión COSMIC en QEMU](../evidencia/cosmic-session-qemu-2026-08-03.png)
16
17Y el paso anterior: `cosmic-comp` arranca sobre el
18kernel de hammer con arje-zero como PID1, toma el DRM, expone `wayland-1` y presenta frames; y
19`cosmic-bg` se conecta, entrega su buffer y el fondo aparece **con el color exacto que se le
20configuró** — `(0.13,0.29,0.53)` → `(33,74,135)`. O sea que la cadena cliente→compositor→KMS funciona
21de punta a punta. Este documento se escribe mientras se hace, no después.
22
23![cosmic-bg pintando en QEMU](../evidencia/cosmic-bg-qemu-2026-08-03.png)
24
25Que el color sea **el que se pidió** y no uno cualquiera es lo que hace de esto una medición y no una
26impresión: descarta que se esté viendo un buffer sin inicializar o el borrado del compositor.
27
28El paso anterior —el compositor solo, gris `(39,41,42)` y el cursor, 134 colores— quedó en
29[`cosmic-comp-qemu-2026-08-03.png`](../evidencia/cosmic-comp-qemu-2026-08-03.png), porque la
30diferencia entre las dos imágenes es exactamente la pregunta que el modo `bare` separa.
31
32COSMIC es el escritorio de System76, en Rust sobre **smithay** (compositor) e **iced/libcosmic**
33(clientes). Es el cuarto de hammer, tras [mirada](mirada-usb-nvidia.md),
34[KDE Plasma 6](kde-qemu-desktop.md) y [GNOME](gnome-qemu-desktop.md).
35
36## Por qué NO se parece a los dos anteriores
37
38KDE y GNOME costaron lo que costaron por la misma razón: una torre de C con Qt o
39glib/GObject/introspección debajo, donde cada capa se paga entera antes de ver un píxel. COSMIC no
40tiene esa torre. La primera receta —`cosmic-session`— salió **a la primera y sin una sola dep en C**:
41ELF estático, cero `NEEDED`.
42
43Lo que sí hereda es lo que ya está pago:
44
45| lo que COSMIC necesita | de dónde sale | costo |
46|---|---|---|
47| las deps en C de smithay (drm, gbm, seat, input, udev, xkb, pixman) | `mirada-compositor`, que ya es un compositor smithay de este lab | **cero** — misma lista |
48| `libdisplay-info` + `hwdata` | copiadas byte a byte de la cola GNOME | **cero** — mismo hash, artefacto ya sellado |
49| `bash`, `dbus-run-session`, `hicolor-icon-theme`, mesa-llvmpipe | corpus | cero |
50| el andamiaje de arranque en QEMU (`run-qemu-desktop.sh`, base rootfs, console-getty, screendump) | campañas KDE/GNOME | cero |
51
52La deuda propia que sí trae, y que ninguna de las otras campañas tocó, es la del **unwinder de la std
53de rustc** cuando el enlace no es estático — la misma que ya está documentada para las recetas Cargo
54del corpus.
55
56## El pin es de la SUITE, no de cada paquete
57
58COSMIC versiona **todos** sus repos en lockstep con el tag `epoch-N`. Comprobado repo por repo: los
59doce componentes están en `epoch-1.5.0`.
60
61**No mezclar epochs entre piezas.** Comparten protocolos propios (`cosmic-protocols`) y el formato de
62configuración (`cosmic-config`); un desajuste ahí no da error de compilación, da un escritorio que
63arranca y no se entiende consigo mismo — que es mucho más caro de diagnosticar.
64
65## La cola
66
67`recipes/incoming-cosmic/`, aislada (otro agente comparte el repo; nunca `git add -A`).
68
69Las deps se resuelven **hermano → padre**: desde `incoming-cosmic/` se ven las recetas de
70`recipes/`, pero **no** las de `incoming-gnome/` ni `incoming-kde/`. Por eso `libdisplay-info` y
71`hwdata` entran copiadas.
72
73**Copiar es gratis sólo si TODA la clausura transitiva resuelve a lo mismo.** El ArtifactHash no
74depende de la ruta de la receta, así que un fichero idéntico *cuyas deps resuelven igual* da el mismo
75hash ⇒ cache hit sobre el artefacto que ya existe. Se cumplió con `libdisplay-info`, `hwdata` y
76`nasm`, y se verificó con `hammer hash` **antes** de copiar (`b3:260f0519`, `b3:bdc36cf9`,
77`b3:33383070`), no después. Dónde deja de cumplirse —y por qué importa— está en la sección de
78`cosmic-settings-daemon`, más abajo.
79
80## Qué levanta la sesión, y por lo tanto el orden de ataque
81
82`cosmic-session/src/main.rs` es la lista autoritativa —el mismo método que cerró la capa JS de GNOME:
83*leé el fichero donde el programa declara lo que arranca, no lo descubras de a uno*:
84
85```
86cosmic-comp  →  cosmic-notifications · cosmic-panel · cosmic-app-library
87             →  cosmic-launcher · cosmic-workspaces · cosmic-osd · cosmic-bg · cosmic-idle
88```
89
90Más `cosmic-settings-daemon` y `xdg-desktop-portal-cosmic` fuera de esa lista.
91
92| pieza | estado | hash |
93|---|---|---|
94| `cosmic-session` | ✅ sellado | `b3:81f02351` |
95| `cosmic-icons` | ✅ sellado (671 SVGs) | `b3:94d06f77` |
96| `dav1d` 1.5.4 | ✅ sellado (dep arrastrada, ver gotcha 8) | `b3:aab7a874` |
97| **`cosmic-comp`** | ✅ **SELLADO — el gate** (filtra `ScreenReader`, ver atajos) | `b3:e871eee4` |
98| `cosmic-bg` (dinámico, PINTA) | ✅ sellado | `b3:b2cfc410` |
99| `cosmic-idle` (dinámico) | ✅ sellado | `b3:e1806acc` |
100| `pulseaudio` · `pipewire` (cadena del settings-daemon) | ✅ sellados | `b3:e1ff4736` · `b3:338d1d8c` |
101| `cosmic-panel` | ✅ sellado | `b3:ac5e48c5` |
102| `cosmic-osd` | ✅ sellado | `b3:f15cb9c1` |
103| `cosmic-settings-daemon` | ✅ sellado (filtra `ScreenReader`, ver atajos) | `b3:642919a5` |
104| `cosmic-notifications` | ✅ sellado | `b3:3e2a5478` |
105| `cosmic-launcher` | ✅ sellado | `b3:c17b4956` |
106| `cosmic-app-library` | ✅ sellado | `b3:b2a163e7` |
107| `cosmic-workspaces-epoch` | ✅ sellado (necesitó `mesa`, ver gotcha 11) | `b3:a031249e` |
108| **`cosmic-applets`** (19 binarios en uno) | ✅ **sellado** (necesitó `dbus-shared`, ver gotcha 10) | `b3:3e53a325` |
109| `pop-launcher` 1.2.7 (otro repo, ver abajo) | ✅ sellado a la primera | `b3:64a5cbaa` |
110| `gmp` 6.3.0 · `mpfr` 4.2.2 (cadena de la calculadora) | ✅ sellados a la primera | `b3:d99a0a5d` · `b3:13982d20` |
111| `libqalculate` 5.12.0 (`qalc`) | ✅ sellado — **pero el plugin del lanzador no lo puede usar, ver abajo** | `b3:6bb435a7` |
112
113**La cola está COMPLETA: 30 recetas, `escritorio-cosmic` 68/68.**
114
115**El mínimo viable de una sesión son cuatro**: `cosmic-comp` + `cosmic-settings-daemon` +
116`cosmic-notifications` + `cosmic-panel` (los tres `.expect` de la tabla de arriba).
117
118**El orden no es el de la lista de arranque.** `cosmic-bg` va antes que el panel a propósito: habla
119Wayland con `smithay-client-toolkit` y **no toca libcosmic ni iced**, mientras que panel, launcher,
120osd y workspaces son todos clientes de iced. Con el fondo sellado, «pinta el fondo pero no el panel»
121separa la capa de UI del transporte; sin él, las dos preguntas llegan juntas.
122
123### `cosmic-settings-daemon`: por qué queda al final y NO se resuelve copiando
124
125Es el único con cadena propia. Su workspace incluye `audio-server` como dep de path **no opcional**,
126que arrastra `cosmic-pipewire` → `pipewire-sys` → `libpipewire-0.3` por pkg-config. Y `pipewire` hoy
127vive sólo en las colas GNOME y KDE.
128
129**Acá el truco de copiar deja de ser gratis, y eso corrige lo que dice más arriba.** La regla completa
130es: *copiar una receta entre colas es gratis sólo si **toda su clausura transitiva** resuelve a lo
131mismo.* Se cumplió con `libdisplay-info`, `hwdata` y `nasm` —sus deps están todas en el corpus—, y
132**no** se cumple con pipewire: de sus catorce deps, cinco viven sólo en colas ajenas
133(`dbus-shared`, `alsa-lib`, `libsndfile`, `pulseaudio`, `zlib-shared`) y —lo decisivo— **`glib`
134resolvería distinto**. Desde `incoming-gnome`, `glib` es la sombra de esa cola (`b3:f6ccdf98`); desde
135`incoming-cosmic` sería la del corpus (`b3:93d2cad0`). Son recetas distintas, no la misma en dos
136lugares.
137
138O sea que copiar produciría un **segundo pipewire** construido contra otra glib, arrastrando su cadena
139entera. Y eso no es sólo caro: es exactamente el cuadro que la campaña GNOME ya midió y evitó —dos
140glib distintas con 370 rutas solapadas y dos registros de GType en un proceso—.
141
142Antes de tocar nada se midió con `yupana radio` (la puerta única, nunca `grep`): `pipewire` tiene
143radio 1 en GNOME y 2 en KDE, pero `glib` del corpus tiene **21 dependientes transitivos y afecta la
144imagen escritorio-gnome**.
145
146**Y después se midió el costo real, que resultó mucho menor que la estimación.** Copiar pipewire a
147`incoming-cosmic` necesita **cuatro** recetas hermanas —`alsa-lib`, `dbus-shared`, `libsndfile`,
148`pulseaudio`—, no las seis contadas a ojo, y **tres de ellas dan hash idéntico y ya están selladas**.
149Sólo `pulseaudio` y `pipewire` hay que construir.
150
151Eso refina la advertencia de arriba en el punto que importa: **el peligro de las dos glib es
152mezclarlas en UNA IMAGEN**, y la imagen COSMIC tiene una sola. Acá el costo es de builds, no de
153corrección. Lo que sigue vigente es no promover a ciegas entre colas.
154
155Gotcha del copiado, que cuesta un minuto de confusión: `[source] patches` se resuelve **relativo a la
156receta**, así que copiar el `.toml` sin su `.patch` da «no pude leer patch» y el hash ni siquiera se
157calcula.
158
159## 🚪 EL GATE PASADO: cosmic-comp compila (2026-08-03)
160
161`b3:b8abc52f`, 51 min 39 s de cargo con `CARGO_BUILD_JOBS=1` y `lto = "fat"`. **A la primera**, salvo
162el `--bin` del gotcha 1. Sin un solo parche a la fuente.
163
164Lo que dice el enlace es la parte que vale, porque es la medición y no la impresión:
165
166```
167NEEDED: libdisplay-info.so.2 · libgbm.so.1 · libseat.so.1 · libudev.so.1
168        libinput.so.10 · libpixman-1.so.0 · libxkbcommon.so.0 · libc.so
169```
170
171Ocho, y las siete primeras son **exactamente** los backends de smithay que la receta declara. La
172octava es musl. **No hay `libgcc_s`** — o sea que el compositor no arrastra la deuda del unwinder que
173sí tienen varias recetas Cargo del corpus, porque acá el enlace es dinámico contra musl y no hay
174`+crt-static` que forzar. Y **no aparece nada que no se haya declarado**: la clausura de build y la de
175runtime coinciden, que es la propiedad que uno quiere y casi nunca se cumple gratis.
176
177Que un compositor Wayland completo —DRM, GBM, EGL, libinput, seat, Vulkan, XWayland, un renderer
178multi-GPU y una capa de UI en iced— cierre con ocho librerías compartidas y ningún parche es el
179resultado más limpio de las cuatro campañas de escritorio.
180
181## 🖥 EL PRIMER ARRANQUE: qué falló y qué no (2026-08-03)
182
183Tres imágenes y tres causas distintas, todas medidas. Vale dejarlas porque **ninguna estaba en el
184camino que uno anticipa**, y las tres se manifestaron a varias capas de distancia de su causa.
185
186**1. `cosmic-session` no es opcional en el sentido que yo asumí — y `cosmic-settings-daemon` tampoco.**
187El compositor arrancó perfecto y le devolvió a la sesión su `WAYLAND_DISPLAY=wayland-1`; el gestor
188entonces intentó lanzar `cosmic-settings-daemon`, no lo encontró, y **panickeó**:
189
190```
191INFO  cosmic_session: got environmental variables from cosmic-comp: [("WAYLAND_DISPLAY", "wayland-1")]
192ERROR panic: 'failed to start settings daemon: NotFound' src/main.rs:255
193```
194
195Es un `.expect()`, sin feature que lo apague. **Y NO es el único — son TRES**, y esto corrige lo que
196esta misma sección afirmaba hace unas horas:
197
198| línea | componente | qué pasa si falta |
199|---|---|---|
200| `main.rs:255` | `cosmic-settings-daemon` | panic |
201| `main.rs:306` | `cosmic-notifications` | panic |
202| `main.rs:325` | `cosmic-panel` | panic |
203
204El resto (app-library, launcher, workspaces, osd, bg, idle) va por `start_component()`, que ante un
205fallo sólo hace `error!("failed to start …")` y sigue (`main.rs:558`). O sea que **el mínimo viable de
206una sesión COSMIC son cuatro binarios**: compositor + esos tres.
207
208**Cómo se equivocó el diagnóstico, que es la parte reusable**: leí `start_component()`, vi que sólo
209logueaba, y generalicé a «todos menos el settings-daemon». Pero notifications y panel **no pasan por
210esa función** — tienen su propio `.expect()` unas líneas antes. Buscar la función que lanza no es lo
211mismo que buscar los `\.expect(` del fichero; **grepear la construcción que mata cuesta lo mismo y no
212generaliza de más**. **Esto corrige lo que decía la sección de
213cosmic-settings-daemon**: no es que sin él se pierdan el brillo y el tema, es que **no hay sesión**.
214Queda por eso el modo `bare` en `cosmic-start` —el camino que upstream ya soporta como
215`install-bare-session`—: se lanza el compositor solo y los clientes a mano contra su WAYLAND_DISPLAY.
216Separa «¿compone?» de «¿arranca la sesión?», que son dos preguntas y estaban viniendo juntas.
217
218**2. La pantalla negra era `libz.so.1`.** El corpus trae `zlib` estática, que le alcanza a todo el
219cierre de COSMIC. Pero `kms_swrast_dri.so` es un `.so` que mesa abre con `dlopen` y NEEDea
220`libz.so.1`:
221
222```
223MESA-LOADER: failed to open kms_swrast: Error loading shared library libz.so.1
224WARN  cosmic_comp::backend::kms: Failed to add device /dev/dri/card0: Failed to initialize GBM device
225```
226
227Sin driver de software no hay GBM, y **el compositor arranca igual y presenta una pantalla negra**. La
228causa está a tres capas del síntoma. Se arregla agregando `zlib-shared` como raíz del hidratador.
229
230**3. Los clientes NO pueden ser estáticos.** `cosmic-bg` moría con «The wayland library could not be
231loaded» **teniendo `libwayland-client.so.0` en el rootfs**. `wayland-client` entra con la feature
232`dlopen`: carga libwayland en runtime en vez de enlazarla, y **un binario musl estático no tiene
233dlopen funcional**. No faltaba la librería: faltaba poder abrirla. Todos los clientes pasan a
234`link = "dynamic"`.
235
236**Lo que NO falló, y conviene decirlo:** el compositor no necesitó un solo parche, ni una perilla de
237KMS, ni forzar modeset legacy. Las cuatro perillas de render por software heredadas de KDE y GNOME
238(`GBM_ALWAYS_SOFTWARE`, `kms_swrast`, `LP_NUM_THREADS=1`) alcanzaron. GNOME costó cinco muros para
239llegar a este punto; COSMIC costó tres, y ninguno era del compositor.
240
241### Dos carreras con /run, la misma causa
242
243`dbus-daemon --system` falló con «Failed to bind socket /run/dbus/system_bus_socket: No such file or
244directory» **aunque el directorio se creaba al principio del script**, y dbus-run-session se quejó
245por su lado de que `XDG_RUNTIME_DIR` no existía. Entre el arranque del getty y el uso pasan varios
246segundos en los que arje-zero sigue montando, y un tmpfs sobre `/run` se lleva puesto lo que hubiera.
247**Crear justo antes de usar** es la única forma de no depender de ese orden; comprobar al principio y
248usar al final es exactamente cómo se cuela una carrera — la misma forma del bug de PolicyKit1 que se
249cerró hoy en GNOME.
250
251## Gotchas medidos (no previstos)
252
2531. **`cargo rustc --` exige UN target.** La fase compile del lab pasa flags tras el `--`, y cualquier
254   paquete con binario + lib + ejemplos corta con «extra arguments to `rustc` can only be passed to
255   one target». Se arregla con `flags = ["--bin", "<nombre>"]`. Le pasa a cosmic-comp y a cosmic-bg
256   (workspace con `config/`), y le va a pasar a casi todos: **ponelo desde el principio.**
2572. **`start-cosmic` es bash de verdad, no sh.** Usa `mapfile`, `[[ ]]` y expansión indirecta
258   `${!var}`; con el busybox del rootfs no arranca. `bash` ya está en el corpus, pero **tiene que
259   entrar en la imagen** — y no lo pide ningún `[deps]`, así que no lo va a traer nadie por accidente.
260   Lo mismo con `dbus-run-session` (de `dbus`), que es lo que el script exec-uta al final.
2613. **`rust-toolchain.toml` con `channel = "1.93"` es inerte acá** — es una perilla de rustup, y el
262   sandbox tiene el rustc de Alpine (1.96) pelado. Conviene saberlo antes de «arreglarlo».
2634. **`cosmic.desktop` existe DOS veces** (en cosmic-session y en cosmic-comp) con contenido distinto
264   y en la misma ruta. El de cosmic-comp es el de la «bare session» y apunta a `/usr/bin/cosmic-service`,
265   que vive en la rama de systemd que acá no va. Se instala **sólo** el de cosmic-session; si entraran
266   los dos, quién gana depende del orden de hidratación y el que pierde es el bueno.
2675. **`libsystemd` no es systemd.** La feature `default = ["systemd"]` de cosmic-comp trae el crate
268   `libsystemd`, que es una **reimplementación en Rust** del protocolo, no un binding a la C. Y
269   `logind` habla `org.freedesktop.login1`, que acá lo sirve `arje-logind-compat`. No hay que apagar
270   nada: el nombre de la feature es el del protocolo, no el del programa que lo contesta.
2716. **Las features de smithay que asustan no cuestan deps de build**: `backend_vulkan` (crate `ash`),
272   `backend_x11` (`x11rb` con `dl-libxcb`) y `xwayland` cargan todo por **dlopen**. Son deuda de
273   RUNTIME —libxcb y vulkan-loader viven hoy sólo en la cola KDE—, no un muro de compilación.
2747. **Todo cliente de la suite lleva las MISMAS CUATRO deps: `libxkbcommon`, `pkgconf`,
275   `libudev-zero`, `libinput`** — incluso las piezas sin interfaz. Las tres primeras se descubrieron
276   de a una, un build por dep, hasta que la línea de enlace las mostró juntas:
277
278   ```
279   -Wl,-Bstatic  -ludev  -linput  -lxkbcommon …
280   ```
281
282   **El error dice la que falta primero; el COMANDO dice todas.** Leerlo entero la primera vez habría
283   ahorrado tres builds. Los tres llegan por la cadena de libcosmic —enumeración de monitores y de
284   dispositivos de entrada—, no por nada que el cliente haga a la vista.
285
286   Y el camino hasta ahí fue de razonamientos buenos y falsos, que es lo que vale dejar escrito:
287   - `cosmic-bg` fue sin `[deps]` porque «habla el protocolo en Rust y no toca C». Reventó en el
288     `build.rs` de `smithay-client-toolkit` pidiendo `xkbcommon.pc`: **sctk ENLAZA libxkbcommon**; el
289     que la dlopea es `winit`, que es otra capa. Hablar Wayland en Rust dice cómo viaja el byte, no
290     con qué se interpreta un teclado.
291   - `cosmic-idle` fue sin `[deps]` porque *ese* argumento ya no aplicaba —no usa sctk— y un demonio
292     de inactividad no interpreta teclas. Reventó en el ENLACE con `-lxkbcommon`, arrastrado por
293     **`cosmic-settings-config`**: de ahí sale la tabla de atajos y la usa **todo** componente de la
294     suite. La dep no viene de lo que el paquete hace, sino de la librería de configuración común.
295
296   La lección de método vale más que la dep: **la dep no se deduce de la función del paquete.** Está
297   escrita en el `build.rs` que panickea o en la línea de enlace, y las dos veces el error dijo
298   exactamente quién y por qué. El `link = "static"` sobrevive porque el artefacto de libxkbcommon
299   trae `.a` además de `.so`.
3008. **Una feature apagada en el paquete puede estar prendida por otro.** `cosmic-bg` declara `image`
301   con `default-features = false` y sin AVIF, y aun así compila `dav1d-sys`: **las features de cargo
302   se UNIFICAN en el grafo**. Se resolvió trayendo `dav1d` (b3:aab7a874) en vez de parchear el
303   Cargo.toml de upstream — si el grafo dice que sabe decodificar AVIF, que lo sepa de verdad.
304   Mismo modo de falla que un `.pc Requires` arrastrando una dep que nadie declaró.
305
3069. **`cosmic-wallpapers` no se puede empaquetar del tarball: está en git-lfs.** El default de
307   cosmic-bg apunta a `/usr/share/backgrounds/cosmic/orion_nebula_nasa_heic0601a.jpg`, y el archivo
308   de GitHub de ese repo pesa **20 KB** — son punteros LFS, no imágenes. Una receta escrita del modo
309   normal produciría un paquete de ficheros de texto que además *parecería* correcto: se instalarían
310   con el nombre bueno en la ruta buena. Mientras tanto `cosmic-start` escribe la config de USUARIO
311   con una fuente `Color`, que cosmic-bg soporta de fábrica — y va en el lanzador, no en el artefacto,
312   porque es política de la imagen de prueba y no algo que el paquete prometa.
313
31410. **`build.rs` contento ≠ linker contento: `cosmic-applets` necesita la libdbus COMPARTIDA.**
315    Los applets de red, bluetooth y status-area hablan D-Bus por `libdbus-sys` (FFI a la C, no zbus
316    como el resto de la suite). Declarar `dbus` a secas alcanza para que su `build.rs` pase —le basta
317    el `.pc`, que el paquete del daemon trae— y el fallo aparece **una hora después, en el enlace
318    final del multiplexor**: `unable to find dynamic system library 'dbus-1'`. El corpus sólo
319    empaqueta `libdbus-1.a`; el `.so` vive en `dbus-shared`. Son dos preguntas distintas y las
320    contestan dos herramientas distintas: pkg-config dice si la dep *existe*, el linker si hay algo
321    que *enlazar*. Era la única receta de la cola que pedía la estática.
322
32311. **`cosmic-workspaces` necesita `mesa`, y la dep sale de lo que el programa MUESTRA.** La vista de
324    espacios de trabajo dibuja miniaturas vivas de las ventanas; el compositor se las pasa como
325    DMA-BUF por `zcosmic-toplevel-info` y el cliente importa el fd con GBM ⇒ `-lgbm`. Es el único
326    cliente de la suite que toca el pipeline gráfico además del compositor, así que el juego fijo de
327    cuatro (`libxkbcommon`, `pkgconf`, `libudev-zero`, `libinput`) no alcanza. Corolario del gotcha
328    de siempre: la dep no se deduce de la familia del paquete, se lee de lo que hace.
329
33012. **DOS GPUs en QEMU = el panel dibuja en la pantalla que no mirás.** `-device virtio-gpu-pci` no
331    reemplaza a la VGA por defecto de QEMU: la SUMA. El invitado ve `card0` y `card1`, cosmic-comp
332    crea dos outputs (`Virtual-1` y `Unknown-1`), `cosmic-bg` pinta el fondo en ambos y el panel se
333    ancla en uno solo. El `screendump` captura el otro ⇒ **fondo perfecto, panel invisible, y ni un
334    solo error en el log**. Con `-vga none` el escritorio aparece entero a la primera.
335    **Y esto corrige un diagnóstico anterior de este mismo runbook**: cuando el panel selló y no
336    dibujó, lo atribuí a que le faltaban los applets. Los applets hacían falta —sin ellos el panel
337    está vacío— pero **no eran la causa de la pantalla lisa**; la causa era la segunda GPU, que ya
338    estaba ahí. Un síntoma puede tener dos causas suficientes y arreglar la primera no prueba nada:
339    la prueba es la pantalla, no el razonamiento.
340
34113. **`mkdir: not found` en `cosmic-start`, y la sesión arrancaba igual.** El getty entrega un PATH
342    sin `/usr/bin`, y en la imagen fundida `mkdir` sólo vive ahí (`/usr/bin/mkdir → coreutils`; la
343    base metal no tendió el symlink `/bin/mkdir → busybox` que sí tienen chmod, mount, sed y tee).
344    Los cuatro `mkdir -p` de la preparación fallaban y **no se notaba**, porque los directorios
345    venían horneados en la imagen. Es la forma más traicionera de bug: gratis hoy, fatal el día que
346    alguien cambie cómo se arma la imagen. Fix: exportar `PATH` como primera línea del script.
347
348## Cómo se construye
349
350```sh
351cd ~/hammer
352./target/release/hammer --store store hash recipes/incoming-cosmic/<pieza>.toml   # dry-run, ~2ms
353./target/release/hammer build recipes/incoming-cosmic/<pieza>.toml --store store
354```
355
356## 🏔 EL ESCRITORIO ENTERO, DIBUJADO (2026-08-04)
357
358`docs/evidencia/cosmic-panel-applets-qemu-2026-08-04.png` — 1280×800, **895 colores distintos**:
359
360- **panel superior** (banda `(27,27,27)`, 32 px): botones *Workspaces* y *Applications* a la
361  izquierda, reloj al centro, y a la derecha los applets de accesibilidad, audio, red, batería y
362  encendido;
363- **dock inferior** centrado y redondeado, con lanzador, workspaces, biblioteca de aplicaciones y
364  las entradas `.desktop` del rootfs;
365- fondo `(33,74,135)` = exactamente el `Color(Single((0.13,0.29,0.53)))` que escribe `cosmic-start`.
366
36748 procesos `cosmic-*` estables a los 30 s, sobre el kernel de hammer con arje-zero como PID1.
368Se reproduce así (headless y automatizable; **el `-vga none` no es opcional**, ver gotcha 12):
369
370```sh
371COSMIC_MODE=session bash scripts/cosmic/qemu-desktop-image.sh
372qemu-system-x86_64 -machine q35,accel=kvm -cpu host -smp 8 -m 8192 \   # 8 vCPU: ver el deadline del panel
373  -drive if=pflash,format=raw,readonly=on,file=/usr/share/edk2/x64/OVMF_CODE.4m.fd \
374  -drive if=pflash,format=raw,file=/tmp/OVMF_VARS.fd \
375  -drive file=work/hammer-cosmic-qemu.img,format=raw,if=virtio \
376  -vga none -device virtio-gpu-pci,xres=1280,yres=800 \
377  -device qemu-xhci,id=xhci -device usb-kbd,bus=xhci.0 -device usb-tablet,bus=xhci.0 \
378  -display none -serial file:/tmp/cosmic.serial -qmp unix:/tmp/qmp.sock,server,nowait
379# y después, por QMP: {"execute":"screendump","arguments":{"filename":"/tmp/shot.ppm"}}
380```
381
382El veredicto es **contar colores distintos del PPM**, no leer el log: con dos GPUs el log salía
383impecable y la pantalla estaba lisa.
384
385## 🖱 LA ENTRADA: se usa, no sólo se ve (2026-08-04)
386
387**Hay que usar USB HID, no virtio-input.** El kernel de hammer no trae `VIRTIO_INPUT` (mirá el
388`-e …` de `recipes/linux-generic.toml`), así que `-device virtio-keyboard` no produce ni un
389`/dev/input/event*`. Sí trae `USB_XHCI_HCD` + `USB_HID` + `INPUT_EVDEV`, y además es lo que se va a
390usar en metal, así que la prueba es más fiel:
391
392```
393-device qemu-xhci,id=xhci -device usb-kbd,bus=xhci.0 -device usb-tablet,bus=xhci.0
394```
395
396`usb-tablet` y no `usb-mouse`: reporta coordenadas ABSOLUTAS, y QMP sólo sabe mandar eventos `abs`
397(el eje va de 0 a 32767 sobre el ancho/alto de la pantalla, no en píxeles).
398
399**Se maneja entero por QMP**, sin ver la pantalla y sin humano:
400
401```jsonc
402// mover el puntero a (155,16) — el botón «Applications»
403{"execute":"input-send-event","arguments":{"events":[
404  {"type":"abs","data":{"axis":"x","value":3968}},
405  {"type":"abs","data":{"axis":"y","value":655}}]}}
406// click
407{"execute":"input-send-event","arguments":{"events":[{"type":"btn","data":{"down":true,"button":"left"}}]}}
408{"execute":"input-send-event","arguments":{"events":[{"type":"btn","data":{"down":false,"button":"left"}}]}}
409// una tecla
410{"execute":"input-send-event","arguments":{"events":[
411  {"type":"key","data":{"down":true,"key":{"type":"qcode","data":"c"}}},
412  {"type":"key","data":{"down":false,"key":{"type":"qcode","data":"c"}}}]}}
413```
414
415**El veredicto también es de píxeles, y conviene medirlo por REGIÓN.** El click en *Applications*
416llevó el color dominante de `(33,74,135)` (fondo, 91 %) a `(27,27,27)` (84 %): la biblioteca de
417aplicaciones se abrió a pantalla casi completa. Y para el teclado, contar colores del rectángulo del
418buscador (440..840 × 80..112) bastó: 155 → 118 colores al reemplazarse el placeholder por lo tecleado.
419Evidencia: `cosmic-app-library-click-qemu-2026-08-04.png` y `cosmic-teclado-busqueda-qemu-2026-08-04.png`.
420
421**La biblioteca sale vacía y está BIEN.** Los 20 `.desktop` de la imagen son `NoDisplay=true` —son
422applets y componentes de sesión, no aplicaciones—, así que no hay nada que listar. Que la búsqueda no
423devuelva resultados no es un fallo del escritorio: es que la distro todavía no tiene ni una sola
424aplicación gráfica. Se sabrá arreglado cuando entre `cosmic-files` o un terminal.
425
426### 🔑 Los atajos: dos ficheros envenenados por la misma línea
427
428`Super+A` abre la biblioteca y `Super+W` la vista de espacios de trabajo
429(`cosmic-super-w-workspaces-qemu-2026-08-04.png`, con **miniatura viva** del escritorio dentro — o
430sea que el camino DMA-BUF→GBM del gotcha 11 anda de verdad). Para llegar ahí hubo que sanear DOS
431ficheros de datos, no uno:
432
433| fichero | lo instala | qué liga |
434|---|---|---|
435| `…Shortcuts/v1/defaults` | `cosmic-comp` | tecla → acción |
436| `…Shortcuts/v1/system_actions` | `cosmic-settings-daemon` | acción → comando |
437
438Los dos traen una entrada `ScreenReader`, una variante que `cosmic-settings-config` —el crate que los
439parsea, pineado por cargo en la rev `8c54bbbc`— todavía no tiene en su enum. **RON no ignora lo que
440no conoce: falla la deserialización del MAPA COMPLETO.** Con `defaults` roto no hay ligaduras; con
441`system_actions` roto hay ligadura pero ningún comando que ejecutar. Hacen falta los dos `grep -v`.
442
443**Y acá me equivoqué de fichero teniendo el dato exacto delante.** El error decía
444`3:5-3:17: Unexpected variant named 'ScreenReader'` — con línea y columna. Busqué el *token* en vez
445de preguntarme *qué fichero lo tiene en esa posición*, di con `keybindings.ron` (que también lo
446traía, en la línea 94), lo arreglé, reconstruí `cosmic-comp` **cuarenta minutos** y el error salió
447igualito. Era otro fichero, de otro paquete. *Cuando el error trae coordenadas, la primera pregunta
448es de qué fichero son, no dónde más aparece esa palabra.*
449
450**Es el riesgo del pin lockstep asomando desde adentro de upstream**: el dato y el parser del *mismo*
451epoch no coinciden.
452
453**`Super` abre el lanzador** — pero hizo falta un paquete más, y de otro repo: ver abajo.
454
455### 🔎 `pop-launcher`: el lanzador es DOS programas
456
457`Super` no abría nada y el único rastro era una línea que no menciona ninguna tecla:
458`ERROR pop-launcher failed to start: No such file or directory`. **`cosmic-launcher` es sólo la
459interfaz**: dibuja la lista y manda lo tecleado por stdin a un proceso hijo, `pop-launcher`, que es
460quien busca. Sin ese binario la ventana no tiene qué mostrar, así que no se muestra — el mismo modo
461de falla que el panel sin applets: *lo que falta es un HIJO, no una librería, y el log del padre se
462lee sano.*
463
464Vive en **otro repo** (`pop-os/launcher`), no versiona por `epoch-N` y no entra en el pin lockstep.
465**La versión la fija el `Cargo.lock` de cosmic-launcher** —rev `a332a3a7` de la 1.2.7—, no el último
466tag del repo: el lock es lo que garantiza que hablen el mismo protocolo. El tarball se pide por
467commit (`/archive/<sha>.tar.gz`), porque no hay tag que nombre esa rev. Selló a la primera
468(`b3:64a5cbaa`) con **un solo `NEEDED`: `libc.so`**.
469
470Es otro **multiplexor por symlink**, como cosmic-applets: un binario, y cada plugin es un enlace con
471su nombre dentro de su propio directorio junto al `plugin.ron` que lo describe. El servicio enumera
472`plugins/*/`; si está el `.ron` y falta el enlace —o al revés— el plugin no existe para él, **sin
473error**. Ojo con el `sed 's/_/-/'` de upstream: cambia sólo el primer guión bajo, así que el
474directorio es `desktop_entries` y el ejecutable de adentro `desktop-entries`. Son dos nombres
475distintos a propósito.
476
477Verificado de punta a punta (`cosmic-super-lanzador-`, `cosmic-pop-launcher-plugins-`,
478`cosmic-pop-launcher-calc-qemu-2026-08-04.png`): `Super` abre el lanzador, `?` lista los seis plugins
479con su sintaxis —o sea que la enumeración y el IPC JSON-sobre-stdio andan— y `=2+2` **lanza el
480plugin, que contesta «qalc command is not installed»**. Esa respuesta es la mejor prueba que había
481disponible: el proceso hijo corrió, evaluó la consulta y devolvió una fila. Lo que falta ahora es
482`libqalculate` (el binario `qalc`), que es un paquete, no un problema.
483
484### 🧮 `libqalculate`: empaquetado y andando, e inservible para el plugin
485
486`qalc` está sellado y **funciona**: `qalc -t '2+2'` → `4`, `-f fichero`, y el modo interactivo sobre
487una terminal calcula perfecto (`123 × 456 = 56088`). La cadena que baja desde una tecla —`Super` →
488cosmic-launcher → pop-launcher → plugin `calc` → `qalc` → **mpfr → gmp**— está entera en el catálogo.
489
490**Y aun así el lanzador sigue mostrando una fila vacía.** El plugin no le pasa la cuenta por argv:
491arranca `qalc` SIN expresión, con stdin y stdout en tubería, le ESCRIBE la expresión y cierra. Ese
492modo, en nuestro binario, no lee nada. Acotado con dos invocaciones que sólo difieren en cuándo llega
493el EOF:
494
495```sh
496{ printf '123*456\n'; sleep 3; } | qalc   # LEE (aparece la pregunta de primer arranque)
497  printf '123*456\n'             | qalc   # NO lee NADA: imprime el prompt y sale con rc=0
498```
499
500O sea: **con el EOF ya pendiente en un stdin que no es terminal, `readline()` devuelve NULL antes de
501entregar la línea que sí está en el búfer** — y así es exactamente como lo invoca el plugin.
502
503Lo que ya se DESCARTÓ midiendo, para que nadie lo repita:
504- **No es el toolchain.** Una sonda estática musl del propio sandbox (C y C++) lee la tubería sin
505  problema. El binario no tiene nada raro: un solo `NEEDED`, `libc.so`.
506- **No es readline vs no-readline.** Sin readline es peor (no lee nunca, ni con la tubería abierta);
507  con readline al menos lee cuando el escritor no ha cerrado.
508- **No es la versión de readline.** Se construyó una 8.3 como sombra de cola y el síntoma no se
509  movió; la sombra se descartó en vez de dejar una receta duplicada que no arregla nada.
510- **No es el descriptor 0.** `qalc -f /dev/stdin` —el MISMO pipe, reabierto por ruta— sí funciona.
511  El que no sirve es el `FILE*` `stdin`.
512
513La pista que queda es justamente esa última asimetría. Y el aviso de método: **empaquetar el binario
514que falta no garantiza que el consumidor lo pueda usar** — «qalc no está instalado» y «qalc está y no
515contesta» son dos estados distintos, y el segundo se ve peor porque la fila sale en blanco.
516
517### ⏱ El panel tiene un DEADLINE de arranque: con 4 vCPU sale mutilado
518
519Medido: con `-smp 4` el panel arranca **sin ala izquierda, sin reloj y sin dock** —sólo la bandeja
520derecha— y el único rastro es `Failed to setup panel dbus server deadline has elapsed`. Con
521`-smp 8 -m 8192`: **4 arranques de 4 con el escritorio completo y cero deadlines vencidos**.
522No es carga del anfitrión (falla con el anfitrión ocioso) sino la estampida del arranque: el panel
523registra su servidor D-Bus mientras catorce clientes de iced escanean fuentes al mismo tiempo.
524
525**Y una lección de medición que costó horas: el conteo de procesos NO sirve como veredicto.**
526Perseguí una regresión inexistente comparando «48 procesos» contra «31», revirtiendo uno por uno
527tres cambios míos que no tenían nada que ver — cuando un escritorio completo y sano muestra **32**.
528El número de procesos no distingue «arrancó» de «dibujó». El framebuffer sí, y sin ambigüedad:
529**894 colores = completo, 130 = mutilado.**
530
531## Lo que falta, en orden
532
5331. **Aplicaciones.** No hay ni una: los 20 `.desktop` de la imagen son `NoDisplay=true`. El primer
534   candidato barato es `libqalculate` (el binario `qalc`), que es lo único que le falta al plugin de
535   la calculadora para dar un resultado en vez de decir que no está.
5362. `xdg-desktop-portal-cosmic` — sin él no hay captura de pantalla, ni file-chooser, ni compartir.
5373. `cosmic-settings` (el panel de control) y `cosmic-files`: la suite tiene aplicaciones y el
538   catálogo todavía no.
5394. `cosmic-greeter` (hoy `cosmic-session` lo lanza y falla con ENOENT, sin consecuencias) y
540   `cosmic-osd` con teclas de brillo/volumen reales.
5415. Metal: la imagen de QEMU y la de metal comparten todo menos el driver; el viaje físico es el
542   mismo que el de `metal-dual-desktop-en-curso`.