Estado de la sesión y restauración

Herdr usa varias vías de estado según la situación.

Qué sobrevive

Caso	Los procesos siguen	Vuelve la disposición	Vuelve la pantalla reciente	Se reanuda la conversación del agente
Desconectar y volver a conectar	Sí	Sí	Sí, desde la terminal viva	Sí, porque el proceso nunca paró
Reinicio del servidor	No	Sí	Solo con historial de pantalla del panel	Solo con restauración nativa de la sesión del agente
Actualización sin --handoff	Los servidores compatibles siguen; los que requieren reinicio pueden necesitar parar y arrancar	Sí, tras el reinicio	Solo con historial de pantalla del panel	Solo con restauración nativa de la sesión del agente
Actualización con --handoff	Mejor esfuerzo en los servidores compatibles en marcha	Sí	Sí, desde la terminal viva si el traspaso funciona	Sí, porque el proceso sigue en marcha si el traspaso funciona

Persistencia en vivo

Desconectarse con normalidad deja el servidor de Herdr en marcha. Los paneles, shells, agentes, servidores, pruebas y procesos de comandos siguen ejecutándose dentro de ese servidor.

Desconecta el cliente con ctrl+b q. Vuelve a conectarte más tarde:

herdr

Es la vía de persistencia más sólida, porque los procesos originales nunca se detienen.

Restauración desde instantánea

Si el servidor de Herdr se para y vuelve a arrancar, los procesos originales de los paneles ya no existen. Herdr restaura la forma guardada de la sesión: espacios de trabajo, pestañas, paneles, directorio de trabajo, disposición y foco.

La restauración desde instantánea no conserva shells, servidores, pruebas ni procesos arbitrarios en marcha. Los paneles que no puedan usar una vía de restauración más fuerte vuelven como shells nuevos en su directorio guardado.

Si un directorio guardado no está disponible o el shell no arranca, el panel se queda en la disposición con un error en vez de desaparecer o irse a tu directorio personal. Su directorio guardado y su referencia de sesión de agente se conservan. Arregla el directorio o la configuración del shell y reinicia el servidor para reintentarlo, o cierra el panel expresamente para quitarlo.

Al guardar, Herdr prefiere el directorio del shell vivo cuando el sistema operativo lo expone, y conserva el último directorio confirmado después de que el shell termine. En otras plataformas, el respaldo es el directorio que informa el propio shell.

Si session.json no se puede leer o analizar, o requiere una versión más nueva de Herdr, Herdr registra por qué ha fallado la carga. Antes de guardar o vaciar la sesión de reemplazo, conserva los bytes originales en session-backups/, junto a session.json, y registra la ruta de recuperación como persist.backup. Un fichero que falte al arrancar se vuelve a comprobar antes del primer guardado o vaciado. Estas copias de recuperación por fallo de carga son independientes del historial normal de instantáneas.

Herdr conserva las tres copias de recuperación más recientes y solo elimina las antiguas después de escribir con éxito una nueva. Si la conservación falla, el guardado automático y el apagado dejan el original intacto y registran el fallo; se reintenta en el siguiente guardado. Las copias nunca se restauran automáticamente. Para recuperar una, para el servidor afectado, copia el fichero de recuperación sobre su session.json y reinicia. Las copias de recuperación no incluyen el historial de pantalla de los paneles.

Apagado y recuperación de instantáneas

En sistemas Linux con systemd-logind, Herdr escucha el aviso de apagado del host y pide un pequeño retraso mientras guarda y se detiene. Ocurre antes de que logind continúe con el apagado. El sistema operativo limita ese retraso; Herdr no bloquea el apagado indefinidamente. Esta protección no está disponible sin logind y no cubre un apagado forzado, un corte de luz ni procesos matados antes de que llegue el aviso.

Además, en todas las plataformas, Herdr guarda hasta 48 instantáneas de la disposición en session-snapshots/, junto a session.json. La primera disposición guardada se copia de inmediato. Los guardados o vaciados posteriores pueden añadir una instantánea de la disposición anterior, como mucho una cada 15 minutos. Las instantáneas sin cambios no se duplican. El intervalo sobrevive a los reinicios del servidor, así que una ráfaga de cierres de paneles o reinicios no puede rotar todas las disposiciones antiguas. Los cambios recientes pueden no estar en las instantáneas de recuperación.

Los cierres normales de paneles siguen actualizando session.json. No hay avisos de recuperación ni restauración automática de instantáneas antiguas. Para recuperar una disposición:

1. Localiza el directorio de la sesión afectada con herdr session list --json.
2. Para ese servidor (herdr server stop para la sesión por defecto, o herdr session stop <nombre> para una sesión con nombre).
3. Guarda una copia de su session.json actual y copia el fichero elegido de session-snapshots/ sobre session.json. La fecha de modificación de cada fichero indica cuándo se tomó la instantánea.
4. Arranca la sesión de nuevo.

Las instantáneas contienen la disposición y las referencias de sesión de los agentes, no procesos en marcha ni historial de pantalla. Trátalas como datos privados de la sesión. Un fallo al escribir una instantánea se registra, pero no impide que se guarde la sesión principal.

Reproducción del historial de pantalla

El historial de pantalla de los paneles restaura el contenido reciente de la terminal después de un reinicio completo del servidor, sin restaurar el proceso antiguo.

Está desactivado por defecto, porque la salida de un panel puede contener secretos, tokens, prompts y salidas de comandos. Actívalo en el fichero de configuración:

[experimental]
pane_history = true

Cuando está activo, Herdr guarda el historial en session-history.json, junto a session.json. Trata el directorio de configuración y sesión de Herdr como si fuera el historial de la terminal.

El historial solo se reproduce cuando coincide exactamente con la disposición guardada. El historial de una disposición distinta, incluida la que queda tras una recuperación manual de instantánea, se ignora. Los ficheros de historial antiguos sin verificación de disposición también se ignoran; el historial que se guarde a partir de ahora podrá reproducirse en el siguiente reinicio.

Restauración nativa de la sesión del agente

Algunos agentes pueden reanudar sus propias conversaciones. Herdr puede usar las referencias de sesión informadas por las integraciones oficiales para reiniciar los paneles de agentes compatibles después de un reinicio del servidor.

La restauración nativa está activada por defecto. Desactívala con:

[session]
resume_agents_on_restore = false

Herdr solo reanuda los paneles que informaron de una referencia de sesión nativa a través de una integración oficial actual.

Después de que un cliente se conecte y proporcione el tamaño de la terminal y el tema, Herdr reanuda los paneles de agente restaurados en todos los espacios de trabajo y pestañas, sin esperar a que cada panel reciba el foco.

La restauración nativa requiere estas versiones de integración de Herdr, o más recientes:

Agente	Versión mínima de la integración	Comando de reanudación
Pi	2	pi --session <ruta-o-id>
Antigravity CLI	1	agy --conversation <id>
OMP	3	omp --resume=<ruta-o-id>
Claude Code	6	claude --resume <id>
Codex	5	codex resume <id>
Cursor Agent CLI	1	cursor-agent --resume <id>
Grok CLI	2	grok --resume <id>
GitHub Copilot CLI	2	copilot --resume=<id>
Devin CLI	2	devin --resume <id>
Droid	2	droid --resume <id>
Kimi Code CLI	3	kimi --session <id>
Qoder CLI	2	qodercli --resume <id>
Qwen Code	1	qwen --resume <id>
Letta Code	1	letta --conversation <id>, o letta --conversation default --agent <agent-id> para default:<agent-id>
OpenCode	5	opencode --session <id>
Kilo Code CLI	1	kilo --session <id>
Hermes Agent	2	hermes --resume <id>
MastraCode	1	mastracode --thread <id>

Ejecuta herdr integration status para ver las versiones instaladas. Reinstala las desactualizadas con herdr integration install <agente>.

Las referencias de sesión no compatibles, ausentes, no válidas, duplicadas u obsoletas se restauran como shells normales en el directorio guardado del panel.

Si a un panel se le aplica la restauración nativa, Herdr reanuda la sesión del agente en vez de reproducir el historial de pantalla guardado de ese panel.

Traspaso en caliente

El traspaso en caliente sirve para los flujos de actualización y de conexión remota que necesitan reemplazar un servidor de Herdr en marcha. Pide al servidor antiguo que transfiera los paneles vivos al nuevo, de modo que los procesos de los paneles sigan ejecutándose durante el reemplazo.

A diferencia de la restauración desde instantánea, la reproducción del historial y la restauración nativa de agentes, el traspaso intenta mantener vivos los procesos actuales en lugar de reconstruir el estado después de que el servidor antiguo pare.

Un traspaso correcto conserva el estado de sesión duradero que gestiona el servidor: los PTY y procesos de los paneles, la identidad y los metadatos duraderos de los agentes, y el estado de plugins y sesión que necesita el servidor de reemplazo. No conserva la coordinación transitoria a través del cambio: las peticiones de CLI o API en curso, las esperas, los flujos de suscripción, los sockets de cliente y los mensajes entre paneles pueden interrumpirse; los clientes deben reconectarse y reintentarlos.

Los servidores Unix actualizados pueden enviar más de 64 paneles en un traspaso, transfiriéndolos por lotes. El servidor emisor ya debe incluir ese soporte: un servidor antiguo en marcha sigue aplicando su límite de 64 paneles en la primera actualización. Ese límite puede exigir un reinicio normal del servidor, que termina los procesos de los paneles. Los lotes no cambian el orden de instalación de la actualización ni eliminan otros requisitos de compatibilidad del traspaso.

El traspaso en caliente es experimental y opcional:

herdr update --handoff
herdr --remote workbox --handoff

herdr update a secas instala el cliente nuevo y deja en marcha los servidores de generación 1 de puntos de acceso. herdr --remote workbox a secas también deja en marcha un servidor remoto compatible aunque las versiones difieran. Solo hace falta parar en la actualización única desde un servidor anterior a la generación 1; usa --handoff cuando quieras reemplazar expresamente un servidor compatible en marcha sin perder los procesos de sus paneles.

herdr update --handoff solo se aplica a las instalaciones gestionadas por el actualizador de Herdr. Las de Homebrew, mise y Nix se actualizan con su gestor de paquetes, así que en ellas herdr update está desactivado y no puede hacer traspaso en caliente.