|
|
|
@@ -0,0 +1,324 @@
|
|
|
|
|
# Incidente: cadena de 4 fallos en `tmux-host` (2026-09-25/26)
|
|
|
|
|
|
|
|
|
|
| | |
|
|
|
|
|
|---|---|
|
|
|
|
|
| **Ventana del incidente** | Noche del 2026-09-25 al 26 (hora local); en `health.log`, de 2026-09-26 04:11Z a ~06:20Z |
|
|
|
|
|
| **Servicio afectado** | Contenedor `tmux-host`: las sesiones `lab` y `cloud-practice` de Claude Code y su Remote Control desde claude.ai (ver [Sesión tmux persistente](../arquitectura/sesion-tmux-persistente.md)) |
|
|
|
|
|
| **Impacto** | Las sesiones remotas no aparecían en claude.ai. Mientras se intentaba arreglar, se perdió el login y la confianza del folder, el supervisor del healthcheck quedó muerto y `claude` no podía conectarse a Anthropic |
|
|
|
|
|
| **Disparador** | Se eliminó el contenedor `tmux-host` a mano creyendo que era la causa |
|
|
|
|
|
|
|
|
|
|
## Contexto / disparador
|
|
|
|
|
|
|
|
|
|
El síntoma inicial era uno solo: **"no toma las sesiones remotas"**. Las
|
|
|
|
|
sesiones de Claude Code dentro de `tmux-host` no aparecían en claude.ai.
|
|
|
|
|
Parecía un problema del contenedor, así que se eliminó `tmux-host` para
|
|
|
|
|
recrearlo desde cero.
|
|
|
|
|
|
|
|
|
|
En realidad ese síntoma tenía una causa que no tenía nada que ver con el
|
|
|
|
|
contenedor: el token OAuth estaba vencido (causa **d**, más abajo). Al
|
|
|
|
|
recrear el contenedor, la mitad de la noche se fue en resolver tres fallos
|
|
|
|
|
reales que *aparecieron* en el camino (causas **a**, **b** y **c**). Cada
|
|
|
|
|
uno se encontró recién después de resolver el anterior. Recién al final
|
|
|
|
|
apareció la causa original.
|
|
|
|
|
|
|
|
|
|
!!! info "Fuentes de la evidencia"
|
|
|
|
|
Este playbook se escribió desde dentro del `tmux-host` ya recuperado.
|
|
|
|
|
Los datos marcados **(verificado)** se confirmaron contra el estado
|
|
|
|
|
real del sistema al escribirlo: `docker inspect`, `docker images`,
|
|
|
|
|
`health.log`, `sysctl`, `curl`, `git diff` y los panes de tmux. Los
|
|
|
|
|
marcados **(reportado)** vienen del relato de la sesión de
|
|
|
|
|
recuperación. Esa sesión se hizo desde fuera del contenedor y no dejó
|
|
|
|
|
transcript ni historial de shell que se pueda revisar.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Causa a — Contenedor recreado sin los volúmenes de autenticación
|
|
|
|
|
|
|
|
|
|
**Síntoma.** Al recrear `tmux-host`, `claude` volvía a pedir login y el
|
|
|
|
|
diálogo de confianza del folder. `--continue` no encontraba ninguna
|
|
|
|
|
conversación previa y arrancaba una en blanco.
|
|
|
|
|
|
|
|
|
|
**Diagnóstico.** El `docker run` que se usó para recrear el contenedor
|
|
|
|
|
se armó de memoria. Tenía solo 3 de los 5 volúmenes documentados en
|
|
|
|
|
[Sesión tmux persistente](../arquitectura/sesion-tmux-persistente.md)
|
|
|
|
|
**(reportado)**. Faltaban justamente los dos de autenticación y estado
|
|
|
|
|
de Claude Code:
|
|
|
|
|
|
|
|
|
|
| Volumen faltante | Qué se perdía |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `/DATA/AppData/k3d-lab-v3/claude-code-home` → `/root/.claude` | Credenciales OAuth, historial de conversaciones (por eso `--continue` no encontraba nada), plugins y memoria |
|
|
|
|
|
| `/DATA/AppData/k3d-lab-v3/claude-code-home.json` → `/root/.claude.json` | Confianza del folder y el flag de Remote Control |
|
|
|
|
|
|
|
|
|
|
Sin esos mounts, `/root/.claude*` vive en el filesystem efímero del
|
|
|
|
|
contenedor, así que cada recreación arrancaba "de fábrica". El contenedor
|
|
|
|
|
se reconstruyó varias veces con el mismo comando incompleto antes de
|
|
|
|
|
comparar contra el doc de arquitectura **(reportado)**. `health.log`
|
|
|
|
|
muestra las sesiones recreándose desde cero a las 04:11Z, 04:40Z, 04:49Z,
|
|
|
|
|
05:03Z, 05:18Z, 06:08Z y 06:10Z **(verificado)**.
|
|
|
|
|
|
|
|
|
|
**Fix.** Recrear el contenedor con el `docker run` completo de la
|
|
|
|
|
sección *Contenedor: `tmux-host`* del doc de arquitectura. Los 5 volúmenes
|
|
|
|
|
van juntos, sin excepciones.
|
|
|
|
|
|
|
|
|
|
**Validación en vivo (verificado).** `docker inspect tmux-host` sobre el
|
|
|
|
|
contenedor final (creado `2026-09-26T06:10:55Z`, imagen
|
|
|
|
|
`tmux-host:2026-09-26-fix-real`) lista los 5 mounts:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
/var/run/docker.sock -> /var/run/docker.sock
|
|
|
|
|
/DATA/AppData/k3d-lab-v3/claude-code-home -> /root/.claude
|
|
|
|
|
/DATA/AppData/k3d-lab-v3/claude-code-home.json -> /root/.claude.json
|
|
|
|
|
/DATA -> /DATA
|
|
|
|
|
/media/HDD-Storage -> /media/HDD-Storage
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
La sesión `lab` retomó la conversación anterior con `--continue`, sin
|
|
|
|
|
pedir de nuevo la confianza del folder.
|
|
|
|
|
|
|
|
|
|
!!! warning "Lección"
|
|
|
|
|
**Antes de improvisar un `docker run` de memoria, leer siempre el doc
|
|
|
|
|
de arquitectura que ya existe.** El comando completo y el motivo de
|
|
|
|
|
cada volumen ya estaban documentados en `sesion-tmux-persistente.md`.
|
|
|
|
|
El tiempo perdido reconstruyendo con un comando incompleto salió de no
|
|
|
|
|
abrirlo primero.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Causa b — `set -e` heredado mataba al supervisor del healthcheck
|
|
|
|
|
|
|
|
|
|
**Síntoma.** `healthcheck.sh` corre en background y no tenía quién lo
|
|
|
|
|
relanzara si moría. Para cubrir eso se agregó a `entrypoint.sh` un
|
|
|
|
|
supervisor: un loop que lo relanza tras 10 s. Aun así, cuando
|
|
|
|
|
`healthcheck.sh` terminaba con error, no se relanzaba y el contenedor
|
|
|
|
|
seguía vivo sin healthcheck.
|
|
|
|
|
|
|
|
|
|
**Diagnóstico.** `entrypoint.sh` tenía `set -eu` desde antes. El
|
|
|
|
|
supervisor corre como función en un subshell (`supervise_healthcheck &`)
|
|
|
|
|
y hereda el `-e`. Cuando `healthcheck.sh` devolvía un código distinto de
|
|
|
|
|
cero, `set -e` mataba al propio subshell del supervisor *en esa misma
|
|
|
|
|
línea*, antes de llegar al `echo WARN` y al `sleep 10` que lo relanzaban.
|
|
|
|
|
Es decir, el supervisor moría justo en el único caso para el que existía.
|
|
|
|
|
|
|
|
|
|
**Paso en falso: el fix que nunca llegó al disco.** La primera
|
|
|
|
|
"corrección" (`set -eu` → `set -u`) nunca se guardó en el archivo, y la
|
|
|
|
|
imagen se reconstruyó dos veces con el contenido viejo **(reportado)**.
|
|
|
|
|
La evidencia sigue en el host **(verificado)**: las etiquetas
|
|
|
|
|
`tmux-host:2026-09-25-supervised` y `tmux-host:2026-09-25-supervised-v2`
|
|
|
|
|
apuntan a la **misma imagen, `ad7f6eff9537`**. Docker reutilizó todas las
|
|
|
|
|
capas porque el archivo no había cambiado. Recién después de confirmar
|
|
|
|
|
con `cat entrypoint.sh` que el cambio no estaba, se guardó de verdad y se
|
|
|
|
|
construyó `tmux-host:2026-09-26-fix-real` (`7e4c94bf0bc8`, 05:03Z).
|
|
|
|
|
|
|
|
|
|
**Fix.** En `scripts/tmux-host/entrypoint.sh`:
|
|
|
|
|
|
|
|
|
|
```diff
|
|
|
|
|
-set -eu
|
|
|
|
|
+set -u
|
|
|
|
|
|
|
|
|
|
-/usr/local/bin/healthcheck.sh &
|
|
|
|
|
+supervise_healthcheck() {
|
|
|
|
|
+ while true; do
|
|
|
|
|
+ /usr/local/bin/healthcheck.sh
|
|
|
|
|
+ echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) WARN: healthcheck.sh salio inesperadamente (exit=$?) -- relanzando en 10s" \
|
|
|
|
|
+ >> /DATA/AppData/k3d-lab-v3/tmux-host/logs/health.log 2>/dev/null || true
|
|
|
|
|
+ sleep 10
|
|
|
|
|
+ done
|
|
|
|
|
+}
|
|
|
|
|
|
|
|
|
|
+supervise_healthcheck &
|
|
|
|
|
exec tail -f /dev/null
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Validación en vivo (verificado).** `health.log` registra el supervisor
|
|
|
|
|
actuando en un caso real. `healthcheck.sh` murió por SIGKILL, se registró
|
|
|
|
|
el aviso y se relanzó solo 10 segundos después:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
2026-09-26T05:04:17Z WARN: healthcheck.sh salio inesperadamente (exit=137) -- relanzando en 10s
|
|
|
|
|
[2026-09-26T05:04:27Z] === healthcheck inicio (intervalo=1800s) ===
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
!!! warning "Lección"
|
|
|
|
|
**Verificar el archivo en disco (`cat`, `git diff`) ANTES de
|
|
|
|
|
reconstruir la imagen.** No hay que asumir que el editor guardó el
|
|
|
|
|
cambio. Dos etiquetas de imagen con el mismo ID indican que el build
|
|
|
|
|
no tuvo cambios.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Causa c — IPv6 roto en el NAS: timeout de conexión a Anthropic
|
|
|
|
|
|
|
|
|
|
**Síntoma.** Con el contenedor ya bien montado, `claude` fallaba al
|
|
|
|
|
arrancar con `Unable to connect to Anthropic services` a los ~10 s.
|
|
|
|
|
|
|
|
|
|
**Diagnóstico** con `curl -v https://api.anthropic.com/` **(reportado)**:
|
|
|
|
|
|
|
|
|
|
1. El resolver devolvía primero la dirección IPv6 de `api.anthropic.com`.
|
|
|
|
|
2. La ruta IPv6 del NAS no sale a internet: el intento fallaba al
|
|
|
|
|
instante con `Network unreachable`.
|
|
|
|
|
3. El fallback automático a IPv4 terminaba funcionando, pero la conexión
|
|
|
|
|
completa tardaba **~14 s**. Eso es más que el timeout interno de
|
|
|
|
|
Claude Code (~10 s), así que el CLI se rendía antes de que el
|
|
|
|
|
fallback llegara a conectar.
|
|
|
|
|
|
|
|
|
|
**Primer intento: parche parcial.**
|
|
|
|
|
`NODE_OPTIONS=--dns-result-order=ipv4first` le indica a Node que prefiera
|
|
|
|
|
IPv4 al resolver. Ayudó, pero no resultó confiable en todos los casos
|
|
|
|
|
**(reportado)**, y además solo corregía el proceso de Node, no la red del
|
|
|
|
|
host. Se descartó y no quedó en la imagen: el contenedor final no tiene
|
|
|
|
|
`NODE_OPTIONS` en su entorno **(verificado)**.
|
|
|
|
|
|
|
|
|
|
**Fix de raíz.** Deshabilitar IPv6 a nivel de sistema operativo del NAS,
|
|
|
|
|
en caliente y persistente:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# En caliente
|
|
|
|
|
sysctl -w net.ipv6.conf.all.disable_ipv6=1
|
|
|
|
|
sysctl -w net.ipv6.conf.default.disable_ipv6=1
|
|
|
|
|
|
|
|
|
|
# Persistente: /etc/sysctl.conf del host
|
|
|
|
|
net.ipv6.conf.all.disable_ipv6 = 1
|
|
|
|
|
net.ipv6.conf.default.disable_ipv6 = 1
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Esto se tiene que hacer **en el host, no dentro del contenedor**.
|
|
|
|
|
`tmux-host` corre con `--network host`, así que comparte el network
|
|
|
|
|
namespace del NAS. Docker no permite fijar sysctls de red
|
|
|
|
|
(`--sysctl net.*`) en un contenedor con `--network host`, porque
|
|
|
|
|
cambiarían la red de todo el host.
|
|
|
|
|
|
|
|
|
|
**Validación en vivo (verificado, 2026-09-26 ~06:40Z):**
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
$ sysctl net.ipv6.conf.all.disable_ipv6 net.ipv6.conf.default.disable_ipv6
|
|
|
|
|
net.ipv6.conf.all.disable_ipv6 = 1
|
|
|
|
|
net.ipv6.conf.default.disable_ipv6 = 1
|
|
|
|
|
|
|
|
|
|
$ getent ahosts api.anthropic.com
|
|
|
|
|
160.79.104.10 STREAM api.anthropic.com # solo IPv4, sin AAAA
|
|
|
|
|
|
|
|
|
|
$ curl -w 'connect=%{time_connect}s total=%{time_total}s' https://api.anthropic.com/
|
|
|
|
|
ip=160.79.104.10 connect=0.035s total=0.65s # antes: ~14 s
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`/etc/sysctl.conf` en el host contiene las dos líneas (escrito
|
|
|
|
|
2026-09-26 05:55:53Z). En ZimaOS, `/` es un `squashfs` de solo lectura,
|
|
|
|
|
pero `/etc` es un overlay con capa de escritura en
|
|
|
|
|
`/mnt/overlay/upper_etc` (ext4 en `/dev/sdc7`), así que el archivo
|
|
|
|
|
persiste.
|
|
|
|
|
|
|
|
|
|
!!! note "Pendiente de validar"
|
|
|
|
|
Todavía no se probó que el sysctl persistente se aplique después de un
|
|
|
|
|
**reinicio real del NAS**. Tampoco se sabe si una actualización de
|
|
|
|
|
ZimaOS pisa `upper_etc`. En el próximo reinicio, revisar
|
|
|
|
|
`sysctl net.ipv6.conf.all.disable_ipv6` antes de dar por cerrado este
|
|
|
|
|
punto.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Causa d — Token OAuth vencido: Remote Control desconectado sin recuperación automática
|
|
|
|
|
|
|
|
|
|
**Síntoma.** Con todo lo anterior resuelto, las sesiones remotas
|
|
|
|
|
*seguían* sin aparecer en claude.ai. Este era el síntoma original de la
|
|
|
|
|
noche.
|
|
|
|
|
|
|
|
|
|
**Diagnóstico (verificado).** Ambos procesos `claude --remote-control
|
|
|
|
|
--continue` estaban corriendo (`ps`), y el healthcheck había recreado
|
|
|
|
|
las dos sesiones sin problema (`health.log`, 06:10:58Z). Así que el
|
|
|
|
|
auto-arranque funcionaba. El contenido de los panes de tmux mostró la
|
|
|
|
|
causa:
|
|
|
|
|
|
|
|
|
|
- Sesión `lab`: `Login expired · Please run /login`
|
|
|
|
|
- Sesión `cloud-practice`:
|
|
|
|
|
`Remote Control disconnected — OAuth token unavailable — run /login to restore Remote Control`
|
|
|
|
|
|
|
|
|
|
El token OAuth de Claude Code había vencido. No había ningún problema de
|
|
|
|
|
red, de contenedor ni de volúmenes. **Esta causa no tenía relación con
|
|
|
|
|
ninguna de las tres anteriores.** Eliminar el contenedor nunca podría
|
|
|
|
|
haberla resuelto.
|
|
|
|
|
|
|
|
|
|
**Fix.**
|
|
|
|
|
|
|
|
|
|
1. `/login` en **una** sesión. Las credenciales viven en
|
|
|
|
|
`/root/.claude/.credentials.json`, que es el volumen compartido por
|
|
|
|
|
todas las sesiones del contenedor.
|
|
|
|
|
2. `/remote-control` → **1. Enable Remote Control** en **cada** sesión ya
|
|
|
|
|
abierta. Un proceso `claude` que ya estaba corriendo **no** se
|
|
|
|
|
reconecta solo al renovarse el token. Hay que reactivarlo en cada uno.
|
|
|
|
|
Para una sesión a la que no estás adjunto:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
tmux send-keys -t cloud-practice '/remote-control' Enter
|
|
|
|
|
# aparece el menú con "1. Enable Remote Control" ya seleccionado
|
|
|
|
|
tmux send-keys -t cloud-practice Enter
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Validación en vivo (verificado).** El pane de `cloud-practice` pasó a
|
|
|
|
|
mostrar `/remote-control is active · Continue here, on your phone, or at
|
|
|
|
|
https://claude.ai/code/session_…`, y en `lab` se activó con
|
|
|
|
|
`/remote-control` después del `/login`. Las dos sesiones volvieron a
|
|
|
|
|
aparecer en claude.ai.
|
|
|
|
|
|
|
|
|
|
!!! tip "Diferencia clave con las otras causas"
|
|
|
|
|
El healthcheck **sí** recrea sola una sesión tmux caída, y `--continue`
|
|
|
|
|
retoma la conversación. Un **token vencido no se recupera solo**: hace
|
|
|
|
|
falta que una persona se reautentique (`/login`) y reactive Remote
|
|
|
|
|
Control (`/remote-control`) en cada sesión abierta. Recrear el
|
|
|
|
|
contenedor no lo arregla. Con los volúmenes bien montados, el
|
|
|
|
|
contenedor nuevo lee el mismo token vencido.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Cronología resumida
|
|
|
|
|
|
|
|
|
|
Horas en UTC, según `health.log`, `docker images` y los timestamps de
|
|
|
|
|
archivos cuando existen.
|
|
|
|
|
|
|
|
|
|
| Hora (UTC) | Qué pasó | ¿Resolvió el síntoma original? |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| antes de 04:11 | Remote Control se desconecta porque vence el token OAuth (causa **d**, todavía sin identificar) | — |
|
|
|
|
|
| ~04:10 | Se elimina `tmux-host` creyendo que es la causa | No |
|
|
|
|
|
| 04:11 → 05:18 | Varias recreaciones con un `docker run` de memoria, sin los mounts de auth: se pide login y confianza de nuevo y `--continue` arranca vacío (causa **a**) | No, y además empeoró |
|
|
|
|
|
| 04:39 | Se agrega el supervisor del healthcheck; builds `supervised` y `supervised-v2`, **misma imagen `ad7f6eff9537`** (el fix de `set -e` no estaba guardado) | No |
|
|
|
|
|
| 05:03 | Se confirma con `cat`, se guarda de verdad y se construye `fix-real` (`7e4c94bf0bc8`) con `set -u` (causa **b**) | No |
|
|
|
|
|
| 05:04 | El supervisor relanza `healthcheck.sh` tras un `exit=137`: primera prueba real | No |
|
|
|
|
|
| hasta ~05:55 | `claude` falla con `Unable to connect to Anthropic services`; con `curl -v` se ve IPv6 unreachable y ~14 s de fallback; se prueba `NODE_OPTIONS` (parcial) | No |
|
|
|
|
|
| 05:55 | Se deshabilita IPv6 en el host, en caliente y en `/etc/sysctl.conf` (causa **c**) | No |
|
|
|
|
|
| 06:10 | Contenedor final: `fix-real` + los 5 volúmenes, recreado según el doc de arquitectura (causa **a** cerrada) | No: Remote Control sigue desconectado |
|
|
|
|
|
| ~06:20 | Los panes muestran `Login expired` / `OAuth token unavailable` → `/login` + `/remote-control` en cada sesión (causa **d**) | **Sí** |
|
|
|
|
|
|
|
|
|
|
**Camino corto para la próxima vez.** Si "no aparecen las sesiones
|
|
|
|
|
remotas", **antes de tocar el contenedor** mirar el pane de cada sesión:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
for s in $(tmux ls -F '#S'); do echo "== $s"; tmux capture-pane -p -t "$s" | grep -v '^\s*$' | tail -5; done
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Si aparece `Login expired` u `OAuth token unavailable`, la solución es
|
|
|
|
|
`/login` + `/remote-control`. No hace falta nada más.
|
|
|
|
|
|
|
|
|
|
## Lección general
|
|
|
|
|
|
|
|
|
|
Un solo síntoma ("no toma las sesiones remotas") puede tener **varias
|
|
|
|
|
causas independientes superpuestas**. En este caso, tres de ellas las
|
|
|
|
|
provocó el propio intento de arreglo. Que la primera causa real
|
|
|
|
|
encontrada se haya resuelto no significa que era *la* causa del síntoma.
|
|
|
|
|
|
|
|
|
|
Lo que destrabó el incidente fue seguir verificando con evidencia
|
|
|
|
|
concreta después de cada fix, en vez de asumir que "ya quedó": el
|
|
|
|
|
contenido de los panes, `health.log`, `docker inspect`, `docker images`
|
|
|
|
|
(IDs repetidos) y `curl -v`. Cada una de las cuatro causas se confirmó
|
|
|
|
|
con un dato observable, no por deducción.
|
|
|
|
|
|
|
|
|
|
## Pendientes
|
|
|
|
|
|
|
|
|
|
- [ ] **Commitear el fix de `entrypoint.sh`.** La imagen `fix-real` que
|
|
|
|
|
corre en producción lo tiene, pero en el repo `scripts` el cambio
|
|
|
|
|
sigue como modificación local sin commitear (`git status` →
|
|
|
|
|
`M tmux-host/entrypoint.sh`). Si alguien reconstruye la imagen
|
|
|
|
|
desde `main`, vuelve el `set -eu` sin supervisor.
|
|
|
|
|
- [ ] Validar que IPv6 siga deshabilitado después del próximo reinicio
|
|
|
|
|
real del NAS (ver la nota de la causa c).
|
|
|
|
|
- [ ] Limpiar las etiquetas de imagen viejas de `tmux-host`
|
|
|
|
|
(`supervised`, `supervised-v2`, `local`, `test-fix`, etc.) para no
|
|
|
|
|
confundir cuál es la vigente.
|
devops
