Gerenciamento e atualização

Instalações do Herdr não possuem collie no PATH; use os IDs de ação do Herdr (Ações do Herdr). Instalações standalone colocam o binário em ~/.local/share/collie/current/bin/collie ou <checkout>/bin/collie:

# the install script's layout
cd ~/.local/share/collie/current && bin/collie version
# a source build or a linked clone
cd ~/my/collie-checkout && bin/collie version

Execute bin/collie link para criar o link simbólico do binário em ~/.local/bin (Coloque collie no seu PATH).

A configuração e o estado ficam fora do checkout e persistem entre atualizações (bridge/solo-baseline.test.ts). O .env e o registro tailscale serve ficam no diretório de configuração, ~/.config/collie em uma instalação binária ou no diretório de configuração de plugins do Herdr em uma instalação do Herdr; dispositivos pareados e stt.json ficam no diretório de estado, ~/.local/state/collie, a menos que COLLIE_STATE_DIR o mova.

Uma instalação via pacote

Onde o seu gerenciador de pacotes instalou o Collie, ele atualiza o Collie, e tudo abaixo desta seção não se aplica:

sudo pacman -Syu collie-bin    # or `nix profile upgrade collie`, or `brew upgrade collie`

O Collie reconhece esta instalação pela estrutura no disco: nenhum .git, nenhum layout versions/, o manifesto incluído no payload do release e uma raiz que é somente leitura, fora do seu diretório home ou pertencente ao root. Qualquer um dos três últimos é suficiente. Ele então se recusa a atualizar no local e indica o comando quando consegue identificar qual gerenciador é o proprietário da pasta:

error: /opt/collie is a packaged install — updates come from your package manager.
       `collie update` will not replace its files.
       Take the new version with: sudo pacman -Syu collie-bin

Onde o prefixo não indica nenhum gerenciador conhecido pelo Collie, ele exibe as duas primeiras linhas e para, em vez de adivinhar um comando que você não pode executar.

O collie doctor relata a mesma instalação como íntegra, e o card de atualização do celular continua mostrando que existe uma versão mais recente — com o comando do pacote no lugar do botão de atualização.

Nota. Esta não é uma limitação a ser contornada. A pasta pertence ao seu gerenciador de pacotes, e substituir seus arquivos sem o conhecimento dele deixaria o banco de dados desatualizado sobre o que está instalado. O sudo collie update se recusa da mesma maneira.

Para usar uma nova versão, execute o seu gerenciador de pacotes e reinicie o serviço:

paru -Syu collie-bin                              # Arch, or your AUR helper of choice
nix profile upgrade collie                        # Nix
mise upgrade --bump github:AltanS/collie          # mise
collie restart

Uma instalação via mise é a exceção: o Collie não a reconhece como empacotada, pois a árvore fica no seu diretório home sem nenhum .git e nenhuma estrutura de versions/, então collie update recusa com cannot tell how this Collie was installed e não indica nenhum gerenciador. O mise ainda é o responsável por ela. Consulte Instalação.

A reinicialização é a parte que o Collie não pode fazer por você, e ela não é opcional. O seu gerenciador de pacotes substitui os arquivos sob a bridge em execução, então esse processo continua executando o código antigo enquanto já reporta a nova versão. O Collie detecta essa incompatibilidade e avisa: collie doctor gera restart-pending, e o celular exibe um aviso de "Bridge restart needed" com o texto "Collie was replaced on disk. Restart it." Ambos desaparecem assim que collie restart for executado.

Em uma crew, um membro instalado via pacote nunca recebe atualizações pelo celular. A crew o lista como "waits for the package manager" e considera a execução concluída sem ele; portanto, os dois comandos acima são os responsáveis por nivelá-lo.

Um lead empacotado recusa apenas a sua própria atualização. O celular ainda nivela todos os membros para a versão que o lead está executando, e uma única confirmação cobre todos eles. Depois que os dois comandos acima atualizarem o lead, nada se nivela sozinho: toque na página Updates mais uma vez e os membros acompanharão a nova versão do lead.

Atualização, pelo celular ou pelo terminal

Existem dois caminhos de atualização, e ambos executam as mesmas etapas em cada host: preparar a nova versão ao lado da ativa, alternar o link simbólico, reiniciar e verificar se o serviço responde. Em um lead da crew, ambos os caminhos cobrem toda a crew. O celular é o caminho mais curto. O terminal é o recurso de contingência para uma máquina que o celular não consegue nivelar.

Pelo celular

Abra Configurações e selecione Updates. O card exibe a versão em execução, a versão mais recente e as versões intermediárias incluídas na atualização. Se o host estiver na versão mais recente, o card informa isso e não oferece nada.

Abaixo disso fica o preflight, com uma linha por verificação: doctor, disk, bun, tree, upstream e service. Em um lead, cada membro da crew também é verificado.

• —
  Verde está livre.
• —
  Vale a pena saber sobre Âmbar e isso nunca bloqueia: divergência de versão em uma crew, um tipo de instalação incomum, uma versão major lançada mas que não está sendo instalada. Arquivos temporários não rastreados em um checkout continuam verdes.
• —
  Vermelho bloqueia a atualização. A linha indica o motivo, como um collie doctor vermelho, menos de 1 GB livre para a compilação preparada, ausência de bun no host ou um upstream inacessível. Onde um comando resolve a situação, o card exibe esse comando como Fix: <command>.

Tocar em Update to <version> solicita confirmação uma única vez, e o texto de confirmação é literal: sua sessão de terminal continua ativa e a visualização no celular cai por até 30 segundos. A reinicialização derruba a bridge, não o seu multiplexador, portanto os agentes continuam rodando e o celular retorna na nova versão. Uma versão major nunca é aplicada em uma atualização de rotina: migrar para uma exige confirmação própria, identifica a versão como uma nova major e instrui você a ler as notas de lançamento primeiro.

Enquanto executa, uma folha cobre a tela. Consulte O que o telefone exibe durante uma atualização abaixo. O card na página Atualizações exibe os mesmos estados em mais detalhes:

Os quatro primeiros indicam progresso; o card informa isso e pede que você mantenha a tela aberta. rolled-back indica a versão em que você ainda está, mostra o final do log do serviço e oferece Tentar novamente. stuck exibe o comando exato para rodar em um terminal. interrupted também oferece Tentar novamente.

Lembrar no próximo resumo descarta o aviso do card. Isso não é um silenciamento: o próximo push aguarda tanto uma versão mais nova quanto uma nova janela.

Com que frequência você recebe avisos. Notificações de atualização funcionam como um resumo, no máximo uma vez por dia, e nunca antes das 09:00 no horário local do host. Um delta composto apenas por versões de patch aguarda uma janela semanal; assim, um trem de patches chega em um único envio em vez de quatro. Uma versão minor ou major mantém a cadência diária e inclui os patches pendentes. Versões retidas são acumuladas, nunca descartadas. Um patch também pode solicitar a cadência diária: uma correção que você precisa aplicar hoje é marcada como urgente ao ser gerada, e o card de atualização passa a exibir um rótulo Urgente com uma frase explicando o motivo. Você recebe o aviso no momento do lançamento ou às 09:00 seguintes. Uma única versão urgente torna diário todo o trem pendente, e a versão continua sendo um patch comum. Uma instalação anterior a esse recurso mantém a janela semanal para um patch urgente até que seja atualizada pela primeira vez. O card sempre exibe o estado atual, independentemente da janela. A preferência de notificação updates, em Configurações → notificações (Web Push), é o único botão para desativar.

Em um lead da crew, o botão mostra Atualizar crew para <version>, e uma única confirmação se aplica a todas as máquinas. O lead atualiza primeiro, sob seu próprio health gate. Cada peer é então nivelado para a mesma versão, um por vez, usando seu próprio preflight, seu próprio health gate e seu próprio rollback. Não há botão individual por peer nem segundo pedido de confirmação. Para detalhes, os dois caminhos de recuperação e o único caso que o telefone não consegue corrigir, consulte Atualizando o restante da crew.

Uma faixa no topo de cada tela mostra o que está pendente em vez do que está em execução: a versão disponível, um peer que não conseguiu atualizar e New version — tap to update quando o app no seu dispositivo está atrás da bridge. Uma atualização em andamento pertence à folha, não à faixa.

O que o telefone exibe durante uma atualização

Uma folha cobre a tela no dispositivo que tocou na confirmação, e todos os outros dispositivos recebem um selo.

A folha contém uma linha por máquina, o líder primeiro, cada uma com sua versão e o estado em que se encontra. Abaixo delas fica a linha do próprio dispositivo, que diz respeito ao app que você está usando e não a uma máquina: assim que a bridge disponibiliza a nova versão, o telefone baixa esse app em segundo plano e a linha conta os arquivos conforme eles chegam. A folha também informa uma vez, em letras pequenas, que a atualização roda nas máquinas e que fechar o app não a interrompe.

O dispositivo que iniciou a execução não pode usar o app atrás da folha. Nada mais fica bloqueado: um segundo telefone ou um tablet exibe uma linha que pode ser tocada para abrir e fechar novamente.

Quando todas as máquinas terminarem e o telefone estiver rodando o novo app, a folha se fecha sozinha e uma mensagem curta indica a versão. Em um crew, lê-se Crew updated to <version>; em uma única máquina, ela exibe o nome dessa máquina.

Uma execução que atualiza apenas os membros, como Retry crew update, assume a tela da mesma forma. A linha do lead mostra already up to date, porque o lead não faz parte dessa execução e não reinicia. O final mostra Members updated to <version>, e um membro que não conseguiu atualizar deixa a folha aberta no celular que iniciou a execução, com o respectivo motivo.

Três estados podem travar, e cada um tem uma saída. Nenhum deles cancela a atualização nem recarrega o app.

Nota. "Ainda baixando, continue usando o app" refere-se ao app no seu celular e nunca à máquina. As máquinas já terminaram; apenas o novo app ainda não chegou. O app que você está segurando continua funcionando e alterna sozinho no momento em que o download terminar.

Pelo terminal

collie update --check            # read-only preflight, --json for a script
collie update --check --local    # the same, this instance only, no crew members
collie update                    # stage, flip, restart, verify
collie update --status           # what the updater did, or is doing, --json for a script
collie update --rollback         # put the previous version back
collie update --major            # cross one major, see below

collie update --help exibe as instruções de uso e não inicia nada. Todo comando collie responde a -h e --help da mesma forma, antes de realizar qualquer trabalho.

Em uma instalação gerenciada pelo Herdr, os mesmos verbos são ações do Herdr:

herdr plugin action invoke update --plugin herdr.collie      # Herdr-managed
bin/collie update                                            # Standalone

collie update --check não altera nada. Ele executa collie doctor, lê o espaço livre, a versão do bun, a working tree, a lista de versões upstream e a unidade de serviço, e em um lead faz a mesma pergunta a cada membro da crew via seu próprio SSH. Ele sai com código 0 a menos que algo esteja em vermelho, e --json exibe um relatório com controle de versão. Adicione --local para verificar apenas esta instância e ignorar os membros da crew. O telefone executa essa verificação local em seu próprio host e lê a linha de cada peer pelo link da crew, portanto seu preflight não precisa de SSH.

collie update busca a versão mais recente da sua major atual e a prepara. O comando então transfere a substituição para um atualizador separado e é encerrado, porque a reinicialização encerra a ponte que solicitou a atualização. Esse atualizador aponta current para a nova versão, reinicia usando o novo binário e consulta GET /api/health por até 30 segundos aguardando uma resposta que traga a versão recém-instalada. Se a resposta não vier, ou vier da versão antiga, ele reverte current e reinicia mais uma vez, registrando rolled-back com o final do log do serviço. Se isso também não subir, ele registra stuck com o comando a ser executado manualmente, e nada reinicia novamente. Ele faz rollback uma vez, nunca duas.

Defina COLLIE_UPDATE_HEALTH_TIMEOUT_MS se 30 segundos não forem suficientes na sua máquina. Uma inicialização a frio lenta que ultrapasse o tempo limite é interpretada como uma atualização com falha e revertida.

collie update --status exibe o registro mantido pelo atualizador, e o telefone lê o mesmo registro. A porta de prontidão de um deputy atende esse registro em /standby/update enquanto a porta principal estiver inativa.

Se um novo evento de hook do beacon estiver disponível, update exibe um aviso para executar hooks install claude novamente.

Após cada atualização, rollback ou troca bem-sucedida, a nova versão executa collie skill sync. Ela instala a skill do walky talky em cada harness de agente nesta máquina e atualiza cópias desatualizadas, para que seus agentes saibam a versão em execução. Ela imprime uma linha para cada arquivo alterado e nunca interrompe a atualização: se não puder executar, update exibe uma nota e você executa collie skill sync manualmente. Ela ignora um harness onde você executou collie skill uninstall. Defina COLLIE_SKILL_SYNC=off para manter seus arquivos de instruções inalterados; a atualização exibirá apenas uma nota quando a skill estiver desatualizada (Instale a skill).

Onde as versões ficam

Uma instalação binária e um clone vinculado compartilham a mesma estrutura sob a raiz de instalação (~/.local/share/collie ou $COLLIE_DIR para uma instalação binária, o próprio clone para um checkout):

current -> versions/v1.3.0
versions/v1.3.0/
versions/v1.2.0/

Em um checkout, cada versions/vX.Y.Z é uma git worktree da tag de versão, compartilhando o único .git, de modo que uma versão custa apenas uma árvore e não um segundo armazenamento de objetos. A compilação roda dentro do novo diretório e grava um marcador de conclusão por último; a alternância é recusada sem esse marcador, portanto uma compilação interrompida deixa a versão ativa intacta. Entrar em produção requer apenas renomear o link simbólico current. A retenção mantém current mais as duas versões anteriores mais recentes, e apenas uma execução bem-sucedida faz a limpeza; assim, uma execução que possa precisar de seu destino de rollback nunca o remove.

Um checkout de Gerenciado pelo Herdr é a exceção e continua avançando no próprio local (ADR 0006, alterado em 2026-09-03). Ele é desanexado e shallow, e reside em um diretório de propriedade do Herdr, portanto não há uma estrutura versions/ ao lado dele, nada para transferir e nada para o qual reverter. --rollback é recusado nesse caso; o caminho de recuperação é uma reinstalação de uma tag específica (herdr plugin install AltanS/collie --ref vX.Y.Z --yes).

Fazer rollback da versão 1.8.0 para a 1.7.0 exige duas edições manuais no diretório de estado. 1.8.0 renomeia os três arquivos de estado na sua primeira inicialização, de modo que ~/.local/state/collie/ agora contém crew-trust.json, crew-ops.json e crew-runtime.json, e uma compilação da 1.7.0 lê apenas os nomes antigos. Renomeie todos os três de volta antes de iniciar a compilação da 1.7.0:

cd ~/.local/state/collie
mv crew-trust.json pack-trust.json
mv crew-ops.json pack-ops.json
mv crew-runtime.json pack-runtime.json

Depois edite dois nomes de chave dentro de pack-trust.json. A 1.8.0 lê o bloco crew sob qualquer uma das grafias e o grava de volta como "crew", com "crewId" dentro dele, onde a 1.7.0 gravava "pack" e "packId". Uma compilação 1.7.0 lê apenas sua própria grafia; portanto, depois que a 1.8.0 tiver gravado o armazenamento — o que acontece em qualquer entrada, rotação, atualização de warrant ou remoção —, renomeie esse bloco de volta para "pack" e seu campo id de volta para "packId". Nada mais dentro dos três arquivos mudou, e crew-ops.json e crew-runtime.json não precisam de nenhuma edição. Se preferir não mexer no arquivo, restaure uma cópia de pack-trust.json feita antes da atualização ou continue na 1.8.0: uma compilação 1.7.0 que não consegue ler o repositório de confiança inicia solo e não impõe nenhuma escala.

Fazer o caminho inverso para a 1.9.0 exige as mesmas duas edições, manualmente. A versão 1.8.x renomeou os três arquivos para você na primeira inicialização; a 1.9.0 não renomeia nada. Portanto, um diretório de estado que nunca viu a 1.8.x ainda mantém os nomes da 1.7.0, e um build da 1.9.0 lê apenas os nomes da crew. Ele avisa isso na inicialização, informa as duas edições e fica solo em vez de adotar o diretório. Faça-as antes de iniciá-lo:

cd ~/.local/state/collie
mv pack-trust.json crew-trust.json
mv pack-ops.json crew-ops.json
mv pack-runtime.json crew-runtime.json

Depois renomeie dois nomes de chave dentro de crew-trust.json: o bloco "pack" vira "crew", e cada "packId" dentro dele vira "crewId". Nada mais nos três arquivos muda. Um arquivo deixado com o nome antigo não custa dados, custa apenas a crew: esse collie inicia solo até ser renomeado.

Verifique

bin/collie update --status
herdr plugin action invoke version --plugin herdr.collie
bin/collie version

Espere a tag mais recente.

O pacote do próprio telefone é algo separado. O PWA verifica se há uma nova versão por conta própria e recarrega em cerca de um minuto, retendo esse recarregamento durante a execução de uma atualização. Se você estiver no meio de uma tarefa, ele exibe um aviso "toque para atualizar" e aguarda seu toque.

No Windows

Um checkout de código-fonte nunca se atualiza sozinho no Windows; uma instalação via zip sim. collie update e o botão Update do telefone informam isso em uma frase em um checkout de código-fonte e não alteram nada. Migrar para a instalação via zip é um passo manual único:

collie uninstall
powershell -ExecutionPolicy Bypass -File .\install.ps1

Depois disso, o collie update funciona a partir do terminal e do celular. Essa sequência foi testada em uma VM com Windows 11 contra uma cópia local dos arquivos de release, mas a migração em si não foi. As versões até a v1.15.0 (inclusive) também não conseguiam substituir um collie.exe em execução. Consulte Collie no Windows.

Se a versão não mudou

collie update consulta o GitHub diretamente a cada execução: git ls-remote para um checkout e a API de tags do GitHub para uma instalação binária. Ele não mantém cache da lista de versões. Uma versão lançada segundos atrás ainda pode levar um minuto para aparecer, pois o próprio GitHub precisa de um momento para se atualizar. Execute collie doctor em seguida. Se isso não explicar, veja Quando o collie não rodar.

Se o GitHub limitar a taxa de verificação de releases

collie update em uma instalação binária lista as releases pela API do GitHub, assim como o banner de atualização do telefone e install.sh. O GitHub permite 60 chamadas de API por hora para usuários anônimos, contabilizadas por endereço de rede; portanto, todas as máquinas atrás do mesmo roteador compartilham essa cota. Quando ela se esgota, a verificação falha de forma segura e não altera nada:

error: GitHub rate-limited the release check (HTTP 403). Wait an hour, or set GH_TOKEN
       to a GitHub token with no scopes, so the limit is yours (docs/upgrading.md).
       Nothing was changed.

Um token torna o limite seu próprio. O Collie lê um do ambiente e nunca pede um:

O primeiro definido tem precedência. A lista de tags é pública, então o token precisa de nenhuma permissão: um personal access token detalhado com acesso ao repositório definido como Public repositories (read-only) e nenhuma permissão selecionada, ou um token clássico sem nenhum escopo marcado. Não use um token com permissão de escrita.

Para uma única execução em um terminal, pegue a credencial da CLI gh emprestada. O valor nunca vai parar na linha de comando nem no histórico do shell:

GH_TOKEN=$(gh auth token) collie update

Para o serviço, coloque-o no .env da instância, que o Collie mantém em modo 600, ou em config.toml sob [update], e reinicie: a bridge lê o token quando inicializa, então o banner do telefone só usa um token novo ou alterado após collie restart. collie config o mostra como set ou unset e nunca imprime o valor. O token vai apenas para api.github.com: o download da release vem de github.com, que não tem esse limite, e nunca o transporta. Uma mensagem que menciona o token cita o nome da variável de onde ele veio, nunca o valor. Um token rejeitado pelo GitHub falha na verificação com HTTP 401 e esse nome, para que um token incorreto não seja confundido com limite de taxa. A bridge registra a mesma mensagem uma vez em seu log e mantém a última release identificada, portanto um banner que para de atualizar após a expiração de um token corresponde a essa linha de log; collie update --check o cita sempre que você consultar.

collie update --check relata os mesmos três casos sob upstream. Um checkout lista as tags usando git ls-remote, o que não conta para o limite da API. Em um crew, cada máquina lê seu próprio token: um membro atualiza executando seu próprio collie update, a partir do seu próprio .env.

Mudar de versão principal

update nunca avança uma versão principal automaticamente.

herdr plugin action invoke update-major --plugin herdr.collie     # Herdr-managed
bin/collie update --major                                         # Standalone

Isso avança uma versão principal para sua versão estrita mais recente. Não tem como alvo versões de pré-lançamento (ADR 0020). Veja também: Atualizando da 0.x para a 1.0.

Se falhar com "Você não está atualmente em uma ramificação"

Instalações do GitHub anteriores à 0.23.1 não têm uma referência de rastreamento de branch (#63). Reinstale para restaurar a funcionalidade de atualização:

# replaces the checkout, rebuilds the UI
herdr plugin install AltanS/collie --yes
# reinstall doesn't restart the service
herdr plugin action invoke restart --plugin herdr.collie
# expect 0.23.1 or newer
herdr plugin action invoke version --plugin herdr.collie

Sua configuração no diretório de configuração de plugins do Herdr, ~/.config/herdr/plugins/config/herdr.collie por convenção, é mantida.

Atualizando o restante da crew

collie crew update <member>…      # on the lead
collie crew update --all

Esse é o caminho pelo terminal, para um peer que o celular não consegue sincronizar. Do celular, atualize toda a crew com um toque e uma confirmação: abra Configurações → Sistema → Atualizações no lead e selecione Atualizar crew para <version>. A verificação prévia acima do botão cobre todos os membros, não apenas o lead. Se uma verificação falhar em qualquer lugar, o botão é desativado e indica a máquina com falha e o motivo.

O lead atualiza primeiro, sob seu próprio controle de integridade. Somente depois de ele estabilizar o primeiro peer é iniciado. A partir da 1.7.0, essa ordem também importa para as palavras: um lead anterior à 1.7.0 lê o status de um membro pela primeira linha impressa, e um membro 1.7.0 imprime crew … onde um 1.6.0 imprimia pack …, de modo que um lead não atualizado não consegue lê-lo. Um lead 1.7.0 lê ambos. Cada peer então se iguala a si mesmo: ele lê a versão que seu lead está executando, busca essa tag exata no GitHub e executa sua própria verificação prévia, seu próprio controle de integridade e seu próprio rollback. Os peers mudam um de cada vez. A página Atualizações mantém uma linha por membro: waiting, checking, staging, restarting, verifying, updated, rolled back ou unreachable.

Um membro se atualiza no máximo uma vez por hora. Um membro que se atualizou dentro dessa hora, por exemplo manualmente, aguarda com rate-limited, retries in about N min abaixo de sua linha, e a execução continua assim que esse tempo passar. Se a atualização do próprio lead for revertida, os membros não são alterados, e suas linhas informam isso. Uma nova atualização aguarda até que a execução da crew termine, no máximo 2 horas.

1.7.0 para 1.8.0. O lead primeiro de novo, por um segundo motivo: a versão 1.8.0 renomeia os caminhos de rede, as duas chaves de ambiente, os três arquivos de estado e o prefixo do journal para crew. Um lead na 1.8.0 responde aos caminhos /pack/v1/* antigos durante uma versão, para que um membro ainda na 1.7.0 acompanhe a transição pelo link que já possui. Ambas as grafias antigas deixam de existir na 1.9.0. Os nomes e o que cada um faz na sua máquina estão em Atualizando para 1.9.0 a partir da 1.7.0 ou 1.8.x. Atualize todos os membros para a 1.8.x antes de migrar o lead para a 1.9.0: a 1.9.0 não responde a nada nos caminhos antigos, e um membro ainda na 1.7.0 passa a aparecer em vermelho no preflight do lead, indicando ambas as versões e o comando a ser executado nessa máquina. O asset collie-release.json publicado pela versão alimenta o texto desse aviso na faixa, no cartão Updates e no push diário, sem jamais alterar o que uma atualização faz. Ele também informa à verificação que uma versão foi lançada: uma tag cujo asset ainda retorna 404 não é oferecida, e a próxima verificação tenta novamente.

Dois requisitos determinam se um peer pode acompanhar o processo:

• —
  Um peer precisa de HTTPS de saída para github.com. É daí que vem o código dele. Sem esse acesso, o peer é reportado como desatualizado e, em vez disso, é sincronizado pelo terminal, usando o comando acima.
• —
  Uma compilação -dev+ nunca acompanha a atualização. Uma máquina em uma compilação de desenvolvimento permanece nela, não importa o que o lead esteja executando.

Um peer que faz rollback informa isso na página Atualizações e não tenta de novo sozinho. Dois caminhos oferecem uma nova tentativa:

• —
  Pelo celular. Quando o lead estiver atualizado e um peer estiver atrás, o botão exibe Retry crew update. Ele inicia uma nova execução cujas únicas etapas são os peers, e essa nova execução é o que concede a cada um deles mais uma tentativa.
• —
  Pelo terminal, no lead. Use isto para um peer que o celular não consegue nivelar de forma alguma. O comando permanece o mesmo:

collie crew update <member>…      # on the lead
collie crew update --all

Executá-lo no lead é uma sequência única via seu próprio SSH. Ele faz a validação prévia de cada máquina primeiro e exibe o relatório de cada peer ao lado da resposta obtida via SSH, deixando qualquer divergência explícita em vez de fazer uma média. Ele pede uma única confirmação. Em seguida, atualiza o próprio lead, caso o lead ainda não esteja executando a build que está distribuindo. Depois, assume cada peer por vez: o commit do lead é enviado para o peer como um git bundle, reconstruído, reiniciado e monitorado até responder com a nova build dentro do mesmo limite de 30 segundos. Um lead sem checkout git, vindo da instalação standalone ou de um pacote, não tem commit para enviar, então instala em cada peer a release que ele próprio executa, via o mesmo ssh e fixado nessa tag; um peer em execução a partir de um checkout git é então ignorado, com collie update --to-tag v<version> indicado na sua linha.

A primeira falha interrompe a execução. Cada membro subsequente permanece intocado e é marcado como "not attempted", e o resumo indica o comando exato que resolve a falha. Um lead que não consegue aplicar a própria atualização não mexe em nenhum peer. Interromper aí é seguro, porque a crew tolera divergência de versões (CREW_PROTOCOL.md §7.1), de modo que uma crew parcialmente atualizada é um estado suportado, enquanto continuar não é.

Um caso que o celular não consegue corrigir. Se você reverter o lead manualmente, com git ou copiando arquivos, depois que seus pares se nivelaram, os pares ficarão à frente do lead. O Collie não detectou a reversão, portanto nenhum membro faz downgrade. Uma reversão feita pelo Reverter do telefone ou com collie update --rollback, e uma troca de volta para Stable, fazem o downgrade dos membros. Consulte "The crew follows the lead" em Linhas de versão. Essas duas execuções são as únicas que movem um membro para uma versão inferior, pois um lead que pudesse reverter um par livremente poderia movê-lo para qualquer versão. O descompasso decorrente de uma reversão manual é inofensivo, e a solução é collie crew update <member> no lead.

O código chega a um peer pelo seu SSH e nunca pelo link da crew (ADR 0016, adendo 2026-09-04). Quando um peer se nivela, seu código vem do GitHub por HTTPS anônimo e o peer decide por si próprio. O lead apenas informa a versão que está rodando e qual peer pode prosseguir.

Se o próprio atualizador travar

Nada acima ajuda se o atualizador tiver sumido. Este é o caminho que assume apenas um terminal.

O atualizador grava um registro, <state dir>/update.json (por padrão ~/.local/state/collie/update.json, ou sob $COLLIE_STATE_DIR). Leia-o primeiro: ele indica o estado, a versão de onde a execução partiu, a versão para a qual ia, o pid do atualizador e, em caso de falha, o final do log de serviço e o comando de recuperação.

Uma atualização iniciada pelo celular não imprime nada no seu terminal. No Linux com um gerenciador de usuário do systemd, ela roda em uma unidade temporária própria, chamada collie-api-update-<stamp>, e o --collect remove essa unidade assim que ela termina, de modo que sua transcrição fica apenas no journal:

journalctl --user -u 'collie-api-update-*' --since '30 min ago'

Em todos os outros lugares, incluindo o macOS, a saída do próprio atualizador vai para um arquivo no diretório de estado:

cat ~/.local/state/collie/update-runner.log

Cada atualização iniciada pelo celular esvazia esse arquivo e mantém a execução anterior como update-runner.log.1. No nível do systemd, o arquivo contém apenas a única linha que o systemd-run imprime, e o journal acima contém o restante.

Um membro da crew pode permanecer na versão antiga após uma atualização da crew. O checkout dele passa a exibir a nova tag, mas /standby/health ou o rodapé ainda mostram a build antiga. Verifique se nenhum atualizador está em execução com systemctl --user list-units 'collie-api-update-*'. Se nenhum estiver rodando, execute collie update nessa máquina. Isso recompila um checkout cuja build não foi concluída.

Uma execução que desiste antes da troca, por exemplo uma nova versão que não inicia nesta máquina, não altera nada no disco. O celular que a iniciou informa que a atualização falhou nessa máquina e apresenta o motivo, e o mesmo motivo é o campo reason de update.json.

É aí que você deve olhar quando o celular indicar sucesso mas algo adiante não acontecer; por exemplo, um aviso de que o registro de execução não pôde ser gravado, o que significa que o lead se atualizou mas não nivelará a crew. O próprio journal do bridge traz a outra metade: uma linha [crew] update <run id>: levelling peers to <version> por execução, quando o lead lê o registro. Antes da 1.8.0, esse prefixo era [pack]. Se essa linha não existir, as etapas nunca começaram.

Atualização anterior à versão 1.5.4 travada no bunx

Antes da versão 1.5.4, as atualizações iniciadas pelo celular rodavam em uma unidade de usuário efêmera do systemd que não herdava seu PATH. Quando o Bun fica apenas em ~/.bun/bin em uma instalação via checkout, o checkout avança, mas a recompilação falha com bunx: command not found. Corrija isso rodando collie update uma vez a partir de um terminal onde o Bun esteja no PATH, ou execute a ação do Herdr, cujo shim localiza o Bun sozinho. Qualquer um dos métodos recompila o checkout atualizado. A partir da versão 1.5.4, o atualizador localiza o Bun por conta própria.

Ao lado dele fica <state dir>/update.lock, contendo um pid e um timestamp. Uma execução por vez. Um registro que ainda contenha preflight, staging, restarting ou verifying, não tenha mudado por 10 minutos e cujo pid não esteja mais na tabela de processos, é considerado encerrado: ele passa a ser lido como interrupted, e uma nova execução pode obter o lock.

Para voltar à versão anterior manualmente, aponte current para ela e reinicie:

cd ~/.local/share/collie        # or $COLLIE_DIR, or the checkout root
ls versions/
ln -sfn versions/<previous> current
collie restart

Ou deixe a versão anterior fazer a mesma coisa por você, que é o comando informado em um registro stuck:

~/.local/share/collie/versions/<previous>/bin/collie update --rollback

Use o caminho completo, não collie: o nome no seu PATH é resolvido através de current, e current é justamente o que pode estar incorreto.

O que a validação de integridade não detecta

A validação garante apenas uma coisa: o serviço voltou a responder a /api/health com a versão que foi instalada. Essa é uma promessa restrita, não uma garantia de "nunca quebrar". Quatro problemas podem ocorrer enquanto a validação reporta sucesso:

• —
  Um pacote web desatualizado no celular. O host está na versão nova e o celular ainda roda JavaScript antigo a partir do seu service worker. O PWA substitui seu próprio pacote no seu próprio tempo; a validação de integridade não tem visibilidade disso.
• —
  Migrações de schema ou configuração. O Collie não distribui migrações nessa frequência, e o atualizador não roda nenhuma. A validação apenas checa se o serviço responde, não se seus dados estão no formato correto.
• —
  Um driver de mux que quebra apenas na interação. A bridge inicia e responde ao health enquanto o adapter falha no primeiro attach ou send real. O health é uma verificação de liveness, não uma execução de conformidade.
• —
  O atualizador executando o código da versão antiga. O atualizador desanexado é iniciado a partir da versão que está sendo substituída. Ele é mantido pequeno e estável e seu registro é versionado, de modo que um atualizador antigo e uma nova bridge ainda se entendem, mas isso é uma mitigação e não uma garantia.

Resolvendo a versão mais recente a partir de um script

Consulte as tags do git e ordene por semver. Evite GET /repos/AltanS/collie/releases/latest, que exclui versões de pré-lançamento.

# newest stable release
git ls-remote --tags --refs https://github.com/AltanS/collie | \
  sed 's#.*refs/tags/##' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1

Linhas de versão

Cada máquina fica em uma de duas linhas de versão. O padrão é Stable.

• —
  Stable aceita apenas versões finais, por exemplo 1.23.0.
• —
  Edge também aceita builds Edge, por exemplo 1.23.0-edge.2. Um build Edge é um pré-lançamento do GitHub, gerado a partir da mesma árvore alguns dias antes da versão final. Ele chega primeiro aos voluntários, permitindo que uma regressão seja encontrada antes de alcançar todos.

Defina a linha no telefone: Settings → Updates → Release line. A troca não instala nada. Ela salva a linha e exibe um comprovante. O cartão Updates passa a oferecer o que a nova linha disponibiliza, por meio da tela normal de atualização.

• —
  No Edge, a oferta é o build mais recente acima daquele que você executa, combinando builds Edge e versões finais, na mesma versão principal. Uma versão final substitui seus próprios builds Edge em ambas as linhas.
• —
  Um build do qual esta máquina foi revertida nunca mais é oferecido, em nenhuma das linhas.
• —
  No Edge, o push sobre um novo build é enviado na verificação seguinte, e não no próximo resumo. Ele ainda aguarda até as 09:00 no horário local. A Stable mantém as janelas de resumo.

O ritmo esperado no Edge. Espere no máximo cerca de um build Edge por dia, e cada um traz uma alteração perceptível. O bridge verifica novos builds a cada seis horas. Você recebe um push por build, e nunca antes das 09:00 no horário local do host. Quando uma verificação encontra vários novos builds, eles são agrupados em um único push. A barra de atualização pergunta uma vez por build, e você pode ignorar um build: a atualização seguinte instalará o mais recente. Dispensar a barra se aplica apenas àquela versão, portanto o build seguinte perguntará novamente.

Voltar para a Stable. Troque para Stable em uma máquina que executa um build Edge, e a página exibirá um de três casos:

1. 01
   Uma versão final igual ou superior ao seu build foi lançada. O cartão Updates a oferece como uma atualização normal.
2. 02
   Seu build Edge está à frente de qualquer versão final. A página oferece duas opções: - Voltar agora instala a versão final mais recente abaixo do seu build, após confirmação. Ela usa o build Stable que esta máquina guardou, se houver um, e faz o download caso não haja. Se um arquivo de estado no seu build não puder ser lido por essa versão, a página lista o arquivo antes do botão. - Aguardar pela Stable mantém seu build. Nenhum outro build Edge será oferecido, e a próxima versão final será oferecida no dia do lançamento.
3. 03
   Você já executa uma versão final. Não há nada a fazer.

Builds retidos. Enquanto uma máquina estiver no Edge, ela mantém o build ativo, o build anterior e o último build Stable. O último build Stable não é removido até que a máquina volte para a Stable, portanto "Voltar agora" é uma troca e não um download.

Reverter. Uma reversão a partir de um build Edge coloca a máquina na Stable e marca aquele build como revertido. Isso se aplica ao Reverter no telefone e ao collie update --rollback. Um build Edge que falha em sua própria verificação de integridade é revertido pelo atualizador e marcado da mesma forma, para não ser oferecido novamente. A linha permanece como Edge, e o próximo build Edge é oferecido normalmente.

A crew segue o lead. A linha do lead é a linha da crew. Um membro acompanha seu lead para um build Edge quando o lead está no Edge, e assume a linha do lead como sua. Um membro faz downgrade apenas quando o lead foi revertido ou retornou para a Stable. Esses são os dois únicos casos em que um membro instala uma versão inferior. A página Crew mostra a linha que os membros seguem.

A partir do terminal. O telefone é onde a linha é definida. Existem duas flags para uso único em execuções pontuais:

collie update --line edge                     # resolve this one run on Edge; the saved line stays
collie update --to-tag v1.22.6 --downgrade    # go down to a lower final release

--to-tag nunca aceita uma tag menor sem --downgrade. Ele só aceita uma tag Edge maior em uma máquina no Edge. Em uma instalação gerenciada pelo Herdr, ambas as linhas e o caminho de volta passam pela mesma atualização no local: o atualizador faz checkout da tag e grava o sufixo Edge diretamente nos arquivos de versão.

Pré-lançamentos

Instalações estáveis não recebem versões de pré-lançamento. Builds Edge são a exceção, na linha Edge (veja Linhas de versão). Ao optar por uma versão de pré-lançamento, você acompanha os pré-lançamentos daquela versão principal até a chegada do lançamento final (ADR 0020):

# Standalone — the install script's opt-in flag takes the newest prerelease
curl -fsSL https://colliepwa.dev/install.sh | sh -s -- --beta

# Herdr-managed — install the tag; that is the whole opt-in
herdr plugin install AltanS/collie --ref <tag> --yes
# a reinstall does not restart the service
herdr plugin action invoke restart --plugin herdr.collie

Resolva <tag> usando Resolvendo a versão mais recente a partir de um script.

Para retornar às versões estáveis:

herdr plugin install AltanS/collie --yes
herdr plugin action invoke restart --plugin herdr.collie

Atualizando para 1.24.0

A versão 1.24.0 adiciona pontos de uso, um botão Parar e um layout para telas grandes. Se você vem da versão 1.23.4, nada precisa ser feito no dia da atualização. O que você vai notar:

• —
  O Collie não altera sua statusLine. O ajuste de quebra de linha é opcional com collie hooks install claude --statusline. Se você pegou o ajuste de um build Edge e quer removê-lo, execute collie hooks uninstall claude e depois collie hooks install claude (O Collie grava hooks nas próprias configurações do Claude).
• —
  O ponto de contexto não precisa de um hook novo. Os hooks instalados pela 1.23.4 já incluem SessionStart e executam o mesmo comando. O novo Collie lê o arquivo de sessão com eles. Se você nunca executou collie hooks install claude, execute uma vez. Uma sessão do Claude já em execução não mostra nenhum ponto até ser reiniciada, retomada, limpa ou compactada, pois o tamanho da janela vem do início da sessão.
• —
  Os pontos de 5 horas e 7 dias leem seus próprios logins. Para o Claude, o Collie lê o arquivo de login nesta máquina e consulta api.anthropic.com. Para o Codex, ele lê os arquivos de sessão do Codex e não consulta ninguém. Ambos ficam ativados por padrão. Defina COLLIE_ACCOUNT_WINDOWS=0 no seu .env, ou account_windows = false sob [bridge], para desativá-los. OpenCode Go e Grok permanecem desativados até você especificá-los (Janelas de uso).
• —
  Um botão Parar, um botão Limpar e Direcionar. O botão Parar exige dois toques e envia a tecla de parada do próprio agente (Parar um turno). Limpar esvazia a caixa de entrada, e Restaurar digita o texto de volta por dois minutos (Limpar a caixa). Mantenha Enviar pressionado para direcionar um turno em execução no pi, Codex e OMP (Direcionar ou enfileirar).
• —
  Um tema que define pane-active é da versão 3. Um Collie anterior à versão 1.24.0 recusa esse arquivo com uma mensagem informando a versão. Os outros temas mantêm sua versão (Versões).
• —
  Uma tela larga mostra uma barra lateral. A partir de 600px de largura e 480px de altura, a tela do painel mostra vários painéis lado a lado. Para manter o layout de celular em um dispositivo, defina Layout para telas grandes como Off nas Configurações.

Atualizando para 1.19.0

A versão 1.19.0 move a inicialização de itens para uma única página e permite que cada telefone configure seus próprios Keys e inicializadores. Nada precisa ser feito no dia da atualização. O que você vai notar:

• —
  O painel New é uma página. + Novo no dashboard abre /new, com a máquina, uma seleção de Agent ou Command, a pasta e a opção Nova worktree. O painel new-space, seu rótulo de espaço e sua lista de worktrees existentes foram removidos. Abra um worktree existente com herdr worktree open na máquina (Inicie um agent ou shell pelo telefone).
• —
  Um membro da crew precisa ser atualizado para iniciar agentes pelo nome. A página lista um membro que executa uma versão mais antiga do Collie, com suas opções desativadas. Atualize o líder primeiro, e os membros em seguida (Iniciando algo em uma máquina).
• —
  Telefones podem adicionar inicializadores. Com o padrão [phone] adds = true, um telefone pareado pode adicionar até 20 linhas a uma máquina, mantidas em launchers-added.json. Defina adds = false em launchers.toml para desativar isso (Inicializadores adicionados de um telefone).
• —
  O teclado de Keys é um painel. Ele começa como o teclado que você tinha, e cada navegador mantém sua própria organização (Seu próprio painel de teclas). Predefinições em keys.toml não são alteradas.
• —
  Um nome simples de pasta é uma pasta sob a home. projects no campo Folder agora significa ~/projects, e uma pasta inexistente é recusada com um aviso.

Atualizando para 1.18.0

A versão 1.18.0 torna o pareamento obrigatório tanto para leituras quanto para gravações (ADR 0086). O que muda no dia da atualização:

• —
  Celulares pareados continuam funcionando. O token armazenado deles já atende à nova regra. Nada precisa ser feito.
• —
  Navegadores não pareados veem a tela de pareamento. Um navegador desktop nunca pareado, que antes conseguia ler, agora recebe 403 device not paired. Execute collie pair no host e insira o código em Configurações nesse navegador (Parear um dispositivo).
• —
  Um app instalado pode manter as telas antigas por mais um carregamento. Um app instalado ainda pode exibir as telas da versão anterior até que seja carregado mais uma vez. Se ele exibir "Sign in" após a atualização para a versão 1.18 ou posterior, recarregue o app ou feche-o e abra-o novamente. Em seguida, faça o pareamento conforme descrito acima.
• —
  Scripts precisam ser pareados uma vez. Um script que lia a API sem um token agora recebe 403. Execute collie pair --expires 30d e depois resgate o código com um POST para /api/pair que contenha {"code": "...", "label": "script"} e um cabeçalho Origin de mesma origem. O token é retornado uma única vez, nessa resposta. Envie-o como Authorization: Bearer <token> em todas as chamadas posteriores. Armazene-o como uma senha.
• —
  CLIs no host não precisam de nada. collie doctor, collie history e a varredura de atualização da equipe leem a sua própria bridge com uma credencial local gravada por ela no diretório de estado.
• —
  Fazer rollback para uma versão anterior a 1.18.0 ignora a expiração de tokens. Uma bridge mais antiga não reconhece o campo expiresAt, portanto um dispositivo expirado volta a funcionar até que a bridge seja atualizada. Revogue-o com collie devices revoke <label> se isso for importante (Definir uma expiração para um dispositivo).
• —
  Arquivos de auditoria antigos podem conter caracteres digitados. Arquivos gravados antes da 1.18.0 podem listar caracteres digitados no celular. Faça a rotação ou exclua arquivos audit.log anteriores à atualização.
• —
  A máscara de segredos pode atrapalhar. Corpos de arquivo em Arquivos e diffs em Alterações agora passam pela mesma máscara de segredos do texto do painel. Se ela ocultar algo necessário, defina COLLIE_REDACT=off no seu .env e reinicie (configurar).
• —
  Um lead 1.18.0 também mascara o texto dos seus membros. Um membro ainda na versão 1.17.x não aplica máscara, portanto o lead mascara o texto desse membro antes que o seu celular o receba. Para ver o texto de um membro sem máscara, defina COLLIE_REDACT=off no lead e também no membro.

Atualizando da 0.x para a 1.0

Se BUN_INSTALL estiver definido apenas em .env, exporte-o no perfil do seu shell ou no ambiente do serviço. Em seguida, execute:

# Herdr-managed
herdr plugin action invoke update-major --plugin herdr.collie

# Linked clone
bin/collie update --major

Verifique com bin/collie version ou herdr plugin action invoke version --plugin herdr.collie.

Para configurações de crew: Atualize o lead primeiro, depois execute collie crew update <member>… (Atualizando o restante da crew). Nota:

• —
  join requer --insecure para leads http:// simples.
• —
  Tokens de convite anteriores à versão 1.0 devem ser gerados novamente com crew invite.
• —
  Registros de membros mais antigos requerem reconnect.
• —
  Peers não atualizados são exibidos como warn: em crew status (CREW_PROTOCOL §7.1).

O que a versão 1.0 muda para você

Os IDs de ação do Herdr e as rotas scripts/collie-ctl.sh permanecem inalterados (ADR 0006).

Os verbos da CLI são compilados em <checkout>/bin/collie (Comandos). Use bin/collie link para adicionar collie ao PATH (Coloque collie no seu PATH, ADR 0021).

Novos recursos:

• —
  pair / devices: Credenciais de gravação por dispositivo (Parear um dispositivo).
• —
  crew … / join / promote: Clustering multi-host (Comandos de crew).
• —
  doctor: Diagnósticos de configuração.
• —
  stt setup: Configuração do compositor de voz (Entrada de voz).
• —
  hooks install claude / beacon emit: Beacons de atividade do agente (Beacons de agentes).
• —
  COLLIE_MUX: selecione herdr (padrão), tmux ou zellij (tmux e zellij).

Lado a lado, se o rebanho for real

A configuração de instâncias secundárias está documentada em Várias instâncias do Collie em um único host.

Revertendo a versão

Faça checkout da última tag 0.x e recompile:

last0x=$(git ls-remote --tags --refs origin | sed 's#.*refs/tags/##' | \
  grep -E '^v0\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
git fetch --depth 1 origin tag "$last0x"
git checkout --detach --force "$last0x"
rm -f bin/collie    # 1.0's binary otherwise survives the rollback

Recompile com bash scripts/collie-ctl.sh build e execute a ação restart do Herdr. Os arquivos de estado (crew-trust.json, crew-runtime.json, paired-devices.json, pairing-pending.json) podem ser mantidos. A reversão remove a exigência de pareamento de dispositivos; configure COLLIE_DEVICE_HEADER se a proteção contra escrita for necessária.

Verifique se funcionou

Verifique se version informa 1.0.0 ou superior. Uma instalação atualizada não pareia nenhum dispositivo automaticamente: execute pair para emitir a credencial de escrita para um telefone e devices revoke se esse telefone for perdido (Parear um dispositivo).

Interromper ou desinstalar

Pause o serviço:

herdr plugin action invoke stop --plugin herdr.collie     # Herdr-managed
bin/collie stop                                           # standalone

Remova a definição do serviço e os mapeamentos de porta (.env e os checkouts são preservados):

herdr plugin action invoke uninstall --plugin herdr.collie   # Herdr-managed
bin/collie uninstall                                         # standalone

Para excluir o programa e também seus próprios arquivos, siga os três passos em Instalar → Desinstalar, que os detalha por tipo de instalação, pacotes incluídos.

Quando o collie não rodar

Para instalações binárias (~/.local/share/collie ou $COLLIE_DIR), execute um binário mais antigo diretamente:

ls ~/.local/share/collie/versions/
~/.local/share/collie/versions/<previous>/bin/collie update --rollback

Para instalar uma versão específica diretamente:

curl -fsSL https://colliepwa.dev/install.sh | COLLIE_TAG=v1.0.0 sh

Para checkouts ou instalações via Herdr, execute git checkout <tag> ou herdr plugin install AltanS/collie --ref vX.Y.Z --yes.

Você usa um fork

collie update compara origin com COLLIE_UPDATE_REPO (padrão AltanS/collie) e aborta se forem diferentes. Defina COLLIE_UPDATE_REPO=you/collie se o seu fork publicar tags próprias.

Para mesclar atualizações do upstream no seu fork manualmente:

git remote add upstream https://github.com/AltanS/collie.git
git fetch upstream --tags
git merge v1.0.0                                            # the tag you decided to take
# resolve the conflicts, commit the merge, then rebuild and restart:
bash scripts/collie-ctl.sh build
# Herdr-managed: invoke the `restart` action instead
bin/collie restart

Não use update --major em um fork; mescle a tag v1.* manualmente. Execute collie doctor para verificar o COLLIE_UPDATE_REPO ativo.

Persistindo após reinicializações

No Linux, ative o lingering para serviços de usuário autônomos:

loginctl enable-linger $USER

Verifique o status com systemctl --user status collie.

No macOS, o start gerencia o ~/Library/LaunchAgents/herdr.collie.plist automaticamente. Ele é executado no login do usuário. Verifique o status com launchctl print gui/$(id -u)/herdr.collie.