Gérer et mettre à jour

Les installations Herdr n'ont pas de collie dans le PATH ; utilisez les identifiants d'action Herdr (Actions Herdr). Les installations autonomes placent le binaire dans ~/.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

Exécutez bin/collie link pour créer un lien symbolique vers le binaire dans ~/.local/bin (Ajoutez collie à votre PATH).

La configuration et l'état se trouvent hors du checkout et persistent lors des mises à jour (bridge/solo-baseline.test.ts). .env et l'enregistrement tailscale serve se trouvent dans le répertoire de configuration, ~/.config/collie sur une installation binaire ou le répertoire de configuration des plugins de Herdr sur une installation Herdr ; les appareils associés et stt.json sont dans le répertoire d'état, ~/.local/state/collie sauf si COLLIE_STATE_DIR le déplace.

Une installation par paquet

Si votre gestionnaire de paquets a installé Collie, il met à jour Collie, et rien en dessous de cette section ne s'applique :

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

Collie reconnaît cette installation à sa disposition sur le disque : pas de .git, pas de structure versions/, le manifeste transporté par la release, et une racine en lecture seule, hors de votre répertoire personnel ou appartenant à root. L'un quelconque des trois derniers critères suffit. Il refuse alors la mise à jour sur place et indique la commande s'il identifie le gestionnaire auquel appartient le dossier :

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

Si le préfixe n'indique aucun gestionnaire connu de Collie, il affiche les deux premières lignes et s'arrête plutôt que de deviner une commande impossible à exécuter.

collie doctor signale la même installation comme saine, et la carte de mise à jour sur le téléphone montre toujours qu'une version plus récente existe, avec la commande du paquet à la place du bouton de mise à jour.

Remarque. Il ne s'agit pas d'une limitation à contourner. Le dossier appartient à votre gestionnaire de paquets, et remplacer ses fichiers sans passer par lui fausserait sa base de données quant à ce qui est installé. sudo collie update refuse de la même façon.

Pour adopter une nouvelle version, exécutez votre gestionnaire de paquets puis redémarrez le service :

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

Une installation via mise fait exception : Collie ne la considère pas comme empaquetée, car l'arborescence réside dans votre répertoire personnel sans structure .git ni versions/ ; collie update refuse donc avec cannot tell how this Collie was installed et n'indique aucun gestionnaire. mise la gère toujours. Consultez Installer.

Le redémarrage est l'étape que Collie ne peut pas effectuer à votre place, et il n'est pas facultatif. Votre gestionnaire de paquets remplace les fichiers sous le bridge en cours d'exécution ; ce processus continue donc d'exécuter l'ancien code alors qu'il signale déjà la nouvelle version. Collie détecte cette incohérence et le signale : collie doctor émet restart-pending, et le téléphone affiche une bannière « Bridge restart needed » indiquant « Collie was replaced on disk. Restart it. » Les deux disparaissent dès que collie restart a été exécuté.

Dans un crew, un membre empaqueté n'adopte jamais de mise à jour depuis le téléphone. Le crew l'affiche sous l'état « waits for the package manager » et considère l'exécution comme terminée sans lui ; ce sont donc les deux commandes ci-dessus qui le mettent à niveau.

Un lead empaqueté ne refuse que sa propre mise à jour. Le téléphone met tout de même à niveau chaque membre vers la version exécutée par le lead, et une seule confirmation suffit pour l'ensemble. Une fois que les deux commandes ci-dessus ont mis à niveau le lead, rien ne se met à niveau tout seul : appuyez à nouveau sur la page Updates et les membres suivront vers la nouvelle version du lead.

Mettre à jour, depuis le téléphone ou le terminal

Deux voies de mise à jour existent, et toutes deux exécutent les mêmes étapes sur chaque hôte : préparer la nouvelle version à côté de celle active, basculer le lien symbolique, redémarrer et vérifier que le service répond. Sur un lead de crew, les deux voies couvrent l'ensemble du crew. Le téléphone représente la voie rapide. Le terminal sert de solution de repli pour une machine que le téléphone ne peut pas mettre à niveau.

Depuis le téléphone

Ouvrez Paramètres et sélectionnez Updates. La carte affiche la version en cours d'exécution, la version la plus récente et les versions intermédiaires incluses dans la mise à jour. Si l'hôte utilise déjà la version la plus récente, la carte l'indique et ne propose rien.

En dessous se trouve la vérification préalable, à raison d'une ligne par contrôle : doctor, disk, bun, tree, upstream et service. Sur un lead, chaque membre du crew est également vérifié.

• —
  Vert est valide.
• —
  Orange est bon à savoir et ne bloque jamais : écart de version au sein d'un crew, type d'installation inhabituel, version majeure disponible mais non adoptée. Les fichiers temporaires non suivis dans un checkout restent au vert.
• —
  Rouge bloque la mise à jour. La ligne indique la raison, telle qu'un collie doctor rouge, moins de 1 Go d'espace libre pour la version préparée, l'absence de bun sur l'hôte, ou un dépôt distant inaccessible. Lorsqu'une commande permet de résoudre le problème, la carte affiche cette commande sous la forme Fix: <command>.

Appuyer sur Mettre à jour vers <version> demande confirmation une seule fois, et le texte de confirmation est littéral : votre session de terminal reste active, et la vue sur le téléphone s'interrompt jusqu'à 30 secondes. Le redémarrage arrête le bridge, pas votre multiplexeur ; les agents continuent donc de s'exécuter et le téléphone se reconnecte sur la nouvelle version. Une mise à jour majeure n'est jamais appliquée lors d'une mise à jour de routine : son passage requiert sa propre confirmation, indique explicitement qu'il s'agit d'une nouvelle version majeure et vous invite à lire d'abord les notes de version.

Pendant son exécution, la carte indique l'état en cours :

Les quatre premiers indiquent une progression ; la fiche le précise et vous demande de laisser l'écran ouvert. rolled-back indique la version sur laquelle vous êtes encore, affiche la fin du journal du service et propose Réessayer. stuck affiche l'unique commande à exécuter dans un terminal. interrupted propose également Réessayer.

Me le rappeler au prochain récapitulatif masque le rappel de la fiche. Ce n'est pas une mise en sourdine : la prochaine notification attend à la fois une version plus récente et un nouveau créneau.

Fréquence des notifications. Les notifications de mise à jour forment un récapitulatif, au plus une fois par jour, et jamais avant 09:00 heure locale de l'hôte. Un différentiel composé uniquement de correctifs attend plutôt un créneau hebdomadaire, pour qu'un train de correctifs arrive en une seule notification au lieu de quatre ; une version mineure ou majeure conserve la cadence quotidienne et emporte les correctifs en attente. Les versions retenues sont regroupées, jamais abandonnées. La fiche affiche toujours l'état actuel quel que soit le créneau. La préférence de notification updates, sous Paramètres → notifications (Web Push), est l'unique interrupteur pour tout désactiver.

Sur un lead de crew, le bouton affiche Mettre à jour le crew vers <version>, et une seule confirmation s'applique à chaque machine. Le lead se met à jour en premier, selon son propre contrôle d'intégrité. Chaque pair se met ensuite au niveau de la même version, un par un, en utilisant son propre preflight, son propre contrôle d'intégrité et son propre rollback. Il n'y a aucun bouton par pair et aucune deuxième demande de confirmation. Pour les détails, les deux voies de récupération et le seul cas que le téléphone ne peut pas corriger, consultez Mise à jour du reste du crew.

Un bandeau en haut de chaque écran affiche l'avancement : la version proposée, puis Starting update…, Updating to <version>, Updated to <version>. Tap to reload., et enfin Updating <n> peers: <names> au fur et à mesure que les pairs suivent. Un pair ayant fait l'objet d'un rollback y est également nommé, avec Voir les mises à jour. pour revenir à la page. Le bandeau s'affiche dans cet ordre :

Depuis le 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

Sur une installation gérée par Herdr, les mêmes verbes sont des actions Herdr :

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

collie update --check ne modifie rien. Elle exécute collie doctor, lit l'espace libre, la version de bun, le working tree, la liste des versions amont et l'unité de service, et sur un lead, elle pose la même question à chaque membre du crew via votre propre SSH. Elle quitte avec le code 0 sauf si un élément est au rouge, et --json affiche un rapport versionné. Ajoutez --local pour vérifier uniquement cette instance et ignorer les membres du crew. Le téléphone exécute cette vérification locale sur son propre hôte et lit la ligne de chaque pair via le lien du crew, son preflight n'a donc pas besoin de SSH.

collie update récupère la version la plus récente de votre version majeure actuelle et la prépare. La commande délègue ensuite le basculement à un outil de mise à jour distinct et quitte, car le redémarrage coupe le pont ayant demandé la mise à jour. Cet outil fait pointer current vers la nouvelle version, redémarre avec le nouveau binaire et interroge GET /api/health pendant 30 secondes au maximum pour obtenir une réponse contenant la version qu'il vient d'installer. Si la réponse n'arrive pas, ou provient de l'ancienne version, il rebascule current en arrière, redémarre encore une fois, et enregistre rolled-back avec la fin du journal du service. Si cela ne démarre pas non plus, il enregistre stuck avec la commande à exécuter manuellement, et plus rien ne redémarre. Il effectue un rollback une fois, jamais deux.

Définissez COLLIE_UPDATE_HEALTH_TIMEOUT_MS si 30 secondes ne suffisent pas sur votre machine. Un démarrage à froid lent qui dépasse ce délai est interprété comme un échec de mise à jour et déclenche un rollback.

collie update --status affiche l'enregistrement conservé par l'outil de mise à jour, et le téléphone lit le même enregistrement. Une issue de secours du deputy le sert sur /standby/update pendant que le port principal est inaccessible.

Si un nouvel événement de hook de balise est disponible, update affiche une notification pour réexécuter hooks install claude.

Emplacement des versions

Une installation binaire et un clone lié partagent la même disposition sous la racine d'installation (~/.local/share/collie ou $COLLIE_DIR pour une installation binaire, le clone lui-même pour un checkout) :

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

Sur un checkout, chaque versions/vX.Y.Z est un worktree git du tag de version, partageant l'unique .git, de sorte qu'une version coûte un arbre et non un second magasin d'objets. La compilation s'exécute dans le nouveau répertoire et écrit un marqueur de complétion en dernier ; le basculement refuse d'opérer sans ce marqueur, garantissant qu'une compilation interrompue ne modifie pas la version active. Le passage en production consiste en un simple renommage du lien symbolique current. La rétention conserve current ainsi que les deux versions précédentes les plus récentes, et seul un cycle réussi purge les anciennes, évitant ainsi qu'une exécution ayant potentiellement besoin de sa cible de rollback ne la supprime.

Un checkout Géré par Herdr fait exception et continue d'avancer sur place (ADR 0006, modifié le 2026-09-03). Il est détaché et superficiel, et il réside dans un répertoire appartenant à Herdr, il n'y a donc pas de structure versions/ à côté, rien à déléguer et aucun état antérieur vers lequel basculer. --rollback y est refusé ; la procédure de récupération consiste en une réinstallation d'un tag désigné (herdr plugin install AltanS/collie --ref vX.Y.Z --yes).

Rétrograder de la version 1.8.0 à la version 1.7.0 nécessite deux modifications manuelles dans le répertoire d'état. 1.8.0 renomme les trois fichiers d'état lors de son premier démarrage : ~/.local/state/collie/ contient désormais crew-trust.json, crew-ops.json et crew-runtime.json, et un build 1.7.0 ne lit que les anciens noms. Renommez tous les trois avec leurs anciens noms avant de lancer le build 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

Modifiez ensuite deux noms de clés dans pack-trust.json. La version 1.8.0 lit le bloc crew sous l'une ou l'autre des graphies et le réécrit sous le nom "crew", avec "crewId" à l'intérieur, là où la version 1.7.0 écrivait "pack" et "packId". Une version 1.7.0 ne lit que sa propre graphie ; par conséquent, dès que la version 1.8.0 a écrit dans le magasin (ce qu'elle fait lors de toute adhésion, rotation, actualisation de warrant ou suppression), renommez ce bloc en "pack" et son champ id en "packId". Rien d'autre n'a changé dans les trois fichiers, et crew-ops.json ainsi que crew-runtime.json ne nécessitent aucune modification. Si vous préférez ne pas toucher au fichier, restaurez une copie de pack-trust.json effectuée avant la mise à jour, ou restez sur la version 1.8.0 : une version 1.7.0 incapable de lire le magasin de confiance démarre en solo et n'applique aucun tableau des membres.

Vérifier

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

Attendez-vous au tag le plus récent.

Le bundle propre au téléphone est indépendant. La PWA vérifie seule l'existence d'une nouvelle version et recharge dans un délai d'environ une minute, puis suspend ce rechargement pendant toute la durée d'une mise à jour. Si vous êtes au milieu d'une tâche, elle affiche un bandeau "appuyer pour mettre à jour" et attend votre validation.

Si la version n'a pas changé

collie update interroge directement GitHub à chaque exécution, via git ls-remote pour une copie de travail ou via l'API des tags GitHub pour une installation binaire. Elle ne met pas en cache la liste des versions. Une version publiée il y a quelques secondes peut mettre une minute à apparaître, car GitHub doit lui-même se synchroniser. Exécutez ensuite collie doctor. Si cela n'explique pas la situation, consultez Si collie ne s'exécute pas.

Changer de version majeure

update ne passe jamais automatiquement à une version majeure supérieure.

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

Cette commande avance d'une version majeure vers sa version finale la plus récente. Elle ne cible pas les préversions (ADR 0020). Voir aussi : Passer de la version 0.x à la version 1.0.

Si cela échoue avec "You are not currently on a branch"

Les installations depuis GitHub antérieures à la version 0.23.1 ne disposent pas d'une référence de suivi de branche (#63). Réinstallez pour rétablir la fonctionnalité de mise à jour :

# 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

Votre configuration dans le répertoire de configuration des plugins de Herdr, ~/.config/herdr/plugins/config/herdr.collie par convention, est conservée.

Mise à jour du reste du crew

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

C'est le chemin par le terminal, pour un pair que le téléphone ne peut pas mettre à niveau. Depuis le téléphone, mettez à jour toute la crew d'un seul geste et avec une seule confirmation : ouvrez Paramètres → Mises à jour sur le lead et sélectionnez Mettre à jour le crew vers <version>. La vérification préalable au-dessus du bouton couvre tous les membres, pas seulement le lead. Si un contrôle est rouge quelque part, le bouton est désactivé et indique la machine en échec ainsi que la raison.

Le lead se met à jour en premier, selon son propre contrôle de santé. Le premier pair ne démarre qu'une fois le lead stabilisé. À partir de la version 1.7.0, cet ordre compte aussi pour les messages : un lead antérieur à la version 1.7.0 lit le statut d'un membre à sa première ligne affichée, et un membre en version 1.7.0 affiche crew … là où une version 1.6.0 affichait pack …, de sorte qu'un lead non mis à jour ne peut pas le lire. Un lead en version 1.7.0 lit les deux. Chaque pair s'aligne ensuite lui-même : il lit la version exécutée par son lead, récupère ce tag exact sur GitHub et exécute sa propre vérification préalable, son propre contrôle de santé et son propre retour arrière. Les pairs avancent un par un. La page Mises à jour conserve une ligne par membre : waiting, checking, staging, restarting, verifying, updated, rolled back ou unreachable.

1.7.0 vers 1.8.0. Le lead passe en premier à nouveau, pour une seconde raison : la version 1.8.0 renomme en crew les chemins réseau, les deux clés d'environnement, les trois fichiers d'état et le préfixe du journal. Un lead en version 1.8.0 répond aux anciens chemins /pack/v1/* pendant une version, permettant à un membre encore en version 1.7.0 de suivre la mise à jour sur le lien déjà établi. Les deux anciennes graphies disparaissent en version 1.9.0. Les noms et leurs effets sur votre machine sont détaillés dans Mise à jour depuis 1.7.0. L'asset collie-release.json publié par la version alimente uniquement le texte de cet avis sur le bandeau, sur la carte Mises à jour et dans la notification quotidienne ; il ne bloque jamais une mise à jour et n'en modifie jamais l'action.

Deux conditions déterminent si un pair peut suivre ou non :

• —
  Un pair nécessite un accès HTTPS sortant vers github.com. C'est de là que provient son code. Sans cet accès, le pair est signalé comme en retard et doit être mis à niveau depuis le terminal, à l'aide de la commande ci-dessus.
• —
  Une version -dev+ ne suit jamais. Une machine sur une version de développement y reste, quelle que soit la version exécutée par son lead.

Un pair qui effectue un retour arrière l'indique sur la page Mises à jour et ne réessaie pas de lui-même. Deux méthodes permettent une nouvelle tentative :

• —
  Depuis le téléphone. Dès que le lead est à jour et qu'un peer est en retard, le bouton indique Réessayer la mise à jour de la crew. Il lance une nouvelle exécution dont les seules étapes concernent les peers, et c'est cette nouvelle exécution qui accorde à chacun d'eux une tentative supplémentaire.
• —
  Depuis le terminal, sur le lead. Utilisez ceci pour un peer que le téléphone ne peut pas du tout mettre à niveau. La commande reste inchangée :

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

L'exécuter sur le lead constitue une séquence unique via votre propre SSH. Elle effectue d'abord un contrôle préalable de chaque machine, et affiche le rapport propre à chaque pair à côté de la réponse obtenue par SSH, rendant ainsi les divergences explicites plutôt que lissées. Elle demande un consentement unique. Elle met ensuite à jour le lead lui-même, si celui-ci n'exécute pas encore le build qu'il distribue. Elle traite ensuite chaque pair tour à tour : le commit du lead est poussé vers le pair sous forme de git bundle, recompilé, redémarré, puis interrogé jusqu'à ce qu'il réponde avec le nouveau build dans la limite des mêmes 30 secondes allouées.

Le premier échec interrompt l'exécution. Chaque membre suivant est laissé intact et signalé comme "non tenté", et le récapitulatif indique la commande unique qui résout l'échec. Un lead qui ne peut pas appliquer sa propre mise à jour ne touche aucun peer. S'arrêter là est sûr, car une crew tolère les écarts de version (CREW_PROTOCOL.md §7.1) ; une crew partiellement mise à jour est donc un état pris en charge, alors que continuer ne l'est pas.

Un cas que le téléphone ne peut pas résoudre. Si vous annulez manuellement la version du lead après la mise à niveau de ses peers, les peers restent en avance sur leur lead. Rien ne rétrograde un peer : un lead capable de faire reculer un peer pourrait le déplacer vers n'importe quelle version. L'écart est inoffensif, et la solution consiste à lancer collie crew update <member> sur le lead.

Le code parvient à un peer via votre SSH et jamais par la liaison de crew (ADR 0016, addendum du 04/09/2026). Lorsqu'un peer se met à niveau lui-même, son code provient de GitHub via HTTPS anonyme et le peer décide de manière autonome. Le lead indique seulement la version qu'il exécute et quel peer peut continuer.

Si l'updater plante lui-même

Rien de ce qui précède n'est utile lorsque l'updater a disparu. C'est la démarche qui suppose seulement un accès terminal.

L'updater écrit un enregistrement, <state dir>/update.json (par défaut ~/.local/state/collie/update.json, ou sous $COLLIE_STATE_DIR). Lisez-le d'abord : il indique l'état, la version d'origine de l'exécution, la version cible, le pid de l'updater et, en cas d'échec, la fin du journal du service ainsi que la commande de récupération.

Une mise à jour lancée par le téléphone n'affiche rien dans votre terminal. Elle s'exécute sous sa propre unité systemd transitoire, nommée collie-api-update-<stamp>, et --collect supprime cette unité dès qu'elle se termine, de sorte que sa transcription ne figure que dans le journal :

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

C'est là qu'il faut regarder lorsque le téléphone a signalé un succès mais qu'une étape en aval ne s'est pas produite ; par exemple, un avertissement indiquant que l'enregistrement d'exécution n'a pas pu être écrit, ce qui correspond à un lead mis à jour mais qui ne mettra pas à niveau sa crew. Le journal propre du bridge contient l'autre moitié : une ligne [crew] update <run id>: levelling peers to <version> par exécution, lorsque le lead récupère l'enregistrement. Avant la version 1.8.0, ce préfixe était [pack]. En l'absence d'une telle ligne, les tours n'ont jamais démarré.

Une mise à jour antérieure à 1.5.4 bloquée sur bunx

Avant la version 1.5.4, les mises à jour lancées depuis un téléphone s'exécutent dans une unité utilisateur systemd transitoire dépourvue de votre PATH. Lorsque Bun se trouve uniquement dans ~/.bun/bin sur une installation par checkout, le checkout avance, mais la reconstruction échoue avec bunx: command not found. Corrigez cela en exécutant collie update une fois depuis un terminal où Bun est dans le PATH, ou lancez l'action Herdr, dont le shim localise Bun lui-même. L'une ou l'autre méthode reconstruit le checkout mis à jour. À partir de la version 1.5.4, l'updater trouve Bun de manière autonome.

À côté se trouve <state dir>/update.lock, qui conserve un pid et un horodatage. Une seule exécution à la fois. Un enregistrement qui indique toujours preflight, staging, restarting ou verifying, n'a pas bougé depuis 10 minutes et dont le pid ne figure plus dans la table des processus, est terminé : il est considéré comme interrupted, et une nouvelle exécution peut acquérir le verrou.

Pour rétablir manuellement la version précédente, pointez current dessus et redémarrez :

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

Ou laissez la version précédente effectuer la même opération pour vous, ce qui correspond à la commande contenue dans un enregistrement stuck :

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

Utilisez le chemin complet, pas collie : le nom présent dans votre PATH est résolu via current, et current est précisément l'élément qui peut être incorrect.

Ce que la vérification d'état ne détecte pas

La vérification prouve une seule chose : le service est revenu et a répondu à /api/health avec la version qui a été installée. Il s'agit d'une garantie limitée, pas d'une promesse de zéro panne définitive. Quatre éléments peuvent être défaillants alors que la vérification signale un succès :

• —
  Un bundle web obsolète sur le téléphone. L'hôte est sur la nouvelle version et le téléphone exécute toujours l'ancien JavaScript depuis son service worker. La PWA remplace son propre bundle selon son propre calendrier ; la vérification d'état n'a aucune visibilité dessus.
• —
  Migrations de configuration ou de schéma. Collie n'en fournit aucune à ce rythme, et l'updater n'en applique aucune. Le contrôle vérifie que le service répond, pas que ses données ont la bonne structure.
• —
  Un pilote mux qui ne plante que lors de l'interaction. Le bridge démarre et répond au health check alors que l'adaptateur échoue lors du premier attachement ou envoi réel. Health est une sonde de liveness, pas un test de conformité.
• —
  L'updater qui exécute le code de l'ancienne version. L'updater détaché est lancé depuis la version en cours de remplacement. Il reste léger et stable et son enregistrement est versionné, de sorte qu'un ancien updater et un nouveau bridge continuent de se comprendre, mais il s'agit d'une atténuation et non d'une garantie.

Résoudre la version la plus récente depuis un script

Interrogez les tags git et triez par semver. Évitez GET /repos/AltanS/collie/releases/latest, qui exclut les préversions.

# 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

Préversions

Les installations stables ne reçoivent pas de préversions. Choisir une préversion suit les préversions de cette version majeure jusqu'à la sortie de la version finale (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

Résolvez <tag> avec Résoudre la version la plus récente depuis un script.

Pour revenir aux versions stables :

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

Passer de la version 0.x à la version 1.0

Si BUN_INSTALL est défini uniquement dans .env, exportez-le plutôt dans votre profil de shell ou dans l'environnement du service. Exécutez ensuite :

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

# Linked clone
bin/collie update --major

Vérifiez avec bin/collie version ou herdr plugin action invoke version --plugin herdr.collie.

Pour les configurations crew : Mettez d'abord à jour le lead, puis exécutez collie crew update <member>… (Mise à jour du reste du crew). Remarque :

• —
  join requiert --insecure pour les leads http:// simples.
• —
  Les jetons d'invitation antérieurs à la 1.0 doivent être régénérés avec crew invite.
• —
  Les anciens enregistrements de membres requièrent reconnect.
• —
  Les pairs non mis à niveau s'affichent sous la forme warn: dans crew status (CREW_PROTOCOL §7.1).

Ce que la version 1.0 change pour vous

Les identifiants d'action Herdr et les routes scripts/collie-ctl.sh restent inchangés (ADR 0006).

Les verbes du CLI sont compilés dans <checkout>/bin/collie (Commandes). Utilisez bin/collie link pour ajouter collie au PATH (Ajoutez collie à votre PATH, ADR 0021).

Nouvelles fonctionnalités :

• —
  pair / devices : Identifiants d'écriture par appareil (Associer un appareil).
• —
  crew … / join / promote : Clustering multi-hôtes (Commandes crew).
• —
  doctor : Diagnostics de configuration.
• —
  stt setup : Configuration du composeur vocal (Entrée vocale).
• —
  hooks install claude / beacon emit : Balises d'activité des agents (Balises d'agent).
• —
  COLLIE_MUX : sélectionnez herdr (par défaut), tmux ou zellij (tmux et zellij).

Côte à côte, si le herd existe

La configuration des instances secondaires est documentée dans Plusieurs instances de Collie sur un même hôte.

Revenir en arrière

Extrayez le dernier tag 0.x et recompilez :

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

Recompilez avec bash scripts/collie-ctl.sh build et exécutez l'action restart de Herdr. Les fichiers d'état (crew-trust.json, crew-runtime.json, paired-devices.json, pairing-pending.json) peuvent être conservés. Le retour en arrière supprime l'obligation d'appairage des appareils ; configurez COLLIE_DEVICE_HEADER si la protection en écriture est requise.

Vérifier le fonctionnement

Vérifiez que version renvoie 1.0.0 ou une version supérieure. Une installation mise à niveau n'appaire aucun appareil automatiquement : exécutez pair pour attribuer son identifiant d'écriture à un téléphone, et devices revoke si ce téléphone est perdu (Associer un appareil).

Arrêter ou désinstaller

Mettre le service en pause :

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

Supprimez la définition du service et les mappages de ports (.env et les checkouts sont conservés) :

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

Pour supprimer les fichiers restants : exécutez herdr plugin uninstall herdr.collie (géré par Herdr), ou exécutez bin/collie unlink et supprimez ~/.local/share/collie / $COLLIE_DIR (autonome).

Si collie ne s'exécute pas

Pour les installations par binaire (~/.local/share/collie ou $COLLIE_DIR), exécutez directement un binaire plus ancien :

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

Pour installer directement une version spécifique :

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

Pour les checkouts ou les installations Herdr, exécutez git checkout <tag> ou herdr plugin install AltanS/collie --ref vX.Y.Z --yes.

Vous utilisez un fork

collie update compare origin à COLLIE_UPDATE_REPO (valeur par défaut AltanS/collie) et s'arrête en cas de différence. Définissez COLLIE_UPDATE_REPO=you/collie si votre fork publie ses propres tags.

Pour fusionner manuellement les mises à jour amont dans votre fork :

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'utilisez pas update --major sur un fork ; fusionnez manuellement le tag v1.*. Exécutez collie doctor pour vérifier le COLLIE_UPDATE_REPO actif.

Persistance aux redémarrages

Sur Linux, activez le lingering pour les services utilisateur sans session :

loginctl enable-linger $USER

Vérifiez l'état avec systemctl --user status collie.

Sur macOS, start gère ~/Library/LaunchAgents/herdr.collie.plist automatiquement. Il s'exécute à la connexion de l'utilisateur. Vérifiez l'état avec launchctl print gui/$(id -u)/herdr.collie.