Arquivos temporários de sessão não estouram mais o seu RAM disk: terminal.temp_dir e limpeza automática de 72 horas

É sábado à noite e você deixou o Hermes rodando um job em lote: processos em segundo plano escrevendo logs, um sandbox de execução de código despejando resultados intermediários, várias chamadas de ferramenta gravando saída em disco de vez em quando. Você acorda às 3h da manhã com um alerta de “disco cheio” — e o culpado não é o diretório do seu projeto, é o /tmp, o diretório em que você nunca pensa. Isso não é um caso raro: muitas distros (especialmente as baseadas em Arch) montam /tmp como um tmpfs em RAM cuja capacidade é apenas uma fração da sua memória física. Assim que o Hermes dispara alguns processos em segundo plano, esse RAM disk enche — e vêm falhas misteriosas de escrita, processos quebrados e tarefas abortadas. A correção mesclada em 28 de agosto (PR #97205) resolve isso de uma vez: os arquivos temporários de sessão agora vão para disco real por padrão, e você ganha uma chave de config para movê-los para onde quiser.

Causa raiz: arquivos temporários em um tmpfs

O Hermes gera um monte de “artefatos temporários de sessão” enquanto trabalha: arquivos de log/pid/exit de processos em segundo plano (o trio hermes_bg_*), sandboxes de execução de código e resultados de ferramentas despejados em disco. Antes dessa mudança, esses arquivos iam por padrão para /tmp.

Em muitas distros Linux, /tmp não é um diretório real em disco — é um tmpfs: os dados ficam na RAM, leituras e escritas são rápidas, mas a capacidade é pequena (normalmente metade da memória física ou menos) e tudo desaparece no reboot. Quando o Hermes trabalha pesado, os processos em segundo plano se acumulam e o RAM disk seca em minutos. Pior: falhas de escrita raramente falham rápido — elas aparecem no meio da tarefa de maneiras confusas.

A descrição do mantenedor é direta: “muitas distros (configurações baseadas em Arch, e as nossas próprias máquinas) montam /tmp como um pequeno tmpfs apoiado em RAM, e o Hermes o enche sob carga.” Até as máquinas da própria equipe oficial esbarram nisso.

A correção: arquivos temporários vão para armazenamento real por padrão

A ordem de resolução depois da mudança é:

  1. Chave de config terminal.temp_dir (explícita, prioridade máxima)
  2. Variáveis de ambiente TMPDIR / TMP / TEMP
  3. ~/.hermes/cache/terminal (novo padrão)
  4. /tmp (fallback de último recurso)

Ou seja, a menos que você configure algo, os arquivos temporários de sessão agora caem no diretório de cache do próprio Hermes — armazenamento real, capacidade deixa de ser problema. O branch do Windows espelha o mesmo padrão, então o comportamento é consistente entre plataformas.

Limpeza automática de 72 horas

A mudança também traz um podador cleanup_terminal_temp_cache(): arquivos temporários com mais de 72 horas são deletados automaticamente. Ele tem um detalhe bem pensado — o trio hermes_bg_* (log / pid / exit) envelhece como um grupo: o arquivo .log recente de um serviço em segundo plano ainda ativo “protege” seus arquivos .pid e .exit de aparência obsoleta de serem deletados. Assim, um serviço ainda em execução nunca perde seu arquivo de pid e se torna impossível de rastrear.

Quer outro local? Duas opções

Se você preferir manter os arquivos temporários de sessão em outro lugar (um SSD dedicado, um volume de dados grande), escolha uma das opções.

Opção 1: a chave de config terminal.temp_dir

# config.yaml
terminal:
  temp_dir: /var/hermes-tmp

Opção 2: a variável de ambiente TERMINAL_TEMP_DIR

export TERMINAL_TEMP_DIR=/var/hermes-tmp

A chave de config tem precedência sobre a variável de ambiente, e ambas têm precedência sobre o padrão. Um detalhe: se você apontar os arquivos temporários explicitamente para algum lugar, esse diretório é seu para gerenciar — a limpeza automática só se aplica ao padrão gerenciado ~/.hermes/cache/terminal, nunca ao seu local personalizado (o comentário no código-fonte é explícito: “locais apontados pelo usuário via terminal.temp_dir são responsabilidade do usuário”).

O que isso significa para você

  • Usuários de Arch / outros tmpfs: você se beneficia imediatamente após atualizar — o padrão já vai para disco real, sem config necessária;
  • Quem quer controle fino: agora existem uma chave de config e uma variável de ambiente, então você decide onde os arquivos temporários ficam;
  • Quem se preocupa com acúmulo de disco: a limpeza automática de 72 horas com envelhecimento em grupo garante que os arquivos nunca se acumulem.

A mudança também corrige silenciosamente uma dor antiga: quando /tmp costumava encher, sandboxes rodando dentro de uma sessão falhavam silenciosamente — aquelas “falhas misteriosas de escrita” agora são bem menos comuns. Se o seu Hermes ainda está numa versão antiga, rode hermes update para a build mais recente que contém essa mudança.

Leitura adicional