@legios/quartermaster 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +1276 -0
  3. package/bin/qm +66 -0
  4. package/bin/qm-barra +63 -0
  5. package/bin/qm-barra.swift +1253 -0
  6. package/bin/qm-indicator +2063 -0
  7. package/bin/qm-tray +41 -0
  8. package/bin/qm-tray.ps1 +1241 -0
  9. package/bin/qm-web +137 -0
  10. package/dist/adapters/cache-cuota.js +45 -0
  11. package/dist/adapters/cache-cuota.js.map +1 -0
  12. package/dist/adapters/cache-endpoint.js +66 -0
  13. package/dist/adapters/cache-endpoint.js.map +1 -0
  14. package/dist/adapters/codex.js +462 -0
  15. package/dist/adapters/codex.js.map +1 -0
  16. package/dist/adapters/credenciales.js +88 -0
  17. package/dist/adapters/credenciales.js.map +1 -0
  18. package/dist/adapters/cuota.js +73 -0
  19. package/dist/adapters/cuota.js.map +1 -0
  20. package/dist/adapters/historial.js +103 -0
  21. package/dist/adapters/historial.js.map +1 -0
  22. package/dist/adapters/opencode.js +214 -0
  23. package/dist/adapters/opencode.js.map +1 -0
  24. package/dist/adapters/transcripciones.js +129 -0
  25. package/dist/adapters/transcripciones.js.map +1 -0
  26. package/dist/adapters/utilizacion.js +151 -0
  27. package/dist/adapters/utilizacion.js.map +1 -0
  28. package/dist/cli/demo-h1.js +60 -0
  29. package/dist/cli/demo-h1.js.map +1 -0
  30. package/dist/cli/preflight.js +39 -0
  31. package/dist/cli/preflight.js.map +1 -0
  32. package/dist/cli/qm.js +779 -0
  33. package/dist/cli/qm.js.map +1 -0
  34. package/dist/core/config.js +63 -0
  35. package/dist/core/config.js.map +1 -0
  36. package/dist/core/perfiles.js +139 -0
  37. package/dist/core/perfiles.js.map +1 -0
  38. package/dist/core/proyeccion.js +83 -0
  39. package/dist/core/proyeccion.js.map +1 -0
  40. package/dist/core/tipos.js +101 -0
  41. package/dist/core/tipos.js.map +1 -0
  42. package/dist/render/barras.js +62 -0
  43. package/dist/render/barras.js.map +1 -0
  44. package/dist/render/tablero.html +664 -0
  45. package/package.json +59 -0
  46. package/src/render/tablero.html +664 -0
package/README.md ADDED
@@ -0,0 +1,1276 @@
1
+ <div align="center">
2
+
3
+ <img src="docs/img/logo-256.png" alt="" width="96" height="96">
4
+
5
+ # quartermaster
6
+
7
+ **Cuánta cuota te queda, en todas tus cuentas de agentes.**
8
+ Cada perfil de Claude Code y, si están instalados, Codex y los proveedores de opencode.
9
+
10
+ [Landing](https://quartermaster.legios.com.ar/) ·
11
+ [Instalar](#instalar) ·
12
+ [Releases](https://github.com/legiosai/quartermaster/releases) ·
13
+ MIT
14
+
15
+ <sub>Un instrumento de</sub><br>
16
+ <a href="https://github.com/legiosai"><picture>
17
+ <source media="(prefers-color-scheme: dark)" srcset="docs/legios.svg">
18
+ <source media="(prefers-color-scheme: light)" srcset="docs/legios-claro.svg">
19
+ <img alt="Legios" src="docs/legios-claro.svg" width="132" height="43">
20
+ </picture></a>
21
+
22
+ <img src="docs/img/barra.png" alt="La barra de arriba de GNOME con un medidor por cuenta" width="480">
23
+
24
+ </div>
25
+
26
+
27
+ > **Misión.** Que nadie se entere de que se quedó sin cuota chocándose contra el
28
+ > límite.
29
+
30
+ Ver [`SOUL.md`](SOUL.md) para la métrica, los non-goals y la apuesta falsable.
31
+
32
+ ## Instalar
33
+
34
+ ```sh
35
+ brew install legiosai/tap/quartermaster # macOS y Linux
36
+ npm install -g @legios/quartermaster # cualquier lado
37
+ ```
38
+
39
+ En Debian y Ubuntu, el `.deb` de la [última
40
+ release](https://github.com/legiosai/quartermaster/releases/latest):
41
+
42
+ ```sh
43
+ sudo apt install ./quartermaster_0.1.3_all.deb
44
+ ```
45
+
46
+ O desde el repo, sin instalar nada global:
47
+
48
+ ```sh
49
+ git clone https://github.com/legiosai/quartermaster && cd quartermaster
50
+ npm install && make instalar # deja `qm` en ~/.local/bin
51
+ ```
52
+
53
+ Necesita **Node >= 22.6**: `qm` lee el TypeScript sin paso de build, y eso
54
+ recién existe desde ahí. El lanzador lo busca en el `PATH` y en las versiones de
55
+ nvm; si no encuentra uno que sirva, lo dice y explica cómo conseguirlo. Por eso
56
+ el `.deb` depende de `nodejs` a secas y no de `nodejs (>= 22.6)`: Debian 13 trae
57
+ un 20, y pedir 22.6 haría un paquete que no se instala en ninguna parte por una
58
+ razón que además no es cierta —la versión nueva suele estar en nvm, que apt no
59
+ ve—. Mejor un paquete que instala y avisa.
60
+
61
+ El `.deb` se arma con `scripts/hacer-deb.sh`, que no compila nada: el paquete es
62
+ el fuente más un enlace en `/usr/bin`, y por eso es `Architecture: all`.
63
+
64
+ ### ¿Se actualiza solo?
65
+
66
+ **Los archivos, cuando vos se lo pedís al gestor**; ninguno de los tres baja
67
+ versiones nuevas por su cuenta:
68
+
69
+ | | trae la versión nueva con | automático de fábrica |
70
+ |---|---|---|
71
+ | apt | `sudo apt update && sudo apt upgrade` | no — `unattended-upgrades` sólo toca los orígenes que le configures |
72
+ | Homebrew | `brew upgrade` | no — salvo que instales `brew autoupdate` |
73
+ | npm | `npm update -g @legios/quartermaster` | no |
74
+
75
+ **El indicador que ya está corriendo sí se actualiza solo.** Ése era el agujero
76
+ real: `apt upgrade` reemplaza los archivos y se va, pero el proceso que está
77
+ andando tiene el módulo cargado en memoria y sigue con el código viejo hasta que
78
+ alguien lo reinicie — y no lo reinicia nadie, porque el indicador es justo lo que
79
+ se deja andando y se olvida. Así que se vigila a sí mismo y se vuelve a lanzar
80
+ con `execv` en cuanto su archivo cambia.
81
+
82
+ Con una condición que no es opcional: **compila la versión nueva antes de
83
+ saltar**. Si está rota, se queda con la que anda y lo dice. Reiniciar a ciegas
84
+ dejaría al usuario sin indicador, que es peor que tenerlo desactualizado.
85
+
86
+ ## El problema
87
+
88
+ Claude Code soporta varios perfiles vía `CLAUDE_CONFIG_DIR`, y cada perfil tiene
89
+ su propia cuenta y su propia credencial. Un asiento de trabajo y una
90
+ suscripción personal en la misma laptop es completamente normal.
91
+
92
+ Los monitores que existen leen **una** credencial: la del directorio por
93
+ defecto. En la máquina donde se escribió esto eso significa leer `~/.claude`,
94
+ que está vacío, mientras las dos cuentas reales viven en `~/.claude-personal`
95
+ (Max) y `~/.claude-teams` (Teramot). El resultado observado fue un monitor
96
+ polleando cada 120 segundos durante horas, escribiendo `credential expired —
97
+ gating poll` en su log, y mostrando nada.
98
+
99
+ ## Primer hallazgo: dónde está la credencial
100
+
101
+ En macOS el servicio del llavero de un perfil es **determinista**:
102
+
103
+ | Directorio de configuración | Servicio del llavero |
104
+ |---|---|
105
+ | `~/.claude` (por defecto) | `Claude Code-credentials` |
106
+ | cualquier otro | `Claude Code-credentials-<sha256(ruta absoluta)[:8]>` |
107
+
108
+ Verificado contra items reales del llavero. Eso convierte el soporte
109
+ multi-perfil en un cálculo, no en una heurística.
110
+
111
+ ## Estado
112
+
113
+ | Hito | Estado | Número comiteado |
114
+ |---|---|---|
115
+ | **H0** perfiles y preflight | ✅ mecanismo | `make demo-h0` — descubre perfiles y dice cuáles autentican, no sólo cuáles existen |
116
+ | **H1** consumo local real | ✅ **número** | [`numeros/h1.json`](numeros/h1.json) — 9 340 requests deduplicados, 2,8 G de tokens en 7 días, 946 ms |
117
+ | **H2** poll de cuota en vivo | ✅ **número** | [`numeros/h2-endpoint.md`](numeros/h2-endpoint.md) — ejecutado por fin: con 95 min de cache, la sesión estaba **11 puntos** abajo y las semanales 0-2 |
118
+ | **H3** `--watch` y `--json` | ✅ mecanismo | `make qm`, `qm --json`, `qm --watch`, `qm --umbral=N` |
119
+ | **H4** Linux y Windows verificados | 🟨 Linux ✅, Windows ⏳ | [`numeros/h4-linux.md`](numeros/h4-linux.md) |
120
+ | **H8** Codex en la misma tabla | ✅ mecanismo | cuota del disco (rollouts) + refresco por app-server + consumo local; `src/adapters/codex.ts` |
121
+ | **H5** cuota sin red ni credencial | ✅ **número** | [`numeros/h5-cuota.md`](numeros/h5-cuota.md) · [`h5-cuota.json`](numeros/h5-cuota.json) |
122
+ | **H6** verlo sin ir a buscarlo | ✅ mecanismo | `make indicador` en GNOME · `make tray` en Windows · `make web` en el navegador · `qm --breve` en la statusline de Claude Code |
123
+ | **H7** que te avise antes de chocar | ✅ mecanismo | proyección por mínimos cuadrados + avisos al 80/95 % y al detectar choque |
124
+ | **H9** el paquete de npm se instala y corre | ✅ **número** | [`numeros/h9-npm.json`](numeros/h9-npm.json) — instalado en un prefix limpio y ejecutado; `make gate-npm-rojo` muestra el rojo |
125
+
126
+ **Advertencias, para que el README no mienta:**
127
+
128
+ - **El cache se equivoca en la sesión, no en las semanales.** Medido en
129
+ [`numeros/h2-endpoint.md`](numeros/h2-endpoint.md): con 95 minutos de cache,
130
+ las semanales estaban 0-2 puntos abajo y la **sesión 10 y 11**. La ventana de
131
+ 5 h se llena veinte veces más rápido que la de 7 días, así que la misma vejez
132
+ duele veinte veces más. Para la pregunta urgente —«¿puedo seguir ahora?»— el
133
+ disco solo no alcanza: hay que refrescar.
134
+ - **Las ramas de error del endpoint siguen sin ejecutarse.** Contestó bien en
135
+ todos los perfiles; token vencido a mitad de camino y endpoint caído siguen
136
+ sin probarse.
137
+ - **`dur()` era distinta en Python que en las otras dos.** Le faltaba la rama de
138
+ días, así que el panel de GNOME decía `3067h28m` donde el de Windows decía
139
+ `127d19h`. Se vio poniendo los dos paneles al lado; no se ve mirando uno solo.
140
+ - **El número del cache puede estar viejo.** Claude Code lo refresca cuando
141
+ quiere —medido: reescribió `.claude.json` 19 s antes y el bloque de cuota
142
+ seguía siendo de hacía 83 minutos—. `qm` imprime la edad siempre.
143
+ - **Windows no está verificado.** El adaptador asume
144
+ `<directorio>/.credentials.json` igual que Linux. Es posible que Claude Code
145
+ use DPAPI o el Credential Manager. Hay que probarlo antes de afirmar nada.
146
+ - **macOS va a abrir un prompt del llavero por perfil** si se usa `--refrescar`.
147
+ El camino por defecto ya no toca el llavero.
148
+
149
+ ## Segundo hallazgo: la cuota ya está en el disco
150
+
151
+ Claude Code guarda en el `.claude.json` de cada perfil la última respuesta de
152
+ cuota que recibió, bajo `cachedUsageUtilization`. El número de cuota **es un
153
+ dato de disco**: no hace falta red, y sobre todo **no hace falta credencial**,
154
+ así que se lee igual en un perfil con el token vencido — que es exactamente el
155
+ estado en el que la herramienta que motivó este repo se quedaba muda.
156
+
157
+ Y trae un segundo silencio, este adentro de un mismo perfil. La respuesta
158
+ incluye un array `limits[]` con barras que **no** tienen clave propia arriba:
159
+
160
+ | Barra | % | Severidad | ¿activa? | Alcance |
161
+ |---|---:|---|---|---|
162
+ | `session` (= `five_hour`) | 8 | normal | no | — |
163
+ | `weekly_all` (= `seven_day`) | 59 | normal | no | — |
164
+ | **`weekly_scoped`** | **75** | **warning** | **sí** | modelo Fable |
165
+
166
+ `seven_day_opus`, `seven_day_sonnet` y otras diez venían `null`. Un monitor que
167
+ lea `five_hour` y `seven_day` —las dos que documenta la statusline— informa
168
+ **8 %**, se ve cómodo, y esconde la única barra con aviso. En esa cuenta el
169
+ error es de 67 puntos. Detalle y medición en
170
+ [`numeros/h5-cuota.md`](numeros/h5-cuota.md).
171
+
172
+ ## La misma falla en Linux, y peor
173
+
174
+ `numeros/h4-linux.md` es la primera corrida fuera de macOS. Encontró 4 perfiles,
175
+ y con ellos una versión del problema original más difícil de notar: acá el
176
+ directorio por defecto **no** está vacío. Tiene 1,2 G de tokens y se ve
177
+ perfectamente sano.
178
+
179
+ > Un monitor que sólo lee `~/.claude` en esa máquina muestra un número
180
+ > creíble que deja afuera el **58,2 %** de los tokens y el **54 %** de los
181
+ > requests, todos del perfil de trabajo.
182
+
183
+ Un directorio vacío se nota. Un número que parece bien y está a la mitad, no.
184
+
185
+ ## De dónde sale el endpoint de cuota
186
+
187
+ No está documentado. Se leyó del binario que Claude Code instala
188
+ (`node_modules/@anthropic-ai/claude-code/bin/claude.exe`), que contiene el call
189
+ site:
190
+
191
+ ```
192
+ fetchUtilization: GET /api/oauth/usage (attempt
193
+ fetchUtilization: 200 after
194
+ ```
195
+
196
+ La **forma** de la respuesta ya no se adivina: `cachedUsageUtilization` guarda
197
+ esa misma respuesta, y de ahí salieron las fixtures de `test/fixtures/`. Eso
198
+ confirmó lo que este README sospechaba antes de tener con qué probarlo: la
199
+ documentación de statusline embebida en el binario describe lo que Claude Code
200
+ **republica** (`used_percentage`, epoch en segundos), no lo que **recibe**
201
+ (`utilization`, ISO con offset). Un parser escrito sólo contra esa doc habría
202
+ leído mal las fechas.
203
+
204
+ Corolario operativo: **el endpoint puede desaparecer sin aviso**, y por eso ni
205
+ las transcripciones ni el cache son un fallback opcional (ver `SOUL.md`).
206
+
207
+ ## La otra cuenta: Codex
208
+
209
+ Un asiento de trabajo, una suscripción personal y **una cuenta de Codex** en la
210
+ misma laptop es tan normal como lo anterior, y la pregunta es la misma: ¿me
211
+ queda cuota? Desde `src/adapters/codex.ts`, `qm` la contesta para las dos
212
+ herramientas en la misma tabla.
213
+
214
+ ```
215
+ codex vos@ejemplo.com · plus
216
+ credencial: la pone codex · 2 reset(s) sin usar
217
+ cache · hace 1m
218
+ ▸ session ███████████████ 100% warning reinicia en 27m
219
+ weekly_all ██████████░░░░░ 67% reinicia en 139h04m
220
+ local: 13,0M en 7d · 5,3M en 5h · 443 requests
221
+ ```
222
+
223
+ ### Con qué está autenticado manda sobre lo que dejó escrito
224
+
225
+ Reportado a mano: la bandeja decía **`plus`** en una máquina sin ninguna
226
+ suscripción. La causa estaba entera en el disco:
227
+
228
+ - ocho rollouts en `~/.codex/sessions` con `"plan_type": "plus"` y barras de
229
+ hasta el **94 %**, todos de **mayo de 2026**;
230
+ - un `~/.codex/auth.json` que dice `"auth_mode": "apikey"` y no tiene `tokens`
231
+ ni `id_token`, sólo una `OPENAI_API_KEY`.
232
+
233
+ O sea: la suscripción existió, se dio de baja, y los rollouts de cuando existía
234
+ no se borran nunca. `codexEnDisco()` buscaba el rollout más nuevo **que tuviera
235
+ barras** y encontraba el del 5 de mayo, así que reportaba un plan que ya no está
236
+ y un porcentaje de hace **127 días** como si fuera de ahora. Peor: en una cuenta
237
+ que paga por uso y por lo tanto **no tiene barras**, mostraba barras.
238
+
239
+ `auth_mode` es la señal autoritativa y ahora se mira **antes** que los rollouts.
240
+ Con `apikey` la fila dice `sin-suscripcion` —«la cuenta no tiene límites de
241
+ suscripción que reportar (API key o enterprise)»— y el plan pasa a ser
242
+ `api key`. Es el mismo caso que las filas de opencode: un plan por API key cuyo
243
+ porcentaje sólo existe del otro lado. Y de paso deja de levantarse un
244
+ `app-server` con 20 s de timeout para preguntar algo que no puede contestar.
245
+
246
+ La regla está clavada en `test/codex.test.ts`, incluidos los dos bordes que
247
+ importan: un `auth.json` viejo sin `auth_mode` se deduce de qué guardó, y si
248
+ están la key **y** el `id_token` —Codex deja la key vieja cuando entrás con la
249
+ cuenta— gana el `id_token`, porque al revés una cuenta con suscripción de verdad
250
+ quedaría reportada como si no la tuviera.
251
+
252
+ ### Una corrección
253
+
254
+ La primera versión de este README decía, en negrita, que **Codex no deja la
255
+ cuota en el disco**. Era falso. Se habían mirado tres rollouts de junio, que
256
+ traían `rate_limits: null`, y se generalizó a partir de ahí — el mismo error de
257
+ método que el repo le critica a los monitores que leen una sola credencial.
258
+
259
+ Los rollouts nuevos (codex-cli 0.153.4) **sí la traen**, adentro de los eventos
260
+ `token_count`, con el timestamp al lado. Así que Codex no es la excepción a H5:
261
+ es otro caso de H5. **El camino por defecto es el disco**, sin red y sin
262
+ credencial, y el app-server queda como refresco — lo que `--refrescar` es para
263
+ Claude. Medido: 212 ms para encontrar la lectura más nueva entre 138 rollouts.
264
+
265
+ Dos trampas que costaron un rato y que están cubiertas por tests:
266
+
267
+ - **Codex escribe varios baldes de límites.** Después del bueno
268
+ (`limit_id: "codex"`) manda uno de `limit_id: "premium"` con `primary: null`.
269
+ Quedarse con el último devolvía ese, y descartarlo descartaba el archivo
270
+ entero — con el número bueno adentro, unos milisegundos antes.
271
+ - **Las dos puntas escriben distinto.** El rollout usa `snake_case`
272
+ (`used_percent`, `rate_limit_reached_type`) y el app-server `camelCase`. Se
273
+ normaliza en un solo lugar, y hay un test que exige que las dos den
274
+ exactamente lo mismo: si divergen, el número cambia según de dónde salió, que
275
+ es peor que no tener número. Ese test encontró que `rate_limit_reached_type`
276
+ no se leía del disco, así que «ya te frenó» no marcaba nada.
277
+
278
+ ### Y el piso, que también estaba
279
+
280
+ Los mismos rollouts tienen `total_token_usage`, así que Codex tiene el consumo
281
+ local que pide `SOUL.md`: aunque el app-server se caiga **y** el disco no traiga
282
+ barras, sigue habiendo un número. Se suma el último acumulado de cada sesión, no
283
+ los parciales, para no contar dos veces.
284
+
285
+ Tres decisiones más:
286
+
287
+ - **No tocamos su credencial.** Al app-server se le habla por el binario
288
+ `codex`, que usa la suya. El mail y el plan salen de los claims del `id_token`
289
+ que Codex ya guardó — se leen, no se copian.
290
+ - **Los nombres de las ventanas se igualan por duración.** El servidor manda
291
+ `primary` y `secondary`, que no dicen nada; 300 minutos es la misma pregunta
292
+ que la `session` de Claude, y 10 080 es la semanal. Igualarlos es lo que deja
293
+ comparar las dos cuentas en la misma columna.
294
+ - **`codex` no se busca en el PATH y ya.** launchd arranca con
295
+ `PATH=/usr/bin:/bin:/usr/sbin:/sbin`; hay un `rutaCodex()` que mira también
296
+ los lugares de siempre, y `QM_CODEX` para forzarlo.
297
+
298
+ ## Elegir qué se muestra
299
+
300
+ Descubrir todo es la misión; **mostrar** todo es una preferencia. Con cuatro
301
+ cuentas la barra de menú ya no entra, y una cuenta que no usás es ruido
302
+ permanente.
303
+
304
+ ```bash
305
+ qm --solo=codex,personal # sólo esas
306
+ qm --ocultar=teams # todas menos esa
307
+ ```
308
+
309
+ o fijo, en `~/.config/quartermaster/config.json`:
310
+
311
+ ```json
312
+ { "ocultar": ["main"] }
313
+ ```
314
+
315
+ Se acepta el nombre corto (`main`, `personal`, `teams`, `codex`) o el completo
316
+ del perfil. `mostrar` gana sobre `ocultar`. Como todos los que dibujan leen el
317
+ JSON de `qm`, la selección vale igual en la terminal, en la barra y en el
318
+ tablero, sin configurar nada tres veces.
319
+
320
+ Un detalle que es una regla del repo: **si el filtro no coincide con ninguna
321
+ cuenta, se muestran todas** y se dice que el filtro no pegó. Casi siempre es un
322
+ nombre mal escrito, y quedarse con una pantalla vacía y sin explicación es
323
+ exactamente el bug que motivó todo esto.
324
+
325
+ ## Sumar otra herramienta: Gemini, GLM, MiniMax
326
+
327
+ La pregunta no es «¿se puede?» sino **de dónde sale el número**. Un proveedor
328
+ tiene que contestar tres cosas, y sólo la primera es obligatoria:
329
+
330
+ | | Qué es | Si falta |
331
+ |---|---|---|
332
+ | **1. Qué cuentas hay** | descubrir directorios/credenciales | no hay fila |
333
+ | **2. Cuánta cuota queda** | barras con % y reinicio | hay fila y una frase que dice por qué no hay número |
334
+ | **3. Cuánto consumiste** | el piso local, de transcripciones | se informa `null`, nunca `0` |
335
+
336
+ Hoy hay dos formas resueltas, y las dos sirven de molde:
337
+
338
+ - **Claude Code** — la cuota está en `.claude.json` (H5) y el endpoint es el
339
+ refresco (H2).
340
+ - **Codex** — la cuota está en los rollouts y el app-server es el refresco. El
341
+ consumo sale de los mismos archivos.
342
+
343
+ ### GLM y MiniMax: estaban adentro de opencode
344
+
345
+ No hacía falta un CLI propio de cada uno. Los dos planes viven en **opencode**,
346
+ y opencode deja en `~/.local/share/opencode/opencode.db` una tabla `session` con
347
+ `model`, `cost` y cinco columnas de tokens. O sea: **el piso está**, local, sin
348
+ red y sin credencial, igual que las transcripciones de Claude y los rollouts de
349
+ Codex.
350
+
351
+ ```
352
+ minimax MiniMax-M3 2,7M en 7d · 2 sesiones
353
+ glm glm-5.3 837,3k en 7d · 1 sesión
354
+ openai gpt-5.6-sol 549,3k en 7d · 4 sesiones
355
+ grok — 0 en 7d · último uso hace 8d21h
356
+ kimi — 0 en 7d · último uso hace 14d18h
357
+ ```
358
+
359
+ El descubrimiento y el consumo son dos preguntas distintas: las cuentas se
360
+ listan por **último uso** (30 días) y no por lo que gastaron en la ventana. Si
361
+ sólo se listara lo segundo, una cuenta que usás cada tanto desaparecería de la
362
+ lista — y «no aparece» es exactamente lo que este repo existe para que no pase.
363
+ Grok aparece con 0 en la semana y la fecha real al lado.
364
+
365
+ Dos decisiones:
366
+
367
+ - **No se lee `auth.json` de opencode.** Los proveedores se descubren de la base
368
+ de sesiones, que además dice cuáles se usaron de verdad y no cuáles están
369
+ configurados. La única forma segura de no filtrar una clave es no leerla.
370
+ - **La cuota no se inventa.** Son planes por API key: el porcentaje sólo existe
371
+ en el endpoint de cada proveedor y hace falta la clave para pedirlo. La fila
372
+ trae consumo y una frase que dice por qué no hay barra — nunca un 0 % que
373
+ parezca un dato. Es un estado nuevo y explícito, `sin-cuota-legible`, distinto
374
+ de «no hay límites» y de «todavía no se escribió».
375
+
376
+ ### Dos correcciones en la misma fila
377
+
378
+ La fila de un plan de opencode traía dos cosas mal, y las dos salieron de
379
+ mirarla en la pantalla, no de leer el código.
380
+
381
+ **El plan mostraba el modelo.** Donde las otras filas ponen `team_tier_1` o
382
+ `plus`, la de opencode ponía `glm-5.3`. Eso salía de `plan: c.modelo` — el id
383
+ del modelo más usado en la ventana. Un modelo no es un plan: no dice qué pagás,
384
+ y **cambia solo** cuando cambiás de modelo. Además ya estaba en el desglose por
385
+ modelo, que es su lugar, así que aparecía dos veces. Ahora ese campo lleva el
386
+ proveedor, y la columna significa lo mismo en todas las filas.
387
+
388
+ **Y el mapa de nombres no aplicaba nunca.** Las claves eran `zai-coding-plan`,
389
+ `minimax-coding-plan`, `kimi-for-coding`. El `providerID` que opencode guarda en
390
+ esta máquina es **`zai`** a secas. Verificado contra la base: los proveedores
391
+ reales son `zai`, `openai`, `amazon-bedrock`, `anthropic` y `opencode-go`. O sea
392
+ que el nombre lindo no se aplicaba y la fila se llamaba `zai` en vez de `glm`.
393
+ Ahora están las dos formas de cada uno, porque no hay motivo para creer que el
394
+ `providerID` sea estable entre instalaciones — y esa suposición es justo la que
395
+ falló acá.
396
+
397
+ Ojo con esto último si tenés scripts: la cuenta ahora se llama `glm`, así que un
398
+ `--solo=zai` o un `--ocultar=zai` hay que actualizarlo.
399
+
400
+ ### Y una tercera: la fila no aparecía en ninguna pantalla
401
+
402
+ Reportado a mano también: «no aparece lo de opencode que tengo una key de
403
+ z.ai». Y era cierto — `filasOpencode()` arrancaba con
404
+ `if (!hayOpencode() || o.breve) return []`, y **todas las pantallas piden
405
+ `--breve`**: la barra de macOS, la bandeja de Windows, el panel de GNOME y la
406
+ statusline. La fila existía sólo si corrías `qm` a mano en una terminal. Una
407
+ cuenta que se usó ayer y no aparece es, literalmente, el bug de la primera
408
+ sección de este README, con otro vendor.
409
+
410
+ Lo que costaba se midió antes de decidir: de los ~460 ms de leer opencode,
411
+ **439 eran `limitesOpencode()`** —la consulta que busca los 429 hace
412
+ `json_extract` del blob de cada mensaje, 10 173 en esta máquina— y el consumo
413
+ apenas 1,4 ms. Así que se arregló la consulta en vez de esconder la fila:
414
+ acotada por fecha baja a **3 ms**, y no se pierde nada que se use, porque lo
415
+ único que produce una barra es un límite cuyo reinicio todavía no pasó y ningún
416
+ proveedor reinicia en más de un mes. Con eso opencode entero son ~25 ms, que sí
417
+ entran en el contrato de `--breve`.
418
+
419
+ ### Se probó de verdad antes de rendirse
420
+
421
+ No alcanza con decir «no se puede». Se buscó el porcentaje por los cuatro
422
+ caminos que había, con los endpoints reales sacados del binario de opencode:
423
+
424
+ | Camino | Resultado |
425
+ |---|---|
426
+ | Cabeceras en la base de opencode | sólo las de OpenAI (`x-codex-*`), y sólo en respuestas con error |
427
+ | `GET /models` con la clave | Z.ai **200**, MiniMax **200** — sin una sola cabecera `x-ratelimit-*` |
428
+ | Una llamada real de 1 token | MiniMax **200**, sin cabeceras. xAI **403**: el token OAuth que guarda opencode está vencido |
429
+ | Un archivo suyo en el disco | no existe |
430
+
431
+ **Pero la llamada real encontró otra cosa.** Z.ai contestó `429` con esto:
432
+
433
+ ```json
434
+ {"error":{"code":"1310","message":"Weekly/Monthly Limit Exhausted.
435
+ Your limit will reset at 2026-09-11 18:35:24"}}
436
+ ```
437
+
438
+ O sea que el porcentaje no existe, pero **los dos datos que se usan sí**:
439
+ ¿me frenaron? y ¿cuándo me libero? Y no hace falta salir a la red para
440
+ tenerlos, porque **opencode guarda esas respuestas**: en su base hay límites
441
+ alcanzados por proveedor, con la fecha de reinicio adentro del texto —incluida
442
+ la ventana de 5 h de Grok—. Se leen del disco, gratis y sin credencial, igual
443
+ que todo lo demás.
444
+
445
+ Así que una cuenta de opencode que está frenada **sí muestra barra**: 100 %,
446
+ con su reinicio y su «libre en». Una que no lo está no afirma nada — dice
447
+ cuándo fue la última vez que la frenaron, porque un límite de la semana pasada
448
+ no dice nada de hoy.
449
+
450
+ Lo que encontré en esta máquina para la que falta:
451
+
452
+ - **Gemini CLI 0.59.0** — instalado, autenticado (`oauth-personal`). Pero en
453
+ `~/.gemini` **no hay ningún número de cuota ni de uso**: hay credenciales,
454
+ cuentas, `installation_id` y estado de UI, y nada más. Su límite además no es
455
+ un porcentaje sino requests por día, así que ni siquiera encaja en la forma
456
+ `VentanaCuota` sin decidir antes qué significa «80 %» ahí. Da para el punto 1
457
+ hoy; el 2 necesita encontrarle una fuente, y el 3 un lugar donde cuente
458
+ tokens, que tampoco aparece.
459
+ El molde está y la selección de arriba ya prevé que sobren cuentas: con siete,
460
+ `--ocultar` deja de ser un lujo.
461
+
462
+ ## Instalación
463
+
464
+ ```bash
465
+ npm install
466
+ make instalar # enlaza bin/qm y bin/qm-web en ~/.local/bin
467
+ qm # ya anda desde cualquier lado
468
+ qm-web # y el tablero también
469
+ ```
470
+
471
+ `bin/qm` **busca solo un Node ≥ 22.6**: mira `$QM_NODE`, después el del `PATH`,
472
+ después las versiones de nvm de mayor a menor. Hace falta porque qm se lee
473
+ directo del TypeScript, y en una máquina donde `node` es un 20 —lo normal si el
474
+ sistema trae uno y las versiones nuevas viven en nvm, que sólo se carga en
475
+ shells interactivos— un shebang común falla con un error de sintaxis que no le
476
+ dice nada a nadie.
477
+
478
+ ## Uso
479
+
480
+ ```bash
481
+ qm # cuota y consumo de todos los perfiles.
482
+ # Sin red y sin credencial: la cuota sale del disco
483
+ qm --breve # un renglón, en milisegundos. Para una statusline
484
+ qm --refrescar # además pide el número al endpoint (token vigente)
485
+ qm --json # para scripts
486
+ qm --watch 60 # se redibuja cada 60 s
487
+ qm --umbral=80 # código de salida 3 si alguna barra pasa el 80 %
488
+ qm --sin-codex # no mirar la cuenta de Codex
489
+ qm --calentar-codex # refresca sólo el cache de Codex, sin imprimir nada
490
+ qm-web # el tablero en el navegador, se redibuja cada 30 s
491
+
492
+ make demo-h0 # ¿qué perfiles hay y cuáles autentican?
493
+ make demo-h1 # consumo de los últimos 7 días, por perfil
494
+ make numero-h5 # regenera numeros/h5-cuota.json, ya redactado
495
+ ```
496
+
497
+ Requiere **Node ≥ 22.6** (lee TypeScript directamente, no hay paso de build).
498
+
499
+ ## ¿Vas a chocarte antes de que se reinicie?
500
+
501
+ Es la pregunta que ni el porcentaje ni el consumo contestan solos. «Vas 75 %»
502
+ no dice nada sin saber a qué velocidad subís.
503
+
504
+ qm guarda una serie de lecturas por barra y le ajusta una recta:
505
+
506
+ ```
507
+ ritmo: 12.4 pts/h · 100 % en 1h58m — antes del reinicio
508
+ ```
509
+
510
+ Lo que importa no es la recta, es **cuándo no se dibuja**. Con dos lecturas, o
511
+ con una ventana que recién arranca, cualquier extrapolación es un número
512
+ inventado con cara de dato. Entonces dice:
513
+
514
+ ```
515
+ ritmo: todavía no sé el ritmo: hacen falta 3 lecturas y hay 1
516
+ ```
517
+
518
+ «No sé si te vas a chocar» y «no te vas a chocar» son cosas distintas y se
519
+ muestran distinto. Dos guardas más: se descartan las lecturas de más de 2 h
520
+ —el ritmo de hace cuatro horas no predice el de ahora— y no se proyecta sobre
521
+ un movimiento menor a 2 puntos, porque el servidor manda enteros y subir uno
522
+ no se distingue de un redondeo.
523
+
524
+ La serie vive en `~/.cache/quartermaster/historial.jsonl` y se indexa por el
525
+ `medidoEn` de la cuota, no por el momento en que qm miró: leer diez veces el
526
+ mismo cache deja **una** muestra.
527
+
528
+ ## En el navegador
529
+
530
+ El indicador de GNOME es la respuesta para GNOME. `qm-web` es la misma idea
531
+ donde no hay barra de GNOME —macOS, Windows, un Linux con otro escritorio—: un
532
+ tablero que se abre en el navegador y se redibuja solo cada 30 s.
533
+
534
+ ```bash
535
+ make web # levanta el tablero y abre el navegador
536
+ qm-web --puerto=8080 # en otro puerto (por defecto 7391)
537
+ qm-web --sin-abrir # sólo imprime la URL
538
+ ```
539
+
540
+ Muestra, de arriba abajo: **lo primero que te frena** —la peor barra de toda la
541
+ máquina, con su cuenta regresiva al reinicio corriendo en vivo y la proyección
542
+ si la hay—, y después una tarjeta por perfil con todas sus barras, la edad del
543
+ cache, el consumo local de la ventana y el desglose por modelo. Un perfil sin
544
+ número muestra la frase que dice por qué, igual que en la terminal.
545
+
546
+ Vale la misma regla que el indicador: **sólo dibuja**. `bin/qm-web` le pide el
547
+ JSON a `qm` por stdout y no sabe qué es una credencial ni habla HTTP con nadie.
548
+ Escucha únicamente en `127.0.0.1` — el tablero muestra mails y planes, y
549
+ `SOUL.md` dice que nada sale de la máquina.
550
+
551
+ Es JavaScript común, no TypeScript, a propósito: corre con cualquier Node ≥ 18 y
552
+ el requisito de 22.6 queda donde de verdad hace falta, adentro de `qm`.
553
+
554
+ ## En la barra de menú de macOS
555
+
556
+ ```bash
557
+ make barra # lo compila la primera vez y lo arranca
558
+ make barra-autostart # y que arranque solo al iniciar sesión, vía launchd
559
+ make barra-quitar # para sacarlo
560
+ ```
561
+
562
+ Queda un item arriba a la derecha que **se dibuja**. Por cada cuenta, tres
563
+ cosas, y cada una quiere decir siempre lo mismo:
564
+
565
+ ```
566
+ ✳ ▍37 ✳ ▍21 <> ▍100
567
+ ```
568
+
569
+ - **El glifo dice qué suscripción es.** La *forma* es el producto —el asterisco
570
+ es la marca de Claude, los chevrones son código—; el *color*, cuál de ellas.
571
+ Esos colores son azul, violeta y magenta: deliberadamente lejos de la paleta
572
+ de estado, porque los colores de estado están reservados y no pueden
573
+ significar además «esta es la cuenta 2».
574
+ - **El medidor es la semanal**: ¿llego al final?
575
+ - **El número es la sesión de 5 h**: ¿puedo seguir ahora? Se tiñe con su propio
576
+ estado, pero recién cuando aprieta — si se pintara siempre, el color dejaría
577
+ de querer decir algo.
578
+
579
+ Antes el medidor mostraba «la que frena antes», que a veces era la semanal y a
580
+ veces la sesión — y cuando era la sesión dibujaba lo mismo que ya decía el
581
+ número al lado. Un encoding que cambia de significado según el dato no se lee de
582
+ un vistazo, que es lo único que hace la barra de menú.
583
+
584
+ `~` va pegado al número, porque califica a *ese* número: `~37` es «esta sesión
585
+ es de hace rato».
586
+
587
+ Cuando no entra, la escalera saca primero los glifos y **el número es lo último
588
+ que se cae**. Antes era al revés y el item quedaba mudo justo en la parte que se
589
+ viene a mirar: la identidad se recupera del orden y del menú, el número no se
590
+ recupera de nada.
591
+
592
+ Es lo que se hace en una barra de menú de macOS —una marca chica y callada, no
593
+ un renglón de texto— y además es lo único que entra: **91 puntos contra los 192
594
+ del renglón horizontal**, medido. Esa diferencia es la que decide si el sistema
595
+ lo muestra o lo esconde.
596
+
597
+ El item y que al desplegarlo muestra cada
598
+ cuenta con su ícono (asterisco para Claude, chevrones para Codex; SF Symbols no
599
+ trae los logos y estos dos se distinguen de un vistazo), con todas sus barras con todas sus barras, la edad del
600
+ cache, la proyección y el motivo cuando un perfil no tiene número. `!` es una
601
+ barra que el servidor marcó con aviso; `~` es un cache de más de 6 horas. Vale
602
+ la misma regla que el indicador de GNOME: **sólo dibuja**, le pide el JSON a
603
+ `qm --json --breve` (~150 ms, no toca las transcripciones) y no sabe qué es una
604
+ credencial.
605
+
606
+ Se compila con `swiftc`, que viene con las Command Line Tools: no hace falta
607
+ Xcode entero, ni empaquetar una `.app`, ni instalar SwiftBar ni nada. El binario
608
+ queda en `~/.cache/quartermaster/`, no en el repo. Se recompila solo cuando el
609
+ fuente cambia.
610
+
611
+ Al desplegarlo, cada cuenta es una fila **dibujada** —`VistaCuenta`, no un
612
+ renglón de texto—: ícono del producto, cuenta y plan, y después cada barra con
613
+ su medidor, su porcentaje, cuándo se reinicia, la edad del cache sobre la que
614
+ manda, y el ritmo en rojo cuando la proyección dice que chocás. Los bloques
615
+ `█░` de antes eran una tabla ASCII adentro de una app nativa.
616
+
617
+ Hace lo mismo que en GNOME: se entera solo (vigila el `.claude.json` de cada
618
+ perfil con `DispatchSource`, y se re-arma cuando Claude Code reescribe el
619
+ archivo por rename, que mata el descriptor), avisa al cruzar 80 % y 95 % y
620
+ cuando la proyección dice que chocás antes del reinicio, y no repite.
621
+
622
+ ### Llegar tarde es la otra forma de mentir
623
+
624
+ Codex subió del 23 % al 100 % en cuarenta minutos y la barra mostró 93 %
625
+ durante siete de ellos. Mostraba la edad, así que no mentía — pero un número
626
+ que llega tarde a esa velocidad no sirve para nada. Fueron **tres** bugs
627
+ apilados, y ninguno hacía ruido:
628
+
629
+ - **App Nap.** Una app sin ventanas es el candidato perfecto, y macOS le corre
630
+ los timers: un sondeo de 5 minutos no disparó en 7. Se arregla con
631
+ `ProcessInfo.beginActivity` y timers con `tolerance = 0` en `.common`.
632
+ - **Cadencia fija.** Cinco minutos es inservible para una barra que sube 1,6
633
+ puntos por minuto: se llega al 100 % adentro de una sola espera. Ahora la
634
+ cadencia sale de lo que ya sabemos —cuán alto está y cuánto falta para el
635
+ techo según la proyección—: 20 s arriba del 90 %, 45 s arriba del 75 %, 120 s
636
+ arriba del 50 %, 5 min si no pasa nada. Y se recalcula **al terminar de
637
+ dibujar**, que es cuando se conoce el estado; programarla en el arranque, con
638
+ el estado todavía vacío, la dejaba clavada en 5 minutos.
639
+ - **El PATH de launchd.** `PATH=/usr/bin:/bin:/usr/sbin:/sbin`, y `codex` vive
640
+ en `/opt/homebrew/bin`. `spawn('codex')` fallaba **en silencio** justo en la
641
+ instalación que importa —la que arranca sola— mientras andaba perfecto desde
642
+ una terminal. Es el mismo bug que `bin/qm` ya resolvía para Node, y estaba sin
643
+ resolver para Codex: ahora hay un `rutaCodex()` que busca en el PATH y en los
644
+ lugares de siempre, y `QM_CODEX` para forzarlo.
645
+
646
+ Medido después: refrescos cada 21 s con la sesión al 100 %.
647
+
648
+ ### Y avisar de más es no avisar
649
+
650
+ Los avisos se recordaban **en memoria**, así que cada arranque volvía a
651
+ notificar todo lo que ya estaba cruzado — y arrancar pasa seguido: reinstalar,
652
+ actualizar, reiniciar sesión. Con Codex al 100 % eso son tres notificaciones
653
+ por arranque, siempre las mismas. Un aviso marca un *cruce*; repetirlo en cada
654
+ arranque es ruido, y el ruido enseña a ignorarlos, que es exactamente lo
655
+ contrario de lo que tienen que lograr.
656
+
657
+ Ahora se persisten en `~/.cache/quartermaster/avisados.json`, con la misma clave
658
+ de siempre (perfil, barra, minuto de reinicio, umbral), así que sobreviven al
659
+ reinicio y la ventana siguiente vuelve a avisar sola. El aviso de «no entro en
660
+ la barra» tampoco se re-arma: se re-armaba al volver a entrar, y un item que
661
+ oscila entre visible y tapado avisaba en cada vuelta.
662
+
663
+ ### Y Claude también llegaba tarde, por otro motivo
664
+
665
+ Codex era el que se veía, pero Claude tenía el mismo problema con otra causa:
666
+ **Claude Code refresca su propio `cachedUsageUtilization` cuando quiere.**
667
+ Medido: reescribió `.claude.json` 19 s antes y el bloque de cuota seguía siendo
668
+ de hacía 83 minutos, con la sesión 11 puntos abajo de la realidad. Mirar el
669
+ disco más seguido no arregla nada — el número del disco no se mueve.
670
+
671
+ Lo que lo arregla es H2, que por fin se ejecutó: `qm --calentar` le pide el
672
+ número al endpoint de cada perfil y al app-server de Codex, y lo guarda. Con
673
+ Claude hay un detalle que no es opcional: **la lectura fresca no se puede
674
+ guardar donde Claude Code guarda la suya**. `.claude.json` es de él; este repo
675
+ lee credenciales y configuración, no las escribe. Así que va a un cache propio
676
+ (`~/.cache/quartermaster/endpoint.json`) y `qm` usa **la más nueva de las dos**,
677
+ la de Claude Code o la nuestra, mostrando siempre la edad de la que ganó.
678
+
679
+ El resultado es que `--breve` sigue tardando milisegundos y ya no lee un número
680
+ de hace hora y media: la barra calienta el cache en su sondeo adaptativo y las
681
+ lecturas rápidas encuentran algo de hace segundos.
682
+
683
+ ### El título se mide, no se elige
684
+
685
+ La barra de menú de una Mac con muesca tiene mucho menos lugar del que aparenta.
686
+ Los items se acomodan de derecha a izquierda y **el sistema esconde, sin decir
687
+ nada y con `isVisible` en `true`, al que caería abajo de la muesca**. Medido en
688
+ la máquina donde se escribió esto: `NSScreen.auxiliaryTopRightArea` daba 645
689
+ puntos a la derecha de la muesca, ya ocupados, y
690
+ `personal ~50% · teams 42%` necesita 192.
691
+
692
+ Por eso el texto no se elige: hay una **escalera** —el porcentaje con su marca,
693
+ el porcentaje pelado, y nada— y se prueba uno, se mide dónde quedó, y si no
694
+ entró se sigue con el siguiente. Los medidores no se negocian: son 30 puntos y
695
+ dicen lo esencial aunque el número se caiga. En una Mac sin muesca o en un
696
+ monitor externo entra el primero y se ve una cuenta por renglón.
697
+
698
+ ### Diseñar a ciegas fue el error
699
+
700
+ Nada de esto se podía ver: `screencapture` no sirve para mirar la barra —con
701
+ varias pantallas se muda a la que tiene el foco, y encima el sistema esconde el
702
+ item sin avisar—, así que las tres primeras versiones se dibujaron sin verlas y
703
+ las tres estuvieron mal. La última, la de dos renglones, salía **recortada por
704
+ arriba** y nadie se enteró hasta que hubo con qué mirarla.
705
+
706
+ Por eso existe `qm-barra --captura ruta.png`: el item se renderiza a sí mismo
707
+ sobre los dos fondos que puede tocarle y escribe dos PNG. No depende de qué
708
+ pantalla mire nadie. Cualquier cambio al dibujo se mira ahí antes de creerle.
709
+
710
+ ```bash
711
+ qm-barra --captura /tmp/barra.png # escribe barra-claro.png y barra-oscuro.png
712
+ ```
713
+
714
+ Otro detalle que costó una tarde: el test de «no entró» **no puede ser
715
+ `frame.minX < 0`**. En una pantalla ubicada a la izquierda de la principal las
716
+ coordenadas globales son negativas y el item se ve perfecto; hay que comparar
717
+ contra el `frame` de su propia pantalla.
718
+
719
+ Y si ni el compacto entra, **lo dice**: notifica una vez, porque un número que
720
+ no se ve es el mismo bug que el silencio. La salida en ese caso es la de macOS:
721
+ **cmd-arrastrar** el item a un hueco de la barra (queda guardado, el item tiene
722
+ `autosaveName`), liberar algún ícono, o mirar el tablero con `make web`.
723
+
724
+ ## En la barra de arriba de GNOME
725
+
726
+ ```bash
727
+ make indicador # lo arranca ahora
728
+ make autostart # y que arranque solo al iniciar sesión
729
+ ```
730
+
731
+ Queda un item en la barra que **se dibuja**: un medidor vertical por cuenta, en
732
+ el orden del panel, más el glifo del producto y el número de la sesión. Es el
733
+ mismo dibujo que el item de la barra de macOS y con las mismas medidas — tres
734
+ cuentas entran en el ancho de una palabra:
735
+
736
+ ```
737
+ ✳ ▮ 8 ✳ ▮ 22 ‹› ▮ 42
738
+ ```
739
+
740
+ El glifo dice QUÉ suscripción es —la forma, el producto; el color, cuál de
741
+ ellas—. El medidor es **siempre la semanal**, pintado por severidad. El número
742
+ es **siempre la sesión de 5 h**, que es la que contesta «¿puedo seguir ahora?»,
743
+ y se tiñe recién cuando aprieta. Sin marcas al lado del número: un `~` de
744
+ «cache viejo» pegado a la cifra obliga a saber qué significa para poder leer la
745
+ cifra, y la edad del cache ya está escrita con todas las letras en el panel.
746
+
747
+ Que un dibujo entre en la barra de GNOME depende de una puerta que la extensión
748
+ deja abierta sin documentar: si el nombre del ícono empieza con `/` lo toma como
749
+ un archivo, y si esa imagen es **ancha** —`width >= height * 1.5`— la dibuja a
750
+ lo ancho en vez de encajarla en el cuadrado de 16 px de un ícono. El archivo
751
+ además tiene que estar en un directorio escribible del usuario (va a
752
+ `~/.cache/quartermaster`), y el nombre se alterna entre dos porque el shell
753
+ cachea la textura por ruta: reescribiendo siempre la misma, el item se queda con
754
+ el dibujo viejo y parece que la cuota no se mueve.
755
+
756
+ **Click del medio: el panel** — el anillo de «lo primero que te frena», un
757
+ medidor de verdad por barra, la curva pegada a la que frena y el ritmo en rojo
758
+ cuando chocás antes del reinicio. Se cierra con un click afuera, con Escape, o
759
+ con otro click del medio.
760
+
761
+ Las cuentas que todavía no tienen número van juntas en una sola tarjeta al
762
+ final. Antes cada una gastaba una tarjeta entera para decir la misma frase, y en
763
+ una pantalla de 768 px el panel ya no entraba; juntas ahorran ~120 px y además
764
+ se leen mejor, porque no son tres misterios distintos sino un hecho con varios
765
+ nombres. Se agrupan por frase: dos cuentas pueden estar calladas por motivos
766
+ distintos, y ahí la frase importa.
767
+
768
+ Es el mismo contenido que el panel de la barra de macOS, pero **no es una copia
769
+ del dibujo**: acá va con la paleta de estado de Adwaita en vez de la de Apple,
770
+ con una tarjeta redondeada por cuenta —la «boxed list» con la que GNOME agrupa
771
+ cosas— en vez de líneas de pelo, y con cuerpos de letra más grandes, porque
772
+ Cantarell es más grande que la tipografía del sistema de Apple y con las medidas
773
+ de allá los renglones quedaban apretados y el texto rozando el borde.
774
+
775
+ El click izquierdo lo tiene tomado la extensión de AppIndicator: abre su propio
776
+ menú y no hay forma de enterarse de que pasó (su `AboutToShow` no llega hasta el
777
+ proceso). Se probó también la bandeja legacy XEmbed como salida —ahí el ícono es
778
+ una ventana nuestra— pero la bandeja lo fuerza a 16×16, que se lleva puestos los
779
+ medidores. Así que con AppIndicator ese menú quedó en **dos renglones**
780
+ —«Panel de cuota» y «Salir»— y ver el panel cuesta dos clicks. Para que cueste
781
+ uno está `make extension`, más abajo.
782
+ Antes repetía cada perfil con cada barra en bloques `█░`, que es lo único que
783
+ GNOME sabe dibujar ahí adentro: los items viajan por DBus y del otro lado la
784
+ extensión hace `label.set_text(...)`, texto pelado y sin markup. Un muro de
785
+ texto delante del dibujo bueno es peor que no tener menú.
786
+
787
+ El panel se arma con **un item de menú por tarjeta**, no como una sola
788
+ superficie. Un menú rueda item por item: con un único item más alto que la
789
+ pantalla no hay nada que rodar y el menú **no abre**, sin un error en ningún
790
+ lado. Venía midiendo 740 px contra 728 de área útil —entraba raspando— y en
791
+ cuanto creció dejó de abrirse. `make gate-dibujo` ahora falla si una tarjeta
792
+ sola pasa de 700 px.
793
+
794
+ ### Y por qué el panel terminó adentro de la extensión
795
+
796
+ Con la extensión puesta, **el panel lo dibuja ella**: qm lo deja en un PNG y la
797
+ extensión lo muestra en su propio menú del shell. Eso no fue una preferencia
798
+ estética, fue la tercera arquitectura y la primera que aguanta.
799
+
800
+ Las dos anteriores fallaron por la misma razón, y las dos veces costó verlo
801
+ porque el síntoma sólo aparece con alguien usando la máquina:
802
+
803
+ 1. **Ventana con foco**: ninguna ventana sostiene el foco acá. Los cuatro tipos
804
+ lo pierden solos entre 0,15 s y 4,6 s.
805
+ 2. **Menú de GTK con agarre propio**: aislado aguanta minutos —medido: 50 s sin
806
+ un solo `unmap`— pero con actividad real del escritorio se cierra a los
807
+ segundos, y **tocarlo para rodarlo lo cierra**, porque en un menú de GTK
808
+ soltar el botón sobre un item lo activa, y activar un item cierra el menú.
809
+
810
+ Adentro de la extensión el panel es un actor del compositor: no hay agarre que
811
+ romper, no hay XWayland, y rueda y se cierra como cualquier menú del shell,
812
+ porque es uno.
813
+
814
+ Sin la extensión sigue existiendo el menú de GTK como respaldo, con las tarjetas
815
+ marcadas insensibles para que tocarlas no lo cierre.
816
+
817
+ **El panel de respaldo es un `Gtk.Menu` propio** —popeado por este proceso, no por DBus— y
818
+ no una ventana suelta. La razón se midió: en este escritorio ninguna ventana
819
+ sostiene el foco. Se probaron los cuatro tipos (UTILITY, NORMAL, DIALOG,
820
+ POPUP_MENU) y las cuatro lo pierden solas entre 0,15 s y 4,6 s después de abrir,
821
+ sin que nadie toque nada, porque mutter se lo devuelve al lado Wayland. Cerrar
822
+ al perder el foco cerraba el panel solo; agarrar el asiento a mano tampoco
823
+ alcanzaba, porque un agarre de XWayland no ve los clicks que caen sobre una
824
+ ventana Wayland. Un menú de GTK, en cambio, agarra el puntero como lo agarra
825
+ cualquier menú del escritorio: el click afuera y el Escape salen gratis, y la
826
+ caja redondeada, la sombra y el fondo los pone el tema.
827
+
828
+ Dos detalles que cuestan una tarde si no están escritos:
829
+
830
+ - **Hay que pasarle un evento de disparo** a `popup_at_rect()`. El panel lo abre
831
+ un mensaje de DBus, así que no hay ningún evento de GDK a mano; sin uno, GTK
832
+ avisa `no trigger event for menu popup` y el agarre que toma se rompe solo a
833
+ los pocos segundos — el menú se cerraba sin que nadie tocara nada. Con un
834
+ evento sintético se queda abierto indefinidamente (medido: 20 s sin
835
+ moverse).
836
+ - **El tiempo de ese evento va en `CURRENT_TIME`.** Pedirle la hora al servidor
837
+ con `x11_get_server_time()` sobre la ventana raíz **cuelga el proceso**:
838
+ escribe una propiedad y espera un `PropertyNotify` que la raíz nunca manda.
839
+
840
+ Y una trampa de tema que dejó el panel ilegible una tarde: GNOME dice
841
+ `color-scheme = prefer-dark`, pero **una app GTK3 no se entera sola** — su
842
+ `gtk-application-prefer-dark-theme` sigue en `False` y el menú que hace de fondo
843
+ se dibuja CLARO. El panel, pintado con los colores oscuros de GNOME, quedaba
844
+ blanco sobre blanco. Ahora se hacen las dos cosas: se le pasa la preferencia a
845
+ GTK, y los grises del dibujo se sacan del **color de texto del propio menú** —
846
+ que no puede mentir sobre qué fondo tiene debajo— en vez de un ajuste que puede
847
+ no corresponderse con él.
848
+
849
+ Sigue haciendo falta X11 para una sola cosa: `popup_at_rect()` contra la ventana
850
+ raíz, que es lo que pega el panel arriba a la derecha. Por eso el proceso arranca
851
+ con `GDK_BACKEND=x11`; al item de la barra no le cambia nada, es DBus puro.
852
+ `QM_SIN_X11=1` lo fuerza a Wayland, donde el panel abre igual pero lo ubica el
853
+ compositor.
854
+
855
+ `bin/qm-indicator --captura panel.png` dibuja el panel a un archivo sin abrir
856
+ ventana, y `--captura-item item.png` el item de la barra; `--claro` / `--oscuro`
857
+ fuerzan el tema. Son las mismas funciones de dibujo que usan el panel y la
858
+ barra, así que los PNG no son una segunda implementación que se parece.
859
+
860
+ Cuatro cosas lo hacen algo más que un reloj:
861
+
862
+ - **Pregunta él.** `qm --breve` lee del disco y no habla con nadie, que es lo
863
+ que lo hace instantáneo — pero entonces el número es tan fresco como la última
864
+ vez que *alguien* preguntó, y Claude Code refresca su propio cache cuando
865
+ quiere: medido acá, **1 día y 11 horas** sin tocarlo, con la semanal 14 puntos
866
+ abajo de la realidad (75 % en pantalla, 89 % de verdad). Así que el indicador
867
+ corre `qm --calentar` él mismo, como ya hacían la barra de macOS y la bandeja
868
+ de Windows, y deja el número en el cache para que las lecturas sigan siendo de
869
+ disco. La cadencia es la misma de macOS —300 s de base, 240 arriba del 50 %,
870
+ 120 arriba del 75 %, 60 arriba del 90 %, con piso de 60 s— y sólo se refrescan
871
+ las cuentas que se mueven: pedirle el número a una que va al 9 % es gastar un
872
+ pedido para confirmar que no pasó nada.
873
+
874
+ Con una corrección sobre la política de macOS: **una barra en 100 no cuenta
875
+ como alta**. Ya no puede subir, así que hasta el reinicio no hay nada nuevo
876
+ que leer —y el instante del reinicio se sabe sin preguntar—. Contándola, el
877
+ sondeo se iba al piso de 60 s para mirar un número congelado: un pedido por
878
+ minuto, a un endpoint que no es nuestro, para confirmar que seguís frenado.
879
+ - **Dice de cuándo es cada número.** Cada tarjeta cierra con `lecturas: cada
880
+ ~4m · última hace 42s`, y el panel con `próxima lectura en 3m 16s`, que baja a
881
+ la vista mientras lo mirás. El «cada cuánto» no es la cadencia que el programa
882
+ se propone sino la **medida**: el historial se indexa por `medidoEn` —el
883
+ instante que informa el servidor, no el momento en que qm miró el disco— así
884
+ que cada muestra es una lectura real y los huecos entre muestras son los
885
+ intervalos entre lectura y lectura. Va la mediana y no el promedio, porque una
886
+ sola pausa larga (la máquina suspendida) no dice nada del ritmo normal.
887
+ - **Se entera solo.** Vigila el `.claude.json` de cada perfil con
888
+ `Gio.FileMonitor`: cuando Claude Code refresca la cuota, el número cambia en
889
+ el acto. Medido: de 82 % a 96 % en menos de 5 s sin reiniciar nada. El sondeo
890
+ cada 5 min queda de red de seguridad.
891
+ - **Avisa sin que lo mires.** Notifica al cruzar 80 % y 95 % —por **todas** las
892
+ barras, no sólo por la que frena: la semanal puede estar tranquila mientras la
893
+ de sesión te para, y al revés— y cuando la proyección pasa a decir que tocás
894
+ el techo *antes* del reinicio, que es el momento útil y no cuando ya chocaste.
895
+ - **Y avisa cuando te liberás**, que es el único aviso que sirve para hacer algo
896
+ distinto ahora mismo: la ventana se reinició habiendo estado contra el techo.
897
+ Un porcentaje solo no alcanza para verlo —3 % puede ser «recién empezás» o
898
+ «acabás de salir de estar frenado»— así que se guarda el minuto de reinicio
899
+ junto al número en `previos.json`: cuando el minuto cambia, la ventana es
900
+ otra. Justo el momento en que dejaste de mirar la barra, porque no había nada
901
+ que mirar.
902
+ - **No repite.** Cada aviso de umbral se recuerda por perfil, barra y minuto de
903
+ reinicio, así que una ventana avisa una vez y vuelve a avisar recién en la
904
+ siguiente. El de liberación no lleva memoria a propósito: tiene que sonar
905
+ cada vez que pasa.
906
+
907
+ El icono acompaña: normal, `dialog-warning` desde 80 %, `dialog-error` al 95 %
908
+ o cuando la proyección dice que chocás. `bin/qm-indicator` no sabe qué es una
909
+ credencial: le pide el JSON a `qm` y dibuja.
910
+
911
+ Necesita el soporte de AppIndicator en GNOME —la extensión
912
+ `appindicatorsupport@rgcjonas.gmail.com`—, que es lo que convierte un
913
+ `StatusNotifierItem` en un item de la barra. Verificado en GNOME Shell 48.7
914
+ sobre Wayland. Para sacarlo: «Salir» en su propio menú, y
915
+ `rm ~/.config/autostart/quartermaster.desktop`.
916
+
917
+ Un detalle del click del medio que cuesta una tarde si no está escrito: el
918
+ objetivo de `set_secondary_activate_target()` tiene que ser un item que **viva
919
+ adentro del menú** y esté marcado visible. Con un widget suelto —o con uno sin
920
+ `show()`— libayatana descarta el evento y no dice nada. Y como el menú se
921
+ reconstruye en cada refresco, hay que volver a apuntarlo cada vez o el click
922
+ deja de hacer efecto en silencio.
923
+
924
+ ### Un click, con extensión propia
925
+
926
+ ```bash
927
+ make extension # instala y habilita quartermaster@legios
928
+ make extension-quitar # y lo deshace
929
+ ```
930
+
931
+ `extension/quartermaster@legios` es una extensión de GNOME Shell de unas cien
932
+ líneas que **no sabe qué es una cuota**. Hace dos cosas: muestra el PNG que
933
+ dibuja `qm-indicator` y, cuando le hacen click, deja un pedido en un archivo
934
+ para que ese proceso abra su panel. Todo el dibujo y todos los números siguen
935
+ viviendo del lado de Python. A cambio, el item es nuestro y **el primer click
936
+ abre el panel** — y el segundo lo cierra.
937
+
938
+ Mientras la extensión está habilitada escribe `~/.cache/quartermaster/extension-viva`,
939
+ y al verlo `qm-indicator` pone su propio item de AppIndicator en `PASSIVE` para
940
+ que no queden dos diciendo lo mismo. No lo destruye: la extensión se puede
941
+ apagar en cualquier momento y el item vuelve solo, sin reiniciar nada.
942
+
943
+ La conversación va por archivos y no por DBus a propósito: son dos procesos que
944
+ ya comparten un directorio de cache, un `Gio.FileMonitor` de cada lado alcanza,
945
+ y no hay que registrar un nombre de bus ni una interfaz para decir «abrí el
946
+ panel». Con una trampa que hay que saber: **una escritura son varios eventos de
947
+ inotify** —se midieron tres, `changed`, `changed`, `changes-done-hint`— así que
948
+ el pedido se junta con un temporizador antes de atenderlo. Sin eso, un click
949
+ abría el panel y los dos eventos siguientes lo cerraban en el mismo instante, y
950
+ desde afuera parecía que el item no hacía nada.
951
+
952
+ **GNOME Shell no carga una extensión recién instalada en Wayland**: hay que
953
+ cerrar sesión y volver a entrar una vez. `ReloadExtension` está deprecada y
954
+ devuelve error, y `EnableExtension` sobre una que el shell todavía no vio
955
+ devuelve `false`.
956
+
957
+ ### Las cuatro escaleras de duración
958
+
959
+ Hay una implementación de la misma escalera por lenguaje —TypeScript, Python,
960
+ Swift, PowerShell— y la regla de que todas den lo mismo estaba escrita en los
961
+ comentarios pero no comprobada. El resultado: **convivieron dos convenciones**,
962
+ tres GUIs de un lado y el CLI del otro, en tres puntos a la vez.
963
+
964
+ | segundos | el CLI decía | las tres GUIs decían |
965
+ |---|---|---|
966
+ | −1 | `vencido` | `ya` |
967
+ | 3600 | `1h00m` | `1h` |
968
+ | 86400 | `1d` | `1d0h` |
969
+
970
+ Sobrevivió porque nadie había comparado **una GUI contra el CLI**: la
971
+ comparación que lo encontró fue entre dos GUIs. Ganó el CLI —`src/render/barras.ts`
972
+ es donde el propio repo dice que pasa todo lo que se imprime, y es la única con
973
+ tests— y las otras tres se alinearon.
974
+
975
+ `make gate-duraciones` congela el canon en `test/fixtures/duraciones.json` y
976
+ **corre las cuatro** contra esa tabla. Las que no tienen intérprete en la máquina
977
+ se saltean diciéndolo; en CI cada job exige los suyos con `QM_GATE_EXIGE`, así
978
+ que Ubuntu comprueba PowerShell y un runner de macOS comprueba Swift. Saltear en
979
+ silencio convertiría el gate en un adorno.
980
+
981
+ ### El gate que faltaba
982
+
983
+ `npm test` cubre el núcleo en TypeScript, y hasta acá eso era todo lo que
984
+ miraba el CI. Afuera quedaban las 1.400 líneas de Python que dibujan el panel y
985
+ el item, y la extensión de GNOME Shell. No es hipotético: sacando código muerto
986
+ de `bin/qm-indicator`, un corte demasiado ancho se llevó puesto el bloque entero
987
+ del panel —unas 700 líneas— y el archivo siguió compilando, así que el CI siguió
988
+ en verde. Se descubrió a mano.
989
+
990
+ ```bash
991
+ make gate-dibujo
992
+ ```
993
+
994
+ Mira tres cosas, en orden de qué tan barato es equivocarse: que el indicador
995
+ **compile**, que la extensión **parsee** —un error ahí lo ve GNOME al iniciar
996
+ sesión, que es el peor momento para enterarse— y que **dibuje**, con
997
+ `test/fixtures/panel.json` de entrada, saliendo con las medidas de siempre y con
998
+ píxeles adentro. Lo tercero es lo que no se puede reemplazar por un import: un
999
+ error de Cairo no rompe la importación del módulo.
1000
+
1001
+ Y el chequeo de píxeles no es decorativo: un PNG del tamaño correcto y
1002
+ enteramente transparente pasa cualquier verificación de medidas sin haber
1003
+ dibujado nada. Probado en rojo contra cuatro sabotajes en
1004
+ [`numeros/gate-rojo.md`](numeros/gate-rojo.md).
1005
+
1006
+ ## En la bandeja de Windows
1007
+
1008
+ ```bash
1009
+ make tray # lo arranca ahora (desde WSL)
1010
+ make tray-autostart # y que arranque solo al iniciar sesión de Windows
1011
+ ```
1012
+
1013
+ El panel es el mismo dibujo que `VistaResumen` y `VistaCuenta` en
1014
+ `bin/qm-barra.swift`: cabecera con el anillo de **lo primero que te frena**, y
1015
+ después una sección por cuenta con el glifo del producto, cuenta y plan,
1016
+ medidores redondeados con la paleta de estado, porcentaje a la derecha, un pie
1017
+ con el reinicio y la edad del cache, la curva de las últimas muestras pegada a
1018
+ la barra que frena, y el ritmo. En WinForms no se puede pintar un item de menú
1019
+ sin subclasear, así que cada sección se dibuja a un `Bitmap` y el `Bitmap` va
1020
+ adentro de un `PictureBox` hosteado en el menú. El efecto es el mismo; el
1021
+ camino, no.
1022
+
1023
+ **El ícono nunca es un número.** La primera versión dibujaba el porcentaje
1024
+ adentro del ícono, como los medidores de batería. Se renderizó a 16×16 —el
1025
+ tamaño real de la bandeja a 96 dpi— y se miró: **un dígito se lee, dos son una
1026
+ mancha.** Así que el número se fue al tooltip y al menú, y el ícono hace de
1027
+ medidor: la forma dice cuánto va, el color dice cuánto importa, y las dos cosas
1028
+ sobreviven a 16 píxeles.
1029
+
1030
+ **Y hay un ícono por cuenta, no uno solo.** La barra de menú de macOS no muestra
1031
+ un medidor: muestra una **tira** —glifo, medidor y número, una vez por cuenta— y
1032
+ eso es lo que uno viene a mirar. En un item de bandeja no cabe: no tiene
1033
+ etiqueta de texto y es un cuadrado de 16×16. Así que la tira se reparte en
1034
+ varios items, uno por cuenta, con el glifo de su producto y el medidor de su
1035
+ semanal, y el número de la sesión en el tooltip. Comparten el mismo menú, así
1036
+ que hacer click en cualquiera abre el panel completo. El anillo quedó para el
1037
+ único caso que no tiene cuenta que dibujar: cuando `qm` no contesta.
1038
+
1039
+ **Dos cosas que aparecieron al mirarlo y no al leerlo.**
1040
+
1041
+ - **El color de cuenta necesitaba las dos tablas.** `colorCuenta()` en Swift
1042
+ devuelve un `NSColor` dinámico con una tabla clara y una oscura; el `.ps1`
1043
+ había copiado sólo la clara. Con el ícono a 16×16 sobre la barra de tareas
1044
+ negra de fábrica, los chevrones de codex —`#4a3aa7`— casi no estaban. Y hace
1045
+ falta elegir **dos veces**, porque el menú y la barra de tareas son
1046
+ superficies distintas con temas distintos: medido acá, `AppsUseLightTheme=0` y
1047
+ aun así `SystemColors.Menu` da `240,240,240` —los colores clásicos de Win32 no
1048
+ siguen al tema oscuro— mientras la barra de tareas sí es oscura.
1049
+ - **Cada perfil tiene un lugar fijo, tenga número o no.** macOS puede dejar
1050
+ afuera a una cuenta muda porque su tira es un solo dibujo que se rehace
1051
+ entero. Acá cada lugar es un item de bandeja, y Windows lo identifica por el
1052
+ hash de (ejecutable + UID) donde el UID lo reparte WinForms **por orden de
1053
+ creación** — visto en `HKCU\Control Panel\NotifyIconSettings`. Sacar y volver
1054
+ a poner un item corre los UID de los que vienen después, y con eso se le muda
1055
+ de cuenta la decisión de «este ícono va fijo en la barra» que el usuario tomó
1056
+ arrastrándolo.
1057
+
1058
+ **El costo de la tira, dicho de frente:** Windows decide por ícono si va a la
1059
+ barra o al desplegable de escondidos, y a los nuevos los manda al desplegable.
1060
+ Se arrastra una vez y, por lo del UID, la elección persiste.
1061
+
1062
+ **Y tiene modo oscuro.** El panel era el único de los cuatro renderizadores que
1063
+ salía siempre blanco, y la causa es la de arriba: `SystemColors.Menu` no sigue al
1064
+ tema de las apps. macOS lo saca de un `NSColor` dinámico y GNOME del tema de
1065
+ GTK, así que Windows era el único que tenía que preguntarle al registro, y el
1066
+ fondo se había quedado atrás mientras el color de cuenta ya lo hacía.
1067
+
1068
+ Pintar los dibujos en oscuro no alcanzaba: el marco del menú, el resaltado del
1069
+ item bajo el mouse y los separadores los pinta WinForms con su propia tabla, que
1070
+ es clara, y un panel oscuro adentro de un menú blanco se ve peor que el problema
1071
+ original. Va una `ProfessionalColorTable` heredada, y el tema entero vive en
1072
+ `AplicarTema`, que se relee en cada tick: cambiar Windows de claro a oscuro se
1073
+ nota en la vuelta siguiente sin reiniciar la bandeja.
1074
+
1075
+ **Y calienta el endpoint, como la barra de macOS.** Esto no es un detalle de
1076
+ adorno: fue el bug. La primera versión sólo leía el disco, y en la máquina donde
1077
+ se escribió esto el perfil por defecto **no tiene `cachedUsageUtilization` en su
1078
+ `.claude.json`** — ni viejo ni nuevo: no está. Mientras tanto el endpoint
1079
+ contestaba `weekly_scoped (Fable)` al **100 %**, `critical`. Una bandeja que sólo
1080
+ mira el disco mostraba, con toda honestidad, «todavía no dejó cuota para este
1081
+ perfil» al lado de un ícono verde, en una cuenta que estaba frenada. Es
1082
+ exactamente el silencio del que habla la primera sección de este README, con
1083
+ otra causa.
1084
+
1085
+ Así que `qm --calentar` se dispara con la misma cadencia adaptativa que
1086
+ `cadencia()` en Swift —300 s de base, 240 desde 50 %, 120 desde 75 %, 60 desde
1087
+ 90 %, y 60 si la proyección dice que faltan menos de 30 minutos para el techo— y
1088
+ sólo para las cuentas que se mueven (≥ 40 %), porque refrescar una que va al 9 %
1089
+ es gastar un pedido para confirmar que no pasó nada. Con `-SinCalentar` no se le
1090
+ pide nada a la red y se vuelve al comportamiento de sólo-disco.
1091
+
1092
+ Hay una diferencia con macOS que es de Windows y no se puede evitar: el timer
1093
+ corre en el hilo de la interfaz, así que en el tick automático el calentado **se
1094
+ dispara y se suelta**, y el número que trae lo levanta el tick siguiente (30 s).
1095
+ Esperarlo ahí congelaría el menú, que es peor que un número medio minuto tarde.
1096
+
1097
+ **«Actualizar ahora» sí espera, y no cierra el panel.** Empezó haciendo el mismo
1098
+ `Calentar; Refrescar` del tick, y ahí estaba el bug: el calentado tarda
1099
+ **~930 ms** y el `Refrescar` de atrás tarda **~250**, así que leía el cache de
1100
+ *antes* del calentado que él mismo acababa de disparar. El panel se cerraba
1101
+ —Windows cierra un menú al clickear un item— y el número era el que ya estabas
1102
+ mirando; había que esperar el tick. El botón decía «ahora» y no hacía nada ahora.
1103
+
1104
+ Ahora espera con un timer y no con el hilo —mira si el proceso del calentado
1105
+ terminó cada 250 ms, con techo de 15 s— y **el panel se queda abierto**: el
1106
+ cierre se cancela, pero sólo para este item, porque «Abrir tablero» y «Salir»
1107
+ tienen que seguir cerrándolo igual que clickear afuera o apretar Escape. Hacen
1108
+ falta dos handlers y no uno: `ItemClicked` corre antes que `Closing` y es el
1109
+ único que sabe *qué* se clickeó; `Closing` es el único que puede cancelar.
1110
+ Mientras el número llega, el item dice **«Actualizando…»** y no acepta otro
1111
+ click: dos segundos sin ninguna señal se leen como que no pasó nada, que es de
1112
+ donde vino todo esto.
1113
+
1114
+ Rehacer el menú estando **visible** necesita `SuspendLayout`/`ResumeLayout` —si
1115
+ no, cada `Add()` relayoutea el menú abierto y se lo ve saltar de tamaño una vez
1116
+ por sección— y un `PerformLayout` al final, porque sin él se queda con el alto
1117
+ viejo y recorta la última. De paso arregla un borde que ya existía: si dejabas
1118
+ el panel abierto más de 30 s, el tick también lo rehacía sin reacomodarlo.
1119
+
1120
+ Lo demás es igual a las otras dos: avisa al cruzar 80 % y 95 % y cuando la
1121
+ proyección dice que tocás el techo antes del reinicio, y no repite —la clave del
1122
+ aviso incluye el minuto de reinicio, así que una ventana avisa una vez y vuelve
1123
+ a avisar recién en la siguiente—. La memoria de avisos vive en
1124
+ `%LOCALAPPDATA%\quartermaster\avisados.json`.
1125
+
1126
+ Vale la misma regla que las otras dos: **sólo dibuja**. `bin/qm-tray.ps1` le
1127
+ pide el JSON a `qm` por stdout y no sabe qué es una credencial ni un endpoint.
1128
+ La regla de cuál barra manda no se reimplementa acá: llega resuelta en
1129
+ `mostrar`, `frena`, `sesion` y `semanal`.
1130
+
1131
+ No necesita instalar nada: PowerShell y WinForms ya están en cualquier Windows.
1132
+ `bin/qm-tray` es el lanzador del lado de WSL —traduce la ruta con `wslpath` y
1133
+ lanza `powershell.exe`—; el proceso vive del lado de Windows, así que si cerrás
1134
+ la terminal el tray sigue. Para sacarlo: «Salir» en su propio menú, o
1135
+ `make tray-quitar`, que además borra el atajo del arranque automático.
1136
+
1137
+ **Lo que está verificado y lo que no**, para que esta sección no mienta:
1138
+
1139
+ - Verificado en Windows 11 con Windows PowerShell 5.1: arranca, dibuja el menú
1140
+ contra los perfiles reales de esta máquina, sobrevive los ticks, sale por
1141
+ `make tray-quitar`, y el atajo de arranque lanza un tray que anda.
1142
+ - **El panel y los íconos se miraron, no se supusieron.** Los dos se
1143
+ renderizaron a PNG con los datos reales; los íconos, además, a los 16×16
1144
+ reales y agrandados con vecino más cercano sobre fondo claro y oscuro, que es
1145
+ mirar los píxeles que va a haber y no una versión cómoda. Ahí se vio que los
1146
+ dígitos no servían y que faltaba la tabla de color oscura. **El panel en
1147
+ oscuro se capturó del proceso vivo**, que se puede: un menú es una ventana
1148
+ normal y `CopyFromScreen` la agarra, al contrario que la barra de tareas, que
1149
+ la compone DWM y devuelve negro.
1150
+ - **La tira se verificó por UI Automation**, justamente porque la barra de
1151
+ tareas no se deja capturar: se le preguntó a la bandeja qué items tiene, y
1152
+ contestó uno por cuenta con su tooltip —incluidos los perfiles mudos y el `~`
1153
+ de cache viejo—, unos en la barra y otros en el desplegable.
1154
+ - **«Actualizar ahora» se probó con los handlers reales del archivo**, no con
1155
+ una copia: la función vuelve en 59 ms —no congela—, el panel sigue abierto
1156
+ después del click, el item muestra y saca el «Actualizando…», clickear
1157
+ cualquier otro item sí cierra, y con dos dibujos de alturas distintas a
1158
+ propósito el panel abierto pasa de 472 a 614 px y vuelve a 472 sin recortar
1159
+ nada.
1160
+ - **Los avisos están probados en la lógica, no en pantalla.** Ningún perfil pasó
1161
+ de 80 % cuando se probó, así que se ejercitaron con una barra sintética al
1162
+ 96 % y un `NotifyIcon` de mentira que anota los globos en vez de dibujarlos:
1163
+ dispara 80 y 95 con la severidad correcta, dispara el choque, **no repite** en
1164
+ la segunda pasada, y **vuelve a avisar** cuando cambia el minuto de reinicio.
1165
+ Lo que sigue sin verse es el globo de Windows en la pantalla.
1166
+ - **Handles medidos, no supuestos.** `GetHicon()` entrega un handle que el GC no
1167
+ libera, así que se destruye a mano. Medido sobre el proceso vivo, en tres
1168
+ muestras a lo largo de 300 s: 639, 589, 615. Fluctúa sin subir.
1169
+ - El `.ps1` está guardado **UTF-8 con BOM a propósito**: sin BOM, PowerShell 5.1
1170
+ lo lee como Windows-1252 y los acentos y las flechas salen rotos.
1171
+ - **Dos colisiones de nombre, las dos del mismo tipo.** PowerShell no distingue
1172
+ mayúsculas, así que `$script:Mono` y el parámetro `$mono` eran la misma
1173
+ variable, y `$PALETA` empezó llamándose `$NIVEL` y la tapaba la local
1174
+ `$nivel`. Las dos aparecieron corriendo el código, no leyéndolo.
1175
+
1176
+ ## En la statusline de Claude Code
1177
+
1178
+ Es donde la herramienta cumple su misión: el número deja de ser algo que te
1179
+ acordás de mirar y pasa a estar siempre a la vista. `--breve` no toca las
1180
+ transcripciones, así que tarda ~85 ms en vez de un segundo.
1181
+
1182
+ En el `settings.json` del perfil:
1183
+
1184
+ ```json
1185
+ {
1186
+ "statusLine": { "type": "command", "command": "qm --breve" }
1187
+ }
1188
+ ```
1189
+
1190
+ Sale así, con `!` para la barra que el servidor marcó con aviso y `~` para un
1191
+ cache de más de 6 horas:
1192
+
1193
+ ```
1194
+ personal 23/75%! · teams 9/42% · codex 49/59%
1195
+ ```
1196
+
1197
+ Son **dos números por cuenta a propósito**: el primero es la sesión y el segundo
1198
+ la barra que te frena antes. Contestan preguntas distintas —«¿puedo seguir
1199
+ ahora?» y «¿llego al final de la semana?»— y una sola de las dos deja media
1200
+ respuesta. Cuando la que frena ES la sesión, se muestra un número solo.
1201
+
1202
+ Ojo con lo que **no** hace: el cache se refresca cuando ese perfil corre Claude
1203
+ Code, así que la statusline de un perfil se actualiza usándolo. Es suficiente
1204
+ para la mecánica que importa —enterarte de que vas al 75 % mientras trabajás—
1205
+ y no para vigilar un perfil que no estás usando.
1206
+
1207
+ ## El build, y por qué es opcional
1208
+
1209
+ El repo lee el TypeScript directo: no hay paso de build y `make instalar`, el
1210
+ `.deb` y Homebrew funcionan así. **npm es la excepción, y no por gusto.** Node
1211
+ se niega a hacer type stripping de cualquier archivo bajo `node_modules`:
1212
+
1213
+ ```
1214
+ ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING
1215
+ Stripping types is currently unsupported for files under node_modules
1216
+ ```
1217
+
1218
+ Y un `npm install -g` deja el paquete exactamente ahí. Medido: se empaquetó el
1219
+ tarball, se instaló en un prefix limpio y `qm` murió; se copió *ese mismo
1220
+ directorio* fuera de `node_modules` y corrió perfecto. Mismo código, mismo Node,
1221
+ misma versión — cambia sólo la ruta.
1222
+
1223
+ Así que `npm run construir` compila `src/` a `dist/` y **sólo el tarball de npm
1224
+ lleva `dist/`**. `bin/qm` prefiere `dist/cli/qm.js` si existe y si no lee
1225
+ `src/cli/qm.ts`, de modo que un clone sigue sin necesitar build.
1226
+
1227
+ ```sh
1228
+ make construir # compila a dist/ — sólo hace falta para publicar
1229
+ make gate-npm # empaqueta, instala en un prefix limpio y CORRE qm
1230
+ make gate-npm-rojo # el rojo: el paquete sin dist/, que es como estaba
1231
+ ```
1232
+
1233
+ El piso de Node **no** baja con el build: sigue en 22.6 porque
1234
+ `src/adapters/opencode.ts` usa `node:sqlite`.
1235
+
1236
+ ## Diseño
1237
+
1238
+ ```
1239
+ src/core/ perfiles, tipos. No sabe de llaveros ni de HTTP.
1240
+ src/adapters/ credenciales (llavero / archivo), transcripciones (JSONL),
1241
+ cuota del cache (.claude.json) y del endpoint (HTTP), el
1242
+ parser de la forma de utilización que comparten los dos, y
1243
+ codex (JSON-RPC contra su app-server, con cache propio).
1244
+ src/cli/ qm (el comando) y las demos de cada hito.
1245
+ dist/ el JS compilado. No se comitea; sólo viaja en el tarball de
1246
+ npm, porque Node no lee TypeScript bajo node_modules.
1247
+ src/render/ barras y formato para la terminal, y tablero.html para el
1248
+ navegador. Sin dependencias.
1249
+ extension/ la extensión de GNOME Shell que se queda con el click
1250
+ bin/ el lanzador que encuentra un Node, el indicador de GNOME, la
1251
+ bandeja de Windows, la barra de macOS y el servidor del
1252
+ tablero. Todos dibujan y nada más: le piden el JSON a qm y no
1253
+ saben de credenciales ni de HTTP.
1254
+ ```
1255
+
1256
+ La regla es la de siempre: si un nombre de vendor o una ruta de sistema
1257
+ operativo aparece fuera de `src/adapters/`, es un bug de diseño.
1258
+
1259
+ ## Licencia
1260
+
1261
+ MIT. Es la excepción a propósito: el núcleo de Legios —cartographer, healer,
1262
+ pipeline— es propietario, y se publica lo que sirve suelto. Esto sirve suelto.
1263
+
1264
+ ---
1265
+
1266
+ <div align="center">
1267
+
1268
+ <a href="https://github.com/legiosai"><picture>
1269
+ <source media="(prefers-color-scheme: dark)" srcset="docs/legios.svg">
1270
+ <source media="(prefers-color-scheme: light)" srcset="docs/legios-claro.svg">
1271
+ <img alt="Legios" src="docs/legios-claro.svg" width="150" height="49">
1272
+ </picture></a>
1273
+
1274
+ <sub>Construido por Valentín Torassa y Sol Soletti.</sub>
1275
+
1276
+ </div>