Referência

Arquitetura.

Três planos e uma invariante. O control plane decide, o worker executa onde o código está, o cockpit observa — e nenhum CLI de agente toca o checkout principal, nunca. Esta página é o resumo; a referência completa é docs/ARCHITECTURE.md.

Os três planos

Control plane

Guarda ordens, runs, eventos, artefatos e leases em Postgres, e expõe REST e SSE. É quem conhece a máquina de estados e quem emite as leases que os workers reivindicam. Nada de agente executa aqui: este processo decide, não constrói.

Worker

Roda no host onde o seu código está. Reivindica uma lease, cria o worktree da ordem, invoca o CLI de agente e devolve o resultado. A credencial vive em FACTORY_WORKER_CREDENTIAL — variável de ambiente, nunca t25.yaml. Lease expirada é reclamada no ciclo seguinte, e uma completion que chega depois de a lease expirar é rejeitada em vez de aceita torta.

Mission Control

O cockpit em localhost:4173: board, log por run, aprovações, retries, custo, políticas por projeto e perfil de agentes, com os eventos de progresso chegando por SSE enquanto a ordem anda.

A máquina de estados

RECEIVED → SPEC → PLAN → AWAITING_APPROVAL → IMPLEMENTING
         → QA → REVIEW → PR_OPEN → DOCS → DONE

fuga: NEEDS_INPUT · FAILED · CANCELLED
volta: QA e REVIEW podem devolver para IMPLEMENTING

As transições legais são declaradas num lugar só e verificadas antes de qualquer mudança de estado — nenhum trecho do pipeline escreve o estado direto. Cada mudança emite um evento, que é o que o cockpit vê chegar.

Os nomes de missão existem só onde há correspondência operacional real — o cockpit segue mostrando o estado técnico, não o apelido.

Isolamento por worktree

É a parte deliberadamente paranoica do sistema, e a que não se mexe sem ler os comentários de segurança do módulo:

• Cada ordem ganha um worktree próprio em branch factory/<id>, criado a partir do branch padrão do repositório.
• Toda chamada a git passa por execução com lista de argumentos, nunca por shell — nome de branch e caminho jamais são interpolados numa string de comando.
• Todo caminho de worktree é verificado como estando dentro da raiz configurada, contra fuga por link simbólico ou ...
• A T25 só adota um worktree se os metadados de posse baterem e o caminho ainda estiver registrado no git worktree list. Um diretório que por acaso existe no caminho certo não é adotado.
• O cleanup recusa árvore com alteração não commitada e nunca remove à força.

Adapters de agente

Um adapter é a menor coisa possível: o nome do binário e como montar os argumentos. Toda a mecânica de processo — descobrir se o CLI existe, ler a versão, streamar saída, matar no timeout — é compartilhada. Acrescentar um CLI novo é declarar um adapter, não reimplementar processo.

Duas escolhas valem registro: a execução é por lista de argumentos, sem shell no meio; e prompt muito grande vai para arquivo temporário em vez de argumento, porque a linha de comando tem teto de tamanho no sistema operacional.

O roteamento por papel é uma cadeia de preferência, não um CLI fixo: a T25 usa o primeiro da lista que estiver disponível. Ver configuração.

Execução durável

A execução não é uma chamada de função que precisa sobreviver ao processo: é uma fila de leases. A ordem é enfileirada, um worker reivindica com prazo, e ao terminar confirma ou devolve. Se o worker morre no meio, a lease expira e o trabalho volta para a fila — é a recuperação de queda, e ela não depende de ninguém lembrar de limpar estado.

Onde está o código

Próximo Configuração: as seções do t25.yaml →