O vazamento de órfãos do vitest

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 uma lição sobre corrigir a interação, não só uma causa.

As duas causas — nenhuma fatal sozinha

Este é o coração da lição. O vazamento precisou de ambas verdadeiras ao mesmo tempo:

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 o wrapper e um hang dentro do grupo ainda trava um core até o timeout de relógio. Ambas as camadas são entregues.

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',

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 */ }
};

• 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.

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.

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.

As regras de operação que decorreram disso

Confusões comuns