Solución de problemas y preguntas frecuentes

Síntoma. La ventana no se abre, se queda en blanco o la interfaz no se renderiza.

Causa. El proceso principal puede fallar al arrancar; una ventana en blanco apunta más bien al renderer de Chromium.

Remedio. Cierra Singularity por completo, vuelve a abrirlo y abre Help → Show Log File. Si la interfaz no es accesible, lee singularity-main.log en la ruta indicada en Registros e informe de error. En desarrollo, lee también el terminal de pnpm dev y usa View → Toggle Developer Tools.

Síntoma. La tarjeta muestra exactamente «Failed to launch agent» o «Agent run failed».

Causa. El CLI del proveedor no está instalado, está fuera del PATH de Electron o no está autenticado.

Remedio. Con la misma cuenta de usuario, ejecuta el comando de versión del CLI y después su comando de inicio de sesión o de estado. Si no se encuentra, instala el CLI oficial y reinicia Singularity por completo para recargar el PATH. Consulta Proveedores de IA.

Síntoma. Mensaje exacto: «Engine is on a stale build (cannot stop a review_required run). Restart Electron (kill pnpm dev and relaunch) so the orchestration fixes load.»

Causa. El renderer y el motor activo no proceden de la misma versión.

Remedio. Cierra toda la aplicación. En desarrollo, detén pnpm dev, cierra cualquier otra instancia Electron de Singularity y vuelve a lanzarla.

Síntoma. La pestaña muestra «No agent work to review» o un estado explícito.

Causa y remedio.

• «The agent is still working»: sigue el terminal.
• «Already merged»: inspecciona Graph y desactiva la fusión automática en adelante.
• «Direct run — no worktree»: activa los worktrees y desactiva la fusión automática.
• «The agent is waiting for an answer»: responde desde la tarjeta del kanban.
• «The ticket cannot be reviewed»: comprueba su estado y vuelve a lanzarlo en un worktree sin fusionar.

Consulta Revisión.

Síntoma. Sigue presente una carpeta antigua. La acción individual indica: «The worktree folder is removed. The branch and its commits are preserved.»

Causa. Una ejecución interrumpida, en revisión o sin integrar conserva su árbol aislado.

Remedio. Comprueba los commits y elimina solo ese worktree en Singularity o con git worktree remove <ruta>, seguido de git worktree prune. No uses la limpieza global si quieres conservar la rama. Consulta Worktrees y hooks de Git.

Síntoma. La salida se detiene en el hook; Singularity recuerda que «a non-zero exit code interrupts the Git operation».

Causa. Ha fallado una prueba, el lint, el formato o un control de negocio. El commit no se ha realizado.

Remedio. Lee el primer error útil, ejecuta localmente el comando del hook, corrígelo y vuelve a hacer el commit. No pases --no-verify ni desactives el hook.

Síntoma. No aparecen ni el autocompletado ni los diagnósticos; el registro contiene «Failed to spawn» o «Runtime error».

Causa. El módulo está inactivo, falta su ejecutable o el proceso termina al arrancar.

Remedio. Comprueba la activación «Enable … for IntelliSense», instala el runtime necesario y lee singularity-main.log. Consulta Servidores de lenguaje.

Síntoma. El módulo sigue desactivado o su activación falla.

Causa. No se ha concedido un permiso necesario, o el módulo es incompatible con esta versión.

Remedio. En su ficha, comprueba la compatibilidad y concede solo los permisos necesarios. Actualiza el módulo o déjalo desactivado; no modifiques su manifiesto para forzar la activación.

Síntoma. El arranque falla en SQLite o PRAGMA integrity_check; no responde ok. «NOT NULL constraint failed: _module_migrations.timestamp» es una migración no válida, no un daño en la base: un restablecimiento no lo corrige.

Causa. singularity.db o sus archivos WAL pueden estar dañados.

Remedio. Cierra todas las instancias y haz una copia de seguridad de la base de datos. Elimina a la vez singularity.db, singularity.db-wal y singularity.db-shm en ~/Library/Application Support/Singularity/ (macOS), %APPDATA%\Singularity\ (Windows) o ~/.config/Singularity/ (Linux) y vuelve a lanzar la app.

Advertencia: pierdes los espacios de trabajo, tickets, historiales, ajustes y conexiones de DB Browser locales. Los repositorios Git permanecen intactos. Eliminar todo el perfil borra también las cachés, los registros, las preferencias y los secretos locales.

Síntoma. Una notificación como «Failed to launch agent» no basta para explicar el fallo.

Causa. El detalle está en singularity-main.log, compartido por el proceso principal y el renderer, con rotación a 5 MB y tres archivos históricos.

Remedio. Usa Help → Open Logs Folder o Help → Show Log File. Rutas: ~/Library/Logs/Singularity/singularity-main.log (macOS), %APPDATA%\Singularity\logs\singularity-main.log (Windows), ~/.config/Singularity/logs/singularity-main.log (Linux).

En el informe, indica los pasos, los resultados esperado y observado, la versión, la plataforma, el mensaje exacto y un extracto del registro en torno a la marca de tiempo. Elimina los secretos y las rutas personales. Consulta Notificaciones.