Resolução de problemas e perguntas frequentes

Sintoma. A janela não abre, fica em branco ou a interface não é renderizada.

Causa. O processo principal pode falhar no arranque; uma janela em branco aponta antes para o renderer do Chromium.

Solução. Sai completamente do Singularity, volta a abri-lo e abre Help → Show Log File. Se a interface estiver inacessível, lê o singularity-main.log no caminho indicado em Registos e relatório de erro. Em desenvolvimento, lê também o terminal do pnpm dev e usa View → Toggle Developer Tools.

Sintoma. O cartão mostra exatamente «Failed to launch agent» ou «Agent run failed».

Causa. O CLI do fornecedor não está instalado, está fora do PATH do Electron ou não está autenticado.

Solução. Com a mesma conta de utilizador, executa o comando de versão do CLI e depois o seu comando de início de sessão ou de estado. Se não for encontrado, instala o CLI oficial e reinicia completamente o Singularity para recarregar o PATH. Vê Fornecedores de IA.

Sintoma. Mensagem exata: «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. O renderer e o motor ativo não provêm da mesma versão.

Solução. Sai de toda a aplicação. Em desenvolvimento, para o pnpm dev, fecha qualquer outra instância Electron do Singularity e volta a lançá-la.

Sintoma. O separador mostra «No agent work to review» ou um estado explícito.

Causa e solução.

• «The agent is still working»: acompanha o terminal.
• «Already merged»: inspeciona Graph e desativa a fusão automática daqui em diante.
• «Direct run — no worktree»: ativa os worktrees e desativa a fusão automática.
• «The agent is waiting for an answer»: responde a partir do cartão do kanban.
• «The ticket cannot be reviewed»: verifica o seu estado e volta a lançá-lo num worktree não fundido.

Vê Revisão.

Sintoma. Continua presente uma pasta antiga. A ação individual indica: «The worktree folder is removed. The branch and its commits are preserved.»

Causa. Uma execução interrompida, em revisão ou não integrada mantém a sua árvore isolada.

Solução. Verifica os commits e elimina apenas esse worktree no Singularity ou com git worktree remove <caminho>, seguido de git worktree prune. Não uses a limpeza global se quiseres manter o ramo. Vê Worktrees e hooks Git.

Sintoma. A saída para no hook; o Singularity lembra que «a non-zero exit code interrupts the Git operation».

Causa. Falhou um teste, o lint, a formatação ou uma verificação de negócio. O commit não foi feito.

Solução. Lê o primeiro erro útil, executa localmente o comando do hook, corrige-o e volta a fazer o commit. Não passes --no-verify nem desatives o hook.

Sintoma. O preenchimento automático e os diagnósticos continuam ausentes; o registo contém «Failed to spawn» ou «Runtime error».

Causa. O módulo está inativo, falta o seu executável ou o processo termina no arranque.

Solução. Verifica a ativação «Enable … for IntelliSense», instala o runtime necessário e lê o singularity-main.log. Vê Servidores de linguagem.

Sintoma. O módulo continua desativado ou a sua ativação falha.

Causa. Não foi concedida uma permissão necessária, ou o módulo é incompatível com esta versão.

Solução. Na sua ficha, verifica a compatibilidade e concede apenas as permissões necessárias. Atualiza o módulo ou deixa-o desativado; não modifiques o seu manifesto para forçar a ativação.

Sintoma. O arranque falha no SQLite ou PRAGMA integrity_check; não devolve ok. «NOT NULL constraint failed: _module_migrations.timestamp» é uma migração inválida, não uma corrupção: uma reposição não a corrige.

Causa. O singularity.db ou os seus ficheiros WAL podem estar danificados.

Solução. Sai de todas as instâncias e faz uma cópia de segurança da base de dados. Elimina em conjunto singularity.db, singularity.db-wal e singularity.db-shm em ~/Library/Application Support/Singularity/ (macOS), %APPDATA%\Singularity\ (Windows) ou ~/.config/Singularity/ (Linux) e volta a lançar a app.

Aviso: perdes os espaços de trabalho, tickets, históricos, definições e ligações do DB Browser locais. Os repositórios Git permanecem intactos. Eliminar todo o perfil apaga também as caches, os registos, as preferências e os segredos locais.

Sintoma. Uma notificação como «Failed to launch agent» não basta para explicar a avaria.

Causa. O detalhe está no singularity-main.log, partilhado pelo processo principal e pelo renderer, com rotação aos 5 MB e três arquivos.

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

No relatório, indica os passos, os resultados esperado e observado, a versão, a plataforma, a mensagem exata e um excerto do registo em torno da marca temporal. Remove os segredos e os caminhos pessoais. Vê Notificações.