mvschwarz/openrig-upgrade

Actualizar OpenRig

Una actualización es un flujo de trabajo de agente observado, no una transacción oculta tras un solo comando. Los hosts difieren, el estado del proceso se desvía, los archivos de plugins locales se acumulan, y la respuesta útil a un paso fallido depende de lo que aún esté vivo.

El agente es dueño de la secuencia. Deténgase después de cada mutación y observe el efecto real antes de elegir el siguiente paso. No existe deliberadamente un subcomando de actualización de extremo a extremo.

Modelo de seguridad

Mantenga estos planos separados:

• Las sesiones normalmente viven en tmux y pueden sobrevivir un reinicio del daemon.
• El daemon, la base de datos, los wrappers y la proyección de plugins gestionados son el plano de control que se cambia.
• rig down derriba las sesiones. No forma parte de una actualización que preserve la continuidad.

Antes de actuar, nombre los rigs y sesiones cuya continuidad importa. En un host de producción, utilice la ceremonia operativa normal del host. En una VM de build amigable para la recuperación, el orquestador puede adoptar un runtime probado directamente, pero aún observa cada paso y se detiene ante desviaciones inexplicadas.

Cuando la recuperación cruza un límite de instancia

Antes de que cualquiera de las vías cambie el estado del runtime, registre un ejecutor calificado por host y seleccione explícitamente el almacén de colas que posee el fallo de recuperación. Indique si el propietario original continúa, espera o transfiere; una obligación abierta en otro almacén no es custodia exclusiva de este fallo. Si el almacén original está caído, retenga la disposición de su propietario en el fallo superviviente y comuníquela a ese propietario antes de que un ejecutor competidor actúe.

Una reclamación rechazada significa reconciliar la propiedad con el propietario del fallo antes de cualquier acción adicional del runtime; no autoriza a continuar bajo una fila anterior separada. Una devolución nombra la dirección completa del ejecutor y el almacén deliberadamente seleccionado. Lea la fila resultante allí, incluyendo origen, destino, cuerpo y la disposición del propietario original, antes de reanudar. La creación de un recibo por sí sola no establece que una vía en espera recibió o aceptó la transferencia.

El bucle

Para cada paso:

1. Inspeccionar. Derivar hechos actuales del host vivo.
2. Decidir. Elegir una mutación acotada y declarar su efecto esperado.
3. Actuar una vez. No agrupar la siguiente mutación con ella.
4. Observar. Verificar las superficies de proceso, listener, base de datos, plugins y sesiones que el paso podría haber cambiado.
5. Continuar, adaptar o detenerse. Una expectativa fallida es información para el agente, no permiso para un reintento ciego.

Ayudantes acotados

Sea SKILL_DIR el directorio que contiene este SKILL.md. Estos scripts emiten JSON y no deciden la secuencia de actualización.

Inspeccionar hechos actuales

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

Esto pregunta al rig instalado por su versión, estado del daemon, inventario de nodos e inventario de plugins. Una superficie faltante permanece visible con una siguiente sonda sugerida. ready: false significa que el agente debe resolver o acotar conscientemente la brecha; no significa que el script deba mutar nada.

Respaldar SQLite

Tome instantáneas de continuidad primero:

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

El ayudante se niega a sobrescribir un destino, utiliza el comando .backup del CLI sqlite3 cuando está disponible (con fallback a una copia de seguridad en proceso mediante node:sqlite cuando el CLI está ausente), y verifica la copia con PRAGMA integrity_check. No detiene el daemon ni restaura una base de datos.

Planificar o aplicar actualizaciones seguras de plugins gestionados

Los árboles de plugins pueden contener habilidades, así como hooks y metadatos. Compare el último ancestro empaquetado, el paquete objetivo y el árbol instalado vivo:

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

Revise las decisiones ordenadas. Para aplicar solo archivos refresh-safe y 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

El ayudante nunca elimina un archivo vivo y nunca sobrescribe una modificación local. Las eliminaciones locales, archivos solo vivos, eliminaciones objetivo y tipos ambiguos se reportan para que el agente los resuelva. Vuelva a ejecutar el plan después de cualquier resolución manual.

Migrar un layout de instancia pre-0.5.9

La versión 0.5.9 coloca la telemetría de uso de contexto en $OPENRIG_HOME/state/context-usage, la telemetría de proveedor en state/provider-usage, la biblioteca direccionable bajo context/ y el Mundo del Sistema predeterminado en context/system/system-world.yaml. Los homes existentes de 0.5.8 cruzan ese límite a través de una Migración Operada por Agente: el runtime objetivo lee primero canónico con fallback legacy mientras todas las nuevas escrituras utilizan las raíces de estado canónicas. Una raíz de biblioteca de contexto personalizada explícitamente configurada permanece estable durante la activación.

El ayudante proporciona operaciones acotadas e inspeccionables. El agente es dueño de su secuencia y de la activación del runtime objetivo entre ellas. Con una ruta exacta de preimagen protegida, primero inspeccione y luego prepare directorios canónicos, el Mundo del Sistema predeterminado y un pin de configuración a la biblioteca existente. La preparación no copia telemetría, reescribe configuraciones de colectores en vivo ni ejecuta acciones de ciclo de vida:

--help imprime la gramática de fase sin inventariar la instancia. Sin indicador de fase, el ayudante ejecuta intencionalmente el plan de solo lectura; las opciones desconocidas fallan con código distinto de cero antes del plan o la mutación.

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"

Active el runtime objetivo exacto usando el flujo de trabajo de actualización ordinario. Luego espere hasta que cada cola legacy posterior a la aplicación acotada sea seguida por muestras pares más nuevas de raíz nueva para esa misma sesión. Esto prueba la convergencia temporal sin reemplazo masivo de procesos; una escritura legacy posterior sigue siendo una parada dura. Capture el JSON de verificación; los sidecars antiguos copiados no son evidencia:

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

Solo un recibo exitoso autoriza el finalizador no destructivo invocado por separado. Copia una biblioteca legacy no configurada en la raíz canónica sin sobrescribir nada; una raíz de biblioteca de contexto personalizada permanece estable:

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

Deténgase ante cada problema reportado: telemetría malformada o extraña, conflicto de ruta reservada, colisión de biblioteca, deriva de configuración, reanudación de escrituras legacy, deriva de bytes o una muestra dual fresca faltante requieren la reparación nombrada antes de continuar. La verificación vincula los bytes exactos de cola aceptados con sus muestras pares más nuevas; el finalizador los revalida inmediatamente antes de cambiar la configuración. El ayudante nunca elimina la telemetría o biblioteca legacy. Su retiro posterior es una decisión separada del agente después de runtime estable y prueba de escritor, lector y recuperación. No detiene/inicia el daemon, lanza una sesión, toca la base de datos ni decide si la actualización procede.

Para recuperar, restaure el runtime anterior según lo requiera el flujo de trabajo liderado por el agente, luego revierta solo los efectos de configuración, Mundo del Sistema, directorio vacío y biblioteca copiada propiedad del ayudante. Las muestras de estado real y ambas fuentes de recuperación legacy permanecen para inspección:

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

Actualización de continuidad liderada por agente

Esta es una guía de decisión, no una receta de comandos. Adapte rutas y verificaciones al host que tiene delante.

1. Inspeccione el CLI actual, daemon, nodos y plugins con el ayudante.
2. Marque el trabajo activo y registre el censo exacto protegido de tmux/sesión.
3. Ejecute rig snapshot <rig-id> para cada rig protegido.
4. Cree y verifique la copia de seguridad de SQLite.
5. Construya o prepare el runtime objetivo por separado. Pruebe su versión e identidad de origen antes de tocar el daemon en vivo.
6. Ejecute rig daemon stop. Verifique que tanto el listener como el proceso daemon identificado hayan desaparecido. Si el comando regresa mientras alguno permanece, deténgase: inspeccione la identidad y use el procedimiento de recuperación autorizado del host. No señale ciegamente un PID.
7. Antes de iniciar el objetivo, considere su actualización de inicio de plugins gestionados y habilidades globales marcadas. Este runtime preserva los archivos reemplazados diferentes bajo $OPENRIG_HOME/backups/managed-refresh/ y reporta cada ruta de recuperación; si el objetivo carece de esa preservación, copie esos árboles primero. Inícielo con rig daemon start o el wrapper conocido del host. Verifique el estado del daemon, ruta del proceso, listener, versión e integridad de la base de datos. Las copias de recuperación retienen bytes; no prometen que el comportamiento personalizado permanezca activo después de la actualización.
8. Ejecute el ayudante de actualización de plugins en modo plan. Su plan gobierna solo las escrituras posteriores del ayudante, no las escrituras de inicio que ya ocurrieron. Aplique escrituras seguras solo después de que las tres raíces y las clasificaciones tengan sentido; resuelva rutas preservadas una a una cuando sea necesario.
9. Verifique las sesiones protegidas con rig ps --nodes -A --json, rig capture representativo y rig restore-check donde sea aplicable. -A es obligatorio: sin él, la lectura de nodo es solo su rig ACTUAL, y una actualización del daemon protege sesiones en cada rig del host — por lo que la forma estrecha reporta éxito mientras las sesiones fuera de su rig quedaron sin verificar.
10. Alinee los wrappers solo después de derivar cómo ese host los posee. Use su mecanismo existente; este skill no reescribe lanzadores.
11. Registre el resultado observado, las decisiones de preservación local restantes y el runtime y respaldo exactos de reversión.
12. Lea qué cambió en la nueva versión, rig context get reference/whats-new.md, e informe a su usuario cualquier cosa que cambie la forma en que trabajan.

Deténgase y devuelva el control cuando

• una sesión tmux protegida falta antes de la actualización;
• la integridad de la base de datos o la verificación de respaldo falla;
• el proceso en ejecución o el listener no coincide con el runtime esperado;
• la detención del daemon reporta éxito pero el proceso o listener identificado permanece;
• el objetivo no puede iniciarse contra la base de datos existente;
• las raíces de plugins no pueden vincularse a un ancestro y objetivo conocidos;
• una ruta de plugin requerida se clasifica como modificada localmente o eliminada y la decisión de propiedad correcta no está clara;
• continuar requeriría rig down, restauración destructiva, cambios de credenciales o autoridad más amplia de la que tiene el operador.

Al detenerse, reporte el último estado bueno conocido, la primera expectativa fallida, la evidencia exacta y la decisión más pequeña necesaria del propietario. Preserve las sesiones activas y la base de datos a menos que la recuperación requiera específicamente lo contrario.

La reversión también es liderada por agente

Prefiera iniciar el runtime anterior conocido contra la base de datos aún válida. Restaure la copia de seguridad de la base de datos solo cuando una migración o hallazgo de corrupción lo requiera; una proyección degradada por sí sola no es prueba de que la base de datos deba reemplazarse. Después de la reversión, repita las mismas observaciones de proceso, listener, base de datos, plugins y sesiones utilizadas durante la ruta directa.