O vitest-orphan-leak

Um incidente real da construção desta fusão. Dois fatos de aparência inofensiva se combinaram em 16 processos imortais travando a máquina. A correção é um pequeno clássico de engenharia de sistemas defensiva — e a lição é mais larga que o bug: corrija a interação entre as causas, não só uma delas, e prove na fronteira do sistema operacional, não no "deveria funcionar".

01 · O incidente, peça por peça

Antes do "por quê", veja exatamente o que foi encontrado. Cada número aqui é um sintoma diagnóstico — e juntos eles apontam para uma assinatura específica: processos que perderam o pai e não vão morrer sozinhos.

02 · As duas causas — nenhuma fatal sozinha

Este é o coração da lição. O vazamento precisou de ambas verdadeiras ao mesmo tempo. Separadas, cada uma é um aborrecimento que você nota e resolve. Juntas, viram um processo que nada mata e nada cansa.

Por que cada causa, sozinha, se cura

Veja as duas linhas do tempo separadas. Em cada uma falta uma metade — e por isso ambas terminam bem. Examples antes da abstração: primeiro o que acontece em cada caso isolado.

A interseção: onde mora o processo imortal

Agora junte. O vazamento não é "causa 1 OU causa 2" — é a interseção das duas. Só onde os dois círculos se cruzam existe um worker que nunca vai terminar sozinho (o hang) e que não tem pai que o ceife (o órfão). É essa célula, e só ela, que produz o processo imortal.

A árvore de processos: antes e depois do pai morrer

Concretamente, eis o que acontece com a árvore de processos. À esquerda, o estado saudável: uma árvore, um pai. À direita, o instante em que o pai é morto sem matar a árvore — e os forks travados reparenteiam ao PID 1.

03 · Preveja o custo de um único loop

Você sabe que 1 worker órfão trava ~1 core a ~95%. Antes de revelar: um loop automatizado de testes que gera 1 worker órfão a cada 2 minutos e roda por 30 minutos — quanta CPU total esses órfãos somam ao final? Chute a ordem de grandeza.

Veja o empilhamento como gráfico: cada barra é um ponto no tempo, e a CPU total só sobe — porque nada nunca desce. É a assinatura visual de um vazamento cumulativo.

04 · A correção — duas camadas, uma por causa

Um único patch não seria robusto: endureça a config e um hang diferente ainda orfaniza; adicione só o wrapper e um hang dentro do grupo ainda trava um core até o timeout de relógio. Ambas as camadas são entregues, e cada uma neutraliza um dos dois círculos da interseção.

05 · Camada 1 — fazer um hang falhar, não travar (causa 1)

Timeouts limitados em vitest.config.ts (aplicados a ambos os projetos raiz via extends) transformam um hang infinito em uma falha limitada, e o pool forks isola um arquivo travado num processo filho que o Vitest mata à força no teardown — então um arquivo travado não pode travar um core indefinidamente.

// vitest.config.ts:20-27
// Endurecimento anti-órfão: um teste travado (server/socket/MCP/interval/promise
// não resolvida sem teardown) DEVE FALHAR num timeout limitado, nunca travar um
// worker pra sempre. O pool `forks` isola hangs em processos filhos que o Vitest
// mata à força no teardown, então um arquivo travado não pode travar um core.
testTimeout: 15_000,
hookTimeout: 15_000,
teardownTimeout: 10_000,
pool: 'forks',

O que o timeout faz: hang infinito → falha em 15 s

Sem timeout, um teste travado é uma reta sem fim. Com testTimeout: 15_000, a mesma trava tem um teto: aos 15 segundos o Vitest aborta o teste e o marca como falha — barulhento e finito, em vez de silencioso e eterno.

Por que pool: 'forks' também é segurança (não só performance)

O pool decide como o Vitest isola cada arquivo de teste. Em threads, uma thread travada vive dentro do mesmo processo e é difícil de matar. Em forks, cada arquivo roda num processo filho separado que o Vitest mata à força no teardown — então um arquivo travado não consegue prender um core como uma thread não-matável conseguiria.

06 · Camada 2 — tornar o orfanamento impossível (causa 2)

scripts/safe-test.mjs (exposto como pnpm test:safe) roda a suíte em seu próprio grupo de processos, sob um timeout de relógio rígido, então mata o grupo inteiro — não só o PID pai — e varre qualquer vitest perdido como rede de último recurso. Três técnicas, cada uma carregando peso:

// scripts/safe-test.mjs:34-44 — grupo destacado + kill por PID negativo
// detached:true => POSIX setsid => o filho lidera um NOVO grupo de processos,
// então `kill(-pid)` alcança todo descendente (vitest main + todos os forks).
const child = spawn(bin, args, { stdio: 'inherit', detached: true });

const killGroup = (signal) => {
  try { process.kill(-child.pid, signal); }   // pid NEGATIVO = o grupo inteiro
  catch { /* grupo já se foi */ }
};

// scripts/safe-test.mjs:26-32 — a varredura de último recurso
const sweep = () => {
  try { execFileSync('pkill', ['-9', '-f', 'vitest'], { stdio: 'ignore' }); }
  catch { /* nada a matar — pkill sai não-zero quando não há match */ }
};

A peça central: detached:true cria um grupo que um sinal alcança inteiro

A diferença entre matar e não matar os forks está num único sinal de menos. Sem detached:true, process.kill(child.pid, …) atinge só o vitest main e deixa os forks reparentearem — o bug. Com detached:true (que faz setsid, criando um novo grupo), process.kill(-child.pid, …) — PID negativo — sinaliza o grupo inteiro de uma vez.

As três técnicas e a rede tripla

• detached:true → o filho lidera um novo grupo de processos (POSIX setsid), então um único sinal alcança todo descendente.
• process.kill(-child.pid, …) → o PID negativo sinaliza o grupo inteiro, incluindo os forks do tinypool — nunca um PID nu.
• A varredura pkill -9 -f vitest → pega qualquer coisa que já escapou para o PID 1 (o caso de orfanamento), então o vazamento não pode acumular entre runs.
• Um SAFE_TEST_TIMEOUT_MS rígido (padrão 600000 = 10 min) limita a run inteira; um timeout sai com 124. O mesmo kill+sweep roda no exit normal, em SIGINT/SIGTERM, e em erro de spawn.

As três camadas de defesa formam uma rede em série — cada uma pega o que a anterior pode deixar passar:

Uma terceira medida de cinto-e-suspensório: .factory/run.ts varre vitest perdido no host no início e no fim de cada iteração — então um loop automatizado nunca herda o vazamento de uma run anterior.

07 · O ciclo de vida de um sinal (passo a passo → agora você)

Você viu o PID negativo no diagrama. Agora siga o caminho exato do sinal quando o safe-test.mjs precisa derrubar a suíte — devagar, um passo de cada vez. Recuperar o procedimento (não só ver o resultado) é o que fixa de verdade.

08 · Fluxograma diagnóstico — "achei processos vitest girando, e agora?"

Junte tudo numa decisão. Diante de processos vitest suspeitos, este fluxograma vai do sintoma à causa e à correção. Siga as setas — cada losango é uma pergunta que escolhe o caminho. O caminho do incidente real está anotado à direita.

09 · Como foi verificado — o Proof Gate

# a verificação, conceitualmente
pnpm test:safe            # run limitada no próprio grupo → 565 passaram
pgrep -f vitest           # → (sem saída): nada vazou. ISSO é a prova.

Por que o "verde" sozinho mente aqui? Porque um vazamento é um bug de ciclo de vida de processo, não de correção de lógica. A suíte pode passar 565/565 e ainda assim deixar um worker girando. As duas checagens medem coisas diferentes:

E o safe-test.mjs deixa o veredito legível por código de saída, para o loop automatizado decidir o que fazer sem ler a saída inteira: 0 = passou, 1 = teste falhou, 124 = estourou o tempo. Três destinos, três decisões diferentes.

10 · Patch único vs duas camadas — o trade-off lado a lado

A tentação é corrigir "a" causa e seguir em frente. Veja por que isso falha: cada patch único deixa metade do buraco aberto. Primeiro em linguagem simples, depois o detalhe técnico.

11 · As regras de operação que decorreram disso

12 · Confusões comuns

13 · Como isso se encaixa

Esta lição não é um bug isolado — é uma peça de infraestrutura de teste que sustenta a máquina inteira. O Alembic constrói tudo rodando loops de teste automatizados: um orquestrador gera builders, cada builder roda a suíte, e o veredito (verde + tabela de processos limpa) alimenta o próximo passo. O safe-test.mjs é a engrenagem que garante que esse loop nunca se envenene a si mesmo com um worker imortal. Veja onde ela mora no fluxo real:

Onde você está na metodologia. O Alembic é uma máquina que se constrói rodando testes em loop (o .factory e o swarm geram builders que rodam pnpm test:safe a cada unidade). Esta lição é a garantia de higiene de processo dessa máquina: sem ela, um único teste travado num loop derruba a CPU inteira e congela toda a fábrica. É infraestrutura silenciosa — você só nota quando falta. Para ver o quadro inteiro em movimento, abra o hub do curso e a galeria de blocos e demos. [uncertain] o curso não tem um arquivo metodologia.html dedicado; o mapa navegável vive no hub (index.html) + na galeria.

14 · Na prática

Chega de teoria — rode a correção. A peça desta lição é exatamente um comando: pnpm test:safe. A prova de que ela funcionou também é um comando: pgrep -fl vitest retornando vazio logo depois. Esse par é o Proof Gate do incidente, em duas linhas.

# 1) rode a suíte completa pelo wrapper seguro (grupo destacado + kill de grupo + sweep)
pnpm test:safe
# … saída do vitest …
#  Test Files  NN passed (NN)
#       Tests  565 passed (565)
# exit 0   → passou  ·  exit 1 → teste vermelho  ·  exit 124 → estourou o tempo

# 2) a PROVA: nenhum worker sobreviveu à run (a parte que "verde" sozinho não vê)
pgrep -fl vitest
# (sem saída)  → a tabela de processos está limpa: nada orfanizou. ISSO é a prova.

Se em vez de vazio o pgrep listar PIDs node … vitest ainda girando, você reproduziu a assinatura do incidente — e a rede de operação entra: pgrep -f vitest | xargs -r kill -9. Para conferir o veredito por código de saída diretamente:

# o exit code é o que o loop automatizado lê para decidir (sem ler a saída inteira)
pnpm test:safe; echo "exit=$?"
# exit=0   → segue o loop
# exit=1   → para e corrige o teste vermelho
# exit=124 → estourou SAFE_TEST_TIMEOUT_MS (padrão 600000 ms): mata o grupo e caça o hang

Fixe os conceitos (flashcards)

Clique pra virar. Tente lembrar a resposta antes de virar — recuperação ativa fixa mais que reler.