🌱 Empieza aquí · Método guardián anti-suspensión por sesión

¿Alguna vez dejaste a tu asistente en una tarea larga o en una corrida de noche, te fuiste un rato, y volviste a encontrar la computadora dormida y el trabajo congelado a la mitad? Esta semilla resuelve justo eso, y lo hace de una forma que no te trae sorpresas: la máquina se mantiene despierta solo mientras la sesión trabaja, y en cuanto termina, vuelve sola a su ahorro de energía de siempre.

Qué es esto (por qué → qué → cómo)

• Por qué: la protección anti-suspensión que muchos asistentes traen de fábrica es breve y con temporizador; en esperas largas (una API que tarda, un tramo sin actividad) se le acaba la cuerda y la máquina se duerme a media chamba.
• Qué: un método con cuatro reglas de diseño para mantener la máquina despierta atando la vigilia a la vida del proceso de la sesión (no a un temporizador), más una implementación de referencia para macOS lista para usar.
• Cómo: se instala como un enganche que se dispara al iniciar cada sesión. De ahí en adelante, no tocas nada.

A diferencia de instalar unos scripts a secas, esta semilla te entrega el razonamiento del método (las cuatro reglas y el porqué de cada una), para que sepas exactamente qué hace, qué NO hace, y puedas confiar en ello. Las reglas en una línea cada una:

1. Se arma al iniciar la sesión y se ata a la vida del proceso, no a un temporizador.
2. Muere solo cuando la sesión termina (cero procesos huérfanos).
3. La suspensión manual siempre gana (cerrar la tapa duerme la máquina; tú mandas).
4. El apagado es por sesión y respeta a otras sesiones que sigan trabajando.

Para ti (el humano)

Solo tienes que decir una frase. Abre esta carpeta con tu asistente (Claude Code o Cowork) y escríbele:

"Siembra esta semilla 🌱"

¿Otras formas de pedirlo? "instala esta semilla", "haz el setup de esto", "ponme esto a funcionar". Te entiende igual. De aquí en adelante tu asistente hace toda la parte técnica; tú no tocas nada. Vas a ver algunas palabras en inglés en la pantalla; ni caso, él te guía.

Para el asistente que siembra 🤖

Este componente es un workflow (un método de trabajo) que trae, además del método, una implementación de referencia para macOS: dos scripts de shell que se enganchan en el "inicio de sesión". En Windows o Linux los scripts se instalan igual pero salen sin efecto y sin daño (caffeinate solo existe en macOS).

Los placeholders entre <...> los resuelves tú según la plataforma del humano:

• <RUTA-DE-HOOKS> → carpeta donde viven los scripts de enganche del asistente.
  • Claude Code: ~/.claude/hooks/ (recomendado; aplica a todas las sesiones).
  • Cowork: la carpeta de configuración equivalente (~/.claude/hooks/ si comparte el mismo directorio de config).
• <ARCHIVO-DE-SETTINGS> → el archivo settings.json del asistente.
  • Claude Code (usuario): ~/.claude/settings.json.
  • Por proyecto: .claude/settings.json dentro del proyecto.

¿Codex? Codex no tiene enganche de "inicio de sesión", así que el armado automático (pasos 3 y 4) no aplica. Haz igual los pasos 1 y 2 (deja el método a la mano y copia los scripts) y corre arma-guardian.sh a mano al empezar una corrida larga; el método sigue siendo válido y el apagado natural (regla 2) funciona igual. Si el proceso de Codex no se llama claude, ajusta el case de ambos scripts (ver Troubleshooting).

1 · (Recomendado) Deja el método a la mano

El corazón de esta semilla es kernel/guardian-anti-sleep.md: el método con sus cuatro reglas de diseño. Guárdalo como referencia (por ejemplo, en la carpeta de reglas o de documentación del asistente) para saber siempre qué garantiza el guardián y qué no. No es obligatorio para que la automatización funcione, pero es lo que hace que confíes en ella.

2 · Copia los dos scripts de referencia

Están en kernel/referencia/. Cópialos a <RUTA-DE-HOOKS> y dales permisos:

mkdir -p <RUTA-DE-HOOKS>
cp kernel/referencia/arma-guardian.sh kernel/referencia/apaga-guardian.sh <RUTA-DE-HOOKS>/
chmod +x <RUTA-DE-HOOKS>/arma-guardian.sh <RUTA-DE-HOOKS>/apaga-guardian.sh

3 · Engancha el armado al inicio de sesión

Abre <ARCHIVO-DE-SETTINGS>. Si ya tiene una sección hooks, fusiona este bloque sin borrar lo que exista (agrega tu entrada al arreglo SessionStart, no lo reemplaces). Si el archivo no existe, créalo con este contenido:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "<RUTA-DE-HOOKS>/arma-guardian.sh" }
        ]
      }
    ]
  }
}

4 · El apagado queda como comando a la mano

apaga-guardian.sh NO se engancha como inicio de sesión. Es el comando que corres cuando el humano quiera devolverle a la máquina su energía normal sin cerrar la sesión ("apaga el guardián", "deja que la compu duerma"). No es obligatorio: por la regla 2, el guardián se apaga solo al terminar la sesión.

Opcional (integración de cierre): si tu asistente tiene un enganche de "fin de sesión" (SessionEnd) o una rutina de cierre, llama ahí a apaga-guardian.sh con el mismo formato del paso 3 pero con la clave "SessionEnd". Así el apagado por sesión (regla 4) queda cableado a tu cierre. Repito: no es necesario para que funcione.

5 · Verificación post-siembra (obligatoria)

Ejecuta esto desde la terminal de tu asistente (corres dentro del proceso de la sesión, así que el guardián encontrará su ancestro):

bash <RUTA-DE-HOOKS>/arma-guardian.sh; sleep 1; pgrep -fl "caffeinate -i -w"

Salida esperada en macOS: una línea con un proceso caffeinate atado al PID de TU sesión, por ejemplo (si aparecen varias líneas, las demás son guardianes de otras sesiones activas; identifica el tuyo comparando el número final con el PID ancestro de tu propia sesión):

57321 caffeinate -i -w 57000

Si ves esa línea, el guardián quedó armado. ✅

• Si no imprime nada en macOS: revisa que copiaste bien los scripts y que corres el comando desde la terminal del asistente (no una terminal suelta).
• En Windows o Linux: el script sale sin efecto y pgrep no devuelve nada. Eso es lo correcto: la implementación de referencia solo actúa en macOS.

Prueba también el apagado por sesión y confirma su mensaje:

bash <RUTA-DE-HOOKS>/apaga-guardian.sh

Salida esperada: Guardián de esta sesión (proceso <PID>) apagado. seguido del censo de guardianes restantes.

Cuando ambos comandos den la salida esperada, la siembra está completa. Reporta al humano en una línea, sin tecnicismos.

✅ ¿Cómo sé que funcionó? (para el humano)

Fácil: pon a tu asistente en una tarea larga, deja la computadora sola un rato y regresa. Ya no debería estar dormida ni con el trabajo congelado a la mitad. Cuando cierres la sesión (o le pidas "apaga el guardián"), tu máquina vuelve a dormir con normalidad. Y ojo: cerrar la tapa siempre la duerme al instante, eso no cambia. Tú mandas. 🌱

Troubleshooting

• "Sigue durmiéndose de noche." ¿La tapa está cerrada y en batería? Ese caso lo fuerza el sistema operativo y ningún guardián lo evita. Deja la tapa abierta (puedes bajar el brillo a cero y bloquear la pantalla; eso no mata procesos).
• "No aparece el proceso caffeinate." Corre la verificación desde la terminal del propio asistente, no desde una terminal aparte: el guardián busca su proceso ancestro y necesita colgar de él.
• "Tengo varias sesiones y apagué una." Es correcto que las demás sigan con su guardián. Por diseño (regla 4), apagar una jamás desprotege a las otras.
• "Mi asistente corre con otro nombre de proceso." Ajusta el case de ambos scripts (claude|*/claude) al nombre real del proceso de tu asistente.