Solución de problemas

Empieza por las versiones y el estado de la sesión:

herdr -V
herdr status

Anota también tu sistema operativo, el nombre y la versión de la terminal exterior, si la sesión es local o remota, y si hay tmux de por medio.

La ventana del IME CJK está mal colocada o el cursor parpadea en Windows

Herdr usa por defecto un cursor pintado por celda en Windows nativo y en WSL, porque los cursores nativos pueden parpadear, saltar o mostrar posiciones atrasadas mientras los multiplexores basados en ConPTY repintan la pantalla. Un cursor pintado por celda no puede aportar el anclaje de cursor nativo que usa la interfaz de composición de los IME coreano, japonés y chino.

Si la ventana de composición o de candidatos del IME aparece en el sitio equivocado, activa el cursor nativo:

[ui]
host_cursor = "native"

El modo nativo recupera el anclaje del IME, pero puede reintroducir algún movimiento extraño del cursor mientras hay salida activa. Vuelve al cursor visualmente estable con host_cursor = "drawn", o quita el ajuste para usar el valor por defecto de Windows. Mira Windows para la limitación actual.

Intro, Tab o Retroceso se disparan dos veces

Las versiones antiguas de algunas terminales pueden emitir la liberación de Intro, Tab y Retroceso con los mismos bytes que la pulsación cuando una aplicación activa el informe de eventos de teclado de Kitty. Herdr no puede distinguir esos bytes duplicados una vez que la terminal los envía.

Actualiza la terminal exterior a una versión que incluya la corrección:

Terminal	Versión mínima corregida
kitty	0.33.0
foot	1.20.0
Alacritty	0.15.0

Es especialmente habitual con los paquetes de terminal antiguos de las distribuciones Linux de soporte extendido. Mira la incidencia #1116 de Herdr para las capturas confirmadas y las referencias de cada terminal. Si el problema persiste con una versión actual, informa de la versión exacta de la terminal y de si también ocurre fuera de Herdr.

Opción+Izquierda u Opción+Derecha insertan `;3D` o `;3C`

Las terminales suelen enviar Alt+Izquierda y Alt+Derecha como las secuencias estándar de flecha con modificador ESC[1;3D y ESC[1;3C. En macOS, primero hay que configurar la terminal exterior para que trate Opción como Alt. Si el shell no tiene asignadas esas secuencias, zsh puede mostrar los caracteres restantes como ;3D o ;3C. Ocurre con kitty, Alacritty y otras terminales; tanto Herdr como tmux conservan la entrada original de flecha con modificador.

Añade asignaciones explícitas en zsh si quieres que las flechas con modificador naveguen por palabras en cualquier terminal y shell anidado:

bindkey $'\e[1;3D' backward-word
bindkey $'\e[1;3C' forward-word

Kitty puede parecer que se comporta distinto fuera de Herdr porque su integración automática con zsh añade esas asignaciones solo a los shells que arranca kitty directamente, no a los creados por multiplexores de terminal. Sigue las instrucciones de integración manual con el shell de kitty, o asigna las teclas en kitty.conf antes de que lleguen al shell:

map alt+left send_text all \x1bb
map alt+right send_text all \x1bf

Herdr no reescribe a propósito las flechas con modificador, porque las aplicaciones de terminal pueden usar Alt+Izquierda y Alt+Derecha directamente. Mira la incidencia #1370 de Herdr para la investigación.

Herdr se ha actualizado, pero la sesión en marcha sigue siendo la antigua

Actualizar el binario no reemplaza un servidor compatible que ya está en marcha. Vuelve a arrancar Herdr para usar el cliente actualizado. Si además necesitas los cambios del lado del servidor de esa versión, comprueba herdr status, para la sesión y lanza Herdr de nuevo:

herdr server stop
herdr

Parar un servidor termina los procesos de sus paneles. Las sesiones con nombre usan herdr session stop <nombre>. Mira Instalar Herdr para el comportamiento del actualizador, de los gestores de paquetes y del traspaso en caliente.

Las herramientas que usan el llavero fallan dentro de Herdr en macOS

Comprueba el contexto de lanzamiento del servidor desde un panel de Herdr:

launchctl managername

Background es normal en los servidores de macOS arrancados automáticamente y no indica por sí solo un problema con el llavero. Si falla el acceso al llavero y el servidor se arrancó por SSH o desde un trabajo en segundo plano, páralo y vuelve a arrancar Herdr desde una terminal gráfica normal:

herdr server stop
herdr

Parar el servidor termina los procesos de sus paneles. Los paneles de Herdr heredan el contexto de lanzamiento de macOS del servidor de larga duración, así que un servidor arrancado por SSH o desde un trabajo en segundo plano puede no tener acceso a los servicios interactivos del llavero. Mira la incidencia #966 de Herdr para los detalles.

SSH o DNS fallan tras cerrar sesión en macOS

Los servidores de macOS arrancados automáticamente usan un contexto de servicio por usuario, para que cerrar sesión no deje sus paneles con una conexión muerta a los servicios de macOS. Los lanzamientos explícitos con herdr server conservan el contexto de quien los llama.

Un servidor antiguo puede sobrevivir al cierre de sesión perdiendo la resolución de usuarios y el DNS. Los síntomas incluyen No user exists for uid 501, Could not get manager name. y curl: (6) Could not resolve host. Volver a iniciar sesión no repara ese servidor. Para la sesión afectada y arranca Herdr desde una terminal gráfica en la sesión nueva. Esto termina los procesos vivos de los paneles, pero restaura la disposición guardada. El traspaso en caliente conserva el contexto de servicio del servidor de origen y sus procesos de panel; por eso los servidores antiguos necesitan un reinicio completo de la sesión para adoptar esta corrección, y el traspaso no puede reparar su contexto heredado.

Si un servidor recién arrancado sigue teniendo este problema, busca could not select persistent user service context en herdr-server.log. Herdr conserva el contexto heredado si las API de macOS necesarias no están disponibles. Mira la incidencia #4100 de Herdr.

No se encuentra el comando `herdr`

Reinicia la terminal para que recargue su entorno, y confirma que el directorio de instalación de Herdr está en el PATH. En las instalaciones por gestor de paquetes, usa ese gestor para actualizar Herdr y exponerlo en el PATH. Mira Instalar Herdr.

Un atajo directo no hace nada

El sistema operativo o la terminal exterior pueden consumir la combinación antes de que Herdr la reciba. Libera la combinación en esa capa o elige otro atajo. Mira Teclado para los conflictos conocidos y los valores seguros.

La conexión remota no consigue autenticarse

Confirma primero que OpenSSH funciona con normalidad con ssh <host>. Para una clave protegida con contraseña en un shell no interactivo, una tarea de CI o una terminal móvil, carga la clave en ssh-agent antes de arrancar la conexión remota. Mira Persistencia y acceso remoto.

Dónde están los registros de diagnóstico

Los registros de Herdr están por defecto en ~/.config/herdr/:

herdr.log
herdr-client.log
herdr-server.log

Define HERDR_LOG=herdr=debug para más detalle. Cuando informes de un problema, incluye el registro actual y los rotados. Mira Configuración.