Dépannage et questions fréquentes

Symptôme. La fenêtre ne s’ouvre pas, reste blanche ou l’interface ne se rend pas.

Cause. Le processus principal peut échouer au démarrage ; une fenêtre blanche pointe plutôt vers le renderer Chromium.

Remède. Quittez complètement Singularity, relancez-le, puis ouvrez Aide → Afficher le fichier journal. Si l’interface est inaccessible, lisez singularity-main.log au chemin indiqué dans Journaux et rapport de bug. En développement, lisez aussi le terminal de pnpm dev et utilisez Vue → Basculer les outils de développement.

Symptôme. La carte affiche exactement « Échec du lancement de l’agent » ou « Échec de l’exécution de l’agent ».

Cause. Le CLI du fournisseur est absent, hors du PATH d’Electron ou non authentifié.

Remède. Sous le même compte utilisateur, exécutez la commande de version du CLI, puis sa commande de connexion ou de statut. S’il est introuvable, installez le CLI officiel et redémarrez entièrement Singularity pour recharger le PATH. Voir Fournisseurs IA.

Symptôme. Message exact : « Le moteur utilise une version obsolète (impossible d’arrêter une exécution review_required). Redémarrez Electron (arrêtez pnpm dev puis relancez-le) pour charger les correctifs d’orchestration. »

Cause. Le renderer et le moteur actif ne proviennent pas de la même version.

Remède. Quittez toute l’application. En développement, arrêtez pnpm dev, fermez toute autre instance Electron Singularity, puis relancez.

Symptôme. L’onglet affiche « Aucun travail d’agent à réviser » ou un état explicite.

Cause et remède.

• « L’agent travaille encore » : suivez le terminal.
• « Déjà fusionné » : inspectez Graphe et désactivez la fusion automatique à l’avenir.
• « Exécution directe — aucun worktree » : activez les worktrees et désactivez la fusion automatique.
• « L’agent attend une réponse » : répondez depuis la carte kanban.
• « Le ticket ne peut pas être révisé » : vérifiez son statut et relancez-le dans un worktree non fusionné.

Voir Revue.

Symptôme. Un ancien dossier reste présent. L’action ciblée précise : « Le dossier du worktree est supprimé. La branche et ses commits sont conservés. »

Cause. Une exécution interrompue, en revue ou non intégrée conserve son arborescence isolée.

Remède. Vérifiez les commits, puis supprimez uniquement ce worktree dans Singularity ou avec git worktree remove <chemin>, suivi de git worktree prune. N’utilisez pas le nettoyage global si vous voulez garder la branche. Voir Worktrees et hooks Git.

Symptôme. La sortie s’arrête dans le hook ; Singularity rappelle qu’« un code de sortie non nul interrompt l’opération Git ».

Cause. Un test, lint, formatage ou contrôle métier a échoué. Le commit n’a pas eu lieu.

Remède. Lisez la première erreur utile, exécutez localement la commande du hook, corrigez-la, puis recommencez le commit. Ne passez pas --no-verify et ne désactivez pas le hook.

Symptôme. Complétion et diagnostics restent absents ; le journal contient « Failed to spawn » ou « Runtime error ».

Cause. Le module est inactif, son exécutable manque ou le processus se termine au démarrage.

Remède. Contrôlez l’activation « Activer … pour IntelliSense », installez le runtime requis et lisez singularity-main.log. Voir Serveurs de langage.

Symptôme. Le module reste désactivé ou son activation échoue.

Cause. Une permission requise n’a pas été accordée, ou le module est incompatible avec cette version.

Remède. Dans sa fiche, contrôlez la compatibilité et accordez uniquement les permissions nécessaires. Mettez le module à jour ou laissez-le désactivé ; ne modifiez pas son manifeste pour forcer l’activation.

Symptôme. Le démarrage échoue sur SQLite ou PRAGMA integrity_check; ne répond pas ok. « NOT NULL constraint failed: _module_migrations.timestamp » est une migration invalide, pas une corruption : une réinitialisation ne la corrige pas.

Cause. singularity.db ou ses fichiers WAL peuvent être endommagés.

Remède. Quittez toutes les instances et sauvegardez la base. Supprimez ensemble singularity.db, singularity.db-wal et singularity.db-shm dans ~/Library/Application Support/Singularity/ (macOS), %APPDATA%\Singularity\ (Windows) ou ~/.config/Singularity/ (Linux), puis relancez.

Avertissement : vous perdez les espaces de travail, tickets, historiques, réglages et connexions DB Browser locaux. Les dépôts Git restent intacts. Supprimer tout le profil efface aussi caches, journaux, préférences et secrets locaux.

Symptôme. Une notification comme « Échec du lancement de l’agent » ne suffit pas à expliquer la panne.

Cause. Le détail est dans singularity-main.log, partagé par le processus principal et le renderer, avec rotation à 5 Mo et trois archives.

Remède. Utilisez Aide → Ouvrir le dossier des journaux ou Aide → Afficher le fichier journal. Chemins : ~/Library/Logs/Singularity/singularity-main.log (macOS), %APPDATA%\Singularity\logs\singularity-main.log (Windows), ~/.config/Singularity/logs/singularity-main.log (Linux).

Dans le rapport, donnez les étapes, résultats attendu et observé, version, plateforme, message exact et extrait autour de l’horodatage. Retirez secrets et chemins personnels. Voir Notifications.