# 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

```bash
# 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"
```

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

```bash
# 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.

```bash
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.