openclaw-parallels-smoke

OpenClaw Parallels Smoke

Use este skill para fluxos de trabalho de convidados Parallels e interpretação de resultados de smoke test. Não o carregue para trabalho normal de repositório.

Regras globais

• Parallels é, por padrão, cobertura de confiança pós-publicação, não um pré-requisito para a fase de publicação beta limitada. Execute-o contra uma versão exata de pacote publicado e registre a tupla Validation SHA + Tooling SHA que autorizou esse pacote. Validation SHA mapeia para seu Code SHA ou Release SHA; não é uma terceira identidade de release.
• Uma lane Parallels pós-publicação com falha não despublica retroativeramente um beta. Classifique-a como falha de produto, de infraestrutura/ferramentaria/proveniência, de infraestrutura/credencial ou de wrapper. Apenas um defeito de produto confirmado entra no próximo beta.
• Use um coordenador e uma lane por família de convidado independente. Diagnostique e tente novamente uma família com falha uma vez, depois reavalie; não reinicie automaticamente a matriz agregada.
• Faça inventário de VMs e snapshots existentes antes de provisionar qualquer coisa. Quando um snapshot pristino pré-configurado corresponder à linha de base solicitada, mude para ele e reutilize seu usuário, ferramentas e configuração base. Não crie uma nova VM, reinstale macOS ou reconstrua a linha de base do convidado para uma execução "nova".
• "Novo" significa restaurar o snapshot pristino existente mais próximo, não criar outro snapshot. Não crie snapshots ad-hoc a menos que o usuário peça explicitamente ou não exista linha de base adequada; restaure o snapshot original e deixe o convidado parado após uma execução ad-hoc.
• Inspecione o estado do snapshot antes de restaurá-lo. Um snapshot poweron pristino pode conter a sessão logada pré-configurada; mude para ele normalmente para que o Parallels retome essa sessão. Não passe --skip-resume na entrada do teste, a menos que a execução intencionalmente precise descartar a sessão salva e inicializar a partir da tela de login. --skip-resume é aceitável para limpeza final que deve deixar o convidado fonte restaurado parado.
• A verificação de gateway em execuções de smoke deve usar openclaw gateway status --deep --require-rpc, a menos que a versão estável sendo verificada ainda não o suporte.
• Diagnósticos pré-upgrade para a versão estável 2026.3.12 podem exigir um fallback simples de gateway status --deep.
• Trate precheck=latest-ref-fail naquela lane estável pré-upgrade como linha de base, não automaticamente como uma regressão.
• Passe --json para resumos legíveis por máquina.
• Logs por fase ficam em .artifacts/parallels/openclaw-parallels-* por padrão. Substitua com OPENCLAW_PARALLELS_ARTIFACT_ROOT quando uma execução precisar de outro volume de artefatos.
• Não execute tarefas de agente locais e de gateway em paralelo no mesmo workspace ou sessão nova.
• Coloque um limite máximo em cada lane Parallels de alto nível com timeout --foreground do host (ou gtimeout --foreground se esse for o binário disponível) para que uma instalação travada, troca de snapshot ou transporte prlctl exec não consuma o restante da janela de teste. Padrões:
  • macOS: 75m
  • Linux: 75m
  • Windows: 90m
  • wrapper agregado npm-update: 150m Se uma lane atingir o limite, pare ali, inspecione o diretório de execução /tmp/openclaw-parallels-* mais recente e o log da fase, depois corrija ou reexecute a menor lane afetada. Não fique esperando por uma lane que atingiu o limite.
• As fases reais de instalação/atualização npm do OpenClaw são um sinal mais restrito do que os limites de lane inteiros: fases de instalação devem normalmente terminar em 7 minutos, e fases de atualização devem normalmente mostrar progresso significativo em 5 minutos. Se uma fase chamada install-main, install-latest, install-baseline ou install-baseline-package exceder 420s, ou uma fase chamada update-dev / openclaw update do mesmo convidado exceder 300s sem novos marcadores, inicie o diagnóstico a partir desse log de fase e do estado do processo convidado. Fases de atualização atuais do Windows ainda podem passar após aproximadamente 10-15 minutos porque doctor --fix pode instalar dependências de runtime de plugin incluídas; mantenha o limite máximo do script perto de 20 minutos, a menos que o log esteja verdadeiramente obsoleto.
• Para uma matriz completa de SOs, prefira executar lanes de famílias de convidados independentes em paralelo quando a capacidade do host permitir:
  • timeout --foreground 75m pnpm test:parallels:macos -- --json
  • timeout --foreground 90m pnpm test:parallels:windows -- --json
  • timeout --foreground 75m pnpm test:parallels:linux -- --json Mantenha cada lane em seu próprio shell/sessão e rastreie o diretório de execução para cada uma. Antes de iniciar a matriz, execute qualquer compilação/empacotamento de host necessário até a conclusão. Quando o empacotamento tgz do main atual for necessário, os scripts de smoke mantêm um bloqueio de pacote compartilhado através de pnpm build, inventário/staging e npm pack; se esse bloqueio estiver faltando ou quebrado, serialize a matriz em vez de aceitar mutação simultânea de dist.
• Não execute várias lanes de smoke contra a mesma família de convidado ao mesmo tempo. As lanes do Tahoe compartilham a porta HTTP do host, e lanes Windows/Linux podem colidir no estado de restauração/inicialização de snapshot se dois trabalhos tocarem a mesma VM simultaneamente.
• Não execute o wrapper agregado pnpm test:parallels:npm-update em paralelo com lanes individuais de smoke macOS/Windows/Linux; ele toca as mesmas famílias de convidados e snapshots.
• Não inicie lanes Parallels enquanto qualquer comando host não relacionado possa reconstruir, limpar ou reestagiar dist (pnpm build, pnpm ui:build, pnpm release:check, pnpm test:install:smoke, npm pack/install smoke ou lanes Docker que executam preparação de pacote/build). Execute primeiro os gates de build/empacotamento não relacionados, deixe-os terminar, depois inicie a matriz de VMs. A mutação simultânea de dist pode fazer o npm pack do host falhar com arquivos faltando e desperdiçar um ciclo completo de VM.
• Durante a execução ou otimização da matriz, registre a duração de tempo real por lane e a fase mais lenta dos logs /tmp/openclaw-parallels-*. Use esse tempo antes de alterar a ordem dos smokes, timeouts ou comportamento dos helpers.
• Se uma compilação do host alterar arquivos gerados rastreados, pare antes de gastar tempo de VM. Confirme o artefato gerado separadamente ou corrija o desvio do gerador, depois reexecute a menor lane afetada.
• Se o main estiver mudando sob trabalho ativo de multiagente, prefira uma árvore de trabalho destacada (detached worktree) fixada em um commit para suítes Parallels longas. Os scripts de smoke agora verificam o commit do tgz empacotado em vez de git rev-parse HEAD em tempo real, mas uma árvore de trabalho fixada ainda evita ruído de reconstrução/desvio de versão durante reexecuções.
• Para lanes openclaw update --channel dev, lembre-se de que o convidado clona o main do GitHub, não sua árvore de trabalho local. Se uma correção local existir, mas a reexecução ainda falhar dentro do checkout dev clonado, não trate isso como refutação da correção até que o branch tenha sido enviado.
• Para prlctl exec, passe o nome da VM antes de --current-user (prlctl exec "$VM" --current-user ...), não o contrário.
• Se o fluxo de trabalho instalar o OpenClaw a partir de um checkout do repositório em vez do instalador do site / npm release, termine instalando um shim real da CLI do convidado e verificando-o em um shell convidado novo. pnpm openclaw ... dentro do repositório não é suficiente para paridade de handoff.
• Em convidados macOS, prefira uma instalação global do usuário mais um shim estável visível no PATH:
  • instale com NPM_CONFIG_PREFIX="$HOME/.npm-global" npm install -g .
  • certifique-se de que ~/.local/bin/openclaw exista ou ~/.npm-global/bin esteja no PATH
  • verifique a partir de um shell convidado novo com which openclaw e openclaw --version

npm install então update

• Ponto de entrada preferido: pnpm test:parallels:npm-update
• Para uma verificação de atualização de release publicado apenas para macOS, use:
  • timeout --foreground 75m pnpm test:parallels:npm-update -- --platform macos --package-spec openclaw@<old-version> --update-target <target-version-or-tag> --json Isso mantém a cobertura de openclaw update --tag ... do mesmo convidado e usa o fallback compartilhado macOS current-user/sudo sem iniciar lanes Windows/Linux.
• Cobertura necessária: toda execução de regressão de release/update deve incluir ambas as lanes:
  • snapshot novo -> instalar pacote/linha de base solicitado -> smoke
  • mesma linha de base do convidado -> executar o comando openclaw update ... instalado do convidado -> smoke novamente
• A lane de update deve exercitar o atualizador interno do OpenClaw. Não conte um npm install -g <tgz-or-spec> direto ou troca de pacote do lado do harness como cobertura de fluxo de update; esses são apenas smokes de instalação.
• Para alvos publicados, instale primeiro o pacote de linha de base antigo (por exemplo [email protected]), depois execute a CLI convidada instalada com o canal/tag pretendido (por exemplo openclaw update --channel beta --yes --json) e verifique openclaw --version, openclaw update status --json, RPC do gateway e um agent turn após o comando.
• Para alvos não publicados, empacote o candidato no host, sirva o .tgz sobre o servidor HTTP do harness e aponte o atualizador do convidado para esse pacote servido. Prefira openclaw update --tag http://<host-ip>:<port>/openclaw-<version>.tgz --yes --json; quando a persistência do canal também importa, passe --channel <stable|beta> e defina OPENCLAW_UPDATE_PACKAGE_SPEC para a mesma URL servida no ambiente de atualização do convidado. O comando sob teste ainda deve ser openclaw update, não npm direto.
• Para validação de correção local não publicada, lembre-se de que o código do atualizador de linha de base antigo ainda controla o primeiro salto. Uma correção que vive apenas no novo código do atualizador não pode mudar aquele processo antigo já em execução; o candidato servido deve manter metadados de pacote/plugin compatíveis com o host de linha de base ou a própria linha de base deve incluir a correção do atualizador.
• Para verificação beta/stable, resolva a tag imediatamente antes da execução (npm view openclaw@beta version dist.tarball ou npm view openclaw@latest ...). Tags podem se mover enquanto uma matriz de VM longa já está em execução; reinicie a matriz quando o pré-lançamento pretendido aparecer após uma verificação anterior de 404/tag-lag no registro.
• Use o fluxo de trabalho de segredo configurado para injetar apenas as chaves de provedor necessárias para lanes OpenAI/Anthropic. Não imprima segredos ou dumps de env; passe segredos do provedor através do ambiente de execução do convidado.
• A verificação de update do mesmo convidado deve definir o modelo padrão explicitamente para openai/gpt-5.4 antes do agent turn e usar um --session-id explícito novo para que o estado do modelo da sessão antiga não vaze para a verificação.
• O wrapper agregado npm-update deve resolver a VM Linux com a mesma política de fallback do Ubuntu que parallels-linux-smoke.sh antes das lanes fresh e update. Trate qualquer convidado Ubuntu com versão principal >= 24 como aceitável quando a VM padrão exata estiver faltando, preferindo o convidado Ubuntu com versão mais recente que tenha um snapshot poweroff recente. No host atual de Peter, use Ubuntu 26.04.
• Em verificações de update do mesmo convidado macOS, reinicie o gateway após o upgrade npm antes de gateway status / agent; o launchd pode, de outra forma, relatar um serviço carregado enquanto o processo antigo foi encerrado e o processo novo ainda não está pronto para RPC.
• A perna de update macOS do agregado npm-update escreve o script de update do convidado como root e depois o executa como o usuário desktop. Se prlctl exec "$MACOS_VM" --current-user ... não puder autenticar, tente novamente através do root simples prlctl exec mais sudo -u <desktop-user> /usr/bin/env HOME=/Users/<desktop-user> USER=<desktop-user> LOGNAME=<desktop-user> PATH=/opt/homebrew/bin:/opt/homebrew/opt/node/bin:/usr/bin:/bin:/usr/sbin:/sbin .... Esse é um fallback de transporte do Parallels; ainda verifique openclaw --version, RPC do gateway e um agent turn após o update.
• Em verificações de update do mesmo convidado Windows, reinicie o gateway após o upgrade npm antes de gateway status / agent; updates npm globais in-loco podem, de outra forma, deixar imports de módulo dist/* hashados obsoletos vivos no serviço em execução.
• Nessas verificações de update do mesmo convidado Windows, não trate um único openclaw gateway restart com código de retorno diferente de zero como falha definitiva. Reinicializações de itens de login atuais podem relatar falha antes que o serviço de fundo se torne observável novamente; siga com uma espera mais longa por prontidão RPC e use gateway start apenas como uma etapa de recuperação se a prontidão nunca retornar.
• Após essa reinicialização no Windows, não confie em uma única chamada gateway status --deep --require-rpc após um sono fixo. Tente novamente a sonda de prontidão RPC por aproximadamente 30 segundos e registre cada tentativa; convidados atuais podem manter a porta 18789 vinculada enquanto o novo endpoint RPC ainda está subindo.
• Para verificações de update do mesmo convidado Windows, prefira o padrão de runner PowerShell com arquivo de conclusão/dreno de log em vez de um transporte prlctl exec ... powershell -EncodedCommand ... de longa duração. O convidado pode terminar com sucesso enquanto o prlctl exec externo ainda está pendurado.
• O helper de update do mesmo convidado Windows deve escrever marcadores de estágio para seu log antes de etapas longas como download tgz e npm install -g para que o monitor de progresso externo não fique parado em waiting for first log line durante instalações saudáveis, mas silenciosas.
• A verificação de update do mesmo convidado Linux também deve exportar HOME=/root, passar OPENAI_API_KEY via prlctl exec ... /usr/bin/env, e usar openclaw agent --local; a linha de base Linux nova não depende de credenciais de gateway persistidas.
• O wrapper npm-update agora imprime progresso por lane a partir dos arquivos de log aninhados. Se uma lane ainda parecer travada, inspecione os logs aninhados em runDir primeiro (macos-fresh.log, windows-fresh.log, linux-fresh.log, macos-update.log, windows-update.log, linux-update.log) em vez de assumir que o wrapper externo travou.
• Cada execução escreve tanto summary.json quanto summary.md; leia o markdown primeiro para triagem humana rápida, depois o JSON/tempos para automação.
• Para validação beta completa após a publicação de uma tag, prefira um comando:
  • timeout --foreground 150m pnpm test:parallels:npm-update -- --beta-validation beta3 --json Isso resolve beta3 para a versão *-beta.3 mais recente, executa cobertura de update do mesmo convidado da última para essa versão e depois executa smoke de instalação nova para esse alvo publicado exato na mesma matriz de SO selecionada. Use --platform macos|windows|linux para restringir reexecuções.
• Para validação npm do beta 4 com agent turns, a forma conhecida como boa é:
  • gtimeout --foreground 150m pnpm test:parallels:npm-update -- --beta-validation beta4 --model openai/gpt-5.4 --json Prefira o alias explícito beta4 em vez de openclaw@beta ao validar um número de pré-lançamento específico; tags npm podem se mover.
• Se o wrapper falhar em uma lane, leia o final do log despejado automaticamente primeiro, depois o log completo aninhado. O final geralmente mostra a mensagem de erro de superfície, não a causa raiz.
• Para validação de lançamento estável manual, acione pnpm test:parallels:npm-update -- --stable-validation <stable-version> --json em vez de reconstruir a matriz manualmente.
• Todos os resumos de smoke (fresh e update) devem incluir a versão exata do OpenClaw instalado, o modelo de agente em uso e se o agent turn foi bem-sucedido.
• Os logs de smoke de agente capturam a conversa truncada se ela exceder 500KB; para ver a conversa completa, inspecione o arquivo de log da fase diretamente, não o resumo.
• Para depuração de agent turn, passe --agent-debug para habilitar logs verbose de entrada/saída do agente na fase de agente. Não use isso em execuções de produção, pois pode gerar grandes volumes de log.
• Se um agent turn falhar consistentemente com model unavailable após um update, verifique se o convidado ainda tem credenciais de provedor válidas (OPENAI_API_KEY, ANTHROPIC_API_KEY) e se o modelo especificado é suportado pela versão instalada.
• O resumo deve indicar claramente se o smoke é de instalação nova (fresh) ou de update (mesmo convidado), e se o gateway foi verificado com RPC.
• Não misture resultados de múltiplas execuções de smoke no mesmo resumo. Cada execução gera seu próprio summary.json/summary.md.
• Se um smoke de update falhar porque o gateway não está pronto, mas o smoke de instalação nova passou, isso é uma regressão no fluxo de update, não uma falha de infraestrutura. Classifique-a como falha de produto.
• Se um smoke de instalação nova falhar, verifique se o artefato de pacote (tgz ou versão publicada) está acessível e se a linha de base do convidado é compatível. Se o pacote estiver quebrado, não reexecute a lane; corrija o pacote primeiro.
• Se uma lane atingir o timeout, registre a duração exata e a fase mais lenta do log. Use essa informação para ajustar timeouts ou otimizar o script de instalação/update.
• Se uma nova versão do Parallels ou do sistema operacional convidado for lançada, valide a matriz de smoke contra ela antes de atualizar a linha de base padrão.
• Se o host estiver com pouca memória ou CPU, serialize a matriz de VMs em vez de executar em paralelo. Monitore a utilização de recursos do host e ajuste a estratégia de execução de acordo.
• Se um snapshot pristino for corrompido ou não estiver mais disponível (por exemplo, após uma exclusão acidental), crie um novo snapshot a partir de uma instalação limpa da linha de base. Documente a mudança e atualize o inventário de VMs/snapshots.
• Se uma dependência de ferramenta exigir uma versão específica do Node.js ou npm no convidado, verifique se ela está disponível e corrija o ambiente convidado, se necessário, antes de iniciar os smokes.
• Se o OpenClaw introduzir um novo subcomando ou mudança de comportamento que afete o fluxo de smoke (por exemplo, novo formato de saída de gateway status), atualize os scripts de smoke e este documento de acordo.
• Se um agente de IA estiver auxiliando na depuração de smokes Parallels, forneça a ele acesso aos logs completos da fase, ao resumo JSON e ao número da versão do OpenClaw em teste. Evite redirecionar o agente apenas com informações de resumo truncadas.
• Para depuração de smokes Parallels com um agente, passe o runDir e o phase que falhou, juntamente com o log completo dessa fase. O agente pode analisar o log, sugerir correções e reexecutar a lane, se necessário.
• Se um agente reexecutar uma lane, certifique-se de que ele restaure o snapshot pristino correto antes de iniciar, e que ele use o mesmo runDir para consistência.
• Se um agente estiver analisando um resumo de smoke, ele deve primeiro verificar a seção de resumo e, em seguida, aprofundar-se nos logs das fases que falharam. Ele não deve tirar conclusões apenas do resumo.
• Se um agente estiver otimizando timeouts de smoke, ele deve basear os novos valores na fase mais lenta registrada nos logs, e não em suposições. Deve também considerar a variação entre execuções.
• Se um agente detectar que uma lane está consistentemente lenta (por exemplo, uma instalação do Windows que sempre leva 18 minutos), ele deve sugerir aumentar o timeout específico dessa lane, em vez de reduzir a cobertura de teste.
• Se um agente encontrar um snapshot corrompido ou VM inacessível, ele deve sinalizar o problema e não tentar reexecutar contra o mesmo snapshot. Deve esperar intervenção humana para corrigir o estado do convidado.
• Se um agente estiver escrevendo código para um novo helper de smoke, ele deve seguir as regras e padrões existentes neste documento. Quaisquer desvios devem ser explicitamente documentados e justificados.
• Se um agente estiver revisando uma alteração proposta neste documento, ele deve verificar consistência com o comportamento real dos scripts de smoke e apontar discrepâncias. A documentação deve corresponder à implementação.

Resumo do Fluxo de Trabalho de Smoke Parallels

1. Inventário: Liste VMs e snapshots disponíveis.
2. Seleção de Linha de Base: Encontre o snapshot pristino mais próximo para a família de convidado solicitada.
3. Provisionamento: Restaure o snapshot (ou crie um novo VM+snapshot se nenhum existir).
4. Instalação: Instale a versão especificada do OpenClaw (pacote publicado ou tgz servido).
5. Verificação Fresh: Execute openclaw --version, gateway status --deep --require-rpc e um agent turn básico.
6. Atualização (mesmo convidado): Execute openclaw update --channel <target> (ou --tag <url>).
7. Verificação Update: Repita a verificação (versão, gateway RPC, agent turn).
8. Limpeza: Restaure o snapshot original e pare o convidado (a menos que seja explicitamente solicitado de outra forma).
9. Relatório: Escreva summary.json e summary.md com os resultados de cada etapa.
10. Tratamento de Falhas: Se uma falha for detectada, classifique-a e registre os detalhes. Execute a repescagem uma vez, se apropriado.

Referência de Comandos Úteis

• pnpm test:parallels:npm-update: Ponto de entrada principal para validação de smoke de instalação + update.
• pnpm test:parallels:macos, pnpm test:parallels:windows, pnpm test:parallels:linux: Executar smokes apenas para uma plataforma.
• prlctl list -a: Listar todas as VMs.
• prlctl snapshot-list <vm>: Listar snapshots para uma VM.
• prlctl snapshot-switch <vm> -i <snapshot-uuid>: Restaurar um snapshot.
• prlctl exec <vm> --current-user <command>: Executar comando como o usuário atual do convidado.
• prlctl exec <vm> <command>: Executar comando como root no convidado.
• npm view openclaw@<tag>: Visualizar detalhes de uma tag de pacote publicada.
• openclaw update status --json: Verificar status do atualizador interno.
• openclaw gateway status --deep --require-rpc: Verificar gateway com confirmação de RPC.