# Autorreparo: o que ele faz

> Como os runners do Latchkey detectam e corrigem falhas transitórias de CI durante a execução, o que eles nunca vão tocar e como as propostas de reparo viram pull requests revisáveis.

Source: https://latchkey.dev/pt/documentation/self-healing

## Summary

- Todo runner detecta e corrige falhas transitórias (rede, config, ferramentas ausentes, memória, disco) **durante a execução**; ligado por padrão.
- Diagnóstico em três estágios: códigos de saída, depois uma biblioteca de padrões, depois IA limitada; correções só tocam o runner efêmero.
- Correções duradouras chegam como **PRs de reparo** que você revisa; falhas reais de código ainda falham, com os logs originais intactos.
- Falhas no seu próprio código chegam como um pacote estruturado via MCP: causa raiz, arquivo exato que falhou, logs completos, prontos para seu agente de código.

Todo runner do Latchkey vem com autorreparo integrado, habilitado por padrão. Quando um passo de workflow falha, o runner diagnostica a falha localmente e, quando é uma classe transitória conhecida, a corrige e repete o passo no lugar. Seu build fica verde sem uma reexecução humana, e toda intervenção é registrada para você inspecionar.

## A cascata de diagnóstico em três estágios

O diagnóstico roda do mais rápido primeiro, então os casos comuns custam quase nada:

1. **Consulta de código de saída (instantânea)** Algumas falhas se identificam sozinhas. A saída **137**, o kernel matando um processo que ficou sem memória, é decidida e corrigida já neste estágio. A saída **127** (comando não encontrado) também é sinalizada aqui, mas sua correção de fato vem da biblioteca de padrões e da allowlist de instalação do estágio 2.
2. **Biblioteca de padrões (determinística)** A saída do passo é comparada com uma biblioteca curada de assinaturas de falha conhecidas: timeouts de registry e respostas 5xx em npm, yarn, pnpm, pip, uv, módulos Go, cargo, NuGet, registries Docker e GitHub, Composer, Bundler, Maven, apt e git; contratempos de DNS e TLS; rate limits; exaustão de heap; erros de disco cheio; drift de lockfile. Uma correspondência de padrão é determinística: mesma falha, mesma correção, toda vez.
3. **Diagnóstico de IA limitado (falhas novas)** Qualquer coisa que os dois primeiros estágios não reconheçam vai para um agente de IA em sandbox com um orçamento de tempo estrito (cerca de quatro minutos). Ele lê a saída capturada, raciocina sobre a causa raiz e, ou aplica uma correção segura no runner, ou propõe uma correção duradoura como um pull request, ou conclui que a falha é real e a deixa acontecer.

## O que ele detecta, por categoria

> **O que ele deliberadamente não detecta**
> Bugs reais no seu código ou testes. Uma falha de código de usuário é classificada exatamente como isso e falha normalmente, com seus logs originais intactos. O autorreparo existe para remover ruído de infraestrutura, não para esconder falhas genuínas.

## A caixa de ferramentas de correção

Toda correção é aplicada apenas dentro do runner efêmero, e o runner é destruído após o job:

- **Repetir com backoff** Para falhas transitórias de rede: esperar, depois reexecutar o passo, escalando o atraso.
- **Definir ambiente** Elevar limites de memória para a repetição: NODE_OPTIONS, _JAVA_OPTIONS, GRADLE_OPTS e afins.
- **Liberar disco** Podar camadas Docker, caches de pacotes e /tmp quando o disco enche no meio do job.
- **Instalar um pacote** apt-get install de uma ferramenta ausente, restrito a uma allowlist: o mesmo conjunto de pacotes encontrado nas imagens de runner hospedadas pelo GitHub.
- **Reescrever comando** Trocar uma invocação sabidamente ruim pela remediação documentada (npm ci por npm install em drift de lockfile).

## Um reparo, de ponta a ponta

Aqui está um reparo real, um timeout de registry do npm, do passo que falha ao job verde. A saída do seu passo transmite inalterada, em tempo real; durante um reparo o runner adiciona duas linhas de diagnóstico próprias enquanto o serviço de reparo no runner é consultado:

```job log
$ npm ci
npm ERR! code ETIMEDOUT
npm ERR! syscall connect
npm ERR! network request to https://registry.npmjs.org/lodash failed, reason: connect ETIMEDOUT 104.16.92.83:443
npm ERR! network This is a problem related to network connectivity.
[latchkey-bash-wrapper] BEGIN sidecar POST (boot_wait=30s max_time=260s url=http://localhost/diagnose socket=/run/latchkey-self-heal/sock)
[latchkey-bash-wrapper] END sidecar POST ok (attempts=1 http=200)
$ npm ci
added 1291 packages, and audited 1292 packages in 42s
found 0 vulnerabilities
```

1. **O passo falha.** O `npm ci` sai não-zero depois que o npm esgota suas próprias repetições internas. O runner capturou a saída do passo enquanto ela transmitia, então o diagnóstico começa já com o quadro completo em mãos.
2. **Estágio 1, código de saída.** A saída 1 não é decisiva por si só, então a cascata segue adiante.
3. **Estágio 2, correspondência de padrão.** As linhas `ETIMEDOUT` correspondem a uma assinatura de rede conhecida do npm na biblioteca de padrões: veredito **heal**, categoria **network**, sem IA envolvida. As duas linhas `[latchkey-bash-wrapper]` são o único rastro dessa consulta nos seus logs.
4. **Repetição com backoff.** O plano permite até 3 tentativas com um atraso escalonado começando em 2 segundos. O runner espera e então reexecuta o passo na mesma máquina, no mesmo workspace: o segundo `npm ci` no log é essa repetição.
5. **Verde.** A repetição passa e o job continua como se o timeout nunca tivesse acontecido. No sucesso, nada mais é adicionado aos seus logs; reparos que mudam a máquina anunciam isso (por exemplo `[latchkey-bash-wrapper] installed package: ffmpeg`), então nenhuma intervenção é invisível.

A narrativa que você não viu nos logs está no dashboard: o feed **Recent Heals** na [página de Runners](/documentation/runners-dashboard) mostra uma linha **Healed** na categoria de rede com uma pílula **Pattern match** e a ação tomada ("Retried the npm command with exponential backoff after a network timeout"), o painel **Heal Details** carrega a história estágio por estágio, e a execução mantém um selo verde **Healed** em [Desempenho de pipeline](/documentation/pipeline-performance).

## Pull requests de reparo

Algumas causas raiz merecem uma correção duradoura no seu repositório, não apenas um resgate na execução: um passo de setup ausente do workflow, um pin `engines` ausente em `package.json`, um timeout de job baixo demais. Quando um reparo bem-sucedido remonta a uma causa estrutural como essas, o autorreparo produz uma proposta estruturada e abre um **PR de reparo** com uma edição tipada e determinística.

- Cada PR é intitulado "Latchkey heal: <error summary>"; o corpo explica o **Error**, a **Root cause** e o **Fix**, e liga de volta à execução do workflow, então a revisão leva minutos.
- PRs de proposta carregam uma nota de verificação: **Verified by run** quando a execução de workflow do próprio PR passou, ou **Proposed fix, not verified by a passing run** quando não passou.
- Quando repetições resgataram as execuções que falhavam, a proposta quantifica isso ("Latchkey auto-retried this workflow N times; M passed on the retry"); as repetições automáticas pausam quando a taxa de aprovação nas repetições de um workflow é ruim.
- PRs de reparo nunca sofrem auto-merge, e pull requests **de forks nunca são tocados**.
- A criação de PR usa as permissões do GitHub App; se você nunca fizer merge de um PR de reparo, nada no seu repositório muda.

### Correções recusadas: parar de propor

Nem toda classe de proposta é bem-vinda em todo repositório. Descobertas de proposta de autorreparo na página AI Insight carregam uma ação **Stop proposing** (owners e admins): o Latchkey então para permanentemente de abrir PRs para aquela classe de falha naquele repositório até você desfazer isso em **Settings, Self-Healing, Declined fixes**. O autorreparo continua atuando nessas falhas; ele só para de propor mudanças de workflow.

## O que ele fará e nunca fará

## Passe a bola para seu agente de código

O autorreparo conserta o ambiente, nunca seu código-fonte. Quando o problema real é um bug no seu próprio código, o build falha de forma verdadeira, e a falha chega como um pacote completo e estruturado servido pelo servidor MCP do Latchkey, pronto para o seu próprio agente de código consertar a partir dele. O pacote entrega ao seu agente o que ele, de outra forma, reconstruiria à mão:

- A **causa raiz**, em linguagem simples.
- O **código de saída** do passo que falhou e o **arquivo-fonte exato** onde o erro surgiu.
- Os **logs completos e não truncados** do passo que falhou, incluindo saída que o GitHub esconde no seu visualizador de logs, com segredos removidos antes de saírem do Latchkey.
- O que o autorreparo **já investigou** e por que recuou, mais a definição do workflow.

No Claude Code, o comando embutido `/mcp__latchkey__fix` faz toda a ida e volta em um passo: ele pega a falha não corrigida mais recente e mãos à obra. Qualquer agente com capacidade MCP (Cursor, Codex e outros) pode ler os mesmos pacotes através das ferramentas do servidor. Setup, chaves de API e o comando de conexão pronto estão em [Conecte seu agente de IA](/documentation/connect-your-ai-agent).

## Observabilidade: todo reparo fica registrado

- **Recent Heals** (na [página de Runners](/documentation/runners-dashboard)) lista toda intervenção com sua categoria, veredito e uma descrição em linguagem simples da ação tomada; reparos diagnosticados por IA incluem as iterações de raciocínio do agente.
- **Execuções reparadas são sinalizadas** na tabela de execuções do Desempenho de pipeline e têm link direto para seu relatório de reparo.
- **KPIs e tendências de reparo** na página de Runners mostram com que frequência o reparo salva uma execução e quais categorias dominam, o que é em si um sinal sobre sua infraestrutura.

| Sinal | O que ele te diz |
| --- | --- |
| Selo de resultado | **Healed** (a correção teve sucesso), **No Action** (o sistema intencionalmente não agiu, como numa falha no seu próprio código), **Failed** (uma correção foi tentada mas não recuperou o passo), ou **Pending** (resultado ainda não registrado). |
| Pílula de tipo de correção | Como o reparo foi decidido: **Auto-fix** (uma regra determinística de código de saída), **Pattern match** (uma assinatura de falha conhecida com uma correção conhecida), ou **Agent fix** (o agente investigou). |
| Transcrição do agente | O registro passo a passo de um reparo por agente: o plano, a hipótese e o raciocínio por turno, cada ação e seu resultado, e as durações. |

## Controles

- **Interruptor em nível de workspace** em **Settings, Self-Healing** (owners e admins), ligado por padrão para novos workspaces; as mudanças entram em vigor em cerca de um minuto.
- Não há alternador por repositório; o interruptor do workspace se aplica a todos os repositórios monitorados.
- **Declined fixes**, também em **Settings, Self-Healing**, lista as classes de proposta que você interrompeu, com a opção de desfazer cada uma.

## Perguntas comuns

### O autorreparo deixa meus builds mais lentos?

Não. Ele só ativa quando um passo falha; passos que passam rodam com zero latência adicional. Uma falha reparada custa o diagnóstico mais a repetição, o que é quase sempre muito mais barato do que um humano notar um build vermelho e clicar em reexecutar.

### Ele pode ver meus segredos?

O diagnóstico roda localmente no seu runner contra a saída do passo que seu job já imprime. Nada de novo é exposto: segredos mascarados pelo GitHub Actions permanecem mascarados, e o runner é destruído após o job.

### Ele pode repetir para sempre e inflar minha conta?

Não. As repetições são limitadas por passo, o estágio de IA tem um orçamento de tempo rígido, e o próprio runner tem um teto de vida de 4 horas. Também não há taxa separada para autorreparo: tempo de execução extra durante um reparo é cobrado pela tarifa padrão por minuto do runner.

### O que acontece quando ele não consegue corrigir uma falha?

O passo falha exatamente como falharia em qualquer outro runner, com os logs originais intactos, mais um diagnóstico que você pode ler em Recent Heals. Não reparável é um veredito de primeira classe, não um erro.

> **Veja nos seus próprios builds**
> Mova um workflow instável para `runs-on: latchkey-small` e observe o feed Recent Heals por uma semana; a maioria das equipes vê seu primeiro build resgatado em poucos dias. [Execute seu primeiro job](/documentation/run-your-first-job).

Para ver quais falhas do mundo real o reparo cobre, navegue pela [biblioteca de padrões de autorreparo](/learn/self-healing-ci) no Learn - cada entrada mostra a correção manual ao lado do que o runner faz automaticamente. Para qualquer coisa que esteja falhando seus builds atualmente, comece pela [biblioteca completa de erros de CI/CD](/learn).

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt