mvschwarz/openrig-upgrade

Atualizar OpenRig

Uma atualização é um workflow observado pelo agente, não uma transação escondida atrás de um único comando. Hosts diferem, o estado do processo deriva, arquivos de plugin locais se acumulam e a resposta útil a uma etapa com falha depende do que ainda está vivo.

O agente é dono da sequência. Pare após cada mutação e observe o efeito real antes de escolher o próximo passo. Não há deliberadamente nenhum subcomando de atualização ponta a ponta.

Modelo de segurança

Mantenha estes planos separados:

• Seats normalmente vivem no tmux e podem sobreviver a uma reinicialização do daemon.
• O daemon, banco de dados, wrappers e a projeção do plugin gerenciado são o plano de controle que está sendo alterado.
• rig down derruba as seats. Não faz parte de uma atualização que preserva continuidade.

Antes de agir, nomeie os rigs e seats cuja continuidade importa. Em um host de produção, use a cerimônia de operador normal do host. Em uma VM de build amigável à recuperação, o orquestrador pode adotar um runtime testado diretamente, mas ainda observa cada etapa e para em caso de deriva inexplicada.

Quando a recuperação cruza um limite de instância

Antes de qualquer lane alterar o estado de runtime, registre um executor qualificado por host e selecione explicitamente o armazenamento de fila que possui a decisão de recuperação. Declare se o proprietário original continua, espera ou transfere; uma obrigação aberta em outro armazenamento não é custódia exclusiva desta decisão. Se o armazenamento original estiver inativo, retenha a disposição de seu proprietário na decisão sobrevivente e comunique-a ao proprietário antes que um executor concorrente aja.

Uma reivindicação recusada significa reconciliar a propriedade com o proprietário da decisão antes de qualquer ação de runtime adicional; não autoriza continuar sob uma linha mais antiga separada. Um retorno nomeia o endereço completo do executor e o armazenamento deliberadamente selecionado. Leia a linha resultante lá, incluindo origem, destino, corpo e a disposição do proprietário original, antes de retomar. A criação de recibo sozinha não estabelece que uma lane em espera recebeu ou aceitou a transferência.

O loop

Para cada etapa:

1. Inspecione. Derive fatos atuais do host ativo.
2. Decida. Escolha uma mutação limitada e declare seu efeito esperado.
3. Aja uma vez. Não agrupe a próxima mutação com ela.
4. Observe. Verifique as superfícies de processo, listener, banco de dados, plugin e seat que a etapa poderia ter alterado.
5. Continue, adapte ou pare. Uma expectativa falha é informação para o agente, não permissão para uma repetição cega.

Ajudantes limitados

Deixe SKILL_DIR ser o diretório que contém este SKILL.md. Esses scripts emitem JSON e não decidem a sequência de atualização.

Inspecionar fatos atuais

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

Isso pergunta ao rig instalado por sua versão, status do daemon, inventário de nós e inventário de plugins. Uma superfície ausente permanece visível com uma próxima sonda sugerida. ready: false significa que o agente deve resolver ou limitar conscientemente a lacuna; não significa que o script deva sofrer mutação em nada.

Fazer backup do SQLite

Faça snapshots de continuidade primeiro:

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

O ajudante se recusa a sobrescrever um destino, usa o comando .backup do CLI sqlite3 quando disponível (caindo para um backup em processo via node:sqlite quando o CLI está ausente) e verifica o backup com PRAGMA integrity_check. Ele não para o daemon nem restaura um banco de dados.

Planejar ou aplicar atualizações seguras de plugins gerenciados

Árvores de plugin podem conter skills, bem como hooks e metadados. Compare o último ancestral empacotado, o pacote alvo e a árvore instalada ativa:

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 as decisões ordenadas. Para aplicar apenas arquivos refresh-safe e 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

O ajudante nunca deleta um arquivo ativo e nunca sobrescreve uma modificação local. Deleções locais, arquivos apenas ativos, remoções alvo e tipos ambíguos são relatados para o agente resolver. Reexecute o plano após qualquer resolução manual.

Migrar um layout de instância pré-0.5.9

A versão 0.5.9 coloca telemetria de uso de contexto em $OPENRIG_HOME/state/context-usage, telemetria de provedor em state/provider-usage, a biblioteca endereçável sob context/, e o Mundo de Sistema padrão em context/system/system-world.yaml. Homes existentes 0.5.8 cruzam esse limite através de uma Migração Operada por Agente: o runtime alvo lê primeiro canônico com fallback legado, enquanto todas as novas escritas usam as raízes de estado canônicas. Uma raiz de biblioteca de contexto personalizada explicitamente configurada permanece estável durante toda a ativação.

O ajudante fornece operações limitadas e inspecionáveis. O agente é dono de sua sequência e da ativação do runtime alvo entre elas. Com um caminho de pré-imagem protegido exato, primeiro inspecione e depois prepare diretórios canônicos, o Mundo de Sistema padrão e um pino de configuração para a biblioteca existente. A preparação não copia telemetria, reescreve configurações de coletor ativo nem executa ações de ciclo de vida:

--help imprime a gramática de fase sem inventariar a instância. Sem sinalizador de fase, o ajudante executa intencionalmente o plano somente leitura; opções desconhecidas falham com código diferente de zero antes do plano ou mutação.

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"

Ative o runtime alvo exato usando o workflow de atualização comum. Então espere até que toda cauda legada pós-aplicação limitada seja seguida por amostras novas pareadas de nova raiz para a mesma seat. Isso prova convergência temporal sem substituição de processo geral; uma escrita legada posterior permanece uma parada forçada. Capture o JSON de verificação; sidecars antigos copiados não são evidência:

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

Apenas um recibo bem-sucedido autoriza o finalizador não destrutivo invocado separadamente. Ele copia uma biblioteca legada não configurada na raiz canônica sem sobrescrever nada; uma raiz de biblioteca de contexto personalizada permanece estável:

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

Pare em cada problema relatado: telemetria malformada ou estrangeira, conflito de caminho reservado, colisão de biblioteca, deriva de configuração, escritas legadas retomadas, deriva de bytes ou uma amostra dupla recente ausente todos exigem a reparação nomeada antes de continuar. A verificação liga os bytes de cauda aceitos exatos às suas amostras novas pareadas; o finalizador os revalida imediatamente antes de trocar a configuração. O ajudante nunca remove a telemetria ou biblioteca legada. Sua aposentadoria posterior é uma decisão separada do agente após runtime, escritor, leitor e prova de recuperação estáveis. Ele não para/inicia o daemon, lança uma seat, toca no banco de dados nem decide se a atualização prossegue.

Para recuperar, restaure o runtime anterior conforme exigido pelo workflow liderado pelo agente, então reverta apenas os efeitos de configuração, Mundo de Sistema, diretório vazio e biblioteca copiada de propriedade do ajudante. Amostras de estado reais e ambas as fontes de recuperação legada permanecem para inspeção:

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

Atualização de continuidade liderada por agente

Este é um guia de decisão, não uma receita de comando. Adapte caminhos e verificações ao host à sua frente.

1. Inspecione o CLI atual, daemon, nós e plugins com o ajudante.
2. Checkpoint o trabalho ativo e registre o censo exato de tmux/sessão protegida.
3. Execute rig snapshot <rig-id> para cada rig protegido.
4. Crie e verifique o backup do SQLite.
5. Construa ou prepare o runtime alvo separadamente. Prove sua versão e identidade de origem antes de tocar no daemon ativo.
6. Execute rig daemon stop. Verifique que tanto o listener quanto o processo do daemon identificado desapareceram. Se o comando retornar enquanto um deles permanecer, pare: inspecione a identidade e use o procedimento de recuperação autorizado do host. Não sinalize cegamente um PID.
7. Antes de iniciar o alvo, considere sua atualização inicial de plugins gerenciados e skills globais marcados. Este runtime preserva arquivos substituídos diferentes sob $OPENRIG_HOME/backups/managed-refresh/ e relata cada caminho de recuperação; se o alvo não tiver essa preservação, copie essas árvores primeiro. Inicie-o com rig daemon start ou o wrapper conhecido do host. Verifique o status do daemon, caminho do processo, listener, versão e integridade do banco de dados. Cópias de recuperação retêm bytes; elas não prometem que o comportamento personalizado permanece ativo após a atualização.
8. Execute o ajudante de atualização de plugin no modo de plano. Seu plano governa apenas as escritas posteriores do ajudante, não as escritas de inicialização que já ocorreram. Aplique escritas seguras somente após as três raízes e classificações fazerem sentido; resolva caminhos preservados um de cada vez quando necessário.
9. Verifique as seats protegidas com rig ps --nodes -A --json, rig capture representativo e rig restore-check onde aplicável. -A é obrigatório: sem ele a leitura de nó é apenas o seu rig ATUAL, e uma atualização de daemon protege seats em todos os rigs no host — então a forma estreita relata sucesso enquanto seats fora do seu rig ficaram sem verificação.
10. Alinhe wrappers somente depois de derivar como aquele host os possui. Use seu mecanismo existente; esta skill não reescreve lançadores.
11. Registre o resultado observado, as decisões de preservação local restantes e o runtime e backup de rollback exatos.
12. Leia o que mudou na nova versão, rig context get reference/whats-new.md, e informe ao seu usuário qualquer coisa nela que mude como eles trabalham.

Pare e devolva quando

• uma sessão tmux protegida está faltando antes da atualização;
• a integridade do banco de dados ou a verificação de backup falha;
• o processo em execução ou o listener não corresponde ao runtime esperado;
• a parada do daemon relata sucesso, mas o processo ou listener identificado permanece;
• o alvo não pode iniciar contra o banco de dados existente;
• raízes de plugin não podem ser vinculadas a um ancestral e alvo conhecidos;
• um caminho de plugin necessário é classificado como localmente modificado ou deletado e a decisão de propriedade correta não é clara;
• continuar exigiria rig down, restauração destrutiva, alterações de credenciais ou autoridade mais ampla do que o operador possui.

Ao parar, relate o último estado comprovadamente bom, a primeira expectativa falha, a evidência exata e a menor decisão necessária do proprietário. Preserve seats ativas e o banco de dados, a menos que a recuperação exija especificamente o contrário.

Rollback também é liderado por agente

Prefira iniciar o runtime anterior conhecido contra o banco de dados ainda válido. Restaure o backup do banco de dados apenas quando uma migração ou descoberta de corrupção exigir; uma projeção degradada sozinha não é prova de que o banco de dados deve ser substituído. Após o rollback, repita as mesmas observações de processo, listener, banco de dados, plugin e seat usadas durante o caminho direto.