Swarm: paralelismo com profundidade limitada

O swarm tem exatamente três papéis, ordenados por profundidade: ROLE_DEPTH = { orchestrator: 0, lead: 1, worker: 2 } e MAX_DEPTH = 2 (packages/swarm/src/types.ts:25–32). Um worker é FOLHA — "cannot spawn". O limite é estrutural duas vezes: no schema, subtasks são taskSpecBaseSchema (sem campo subtasks, types.ts:117–124 — aninhamento limitado a um nível POR TIPO); e em runtime, canSpawn(depth) = depth < MAX_DEPTH (orchestrator.ts:107). Recursão infinita de agentes não é um risco monitorado — é um estado irrepresentável.

Pense como… uma obra com mestre de obras (orchestrator), encarregado (lead) e pedreiros (workers): o pedreiro não contrata ninguém — se a tarefa dele precisar de mais gente, isso volta para o encarregado decidir. Onde quebra: numa obra o limite é informal; aqui o pedreiro-que-contrata simplesmente não compila (o tipo da subtask não tem onde declarar subtasks).

O contrato de entrada é swarmOptionsSchema (packages/mission/src/mission-options.ts:102–121): promptTemplate OBRIGADO a conter o placeholder {{item}} (refine com mensagem própria, :108–110), items de 1 a 128 strings, tier default T2, maxConcurrency default 1 e um ramp opcional (initialLimit 5, intervalMs 700 — subida gradual de concorrência). O compilador compileSwarmToLead (packages/mission/src/compiler.ts:245–286) expande cada item com replaceAll('{{item}}', item) e monta UM lead (roleHint: 'lead') cujas subtasks são os prompts expandidos.

// trecho real, não editado
const prompt = swarm.promptTemplate.replaceAll('{{item}}', item);

if (seenPrompts.has(prompt)) {
  const firstItem = seenPrompts.get(prompt)!;
  throw new Error(
    `Duplicate prompt generated for items "${firstItem}" and "${item}"`,
  );
}

No VM, h.swarm (packages/vm/src/hooks.ts:248–292) valida as options, compila o lead e prefixa os ids: swarm-N-lead e swarm-N-task-0… (hooks.ts:270–277). Por quê? Porque a run inteira compartilha UM journal keyed por id — "task ids are prefixed with a per-hook counter so multiple calls inside the same plan never collide in the shared store" (hooks.ts:52–54); o orquestrador ainda reprova ids duplicados em qualquer ponto da árvore antes de journalizar (checkUniqueIds, orchestrator.ts:141–150, 170–175).

runSwarm (packages/swarm/src/orchestrator.ts:158–242) é o mesmo caminho para tudo: valida o spec, checa unicidade de ids na árvore INTEIRA, monta a fila (createQueue), faz resume-or-start (replayInto reaplica o estado durável; task running órfã de um processo morto é rebaixada a ready e re-tentada — "at-least-once execution", orchestrator.ts:181–187), declara task-enqueued idempotente para toda a árvore (:198–211), estaciona o inelegível (parkIneligible → ledger T4, :213–214, 250–271) e então drena: enquanto houver ready, roda um lote limitado por maxConcurrency, um lead abre sub-run um nível abaixo (limitado por canSpawn) e uma folha executa o worker (:216–228).

A fila é o portão de dependência: "a task is ready only when every id in its dependsOn has reached done" (packages/swarm/src/queue.ts:17); sem deps nasce ready, com deps nasce blocked (queue.ts:57), e a promoção blocked → ready acontece quando os deps completam (queue.ts:155–163). O "pronto" de um worker é um RENAME atômico: o relatório é escrito em arquivo de progresso e renomeado para <taskId>.complete.md / .failed.md — "the orchestrator watches only for the terminal names, so it never observes a partially-written report" (packages/swarm/src/worker.ts:24–29, 37–38).

As três fachadas diferem no que persiste: h.agent e h.swarm são CACHEADOS — a chave é sha256(JSON estável de {prompt, opts}) (computeCacheKey, packages/vm/src/cache.ts:20–21), guardada em <runDir>/workflows/<wf-id>/cache.json (cache.ts:23–24). Para h.swarm, a chave cobre description, subagentType, promptTemplate, items, tier, maxConcurrency, modelId, ramp (hooks.ts:254–262) — mude UM item e é outra chave. Já h.mission NÃO cacheia o resultado: ele persiste o SPEC compilado em specs/mission-N.json no run-dir (hooks.ts:228–239) e conta com o resume do próprio swarm (journal + checkpoint) para não repetir trabalho — tasks terminais não re-executam num replay.