Recuperação de Workspace Hosted pelo operador

Use este procedimento apenas para um worker durable local-process em Linux no host original cuja captura incompleta do Hosted Shell reteve um lease de Workspace. Uma reinicialização entre prepare e complete não remove o fence; o operador ainda deve verificar que todos os writers potenciais estão parados e não podem ser reiniciados, e então submeter a prova com complete. A recuperação torna o Workspace físico disponível para novas sessões. Ela não finaliza, repete nem certifica a chamada Shell original.

O comando de manutenção é distribuído como qwen-managed-agent-server-*-operator-recovery.jar. Na distribuição de referência, invoque-o através de bin/qwen-managed-agent-operator-recovery; a partir de um build de módulo, use java -jar qwen-managed-agent-server-*-operator-recovery.jar. Execute-o no host worker original como a conta de serviço do SO, usando as configurações de banco de dados do serviço, o key ring completo de credenciais do Runtime e QWEN_MANAGED_AGENT_RUNTIME_STATE_DIRECTORY. A entrada lê o par ativo e previous-credential-keys da mesma configuração Spring que o servidor. Após a rotação, o launcher carrega config/application.yml a partir da raiz da distribuição; quando o arquivo estiver em outro local, defina SPRING_CONFIG_ADDITIONAL_LOCATION=file:<absolute-path>/application.yml; mantenha o novo par ativo e as chaves anteriores necessárias pelo binding alvo. O mapa de chaves anteriores não pode ser fornecido através de variáveis de ambiente QWEN_MANAGED_AGENT_*; siga as regras de bracket-key do rotation runbook. Seu resumo de inicialização e erros de chave indisponível contêm apenas IDs de chave escapados, nunca valores secretos. Defina QWEN_MANAGED_AGENT_RUNTIME_DURABLE_LOCAL_PROCESS=true, QWEN_MANAGED_AGENT_RUNTIME_PROVISIONER=local-process e QWEN_MANAGED_AGENT_RUNTIME_OPERATOR_RECOVERY_ENABLED=true para este processo de manutenção. Mantenha o ambiente de banco de dados e credenciais privado. Aplique a migração do banco de dados do serviço antes de executar o comando. O comando não inicia um listener HTTP, scheduler ou worker.

Encontre o runtime.runtimeBindingId e runtime.generation da execução afetada. Se o registro da execução não estiver disponível, um DBA autorizado pode usar uma consulta somente leitura em qwen_runtime_binding para o tenant_id e workspace_id afetados para listar binding_id, runtime_generation e binding_state; inspecione cada candidato e use apenas aquele com o lease mantido correspondente e a captura Shell. A partir do bundle de referência, execute bin/qwen-managed-agent-operator-recovery inspect <bindingId> <generation>; a partir de um build de módulo, use o comando java -jar equivalente acima. Registre o holderKey, sessão do Runtime, chamada Shell, captureStatus e captureReason retornados. A recuperação requer um resultado Shell producer_lost salvo e um lease de Workspace exato e ainda mantido. Um worker legado não suportado, identidade de registro ausente ou holder ausente não podem ser reparados criando registros de identidade substitutos.
A partir do bundle de referência, execute bin/qwen-managed-agent-operator-recovery prepare <bindingId> <generation> <holderKey> '<motivo do incidente>'; a partir de um build de módulo, use o comando java -jar equivalente acima. Salve o recoveryId retornado. Um binding ativo ou bloqueado por recuperação é fenced como OPERATOR_RECOVERY; um binding já LOST permanece LOST e é excluído da varredura de recuperação em background. Nenhum lease de Workspace é liberado. Repetir a mesma conta de serviço do SO e motivo é seguro. Uma conta, motivo, geração ou holder registrado diferente é rejeitado. Registre o operador humano separadamente no registro do incidente; operator_id identifica a conta do SO executando o comando.
Pare o worker original e inspecione todos os writers possíveis para o Workspace, incluindo filhos desanexados e supervisores externos. Impeça que o worker original e os writers sejam reiniciados. Confirme que eles pararam. Morte de grupo de processos, pipe EOF, tempo decorrido e perda do PID pai sozinhos são insuficientes. Se isso não puder ser estabelecido, pare aqui e deixe o Workspace fenced.
Crie um arquivo JSON UTF-8 regular, não-symlink, de no máximo 8 KiB diretamente dentro do diretório privado de estado do Runtime, modo 0600, com exatamente estes campos (substitua os valores de exemplo):
```
{
  "version": 1,
  "recoveryId": "<recoveryId>",
  "verifiedAt": "2026-09-29T03:00:00Z",
  "method": "host inspection",
  "actions": "Stopped worker and detached writers; disabled their external restart source; verified no writer remains",
  "restartPrevention": true
}
```
verifiedAt deve ser um horário de verificação UTC real não anterior ao prepare e não mais que cinco minutos à frente do relógio do host de manutenção. Registre passos concretos e a fonte de prevenção de reinicialização; nunca escreva a declaração antes de concluir essas verificações. Mantenha o arquivo e o registro do incidente privados.
A partir do bundle de referência, execute bin/qwen-managed-agent-operator-recovery complete <recoveryId> <absoluteEvidenceFile>; a partir de um build de módulo, use o comando java -jar equivalente acima. O comando verifica a identidade exata do worker salvo e, na mesma inicialização, sua ausência; após uma reinicialização do host original, verifica a identidade de inicialização alterada. Em seguida, faz tombstone do registro, persiste a declaração imutável e recupera apenas o holder original. Pode ser repetido com o mesmo arquivo após uma falha ou um erro temporário de banco de dados. Uma declaração alterada é rejeitada. A saída bem-sucedida é completed.

Após a conclusão, inicie uma nova sessão e verifique se ela pode usar o Workspace. Inspecione o turno original separadamente: sua saída parcial e efeitos incertos permanecem incertos, e nenhuma chamada Shell é repetida. Não limpe tabelas SQL ou arquivos de registro manualmente para contornar uma recusa. Se o registro original estiver ausente ou corrompido, ou o worker for de um modo efêmero mais antigo, este procedimento não é suportado; escale com a evidência preservada em vez de fabricá-la.

O software pode verificar a identidade do worker registrado e o holder SQL exato, mas não pode provar que descendentes arbitrários que escaparam pararam. A declaração do operador é o limite de confiança para esse fato.