Você roda hermes update numa manhã de quarta-feira como sempre faz, esperando que ele puxe as poucas dúzias de commits que caíram na main. Em vez disso ele imprime uma única linha: ✓ No newer release: stable v0.21.6; this checkout is newer and waits for the next release… — e menciona que você está algumas centenas de commits atrás da main. Você não tocou em nenhuma configuração.

Nada está quebrado. O padrão mudou: numa instalação oficial a partir do código-fonte, hermes update agora segue o canal stable — a release mais recente publicada no GitHub — em vez de cada commit na main. Estas são as novas regras, incluindo a que pega as pessoas desprevenidas: o padrão só anda para a frente.

O que “stable” aponta de fato

Stable é a Release do GitHub publicada mais recente no repositório oficial, e ela precisa satisfazer três coisas ao mesmo tempo:

• não é rascunho nem prerelease;
• a tag dela é uma versão semântica estrita, vX.Y.Z — três números, sem sufixo.

Quando bate, o alvo da atualização é o commit exato para o qual a tag aponta, não a ponta atual de qualquer branch onde a tag por acaso esteja. Assim você nunca deriva para os lados, para dentro de código pela metade, entre duas atualizações.

Uma peça de história vale a pena aqui: o projeto costumava publicar tags baseadas em data (v2026.9.24 e afins). Só versões semânticas são elegíveis para o feed stable, o que significa que uma tag CalVer nunca pode ser confundida com uma release.

Onde o canal vive: por instalação, não global

O registro do canal é escrito no config.yaml, mas de propósito não como um update.channel global:

update:
  installs:
    a4f3b2c1d0e9f8a7:                      # id da instalação (sha16 do caminho raiz da instalação)
      path: /home/u/.hermes/hermes-agent
      channel: stable

Por que o salto extra? Porque um mesmo ~/.hermes é rotineiramente compartilhado por várias instalações — o Hermes no host, um gateway em Docker e o app desktop podem todos montar o mesmo config via bind-mount. Com um único interruptor global, virar o seu checkout de desenvolvimento para canary também viraria o feed de atualização do app desktop.

Para ver a identidade e o caminho desta instalação:

hermes update --install-id

Três comandos, não os confunda

Comando	O que faz
hermes update	Aplica uma atualização no canal desta instalação
hermes update --check	Compara com o alvo sem puxar, instalar ou reiniciar
hermes update --plan	Imprime o plano: tipo de instalação (git/Docker/Nix/apt) e cada serviço em execução com seu supervisor
hermes update --set-channel stable	Persiste o canal para esta instalação; não atualiza nada por si
hermes update --channel main	Afeta só esta execução; nada é salvo
hermes update --install-id	Imprime a identidade e o caminho desta instalação

O par que as pessoas confundem é --set-channel contra --channel: o primeiro escreve no config, o segundo evapora quando o comando termina. Se você só quer espiar o que a main tem, --channel main basta e não muda nada no comportamento futuro.

A regra que pega as pessoas de surpresa: o padrão só anda para a frente

Trocar o padrão foi feito de forma conservadora, e a regra é que uma instalação que nunca escolheu um canal só anda para a frente:

• se o seu checkout já contém a release mais recente — digamos que você seguia a main e estava à frente — ele fica onde está até sair uma release mais nova;
• só um --set-channel stable explícito conta como consentimento para parar no commit exato da release, mesmo quando isso significa andar para trás.

Essa regra cobre o --check, o caminho de aplicação e a checagem passiva que o app desktop e o banner de atualização usam. Você não será rebaixado em silêncio por uma atualização perdida, nem ficará preso a código antigo para sempre.

Dois tipos de instalação não são afetados:

• forks e espelhos seguem na main. Eles não têm releases oficiais, então não há stable a seguir;
• instalações empacotadas (MSIX, Store, bundled, electron-updater, de propriedade externa) têm o canal embutido no momento do build e não conseguem mudá-lo.

Desktop: um novo interruptor em Configurações → Sobre

Num install de código-fonte, o app desktop agora mostra uma linha Canal de atualização em Configurações → Sobre → Atualizações, deixando você alternar entre releases Stable e Every commit. Ela só aparece para installs de código-fonte (posix-handoff / windows-handoff); installs empacotadas nunca a veem, porque o canal delas é fixo.

O detalhe de interação é bem pensado:

• main → stable pergunta primeiro, porque esse passo pode te levar a código mais antigo;
• stable → main troca na hora, porque nunca pode te mover para trás.

O GUI e a CLI escrevem o mesmo registro, então uma mudança feita no app é visível para hermes update --check imediatamente.

Três correções que vieram junto

Algumas correções companheiras caíram junto, e as três valem a pena conhecer:

1. A busca de stable costumava sair sem autenticação e bater no limite de requisições anônimo. O código antigo lia releases/latest com uma chamada HTTP crua sem nenhuma credencial, gastando o orçamento anônimo de 60 requisições por hora do GitHub mesmo quando GH_TOKEN estava definido ou o gh estava logado. Atrás de um IP de saída compartilhado de escritório, CI ou Docker esse orçamento acaba rápido, e o 403 resultante era renderizado como ✗ Could not resolve the stable source channel: No published stable release could be verified — o que se lê como “não existe release nenhuma”. A busca agora percorre a escada de tokens (ambiente, depois gh auth token, depois anônimo) e reporta um limite de requisições como limite de requisições, com o horário de reset e, para chamadores anônimos, uma dica para definir GITHUB_TOKEN. Uma busca que falha ainda para onde está e nunca toca no checkout.

2. Checkouts rasos ou offline nunca são arrastados de volta. Se um clone raso ou uma cópia offline já é mais nova que a release mais recente, uma atualização não a “corrige” mais para essa release.

3. Uma falha de dependência de Node só do desktop não derruba mais a TUI e a web UI junto. Esta importa em hosts headless. npm ci instala ui-tui, web e apps/desktop como uma união, e só o app desktop puxa addons nativos (node-pty, electron) que precisam de um compilador. Então um servidor Ubuntu com g++ 9 — que rejeita -std=gnu++20 — falhava a instalação de dependências inteira, a TUI e a web UI nunca eram construídas, e toda inicialização imprimia a source update could not be finished automatically (6 attempts). Agora a instalação tenta de novo uma vez sem o app desktop, constrói a TUI e a web UI como de costume e registra o build do desktop como pendente: Desktop app build owed: desktop dependencies failed. Ela também imprime uma saída genuinamente útil: se este host nunca roda o app desktop, hermes uninstall --gui o remove do checkout para que atualizações futuras parem de construir as dependências nativas dele.

Qual você deve escolher?

• Quer estabilidade (o padrão, e o que a maioria quer): não faça nada, continue rodando hermes update.
• Quer a ponta sangrenta: hermes update --set-channel main restaura o comportamento antigo commit a commit.
• Só quer olhar: hermes update --channel main --check não muda nada a longo prazo.
• Não sabe em que canal está: a primeira linha de hermes update --check te diz.

Uma ressalva se você desenvolve no seu próprio fork: releases oficiais não são suas, então o seu padrão continua main. Essa é a decisão correta — a fonte de atualização de um fork deve ser decisão dele.

A versão curta

Esta mudança transforma a atualização de um fluxo contínuo numa escada com fronteiras de versão: mover-se só entre releases publicadas, não fazer rollback por padrão, manter a escolha por instalação e autenticar a busca como você. Se você roda hermes update todo dia, há só três coisas a lembrar — stable é o padrão, só --set-channel persiste, e a main precisa ser pedida.

Para o panorama mais amplo, comece pela nossa referência do comando hermes update, pelo texto mais antigo sobre atualizações graduais e sobre o que fazer quando uma atualização estoura o seu disco. A release atual é a v0.21.6; se você ainda não instalou o Hermes, o guia de instalação é o lugar para começar.