1# Reglas del repo compartido
2
3Este repo lo trabajan **varios agentes a la vez** (hoy: frente granja/store y frente kernel). Lo de
4aquí abajo no son preferencias de estilo: son las dos formas conocidas de que un agente destruya el
5trabajo de otro sin enterarse. El resto del diseño está en `docs/`.
6
7## 1. Todo `takana build` va envuelto en `flock`
8
9```sh
10flock work/.farm-build.lock ./target/release/takana --store ./store build <receta>
11```
12
13Para una tanda, tomar el lock una sola vez y no por receta:
14
15```sh
16flock work/.farm-build.lock bash -c 'for r in ...; do ./target/release/takana --store ./store build "$r"; done'
17```
18
19**Por qué.** `takana build` comparte `work/sources/<dep>-<sha>` entre todas las recetas. Dos builds
20concurrentes que compartan una dependencia se pisan el árbol de fuentes: uno hace fetch y lo borra
21mientras el otro lo usa, y **el árbol queda roto para siempre** — reintentar no lo arregla. Medido a
22escala: al invalidar libdrm, ~93 de 205 recetas KDE murieron con `/src/.zwrap/cc is not a full path
23to an existing compiler tool`, que es el wrapper de zig que la receta deja EN EL ÁRBOL, barrido por
24el fetch concurrente de otra receta. Es el **ADR 0012**, sin decidir; hasta que se decida
25(lock por árbol / árbol privado / caché inmutable + copia), serializar es la única mitigación
26correcta. Por eso el worker corre con `JOBS=1`.
27
28⚠ **Y usar `flock -o`, no `flock` a secas — esto es medido, no teórico (2026-09-08).** El lock lo
29sostiene la *descripción de fichero abierta*, y los hijos la HEREDAN: si un nieto se fuga, el lock
30queda tomado para siempre aunque el `flock` haya terminado hace rato. Pasó: dos `firefox` colgados de
31una caza de bugs sobrevivieron al `kill` del `bwrap` que los envolvía y **dejaron a la granja sin
32poder compilar durante hora y media, en silencio** — nada falla, simplemente el siguiente `flock`
33espera para siempre. Comprobado en los dos sentidos:
34
35```sh
36flock    lock sh -c 'sleep 25 & exit 0'   # ⇒ el nieto RETIENE el lock tras salir flock
37flock -o lock sh -c 'sleep 25 & exit 0'   # ⇒ lock LIBRE; -o cierra el fd antes de ejecutar
38```
39
40Si el lock parece tomado y no hay ningún build, `fuser -v work/.farm-build.lock` dice quién lo tiene;
41casi siempre es un proceso fugado que nadie asocia con el lock. **Los scripts de `scripts/farm/` usan
42el estilo `exec 9>` + `flock 9`, que es vulnerable igual** (haría falta `9>&-` en cada hijo): deuda
43conocida, no barrida.
44
45`scripts/farm/farm-worker-loop.sh` y `campana-deuda.sh` ya toman **ese mismo fichero de lock**, así
46que usarlo nos serializa con la granja además de entre nosotros. **No está dentro de `takana build`
47a propósito**: esos scripts lo toman por fuera y takana se bloquearía contra ellos.
48
49## 1 bis. El worker es el LXC PRESTADO, y es GRATIS: no se levanta nada en Hetzner
50
51**`dev.gioser.net` (154.197.1.13, hostname interno `PruebasIA`) es dónde se compila.** Es un LXC
52prestado en el Proxmox de gioser: 6 cores, 16 G RAM + 8 G swap, 196 G de disco, **coste €0**.
53Se usa exactamente por eso — **para no gastar Hetzner**.
54
55⇒ **No levantar cajas hcloud** (`farm-up.sh`, `farm-run.sh`) salvo que el usuario lo pida por su
56nombre. El modelo efímero de pago sigue documentado y funcionando, pero está SUPERADO como sitio de
57trabajo desde el 2026-09-05. Un `farm-up` por reflejo cuesta dinero real y no hace falta.
58
59```sh
60ssh -i ~/.ssh/id_ed25519 root@dev.gioser.net  # la que entra HOY; NO hay entrada en ssh/config
61```
62
63⚠ **Los scripts piden `~/.ssh/github5`, ese fichero NO EXISTE en el hub, y aun así todo funciona —
64por accidente** (medido 2026-09-18). Una docena larga de scripts trae
65`SSH_KEY="${SSH_KEY:-$HOME/.ssh/github5}"`: `estado-granja.sh`, `cosecha-cron.sh`, `harvest-go.sh`,
66`farm-up.sh`, `farm-down.sh`, `harkaq-vol.sh`… El único fichero en `~/.ssh` es `id_ed25519`, y sin
67embargo `estado-granja.sh` con su default entra y reporta. **`ssh -i <fichero inexistente>` no
68falla**: avisa por stderr y cae a las identidades por defecto, que es donde está la buena:
69
70```
71Warning: Identity file /home/sergio/.ssh/github5 not accessible: No such file or directory.
72debug1: identity file /home/sergio/.ssh/id_ed25519 type 2
73debug1: Offering public key: /home/sergio/.ssh/id_ed25519 ED25519 SHA256:kAqayFW4hSqq…
74debug1: Server accepts key: … · Authenticated to dev.gioser.net using "publickey".
75```
76
77O sea que **el `-i` de todos esos scripts es hoy un no-op** y quien manda es el fallback. Se cae el
78día que alguien ponga un `~/.ssh/github5` que no entre (el `-i` explícito GANA sobre el default), o
79que aparezca un `IdentityFile`/`IdentitiesOnly` en `ssh/config`. Y el error dirá `Permission
80denied`, sin mencionar `SSH_KEY` ni `github5`. Mismo patrón que el reaper salvándose por la
81subcadena `gioser`: *una protección que funciona por accidente se ve igual que una que funciona por
82diseño*. Barrer el default de los scripts es su propia unidad de trabajo — no tocarlos de paso.
83
84**Se enchufa por `scripts/farm/.fleet`** (`<nombre> <ip>` por línea), que **está en `.gitignore`**:
85o sea que un hub recién clonado nace con la flota VACÍA y la granja queda desconectada **sin que
86nada falle** — la cosecha dice «flota vacía» cada 30 min y los artefactos del worker no vuelven.
87Pasó, y se descubrió por casualidad. Si `estado-granja.sh` dice «no hay worker vivo», mirá `.fleet`
88antes de creerle.
89
90    echo "dev.gioser.net 154.197.1.13" > scripts/farm/.fleet
91
92⚠ **Y hasta el 2026-09-08 eso sobrevivía por una CASUALIDAD DE NOMBRE.** El reaper de
93`cosecha-cron.sh` saca de `.fleet` a todo lo que no esté en hcloud; el LXC se salvaba sólo porque su
94nombre contiene la subcadena `gioser` y caía en una lista negra que existe para proteger al HUB de
95Hetzner y no tiene nada que ver con él. Medido: el mismo host llamado `pruebasia-lxc` era expulsado
96en el primer ciclo. **Arreglado** — ahora el reaper pregunta por SSH si el host responde en vez de
97mirarle el nombre — pero la lección queda: *una protección que funciona por accidente se ve igual
98que una que funciona por diseño*.
99
100## 2. Nunca `git add -A` — y acotar el COMMIT, no sólo el `add`
101
102Sólo rutas explícitas. Un `add -A` arrastra al commit los ficheros a medias de otro agente. Commits
103granulares, en español, directo sobre `main`, y `git push` tras cada unidad de trabajo (el `origin`
104empuja a gitea **y** al espejo privado de GitHub; ver `scripts/espejo-setup.sh`).
105
106⚠ **Desde la jaula qorpa ese `push` doble SÓLO llega a gitea: el espejo de GitHub falla siempre**
107(medido 2026-09-18). El `PATH` del lab pone primero el git del CORPUS —`/work/sergio/bin/git`,
1082.54.0, musl— y ese build **no trae los helpers `remote-http`/`remote-https`**. El push termina así,
109con gitea ya actualizado y GitHub intacto:
110
111```
112To ssh://git.gioser.net:2345/sergio/takana.git
113   317ce48c..fd065720  main -> main            ← gitea OK
114git: 'remote-https' is not a git command.      ← y el espejo se queda atrás
115fatal: remote helper 'https' aborted session
116```
117
118Sale con estado ≠ 0, pero **la primera línea dice «main -> main» y se lee como éxito**. El git de la
119imagen sí los tiene (`/usr/bin/git`, 2.55.0), así que el espejo se empuja con él:
120
121```sh
122/usr/bin/git push https://github.com/sergiovelasquezzeballos/takana.git main
123```
124
125Corolario: el espejo deriva solo mientras se trabaje desde adentro — el 2026-09-18 estaba una hora
126atrás y nadie se había enterado. Comprobar con `git log --oneline -1` de los dos lados, no con la
127salida del push.
128
129⚠ **«Rutas explícitas» en el `add` NO ALCANZA, y esto es medido, no teórico** (2026-09-06): el
130commit `ff0b556` se llevó dentro un rename y un borrado de otro agente **habiendo usado
131`git add recipes/firefox.toml` y `git commit` sin `-a`**. La causa es que **el índice es estado
132COMPARTIDO**: `git commit` commitea el índice ENTERO, no lo que vos acabás de añadir, así que
133cualquier cosa que el otro agente dejó en `git add` viaja en tu commit. Comprobado en un repo de
134juguete, en los dos sentidos:
135
136```sh
137git add mio.txt && git commit -m …          # ⇒ arrastra ajeno.txt (estaba staged por el otro)
138git commit -m … -- mio.txt                  # ⇒ SÓLO mio.txt; lo del otro queda staged e intacto
139```
140
141**Entonces: `git commit -m "…" -- <rutas>`.** El `--` acota el commit por pathspec y es lo único que
142aísla de verdad. Vale también para `git commit -F -`. Corolario: no dar por bueno el alcance sin
143mirarlo — `git show --stat` sobre el commit recién hecho cuesta un segundo y es la única forma de
144enterarse el mismo día en vez de por el otro agente.
145
146⚠ **Pero el `--` NO protege la ruta que vos nombrás, y la intuición es la contraria** (medido
1472026-09-15, repo de juguete): con un fichero en estado `MM` —stageado *y* modificado por otro—,
148`git commit -- f.txt` commitea **el ÁRBOL, no lo stageado**, y además deja el índice en la versión
149del árbol, o sea que **lo que el otro agente tenía stageado en ESA ruta desaparece**.
150
151```sh
152# f.txt: v2 en el índice (del otro), v3 en el árbol (mío)
153git commit -m … -- f.txt     # ⇒ commitea v3 · el índice queda en v3 · v2 se perdió
154```
155
156El pathspec aísla de lo que el otro dejó en **otras** rutas — que es lo del párrafo de arriba y
157sigue siendo cierto. Corolario: **un fichero que aparece `MM` y que vos no tocaste no se commitea
158ni con pathspec — se avisa.** Pasó con el `Cargo.lock` de tawasuyu (SDD 26 §7.quinquies), donde el
159árbol del otro agente ya traía la reparación que hacía falta.
160
161## 2 ter. `git pull --rebase` puede DESCARTAR tu commit sin decir nada
162
163⚠ **Medido acá el 2026-09-16, y cuesta una hora de trabajo si no sabés mirar el reflog.**
164
165Secuencia real: commit propio en `main` (10 ficheros nuevos) → `git push` → **gitea lo rechaza**
166porque otro agente empujó → `git pull --rebase` → el push vuelve a fallar y **el commit ya no está**,
167ni en el log ni en el ÁRBOL: los diez ficheros habían desaparecido del disco.
168
169El reflog lo explica y es lo único que lo explica:
170
171```
17211a9ead6 HEAD@{0}: pull --rebase (finish): returning to refs/heads/main
17311a9ead6 HEAD@{1}: pull --rebase (start): checkout 11a9ead6
174f3d7be6c HEAD@{2}: commit: los 9 daemons propios entran al catálogo…     ← el mío
175```
176
177**Entre `start` y `finish` no hay ni un `pick`**: el rebase no encontró NADA que reaplicar, y con
178`-q` eso se ve igual que un pull limpio.
179
180⚠ **PASÓ DOS VECES EL MISMO DÍA** (2026-09-16 y 2026-09-17), con el mismo reflog: `commit` propio,
181`(start): checkout <otro>`, `(finish): returning to refs/heads/main` — y ni un `pick` en el medio.
182
183**Y el comando NO es el culpable: se reprodujo en un repo de juguete y ahí funciona bien.** Dos
184clones, el otro empuja, yo commiteo local, `git pull --rebase -q origin main` ⇒ **mi commit se
185reaplica y mi fichero sigue ahí**. O sea que lo que falla no es `pull --rebase`: es que este árbol
186lo comparten varios agentes y **alguien mueve `refs/heads/main` mientras el rebase está en vuelo**.
187La receta práctica no cambia; el diagnóstico sí, y evita ir a buscar el bug al lugar equivocado.
188
189⚠ **La CAUSA exacta no está determinada, y conviene decirlo así en vez de inventarla.** Lo medido es el
190reflog de arriba y que los diez ficheros desaparecieron también del ÁRBOL, que es lo que un
191`reset --hard` o un `checkout` concurrente de otro agente sí explicaría. Lo que NO es evidencia —y
192se escribió como si lo fuera— es que los commits que trajo el `pull` cuelguen del commit anterior al
193mío: eso es lo normal cuando el otro lado empujó desde una máquina que había hecho `fetch` antes, y
194no dice nada de lo que pasó acá. **Que el árbol perdiera los ficheros es el dato fuerte; el resto,
195hipótesis.**
196
197**Qué hacer:**
198
199```sh
200git reflog -15                      # tu commit está acá, con su sha
201git cherry-pick <sha>               # vuelve entero, ficheros incluidos
202```
203
204Y la comprobación que evita el susto: **`git log --oneline -1` después de cada `pull --rebase`.** Si
205tu commit no es el primero, no se rebasó — se perdió de la rama, y el reflog lo tiene.
206
207⚠ **El espejo de GitHub queda DIVERGENTE en ese escenario**, y es normal: el `push` doble puede
208triunfar en un remoto y fallar en el otro (pasó: gitea rechazó, GitHub aceptó). Tras recuperar el
209commit, el espejo tiene un sha huérfano con el mismo contenido. Se repara empujando **sólo la URL de
210GitHub** con `--force-with-lease=main:<sha-huérfano>` — con lease, que verifica que el remoto sigue
211donde creés antes de pisarlo. Comprobar antes que el contenido no se pierde:
212`git diff --stat <huérfano> HEAD`.
213
214## 3. Antes de dar un artefacto por presente, mirá que tenga contenido
215
216Un directorio **vacío** en el store no es un artefacto: es un nombre. `Store::has` ya lo rechaza y
217`respaldo-storagebox.sh --listar` los separa a `work/respaldo-vacios.txt`, pero la regla general
218sigue valiendo para cualquier código nuevo — **un ausente falla ruidosamente; un vacío llega hasta
219el final diciendo que todo fue bien**.
220
221## 4. La superficie de la CLI va en INGLÉS; los mensajes, en castellano
222
223Subcomandos, flags y nombres de opciones: **inglés** (`build`, `hash`, `hydrate`, `mirror push`,
224`kernel closure`, `qorpa pull`). Lo que el usuario LEE —ayuda, errores, logs— va en castellano, y
225los nombres propios del proyecto son quechua (`takana`, `qorpa`, `harkaq`, `yupana`, `arje`).
226
227**La única excepción, y es cerrada:** el ADR 0016 admite **alias de marca** en castellano sobre un
228verbo canónico —hoy uno solo, `forja` → `build`— para que la invocación de la hoja de marca
229funcione. El alias **no reemplaza nada**: el canónico sigue siendo el inglés y es el que usan los
230scripts, el cron y los runbooks. Un alias es superficie de marca; el contrato es el canónico.
231Agregar otro alias es una decisión de ADR, no algo que se hace de paso.
232
233**Por qué.** Un verbo de CLI es contrato: entra en scripts, cron y runbooks, y renombrarlo después
234rompe llamadores que nadie recuerda. Media superficie en cada idioma obliga a adivinar en cada
235comando nuevo, y ya pasó: el ADR 0015 nació con `traer/crear/correr` y hubo que corregirlo.
236
237⚠ **Deuda conocida, NO barrida todavía:** varios scripts de `scripts/` exponen flags en castellano
238(`--crear`, `--traer`, `--listar`, `--sha`). El barrido es su propia unidad de trabajo — tocarlos de
239paso rompe cron y la granja. Código NUEVO nace en inglés desde hoy.