Um cron job reescreveu o próprio destino de entrega e os relatórios pararam de chegar

Sua tabela de cron tem 19 jobs. Um deles se chama upkeep e roda a “arrumação” às 4 da manhã de todo sábado. Ele faz algo banal: lista todos os jobs, atualiza o prompt e as configurações de entrega de alguns irmãos a partir de um template — inclusive a linha
hermes cron edit <upkeep-id> --deliver origin
que se lê como “manda os resultados de volta para o chat em que eu fui criado”. A primeira semana foi tranquila. Na segunda, o relatório de sábado não chegou. Na terceira, também não. O hermes cron list mostra o campo deliver desse job como local — sem erro, sem aviso: ele simplesmente passou de “entregar para mim” para “não entregar em lugar nenhum”.
O que origin realmente significa
A semântica importa, porque o bug mora dentro dela. O deliver de um cron job pode nomear um destino concreto (telegram:<chat_id>, slack, local, all), ou pode ser origin — o chat em que o job foi criado.
origin é uma expressão relativa ao momento da criação. Quando o job é criado, o Hermes grava o endereço da conversa daquele instante; toda execução posterior entrega ali. Se não havia nenhuma origem utilizável no momento da criação (um job criado por um script, ou na plataforma api_server de request/response, que não consegue receber entregas), entra um fallback de home channel.
A documentação oficial explica o design sem rodeios, na seção sobre gerenciar cron de dentro de uma execução de cron:
Sem entrega pendurada. A execução de um cron é efêmera, então
deliver: originde dentro dela é resolvido no momento da criação para o destino concreto do job criador (platform:chat_id[:thread_id], oulocalse o job criador não entrega em lugar nenhum).
Repare nessas três palavras: no momento da criação. O cenário documentado é criar um job novo de dentro de uma execução de cron — um job recém-nascido não pode apontar para uma sessão efêmera que vai desaparecer, então o origin é resolvido no instante em que ele é criado.
Atualizar um job que já existe é outra história. O job já existe, o origin dele foi gravado faz tempo, e origin é significativo e estável para ele. Resolver de novo nesse ponto não corrige nada — estraga um valor que já estava certo.
O que o código faz
_update_core_fields, em tools/cronjob_tools.py, manda tanto deliver quanto failure_deliver pelo mesmo resolver no caminho de atualização:
if deliver is not None:
...
updates["deliver"] = _resolve_cron_context_deliver(_normalize_deliver_param(deliver))
if a["failure_deliver"] is not None:
...
_norm_fd = _resolve_cron_context_deliver(_norm_fd)
updates["failure_deliver"] = _norm_fd
E a docstring do próprio resolver declara o escopo (tools/cronjob_job_args.py):
def _resolve_cron_context_deliver(deliver: Optional[str]) -> Optional[str]:
"""Resolve ``origin`` to a concrete target for creates made FROM a cron run (the creating
session is ephemeral, so by fire time there is no origin). Non-cron sessions: unchanged.
Cron sessions: ``origin`` (or omitted) becomes the creating run's ``platform:chat_id[:thread]``
from HERMES_CRON_AUTO_DELIVER_*, or ``local`` when it has no concrete target; other
elements pass through. Otherwise the scheduler would guess a home channel."""
“For creates made FROM a cron run.” A primeira linha do corpo diz a mesma coisa:
if not is_truthy_value(get_session_env("HERMES_CRON_SESSION", "")):
return deliver
Fora de uma execução de cron ele devolve o valor intacto. Dentro de uma, origin (e None) viram o endereço concreto do criador, montado a partir de HERMES_CRON_AUTO_DELIVER_PLATFORM / _CHAT_ID / _THREAD_ID; sem destino concreto, degrada para local.
O problema é que o scheduler define essas três variáveis para o job que está rodando naquele momento (cron/scheduler.py atribui HERMES_CRON_AUTO_DELIVER_* e as marca como herdáveis por subprocessos). Então, quando você chama hermes cron edit de dentro de uma execução de cron, o processo filho carrega o destino de entrega do job em execução. Um comando que deveria significar “mantenha o seu próprio origin” passa a significar “vire o meu chat” — e, se o próprio job de manutenção entrega em local, o resultado é local.
Você não vê acontecer. updates["deliver"] é simplesmente sobrescrito, o comando sai com 0, e uma coluna no hermes cron list mudou em silêncio.
Três checagens para rodar
Um: liste os jobs com origin e confirme que eles ainda dizem origin.
hermes cron list
Se você encontrar local em jobs que nunca mexeu, foi isso que aconteceu.
Dois: rode o health check de entrega.
hermes cron doctor
É uma verificação somente leitura da frota inteira: execuções que falharam, entregas que falharam, next_run_at atrasado ou ausente, scripts ou workdirs faltando — saindo com código diferente de zero quando encontra problema. Ele não vai te dizer “o origin foi reescrito para local”, mas “este job está configurado para entregar e vive falhando” costuma aparecer aqui.
Três: não edite entrega de dentro de uma execução de cron.
Esse é o contorno direto. Um job de manutenção pode mudar prompts, schedules e nomes pelo tool cronjob sem risco; o campo de entrega deve ser alterado por uma pessoa, ou escrito como destino explícito em vez de origin.
Se você realmente precisa rodar essa edição de dentro de uma execução de cron, tire as variáveis em volta da chamada do CLI:
env -u HERMES_CRON_SESSION \
-u HERMES_CRON_AUTO_DELIVER_PLATFORM \
-u HERMES_CRON_AUTO_DELIVER_CHAT_ID \
-u HERMES_CRON_AUTO_DELIVER_THREAD_ID \
hermes cron edit <id> --deliver origin
O mecanismo é fácil de acompanhar: fora de uma “sessão de cron” o resolver devolve a entrada logo na primeira linha, origin continua literal, e um origin literal é válido para um job existente — ele tem um origin gravado e, quando não tem, um fallback de home channel.
Por que esse bug é tão difícil de perceber
Três características silenciosas se empilham:
- Nenhum erro. O caminho de sucesso é uma sobrescrita de campo e um exit code 0.
- Exposição atrasada. A execução de manutenção em si parece normal; o estrago só aparece quando um job irmão dispara de novo e nada surge, geralmente dias depois.
- Sintomas enganosos. Seu primeiro instinto é “a plataforma de entrega quebrou” ou “o token do bot expirou”, então você vai ler logs do Telegram e do gateway enquanto a mudança real está parada no
jobs.json.
O fix é estreito: aplicar a resolução de contexto de cron só na criação e manter o origin literal na atualização. Existe um patch da comunidade com teste de regressão (o teste novo falha na main e passa com o patch), mas ele ainda não foi merged. Até lá, as três checagens acima são o melhor que você tem.
Mais uma coisa sobre entrega de cron
deliver e failure_deliver são dois campos separados — o segundo diz para onde vão as falhas e compartilha o caminho de resolução do primeiro. Então esse bug reescreve os dois. Se você tinha configurado “sucesso para o grupo, falhas para mim em privado”, confira as duas colunas.
Cron tem mais botões do que a maioria imagina: um job pode entregar pelo próprio bot (veja dar a um cron job o seu próprio bot), carregar memória entre execuções (veja continuidade de memória no cron) e ser checado com cron doctor (veja o guia do cron doctor). A lista completa de subcomandos está na referência do comando cron.
Se você guardar uma frase, guarde esta: origin é relativo ao momento da criação, e qualquer coisa que “resolva de novo” esse valor depois pode quebrar um endereço que já estava certo.