Modo Tower

O Tower mode (modo Tower) transforma uma sessão do Jarvis Code em uma torre de controle para vários agentes trabalhando no mesmo repositório ao mesmo tempo. Você declara um objetivo; o agente principal para de escrever código e passa a dividir o trabalho em missões, criar um worker para cada uma em seu próprio git worktree, criar revisores para auditar os branches e mesclar apenas o que passa na revisão.

Enquanto o modo de metas conduz um único agente em direção a um resultado ao longo dos turnos, o Tower mode coordena uma frota. Use-o quando uma tarefa se divide naturalmente em partes que podem avançar em paralelo e que, de outra forma, colidiriam nos mesmos arquivos.

Experimental

O Tower mode é um recurso experimental e vem desligado por padrão. Ele roda apenas no engine padrão agent-core-v2, cria branches e worktrees do git no seu repositório e seu protocolo ainda muda entre releases. Não o use em um repositório que você não possa inspecionar depois.

Como habilitar

O Tower mode é controlado pela flag experimental tower. Ative-a de uma destas duas formas:

JARVIS_CODE_EXPERIMENTAL_TOWER=1 jarvis

Ou abra /experiments na TUI, habilite Tower mode e reinicie o CLI. O reinício é necessário nos dois casos: a flag é lida uma única vez, quando o engine monta suas features, então alterná-la em /experiments no meio da sessão não cria as ferramentas do tower até o próximo início.

Com a flag ligada, /tower aparece no painel de comandos de barra e uma linha Tower mode aparece em /status.

Requisitos

O Tower mode executa operações reais de git, então o diretório de trabalho precisa ser um repositório git com pelo menos um commit. Quando não é, o agente trata assim:

• Diretório vazio: executa git init e cria um commit inicial vazio, e então continua.
• Diretório não vazio: nunca adiciona tudo às cegas. Ele inspeciona o diretório, mostra o que encontrou e pergunta uma única vez se deve inicializar e commitar. No modo de permissão auto ele não consegue perguntar, então para e informa os dois comandos para você executar por conta própria.

As missões partem de um único branch base e voltam a ele. Esse branch é registrado uma vez, quando o workspace é criado. Por padrão é o branch que está no checkout do worktree principal. Somente branches locais são aceitos; uma referência de rastreamento remoto como origin/main não pode receber merges, então crie um branch local antes. Enquanto o checkout principal estiver em outro branch (ou destacado), o trabalho prossegue mas os merges ficam bloqueados até você voltar ao branch base.

Iniciar uma execução

Escreva o objetivo depois de /tower:

/tower Divida a refatoração do renderer entre as camadas de build, shader e testes e entregue na main

Esse único comando liga o modo e envia o objetivo como seu próximo prompt. O agente então inicializa o workspace do tower, planeja as missões e lança a frota sem esperar outro turno seu.

Para ligar ou desligar o modo sem enviar um objetivo:

/tower on
/tower off

O Tower mode pode falhar ao ligar por três motivos, e o CLI informa qual: o experimento está desligado, o experimento acabou de ser ligado e precisa de um reinício, ou outra sessão já é dona do tower deste workspace.

O que acontece durante uma execução

A execução tem três papéis.

Você é dono do objetivo. Pode falar, redirecionar ou acrescentar requisitos a qualquer momento, e nada na execução fica esperando por você. Suas mensagens são tratadas como mudanças de plano, não como travas.

A torre é o agente principal, e existe exatamente uma. Ela nunca escreve código de produto. Ela planeja missões, cria workers e revisores, roteia mensagens, tria achados, mescla branches e reporta a você. As chamadas de ferramenta de orquestração dela continuam seguindo o modo de permissão da sua sessão.

Workers e revisores são subagentes em segundo plano criados pela torre no perfil tower-worker. Cada worker é dono de uma missão e trabalha em seu próprio git worktree em .tower/worktrees/; cada revisor audita um branch. Eles são fixados no modo de permissão auto ao serem criados, porque rodam sem supervisão, e uma troca de permissão da sessão inteira nunca os tira desse modo. Eles não podem fazer perguntas a você — o perfil deles não tem AskUserQuestion — então escalam para a torre.

O fluxo que a torre segue é fixo:

1. Init cria o workspace .tower/ e registra o branch base.
2. Plan divide o objetivo em missões, tipicamente de duas a quatro. Cada missão recebe um id (M1, M2, …), um branch chamado feat/<slug>, um worktree isolado, um conjunto de globs de escopo, uma lista de tarefas e dependências opcionais de outras missões.
3. Spawn lança um worker por missão desbloqueada, todos de uma vez em vez de um por vez.
4. Supervise roda a cada despertar: a torre lê sua caixa de entrada e o painel, cria revisores quando o trabalho está pronto, retoma autores cujas revisões voltaram com pendências, responde bloqueios e tria achados.
5. Merge entrega cada branch pelo portão de merge, em ordem de dependência.
6. Teardown remove os worktrees quando toda missão foi mesclada ou abandonada, e reporta o resumo final.

Isolamento de escopo

Os escopos são o mecanismo que impede agentes paralelos de colidir, e são impostos por código, não por instruções. Missões de build precisam ter globs de escopo mutuamente disjuntos — a ferramenta de planejamento rejeita um plano cujos escopos se sobrepõem — e o portão de merge recusa qualquer branch que tenha alterado um arquivo fora do escopo da própria missão. Se uma missão legitimamente precisar de mais espaço, apenas a torre pode ampliar o escopo dela, e a mudança fica registrada.

Missões de investigação somente leitura são marcadas como surveys. O escopo de uma survey é informativo e não reserva nada, então surveys podem se sobrepor a missões de build; o worker não pode alterar código, e a missão é encerrada com um merge de diff zero e sem revisor.

O portão de revisão

Nenhum branch é mesclado sem uma revisão limpa. O portão recusa um merge a menos que tudo isto seja verdade:

• O último veredito de revisão do branch é limpo.
• Essa revisão foi escrita contra o tip atual do branch. Se o branch se moveu depois da revisão, uma nova revisão é obrigatória.
• Toda missão da qual essa depende já foi mesclada.
• Todo arquivo alterado está dentro do escopo declarado da missão.

Quando o portão recusa, o erro indica o próximo passo: designar um revisor, esperar as correções, revisar de novo um tip que se moveu, mesclar as dependências primeiro ou ampliar o escopo. Após um merge bem-sucedido, os branches que passam a conflitar precisam fazer rebase sobre a nova base e ser revisados novamente.

Os ciclos de revisão têm limite. Na quinta rodada, ou quando duas rodadas consecutivas relatam os mesmos achados, a torre interrompe o ciclo, avisa você e redireciona o trabalho.

Acompanhar uma execução

Peça o painel a qualquer momento:

/tower status

O painel lista cada missão com seu status e dono, o roster de agentes, o estado do portão de revisão de cada branch não mesclado (última rodada, veredito e se o commit revisado ainda corresponde ao tip) e o final do log de atividade.

Enquanto o modo está ativo, o rodapé da TUI mostra um selo tower ao lado dos demais indicadores de modo, e /status traz uma linha Tower mode.

Toda ação de todo participante é anexada a .tower/comms/log/activity.log. Quando algo parece errado, esse arquivo é o primeiro lugar para olhar.

Limites de concorrência

Os spawns do tower são limitados por um orçamento adaptativo, e não por um número fixo. O orçamento começa sem limite e encolhe quando o provedor retorna erros de limite de taxa, recuperando um slot a cada três minutos até um teto de 16 agentes de tower simultâneos. Depois de um episódio de limite de taxa, novos spawns ficam pausados por cerca de 60 segundos; uma requisição bem-sucedida libera a pausa antes. Quando um spawn é recusado, a ferramenta informa se foi a pausa ou o orçamento e o que fazer a respeito.

A escolha de modelo dos workers segue o pool de modelos de subagente: workers usam o modelo secundário configurado quando esse experimento está ligado, e herdam o modelo da torre caso contrário. Revisores sempre usam o modelo primário da torre.

Encerrar uma execução

Peça o encerramento a qualquer momento:

/tower teardown

O teardown remove os worktrees das missões e sai do Tower mode. Worktrees com alterações não commitadas são preservados e listados em vez de destruídos, a menos que a torre receba instrução explícita de forçar. Os branches são preservados. O diretório .tower/comms/ — estado, caixa de entrada, achados, revisões, missões e o log de atividade — é sempre preservado como trilha de auditoria.

Espera-se que a torre encerre por conta própria assim que toda missão for mesclada e nenhum item da caixa de entrada estiver pendente, então /tower teardown serve principalmente para parar antes.

Layout do workspace

Tudo o que o protocolo escreve fica sob .tower/ na raiz do repositório:

.tower/
├── comms/
│   ├── state.json          # Estado do workspace do tower
│   ├── MISSIONS.md         # Índice de missões legível por humanos
│   ├── missions/           # Um arquivo por missão
│   ├── inbox/              # Mensagens entre participantes
│   ├── findings/           # Achados estruturados registrados pelos agentes
│   ├── reviews/            # Um arquivo por rodada de revisão
│   └── log/activity.log    # Log de auditoria somente de acréscimo
└── worktrees/              # Um git worktree por missão ativa

Nota

Esses arquivos são escritos exclusivamente pelas ferramentas Tower*. Editá-los à mão — diretamente ou por um comando de shell — quebra o portão de merge. Adicione .tower/ ao .gitignore se você não quiser o workspace versionado.

Retomar entre sessões

Voltar ao Tower mode a partir de uma nova sessão do CLI adota o workspace existente em vez de reiniciá-lo. Missões, worktrees e o log de atividade são preservados; as entradas de roster da sessão anterior são aposentadas, porque ids de agente não podem ser retomados entre sessões.

Missões herdadas continuam reservando seus escopos, então a torre resolve a situação delas antes de planejar qualquer coisa nova: continua as que pertencem ao objetivo atual com workers novos e abandona as demais. Uma missão abandonada deixa de reservar arquivos, libera o merge das que dependiam dela, sai das verificações de conflito e permanece em MISSIONS.md como parte da trilha de auditoria.

Próximos passos

• Usando metas — conduza um único agente em direção a um resultado verificável
• Ferramentas integradas — a referência das ferramentas Tower*
• Comandos de barra — a superfície completa do comando /tower
• Agentes e subagentes — como funcionam os perfis de subagente e a escolha de modelo