O swarm: orchestrator → lead → worker

O swarm L3 é como o Alembic roda muitas unidades de trabalho ao mesmo tempo e sobrevive a crashes. Pense num canteiro de obra: um mestre de obras (o orchestrator) divide o serviço entre alguns chefes de equipe (os leads), e cada chefe coloca pedreiros (os workers) para executar. A graça está nas regras que impedem o caos: profundidade limitada, uma fila que só libera quem pode rodar, o disco como fonte da verdade, isolamento por git-worktree e um freio de mão para trabalho perigoso. Fonte: packages/swarm/.

01 · Três camadas, um nível de aninhamento

A hierarquia de papéis é orchestrator → lead → worker, e é deliberadamente curta. O orchestrator pode spawnar leads; um lead pode spawnar workers; um worker faz o trabalho-folha e nunca spawna. O número que prende tudo isso é MAX_DEPTH = 2: a profundidade de cada papel (ROLE_DEPTH) é orchestrator=0, lead=1, worker=2, e a profundidade máxima é justamente 2.

Como o aninhamento é limitado por construção e não só por convenção? No tipo. Uma task pode carregar subtasks — e quando carrega, ela é um lead: o orchestrator roda os subtasks como uma sub-run um nível mais fundo. Mas os subtasks são do tipo taskSpecBaseSchema, que não tem campo subtasks. Logo um subtask não pode carregar subtasks — o aninhamento é travado em um nível pelo próprio sistema de tipos, além da checagem em runtime por canSpawn.

O bound de uma linha: canSpawn(depth) = depth < MAX_DEPTH

A regra inteira que sustenta a árvore é uma única função, e o melhor jeito de internalizá-la é como um fluxograma de decisão sobre a profundidade: dado o depth de um nó, ela responde "spawna um filho?" comparando com o teto. Siga as setas — só a profundidade 0 e 1 passam; a 2 (worker) é o fundo.

02 · A fila — com portão de dependência, pronto significa pronto

Rodar concorrente sem regra é receita para desastre: uma task que depende de outra rodaria antes do pré-requisito existir. A fila do swarm resolve isso com um portão de dependências. Só tasks ready rodam, e uma task só vira ready quando todos os ids em seu dependsOn alcançaram sucesso-terminal (done). O grafo de dependências é honrado, não torcido.

A fila é pura contabilidade em memória sobre o estado das tasks; ela nunca executa nada — só responde "o que pode rodar agora?" e "a run terminou?". Antes de qualquer agendamento, validateGraph (estilo Kahn, redução de indegree) rejeita ciclos e dependências para ids inexistentes. Há três tipos de worker, e a diferença entre eles é o que de fato roda:

O sinal atômico de "done": renomear o report

Como o orchestrator sabe, sem corrida, que um worker terminou? Pelo rename do arquivo de report. O worker escreve o corpo num arquivo em progresso e, ao terminar, o renomeia para o nome terminal (.complete.md ou .failed.md). O rename é o sinal atômico — ou o arquivo final existe inteiro, ou não existe. Não há estado meio-escrito que o orchestrator possa ler errado.

O portão em ação: uma task espera as duas dependências

Veja três tasks. C declara dependsOn: [A, B]. Enquanto A e B não estiverem ambas done, C fica blocked — o orchestrador não a toca. Quando a última delas conclui, a fila re-avalia (a função regate) e promove C a ready:

03 · O ciclo de vida de uma task (a máquina de estados)

Toda task vive numa pequena máquina de estados de seis posições. Entender as setas dela é entender o swarm inteiro: o portão de dependências, o resume e o park são todos transições nesta máquina. As terminais (done, failed, parked) não voltam atrás — salvo a recuperação de órfãs, a única seta que reabre um estado, e que é exatamente o coração do resume (seção 05).

A run é completa (isComplete) quando nenhuma task está blocked, ready ou running. Uma task failed ou parked é terminal e não trava a conclusão — seus dependentes simplesmente nunca viram ready. Fonte: queue.ts.

04 · Monte a árvore de execução na mão (passo a passo → agora você)

Você viu a hierarquia e a fila. Agora trace uma run pequena na mão, devagar — recuperar o procedimento fixa mais que ver o resultado pronto. Considere uma run com quatro tasks: setup, build (dep: setup), test (dep: build) e um deploy marcado tier: T4.

05 · Resume seguro a crash — o filesystem é a verdade

Aqui está a peça que distingue um brinquedo de um motor de produção. O que acontece se a máquina morre no meio de uma run de 8 horas? O swarm não perde o trabalho. O estado é durável no disco: um journal append-only (events.jsonl) mais um checkpoint.json. Re-rodar a mesma run não recomeça do zero — ele reproduz o journal e continua.

A parte engenhosa é como ele trata um worker que morreu no meio do voo. A função recoverOrphans (orchestrator.ts:747) percorre os estados: toda task cujo último estado durável é running teve seu worker morto sem evento terminal — então é rebaixada de volta a ready e re-tentada. Isso dá execução pelo-menos-uma-vez, e como o enqueue é idempotente, o denominador do monitor cobre toda task mesmo após um crash no meio da declaração.

// packages/swarm/src/orchestrator.ts:747-755 (condensado) — recoverOrphans
const recoverOrphans = (queue, now) => {
  let count = 0;
  for (const state of queue.states()) {
    if (state.status !== 'running') continue;
    queue.applyState({ ...state, status: 'ready', updatedAt: now() }); // órfã → re-tentada
    count += 1;
  }
  return count;
};

A anatomia do diário: events.jsonl append-only + checkpoint.json

O que exatamente é gravado no disco? Um journal append-only (events.jsonl): uma linha por evento, cada uma com seq (contador monotônico por run), at e um payload validado por Zod contra o schema do kind. Periodicamente, um checkpoint.json condensa o estado reconstituível num ponto — o pré-seed do replay, nunca um corte. As espécies de evento (swarmEventKindSchema) são um conjunto fechado; veja a linha do tempo de uma run típica:

A run-id é content-addressed — e é por isso que o resume "encontra" o estado

Por que re-submeter a mesma run cai exatamente no diretório de estado já existente em vez de criar uma árvore nova? Porque o id da run é o hash do seu spec imutável: runIdFor(spec) = run-${shortHash(spec)} (ids.ts:30), um SHA-256 de 16 caracteres. Crucialmente, o hash usa canonicalJson (chaves ordenadas recursivamente), então a ordem dos campos no objeto não muda o digest — o mesmo goal + as mesmas tasks sempre resolvem para o mesmo runId, e portanto para o mesmo diretório on-disk.

A unicidade global de id por toda a árvore (checkUniqueIds, orchestrator.ts:141) é validada antes de qualquer coisa ser jornalada, porque a run compartilha um único journal chaveado por id — um id duplicado deixaria o estado de uma task sobrescrever o de outra e poderia envenenar um resume.

06 · Decisão: "este nó spawna ou é folha?" (fluxograma)

Junte a profundidade, os subtasks e o portão num único fluxograma de decisão — exatamente o que o orchestrator executa para cada task. Siga as setas: cada losango é uma pergunta que escolhe o caminho entre "vira um lead (sub-run)" e "roda como worker-folha".

O fold do lead: como os subtasks viram um único veredito

Quando uma task vira lead, seus subtasks rodam como uma sub-run — mas o orchestrator precisa de um resultado para a task-lead. Ele dobra (fold) os estados dos subtasks numa regra estrita: o lead é done se e somente se nenhum subtask ficou failed ou blocked. Um único subtask que falha (ou que nunca acendeu por uma dep aberta) já derruba o lead:

07 · Isolamento e o park T4 — fail-closed, ambos

Duas fronteiras do swarm são fail-closed: quando em dúvida, elas param em vez de seguir em silêncio. São o mecanismo de segurança do motor.

A precedência de classifyPark (park.ts:38) é deliberada — o primeiro motivo que casa vence, para o ledger registrar a causa mais específica: marcadores legal/security nos metadados primeiro, depois a flag/metadado irreversible, e por último a regra do tier T4. "When in doubt, park."

08 · O reward — heurístico, não aprendizado por reforço

O swarm tem um sinal de reward, e o nome engana de propósito. computeReward (reward.ts:74) é um escalar heurístico moldado — estilo PARL — e não é aprendizado por reforço: não há gradiente de política, não há replay buffer, não há atualização online de pesos. É uma conta determinística e explicável sobre três componentes, com um humano no loop.

E o sinal é inerte até aprovado: requiresApproval nasce true, então nada pode influenciar o roteamento futuro antes de um humano assinar (HITL). Só sinais aprovados (ou que nunca precisaram de aprovação) contam — isActionable. O reward molda a priorização com um humano no loop; não há treino.

O ramp do lead: arranque controlado, não enxurrada

Por que um lead não dispara todos os subtasks de uma vez? Para não saturar a máquina (e o gateway) no instante zero. O ramp começa com initialLimit (5) tarefas e solta +1 vaga a cada 700 ms até maxConcurrency. Detalhe que confunde: tarefas que terminam não devolvem vagas — o ramp governa o total lançado ao longo do tempo, como abrir um registro aos poucos:

E o lead transmite cada passo: o stream consult/update

Enquanto fan-outa, o lead emite um stream de lifecycle por subtask — uma união discriminada por kind, validada por Zod, para um observador AFK (ou um log de transcript compartilhado) acompanhar sem o dispatcher vazar internals. São quatro espécies; hoje o dispatcher emite o par terminal, e update fica reservado para quem fia progresso intermediário:

09 · Por que delegate_tool.py do Hermes é IGNORE (comparativo)

A matriz de fusão (§2.4) classifica o delegate_tool.py do Hermes como IGNORE — não porque delegar seja ruim, mas porque o Alembic já delega nativamente e com mais garantias. Veja o trade-off lado a lado: o que o swarm L3 oferece que uma tool de delegação simples não tem.

10 · Como isso se encaixa

O swarm não age sozinho — ele é o braço executor no meio da máquina. Antes dele, os gates decidem se e o que rodar; o swarm então roda exatamente as unidades aprovadas, em paralelo e com resume; e o que ele não pode tocar (T4/irreversível) ele devolve ao portão humano. Veja a peça (em destaque) dentro do pipeline real do Alembic:

Onde você está na metodologia: o swarm é o estágio de execução — o único que roda trabalho de verdade. Tudo antes dele (Scope, Council, Proof, Validator) é decisão; tudo depois (park T4, reward, aprendizado) é consolidação sob portão humano. Ele é o motor que pega o plano aprovado e o transforma em unidades concluídas, sem perder trabalho num crash e sem dar sozinho o passo perigoso. Veja o mapa interativo inteiro em a metodologia completa →.

11 · Na prática

O swarm não tem um comando "swarm" próprio — ele é o que alembic run aciona por baixo quando uma run tem várias unidades. Você o dispara com run e o observa com runs list, tui e tail; um replay retoma uma run que caiu. Os comandos abaixo são todos canônicos (CLAUDE.md):

# 1) Disparar uma run a partir de um spec (mission.json / tasks.json):
#    o swarm vira o executor — orchestrator divide em leads, leads em workers.
alembic run mission.json

# 1b) …ou a partir de um GOAL.md + plano (h.mission() com units[]):
alembic run --goal GOAL.md --plan alembic.plan.ts --yes

# 2) Listar as runs e seus estados (encontre a run-id content-addressed):
alembic runs list
# run-3f9a1c… · finished · 7/8 done · 1 parked (T4)

# 3) Acompanhar AFK — um dashboard de terminal por run-id:
alembic tui run-3f9a1c

# 4) …ou seguir o journal append-only em tempo real (events.jsonl):
alembic tail run-3f9a1c -f
# task-state  build   running
# task-state  build   done
# task-parked deploy  tier-t4   → reabra com approve/reject/propose

# 5) Caiu no meio? Retome do disco — content-addressed, sem refazer o feito:
alembic replay run-3f9a1c
# recoverOrphans: 1 task running órfã → ready (re-tentada)

Note o ciclo que toda a lição descreve, agora no terminal: run aciona o swarm; tail -f mostra cada task-state sendo jornalado; um task-parked tier-t4 aparece e não auto-roda; e se a máquina morrer, replay reproduz o journal e a recoverOrphans rebaixa a task órfã de running de volta a ready — exatamente o resume seguro a crash da seção 05. [uncertain] a forma exata das linhas do tail é ilustrativa do conceito (task-state / task-parked do events.jsonl); o formato textual impresso pode diferir.

Confusões comuns

Fixe os conceitos (flashcards)

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