@legios/quartermaster 0.1.5 → 0.1.7

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 (41) hide show
  1. package/README.md +185 -1445
  2. package/bin/buscar-node.cmd +80 -0
  3. package/bin/qm +17 -0
  4. package/bin/qm-barra +38 -0
  5. package/bin/qm-indicator +261 -8
  6. package/bin/qm-tray-quitar.cmd +19 -0
  7. package/bin/qm-tray.cmd +20 -0
  8. package/bin/qm-tray.ps1 +150 -21
  9. package/bin/qm-web +25 -2
  10. package/bin/qm-web.cmd +22 -0
  11. package/bin/qm.cmd +52 -0
  12. package/bin/qm.mjs +89 -0
  13. package/dist/adapters/barra.js +154 -0
  14. package/dist/adapters/barra.js.map +1 -0
  15. package/dist/adapters/credenciales.js +21 -14
  16. package/dist/adapters/credenciales.js.map +1 -1
  17. package/dist/adapters/entorno.js +223 -0
  18. package/dist/adapters/entorno.js.map +1 -0
  19. package/dist/adapters/transcripciones.js +28 -0
  20. package/dist/adapters/transcripciones.js.map +1 -1
  21. package/dist/cli/qm.js +212 -8
  22. package/dist/cli/qm.js.map +1 -1
  23. package/dist/core/presupuesto.js +69 -3
  24. package/dist/core/presupuesto.js.map +1 -1
  25. package/dist/core/tipos.js +43 -2
  26. package/dist/core/tipos.js.map +1 -1
  27. package/package.json +4 -2
  28. package/scripts/bumpear.mjs +127 -0
  29. package/scripts/construir.mjs +15 -4
  30. package/scripts/cortar-release.sh +76 -0
  31. package/scripts/gate-bandeja.ps1 +86 -3
  32. package/scripts/gate-calentado.py +165 -0
  33. package/scripts/gate-paquetes.sh +118 -0
  34. package/scripts/gate-windows.ps1 +198 -0
  35. package/scripts/hacer-deb.sh +10 -0
  36. package/scripts/hacer-extension-zip.sh +123 -0
  37. package/scripts/hacer-manifests.mjs +224 -0
  38. package/scripts/hacer-setup.ps1 +116 -0
  39. package/scripts/instalar-barra.mjs +57 -59
  40. package/scripts/mandar-pr-winget.mjs +189 -0
  41. package/scripts/quartermaster.iss +249 -0
package/README.md CHANGED
@@ -4,1535 +4,275 @@
4
4
 
5
5
  # quartermaster
6
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.
7
+ **How much quota you have left — in every agent account on the machine.**
8
+ Every Claude Code profile, not just the default one, plus Codex and the
9
+ providers stored by opencode.
9
10
 
10
11
  [Landing](https://quartermaster.legios.com.ar/) ·
11
- [Instalar](#instalar) ·
12
+ [Install](#install) ·
12
13
  [Releases](https://github.com/legiosai/quartermaster/releases) ·
14
+ [Security](SECURITY.md) ·
15
+ [En castellano](LEEME.md) ·
13
16
  MIT
14
17
 
15
- <sub>Un instrumento de</sub><br>
18
+ <sub>An instrument by</sub><br>
16
19
  <a href="https://github.com/legiosai"><picture>
17
20
  <source media="(prefers-color-scheme: dark)" srcset="docs/legios.svg">
18
21
  <source media="(prefers-color-scheme: light)" srcset="docs/legios-claro.svg">
19
22
  <img alt="Legios" src="docs/legios-claro.svg" width="132" height="43">
20
23
  </picture></a>
21
24
 
22
- <img src="docs/img/barra.png" alt="La barra de arriba de GNOME con un medidor por cuenta" width="480">
25
+ <img src="docs/img/barra.png" alt="The GNOME top bar with one meter per account" width="480">
23
26
 
24
27
  </div>
25
28
 
29
+ > **Mission.** Nobody should find out their quota is gone by hitting the wall.
26
30
 
27
- > **Misión.** Que nadie se entere de que se quedó sin cuota chocándose contra el
28
- > límite.
31
+ ## The problem
29
32
 
30
- Ver [`SOUL.md`](SOUL.md) para la métrica, los non-goals y la apuesta falsable.
33
+ Claude Code supports several profiles through `CLAUDE_CONFIG_DIR`, and each one
34
+ has its own account and its own credential. A work seat and a personal
35
+ subscription on the same laptop is ordinary.
31
36
 
32
- ## Instalar
37
+ Every monitor out there reads **one** credential: the default directory's. On
38
+ the machine this was written on, that means reading `~/.claude` — which is
39
+ empty — while the two real accounts live in `~/.claude-personal` and
40
+ `~/.claude-teams`. The observed result was a monitor polling every 120 seconds
41
+ for hours, logging `credential expired — gating poll`, and displaying nothing.
33
42
 
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
- ```
43
+ quartermaster finds every account, and reads the number from disk.
45
44
 
46
- O desde el repo, sin instalar nada global:
45
+ ## Install
47
46
 
48
47
  ```sh
49
- git clone https://github.com/legiosai/quartermaster && cd quartermaster
50
- npm install && make instalar # deja `qm` en ~/.local/bin
48
+ brew install legiosai/tap/quartermaster # macOS and Linux
49
+ npm install -g @legios/quartermaster # anywhere
51
50
  ```
52
51
 
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 ✅ el CLI · ⏳ la credencial | [`numeros/h4-linux.md`](numeros/h4-linux.md) · [`h4-windows.md`](numeros/h4-windows.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
- - **En Windows nativo el CLI anda; la credencial sigue sin verificarse.**
144
- Medido y comiteado en [`numeros/h4-windows.md`](numeros/h4-windows.md): con
145
- Node nativo, `qm` contesta `plataforma: win32`, descubre los perfiles en rutas
146
- de Windows y lee la cuota de Codex del disco sin red ni credencial. Lo que
147
- sigue abierto es si Claude Code guarda la suya en `.credentials.json` o en
148
- DPAPI, y **no se pudo contestar porque en esa máquina Claude Code nunca corrió
149
- nativo**: no está en el PATH, no hay `.claude.json`, y el Credential Manager
150
- no tiene ninguna entrada de Anthropic. El adaptador sigue diciendo «sin
151
- verificar» en vez de inventar un diagnóstico.
152
- - **macOS va a abrir un prompt del llavero por perfil** si se usa `--refrescar`.
153
- El camino por defecto ya no toca el llavero.
154
-
155
- ## Segundo hallazgo: la cuota ya está en el disco
156
-
157
- Claude Code guarda en el `.claude.json` de cada perfil la última respuesta de
158
- cuota que recibió, bajo `cachedUsageUtilization`. El número de cuota **es un
159
- dato de disco**: no hace falta red, y sobre todo **no hace falta credencial**,
160
- así que se lee igual en un perfil con el token vencido — que es exactamente el
161
- estado en el que la herramienta que motivó este repo se quedaba muda.
162
-
163
- Y trae un segundo silencio, este adentro de un mismo perfil. La respuesta
164
- incluye un array `limits[]` con barras que **no** tienen clave propia arriba:
165
-
166
- | Barra | % | Severidad | ¿activa? | Alcance |
167
- |---|---:|---|---|---|
168
- | `session` (= `five_hour`) | 8 | normal | no | — |
169
- | `weekly_all` (= `seven_day`) | 59 | normal | no | — |
170
- | **`weekly_scoped`** | **75** | **warning** | **sí** | modelo Fable |
171
-
172
- `seven_day_opus`, `seven_day_sonnet` y otras diez venían `null`. Un monitor que
173
- lea `five_hour` y `seven_day` —las dos que documenta la statusline— informa
174
- **8 %**, se ve cómodo, y esconde la única barra con aviso. En esa cuenta el
175
- error es de 67 puntos. Detalle y medición en
176
- [`numeros/h5-cuota.md`](numeros/h5-cuota.md).
177
-
178
- ## La misma falla en Linux, y peor
179
-
180
- `numeros/h4-linux.md` es la primera corrida fuera de macOS. Encontró 4 perfiles,
181
- y con ellos una versión del problema original más difícil de notar: acá el
182
- directorio por defecto **no** está vacío. Tiene 1,2 G de tokens y se ve
183
- perfectamente sano.
184
-
185
- > Un monitor que sólo lee `~/.claude` en esa máquina muestra un número
186
- > creíble que deja afuera el **58,2 %** de los tokens y el **54 %** de los
187
- > requests, todos del perfil de trabajo.
188
-
189
- Un directorio vacío se nota. Un número que parece bien y está a la mitad, no.
190
-
191
- ## De dónde sale el endpoint de cuota
192
-
193
- No está documentado. Se leyó del binario que Claude Code instala
194
- (`node_modules/@anthropic-ai/claude-code/bin/claude.exe`), que contiene el call
195
- site:
196
-
197
- ```
198
- fetchUtilization: GET /api/oauth/usage (attempt
199
- fetchUtilization: 200 after
200
- ```
52
+ **The menu bar item on macOS:** the first time you run `qm` in a terminal, it
53
+ asks once whether to put it in the menu bar and start it at every login. The
54
+ install itself can't: brew can't start anything from a formula, and a tool that
55
+ reads OAuth tokens shouldn't register login agents nobody asked for. Without the
56
+ question: `brew services start quartermaster`.
201
57
 
202
- La **forma** de la respuesta ya no se adivina: `cachedUsageUtilization` guarda
203
- esa misma respuesta, y de ahí salieron las fixtures de `test/fixtures/`. Eso
204
- confirmó lo que este README sospechaba antes de tener con qué probarlo: la
205
- documentación de statusline embebida en el binario describe lo que Claude Code
206
- **republica** (`used_percentage`, epoch en segundos), no lo que **recibe**
207
- (`utilization`, ISO con offset). Un parser escrito sólo contra esa doc habría
208
- leído mal las fechas.
58
+ **Windows:** the installer from the [latest
59
+ release](https://github.com/legiosai/quartermaster/releases/latest). Per-user
60
+ and no UAC: it puts `qm` on your `PATH`, the tray in the Start menu, and — if
61
+ you leave the box ticked — the tray in startup.
209
62
 
210
- Corolario operativo: **el endpoint puede desaparecer sin aviso**, y por eso ni
211
- las transcripciones ni el cache son un fallback opcional (ver `SOUL.md`).
63
+ **Debian and Ubuntu:** the `.deb` from the same release, or the signed apt repo
64
+ ([two lines](LEEME.md#instalar)).
212
65
 
213
- ## La otra cuenta: Codex
66
+ **Arch:** a `PKGBUILD` in [`paquetes/aur/`](paquetes/aur/PKGBUILD).
67
+ **Nix:** `nix run github:legiosai/quartermaster`.
214
68
 
215
- Un asiento de trabajo, una suscripción personal y **una cuenta de Codex** en la
216
- misma laptop es tan normal como lo anterior, y la pregunta es la misma: ¿me
217
- queda cuota? Desde `src/adapters/codex.ts`, `qm` la contesta para las dos
218
- herramientas en la misma tabla.
69
+ Needs **Node >= 22.6**: `qm` reads its own TypeScript with no build step, and
70
+ type stripping starts there. The launcher looks for a usable Node on the `PATH`
71
+ and in nvm, fnm and volta; if it cannot find one it says so and explains how to
72
+ get one, rather than dying with a syntax error.
219
73
 
220
- ```
221
- codex vos@ejemplo.com · plus
222
- credencial: la pone codex · 2 reset(s) sin usar
223
- cache · hace 1m
224
- ▸ session ███████████████ 100% warning reinicia en 27m
225
- weekly_all ██████████░░░░░ 67% reinicia en 139h04m
226
- local: 13,0M en 7d · 5,3M en 5h · 443 requests
227
- ```
74
+ ## Use
228
75
 
229
- ### Con qué está autenticado manda sobre lo que dejó escrito
230
-
231
- Reportado a mano: la bandeja decía **`plus`** en una máquina sin ninguna
232
- suscripción. La causa estaba entera en el disco:
233
-
234
- - ocho rollouts en `~/.codex/sessions` con `"plan_type": "plus"` y barras de
235
- hasta el **94 %**, todos de **mayo de 2026**;
236
- - un `~/.codex/auth.json` que dice `"auth_mode": "apikey"` y no tiene `tokens`
237
- ni `id_token`, sólo una `OPENAI_API_KEY`.
238
-
239
- O sea: la suscripción existió, se dio de baja, y los rollouts de cuando existía
240
- no se borran nunca. `codexEnDisco()` buscaba el rollout más nuevo **que tuviera
241
- barras** y encontraba el del 5 de mayo, así que reportaba un plan que ya no está
242
- y un porcentaje de hace **127 días** como si fuera de ahora. Peor: en una cuenta
243
- que paga por uso y por lo tanto **no tiene barras**, mostraba barras.
244
-
245
- `auth_mode` es la señal autoritativa y ahora se mira **antes** que los rollouts.
246
- Con `apikey` la fila dice `sin-suscripcion` —«la cuenta no tiene límites de
247
- suscripción que reportar (API key o enterprise)»— y el plan pasa a ser
248
- `api key`. Es el mismo caso que las filas de opencode: un plan por API key cuyo
249
- porcentaje sólo existe del otro lado. Y de paso deja de levantarse un
250
- `app-server` con 20 s de timeout para preguntar algo que no puede contestar.
251
-
252
- La regla está clavada en `test/codex.test.ts`, incluidos los dos bordes que
253
- importan: un `auth.json` viejo sin `auth_mode` se deduce de qué guardó, y si
254
- están la key **y** el `id_token` —Codex deja la key vieja cuando entrás con la
255
- cuenta— gana el `id_token`, porque al revés una cuenta con suscripción de verdad
256
- quedaría reportada como si no la tuviera.
257
-
258
- ### Una corrección
259
-
260
- La primera versión de este README decía, en negrita, que **Codex no deja la
261
- cuota en el disco**. Era falso. Se habían mirado tres rollouts de junio, que
262
- traían `rate_limits: null`, y se generalizó a partir de ahí — el mismo error de
263
- método que el repo le critica a los monitores que leen una sola credencial.
264
-
265
- Los rollouts nuevos (codex-cli 0.153.4) **sí la traen**, adentro de los eventos
266
- `token_count`, con el timestamp al lado. Así que Codex no es la excepción a H5:
267
- es otro caso de H5. **El camino por defecto es el disco**, sin red y sin
268
- credencial, y el app-server queda como refresco — lo que `--refrescar` es para
269
- Claude. Medido: 212 ms para encontrar la lectura más nueva entre 138 rollouts.
270
-
271
- Dos trampas que costaron un rato y que están cubiertas por tests:
272
-
273
- - **Codex escribe varios baldes de límites.** Después del bueno
274
- (`limit_id: "codex"`) manda uno de `limit_id: "premium"` con `primary: null`.
275
- Quedarse con el último devolvía ese, y descartarlo descartaba el archivo
276
- entero — con el número bueno adentro, unos milisegundos antes.
277
- - **Las dos puntas escriben distinto.** El rollout usa `snake_case`
278
- (`used_percent`, `rate_limit_reached_type`) y el app-server `camelCase`. Se
279
- normaliza en un solo lugar, y hay un test que exige que las dos den
280
- exactamente lo mismo: si divergen, el número cambia según de dónde salió, que
281
- es peor que no tener número. Ese test encontró que `rate_limit_reached_type`
282
- no se leía del disco, así que «ya te frenó» no marcaba nada.
283
-
284
- ### Y el piso, que también estaba
285
-
286
- Los mismos rollouts tienen `total_token_usage`, así que Codex tiene el consumo
287
- local que pide `SOUL.md`: aunque el app-server se caiga **y** el disco no traiga
288
- barras, sigue habiendo un número. Se suma el último acumulado de cada sesión, no
289
- los parciales, para no contar dos veces.
290
-
291
- Tres decisiones más:
292
-
293
- - **No tocamos su credencial.** Al app-server se le habla por el binario
294
- `codex`, que usa la suya. El mail y el plan salen de los claims del `id_token`
295
- que Codex ya guardó — se leen, no se copian.
296
- - **Los nombres de las ventanas se igualan por duración.** El servidor manda
297
- `primary` y `secondary`, que no dicen nada; 300 minutos es la misma pregunta
298
- que la `session` de Claude, y 10 080 es la semanal. Igualarlos es lo que deja
299
- comparar las dos cuentas en la misma columna.
300
- - **`codex` no se busca en el PATH y ya.** launchd arranca con
301
- `PATH=/usr/bin:/bin:/usr/sbin:/sbin`; hay un `rutaCodex()` que mira también
302
- los lugares de siempre, y `QM_CODEX` para forzarlo.
303
-
304
- ## Elegir qué se muestra
305
-
306
- Descubrir todo es la misión; **mostrar** todo es una preferencia. Con cuatro
307
- cuentas la barra de menú ya no entra, y una cuenta que no usás es ruido
308
- permanente.
309
-
310
- ```bash
311
- qm --solo=codex,personal # sólo esas
312
- qm --ocultar=teams # todas menos esa
76
+ ```sh
77
+ qm # quota and usage for every account
78
+ qm --breve # one line — this is what goes in a statusline
79
+ qm --json # the same, for scripts and panels
80
+ qm --refrescar # also ask the endpoint (needs a live token)
81
+ qm --watch 60 # redraw every N seconds
82
+ qm --umbral=80 # exit 3 if any bar is over N%
83
+ qm --esperar # block until quota drops: qm --esperar && codex ...
84
+ qm --diagnostico # everything a bug report needs, already redacted
313
85
  ```
314
86
 
315
- o fijo, en `~/.config/quartermaster/config.json`:
87
+ In Claude Code's `settings.json`:
316
88
 
317
89
  ```json
318
- { "ocultar": ["main"] }
90
+ { "statusLine": { "type": "command", "command": "qm --breve" } }
319
91
  ```
320
92
 
321
- Se acepta el nombre corto (`main`, `personal`, `teams`, `codex`) o el completo
322
- del perfil. `mostrar` gana sobre `ocultar`. Como todos los que dibujan leen el
323
- JSON de `qm`, la selección vale igual en la terminal, en la barra y en el
324
- tablero, sin configurar nada tres veces.
325
-
326
- Un detalle que es una regla del repo: **si el filtro no coincide con ninguna
327
- cuenta, se muestran todas** y se dice que el filtro no pegó. Casi siempre es un
328
- nombre mal escrito, y quedarse con una pantalla vacía y sin explicación es
329
- exactamente el bug que motivó todo esto.
330
-
331
- ## Sumar otra herramienta: Gemini, GLM, MiniMax
332
-
333
- La pregunta no es «¿se puede?» sino **de dónde sale el número**. Un proveedor
334
- tiene que contestar tres cosas, y sólo la primera es obligatoria:
335
-
336
- | | Qué es | Si falta |
337
- |---|---|---|
338
- | **1. Qué cuentas hay** | descubrir directorios/credenciales | no hay fila |
339
- | **2. Cuánta cuota queda** | barras con % y reinicio | hay fila y una frase que dice por qué no hay número |
340
- | **3. Cuánto consumiste** | el piso local, de transcripciones | se informa `null`, nunca `0` |
341
-
342
- Hoy hay dos formas resueltas, y las dos sirven de molde:
343
-
344
- - **Claude Code** — la cuota está en `.claude.json` (H5) y el endpoint es el
345
- refresco (H2).
346
- - **Codex** — la cuota está en los rollouts y el app-server es el refresco. El
347
- consumo sale de los mismos archivos.
348
-
349
- ### GLM y MiniMax: estaban adentro de opencode
350
-
351
- No hacía falta un CLI propio de cada uno. Los dos planes viven en **opencode**,
352
- y opencode deja en `~/.local/share/opencode/opencode.db` una tabla `session` con
353
- `model`, `cost` y cinco columnas de tokens. O sea: **el piso está**, local, sin
354
- red y sin credencial, igual que las transcripciones de Claude y los rollouts de
355
- Codex.
356
-
357
93
  ```
358
- minimax MiniMax-M3 2,7M en 7d · 2 sesiones
359
- glm glm-5.3 837,3k en 7d · 1 sesión
360
- openai gpt-5.6-sol 549,3k en 7d · 4 sesiones
361
- grok — 0 en 7d · último uso hace 8d21h
362
- kimi — 0 en 7d · último uso hace 14d18h
94
+ personal 23/75%! · teams 9/42% · codex 49/59%
363
95
  ```
364
96
 
365
- El descubrimiento y el consumo son dos preguntas distintas: las cuentas se
366
- listan por **último uso** (30 días) y no por lo que gastaron en la ventana. Si
367
- sólo se listara lo segundo, una cuenta que usás cada tanto desaparecería de la
368
- lista — y «no aparece» es exactamente lo que este repo existe para que no pase.
369
- Grok aparece con 0 en la semana y la fecha real al lado.
370
-
371
- Dos decisiones:
372
-
373
- - **No se lee `auth.json` de opencode.** Los proveedores se descubren de la base
374
- de sesiones, que además dice cuáles se usaron de verdad y no cuáles están
375
- configurados. La única forma segura de no filtrar una clave es no leerla.
376
- - **La cuota no se inventa.** Son planes por API key: el porcentaje sólo existe
377
- en el endpoint de cada proveedor y hace falta la clave para pedirlo. La fila
378
- trae consumo y una frase que dice por qué no hay barra — nunca un 0 % que
379
- parezca un dato. Es un estado nuevo y explícito, `sin-cuota-legible`, distinto
380
- de «no hay límites» y de «todavía no se escribió».
381
-
382
- ### Dos correcciones en la misma fila
383
-
384
- La fila de un plan de opencode traía dos cosas mal, y las dos salieron de
385
- mirarla en la pantalla, no de leer el código.
386
-
387
- **El plan mostraba el modelo.** Donde las otras filas ponen `team_tier_1` o
388
- `plus`, la de opencode ponía `glm-5.3`. Eso salía de `plan: c.modelo` — el id
389
- del modelo más usado en la ventana. Un modelo no es un plan: no dice qué pagás,
390
- y **cambia solo** cuando cambiás de modelo. Además ya estaba en el desglose por
391
- modelo, que es su lugar, así que aparecía dos veces. Ahora ese campo lleva el
392
- proveedor, y la columna significa lo mismo en todas las filas.
393
-
394
- **Y el mapa de nombres no aplicaba nunca.** Las claves eran `zai-coding-plan`,
395
- `minimax-coding-plan`, `kimi-for-coding`. El `providerID` que opencode guarda en
396
- esta máquina es **`zai`** a secas. Verificado contra la base: los proveedores
397
- reales son `zai`, `openai`, `amazon-bedrock`, `anthropic` y `opencode-go`. O sea
398
- que el nombre lindo no se aplicaba y la fila se llamaba `zai` en vez de `glm`.
399
- Ahora están las dos formas de cada uno, porque no hay motivo para creer que el
400
- `providerID` sea estable entre instalaciones — y esa suposición es justo la que
401
- falló acá.
402
-
403
- Ojo con esto último si tenés scripts: la cuenta ahora se llama `glm`, así que un
404
- `--solo=zai` o un `--ocultar=zai` hay que actualizarlo.
405
-
406
- ### Y una tercera: la fila no aparecía en ninguna pantalla
407
-
408
- Reportado a mano también: «no aparece lo de opencode que tengo una key de
409
- z.ai». Y era cierto — `filasOpencode()` arrancaba con
410
- `if (!hayOpencode() || o.breve) return []`, y **todas las pantallas piden
411
- `--breve`**: la barra de macOS, la bandeja de Windows, el panel de GNOME y la
412
- statusline. La fila existía sólo si corrías `qm` a mano en una terminal. Una
413
- cuenta que se usó ayer y no aparece es, literalmente, el bug de la primera
414
- sección de este README, con otro vendor.
415
-
416
- Lo que costaba se midió antes de decidir: de los ~460 ms de leer opencode,
417
- **439 eran `limitesOpencode()`** —la consulta que busca los 429 hace
418
- `json_extract` del blob de cada mensaje, 10 173 en esta máquina— y el consumo
419
- apenas 1,4 ms. Así que se arregló la consulta en vez de esconder la fila:
420
- acotada por fecha baja a **3 ms**, y no se pierde nada que se use, porque lo
421
- único que produce una barra es un límite cuyo reinicio todavía no pasó y ningún
422
- proveedor reinicia en más de un mes. Con eso opencode entero son ~25 ms, que sí
423
- entran en el contrato de `--breve`.
424
-
425
- ### Se probó de verdad antes de rendirse
426
-
427
- No alcanza con decir «no se puede». Se buscó el porcentaje por los cuatro
428
- caminos que había, con los endpoints reales sacados del binario de opencode:
429
-
430
- | Camino | Resultado |
431
- |---|---|
432
- | Cabeceras en la base de opencode | sólo las de OpenAI (`x-codex-*`), y sólo en respuestas con error |
433
- | `GET /models` con la clave | Z.ai **200**, MiniMax **200** — sin una sola cabecera `x-ratelimit-*` |
434
- | Una llamada real de 1 token | MiniMax **200**, sin cabeceras. xAI **403**: el token OAuth que guarda opencode está vencido |
435
- | Un archivo suyo en el disco | no existe |
436
-
437
- **Pero la llamada real encontró otra cosa.** Z.ai contestó `429` con esto:
97
+ **Two numbers per account, on purpose.** The first is the session; the second is
98
+ the bar that stops you first. They answer different questions — "can I keep
99
+ going right now?" and "do I make it to the end of the week?" — and either one
100
+ alone is half an answer.
438
101
 
439
- ```json
440
- {"error":{"code":"1310","message":"Weekly/Monthly Limit Exhausted.
441
- Your limit will reset at 2026-09-11 18:35:24"}}
442
- ```
102
+ ## When something is wrong
443
103
 
444
- O sea que el porcentaje no existe, pero **los dos datos que se usan sí**:
445
- ¿me frenaron? y ¿cuándo me libero? Y no hace falta salir a la red para
446
- tenerlos, porque **opencode guarda esas respuestas**: en su base hay límites
447
- alcanzados por proveedor, con la fecha de reinicio adentro del texto —incluida
448
- la ventana de 5 h de Grok—. Se leen del disco, gratis y sin credencial, igual
449
- que todo lo demás.
450
-
451
- Así que una cuenta de opencode que está frenada **sí muestra barra**: 100 %,
452
- con su reinicio y su «libre en». Una que no lo está no afirma nada — dice
453
- cuándo fue la última vez que la frenaron, porque un límite de la semana pasada
454
- no dice nada de hoy.
455
-
456
- Lo que encontré en esta máquina para la que falta:
457
-
458
- - **Gemini CLI 0.59.0** — instalado, autenticado (`oauth-personal`). Pero en
459
- `~/.gemini` **no hay ningún número de cuota ni de uso**: hay credenciales,
460
- cuentas, `installation_id` y estado de UI, y nada más. Su límite además no es
461
- un porcentaje sino requests por día, así que ni siquiera encaja en la forma
462
- `VentanaCuota` sin decidir antes qué significa «80 %» ahí. Da para el punto 1
463
- hoy; el 2 necesita encontrarle una fuente, y el 3 un lugar donde cuente
464
- tokens, que tampoco aparece.
465
- El molde está y la selección de arriba ya prevé que sobren cuentas: con siete,
466
- `--ocultar` deja de ser un lujo.
467
-
468
- ## Instalación
469
-
470
- ```bash
471
- npm install
472
- make instalar # enlaza bin/qm y bin/qm-web en ~/.local/bin
473
- qm # ya anda desde cualquier lado
474
- qm-web # y el tablero también
475
- ```
476
-
477
- `bin/qm` **busca solo un Node ≥ 22.6**: mira `$QM_NODE`, después el del `PATH`,
478
- después las versiones de nvm de mayor a menor. Hace falta porque qm se lee
479
- directo del TypeScript, y en una máquina donde `node` es un 20 —lo normal si el
480
- sistema trae uno y las versiones nuevas viven en nvm, que sólo se carga en
481
- shells interactivos— un shebang común falla con un error de sintaxis que no le
482
- dice nada a nadie.
483
-
484
- ## Uso
485
-
486
- ```bash
487
- qm # cuota y consumo de todos los perfiles.
488
- # Sin red y sin credencial: la cuota sale del disco
489
- qm --breve # un renglón, en milisegundos. Para una statusline
490
- qm --refrescar # además pide el número al endpoint (token vigente)
491
- qm --json # para scripts
492
- qm --watch 60 # se redibuja cada 60 s
493
- qm --umbral=80 # código de salida 3 si alguna barra pasa el 80 %
494
- qm --sin-codex # no mirar la cuenta de Codex
495
- qm --calentar-codex # refresca sólo el cache de Codex, sin imprimir nada
496
- qm-web # el tablero en el navegador, se redibuja cada 30 s
497
-
498
- make demo-h0 # ¿qué perfiles hay y cuáles autentican?
499
- make demo-h1 # consumo de los últimos 7 días, por perfil
500
- make numero-h5 # regenera numeros/h5-cuota.json, ya redactado
104
+ ```sh
105
+ qm --diagnostico
501
106
  ```
502
107
 
503
- Requiere **Node ≥ 22.6** (lee TypeScript directamente, no hay paso de build).
504
-
505
- ## ¿Vas a chocarte antes de que se reinicie?
506
-
507
- Es la pregunta que ni el porcentaje ni el consumo contestan solos. «Vas 75 %»
508
- no dice nada sin saber a qué velocidad subís.
108
+ One command, and you can paste the output straight into an issue: home paths
109
+ become `~`, and no e-mail, token or account id is ever printed.
509
110
 
510
- qm guarda una serie de lecturas por barra y le ajusta una recta:
111
+ It gathers what otherwise takes five commands nobody should have to know —
112
+ `gnome-extensions info`, `gdbus … GetExtensionErrors`, `journalctl --user -b`,
113
+ the cache directory, and `ps` for when the graphical session started — and it
114
+ **states the conclusion** rather than leaving you the data. The case that
115
+ prompted it:
511
116
 
512
117
  ```
513
- ritmo: 12.4 pts/h · 100 % en 1h58m — antes del reinicio
118
+ ⚠ extension.js es 12.9 h MÁS NUEVO que la sesión gráfica.
119
+ El shell carga el módulo una vez y lo deja en memoria: lo que está
120
+ corriendo es el archivo viejo …
121
+ → cerrá sesión y volvé a entrar. Es el único paso que falta.
514
122
  ```
515
123
 
516
- Lo que importa no es la recta, es **cuándo no se dibuja**. Con dos lecturas, o
517
- con una ventana que recién arranca, cualquier extrapolación es un número
518
- inventado con cara de dato. Entonces dice:
124
+ Anything it cannot find out it says so — it never omits and never guesses. It
125
+ works with none of those commands installed.
519
126
 
520
- ```
521
- ritmo: todavía no sé el ritmo: hacen falta 3 lecturas y hay 1
522
- ```
523
-
524
- «No sé si te vas a chocar» y «no te vas a chocar» son cosas distintas y se
525
- muestran distinto. Dos guardas más: se descartan las lecturas de más de 2 h
526
- —el ritmo de hace cuatro horas no predice el de ahora— y no se proyecta sobre
527
- un movimiento menor a 2 puntos, porque el servidor manda enteros y subir uno
528
- no se distingue de un redondeo.
529
-
530
- La serie vive en `~/.cache/quartermaster/historial.jsonl` y se indexa por el
531
- `medidoEn` de la cuota, no por el momento en que qm miró: leer diez veces el
532
- mismo cache deja **una** muestra.
533
-
534
- ## ¿Y cuánto me puedo gastar hoy?
535
-
536
- La proyección contesta «a este ritmo, cuándo choco». Es la pregunta del que ya
537
- va rápido. La del que todavía no chocó y quiere no chocar es otra: **cuánto
538
- puedo gastar por día para que la cuota llegue justa al reinicio, y cuánto de eso
539
- me queda hoy.** Un 78 % con reinicio el sábado no dice si mañana hay que frenar;
540
- repartirlo sí, y en la misma unidad que todo lo demás:
127
+ **The GNOME item also writes what it does** to stderr, which systemd's journal
128
+ picks up when it starts from the autostart entry:
541
129
 
542
- ```
543
- presupuesto: podés gastar 4.2 %/día · hoy te queda 1.8 % · weekly_scoped (Fable)
544
- ```
545
-
546
- La cuenta es de dos renglones y está en `src/core/presupuesto.ts`:
547
-
548
- ```
549
- porDia = (100 − porcentaje) / días hasta el reinicio
550
- quedaHoy = porDia × (horas que le quedan al día / 24)
130
+ ```sh
131
+ journalctl --user -b | grep qm-indicator
551
132
  ```
552
133
 
553
- Mira **hacia adelante**, y eso es lo que la hace honesta sin historial: todo lo
554
- que ya gastaste hoy está adentro del porcentaje actual, así que no hay que
555
- restarlo ni ir a buscarlo a un JSONL que puede no cubrir la medianoche. Si te
556
- pasaste de rosca a la mañana, `porDia` baja solo en la lectura siguiente y
557
- `quedaHoy` con él; si no tocaste nada, sube. Nunca da negativo.
558
-
559
- Dos decisiones que no son obvias:
560
-
561
- - **Se reparte la ventana larga, no la que frena.** Una de 5 h se reinicia
562
- cuatro veces por día: «cuánto por día» ahí no quiere decir nada, y un número
563
- que no quiere decir nada al lado de uno que sí es peor que no mostrarlo.
564
- - **A menos de una hora del reinicio no se reparte.** Cuatro puntos en veinte
565
- minutos dan «288 %/día», que es cierto y no le sirve a nadie. A esa altura la
566
- pregunta ya no es cómo dosificar sino cuánto falta, y ésa la contesta el reloj
567
- del reinicio, que está al lado.
568
-
569
- Cuando no se puede repartir sale la frase que dice por qué —«esta cuenta no
570
- informa una ventana larga que repartir»— y no un cero con cara de dato. Va en las
571
- cinco pantallas —`qm`, el tablero, la barra de menú de macOS, el panel de GNOME y
572
- el de la bandeja de Windows—, leyendo el mismo campo `presupuesto` del JSON: acá
573
- tampoco divide nadie.
574
-
575
- ## En el navegador
576
-
577
- El indicador de GNOME es la respuesta para GNOME. `qm-web` es la misma idea
578
- donde no hay barra de GNOME —macOS, Windows, un Linux con otro escritorio—: un
579
- tablero que se abre en el navegador y se redibuja solo cada 30 s.
580
-
581
- ```bash
582
- make web # levanta el tablero y abre el navegador
583
- qm-web --puerto=8080 # en otro puerto (por defecto 7391)
584
- qm-web --sin-abrir # sólo imprime la URL
585
134
  ```
586
-
587
- Muestra, de arriba abajo: **lo primero que te frena** —la peor barra de toda la
588
- máquina, con su cuenta regresiva al reinicio corriendo en vivo, la proyección
589
- si la hay y el presupuesto del día—, y después una tarjeta por perfil con todas
590
- sus barras, su presupuesto diario, la edad del cache, el consumo local de la
591
- ventana y el desglose por modelo. Un perfil sin
592
- número muestra la frase que dice por qué, igual que en la terminal.
593
-
594
- Vale la misma regla que el indicador: **sólo dibuja**. `bin/qm-web` le pide el
595
- JSON a `qm` por stdout y no sabe qué es una credencial ni habla HTTP con nadie.
596
- Escucha únicamente en `127.0.0.1` — el tablero muestra mails y planes, y
597
- `SOUL.md` dice que nada sale de la máquina.
598
-
599
- Es JavaScript común, no TypeScript, a propósito: corre con cualquier Node ≥ 18 y
600
- el requisito de 22.6 queda donde de verdad hace falta, adentro de `qm`.
601
-
602
- ## En la barra de menú de macOS
603
-
604
- ```bash
605
- make barra # lo compila la primera vez y lo arranca
606
- make barra-autostart # y que arranque solo al iniciar sesión, vía launchd
607
- make barra-quitar # para sacarlo
135
+ qm-indicator: pedido accion=actualizar
136
+ qm-indicator: calentar cuentas=.claude,.claude-teams,codex
137
+ qm-indicator: panel.abierto donde=arriba-derecha alto=1032
138
+ qm-indicator: panel.cerrado vivio_ms=3999
139
+ qm-indicator: panel.agarre-roto
140
+ qm-indicator: aviso clave=teams|weekly_all|2026-09-13T11:00|80 urgente=False
141
+ qm-indicator: qm.sin-datos motivo=qm salió 2: opción desconocida
608
142
  ```
609
143
 
610
- Queda un item arriba a la derecha que **se dibuja**. Por cada cuenta, tres
611
- cosas, y cada una quiere decir siempre lo mismo:
144
+ The events, and the question each one answers:
612
145
 
613
- ```
614
- ✳ ▍37 ✳ ▍21 <> ▍100
615
- ```
146
+ | event | answers |
147
+ | --- | --- |
148
+ | `pedido` | did the click reach the indicator at all? |
149
+ | `calentar` / `calentar.fallo` | which accounts were re-read, and why a refresh did not happen |
150
+ | `panel.abierto` / `panel.cerrado` | `vivio_ms` — a panel that lived 40 ms was not closed by you |
151
+ | `panel.agarre-roto` | the compositor took the grab away |
152
+ | `aviso` / `aviso.repetido` / `aviso.fallo` | it fired, it was suppressed as a duplicate, or the notification server refused it |
153
+ | `qm.sin-datos` | why there is no number, instead of only a phrase on screen |
154
+ | `reinicio` | the process replaced itself because the source changed |
155
+ | `suspension.duerme` / `.vuelve` | the machine slept, and the quota was re-read on resume |
156
+ | `calentar.colgado` | a warm never called back and its flag was released after the deadline |
616
157
 
617
- - **El glifo dice qué suscripción es.** La *forma* es el producto —el asterisco
618
- es la marca de Claude, los chevrones son código—; el *color*, cuál de ellas.
619
- Esos colores son azul, violeta y magenta: deliberadamente lejos de la paleta
620
- de estado, porque los colores de estado están reservados y no pueden
621
- significar además «esta es la cuenta 2».
622
- - **El medidor es la semanal**: ¿llego al final?
623
- - **El número es la sesión de 5 h**: ¿puedo seguir ahora? Se tiñe con su propio
624
- estado, pero recién cuando aprieta — si se pintara siempre, el color dejaría
625
- de querer decir algo.
626
-
627
- Antes el medidor mostraba «la que frena antes», que a veces era la semanal y a
628
- veces la sesión — y cuando era la sesión dibujaba lo mismo que ya decía el
629
- número al lado. Un encoding que cambia de significado según el dato no se lee de
630
- un vistazo, que es lo único que hace la barra de menú.
631
-
632
- `~` va pegado al número, porque califica a *ese* número: `~37` es «esta sesión
633
- es de hace rato».
634
-
635
- Hasta acá este archivo era **el único fuente del repo que no abría ningún
636
- gate**: `gate-duraciones.py` le extrae una función y compila esa sola, así que
637
- el resto podía tener un error de sintaxis y el CI pasaba en verde — el mismo
638
- agujero que tuvieron el indicador de GNOME y la bandeja de Windows, contado dos
639
- veces más abajo. Ahora `gate-dibujo.sh` le corre `swiftc -parse` desde Ubuntu:
640
- AppKit es de macOS, pero `-parse` sólo parsea —no carga módulos ni chequea
641
- tipos—, así que el error más barato de cometer deja de descubrirse recién cuando
642
- alguien compila en una Mac. Si ese `swiftc` igual no puede, el gate lo dice y se
643
- saltea; nunca se da por bueno en silencio.
644
-
645
- Cuando no entra, la escalera saca primero los glifos y **el número es lo último
646
- que se cae**. Antes era al revés y el item quedaba mudo justo en la parte que se
647
- viene a mirar: la identidad se recupera del orden y del menú, el número no se
648
- recupera de nada.
649
-
650
- Es lo que se hace en una barra de menú de macOS —una marca chica y callada, no
651
- un renglón de texto— y además es lo único que entra: **91 puntos contra los 192
652
- del renglón horizontal**, medido. Esa diferencia es la que decide si el sistema
653
- lo muestra o lo esconde.
654
-
655
- El item y que al desplegarlo muestra cada
656
- cuenta con su ícono (asterisco para Claude, chevrones para Codex; SF Symbols no
657
- trae los logos y estos dos se distinguen de un vistazo), con todas sus barras con todas sus barras, la edad del
658
- cache, la proyección y el motivo cuando un perfil no tiene número. `!` es una
659
- barra que el servidor marcó con aviso; `~` es un cache de más de 6 horas. Vale
660
- la misma regla que el indicador de GNOME: **sólo dibuja**, le pide el JSON a
661
- `qm --json --breve` (~150 ms, no toca las transcripciones) y no sabe qué es una
662
- credencial.
663
-
664
- Se compila con `swiftc`, que viene con las Command Line Tools: no hace falta
665
- Xcode entero, ni empaquetar una `.app`, ni instalar SwiftBar ni nada. El binario
666
- queda en `~/.cache/quartermaster/`, no en el repo. Se recompila solo cuando el
667
- fuente cambia.
668
-
669
- Al desplegarlo, cada cuenta es una fila **dibujada** —`VistaCuenta`, no un
670
- renglón de texto—: ícono del producto, cuenta y plan, y después cada barra con
671
- su medidor, su porcentaje, cuándo se reinicia, la edad del cache sobre la que
672
- manda, y el ritmo en rojo cuando la proyección dice que chocás. Los bloques
673
- `█░` de antes eran una tabla ASCII adentro de una app nativa.
674
-
675
- Hace lo mismo que en GNOME: se entera solo (vigila el `.claude.json` de cada
676
- perfil con `DispatchSource`, y se re-arma cuando Claude Code reescribe el
677
- archivo por rename, que mata el descriptor), avisa al cruzar 80 % y 95 % y
678
- cuando la proyección dice que chocás antes del reinicio, y no repite.
679
-
680
- ### Llegar tarde es la otra forma de mentir
681
-
682
- Codex subió del 23 % al 100 % en cuarenta minutos y la barra mostró 93 %
683
- durante siete de ellos. Mostraba la edad, así que no mentía — pero un número
684
- que llega tarde a esa velocidad no sirve para nada. Fueron **tres** bugs
685
- apilados, y ninguno hacía ruido:
686
-
687
- - **App Nap.** Una app sin ventanas es el candidato perfecto, y macOS le corre
688
- los timers: un sondeo de 5 minutos no disparó en 7. Se arregla con
689
- `ProcessInfo.beginActivity` y timers con `tolerance = 0` en `.common`.
690
- - **Cadencia fija.** Cinco minutos es inservible para una barra que sube 1,6
691
- puntos por minuto: se llega al 100 % adentro de una sola espera. Ahora la
692
- cadencia sale de lo que ya sabemos —cuán alto está y cuánto falta para el
693
- techo según la proyección—: 20 s arriba del 90 %, 45 s arriba del 75 %, 120 s
694
- arriba del 50 %, 5 min si no pasa nada. Y se recalcula **al terminar de
695
- dibujar**, que es cuando se conoce el estado; programarla en el arranque, con
696
- el estado todavía vacío, la dejaba clavada en 5 minutos.
697
- - **El PATH de launchd.** `PATH=/usr/bin:/bin:/usr/sbin:/sbin`, y `codex` vive
698
- en `/opt/homebrew/bin`. `spawn('codex')` fallaba **en silencio** justo en la
699
- instalación que importa —la que arranca sola— mientras andaba perfecto desde
700
- una terminal. Es el mismo bug que `bin/qm` ya resolvía para Node, y estaba sin
701
- resolver para Codex: ahora hay un `rutaCodex()` que busca en el PATH y en los
702
- lugares de siempre, y `QM_CODEX` para forzarlo.
703
-
704
- Medido después: refrescos cada 21 s con la sesión al 100 %.
705
-
706
- ### Y avisar de más es no avisar
707
-
708
- Los avisos se recordaban **en memoria**, así que cada arranque volvía a
709
- notificar todo lo que ya estaba cruzado — y arrancar pasa seguido: reinstalar,
710
- actualizar, reiniciar sesión. Con Codex al 100 % eso son tres notificaciones
711
- por arranque, siempre las mismas. Un aviso marca un *cruce*; repetirlo en cada
712
- arranque es ruido, y el ruido enseña a ignorarlos, que es exactamente lo
713
- contrario de lo que tienen que lograr.
714
-
715
- Ahora se persisten en `~/.cache/quartermaster/avisados.json`, con la misma clave
716
- de siempre (perfil, barra, minuto de reinicio, umbral), así que sobreviven al
717
- reinicio y la ventana siguiente vuelve a avisar sola. El aviso de «no entro en
718
- la barra» tampoco se re-arma: se re-armaba al volver a entrar, y un item que
719
- oscila entre visible y tapado avisaba en cada vuelta.
720
-
721
- ### Y Claude también llegaba tarde, por otro motivo
722
-
723
- Codex era el que se veía, pero Claude tenía el mismo problema con otra causa:
724
- **Claude Code refresca su propio `cachedUsageUtilization` cuando quiere.**
725
- Medido: reescribió `.claude.json` 19 s antes y el bloque de cuota seguía siendo
726
- de hacía 83 minutos, con la sesión 11 puntos abajo de la realidad. Mirar el
727
- disco más seguido no arregla nada — el número del disco no se mueve.
728
-
729
- Lo que lo arregla es H2, que por fin se ejecutó: `qm --calentar` le pide el
730
- número al endpoint de cada perfil y al app-server de Codex, y lo guarda. Con
731
- Claude hay un detalle que no es opcional: **la lectura fresca no se puede
732
- guardar donde Claude Code guarda la suya**. `.claude.json` es de él; este repo
733
- lee credenciales y configuración, no las escribe. Así que va a un cache propio
734
- (`~/.cache/quartermaster/endpoint.json`) y `qm` usa **la más nueva de las dos**,
735
- la de Claude Code o la nuestra, mostrando siempre la edad de la que ganó.
736
-
737
- El resultado es que `--breve` sigue tardando milisegundos y ya no lee un número
738
- de hace hora y media: la barra calienta el cache en su sondeo adaptativo y las
739
- lecturas rápidas encuentran algo de hace segundos.
740
-
741
- ### El título se mide, no se elige
742
-
743
- La barra de menú de una Mac con muesca tiene mucho menos lugar del que aparenta.
744
- Los items se acomodan de derecha a izquierda y **el sistema esconde, sin decir
745
- nada y con `isVisible` en `true`, al que caería abajo de la muesca**. Medido en
746
- la máquina donde se escribió esto: `NSScreen.auxiliaryTopRightArea` daba 645
747
- puntos a la derecha de la muesca, ya ocupados, y
748
- `personal ~50% · teams 42%` necesita 192.
749
-
750
- Por eso el texto no se elige: hay una **escalera** —el porcentaje con su marca,
751
- el porcentaje pelado, y nada— y se prueba uno, se mide dónde quedó, y si no
752
- entró se sigue con el siguiente. Los medidores no se negocian: son 30 puntos y
753
- dicen lo esencial aunque el número se caiga. En una Mac sin muesca o en un
754
- monitor externo entra el primero y se ve una cuenta por renglón.
755
-
756
- ### Diseñar a ciegas fue el error
757
-
758
- Nada de esto se podía ver: `screencapture` no sirve para mirar la barra —con
759
- varias pantallas se muda a la que tiene el foco, y encima el sistema esconde el
760
- item sin avisar—, así que las tres primeras versiones se dibujaron sin verlas y
761
- las tres estuvieron mal. La última, la de dos renglones, salía **recortada por
762
- arriba** y nadie se enteró hasta que hubo con qué mirarla.
763
-
764
- Por eso existe `qm-barra --captura ruta.png`: el item se renderiza a sí mismo
765
- sobre los dos fondos que puede tocarle y escribe dos PNG. No depende de qué
766
- pantalla mire nadie. Cualquier cambio al dibujo se mira ahí antes de creerle.
767
-
768
- ```bash
769
- qm-barra --captura /tmp/barra.png # escribe barra-claro.png y barra-oscuro.png
770
- ```
158
+ `vivio_ms` is the one that matters for "the panel closes on its own": a panel
159
+ that lives 40 ms was not closed by you. `QM_SILENCIO=1` turns it off.
771
160
 
772
- Otro detalle que costó una tarde: el test de «no entró» **no puede ser
773
- `frame.minX < 0`**. En una pantalla ubicada a la izquierda de la principal las
774
- coordenadas globales son negativas y el item se ve perfecto; hay que comparar
775
- contra el `frame` de su propia pantalla.
161
+ ## Where you can see it
776
162
 
777
- Y si ni el compacto entra, **lo dice**: notifica una vez, porque un número que
778
- no se ve es el mismo bug que el silencio. La salida en ese caso es la de macOS:
779
- **cmd-arrastrar** el item a un hueco de la barra (queda guardado, el item tiene
780
- `autosaveName`), liberar algún ícono, o mirar el tablero con `make web`.
163
+ | | |
164
+ |---|---|
165
+ | **Terminal** | `qm`, and `qm --breve` for a statusline — it skips transcripts, so it takes milliseconds |
166
+ | **GNOME** | an item in the top bar, panel on the first click. Ships its own Shell extension, because the AppIndicator one eats the left click |
167
+ | **macOS** | the menu bar, with live text next to the icon |
168
+ | **Windows** | the notification area, with the percentage drawn inside the icon like a battery meter |
169
+ | **Browser** | `qm-web` — a local dashboard on `127.0.0.1` only. Works everywhere |
170
+ | **waybar** | [`paquetes/waybar/`](paquetes/waybar/) — for Hyprland, Sway and river |
781
171
 
782
- ## En la barra de arriba de GNOME
172
+ All of them only draw. The CLI resolves which bar wins and emits the resolved
173
+ answer in `qm --json` (`mostrar`, `frena`, `sesion`, `semanal`); no renderer
174
+ reimplements a rule. That is a design rule with a scar behind it: the same
175
+ function once lived in Python, JavaScript and Swift at the same time.
783
176
 
784
- ```bash
785
- make indicador # lo arranca ahora
786
- make autostart # y que arranque solo al iniciar sesión
787
- ```
177
+ ## What it reads, and what leaves the machine
788
178
 
789
- Queda un item en la barra que **se dibuja**: un medidor vertical por cuenta, en
790
- el orden del panel, más el glifo del producto y el número de la sesión. Es el
791
- mismo dibujo que el item de la barra de macOS y con las mismas medidas — tres
792
- cuentas entran en el ancho de una palabra:
179
+ The number needs **no network and no credential**. Claude Code stores the last
180
+ quota response it got in each profile's `.claude.json`, so quartermaster reads
181
+ it from disk — which means it still works on a profile whose token expired,
182
+ the exact state the motivating monitor died in.
793
183
 
794
- ```
795
- ✳ ▮ 8 ✳ ▮ 22 ‹› ▮ 42
796
- ```
184
+ The only thing that ever leaves is one request, and only when you ask for it
185
+ (`--refrescar`, or `--calentar`, which is what the panels run):
797
186
 
798
- El glifo dice QUÉ suscripción es —la forma, el producto; el color, cuál de
799
- ellas—. El medidor es **siempre la semanal**, pintado por severidad. El número
800
- es **siempre la sesión de 5 h**, que es la que contesta «¿puedo seguir ahora?»,
801
- y se tiñe recién cuando aprieta. Sin marcas al lado del número: un `~` de
802
- «cache viejo» pegado a la cifra obliga a saber qué significa para poder leer la
803
- cifra, y la edad del cache ya está escrita con todas las letras en el panel.
804
-
805
- Que un dibujo entre en la barra de GNOME depende de una puerta que la extensión
806
- deja abierta sin documentar: si el nombre del ícono empieza con `/` lo toma como
807
- un archivo, y si esa imagen es **ancha** —`width >= height * 1.5`— la dibuja a
808
- lo ancho en vez de encajarla en el cuadrado de 16 px de un ícono. El archivo
809
- además tiene que estar en un directorio escribible del usuario (va a
810
- `~/.cache/quartermaster`), y el nombre se alterna entre dos porque el shell
811
- cachea la textura por ruta: reescribiendo siempre la misma, el item se queda con
812
- el dibujo viejo y parece que la cuota no se mueve.
813
-
814
- **Click del medio: el panel** — el anillo de «lo primero que te frena», un
815
- medidor de verdad por barra, la curva pegada a la que frena y el ritmo en rojo
816
- cuando chocás antes del reinicio. Se cierra con un click afuera, con Escape, o
817
- con otro click del medio.
818
-
819
- Las cuentas que todavía no tienen número van juntas en una sola tarjeta al
820
- final. Antes cada una gastaba una tarjeta entera para decir la misma frase, y en
821
- una pantalla de 768 px el panel ya no entraba; juntas ahorran ~120 px y además
822
- se leen mejor, porque no son tres misterios distintos sino un hecho con varios
823
- nombres. Se agrupan por frase: dos cuentas pueden estar calladas por motivos
824
- distintos, y ahí la frase importa.
825
-
826
- Es el mismo contenido que el panel de la barra de macOS, pero **no es una copia
827
- del dibujo**: acá va con la paleta de estado de Adwaita en vez de la de Apple,
828
- con una tarjeta redondeada por cuenta —la «boxed list» con la que GNOME agrupa
829
- cosas— en vez de líneas de pelo, y con cuerpos de letra más grandes, porque
830
- Cantarell es más grande que la tipografía del sistema de Apple y con las medidas
831
- de allá los renglones quedaban apretados y el texto rozando el borde.
832
-
833
- El click izquierdo lo tiene tomado la extensión de AppIndicator: abre su propio
834
- menú y no hay forma de enterarse de que pasó (su `AboutToShow` no llega hasta el
835
- proceso). Se probó también la bandeja legacy XEmbed como salida —ahí el ícono es
836
- una ventana nuestra— pero la bandeja lo fuerza a 16×16, que se lleva puestos los
837
- medidores. Así que con AppIndicator ese menú quedó en **dos renglones**
838
- —«Panel de cuota» y «Salir»— y ver el panel cuesta dos clicks. Para que cueste
839
- uno está `make extension`, más abajo.
840
- Antes repetía cada perfil con cada barra en bloques `█░`, que es lo único que
841
- GNOME sabe dibujar ahí adentro: los items viajan por DBus y del otro lado la
842
- extensión hace `label.set_text(...)`, texto pelado y sin markup. Un muro de
843
- texto delante del dibujo bueno es peor que no tener menú.
844
-
845
- El panel se arma con **un item de menú por tarjeta**, no como una sola
846
- superficie. Un menú rueda item por item: con un único item más alto que la
847
- pantalla no hay nada que rodar y el menú **no abre**, sin un error en ningún
848
- lado. Venía midiendo 740 px contra 728 de área útil —entraba raspando— y en
849
- cuanto creció dejó de abrirse. `make gate-dibujo` ahora falla si una tarjeta
850
- sola pasa de 700 px.
851
-
852
- ### Y por qué el panel terminó adentro de la extensión
853
-
854
- Con la extensión puesta, **el panel lo dibuja ella**: qm lo deja en un PNG y la
855
- extensión lo muestra en su propio menú del shell. Eso no fue una preferencia
856
- estética, fue la tercera arquitectura y la primera que aguanta.
857
-
858
- Las dos anteriores fallaron por la misma razón, y las dos veces costó verlo
859
- porque el síntoma sólo aparece con alguien usando la máquina:
860
-
861
- 1. **Ventana con foco**: ninguna ventana sostiene el foco acá. Los cuatro tipos
862
- lo pierden solos entre 0,15 s y 4,6 s.
863
- 2. **Menú de GTK con agarre propio**: aislado aguanta minutos —medido: 50 s sin
864
- un solo `unmap`— pero con actividad real del escritorio se cierra a los
865
- segundos, y **tocarlo para rodarlo lo cierra**, porque en un menú de GTK
866
- soltar el botón sobre un item lo activa, y activar un item cierra el menú.
867
-
868
- Adentro de la extensión el panel es un actor del compositor: no hay agarre que
869
- romper, no hay XWayland, y rueda y se cierra como cualquier menú del shell,
870
- porque es uno.
871
-
872
- Sin la extensión sigue existiendo el menú de GTK como respaldo, con las tarjetas
873
- marcadas insensibles para que tocarlas no lo cierre.
874
-
875
- **El panel de respaldo es un `Gtk.Menu` propio** —popeado por este proceso, no por DBus— y
876
- no una ventana suelta. La razón se midió: en este escritorio ninguna ventana
877
- sostiene el foco. Se probaron los cuatro tipos (UTILITY, NORMAL, DIALOG,
878
- POPUP_MENU) y las cuatro lo pierden solas entre 0,15 s y 4,6 s después de abrir,
879
- sin que nadie toque nada, porque mutter se lo devuelve al lado Wayland. Cerrar
880
- al perder el foco cerraba el panel solo; agarrar el asiento a mano tampoco
881
- alcanzaba, porque un agarre de XWayland no ve los clicks que caen sobre una
882
- ventana Wayland. Un menú de GTK, en cambio, agarra el puntero como lo agarra
883
- cualquier menú del escritorio: el click afuera y el Escape salen gratis, y la
884
- caja redondeada, la sombra y el fondo los pone el tema.
885
-
886
- Dos detalles que cuestan una tarde si no están escritos:
887
-
888
- - **Hay que pasarle un evento de disparo** a `popup_at_rect()`. El panel lo abre
889
- un mensaje de DBus, así que no hay ningún evento de GDK a mano; sin uno, GTK
890
- avisa `no trigger event for menu popup` y el agarre que toma se rompe solo a
891
- los pocos segundos — el menú se cerraba sin que nadie tocara nada. Con un
892
- evento sintético se queda abierto indefinidamente (medido: 20 s sin
893
- moverse).
894
- - **El tiempo de ese evento va en `CURRENT_TIME`.** Pedirle la hora al servidor
895
- con `x11_get_server_time()` sobre la ventana raíz **cuelga el proceso**:
896
- escribe una propiedad y espera un `PropertyNotify` que la raíz nunca manda.
897
-
898
- Y una trampa de tema que dejó el panel ilegible una tarde: GNOME dice
899
- `color-scheme = prefer-dark`, pero **una app GTK3 no se entera sola** — su
900
- `gtk-application-prefer-dark-theme` sigue en `False` y el menú que hace de fondo
901
- se dibuja CLARO. El panel, pintado con los colores oscuros de GNOME, quedaba
902
- blanco sobre blanco. Ahora se hacen las dos cosas: se le pasa la preferencia a
903
- GTK, y los grises del dibujo se sacan del **color de texto del propio menú** —
904
- que no puede mentir sobre qué fondo tiene debajo— en vez de un ajuste que puede
905
- no corresponderse con él.
906
-
907
- Sigue haciendo falta X11 para una sola cosa: `popup_at_rect()` contra la ventana
908
- raíz, que es lo que pega el panel arriba a la derecha. Por eso el proceso arranca
909
- con `GDK_BACKEND=x11`; al item de la barra no le cambia nada, es DBus puro.
910
- `QM_SIN_X11=1` lo fuerza a Wayland, donde el panel abre igual pero lo ubica el
911
- compositor.
912
-
913
- `bin/qm-indicator --captura panel.png` dibuja el panel a un archivo sin abrir
914
- ventana, y `--captura-item item.png` el item de la barra; `--claro` / `--oscuro`
915
- fuerzan el tema. Son las mismas funciones de dibujo que usan el panel y la
916
- barra, así que los PNG no son una segunda implementación que se parece.
917
-
918
- Cuatro cosas lo hacen algo más que un reloj:
919
-
920
- - **Pregunta él.** `qm --breve` lee del disco y no habla con nadie, que es lo
921
- que lo hace instantáneo — pero entonces el número es tan fresco como la última
922
- vez que *alguien* preguntó, y Claude Code refresca su propio cache cuando
923
- quiere: medido acá, **1 día y 11 horas** sin tocarlo, con la semanal 14 puntos
924
- abajo de la realidad (75 % en pantalla, 89 % de verdad). Así que el indicador
925
- corre `qm --calentar` él mismo, como ya hacían la barra de macOS y la bandeja
926
- de Windows, y deja el número en el cache para que las lecturas sigan siendo de
927
- disco. La cadencia es la misma de macOS —300 s de base, 240 arriba del 50 %,
928
- 120 arriba del 75 %, 60 arriba del 90 %, con piso de 60 s— y sólo se refrescan
929
- las cuentas que se mueven: pedirle el número a una que va al 9 % es gastar un
930
- pedido para confirmar que no pasó nada.
931
-
932
- Con una corrección sobre la política de macOS: **una barra en 100 no cuenta
933
- como alta**. Ya no puede subir, así que hasta el reinicio no hay nada nuevo
934
- que leer —y el instante del reinicio se sabe sin preguntar—. Contándola, el
935
- sondeo se iba al piso de 60 s para mirar un número congelado: un pedido por
936
- minuto, a un endpoint que no es nuestro, para confirmar que seguís frenado.
937
- - **Dice de cuándo es cada número.** Cada tarjeta cierra con `lecturas: cada
938
- ~4m · última hace 42s`, y el panel con `próxima lectura en 3m 16s`, que baja a
939
- la vista mientras lo mirás. El «cada cuánto» no es la cadencia que el programa
940
- se propone sino la **medida**: el historial se indexa por `medidoEn` —el
941
- instante que informa el servidor, no el momento en que qm miró el disco— así
942
- que cada muestra es una lectura real y los huecos entre muestras son los
943
- intervalos entre lectura y lectura. Va la mediana y no el promedio, porque una
944
- sola pausa larga (la máquina suspendida) no dice nada del ritmo normal.
945
- - **Se entera solo.** Vigila el `.claude.json` de cada perfil con
946
- `Gio.FileMonitor`: cuando Claude Code refresca la cuota, el número cambia en
947
- el acto. Medido: de 82 % a 96 % en menos de 5 s sin reiniciar nada. El sondeo
948
- cada 5 min queda de red de seguridad.
949
- - **Avisa sin que lo mires.** Notifica al cruzar 80 % y 95 % —por **todas** las
950
- barras, no sólo por la que frena: la semanal puede estar tranquila mientras la
951
- de sesión te para, y al revés— y cuando la proyección pasa a decir que tocás
952
- el techo *antes* del reinicio, que es el momento útil y no cuando ya chocaste.
953
- - **Y avisa cuando te liberás**, que es el único aviso que sirve para hacer algo
954
- distinto ahora mismo: la ventana se reinició habiendo estado contra el techo.
955
- Un porcentaje solo no alcanza para verlo —3 % puede ser «recién empezás» o
956
- «acabás de salir de estar frenado»— así que se guarda el minuto de reinicio
957
- junto al número en `previos.json`: cuando el minuto cambia, la ventana es
958
- otra. Justo el momento en que dejaste de mirar la barra, porque no había nada
959
- que mirar.
960
- - **No repite.** Cada aviso de umbral se recuerda por perfil, barra y minuto de
961
- reinicio, así que una ventana avisa una vez y vuelve a avisar recién en la
962
- siguiente. El de liberación no lleva memoria a propósito: tiene que sonar
963
- cada vez que pasa.
964
-
965
- El icono acompaña: normal, `dialog-warning` desde 80 %, `dialog-error` al 95 %
966
- o cuando la proyección dice que chocás. `bin/qm-indicator` no sabe qué es una
967
- credencial: le pide el JSON a `qm` y dibuja.
968
-
969
- Necesita el soporte de AppIndicator en GNOME —la extensión
970
- `appindicatorsupport@rgcjonas.gmail.com`—, que es lo que convierte un
971
- `StatusNotifierItem` en un item de la barra. Verificado en GNOME Shell 48.7
972
- sobre Wayland. Para sacarlo: «Salir» en su propio menú, y
973
- `rm ~/.config/autostart/quartermaster.desktop`.
974
-
975
- Un detalle del click del medio que cuesta una tarde si no está escrito: el
976
- objetivo de `set_secondary_activate_target()` tiene que ser un item que **viva
977
- adentro del menú** y esté marcado visible. Con un widget suelto —o con uno sin
978
- `show()`— libayatana descarta el evento y no dice nada. Y como el menú se
979
- reconstruye en cada refresco, hay que volver a apuntarlo cada vez o el click
980
- deja de hacer efecto en silencio.
981
-
982
- ### Un click, con extensión propia
983
-
984
- ```bash
985
- make extension # instala y habilita quartermaster@legios
986
- make extension-quitar # y lo deshace
987
187
  ```
988
-
989
- `extension/quartermaster@legios` es una extensión de GNOME Shell de unas cien
990
- líneas que **no sabe qué es una cuota**. Hace dos cosas: muestra el PNG que
991
- dibuja `qm-indicator` y, cuando le hacen click, deja un pedido en un archivo
992
- para que ese proceso abra su panel. Todo el dibujo y todos los números siguen
993
- viviendo del lado de Python. A cambio, el item es nuestro y **el primer click
994
- abre el panel** — y el segundo lo cierra.
995
-
996
- Mientras la extensión está habilitada escribe `~/.cache/quartermaster/extension-viva`,
997
- y al verlo `qm-indicator` pone su propio item de AppIndicator en `PASSIVE` para
998
- que no queden dos diciendo lo mismo. No lo destruye: la extensión se puede
999
- apagar en cualquier momento y el item vuelve solo, sin reiniciar nada.
1000
-
1001
- La conversación va por archivos y no por DBus a propósito: son dos procesos que
1002
- ya comparten un directorio de cache, un `Gio.FileMonitor` de cada lado alcanza,
1003
- y no hay que registrar un nombre de bus ni una interfaz para decir «abrí el
1004
- panel». Con una trampa que hay que saber: **una escritura son varios eventos de
1005
- inotify** —se midieron tres, `changed`, `changed`, `changes-done-hint`— así que
1006
- el pedido se junta con un temporizador antes de atenderlo. Sin eso, un click
1007
- abría el panel y los dos eventos siguientes lo cerraban en el mismo instante, y
1008
- desde afuera parecía que el item no hacía nada.
1009
-
1010
- **GNOME Shell no carga una extensión recién instalada en Wayland**: hay que
1011
- cerrar sesión y volver a entrar una vez. `ReloadExtension` está deprecada y
1012
- devuelve error, y `EnableExtension` sobre una que el shell todavía no vio
1013
- devuelve `false`.
1014
-
1015
- ### Las cuatro escaleras de duración
1016
-
1017
- Hay una implementación de la misma escalera por lenguaje —TypeScript, Python,
1018
- Swift, PowerShell— y la regla de que todas den lo mismo estaba escrita en los
1019
- comentarios pero no comprobada. El resultado: **convivieron dos convenciones**,
1020
- tres GUIs de un lado y el CLI del otro, en tres puntos a la vez.
1021
-
1022
- | segundos | el CLI decía | las tres GUIs decían |
1023
- |---|---|---|
1024
- | −1 | `vencido` | `ya` |
1025
- | 3600 | `1h00m` | `1h` |
1026
- | 86400 | `1d` | `1d0h` |
1027
-
1028
- Sobrevivió porque nadie había comparado **una GUI contra el CLI**: la
1029
- comparación que lo encontró fue entre dos GUIs. Ganó el CLI —`src/render/barras.ts`
1030
- es donde el propio repo dice que pasa todo lo que se imprime, y es la única con
1031
- tests— y las otras tres se alinearon.
1032
-
1033
- `make gate-duraciones` congela el canon en `test/fixtures/duraciones.json` y
1034
- **corre las cuatro** contra esa tabla. Las que no tienen intérprete en la máquina
1035
- se saltean diciéndolo; en CI cada job exige los suyos con `QM_GATE_EXIGE`, así
1036
- que Ubuntu comprueba PowerShell y un runner de macOS comprueba Swift. Saltear en
1037
- silencio convertiría el gate en un adorno.
1038
-
1039
- ### El gate que faltaba
1040
-
1041
- `npm test` cubre el núcleo en TypeScript, y hasta acá eso era todo lo que
1042
- miraba el CI. Afuera quedaban las 1.400 líneas de Python que dibujan el panel y
1043
- el item, y la extensión de GNOME Shell. No es hipotético: sacando código muerto
1044
- de `bin/qm-indicator`, un corte demasiado ancho se llevó puesto el bloque entero
1045
- del panel —unas 700 líneas— y el archivo siguió compilando, así que el CI siguió
1046
- en verde. Se descubrió a mano.
1047
-
1048
- ```bash
1049
- make gate-dibujo
188
+ GET https://api.anthropic.com/api/oauth/usage
1050
189
  ```
1051
190
 
1052
- Mira tres cosas, en orden de qué tan barato es equivocarse: que el indicador
1053
- **compile**, que la extensión **parsee** —un error ahí lo ve GNOME al iniciar
1054
- sesión, que es el peor momento para enterarse— y que **dibuje**, con
1055
- `test/fixtures/panel.json` de entrada, saliendo con las medidas de siempre y con
1056
- píxeles adentro. Lo tercero es lo que no se puede reemplazar por un import: un
1057
- error de Cairo no rompe la importación del módulo.
191
+ Same host Claude Code already talks to, same credential it already stored, with
192
+ a 60-second floor. No account, no cloud, no telemetry, and zero runtime
193
+ dependencies. **It never refreshes a token** — a locked non-goal, with a test.
1058
194
 
1059
- Y el chequeo de píxeles no es decorativo: un PNG del tamaño correcto y
1060
- enteramente transparente pasa cualquier verificación de medidas sin haber
1061
- dibujado nada. Probado en rojo contra cuatro sabotajes en
1062
- [`numeros/gate-rojo.md`](numeros/gate-rojo.md).
195
+ The full table, and the straight paragraph about that endpoint being
196
+ undocumented, are in [`SECURITY.md`](SECURITY.md).
1063
197
 
1064
- ## En la bandeja de Windows
198
+ ## Package managers
1065
199
 
1066
- ```bash
1067
- make tray # lo arranca ahora (desde WSL)
1068
- make tray-autostart # y que arranque solo al iniciar sesión de Windows
1069
- ```
200
+ One tag publishes everywhere. `git push origin v0.1.7` runs the release
201
+ workflow, which builds every artifact and pushes it to each channel that has its
202
+ secret configured — and says in the log which ones it skipped and why.
1070
203
 
1071
- El panel es el mismo dibujo que `VistaResumen` y `VistaCuenta` en
1072
- `bin/qm-barra.swift`: cabecera con el anillo de **lo primero que te frena**, y
1073
- después una sección por cuenta con el glifo del producto, cuenta y plan,
1074
- medidores redondeados con la paleta de estado, porcentaje a la derecha, un pie
1075
- con el reinicio y la edad del cache, la curva de las últimas muestras pegada a
1076
- la barra que frena, y el ritmo. En WinForms no se puede pintar un item de menú
1077
- sin subclasear, así que cada sección se dibuja a un `Bitmap` y el `Bitmap` va
1078
- adentro de un `PictureBox` hosteado en el menú. El efecto es el mismo; el
1079
- camino, no.
1080
-
1081
- **El ícono nunca es un número.** La primera versión dibujaba el porcentaje
1082
- adentro del ícono, como los medidores de batería. Se renderizó a 16×16 —el
1083
- tamaño real de la bandeja a 96 dpi— y se miró: **un dígito se lee, dos son una
1084
- mancha.** Así que el número se fue al tooltip y al menú, y el ícono hace de
1085
- medidor: la forma dice cuánto va, el color dice cuánto importa, y las dos cosas
1086
- sobreviven a 16 píxeles.
1087
-
1088
- **Y hay un ícono por cuenta, no uno solo.** La barra de menú de macOS no muestra
1089
- un medidor: muestra una **tira** —glifo, medidor y número, una vez por cuenta— y
1090
- eso es lo que uno viene a mirar. En un item de bandeja no cabe: no tiene
1091
- etiqueta de texto y es un cuadrado de 16×16. Así que la tira se reparte en
1092
- varios items, uno por cuenta, con el glifo de su producto y el medidor de su
1093
- semanal, y el número de la sesión en el tooltip. Comparten el mismo menú, así
1094
- que hacer click en cualquiera abre el panel completo. El anillo quedó para el
1095
- único caso que no tiene cuenta que dibujar: cuando `qm` no contesta.
1096
-
1097
- **Dos cosas que aparecieron al mirarlo y no al leerlo.**
1098
-
1099
- - **El color de cuenta necesitaba las dos tablas.** `colorCuenta()` en Swift
1100
- devuelve un `NSColor` dinámico con una tabla clara y una oscura; el `.ps1`
1101
- había copiado sólo la clara. Con el ícono a 16×16 sobre la barra de tareas
1102
- negra de fábrica, los chevrones de codex —`#4a3aa7`— casi no estaban. Y hace
1103
- falta elegir **dos veces**, porque el menú y la barra de tareas son
1104
- superficies distintas con temas distintos: medido acá, `AppsUseLightTheme=0` y
1105
- aun así `SystemColors.Menu` da `240,240,240` —los colores clásicos de Win32 no
1106
- siguen al tema oscuro— mientras la barra de tareas sí es oscura.
1107
- - **Cada perfil tiene un lugar fijo, tenga número o no.** macOS puede dejar
1108
- afuera a una cuenta muda porque su tira es un solo dibujo que se rehace
1109
- entero. Acá cada lugar es un item de bandeja, y Windows lo identifica por el
1110
- hash de (ejecutable + UID) donde el UID lo reparte WinForms **por orden de
1111
- creación** — visto en `HKCU\Control Panel\NotifyIconSettings`. Sacar y volver
1112
- a poner un item corre los UID de los que vienen después, y con eso se le muda
1113
- de cuenta la decisión de «este ícono va fijo en la barra» que el usuario tomó
1114
- arrastrándolo.
1115
-
1116
- **El costo de la tira, dicho de frente:** Windows decide por ícono si va a la
1117
- barra o al desplegable de escondidos, y a los nuevos los manda al desplegable.
1118
- Se arrastra una vez y, por lo del UID, la elección persiste. **Y ahora avisa
1119
- cuando pasa**, que es lo que faltaba: un ícono que Windows escondió y un ícono
1120
- que no arrancó se ven exactamente igual —nada— y eso es la misma clase de
1121
- silencio que motivó el repo. No se supone: cada item vive en
1122
- `HKCU\Control Panel\NotifyIconSettings` con un `IsPromoted` que vale 1 si está
1123
- en la barra, y el UID que lo identifica sale por reflexión del campo privado
1124
- `id` del `NotifyIcon`. Si ninguno de los nuestros está promovido, va un globo.
1125
- Es el equivalente de `revisarSiSeVe()` en la barra de macOS, que cubre el mismo
1126
- problema por el otro lado (la barra llena y la muesca).
1127
-
1128
- **Un ícono general, y uno por cuenta, y cada uno abre SU panel.** La tira
1129
- empezó siendo un ícono por cuenta y nada más, y con cuatro cuentas eso deja
1130
- cuatro cuadraditos que abren los cuatro la misma pantalla: el ícono que
1131
- clickeaste no quería decir nada. Ahora hay un **ícono general** —la marca de
1132
- quartermaster, que ya es un manómetro: el arco se llena hasta el peor
1133
- porcentaje de la máquina y se pinta con el color de ese estado, y la cola en
1134
- diagonal es lo que lo distingue de un anillo cualquiera— cuyo panel es el de
1135
- siempre, con todas las cuentas y la cabecera de lo primero que te frena. Y el
1136
- de cada cuenta abre **esa cuenta sola**.
1137
-
1138
- **Y se eligen desde el ícono, no desde un flag.** Cuatro cuentas son cuatro
1139
- cuadraditos, y en una barra de tareas llena eso es una inundación. Cualquiera de
1140
- los paneles —el general y el de cada cuenta— tiene **«Íconos en la bandeja»**:
1141
- un tilde por cuenta más el general. Destildar uno lo saca en el acto, sin
1142
- reiniciar nada, y la elección se guarda en
1143
- `%LOCALAPPDATA%\quartermaster\iconos.json`.
1144
-
1145
- **Y el panel no se cierra al tildar.** WinForms cierra el menú al clickear
1146
- cualquier item, y acá eso es peor que en ningún otro lado: elegir íconos es
1147
- justamente la tarea en la que uno toca varios seguidos, y cerrar el panel
1148
- después de cada tilde obliga a reabrirlo una vez por cuenta. Va el mismo
1149
- mecanismo que «Actualizar ahora» —cancelar el cierre, y sólo para eso— con una
1150
- diferencia que hay que conocer: los eventos de un `ToolStripDropDown` **no suben**
1151
- al `ContextMenuStrip`, así que el padre nunca se entera de qué nieto se clickeó.
1152
- La bandera la prende `AlternarIcono`, que es quien sabe; el que cancela sigue
1153
- siendo el handler del padre. Y `AlClickear` ahora sólo PRENDE la bandera y nunca
1154
- la apaga: con un `=` la apagaba justo antes de que el otro handler la mirara.
1155
-
1156
- Va en TODOS los paneles a propósito: el ícono que sobra suele ser justo el que
1157
- estás mirando, y si el ajuste viviera sólo en el general, esconder el general te
1158
- dejaría sin forma de volver atrás. Por lo mismo, **el último no se puede
1159
- esconder**: una bandeja vacía no es una preferencia, es la herramienta apagada
1160
- sin decirlo, y desde una bandeja vacía no hay menú desde donde volver a
1161
- prenderla. Y una cuenta escondida sigue LISTADA en el submenú, destildada, que es
1162
- lo que permite traerla de vuelta.
1163
-
1164
- Lo que se guarda es la lista de los ESCONDIDOS y no la de los visibles, y la
1165
- diferencia importa: guardando los visibles, un perfil que aparece después nacería
1166
- invisible, y una cuenta que no se ve es exactamente igual a una cuenta que va
1167
- bien. El silencio otra vez, y encima permanente.
1168
-
1169
- `-Iconos` sigue existiendo para arrancar con una combinación, separando por coma:
204
+ | | Install | What it gets | Published by |
205
+ |---|---|---|---|
206
+ | **npm** | `npm install -g @legios/quartermaster` | the tarball with `dist/`, **with provenance** | the tag, automatically |
207
+ | **Homebrew** | `brew install legiosai/tap/quartermaster` | the formula, from the tag's tarball | the tag, automatically |
208
+ | **apt** | `sudo apt install quartermaster` | a **signed** repo, so `apt upgrade` brings new versions by itself | the tag, automatically |
209
+ | **`.deb`** | `sudo apt install ./quartermaster_*.deb` | the same package, standalone | attached to the release |
210
+ | **Windows installer** | `quartermaster-<v>-setup.exe` | per-user, no UAC: `qm` on `PATH`, tray in the Start menu | attached to the release |
211
+ | **scoop** | `scoop install quartermaster` | the portable zip, no installer | the tag, automatically |
212
+ | **winget** | `winget install Legios.Quartermaster` | the installer, declaring Node as a dependency | the tag opens the PR |
213
+ | **AUR** | `yay -S quartermaster` | `PKGBUILD`, with a real `nodejs>=22.6` | the tag, automatically |
214
+ | **Nix** | `nix run github:legiosai/quartermaster` | the flake, with its own Node in the closure | nothing to publish |
215
+ | **GNOME Extensions** | from the Extensions app | the Shell extension | **by hand** — no upload API |
216
+ | **waybar** | copy `paquetes/waybar/` | a module for Hyprland, Sway, river | copied by hand |
1170
217
 
1171
- ```
1172
- (vacío) lo que el usuario haya elegido; la primera vez, todos
1173
- general sólo el general, con todas las cuentas adentro
1174
- main,codex sólo esas dos cuentas, sin general
1175
- general,codex el general y codex
1176
- ```
218
+ The one exception is extensions.gnome.org, which has no API for uploading. The
219
+ release reminds you, with a link to the artifact.
1177
220
 
1178
- Siembra la elección **una vez** y después manda el menú: un flag que se impusiera
1179
- en cada arranque sería un ajuste que se deshace solo, que es peor que no tenerlo.
1180
-
1181
- El filtro se aplica a la TIRA y no a los paneles: el general sigue mostrando
1182
- todas las cuentas aunque no tengan ícono propio. Y si `-Iconos` no coincide con
1183
- nada queda el general igual, diciéndolo — una bandeja vacía sería otra vez el
1184
- silencio, y encima uno que se causó el usuario con un typo.
1185
-
1186
- **`-Iconos` es la única forma de sacar uno solo, y conviene decir por qué.**
1187
- Arrastrar un ícono al desplegable de escondidos, que es lo que uno haría, no
1188
- funciona de a uno: se llevan todos. La causa se midió y no se supone. Windows
1189
- identifica un ícono de bandeja por `(ruta del ejecutable, UID)` —o por un
1190
- `guidItem` propio, si la aplicación se lo da— y los cuatro nuestros salen del
1191
- mismo `powershell.exe`. Con la bandeja andando y sus cuatro íconos visibles
1192
- (UID 1, 2, 3 y 4, comprobado por reflexión sobre el campo privado `id` del
1193
- `NotifyIcon`), `HKCU\Control Panel\NotifyIconSettings` tenía **dos** entradas
1194
- para esos cuatro íconos: los que no tienen entrada propia no tienen ajuste
1195
- propio, y la decisión de esconderlos cae sobre la aplicación entera.
1196
-
1197
- Lo que lo arreglaría de verdad es darle a cada ícono un `guidItem` estable, que
1198
- es justamente para esto. **`NotifyIcon` de WinForms no lo expone** —se listaron
1199
- sus campos: hay `icon`, `text`, `id`, `contextMenuStrip`, y ningún `guid`— así
1200
- que habría que dejar de usarlo y hablar con `Shell_NotifyIcon` directamente, lo
1201
- que implica reescribir a mano la recepción de los clicks y los globos. No está
1202
- hecho: es la parte más probada de este archivo y reemplazarla a ciegas sería
1203
- cambiar un problema de acomodo por uno de funcionamiento.
1204
-
1205
- Verificado por UI Automation contra el fixture de cinco perfiles: la bandeja
1206
- queda con `quartermaster · 3 cuenta(s) · lo peor 100%` más `main`, `teams`,
1207
- `codex`, `bedrock` y `personal`, cada uno con su tooltip; y con
1208
- `-Iconos general,codex,teams` quedan exactamente tres.
1209
-
1210
- **Y tiene modo oscuro.** El panel era el único de los cuatro renderizadores que
1211
- salía siempre blanco, y la causa es la de arriba: `SystemColors.Menu` no sigue al
1212
- tema de las apps. macOS lo saca de un `NSColor` dinámico y GNOME del tema de
1213
- GTK, así que Windows era el único que tenía que preguntarle al registro, y el
1214
- fondo se había quedado atrás mientras el color de cuenta ya lo hacía.
1215
-
1216
- Pintar los dibujos en oscuro no alcanzaba: el marco del menú, el resaltado del
1217
- item bajo el mouse y los separadores los pinta WinForms con su propia tabla, que
1218
- es clara, y un panel oscuro adentro de un menú blanco se ve peor que el problema
1219
- original. Va una `ProfessionalColorTable` heredada, y el tema entero vive en
1220
- `AplicarTema`, que se relee en cada tick: cambiar Windows de claro a oscuro se
1221
- nota en la vuelta siguiente sin reiniciar la bandeja.
1222
-
1223
- **Y calienta el endpoint, como la barra de macOS.** Esto no es un detalle de
1224
- adorno: fue el bug. La primera versión sólo leía el disco, y en la máquina donde
1225
- se escribió esto el perfil por defecto **no tiene `cachedUsageUtilization` en su
1226
- `.claude.json`** — ni viejo ni nuevo: no está. Mientras tanto el endpoint
1227
- contestaba `weekly_scoped (Fable)` al **100 %**, `critical`. Una bandeja que sólo
1228
- mira el disco mostraba, con toda honestidad, «todavía no dejó cuota para este
1229
- perfil» al lado de un ícono verde, en una cuenta que estaba frenada. Es
1230
- exactamente el silencio del que habla la primera sección de este README, con
1231
- otra causa.
1232
-
1233
- Así que `qm --calentar` se dispara con la misma cadencia adaptativa que
1234
- `cadencia()` en Swift —300 s de base, 240 desde 50 %, 120 desde 75 %, 60 desde
1235
- 90 %, y 60 si la proyección dice que faltan menos de 30 minutos para el techo— y
1236
- sólo para las cuentas que se mueven (≥ 40 %), porque refrescar una que va al 9 %
1237
- es gastar un pedido para confirmar que no pasó nada. Con `-SinCalentar` no se le
1238
- pide nada a la red y se vuelve al comportamiento de sólo-disco.
1239
-
1240
- Hay una diferencia con macOS que es de Windows y no se puede evitar: el timer
1241
- corre en el hilo de la interfaz, así que en el tick automático el calentado **se
1242
- dispara y se suelta**, y el número que trae lo levanta el tick siguiente (30 s).
1243
- Esperarlo ahí congelaría el menú, que es peor que un número medio minuto tarde.
1244
-
1245
- **«Actualizar ahora» sí espera, y no cierra el panel.** Empezó haciendo el mismo
1246
- `Calentar; Refrescar` del tick, y ahí estaba el bug: el calentado tarda
1247
- **~930 ms** y el `Refrescar` de atrás tarda **~250**, así que leía el cache de
1248
- *antes* del calentado que él mismo acababa de disparar. El panel se cerraba
1249
- —Windows cierra un menú al clickear un item— y el número era el que ya estabas
1250
- mirando; había que esperar el tick. El botón decía «ahora» y no hacía nada ahora.
1251
-
1252
- Ahora espera con un timer y no con el hilo —mira si el proceso del calentado
1253
- terminó cada 250 ms, con techo de 15 s— y **el panel se queda abierto**: el
1254
- cierre se cancela, pero sólo para este item, porque «Abrir tablero» y «Salir»
1255
- tienen que seguir cerrándolo igual que clickear afuera o apretar Escape. Hacen
1256
- falta dos handlers y no uno: `ItemClicked` corre antes que `Closing` y es el
1257
- único que sabe *qué* se clickeó; `Closing` es el único que puede cancelar.
1258
- Mientras el número llega, el item dice **«Actualizando…»** y no acepta otro
1259
- click: dos segundos sin ninguna señal se leen como que no pasó nada, que es de
1260
- donde vino todo esto.
1261
-
1262
- Rehacer el menú estando **visible** necesita `SuspendLayout`/`ResumeLayout` —si
1263
- no, cada `Add()` relayoutea el menú abierto y se lo ve saltar de tamaño una vez
1264
- por sección— y un `PerformLayout` al final, porque sin él se queda con el alto
1265
- viejo y recorta la última. De paso arregla un borde que ya existía: si dejabas
1266
- el panel abierto más de 30 s, el tick también lo rehacía sin reacomodarlo.
1267
-
1268
- Lo demás es igual a las otras dos: avisa al cruzar 80 % y 95 % y cuando la
1269
- proyección dice que tocás el techo antes del reinicio, y no repite —la clave del
1270
- aviso incluye el minuto de reinicio, así que una ventana avisa una vez y vuelve
1271
- a avisar recién en la siguiente—. La memoria de avisos vive en
1272
- `%LOCALAPPDATA%\quartermaster\avisados.json`.
1273
-
1274
- **Y ahora avisa también cuando te liberás**, que era el único aviso que la
1275
- bandeja no tenía: macOS lo hacía con `revisarLiberadas()` y GNOME con
1276
- `revisar_liberada()`, y Windows no. Es el aviso que sirve para hacer algo
1277
- distinto ahora mismo —todos los demás avisan cuando SUBÍS— y es justo el momento
1278
- en que dejaste de mirar la barra, porque no había nada que mirar. Necesita
1279
- memoria de la vuelta anterior, porque un 3 % puede ser «recién empezás» o
1280
- «acabás de salir de estar contra el techo» y la diferencia es todo: se guarda el
1281
- minuto de reinicio junto al porcentaje en
1282
- `%LOCALAPPDATA%\quartermaster\previos.json`, y cuando el minuto cambia habiendo
1283
- estado arriba del 80 %, avisa. No pasa por `avisados.json` a propósito: la
1284
- condición ya es un flanco, y anotarla ahí la silenciaría para el reinicio
1285
- siguiente, que es el que sí hay que avisar.
1286
-
1287
- **Y avisa de TODAS las barras, no sólo de la que frena.** Esto era un bug que
1288
- sólo se ve comparando los tres renderizadores: la bandeja le pasaba a
1289
- `RevisarAvisos` una sola ventana —`frena`— y `peor()` en `src/core/tipos.ts`
1290
- devuelve la más alta, así que con la sesión al 96 % y una semanal al 85 % la
1291
- bandeja avisaba de la sesión y de la semanal no decía nada. macOS y GNOME
1292
- siempre recorrieron la lista. Es justo lo contrario del principio de SOUL.md que
1293
- dice leer todas las barras.
1294
-
1295
- **Y un candado, que faltaba.** Arrancarla dos veces —el arranque automático más
1296
- un `make tray` a mano, que es lo más fácil del mundo— dejaba DOS tiras enteras:
1297
- un ícono por cuenta repetido, los globos por duplicado, y los dos procesos
1298
- pisándose `avisados.json` y `previos.json`. En GNOME eso lo resuelve un nombre
1299
- en el bus de sesión (`soy_el_unico()`); acá es un mutex nombrado `Global\`, que
1300
- tiene la misma propiedad que lo hace servir: si el proceso muere de cualquier
1301
- forma, Windows lo suelta solo. Un archivo con el PID hay que limpiarlo, y nunca
1302
- se limpia en el caso que importa. La segunda instancia dice
1303
- `ya hay una bandeja de quartermaster andando en esta máquina` y se va.
1304
-
1305
- **Un mapa de bits, un dueño.** Esto costó dos bugs del mismo tipo, los dos con
1306
- el mismo síntoma —«Parameter is not valid», que es lo que tira GDI+ al dibujar
1307
- un `Bitmap` ya liberado— y ninguno de los dos se ve leyendo la función donde
1308
- estaba el error. El primero: al pasar a varios menús, los mapas de bits del tick
1309
- anterior se liberaban al empezar `Refrescar`, cuando los `PictureBox` de los
1310
- menús todavía los tenían. El segundo, más fino: `ArmarMenu` dibujaba el pie él
1311
- mismo, o sea **una vez por menú**, y cada llamada liberaba el que el menú
1312
- anterior acababa de recibir — con cuatro íconos quedaban tres pies apuntando a
1313
- una imagen muerta, y el renglón salía en blanco. Medido con una sonda que
1314
- pregunta por cada imagen de cada menú: **3 muertas por vuelta contra 0** con el
1315
- arreglo. La regla que quedó es una sola: el que crea un mapa de bits es el que
1316
- lo libera, y lo libera al final, cuando ningún menú lo mira. `gate-bandeja.ps1`
1317
- comprueba que `ArmarMenu` no dibuje el pie.
1318
-
1319
- **Y no muere con un cartel.** Por defecto WinForms le muestra al usuario
1320
- «Unhandled exception has occurred in your application» y, si aprieta Quit o si
1321
- el cartel aparece con la pantalla bloqueada, la bandeja desaparece — y un ícono
1322
- que no está se lee exactamente igual que una cuenta que va bien. Ahora una
1323
- excepción en el hilo de la interfaz se atrapa, se sigue andando con lo anterior,
1324
- y se DICE: una línea a stderr siempre y un globo la primera vez. Además todo
1325
- `Bitmap` se crea con `Lienzo`, que acota las dimensiones a 1 px de piso: un
1326
- `Bitmap` con un lado en 0 tira literalmente «Parameter is not valid», que era el
1327
- cartel, y un renglón vacío es mejor que una aplicación cerrada. Que una medida dé
1328
- 0 sigue siendo un bug, y lo agarra el gate, que mide los píxeles que salen.
1329
-
1330
- **Y se reinicia sola cuando el archivo cambia debajo.** `git pull` reemplaza el
1331
- `.ps1` y se va; el proceso que ya está corriendo tiene el guión leído y sigue
1332
- con el código viejo hasta que alguien lo reinicie a mano, que no lo hace nadie,
1333
- porque la bandeja es justamente lo que se deja andando y se olvida. Es
1334
- `vigilar_version()` de GNOME, con dos diferencias: va por **sondeo** y no por
1335
- `FileSystemWatcher` —el guión puede estar del otro lado del 9P de WSL, donde
1336
- `FileSystemWatcher` no es confiable, y el tick de 30 s ya está pago— y **parsea
1337
- la versión nueva antes de saltar**, porque si está rota reiniciar te deja sin
1338
- bandeja y quedarse con la vieja te deja con una que anda. De yapa, eso resuelve
1339
- gratis la espera a que el gestor de paquetes termine de escribir: un archivo a
1340
- medio escribir no parsea.
1341
-
1342
- Tiene un costo, y conviene saberlo antes de que muerda: **es hostil para quien
1343
- está editando el archivo.** Cada guardado relanza la bandeja, y la relanza con el
1344
- trabajo a medio hacer — el parseo previo atrapa un archivo roto, no atrapa uno
1345
- que parsea y todavía no está terminado, que es la forma normal de un archivo
1346
- mientras se lo escribe. Para eso está `-SinAutoReinicio`.
1347
-
1348
- **Y el panel dice de cuándo es el número y cuándo deja de serlo.** Cada cuenta
1349
- lleva `lecturas: cada ~5m · última hace 2m` —la cadencia MEDIDA, mediana de los
1350
- huecos del historial, no la que el programa se propone— y el panel entero
1351
- termina en `próxima lectura en 4m 12s`, que **baja sola** mientras está abierto.
1352
- Las dos cosas venían del panel de GNOME. La edad del cache se mudó ahí desde el
1353
- pie de la barra que frena: sola decía la mitad, porque «hace 40 m» es
1354
- tranquilizador si se lee cada hora y alarmante si se lee cada cinco minutos.
1355
- El renglón que baja se redibuja solo a él, una vez por segundo y sólo con el
1356
- panel abierto: el resto no cambió.
1357
-
1358
- Vale la misma regla que las otras dos: **sólo dibuja**. `bin/qm-tray.ps1` le
1359
- pide el JSON a `qm` por stdout y no sabe qué es una credencial ni un endpoint.
1360
- La regla de cuál barra manda no se reimplementa acá: llega resuelta en
1361
- `mostrar`, `frena`, `sesion` y `semanal`.
1362
-
1363
- No necesita instalar nada: PowerShell y WinForms ya están en cualquier Windows.
1364
- `bin/qm-tray` es el lanzador del lado de WSL —traduce la ruta con `wslpath` y
1365
- lanza `powershell.exe`—; el proceso vive del lado de Windows, así que si cerrás
1366
- la terminal el tray sigue. Para sacarlo: «Salir» en su propio menú, o
1367
- `make tray-quitar`, que además borra el atajo del arranque automático.
1368
-
1369
- **Y por fin tiene un gate.** Era la superficie que más tiempo estuvo sin que la
1370
- mirara nadie: de las ~1500 líneas de `bin/qm-tray.ps1`, el CI comprobaba **una
1371
- función** —la escalera de duración, que `gate-duraciones.py` extrae y corre
1372
- suelta— y todo lo demás pasaba en verde con un error de sintaxis adentro. Es
1373
- exactamente lo que le pasó a `bin/qm-indicator` antes de que existiera
1374
- `gate-dibujo.sh`, y está contado ahí mismo: se borró medio archivo y el CI no se
1375
- enteró, porque el CI ni lo abría.
1376
-
1377
- Hicieron falta dos cosas. Primero, un **modo captura** (`-Desde` un JSON fijo,
1378
- `-Captura` un PNG, `-Panel` cuál, `-Oscuro`/`-Claro` qué tema) que dibuja sin
1379
- bandeja ni bucle de mensajes, usando las mismas funciones que el menú — si
1380
- dibujara por su cuenta, el gate estaría comprobando un dibujo que nadie ve. Es
1381
- el equivalente de `--desde`/`--captura` en el indicador de GNOME. Y segundo,
1382
- `scripts/gate-bandeja.ps1` (`make gate-bandeja`, y un job de `windows-latest` en
1383
- CI), que comprueba cuatro cosas y **las cuatro se probaron en rojo**:
1384
-
1385
- 1. que **parsee** — también desde Ubuntu, en `gate-dibujo.sh`, porque un error
1386
- de sintaxis se descubre recién cuando alguien inicia sesión;
1387
- 2. que **dibuje**: 340 px de ancho y píxeles adentro, en los dos temas;
1388
- 3. que **nada se salga de la tarjeta**;
1389
- 4. que el panel de una cuenta **no sea** el de todas.
1390
-
1391
- El 3 encontró un bug de verdad la primera vez que corrió. GDI+ no recorta nada
1392
- cuando se dibuja en un punto —igual que Cairo, y por eso el panel de GNOME tiene
1393
- su `margen_limpio`— así que con el fixture de nombres largos el nombre del perfil
1394
- se dibujaba **por encima del borde** del panel y el nombre de la ventana se
1395
- metía **por debajo del porcentaje**, dejando los dos ilegibles. Ahora todo lo que
1396
- puede ser largo se recorta con puntos suspensivos, y el porcentaje se dibuja
1397
- primero para que el nombre se recorte contra el hueco que queda. Eso no se ve
1398
- leyendo el código; se ve mirando una captura, que es para lo que existe el modo.
1399
-
1400
- **Lo que está verificado y lo que no**, para que esta sección no mienta:
1401
-
1402
- - Verificado en Windows 11 con Windows PowerShell 5.1: arranca, dibuja el menú
1403
- contra los perfiles reales de esta máquina, sobrevive los ticks, sale por
1404
- `make tray-quitar`, y el atajo de arranque lanza un tray que anda.
1405
- - **Los seis íconos y sus tooltips se verificaron por UI Automation** contra el
1406
- fixture de cinco perfiles, y el filtro `-Iconos` también. Lo que **no** se
1407
- pudo probar acá es el click: un `mouse_event` sintético no llega al ícono en
1408
- este build de Windows 11 —se comprobó corriendo el mismo arnés contra la
1409
- versión commiteada, que falla igual— así que el wiring se verificó por el
1410
- otro lado: `-Panel <cuenta>` dibuja lo mismo que arma el menú de esa cuenta, y
1411
- el gate comprueba que ese panel sea más chico que el general.
1412
- - **El candado se probó**: la segunda instancia sale sola con su mensaje.
1413
- - **El aviso de «se liberó» y el de todas-las-barras están probados en la
1414
- lógica, no en pantalla**, igual que los otros avisos de esta sección.
1415
- - **El panel y los íconos se miraron, no se supusieron.** Los dos se
1416
- renderizaron a PNG con los datos reales; los íconos, además, a los 16×16
1417
- reales y agrandados con vecino más cercano sobre fondo claro y oscuro, que es
1418
- mirar los píxeles que va a haber y no una versión cómoda. Ahí se vio que los
1419
- dígitos no servían y que faltaba la tabla de color oscura. **El panel en
1420
- oscuro se capturó del proceso vivo**, que se puede: un menú es una ventana
1421
- normal y `CopyFromScreen` la agarra, al contrario que la barra de tareas, que
1422
- la compone DWM y devuelve negro.
1423
- - **La tira se verificó por UI Automation**, justamente porque la barra de
1424
- tareas no se deja capturar: se le preguntó a la bandeja qué items tiene, y
1425
- contestó uno por cuenta con su tooltip —incluidos los perfiles mudos y el `~`
1426
- de cache viejo—, unos en la barra y otros en el desplegable.
1427
- - **«Actualizar ahora» se probó con los handlers reales del archivo**, no con
1428
- una copia: la función vuelve en 59 ms —no congela—, el panel sigue abierto
1429
- después del click, el item muestra y saca el «Actualizando…», clickear
1430
- cualquier otro item sí cierra, y con dos dibujos de alturas distintas a
1431
- propósito el panel abierto pasa de 472 a 614 px y vuelve a 472 sin recortar
1432
- nada.
1433
- - **Los avisos están probados en la lógica, no en pantalla.** Ningún perfil pasó
1434
- de 80 % cuando se probó, así que se ejercitaron con una barra sintética al
1435
- 96 % y un `NotifyIcon` de mentira que anota los globos en vez de dibujarlos:
1436
- dispara 80 y 95 con la severidad correcta, dispara el choque, **no repite** en
1437
- la segunda pasada, y **vuelve a avisar** cuando cambia el minuto de reinicio.
1438
- Lo que sigue sin verse es el globo de Windows en la pantalla.
1439
- - **Handles medidos, no supuestos.** `GetHicon()` entrega un handle que el GC no
1440
- libera, así que se destruye a mano. Medido sobre el proceso vivo, en tres
1441
- muestras a lo largo de 300 s: 639, 589, 615. Fluctúa sin subir.
1442
- - El `.ps1` está guardado **UTF-8 con BOM a propósito**: sin BOM, PowerShell 5.1
1443
- lo lee como Windows-1252 y los acentos y las flechas salen rotos.
1444
- - **Dos colisiones de nombre, las dos del mismo tipo.** PowerShell no distingue
1445
- mayúsculas, así que `$script:Mono` y el parámetro `$mono` eran la misma
1446
- variable, y `$PALETA` empezó llamándose `$NIVEL` y la tapaba la local
1447
- `$nivel`. Las dos aparecieron corriendo el código, no leyéndolo.
1448
-
1449
- ## En la statusline de Claude Code
1450
-
1451
- Es donde la herramienta cumple su misión: el número deja de ser algo que te
1452
- acordás de mirar y pasa a estar siempre a la vista. `--breve` no toca las
1453
- transcripciones, así que tarda ~85 ms en vez de un segundo.
1454
-
1455
- En el `settings.json` del perfil:
221
+ Cutting a version is one command:
1456
222
 
1457
- ```json
1458
- {
1459
- "statusLine": { "type": "command", "command": "qm --breve" }
1460
- }
1461
- ```
1462
-
1463
- Sale así, con `!` para la barra que el servidor marcó con aviso y `~` para un
1464
- cache de más de 6 horas:
1465
-
1466
- ```
1467
- personal 23/75%! · teams 9/42% · codex 49/59%
223
+ ```sh
224
+ ./scripts/cortar-release.sh patch # moves the version in all seven places,
225
+ # runs the gates, commits and tags
226
+ git push origin main && git push origin v0.1.7
1468
227
  ```
1469
228
 
1470
- Son **dos números por cuenta a propósito**: el primero es la sesión y el segundo
1471
- la barra que te frena antes. Contestan preguntas distintas —«¿puedo seguir
1472
- ahora?» y «¿llego al final de la semana?»— y una sola de las dos deja media
1473
- respuesta. Cuando la que frena ES la sesión, se muestra un número solo.
1474
-
1475
- Ojo con lo que **no** hace: el cache se refresca cuando ese perfil corre Claude
1476
- Code, así que la statusline de un perfil se actualiza usándolo. Es suficiente
1477
- para la mecánica que importa —enterarte de que vas al 75 % mientras trabajás—
1478
- y no para vigilar un perfil que no estás usando.
229
+ What each channel needs configured is in
230
+ [`paquetes/README.md`](paquetes/README.md).
1479
231
 
1480
- ## El build, y por qué es opcional
1481
-
1482
- El repo lee el TypeScript directo: no hay paso de build y `make instalar`, el
1483
- `.deb` y Homebrew funcionan así. **npm es la excepción, y no por gusto.** Node
1484
- se niega a hacer type stripping de cualquier archivo bajo `node_modules`:
232
+ ## Design
1485
233
 
1486
234
  ```
1487
- ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING
1488
- Stripping types is currently unsupported for files under node_modules
235
+ src/core/ profiles, types. Knows nothing about keychains or HTTP.
236
+ src/adapters/ credentials (keychain / file), transcripts (JSONL), quota
237
+ from the cache (.claude.json) and from the endpoint (HTTP),
238
+ Codex (JSON-RPC) and opencode (SQLite).
239
+ src/cli/ qm, and one demo per milestone.
240
+ src/render/ bars and formatting for the terminal, and the dashboard.
241
+ bin/ the launchers — qm (POSIX), qm.cmd + buscar-node.cmd
242
+ (Windows), qm.mjs (npm's entry, which has to work on both) —
243
+ and the four surfaces. They draw and nothing else.
244
+ extension/ the GNOME Shell extension that keeps the click.
245
+ paquetes/ how it reaches a machine that never clones the repo.
246
+ numeros/ one file per milestone: measured output, and an explicit
247
+ list of what could NOT be measured and why.
1489
248
  ```
1490
249
 
1491
- Y un `npm install -g` deja el paquete exactamente ahí. Medido: se empaquetó el
1492
- tarball, se instaló en un prefix limpio y `qm` murió; se copió *ese mismo
1493
- directorio* fuera de `node_modules` y corrió perfecto. Mismo código, mismo Node,
1494
- misma versión — cambia sólo la ruta.
250
+ If a vendor name or an OS-specific path shows up outside `src/adapters/`, that
251
+ is a design bug.
1495
252
 
1496
- Así que `npm run construir` compila `src/` a `dist/` y **sólo el tarball de npm
1497
- lleva `dist/`**. `bin/qm` prefiere `dist/cli/qm.js` si existe y si no lee
1498
- `src/cli/qm.ts`, de modo que un clone sigue sin necesitar build.
253
+ ## The rest of it
1499
254
 
1500
- ```sh
1501
- make construir # compila a dist/ — sólo hace falta para publicar
1502
- make gate-npm # empaqueta, instala en un prefix limpio y CORRE qm
1503
- make gate-npm-rojo # el rojo: el paquete sin dist/, que es como estaba
1504
- ```
1505
-
1506
- El piso de Node **no** baja con el build: sigue en 22.6 porque
1507
- `src/adapters/opencode.ts` usa `node:sqlite`.
1508
-
1509
- ## Diseño
1510
-
1511
- ```
1512
- src/core/ perfiles, tipos. No sabe de llaveros ni de HTTP.
1513
- src/adapters/ credenciales (llavero / archivo), transcripciones (JSONL),
1514
- cuota del cache (.claude.json) y del endpoint (HTTP), el
1515
- parser de la forma de utilización que comparten los dos, y
1516
- codex (JSON-RPC contra su app-server, con cache propio).
1517
- src/cli/ qm (el comando) y las demos de cada hito.
1518
- dist/ el JS compilado. No se comitea; sólo viaja en el tarball de
1519
- npm, porque Node no lee TypeScript bajo node_modules.
1520
- src/render/ barras y formato para la terminal, y tablero.html para el
1521
- navegador. Sin dependencias.
1522
- extension/ la extensión de GNOME Shell que se queda con el click
1523
- bin/ el lanzador que encuentra un Node, el indicador de GNOME, la
1524
- bandeja de Windows, la barra de macOS y el servidor del
1525
- tablero. Todos dibujan y nada más: le piden el JSON a qm y no
1526
- saben de credenciales ni de HTTP.
1527
- ```
255
+ - **[`SOUL.md`](SOUL.md)** — the mission, the metric, and the locked non-goals.
256
+ Short, and the only file you need before proposing a change.
257
+ - **[`BITACORA.md`](BITACORA.md)** — the engineering log, in Spanish: how each
258
+ decision was reached, mistakes included. Three architectures for the GNOME
259
+ panel before one held; an assumption about the macOS menu bar that turned out
260
+ to be false; a CI gate that watched one function out of 1500 lines; an npm
261
+ package that installed and then refused to run.
262
+ - **[`CONTRIBUTING.md`](CONTRIBUTING.md)** — the three unusual rules:
263
+ everything is measured, renderers only draw, gates are proven red.
264
+ - **[`docs/esquema-json.md`](docs/esquema-json.md)** — the `qm --json`
265
+ contract, if you are writing a consumer.
266
+ - **[`numeros/`](numeros/)** — the measurements themselves, one per milestone.
1528
267
 
1529
- La regla es la de siempre: si un nombre de vendor o una ruta de sistema
1530
- operativo aparece fuera de `src/adapters/`, es un bug de diseño.
268
+ The code and its comments are in Spanish; what faces outward is in English.
269
+ That is deliberate, and `CONTRIBUTING.md` says why.
1531
270
 
1532
- ## Licencia
271
+ ## License
1533
272
 
1534
- MIT. Es la excepción a propósito: el núcleo de Legios —cartographer, healer,
1535
- pipeline— es propietario, y se publica lo que sirve suelto. Esto sirve suelto.
273
+ MIT. The deliberate exception: the core of Legios — cartographer, healer,
274
+ pipeline — is proprietary, and what gets published is what stands on its own.
275
+ This stands on its own.
1536
276
 
1537
277
  ---
1538
278
 
@@ -1544,6 +284,6 @@ pipeline— es propietario, y se publica lo que sirve suelto. Esto sirve suelto.
1544
284
  <img alt="Legios" src="docs/legios-claro.svg" width="150" height="49">
1545
285
  </picture></a>
1546
286
 
1547
- <sub>Construido por Valentín Torassa y Sol Soletti.</sub>
287
+ <sub>Built by Valentín Torassa and Sol Soletti.</sub>
1548
288
 
1549
289
  </div>