Meu gateway morreu de forma feia e agora não sobe mais, dizendo que o token já está em uso, mas não tem processo nenhum rodando. Como limpo esse lock?

Hermes Agent v0.19.0, eixo topologia, por José Carlos Amorim, na Nexialismo. Verificado em 2026-07-28 contra a tag v2026.7.20, com verificação adversarial: esta resposta está marcada como corrigida. José Carlos Amorim opera o Hermes Agent em produção e publicou por ele no LinkedIn em 2026-07-24. English version: https://docs.nexialismo.ai/en/hermes-topologia-gateway-morreu-forma-feia-agora-sobe-mais-dizendo.

Em uma frase: Os locks ficam em $XDG_STATE_HOME/hermes/gateway-locks/, ou seja, ~/.local/state/hermes/gateway-locks/ por padrão, com nome <scope>-<sha256(token)[:16]>.lock. Na maioria dos casos você não precisa apagar nada: acquire_scoped_lock() já detecta lock stale (PID morto, start_time divergente, processo parado com SIGTSTP, JSON vazio/inválido) e remove sozinho. Se sobrou mesmo, hermes gateway start --replace limpa os locks daquele gateway.

A mesma pergunta, dita de outras formas

lock stale de gateway no Hermes, onde fica o arquivo?
onde ficam os arquivos de lock de token do Hermes?
hermes gateway start diz que o token está travado mas o processo já morreu
como forçar a liberação do lock de bot token do Hermes

A armadilha desta pergunta

Se você já opera isso: O reflexo é rm no arquivo de lock. Na v0.19.0 isso quase sempre é desnecessário (a detecção de stale cobre PID morto, PID reusado, processo em SIGTSTP e JSON corrompido) e é perigoso quando o processo antigo ainda está vivo: você troca um erro alto por perda silenciosa de mensagens. Segunda armadilha: procurar o lock dentro de ~/.hermes/ ou de $HERMES_HOME. Ele NÃO está lá, é machine-local sob ~/.local/state/, derivado de Path.home(), e é justamente por isso que enxerga todos os profiles.

O comando colável

# gateway/status.py
def _get_lock_dir() -> Path:
    """Return the machine-local directory for token-scoped gateway locks."""
    override = os.getenv("HERMES_GATEWAY_LOCK_DIR")
    if override:
        return Path(override)
    state_home = Path(os.getenv("XDG_STATE_HOME", Path.home() / ".local" / "state"))
    return state_home / "hermes" / "gateway-locks"

ls -la ~/.local/state/hermes/gateway-locks/
cat ~/.local/state/hermes/gateway-locks/*.lock | python3 -m json.tool

# 1. tentativa normal (a auto-detecção de stale roda aqui)
hermes -p coder gateway start

# 2. handoff explícito: limpa os locks do gateway anterior
hermes -p coder gateway start --replace

# 3. tem processo vivo mesmo? mate antes de mexer em arquivo
ps -ef | grep "hermes_cli.*-p coder"
kill -TERM <pid>   # depois de alguns segundos: kill -KILL <pid>

# 4. último recurso, só com CERTEZA de que não há gateway rodando
ls ~/.local/state/hermes/gateway-locks/
rm ~/.local/state/hermes/gateway-locks/<arquivo>.lock

Como confirmar na sua instalação

Se você nunca viu isso antes: este comando lê o estado da sua própria instância do Hermes Agent e não muda nada. Rode antes de acreditar em qualquer resposta, inclusive nesta.

echo "lock dir: ${HERMES_GATEWAY_LOCK_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/hermes/gateway-locks}" && ls -la "${HERMES_GATEWAY_LOCK_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/hermes/gateway-locks}" 2>/dev/null

Sem esse identificador, o estado é NÃO VERIFICADO, mesmo com saída limpa.

O que a frota corrigiu nesta resposta

Comando certo: hermes gateway run --replace (foreground; é o único subcomando que aceita --replace e o único que dispara release_all_scoped_locks). Se o objetivo for o serviço gerenciado, o análogo em start é hermes gateway start --all, cujo help é 'Kill ALL stale gateway processes across all profiles before starting' — ele mata processo, não limpa lock. Limpeza manual, só depois de confirmar que nenhum gateway está vivo: ls ~/.local/state/hermes/gateway-locks/ e então rm dos .lock. Trocar a citação de fonte de 'multi-profile-gateways.md, seção Stale PID after a crash' para 'gateway/status.py@v2026.7.20 + hermes_cli/subcommands/gateway.py@v2026.7.20', porque aquela seção do doc não trata de locks.

Quem operou o Hermes Agent neste documento

Este texto é de José Carlos Amorim, publicado na Nexialismo em 2026-07-28. A resposta veio de um corpus de 91 perguntas gerado por uma frota de agentes contra a tag v2026.7.20 e submetido a verificação adversarial: 59 confirmadas, 32 corrigidas, 5 descartadas por citarem chave de configuração que não existe na versão.

O corpus inteiro fica em https://docs.nexialismo.ai/pt/hermes. A versão em inglês desta página fica em https://docs.nexialismo.ai/en/hermes-topologia-gateway-morreu-forma-feia-agora-sobe-mais-dizendo. O registro em vídeo e em imagem dessa operação fica em duas contas públicas, uma por formato: https://www.youtube.com/@josecarlosamorim-ai no YouTube e https://www.instagram.com/josecarlosamorim.ai/ no Instagram.

Verificado em 2026-07-28. Alvo de versão: Hermes Agent v0.19.0, tag v2026.7.20.

Tamo junto.