mvschwarz/openrig-upgrade

OpenRigのアップグレード

アップグレードは観察されるエージェントワークフローであり、1つのコマンドの背後に隠されたトランザクションではありません。 ホストは異なり、プロセス状態はドリフトし、ローカルプラグインファイルは蓄積され、 失敗したステップへの有用な応答は何がまだ生きているかに依存します。

エージェントがシーケンスを所有します。すべての変更後に停止し、次のステップを選択する前に実際の効果を観察してください。 エンドツーエンドのアップグレードサブコマンドは意図的に存在しません。

安全モデル

以下のプレーンを分離してください：

• シートは通常tmux内に存在し、デーモン再起動後も存続できます。
• デーモン、データベース、ラッパー、管理対象プラグインプロジェクションは、変更されるコントロールプレーンです。
• rig downはシートを破棄します。継続性を保持するアップグレードの一部ではありません。

アクションを起こす前に、継続性が重要なリグとシートに名前を付けてください。実稼働ホストでは、ホストの通常のオペレーター儀式を使用してください。リカバリフレンドリーなビルドVMでは、オーケストレーターはテスト済みのランタイムを直接採用できますが、それでも各ステップを観察し、説明できないドリフトが発生した場合は停止します。

リカバリがインスタンス境界を越える場合

どちらのレーンがランタイム状態を変更する前にも、ホスト修飾されたエグゼキュータを1つ記録し、リカバリ判定を所有するキューストアを明示的に選択してください。元の所有者が継続するか、待機するか、または転送するかを記述してください。別のストアでの未解決の義務は、この判定の排他的な管理権ではありません。元のストアがダウンしている場合は、その所有者の処分を存続している判定に保持し、競合するエグゼキュータが行動する前にその所有者に伝達してください。

拒否されたクレームは、それ以上のランタイムアクションの前に判定所有者との所有権を調整することを意味します。別の古い行の下で継続することを許可するものではありません。返却は、完全なエグゼキュータアドレスと意図的に選択されたストアを指定します。再開する前に、ソース、宛先、本文、元の所有者の処分を含む、結果の行をそこで読み取ってください。受信作成だけでは、待機中のレーンが転送を受信または受け入れたことを証明しません。

ループ

すべてのステップについて：

1. 調査する。 ライブホストから現在の事実を導き出します。
2. 決定する。 1つの境界のある変更を選択し、その期待される効果を述べます。
3. 1回だけ行動する。 次の変更をバンドルしないでください。
4. 観察する。 ステップが変更した可能性のあるプロセス、リスナー、データベース、プラグイン、シートの表面をチェックします。
5. 継続、適応、または停止する。 期待の失敗はエージェントへの情報であり、盲目的な再試行の許可ではありません。

境界のあるヘルパー

SKILL_DIRをこのSKILL.mdを含むディレクトリとします。これらのスクリプトはJSONを出力し、アップグレードシーケンスを決定しません。

現在の事実を調査する

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

これは、インストールされたrigのバージョン、デーモンステータス、ノードインベントリ、プラグインインベントリを照会します。欠落している表面は、提案された次のプローブとともに表示されたままになります。ready: falseは、エージェントがギャップを解決するか、意識的に制限する必要があることを意味します。スクリプトが何かを変更することを意味するものではありません。

SQLiteのバックアップ

最初に継続性スナップショットを取得します：

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

このヘルパーは、宛先の上書きを拒否し、利用可能な場合はsqlite3 CLIの.backupコマンドを使用し（CLIがない場合はnode:sqliteを介したインプロセスバックアップにフォールバック）、PRAGMA integrity_checkでバックアップを検証します。デーモンを停止したり、データベースを復元したりしません。

安全な管理対象プラグインリフレッシュの計画または適用

プラグインツリーには、スキル、フック、メタデータが含まれる場合があります。最後にパッケージ化された祖先、ターゲットパッケージ、およびライブインストールツリーを比較します：

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

ソートされた決定を確認します。refresh-safeおよびadd-safeファイルのみを適用するには：

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

このヘルパーは、ライブファイルを削除したり、ローカルの変更を上書きしたりしません。ローカル削除、ライブのみのファイル、ターゲット削除、曖昧なタイプは、エージェントが解決するために報告されます。手動解決後、計画を再実行してください。

0.5.9より前のインスタンスレイアウトの移行

バージョン0.5.9は、コンテキスト使用テレメトリを$OPENRIG_HOME/state/context-usageに、プロバイダーテレメトリをstate/provider-usageに、アドレス可能ライブラリをcontext/の下に、デフォルトのシステムワールドをcontext/system/system-world.yamlに配置します。既存の0.5.8ホームは、エージェント操作移行を通じてその境界を越えます：ターゲットランタイムは、標準優先でレガシーフォールバックで読み取りますが、すべての新しい書き込みは標準状態ルートを使用します。明示的に構成されたカスタムコンテキストライブラリルートは、アクティベーション全体で安定したままです。

ヘルパーは、境界があり検査可能な操作を提供します。エージェントがそれらのシーケンスとそれらの間のターゲットランタイムアクティベーションを所有します。正確な保護されたプレイメージパスを使用して、最初に調査し、次に標準ディレクトリ、デフォルトのシステムワールド、および既存のライブラリへの構成ピンを準備します。準備は、テレメトリをコピーしたり、ライブコレクター設定を書き換えたり、ライフサイクルアクションを実行したりしません：

--helpは、インスタンスをインベントリせずにフェーズ文法を出力します。フェーズフラグがない場合、ヘルパーは意図的に読み取り専用計画を実行します。不明なオプションは、計画または変更の前にゼロ以外で失敗します。

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"

通常のアップグレードワークフローを使用して、正確なターゲットランタイムをアクティベートします。次に、同じシートについて、境界のある適用後のすべてのレガシーテールの後に、新しいペアの新しいルートサンプルが続くまで待機します。これは、包括的なプロセス置き換えなしの一時的な収束を証明します。後でのレガシー書き込みはハードストップのままです。検証JSONをキャプチャします。コピーされた古いサイドカーは証拠になりません：

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

成功した受信のみが、個別に呼び出される非破壊的なファイナライザーを許可します。ファイナライザーは、何も上書きせずに、構成されていないレガシーライブラリを標準ルートにコピーします。カスタムコンテキストライブラリルートは安定したままです：

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

報告されたすべての問題で停止します：不正な形式または外部のテレメトリ、予約パスの競合、ライブラリの衝突、構成ドリフト、再開されたレガシー書き込み、バイトドリフト、または新しいデュアルサンプルの欠落はすべて、続行する前に名前付き修復が必要です。検証は、正確に受け入れられたテールバイトをペアの新しいサンプルにバインドします。ファイナライザーは、構成を切り替える直前にそれらを再検証します。ヘルパーは、レガシーテレメトリやライブラリを削除しません。それらの後の廃止は、安定したランタイム、ライター、リーダー、リカバリの証明の後、別のエージェントの決定です。デーモンを停止/開始したり、シートを起動したり、データベースに触れたり、アップグレードが続行するかどうかを決定したりしません。

リカバリするには、エージェント主導のワークフローで必要な以前のランタイムを復元し、次にヘルパー所有の設定、システムワールド、空のディレクトリ、コピーされたライブラリの影響のみを元に戻します。実際の状態サンプルと両方のレガシーリカバリソースは、検査のために残ります：

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

エージェント主導の継続性アップグレード

これは、コマンドレシピではなく、決定ガイドです。目の前のホストに合わせてパスとチェックを調整してください。

1. ヘルパーを使用して、現在のCLI、デーモン、ノード、プラグインを調査します。
2. アクティブな作業をチェックポイントし、正確な保護されたtmux/セッションセンサスを記録します。
3. 各保護されたリグに対してrig snapshot <rig-id>を実行します。
4. SQLiteバックアップを作成し、検証します。
5. ターゲットランタイムを個別にビルドまたはステージングします。ライブデーモンに触れる前に、そのバージョンとソースIDを証明します。
6. rig daemon stopを実行します。リスナーと特定されたデーモンプロセスの両方がなくなっていることを確認します。いずれかが残っている間にコマンドが戻った場合は、停止します。IDを調査し、ホストの承認されたリカバリ手順を使用します。PIDに盲目的にシグナルを送信しないでください。
7. ターゲットを開始する前に、管理対象プラグインとマークされたグローバルスキルの起動時リフレッシュを考慮してください。このランタイムは、異なる置き換えられたファイルを$OPENRIG_HOME/backups/managed-refresh/の下に保持し、各リカバリパスを報告します。ターゲットにその保持がない場合は、最初にそれらのツリーをコピーしてください。rig daemon startまたはホストの既知のラッパーで開始します。デーモンステータス、プロセスパス、リスナー、バージョン、データベースの整合性を確認します。リカバリコピーはバイトを保持します。リフレッシュ後にカスタム動作がアクティブのままであることを約束するものではありません。
8. プラグインリフレッシュヘルパーを計画モードで実行します。その計画は、ヘルパーの後続の書き込みのみを管理し、すでに発生した起動時書き込みは管理しません。3つのルートと分類が意味をなした後にのみ、安全な書き込みを適用します。必要な場合、保存されたパスを1つずつ解決します。
9. 保護されたシートをrig ps --nodes -A --json、代表的なrig capture、該当する場合はrig restore-checkで確認します。-Aは必須です。これがないと、ノードの読み取りは現在のリグのみになり、デーモンアップグレードはホスト上のすべてのリグにわたってシートを保護するため、狭い形式は成功を報告しますが、リグ外のシートは未チェックのままになります。
10. そのホストがラッパーを所有する方法を導き出した後にのみ、ラッパーを調整します。既存のメカニズムを使用してください。このスキルはランチャーを書き換えません。
11. 観察された結果、残っているローカル保存の決定、正確なロールバックランタイムとバックアップを記録します。
12. 新しいバージョンで何が変更されたかを読み取り、rig context get reference/whats-new.md、ユーザーの作業方法を変更するものがあればユーザーに伝えます。

停止してハンドバックする場合

• アップグレード前に保護されたtmuxセッションが欠落している場合。
• データベースの整合性またはバックアップ検証が失敗した場合。
• 実行中のプロセスまたはリスナーが期待されるランタイムと一致しない場合。
• デーモン停止が成功を報告したが、特定されたプロセスまたはリスナーが残っている場合。
• ターゲットが既存のデータベースに対して起動できない場合。
• プラグインルートを既知の祖先とターゲットに結び付けることができない場合。
• 必要なプラグインパスがローカルで変更または削除された分類され、正しい所有権の決定が不明確な場合。
• 続行するにはrig down、破壊的な復元、資格情報の変更、またはオペレーターが持つより広範な権限が必要になる場合。

停止するときは、最後に証明された良好な状態、最初の失敗した期待、正確な証拠、および所有者が必要とする最小の決定を報告してください。リカバリが特に別のことを要求しない限り、ライブシートとデータベースを保持してください。

ロールバックもエージェント主導です

有効なデータベースに対して以前の既知のランタイムを開始することを優先します。移行または破損の発見が必要な場合にのみ、データベースバックアップを復元してください。劣化したプロジェクションだけでは、データベースを置き換えるべきであるという証明にはなりません。ロールバック後、フォワードパスで使用したのと同じプロセス、リスナー、データベース、プラグイン、シートの観察を繰り返します。