mvschwarz/openrig-upgrade

OpenRig upgraden

Ein Upgrade ist ein beobachteter Agenten-Workflow, keine Transaktion, die hinter einem Befehl verborgen ist. Hosts unterscheiden sich, der Prozesszustand driftet, lokale Plugin-Dateien sammeln sich an, und die sinnvolle Reaktion auf einen fehlgeschlagenen Schritt hängt davon ab, was noch aktiv ist.

Der Agent besitzt die Abfolge. Stoppen Sie nach jeder Änderung und beobachten Sie die tatsächliche Wirkung, bevor Sie den nächsten Schritt wählen. Es gibt bewusst keinen End-to-End-Upgrade-Befehl.

Sicherheitsmodell

Halten Sie diese Ebenen getrennt:

• Seats leben normalerweise in tmux und können einen Neustart des Daemons überleben.
• Der Daemon, die Datenbank, Wrapper und die verwaltete Plugin-Projektion sind die Steuerungsebene, die geändert wird.
• rig down baut Seats ab. Es ist kein Teil eines kontinuitätserhaltenden Upgrades.

Bevor Sie handeln, benennen Sie die Rigs und Seats, deren Kontinuität wichtig ist. Verwenden Sie auf einem Produktionshost die normale Operator-Zeremonie des Hosts. Auf einer wiederherstellungsfreundlichen Build-VM kann der Orchestrator eine getestete Laufzeit direkt übernehmen, beobachtet aber dennoch jeden Schritt und stoppt bei unerklärlichem Drift.

Wenn die Wiederherstellung eine Instanzgrenze überschreitet

Bevor eine der beiden Spuren den Laufzeitzustand ändert, zeichnen Sie einen hostqualifizierten Executor auf und wählen Sie explizit den Warteschlangenspeicher aus, dem die Wiederherstellungsentscheidung gehört. Geben Sie an, ob der ursprüngliche Eigentümer fortfährt, wartet oder überträgt; eine offene Verpflichtung in einem anderen Speicher ist kein exklusives Sorgerecht für diese Entscheidung. Wenn der ursprüngliche Speicher ausgefallen ist, behalten Sie die Disposition seines Eigentümers in der überlebenden Entscheidung bei und teilen Sie sie diesem Eigentümer mit, bevor ein konkurrierender Executor handelt.

Eine abgelehnte Anforderung bedeutet, dass das Eigentum mit dem Entscheidungsinhaber abgestimmt werden muss, bevor weitere Laufzeitaktionen erfolgen; es autorisiert nicht die Fortsetzung unter einer separaten älteren Zeile. Eine Rückgabe nennt die vollständige Executor-Adresse und den bewusst ausgewählten Speicher. Lesen Sie die resultierende Zeile dort, einschließlich Quelle, Ziel, Text und der Disposition des ursprünglichen Eigentümers, bevor Sie fortfahren. Die alleinige Erstellung eines Empfangs begründet nicht, dass eine wartende Spur die Übertragung erhalten oder akzeptiert hat.

Die Schleife

Für jeden Schritt:

1. Untersuchen. Leiten Sie aktuelle Fakten vom Live-Host ab.
2. Entscheiden. Wählen Sie eine begrenzte Mutation aus und geben Sie ihre erwartete Wirkung an.
3. Einmal handeln. Bündeln Sie nicht die nächste Mutation damit.
4. Beobachten. Überprüfen Sie die Oberflächen des Prozesses, Listeners, der Datenbank, der Plugins und der Seats, die der Schritt hätte ändern können.
5. Fortfahren, anpassen oder anhalten. Eine fehlgeschlagene Erwartung ist eine Information für den Agenten, keine Erlaubnis für einen blinden Wiederholungsversuch.

Begrenzte Helfer

Sei SKILL_DIR das Verzeichnis, das diese SKILL.md enthält. Diese Skripte geben JSON aus und entscheiden nicht über die Upgrade-Reihenfolge.

Aktuelle Fakten untersuchen

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

Dies fragt das installierte rig nach seiner Version, dem Daemon-Status, dem Knoten-Inventar und dem Plugin-Inventar. Eine fehlende Oberfläche bleibt mit einem empfohlenen nächsten Prüfpunkt sichtbar. ready: false bedeutet, dass der Agent die Lücke beheben oder bewusst eingrenzen muss; es bedeutet nicht, dass das Skript etwas mutieren sollte.

SQLite sichern

Machen Sie zuerst Kontinuitäts-Schnappschüsse:

rig snapshot <rig-id>
node "$SKILL_DIR/scripts/backup-sqlite.mjs" \
  --source "$OPENRIG_HOME/openrig.sqlite" \
  --destination "/safe/path/openrig-before-upgrade.sqlite"

Der Helfer weigert sich, ein Ziel zu überschreiben, verwendet den .backup-Befehl der sqlite3-CLI, wenn verfügbar (fällt auf ein prozessinternes Backup über node:sqlite zurück, wenn die CLI fehlt), und überprüft das Backup mit PRAGMA integrity_check. Er stoppt den Daemon nicht und stellt keine Datenbank wieder her.

Sichere Aktualisierungen verwalteter Plugins planen oder anwenden

Plugin-Bäume können sowohl Skills als auch Hooks und Metadaten enthalten. Vergleichen Sie den letzten verpackten Vorgänger, das Zielpaket und den live installierten Baum:

node "$SKILL_DIR/scripts/refresh-managed-plugin.mjs" \
  --ancestor /path/to/previous/package/plugin \
  --target /path/to/target/package/plugin \
  --live "$OPENRIG_HOME/plugins/<plugin>"

Überprüfen Sie die sortierten Entscheidungen. Um nur refresh-safe- und add-safe-Dateien anzuwenden:

node "$SKILL_DIR/scripts/refresh-managed-plugin.mjs" \
  --ancestor /path/to/previous/package/plugin \
  --target /path/to/target/package/plugin \
  --live "$OPENRIG_HOME/plugins/<plugin>" \
  --apply-safe

Der Helfer löscht niemals eine Live-Datei und überschreibt niemals eine lokale Änderung. Lokale Löschungen, Nur-Live-Dateien, Zielentfernungen und mehrdeutige Typen werden zur Lösung durch den Agenten gemeldet. Führen Sie den Plan nach jeder manuellen Lösung erneut aus.

Migration einer Instanz vor Version 0.5.9

Version 0.5.9 platziert Kontextnutzungs-Telemetrie in $OPENRIG_HOME/state/context-usage, Anbieter-Telemetrie in state/provider-usage, die adressierbare Bibliothek unter context/ und die Standard-Systemwelt unter context/system/system-world.yaml. Vorhandene 0.5.8-Homes überqueren diese Grenze durch eine Agentengeführte Migration: Die Ziellaufzeit liest zuerst kanonisch mit Legacy-Fallback, während alle neuen Schreibvorgänge die kanonischen Statuswurzeln verwenden. Ein explizit konfiguriertes benutzerdefiniertes Kontextbibliotheksverzeichnis bleibt während der gesamten Aktivierung stabil.

Der Helfer bietet begrenzte, überprüfbare Operationen. Der Agent besitzt deren Abfolge und die Ziel-Laufzeitaktivierung dazwischen. Mit einem exakten geschützten Preimage-Pfad zuerst untersuchen und dann kanonische Verzeichnisse, die Standard-Systemwelt und eine Konfigurations-Pin auf die vorhandene Bibliothek vorbereiten. Die Vorbereitung kopiert keine Telemetrie, überschreibt keine Live-Collector-Einstellungen und führt keine Lebenszyklusaktionen aus:

--help gibt die Phasengrammatik aus, ohne die Instanz zu inventarisieren. Ohne Phasen-Flag führt der Helfer absichtlich den schreibgeschützten Plan aus; unbekannte Optionen schlagen mit einem Fehler ungleich Null vor Plan oder Mutation fehl.

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-before"

Aktivieren Sie die exakte Ziellaufzeit mit dem normalen Upgrade-Workflow. Warten Sie dann, bis jeder begrenzte Post-Apply-Legacy-Schwanz von neueren gepaarten Neu-Root-Proben für denselben Seat gefolgt wird. Dies beweist zeitliche Konvergenz ohne pauschalen Prozessaustausch; ein späterer Legacy-Schreibvorgang bleibt ein harter Stopp. Erfassen Sie das Verifizierungs-JSON; kopierte alte Sidecars sind kein Beweis:

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --verify \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before" \
  > /safe/path/layout-0.5.9-verify.json

Nur ein erfolgreicher Empfang autorisiert den separat aufgerufenen nicht-destruktiven Finalisierer. Er kopiert eine unkonfigurierte Legacy-Bibliothek in die kanonische Wurzel, ohne etwas zu überschreiben; ein benutzerdefiniertes Kontextbibliotheksverzeichnis bleibt stabil:

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --apply-library \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before" \
  --verification /safe/path/layout-0.5.9-verify.json

Halten Sie bei jedem gemeldeten Problem an: fehlerhafte oder fremde Telemetrie, ein reservierter Pfadkonflikt, eine Bibliothekskollision, Konfigurationsdrift, wiederaufgenommene Legacy-Schreibvorgänge, Byte-Drift oder eine fehlende frische Doppelprobe erfordern alle die benannte Reparatur vor dem Fortfahren. Die Verifikation bindet die exakten akzeptierten Schwanzbytes an ihre gepaart-neueren Proben; der Finalisierer validiert sie unmittelbar vor dem Umschalten der Konfiguration erneut. Der Helfer entfernt niemals die Legacy-Telemetrie oder -Bibliothek. Ihre spätere Stilllegung ist eine separate Agentenentscheidung nach stabilem Laufzeit-, Schreiber-, Leser- und Wiederherstellungsnachweis. Er startet/stoppt den Daemon nicht, startet keinen Seat, berührt die Datenbank nicht und entscheidet nicht, ob das Upgrade fortgesetzt wird.

Zur Wiederherstellung die vorherige Laufzeit gemäß dem agentengeführten Workflow wiederherstellen, dann nur die vom Helfer geänderten Konfigurationen, die Systemwelt, leere Verzeichnisse und kopierten Bibliothekseffekte rückgängig machen. Reale Zustandsproben und beide Legacy-Wiederherstellungsquellen bleiben zur Überprüfung erhalten:

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

Agentengeführtes Kontinuitäts-Upgrade

Dies ist ein Entscheidungsleitfaden, kein Befehlsrezept. Passen Sie Pfade und Überprüfungen an den Host vor Ihnen an.

1. Untersuchen Sie die aktuelle CLI, den Daemon, die Knoten und Plugins mit dem Helfer.
2. Setzen Sie einen Prüfpunkt für aktive Arbeit und zeichnen Sie die exakte geschützte tmux/Session-Zählung auf.
3. Führen Sie rig snapshot <rig-id> für jedes geschützte Rig aus.
4. Erstellen und überprüfen Sie das SQLite-Backup.
5. Bauen Sie die Ziellaufzeit separat oder stufen Sie sie bereit. Beweisen Sie ihre Version und Quellidentität, bevor Sie den Live-Daemon berühren.
6. Führen Sie rig daemon stop aus. Überprüfen Sie, dass sowohl der Listener als auch der identifizierte Daemon-Prozess verschwunden sind. Wenn der Befehl zurückkehrt, während einer von beiden noch existiert, anhalten: Identität prüfen und das autorisierte Wiederherstellungsverfahren des Hosts verwenden. Nicht blind einer PID signalisieren.
7. Bevor Sie die Ziellaufzeit starten, tragen Sie ihrem Start-Refresh der verwalteten Plugins und markierten globalen Skills Rechnung. Diese Laufzeit bewahrt unterschiedliche ersetzte Dateien unter $OPENRIG_HOME/backups/managed-refresh/ auf und meldet jeden Wiederherstellungspfad; wenn der Ziellaufzeit diese Bewahrung fehlt, kopieren Sie diese Bäume zuerst. Starten Sie sie mit rig daemon start oder dem bekannten Wrapper des Hosts. Überprüfen Sie Daemon-Status, Prozesspfad, Listener, Version und Datenbankintegrität. Wiederherstellungskopien bewahren Bytes; sie versprechen nicht, dass benutzerdefiniertes Verhalten nach dem Refresh aktiv bleibt.
8. Führen Sie den Plugin-Refresh-Helfer im Planmodus aus. Sein Plan steuert nur die späteren Schreibvorgänge des Helfers, nicht die bereits erfolgten Start-Schreibvorgänge. Wenden Sie sichere Schreibvorgänge erst an, nachdem die drei Wurzeln und Klassifikationen Sinn ergeben; lösen Sie bewahrte Pfade bei Bedarf einzeln auf.
9. Überprüfen Sie geschützte Seats mit rig ps --nodes -A --json, repräsentativem rig capture und rig restore-check, wo zutreffend. -A ist erforderlich: Ohne sie ist der Knoten-Lesevorgang NUR Ihr aktuelles Rig, und ein Daemon-Upgrade schützt Seats auf jedem Rig des Hosts – daher meldet die enge Form Erfolg, während Seats außerhalb Ihres Rigs ungeprüft blieben.
10. Gleichen Sie Wrapper erst ab, nachdem Sie abgeleitet haben, wie dieser Host sie besitzt. Verwenden Sie seinen bestehenden Mechanismus; dieses Skill schreibt keine Launcher neu.
11. Zeichnen Sie das beobachtete Ergebnis, verbleibende lokale Bewahrungsentscheidungen und die exakte Rollback-Laufzeit und das Backup auf.
12. Lesen Sie, was sich in der neuen Version geändert hat, rig context get reference/whats-new.md, und teilen Sie Ihrem Benutzer alles darin mit, das die Art und Weise, wie er arbeitet, ändert.

Anhalten und Rückgabe, wenn

• eine geschützte tmux-Sitzung vor dem Upgrade fehlt;
• die Datenbankintegrität oder Backup-Verifikation fehlschlägt;
• der laufende Prozess oder Listener nicht der erwarteten Laufzeit entspricht;
• daemon stop Erfolg meldet, aber der identifizierte Prozess oder Listener weiterhin existiert;
• die Ziellaufzeit nicht gegen die vorhandene Datenbank gestartet werden kann;
• Plugin-Wurzeln nicht mit einem bekannten Vorgänger und Ziel verknüpft werden können;
• ein erforderlicher Plugin-Pfad als lokal geändert oder gelöscht klassifiziert ist und die korrekte Eigentumsentscheidung unklar ist;
• das Fortfahren rig down, zerstörerische Wiederherstellung, Zugangsdatenänderungen oder umfassendere Autorität als der Bediener hat, erfordern würde.

Wenn Sie anhalten, melden Sie den letzten bestätigten guten Zustand, die erste fehlgeschlagene Erwartung, die exakten Beweise und die kleinste Entscheidung, die vom Eigentümer benötigt wird. Bewahren Sie Live-Seats und die Datenbank, es sei denn, die Wiederherstellung erfordert spezifisch etwas anderes.

Rollback ist ebenfalls agentengeführt

Bevorzugen Sie das Starten der vorherigen bekannten Laufzeit gegen die weiterhin gültige Datenbank. Stellen Sie die Datenbanksicherung nur wieder her, wenn eine Migration oder ein Korruptionsbefund dies erfordert; eine degradierte Projektion allein ist kein Beweis dafür, dass die Datenbank ersetzt werden sollte. Wiederholen Sie nach dem Rollback dieselben Prozess-, Listener-, Datenbank-, Plugin- und Seat-Beobachtungen, die während des Vorwärtspfads verwendet wurden.