Merge branch 'docs/incidente-tmux-host-2026-09-25'

Documenta la cadena de causas encontradas tras eliminar tmux-host por
"no toma las sesiones remotas": volumenes de auth faltantes al recrear,
set -e matando al supervisor del healthcheck, IPv6 roto en el NAS
(timeout a Anthropic) y, como causa original, el token OAuth vencido.
Agrega la fila de expiracion OAuth a "Que sobrevive a que" en
sesion-tmux-persistente.md con enlace cruzado al playbook.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_018r19s4H8MBGegqToqw5guP

workloads/docs-portal/docs/arquitectura/sesion-tmux-persistente.md

@@ -408,6 +408,14 @@ después del swap.
 | `docker restart tmux-host` (reinicio del NAS) | **No al toque, pero se auto-recupera solo** — el proceso `tmux server` muere con el contenedor; `healthcheck.sh` la recrea en el próximo ciclo (máx. 30 min) sin intervención, o `lab-session.sh` la crea al instante si alguien se reconecta antes | Sí, vía el volumen montado en `/root/.claude` | Sí, desde el 2026-09-20 — `--continue` retoma la conversación más reciente en `WORKDIR` (ver gotcha arriba) |
 | `docker rm` + recrear el contenedor desde cero | No, pero igual se auto-recupera sola (mismo mecanismo de arriba) | Sí, vía el mismo volumen — no hace falta volver a autenticar ni reconfirmar el diálogo de confianza del folder (ver el mount de `claude-code-home.json`) | Sí, mismo mecanismo — validado en vivo durante el swap de imagen del 2026-09-20 |
 | Falla de red real del host/NAS | N/A | N/A — `healthcheck.sh` la detecta y notifica, pero no la corrige (fuera de su alcance) | N/A |
+| Expiración del token OAuth de Claude Code | Sí — el proceso `claude` sigue vivo en el pane, pero muestra `Login expired` y Remote Control queda desconectado (`OAuth token unavailable`) | **No** — requiere `/login` manual (una vez alcanza: el volumen de credenciales es compartido) y después `/remote-control` en **cada** sesión ya abierta. Recrear el contenedor **no** lo arregla | Sí, una vez reautenticado — misma sesión, mismo proceso |
+
+!!! warning "Incidente relacionado"
+    La fila de expiración del token OAuth salió del
+    [incidente de la cadena de 4 fallos en `tmux-host` (2026-09-25/26)](../playbooks/incidente-tmux-host-cadena-fallos-2026-09-25.md).
+    El síntoma "no aparecen las sesiones remotas" llevó a eliminar el
+    contenedor, aunque la causa real era un token vencido. **Antes de
+    tocar el contenedor, mirá el pane de cada sesión.**
 
 ## Validación en vivo
 

workloads/docs-portal/docs/decisiones/0012-practica-multicloud-gcp-azure.md

@@ -1,9 +1,13 @@
 # ADR 0012 — Práctica multi-cloud: GCP y Azure DevOps en paralelo al lab ZimaOS
 
-**Estado:** aceptada — Fase 1 (Google Workspace) en ejecución en esta
-misma sesión; Fases 2-4 quedan documentadas como roadmap, explícitamente
-no implementadas hasta que se pidan en una sesión futura.
-**Fecha:** 2026-09-20
+**Estado:** aceptada — Fase 1 (Google Workspace) completa y verificada
+en vivo, con un giro real: el MCP self-hosted planeado
+(`taylorwilsdon/google_workspace_mcp`) quedó abandonado por un límite
+real de esa librería (ver §Fase 1), reemplazado por los Connectors
+nativos de claude.ai. Fases 2-4 quedan documentadas como roadmap,
+explícitamente no implementadas hasta que se pidan en una sesión
+futura.
+**Fecha:** 2026-09-20 (Fase 1 cerrada 2026-09-21)
 
 ## Contexto
 
@@ -36,7 +40,7 @@ empujan a abrir una segunda línea de práctica en paralelo:
   arquitectónica real, diagramas Mermaid, cifras verificadas en vivo o
   contra fuente primaria (no contra un blog de terceros sin
   corroborar — ver el caso del supuesto MCP "oficial" de Google
-  Workspace en la [Fase 1](#fase-1-ejecutar-en-esta-sesion-google-workspace)).
+  Workspace en la [Fase 1](#fase-1-ejecutada-google-workspace-con-un-giro-real-en-la-implementacion)).
 
 ## Diagrama del lab actual (ZimaOS)
 
@@ -194,20 +198,60 @@ Todas documentadas acá; **solo la Fase 1 se ejecuta en esta sesión.**
 Las Fases 2-4 no se implementan sin pedido explícito en una sesión
 futura — quedan como roadmap, no como trabajo en curso.
 
-### Fase 1 (ejecutar en esta sesión) — Google Workspace
+### Fase 1 (ejecutada) — Google Workspace, con un giro real en la implementación
 
-MCP de Google Workspace vía cuenta personal, para las iniciativas ya
-en curso. Detalle de la investigación previa a implementar (qué MCP
-usar, oficial vs comunitario) en la Parte 3 de esta conversación —
-resumen: **no existe un MCP oficial de Google Workspace** publicado
-por Google (se verificó explícitamente buscando en los GitHub
-`google`/`googleworkspace` oficiales — no aparece ninguno; un solo
-blog de terceros afirma que "ya existe uno oficial" sin que ninguna
-otra fuente lo corrobore, así que se descarta esa afirmación por no
-verificable). `taylorwilsdon/google_workspace_mcp` es la opción
-comunitaria más completa y activamente mantenida (120+ herramientas,
-OAuth 2.1, +2500 estrellas) — es la que se usa, etiquetada como
-comunitaria, no oficial.
+**Objetivo cumplido — acceso real a Google Calendar desde Claude,
+verificado en vivo — pero por un camino distinto al planeado
+originalmente.** Detalle de la investigación previa (qué MCP usar,
+oficial vs comunitario) — resumen: **no existe un MCP oficial de
+Google Workspace** publicado por Google (se verificó explícitamente
+buscando en los GitHub `google`/`googleworkspace` oficiales — no
+aparece ninguno; un solo blog de terceros afirma que "ya existe uno
+oficial" sin que ninguna otra fuente lo corrobore, así que se descarta
+esa afirmación por no verificable). Se optó por
+`taylorwilsdon/google_workspace_mcp` (comunitario, el más completo y
+activamente mantenido: 120+ herramientas, OAuth 2.1, +2500 estrellas)
+como primer intento, self-hosted dentro de `tmux-host`.
+
+**Ese self-hosted quedó abandonado — límite real encontrado en la
+librería, no un error de configuración.** El servidor usa FastMCP's
+`GoogleProvider`/`OAuthProxy`, que construye el `redirect_uri`
+enviado a Google directamente desde su propio `base_url` — **no**
+desde la variable `GOOGLE_OAUTH_REDIRECT_URI` que el proyecto expone
+(esa variable solo valida entradas, no arma la salida real; hallazgo
+confirmado leyendo el código fuente instalado, no la documentación
+pública). Y `base_url` es la misma variable de la que depende por
+default `issuer_url`, que el SDK de MCP exige sea HTTPS salvo que sea
+literalmente `localhost`/`127.0.0.1` (chequeo hardcodeado en
+`mcp/server/auth/routes.py:validate_issuer_url`, sin variable de
+entorno que lo salte). Resultado: **no hay combinación de variables
+de entorno que satisfaga a la vez** "el navegador del usuario debe
+poder llegar al callback" (necesita un dominio real, no `localhost`)
+y "el issuer debe ser HTTPS o `localhost`" — `workspace-mcp` no
+expone `issuer_url` por separado de `base_url` en su capa de
+configuración (confirmado en `core/server.py`: solo pasa `base_url` a
+`GoogleProvider(...)`).
+
+**Decisión del usuario ante ese límite:** en vez de armar un proxy
+HTTPS con certificado autofirmado (infraestructura extra, fricción de
+certificado no confiable en cada uso) o parchear el paquete instalado
+a mano (frágil, se pierde en cualquier reinstalación), se usaron los
+**Connectors nativos de claude.ai** (Google Calendar, vía el
+directorio de conectores de la cuenta, fuera de Claude Code por
+completo) — mismo resultado práctico (Claude con acceso real al
+calendario personal), infraestructura cero de nuestro lado, sin
+tocar código de terceros. Contrapartida real: es una integración de
+cuenta de claude.ai, no un MCP configurado dentro del proyecto
+`platform-multicloud` — no aparece como herramienta en sesiones de
+Claude Code (`lab`/`cloud-practice`), solo en el chat normal de
+claude.ai.
+
+**Verificado en vivo:** pregunta real en claude.ai normal ("¿qué
+tengo en el calendario esta semana?") devolvió una respuesta correcta
+revisando 3 calendarios reales de la cuenta (principal, Familia,
+festivos de Colombia) vía la herramienta `Google Calendar: Lists
+calendar events`, con razonamiento correcto sobre qué cuenta como
+"esta semana" dado el día/hora real de la consulta.
 
 ### Fase 2 (documentar, no ejecutar) — Terraform aislado
 

workloads/docs-portal/docs/decisiones/0013-iniciativas-clientes.md

@@ -0,0 +1,122 @@
+# ADR 0013 — Iniciativas de clientes: Google Apps Script y AppSheet
+
+**Estado:** aceptada — **fase prioritaria**, precede la reanudación de
+las Fases 2-4 del [ADR 0012](0012-practica-multicloud-gcp-azure.md).
+Scaffold del repo en curso; primeras iniciativas reales se agregan
+sesión a sesión, a medida que se comparten.
+**Fecha:** 2026-09-21
+
+## Contexto
+
+Iniciativas propias de la empresa (no del lab), trabajadas con **cuenta
+personal de Google** — dos herramientas concretas: **Google Apps
+Script** (código, automatizaciones) y **Google AppSheet** (apps
+no-code sobre Sheets). Se abre como fase separada del ADR 0012 y con
+prioridad sobre él por decisión explícita: retomar las Fases 2-4 del
+lab (Terraform, Azure DevOps, GKE) espera a que esto avance primero.
+
+**Restricción dura, no negociable:** ningún repo ni documento de esta
+iniciativa contiene credenciales, datos ni información real de
+cliente. Apps Script versiona código (lógica), nunca datos. AppSheet
+no tiene export de código — solo se documenta desde afuera (tablas,
+columnas, expresiones, capturas), nunca se copian datos reales de
+ninguna hoja de cálculo al repo.
+
+## Opciones consideradas
+
+### Apps Script: MCP vs. `clasp`
+
+| Opción | A favor | En contra |
+|---|---|---|
+| MCP para Apps Script | Interacción conversacional directa | **No existe un MCP oficial de Google.** Se verificó explícitamente buscando — solo hay servidores comunitarios (`mohalmah/google-appscript-mcp-server`, `whichguy/gas_mcp`, entre otros), ninguno publicado por Google. Se descartan sin evaluar más a fondo: no hay necesidad de agregar una dependencia comunitaria no verificada cuando existe una CLI oficial que cubre el caso de uso completo. |
+| **`clasp`** (elegido) | CLI oficial de Google (`@google/clasp`), mantenida por el equipo de Apps Script, cubre push/pull/login/versiones/despliegues | Requiere login interactivo (OAuth) — mitigado: el login lo corre el dueño de la cuenta, nunca se comparte el código de autorización |
+
+### AppSheet: qué se puede versionar
+
+Se verificó contra la documentación oficial vigente (no se asumió):
+**AppSheet no expone ningún mecanismo de export de la definición de la
+app** (tablas virtuales, vistas, expresiones, automatizaciones) hacia
+un formato versionable con git. La única superficie exportable es la
+app en sí vía la consola de AppSheet, no un artefacto de código. Existe
+un addon de terceros ("App Script Saver") pero es específico de Apps
+Script, no de AppSheet, y no se evaluó como parte de esta decisión
+(mismo criterio que con los MCP: no se instala nada de terceros sin
+pasar primero por la verificación de publicador/permisos ya establecida
+en el lab).
+
+**Decisión sobre AppSheet:** no se intenta versionar la app —se
+documenta desde afuera. La documentación (markdown + capturas) es la
+única fuente versionada; la app real en la consola de AppSheet sigue
+siendo la fuente de verdad operativa, con el riesgo explícito de que
+la documentación quede desactualizada (ver Consecuencias).
+
+## Decisión
+
+Repo privado nuevo `client-initiatives` en Gitea (separado de
+`apps-registry`/`platform-infra`/`scripts`/`platform-multicloud` — ni
+lab GitOps ni práctica multi-cloud, es su propia categoría). Estructura:
+una carpeta por iniciativa bajo `apps-script/` (proyecto `clasp`
+completo, con su propio `.clasp.json`) o `appsheet/` (documentación +
+plantilla de estructura vacía). Mismo criterio de versionado semántico
+y modularidad que ya usa `docs-portal`.
+
+**Flujo Apps Script:** rama `fix/*` → diff mostrado → `merge --no-ff`
+a `main`. `clasp push` (subir el código a Google) es una confirmación
+explícita **aparte**, nunca agrupada con el merge a git — son dos
+sistemas de versionado distintos (git para el repo, Apps Script para
+las versiones desplegadas) y no deben confundirse.
+
+**Gitleaks:** se agrega al pipeline del repo nuevo. Nota real
+encontrada al planificar esto: Gitleaks hoy solo corre en
+`apps-registry` (3 workflows) — `platform-infra` y `scripts` no tienen
+Gitea Actions configurado en absoluto, no hay "los otros tres repos con
+Gitleaks" como se asumió al principio. Se replica el step exacto que
+ya usa `apps-registry` (Gitleaks v8.21.2, `--no-git --redact`, reporte
+JSON) por ser el único precedente real en el lab.
+
+## Fases
+
+### Fase A — Google Apps Script
+
+1. Scaffold del repo `client-initiatives` (estructura, Gitleaks,
+   convenciones documentadas).
+2. Login de `clasp` (`clasp login --no-localhost`) corrido por el
+   dueño de la cuenta — verificación posterior de que
+   `~/.clasprc.json` queda fuera de cualquier repo y con `chmod 600`.
+3. Primeras iniciativas: pendientes de compartir, se agregan una por
+   una bajo `apps-script/<slug>/` a medida que llegan.
+
+### Fase B — Google AppSheet
+
+1. Por cada app existente: documentar tablas, columnas y expresiones
+   en markdown, más capturas del estado actual, bajo
+   `appsheet/<slug>/`.
+2. Plantilla de estructura de datos vacía si aplica (schema, nunca
+   filas reales).
+3. Limitación dejada explícita en cada README de iniciativa: sin diff
+   automático posible entre esta doc y la app real.
+
+## En pausa mientras esta fase esté activa
+
+Por decisión explícita del usuario, prioridad sobre lo ya documentado
+en el ADR 0012 y el resto del lab:
+
+- **Swap de `tmux-host`** — no se corre en esta fase.
+- **[Fase 4 del ADR 0012](0012-practica-multicloud-gcp-azure.md#fase-4-documentar-no-ejecutar-gke-real-con-spot-auto-apagado)**
+  (GKE real con Spot + auto-apagado) — sigue solo documentada.
+- **Prueba del skill `frontend-design`** (pendiente desde la
+  instalación de plugins del 2026-09-20) — no se ejecuta.
+
+Tampoco se toca NPM, `cloudflared`, ni `lab-agent` durante esta fase.
+
+## Consecuencias
+
+- Se gana un espacio versionado y auditado (Gitleaks) para
+  automatizaciones reales de la empresa, sin mezclar nada con el lab
+  GitOps ni con la práctica multi-cloud.
+- Se acepta como deuda consciente que la documentación de AppSheet
+  puede desincronizarse de la app real — no hay forma técnica de
+  evitarlo, solo disciplina de actualizarla.
+- Revertir esta decisión implicaría: eliminar el repo
+  `client-initiatives` (las iniciativas seguirían existiendo en Google,
+  solo se perdería el historial versionado y la documentación externa).

workloads/docs-portal/docs/playbooks/incidente-tmux-host-cadena-fallos-2026-09-25.md

@@ -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.

workloads/docs-portal/mkdocs.yml

@@ -101,6 +101,7 @@ nav:
       - "0010 · Pago y envío reales": decisiones/0010-pago-envio-reales-y-storefront.md
       - "0011 · Ambiente de Staging": decisiones/0011-ambiente-staging.md
       - "0012 · Práctica multi-cloud GCP/Azure": decisiones/0012-practica-multicloud-gcp-azure.md
+      - "0013 · Iniciativas de clientes": decisiones/0013-iniciativas-clientes.md
       - Plantilla ADR: decisiones/plantilla-adr.md
   - Playbooks:
       - Crashloop Medusa: playbooks/incidente-crashloop-medusa.md
@@ -113,6 +114,7 @@ nav:
       - Realm HTTP y Cosign: playbooks/incidente-cosign-realm-http-tunnel-2026-08.md
       - Contención de recursos Gitea/runner: playbooks/incidente-contencion-recursos-gitea-runner-2026-08.md
       - Blackhole MTU cross-node: playbooks/incidente-mtu-blackhole-cross-node-2026-08.md
+      - "Cadena de fallos tmux-host": playbooks/incidente-tmux-host-cadena-fallos-2026-09-25.md
       - "Migración a platform-templates": playbooks/migracion-platform-templates-2026-08.md
   - Aprendizajes:
       - Notas sueltas: aprendizajes/notas-sueltas.md

workloads/docs-portal/patches/deployment.yaml

@@ -25,7 +25,7 @@ spec:
         runAsNonRoot: false
       containers:
         - name: app
-          image: gitea.cruzcloud.net/devops/docs-portal:v1.0.276
+          image: gitea.cruzcloud.net/devops/docs-portal:v1.0.280
           # El base saca TODAS las capabilities. Probado en vivo y
           # revertido: con drop: ALL (aunque se agregue NET_BIND_SERVICE
           # de vuelta) el propio entrypoint de nginx:1.27-alpine falla al