mvschwarz/openrig-upgrade

Mise à niveau d'OpenRig

Une mise à niveau est un workflow observé par l'agent, et non une transaction cachée derrière une seule commande. Les hôtes diffèrent, l'état des processus dérive, les fichiers de plugins locaux s'accumulent, et la réponse utile à une étape échouée dépend de ce qui est encore vivant.

L'agent possède la séquence. Arrêtez-vous après chaque mutation et observez l'effet réel avant de choisir la prochaine étape. Il n'existe délibérément pas de sous-commande de mise à niveau de bout en bout.

Modèle de sécurité

Gardez ces plans séparés :

• Les sessions (seats) vivent normalement dans tmux et peuvent survivre à un redémarrage du daemon.
• Le daemon, la base de données, les wrappers et la projection des plugins gérés constituent le plan de contrôle que l'on modifie.
• rig down détruit les sessions. Il ne fait pas partie d'une mise à niveau préservant la continuité.

Avant d'agir, nommez les rigs et les seats dont la continuité importe. Sur un hôte de production, utilisez la procédure opérateur normale de l'hôte. Sur une VM de construction favorable à la récupération, l'orchestrateur peut adopter directement un runtime testé, mais observe toujours chaque étape et s'arrête en cas de dérive inexpliquée.

Lorsque la récupération traverse une frontière d'instance

Avant que l'une ou l'autre voie ne modifie l'état d'exécution, enregistrez un exécuteur qualifié par hôte et sélectionnez explicitement le magasin de files d'attente qui possède la décision de récupération. Indiquez si le propriétaire d'origine continue, attend ou transfère ; une obligation ouverte dans un autre magasin ne constitue pas une garde exclusive de cette décision. Si le magasin d'origine est hors service, conservez la disposition de son propriétaire dans la décision survivante et communiquez-la à ce propriétaire avant qu'un exécuteur concurrent n'agisse.

Une réclamation refusée signifie qu'il faut réconcilier la propriété avec le propriétaire de la décision avant toute action d'exécution ultérieure ; elle n'autorise pas à continuer sous une ligne plus ancienne et séparée. Un retour nomme l'adresse complète de l'exécuteur et le magasin délibérément sélectionné. Lisez la ligne résultante à cet endroit, y compris la source, la destination, le corps et la disposition du propriétaire d'origine, avant de reprendre. La simple création d'un accusé de réception n'établit pas qu'une voie en attente a reçu ou accepté le transfert.

La boucle

Pour chaque étape :

1. Inspectez. Dérivez les faits courants de l'hôte actif.
2. Décidez. Choisissez une mutation bornée et énoncez son effet attendu.
3. Agissez une fois. Ne regroupez pas la mutation suivante avec celle-ci.
4. Observez. Vérifiez les surfaces de processus, d'écouteur, de base de données, de plugin et de session que l'étape a pu modifier.
5. Continuez, adaptez-vous ou arrêtez. Une attente non satisfaite est une information pour l'agent, pas une autorisation de réessayer aveuglément.

Assistants bornés

Soit SKILL_DIR le répertoire contenant ce SKILL.md. Ces scripts émettent du JSON et ne décident pas de la séquence de mise à niveau.

Inspecter les faits courants

node "$SKILL_DIR/scripts/inspect-upgrade.mjs"

Cela interroge le rig installé pour sa version, l'état du daemon, l'inventaire des nœuds et l'inventaire des plugins. Une surface manquante reste visible avec une suggestion de prochaine sonde. ready: false signifie que l'agent doit résoudre ou reconnaître consciemment le manque ; cela ne signifie pas que le script doit muter quoi que ce soit.

Sauvegarder SQLite

Prenez d'abord des instantanés de continuité :

rig snapshot <rig-id>
node "$SKILL_DIR/scripts/backup-sqlite.mjs" \
  --source "$OPENRIG_HOME/openrig.sqlite" \
  --destination "/chemin/sûr/openrig-avant-mise-a-niveau.sqlite"

L'assistant refuse d'écraser une destination, utilise la commande .backup du CLI sqlite3 lorsqu'elle est disponible (en recourant à une sauvegarde en processus via node:sqlite en l'absence du CLI), et vérifie la sauvegarde avec PRAGMA integrity_check. Il n'arrête pas le daemon et ne restaure pas une base de données.

Planifier ou appliquer des rafraîchissements sécurisés de plugins gérés

Les arbres de plugins peuvent contenir des compétences ainsi que des hooks et des métadonnées. Comparez le dernier ancêtre empaqueté, le paquet cible et l'arbre installé actif :

node "$SKILL_DIR/scripts/refresh-managed-plugin.mjs" \
  --ancestor /chemin/vers/paquet/précédent/plugin \
  --target /chemin/vers/paquet/cible/plugin \
  --live "$OPENRIG_HOME/plugins/<plugin>"

Passez en revue les décisions triées. Pour appliquer uniquement les fichiers refresh-safe et add-safe :

node "$SKILL_DIR/scripts/refresh-managed-plugin.mjs" \
  --ancestor /chemin/vers/paquet/précédent/plugin \
  --target /chemin/vers/paquet/cible/plugin \
  --live "$OPENRIG_HOME/plugins/<plugin>" \
  --apply-safe

L'assistant ne supprime jamais un fichier actif et n'écrase jamais une modification locale. Les suppressions locales, les fichiers uniquement actifs, les suppressions de cible et les types ambigus sont signalés pour que l'agent les résolve. Réexécutez le plan après toute résolution manuelle.

Migrer une disposition d'instance pré-0.5.9

La version 0.5.9 place la télémétrie d'utilisation de contexte dans $OPENRIG_HOME/state/context-usage, la télémétrie des fournisseurs dans state/provider-usage, la bibliothèque adressable sous context/, et le Monde Système par défaut à context/system/system-world.yaml. Les homes 0.5.8 existants franchissent cette frontière via une Migration Opérée par l'Agent : le runtime cible lit d'abord en mode canonique avec repli hérité, tandis que toutes les nouvelles écritures utilisent les racines d'état canoniques. Une racine de bibliothèque de contexte personnalisée explicitement configurée reste stable tout au long de l'activation.

L'assistant fournit des opérations bornées et inspectables. L'agent possède leur séquence et l'activation du runtime cible entre elles. Avec un chemin d'image préalable exact protégé, inspectez d'abord puis préparez les répertoires canoniques, le Monde Système par défaut et une configuration pointant vers la bibliothèque existante. La préparation ne copie pas la télémétrie, ne réécrit pas les paramètres du collecteur actif et n'exécute pas d'actions de cycle de vie :

--help affiche la grammaire des phases sans inventorier l'instance. Sans indicateur de phase, l'assistant exécute intentionnellement le plan en lecture seule ; les options inconnues échouent avec un code non nul avant le plan ou la mutation.

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --help

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME"

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --apply-state \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-avant"

Activez le runtime cible exact en utilisant le workflow de mise à niveau ordinaire. Attendez ensuite que chaque queue héritée bornée post-application soit suivie de nouveaux échantillons de nouvelle racine appariés pour cette même session. Cela prouve la convergence temporelle sans remplacement global de processus ; une écriture héritée ultérieure reste un arrêt net. Capturez le JSON de vérification ; les sidecars anciens copiés ne sont pas une preuve :

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --verify \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-avant" \
  > /chemin/sûr/layout-0.5.9-verify.json

Seul un accusé de réception réussi autorise le finaliseur non destructif invoqué séparément. Il copie une bibliothèque héritée non configurée dans la racine canonique sans rien écraser ; une racine de bibliothèque de contexte personnalisée reste stable :

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --apply-library \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-avant" \
  --verification /chemin/sûr/layout-0.5.9-verify.json

Arrêtez-vous sur tout problème signalé : télémétrie malformée ou étrangère, conflit de chemin réservé, collision de bibliothèque, dérive de configuration, reprise d'écritures héritées, dérive d'octets ou absence d'un double échantillon frais nécessitent tous la réparation nommée avant de continuer. La vérification lie les octets exacts de la queue acceptée à leurs nouveaux échantillons appariés ; le finaliseur les revalide immédiatement avant de basculer la configuration. L'assistant ne supprime jamais la télémétrie ou la bibliothèque héritée. Leur retrait ultérieur est une décision d'agent distincte après un runtime stable, une preuve d'écrivain, de lecteur et de récupération. Il ne démarre/arrête pas le daemon, ne lance pas de session, ne touche pas à la base de données et ne décide pas si la mise à niveau se poursuit.

Pour récupérer, restaurez le runtime précédent selon le workflow dirigé par l'agent, puis inversez uniquement les effets de configuration, de Monde Système, de répertoire vide et de bibliothèque copiée appartenant à l'assistant. Les échantillons d'état réels et les deux sources de récupération héritées restent pour inspection :

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --rollback "$OPENRIG_HOME/backups/layout-0.5.9-avant"

Mise à niveau dirigée par l'agent avec continuité

Ceci est un guide de décision, pas une recette de commande. Adaptez les chemins et les vérifications à l'hôte en face de vous.

1. Inspectez le CLI, le daemon, les nœuds et les plugins actuels à l'aide de l'assistant.
2. Créez un point de contrôle du travail actif et enregistrez le recensement exact protégé des sessions tmux.
3. Exécutez rig snapshot <rig-id> pour chaque rig protégé.
4. Créez et vérifiez la sauvegarde SQLite.
5. Construisez ou staging le runtime cible séparément. Prouvez sa version et son identité de source avant de toucher au daemon actif.
6. Exécutez rig daemon stop. Vérifiez que l'écouteur et le processus daemon identifié ont disparu. Si la commande revient alors que l'un ou l'autre reste, arrêtez-vous : inspectez l'identité et utilisez la procédure de récupération autorisée de l'hôte. Ne signalez pas aveuglément un PID.
7. Avant de démarrer la cible, tenez compte de son rafraîchissement de démarrage des plugins gérés et des compétences globales marquées. Ce runtime préserve les fichiers remplacés différents sous $OPENRIG_HOME/backups/managed-refresh/ et signale chaque chemin de récupération ; si la cible ne dispose pas de cette préservation, copiez d'abord ces arbres. Démarrez-la avec rig daemon start ou le wrapper connu de l'hôte. Vérifiez l'état du daemon, le chemin du processus, l'écouteur, la version et l'intégrité de la base de données. Les copies de récupération conservent les octets ; elles ne garantissent pas qu'un comportement personnalisé reste actif après le rafraîchissement.
8. Exécutez l'assistant de rafraîchissement de plugins en mode plan. Son plan régit uniquement les écritures ultérieures de l'assistant, pas les écritures de démarrage déjà effectuées. Appliquez les écritures sécurisées uniquement après que les trois racines et classifications aient un sens ; résolvez les chemins préservés un par un si nécessaire.
9. Vérifiez les sessions protégées avec rig ps --nodes -A --json, rig capture représentatif, et rig restore-check le cas échéant. -A est requis : sans cela, la lecture du nœud est limitée à VOTRE rig actuel, et une mise à niveau du daemon protège les sessions de chaque rig sur l'hôte — donc la forme étroite rapporte un succès alors que les sessions en dehors de votre rig n'ont pas été vérifiées.
10. Alignez les wrappers seulement après avoir dérivé comment cet hôte les possède. Utilisez son mécanisme existant ; ce skill ne réécrit pas les lanceurs.
11. Enregistrez le résultat observé, les décisions de préservation locales restantes, ainsi que le runtime de retour en arrière exact et la sauvegarde.
12. Lisez ce qui a changé dans la nouvelle version, rig context get reference/whats-new.md, et informez votre utilisateur de tout élément qui modifie sa façon de travailler.

Arrêtez-vous et rendez la main lorsque

• une session tmux protégée est manquante avant la mise à niveau ;
• l'intégrité de la base de données ou la vérification de la sauvegarde échoue ;
• le processus en cours ou l'écouteur ne correspond pas au runtime attendu ;
• l'arrêt du daemon indique un succès mais le processus ou l'écouteur identifié reste ;
• la cible ne peut pas démarrer avec la base de données existante ;
• les racines des plugins ne peuvent pas être liées à un ancêtre et une cible connus ;
• un chemin de plugin requis est classé comme modifié localement ou supprimé et la décision de propriété correcte n'est pas claire ;
• continuer nécessiterait rig down, une restauration destructive, des changements d'identifiants, ou une autorisation plus large que celle de l'opérateur.

Lorsque vous vous arrêtez, signalez le dernier état connu bon, la première attente non satisfaite, la preuve exacte et la plus petite décision nécessaire de la part du propriétaire. Préservez les sessions actives et la base de données, sauf si la récupération nécessite spécifiquement le contraire.

Le retour en arrière est également dirigé par l'agent

Préférez démarrer le runtime précédent connu avec la base de données toujours valide. Ne restaurez la sauvegarde de la base de données que si une migration ou une détection de corruption l'exige ; une projection dégradée seule ne prouve pas que la base de données doit être remplacée. Après le retour en arrière, répétez les mêmes observations de processus, d'écouteur, de base de données, de plugin et de session que lors de la progression initiale.