# Notas para agentes que trabajan en este cluster

Este es el directorio de trabajo de **Hermes** (el agente de Telegram) y de
cualquier sesión de Claude Code sobre el homelab. Aquí van solo las cosas que
**engañan al mirarlas**: lo que parece una avería y no lo es, y lo que parece
inofensivo y no lo es. Lo demás está en el skill `k8s-infra`.

## n8n: las ejecuciones «running» que nunca terminan NO están colgadas

Desde el **2026-07-30** el deployment lleva `EXECUTIONS_DATA_SAVE_ON_SUCCESS=none`.
Cuando un workflow sale **bien**, n8n crea igualmente la fila en
`execution_entity`, le pone `deletedAt` al instante y **no actualiza el estado**,
porque la va a tirar. El barrido duro se las lleva cada ~15 min.

O sea que `SELECT ... FROM execution_entity` enseña filas con
`status='running'` y `stoppedAt=NULL` que son **ejecuciones exitosas ya
borradas**. No hay nada que arreglar. Ya provocó un diagnóstico en falso el
mismo día que se puso.

Para saber si un workflow corre de verdad, mirar **`workflow_statistics`**:

```sql
SELECT name, count FROM workflow_statistics WHERE workflowId='<id>';
-- production_success sube en cada vuelta aunque la ejecución no se guarde
```

Sale también en `deletedAt IS NOT NULL`. Y ojo: `startedAt` y `deletedAt` no
llevan el mismo huso, así que restarlas no significa nada.

## n8n: lo que se ejecuta es la versión PUBLICADA, no el borrador

`workflow_entity.nodes` es el **borrador**. Producción usa la versión de
`workflow_history` apuntada por `workflow_entity.activeVersionId`. Editar
`nodes` a mano y reiniciar **no cambia nada y no da ningún error**. La API
pública (`PUT /api/v1/workflows/{id}`) sí publica; parcheando SQLite hay que
escribir en las dos tablas.

Diagnóstico rápido: comparar las dos columnas. Si difieren, lo que corre no es
lo que estás leyendo.

## Antes de tocar una BD de un pod: desarmar ArgoCD

Casi todo está bajo Applications con `automated{selfHeal,prune}`. Un
`kubectl scale --replicas=0` para hacer un `VACUUM` se revierte solo a mitad.

```sh
kubectl -n argocd patch app <app> --type json \
  -p '[{"op":"remove","path":"/spec/syncPolicy/automated"}]'
# ... trabajo ...
kubectl -n argocd patch app <app> --type merge \
  -p '{"spec":{"syncPolicy":{"automated":{"prune":true,"selfHeal":true}}}}'
```

Rearmarlo al final levanta el pod y aplica la config nueva de una vez.

## ArgoCD: una Application de directorio se traga los `.json`

`path: n8n` incluye `*.yaml`, `*.yml` **y `*.json`** como manifiestos. Un JSON
que no sea un objeto de Kubernetes deja la app en `ComparisonError` («Object
'Kind' is missing»). Por eso `application-n8n.yaml` tiene
`directory.exclude: "workflow-*.json"`. Los `.md` no se parsean: este fichero es
seguro.

## El auto-reinicio de Uptime Kuma sí funciona (desde 2026-07-30) y va cerrado

Kuma cae → notificación «n8n Auto-Restart» → webhook público de n8n → PATCH del
`restartedAt`. Antes no reiniciaba nada (sin RBAC: 403), y sus «éxitos» eran el
aviso de FALLO enviándose bien.

- La SA es `n8n-restarter`, con **un RoleBinding por namespace** (ver
  `n8n/rbac-restarter.yaml`). Si añades un servicio al `SERVICE_MAP` del
  workflow, hace falta también su RoleBinding o dará 403.
- La clave del mapa es el **nombre exacto del monitor en Kuma**. Renombrarlo
  allí lo desconecta en silencio.
- El webhook exige la cabecera `X-Kuma-Token` (secret `n8n-kuma-webhook`, fuera
  de git). Sin secreto configurado la comprobación se salta a propósito, para
  que un despiste no te deje sin avisos.
- Para apps bajo ArgoCD, el `restartedAt` se **revierte** tras el reinicio. El
  pod sí se reinicia; la anotación no queda. No es un fallo.

## Un workflow que termina en verde no dice que haya hecho su trabajo

Vale para n8n y para cualquier automatismo de aquí: comprobar el **efecto**
(que el `restartedAt` cambió, que el pod es nuevo, que el fichero está), no el
código de salida ni el contador de éxitos.