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 — la calculadora del lanzador ANDA (ver abajo) | `b3:edb8d14d` |
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`: la calculadora del lanzador, y un `stdin` que era `stdout`
485
486**`=123*456` → `56088` en el lanzador** (`cosmic-calculadora-qemu-2026-08-04.png`). La cadena entera
487desde una tecla está en el catálogo: `Super` → cosmic-launcher → pop-launcher → plugin `calc` →
488`qalc` → **mpfr → gmp**.
489
490Pero el camino hasta ahí tuvo dos muros que vale la pena dejar escritos, porque ninguno se parecía a
491lo que era.
492
493**1) `stdin` apuntaba al descriptor 1.** El plugin no le pasa la cuenta por argv: arranca `qalc` SIN
494expresión, con stdin en tubería, le escribe la expresión y cierra. En ese modo el binario **no leía
495nada** — ni error ni resultado, la fila del lanzador salía en blanco. El síntoma acusaba a readline,
496al toolchain y a la versión, y no era ninguno:
497
498```
499DIAG-main isatty=0 feof=0 ferror=0 fd=1        ← fileno(stdin) == 1
500nm -S qalc | grep -E ' (stdin|stdout|stderr)$'
501  1847148 8 B stderr
502  1847148 8 B stdin                             ← las TRES en la misma dirección
503  1847148 8 B stdout
504```
505
506La causa: **el binario salía DINÁMICO aunque la receta dice `link = "static"`, porque libtool se come
507el `-static` que inyecta el harness** ([[link-static-mentira-libtool]] otra vez, cuarto caso). Y en
508un musl dinámico las tres variables de stdio se resolvieron por *copy relocation* a **una sola ranura
509de BSS compartida**: la última que escribe el loader gana, así que el `stdin` del programa era el
510`stdout`. De ahí la asimetría que parecía absurda: `qalc -f /dev/stdin` funcionaba —abre el
511descriptor por RUTA, sin tocar el `FILE*` roto— y `qalc` leyendo `stdin` no.
512
513El fix es el par que ya usa `libxml2`: `make LDFLAGS="-all-static -no-pie"`. Con él el binario queda
514estático de verdad y los tres símbolos vuelven a tener direcciones distintas, en `.rodata`:
515
516```
517  11e71c8 8 R stderr
518  11e71d0 8 R stdin
519  11e71d8 8 R stdout
520```
521
522**La regla, y es de las caras: `link = "static"` en la receta no garantiza un binario estático.**
523Cuando algo se comporta como si su `stdin`/`stdout` estuvieran cruzados, `readelf -d` y
524`nm -S | grep ' std'` contestan en dos segundos lo que el log no dice nunca.
525
526Barrido de la cola entera con ese criterio, después del fix: de las 7 recetas que declaran
527`link = "static"` (`cosmic-session`, `gmp`, `mpfr`, `nasm`, `libqalculate` y las dos que en realidad
528son `dynamic`), **ninguna tiene `NEEDED` indebido y ninguna tiene los símbolos de stdio aliasados**.
529Era un caso, no un patrón — pero el patrón que lo causa (libtool comiéndose el `-static`) ya tiene
530cuatro víctimas anteriores en el corpus.
531
532**2) La pregunta de primer arranque se come la cuenta, SIEMPRE.** Antes de leer nada, `qalc` pregunta
533si activar `autocalc`. El plugin le manda la expresión y cierra: la expresión se consume como
534respuesta, no es un sí/no válido, y qalc **no llega a guardar config** ⇒ la próxima vez vuelve a
535preguntar. No es «falla la primera vez»: no anda nunca. Se siembra
536`~/.config/qalculate/qalc.cfg` con `calculate_as_you_type=0` desde `cosmic-start` — política de la
537imagen, como el color de fondo; una distro de verdad lo pondría en `/etc/skel`.
538
539**Gotchas de empaquetado de la cadena:**
540- **`gmp` va con `--disable-assembly`.** Elige rutinas en ensamblador mirando la CPU de quien
541  compila, o sea hornearía la ISA del laptop en el artefacto y el hash dejaría de significar lo mismo
542  en la granja. Es una calculadora de escritorio: la implementación en C portable sobra.
543- **El configure de libqalculate no encuentra readline** porque prueba `-lreadline` junto a
544  `-lncurses`, `-lcurses`, `-ltermcap` y `-ltinfo`, y el corpus **sólo empaqueta `libncursesw.a`**.
545  Que el paquete se llame `ncurses` no significa que provea `-lncurses`. Los alias van en un
546  directorio LOCAL (`.curses-compat/`) y no en `/usr/lib`: esa vista es la evidencia de qué se
547  declaró, y ensuciarla para que pase un test deja mintiendo justo al mecanismo que existe para no
548  mentir. Ojo: hay que repetir el `-L` en el `make`, porque el `LDFLAGS` del `make` PISA al del
549  `configure`.
550
551### ⏱ El panel tiene un DEADLINE de arranque: con 4 vCPU sale mutilado
552
553Medido: con `-smp 4` el panel arranca **sin ala izquierda, sin reloj y sin dock** —sólo la bandeja
554derecha— y el único rastro es `Failed to setup panel dbus server deadline has elapsed`. Con
555`-smp 8 -m 8192`: **4 arranques de 4 con el escritorio completo y cero deadlines vencidos**.
556No es carga del anfitrión (falla con el anfitrión ocioso) sino la estampida del arranque: el panel
557registra su servidor D-Bus mientras catorce clientes de iced escanean fuentes al mismo tiempo.
558
559**Y una lección de medición que costó horas: el conteo de procesos NO sirve como veredicto.**
560Perseguí una regresión inexistente comparando «48 procesos» contra «31», revirtiendo uno por uno
561tres cambios míos que no tenían nada que ver — cuando un escritorio completo y sano muestra **32**.
562El número de procesos no distingue «arrancó» de «dibujó». El framebuffer sí, y sin ambigüedad:
563**894 colores = completo, 130 = mutilado.**
564
565## Lo que falta, en orden
566
5671. **Aplicaciones con ventana.** Sigue sin haber ninguna: los 20 `.desktop` de la imagen son
568   `NoDisplay=true`, así que la biblioteca sale vacía y eso es correcto. La calculadora del lanzador
569   ya da resultados, pero es una fila de texto, no una app. `cosmic-term` sería la primera de verdad.
5702. `xdg-desktop-portal-cosmic` — sin él no hay captura de pantalla, ni file-chooser, ni compartir.
5713. `cosmic-settings` (el panel de control) y `cosmic-files`: la suite tiene aplicaciones y el
572   catálogo todavía no.
5734. `cosmic-greeter` (hoy `cosmic-session` lo lanza y falla con ENOENT, sin consecuencias) y
574   `cosmic-osd` con teclas de brillo/volumen reales.
5755. Metal: la imagen de QEMU y la de metal comparten todo menos el driver; el viaje físico es el
576   mismo que el de `metal-dual-desktop-en-curso`.