Segunda-feira de manhã, você abre o laptop e percebe que o job agendado da noite anterior nunca rodou — e que ele está morto em silêncio há três dias. hermes cron list ainda mostra o job, hermes cron status não reporta erro, mas não há saída, nem mensagem, nem log dizendo o que deu errado. Esse tipo de falha silenciosa é pior que um erro: o job “parece saudável” enquanto está, na verdade, morto. O novo comando hermes cron doctor, mesclado em 31 de agosto, existe exatamente para esse cenário: um único comando somente leitura que verifica toda a sua frota de cron de ponta a ponta, diz explicitamente o que está errado e usa o código de saída para você conectá-lo a alertas automatizados.

Por que “parece tudo bem” enquanto nada roda

Este comando nasceu de um incidente real de produção: em uma frota rodando 60 cron jobs, um job estava morto há 5 dias (uma falha do filtro de conteúdo) e dois jobs watchdog não estavam disparando em silêncio — e nenhuma das superfícies existentes (list, status, incidents) mostrava o problema de relance. Os jobs ainda estavam na lista, então tudo “parecia normal”; o next_run_at deles tinha expirado há muito tempo, mas ninguém estava verificando.

Essa é a doença clássica do cron: o agendador não reclama a menos que você vá olhar “quando era para rodar — e rodou de verdade?”

hermes cron doctor: um checkup, sete verificações

hermes cron doctor é um novo subcomando da família hermes cron (hermes cron [list|create|edit|pause|resume|run|remove|status|runs|doctor|tick]). Ele é somente leitura — nunca altera a configuração de um job; apenas percorre cada job habilitado e reporta o que encontra. De acordo com o código-fonte (_cron_doctor_issues_for_job em hermes_cli/cron.py), eis o que ele verifica:

• Última execução falhou: quando o last_status registrado do job não é ok, ele reporta o last_error concreto;
• Última entrega falhou: ele reporta last_delivery_error, por exemplo uma mensagem que nunca chegou à sua plataforma de chat;
• Job habilitado sem next_run_at: um job ativo que não consegue agendar a próxima execução já é por si só um sintoma;
• next_run_at atrasado: com uma margem de 15 minutos do ticker; um timestamp atrasado imprime “next_run_at is Xm/h overdue — job is not firing (is the scheduler running?)” — o sinal de um job que não dispara em silêncio;
• Job sem agente e sem script: um job apenas de script (no_agent: true) sem script configurado;
• Problemas de saúde do script: o health check do próprio script (por exemplo, o arquivo não existir);
• Workdir morto: o workdir do job não existe mais no disco.

Qualquer job que bata em qualquer um desses pontos é listado — e esses rastros são exatamente o único resíduo que um job “na lista, mas morto” deixa para trás.

Como é a saída

Quando está tudo saudável, a saída é agradavelmente enxuta:

✓ Cron doctor found no issues
  Checked 12 active job(s).

Quando existem problemas, ele lista cada ocorrência por job e termina com o código de saída 1:

Cron doctor found 3 issue(s) across 2 job(s):

  cron_daily_report
    - last run failed: content filter rejected output
    - next_run_at is 26.4h overdue — job is not firing (is the scheduler running?)
  nightly_backup
    - workdir not found: /data/backups

Next: fix the listed job config, then run `hermes cron doctor` again.

Como usar: o código de saída é o que importa

Um health check só se paga quando alimenta automação. O código de saída é deliberadamente simples: 0 = tudo saudável, 1 = algo precisa de ação. Então você pode conectá-lo direto num script de monitoramento:

# Checkup da frota em uma linha toda manhã; alerta quando algo está errado
if ! hermes cron doctor; then
  hermes send -t telegram "cron fleet has a job in trouble — go check!"
fi

Ou simplesmente rode hermes cron doctor manualmente sempre que quiser uma auditoria rápida. Ele é somente leitura, então sempre é seguro rodar.

Quando você pode usar

O PR #99479 foi mesclado em 31 de agosto de 2026 e está apenas na main — o v0.20.6 (lançado em 27 de agosto) ainda não tem esse subcomando. Atualize para a main mais recente para usá-lo agora, ou espere o próximo release. A documentação oficial (o guia de cron e a referência da CLI) já o documenta.

Jobs agendados só cumprem seu papel quando rodam de forma confiável sem ninguém vigiando, e confiabilidade começa por saber que eles realmente rodam. hermes cron doctor transforma esse “saber” em um único comando. Para uma configuração de automação mais completa, veja nosso guia completo de automação de cron e monitoramento de cron e preflight checks; se seus jobs continuam falhando em silêncio às 3h da manhã, o guia de ajuste do loop-watchdog do gateway também vale a leitura. Referência do comando: hermes cron.