feat(arje): incluye CLIs admin en el initrd (brahman-status/busctl/brainctl)

Para "ver" la administración del init desde el shell que arrancó dentro
del initramfs hacían falta clientes que hablen los 4 sockets Unix. Los
exists como examples de cada crate; los empaquetamos ahora.

build-arje-initrd.sh:
- cargo build --example brahman-status -p brahman-admin
- cargo build --example busctl         -p ente-bus
- cargo build --example brainctl       -p ente-brain
- Copia los 3 a /usr/bin/ del initrd.

docs/arje-boot.md §6b reescrita con:
- Tabla de sockets corregida (defaults a /tmp/ cuando no hay
  XDG_RUNTIME_DIR/TMPDIR, que es el caso en initrd).
- Cookbook de los 3 CLIs con ejemplos de sesión típica dentro de la VM.
- Nota para vendorear socat-static via EXTRA_BINS si querés conectar
  crudo a un socket.

§1 layout actualizado con /usr/bin/{brahman-status,busctl,brainctl}.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
sergio
2026-05-18 19:42:29 +00:00
parent ec458b8a6f
commit e4b1d41b62
2 changed files with 74 additions and 9 deletions
+59 -8
View File
@@ -26,6 +26,9 @@ El initrd es un **CPIO + gzip** (formato `newc`, estándar Linux). Su raíz:
/usr/sbin/ente-echo
/usr/sbin/ente-policy-provider
/usr/sbin/ente-*-compat 13 shims D-Bus (logind, hostnamed, …)
/usr/bin/brahman-status CLI: snapshot del broker (sesiones + matches)
/usr/bin/busctl CLI: bus interno (list-entes, announce, …)
/usr/bin/brainctl CLI: cerebro (rules, entropy, crystals)
/ente/seed.card.json Tarjeta Semilla canónica
/bin/{sh,ls,mount,…} busybox-static
/etc, /dev, /proc, /sys, /run mountpoints vacíos
@@ -301,15 +304,63 @@ echo 'export RUST_LOG="trace"' >> wrapper
### 6b. Sockets de introspección (Unix, dentro del initrd)
| socket | servicio |
| ---------------------------- | ------------------------------------------------- |
| `/run/ente-bus.sock` | bus interno (postcard, `BusRequest::Invoke/...`) |
| `/run/brahman-init.sock` | handshake brahman |
| `/run/brahman-admin.sock` | snapshots de sesiones + matches |
| `/run/ente-brain.sock` | introspección del cerebro |
Sin `XDG_RUNTIME_DIR` ni `TMPDIR` en el env de PID 1 (caso del initrd),
los sockets caen al fallback `/tmp/`:
Conectar desde un Ente hijo: `socat - UNIX-CONNECT:/run/brahman-admin.sock`.
(El initrd debe tener `socat` o equivalente; agregalo con `EXTRA_BINS`.)
| socket | env override | servicio |
| ---------------------------- | ----------------------- | ----------------------------------------- |
| `/tmp/ente-bus-*.sock` | `ENTE_BUS_SOCK` | bus interno (Announce/Invoke/ListEntes) |
| `/tmp/brahman-init.sock` | `BRAHMAN_INIT_SOCKET` | handshake brahman |
| `/tmp/brahman-admin.sock` | `BRAHMAN_ADMIN_SOCKET` | snapshots de sesiones + matches |
| `/tmp/ente-brain.sock` | `ENTE_BRAIN_SOCK` | introspección del cerebro (rules, observer) |
El initrd trae 3 CLI clients precompilados en `/usr/bin/`:
```sh
brahman-status # snapshot completo: sesiones + matches + WIT + flows
busctl list-entes # entes anunciados en el bus
busctl announce # smoke test: anuncia una Card desde el shell
busctl power-off # apaga el fractal
brainctl list-rules # reglas crystallizadas + manuales
brainctl entropy # entropía del observer estadístico
brainctl top 10 # top-10 kinds por frecuencia
brainctl crystals # patrones detectados con auto-promote
brainctl crystal-json 0 # exporta un crystal específico como Rule JSON
```
Ejemplo de sesión típica dentro de la VM:
```sh
arje# brahman-status
Init: server=0.1.0 protocol=0.1.0 attached=true
Context: (sin set)
Sessions (3):
[ente] 01HQ5R2K… compat-logind lifecycle=Daemon priority=High
[ente] 01HQ5R2K… compat-hostnamed lifecycle=Daemon priority=Normal
[ente] 01HQ5R2K… echo-smoke lifecycle=Daemon priority=Low
Matches (0):
(ninguno)
arje# busctl list-entes
14 entes en el bus:
01HQ… compat-logind provides=[LegacyLogind]
01HQ… compat-journald provides=[Journal]
arje# brainctl top 5
spawn 14
ente_died 0
```
Si en cambio querés conectar crudo con `socat`/`nc`, agregalo con
`EXTRA_BINS=/usr/bin/socat-static scripts/build-arje-initrd.sh` y luego:
```sh
arje# socat - UNIX-CONNECT:/tmp/brahman-admin.sock | jq .
```
### 6c. Snapshot / restore