Pular para o conteúdo
emet

Solução de problemas

Falhas do emet doctor e do emet preflight, agrupadas pelo que você vê, cada uma com a causa e uma correção. Os termos seguem o GLOSSARY.md. Para saber como as verificações se encaixam, veja a arquitetura.

Um repositório que ainda tem apenas forge.config.json, .forge/ ou variáveis FORGE_* continua funcionando: o emet lê os nomes legados, imprime uma linha no stderr nomeando cada arquivo legado, e o emet migrate os renomeia.

Sem emet.config.json

Sintoma: o emet doctor imprime no emet.config.json — run "emet init" here.

Causa: O repositório ainda não tem configuração do /emet.

Correção: Execute emet init na raiz do repositório, depois revise a configuração gerada e preencha os arquivos de docs/agents/.

emet.config.json está malformado

Sintoma: emet.config.json is malformed: <reason>; o emet preflight termina com código 2.

Causa: A configuração é JSON estrito e é validada contra emet/schema/emet.config.schema.json. Comentários e vírgulas finais são rejeitados.

Correção: Corrija o campo nomeado no motivo, ou regenere com emet init --force.

docs/agents ainda tem marcadores TODO(emet)

Sintoma: docs/agents/ still has N TODO(emet): marker(s); o emet doctor também informa um docs/agents/<file> ausente.

Causa: O emet init deixa um marcador onde quer que não consiga detectar um valor.

Correção: Preencha cada linha marcada, ou resolva-as e execute emet init --force. O preflight se recusa a despachar enquanto restar algum.

Uma verificação de dependência falha

Sintoma: linhas dependency: ... no emet doctor, ou uma falha de dependência bloqueante no emet preflight (por exemplo gh ausente ou não autenticado, ou o plugin mattpocock-skills ausente ou em uma versão não testada).

Causa: O /emet precisa de git, gh e do plugin mattpocock-skills; veja emet/src/dependencies.ts e emet/src/skills.ts.

Correção: Instale ou autentique a ferramenta, ou execute /setup-matt-pocock-skills. Se uma verificação estiver errada para o seu ambiente, EMET_SKIP_DEPENDENCY_CHECKS=1 emet preflight a rebaixa a um aviso.

não documenta mais uma flag em –help

Sintoma: <tool> no longer documents <flags> in --help — emet relies on it, ou could not be run — cannot verify <flags>.

Causa: O emet doctor verifica as flags das quais o emet depende, não apenas se o binário existe. A versão instalada removeu ou renomeou uma delas.

Correção: Instale uma versão da ferramenta que ainda documente a flag.

Um arquivo instalado está ausente ou foi editado desde a instalação

Sintoma: ~/<path> is missing — re-run install.sh ou ~/<path> was edited since install.

Causa: A cópia instalada não corresponde mais ao manifesto de instalação.

Correção: Execute o install.sh de novo. Se houver um arquivo .new pendente ao lado de um arquivo editado, mescle-o ou apague-o.

Stop hook error: forge: No such file or directory

Sintoma: o Claude Code imprime Stop hook error: … forge: No such file or directory (ou o mesmo para emet) ao final de cada turno.

Causa: O ~/.claude/settings.json ainda tem um hook forge guard ou emet guard cujo binário foi movido ou removido.

Correção: Execute emet doctor .. Ele lista cada hook guard morto com seu evento e imprime um comando cp … && jq … que faz backup do settings.json e remove somente esses hooks. O doctor nunca edita o arquivo por conta própria.

Sem slots de worker livres

Sintoma: No free worker slots at all: 0 free out of N, ou only K/N worker slot(s) free.

Causa: Cada slot em ~/.local/state/emet/slots está nas mãos de uma execução viva ou ociosa, então a onda não consegue ser despachada por completo.

Correção: Espere uma execução liberar um slot, ou execute emet cleanup --run <runId> para uma execução que você sabe que terminou. O emet status mostra quem tem o quê.

Worktrees bloqueados esperados, encontrados menos

Sintoma: Expected N locked worktree(s) for run <id>, found M.

Causa: Os workers não reivindicaram seu worktree com o motivo de bloqueio, ou isolation: "worktree" os colocou em outro lugar. Veja incidents.md.

Correção: Verifique git worktree list --porcelain para ver as entradas bloqueadas, e emet lock-reason para o formato de motivo esperado.

Um ticket é reivindicado por vários worktrees ou branches

Sintoma: <ticket> is claimed by N worktrees, has N branches, ou is checked out on branch ..., but its own lock names ticket ....

Causa: Uma nova tentativa ou um shell roteado incorretamente deixou um duplicado.

Correção: Mantenha o worktree ou a branch canônicos, apague ou bloqueie de novo o restante, e execute o emet preflight novamente.

requiredCommands fora do PATH

Sintoma: preflight.requiredCommands not on PATH: <names>.

Causa: preflight.requiredCommands no emet.config.json lista binários de que o repositório precisa.

Correção: Instale os binários nomeados, ou remova-os da configuração se não forem mais necessários.

Veja também