Orquestrar na prática

As ferramentas estão em Ferramentas MCP e o contrato em Escrever um contrato. Esta página é o que o orquestrador precisa lembrar enquanto o board roda — cada item já custou rodada perdida quando foi ignorado.

deps disparam sozinhas

Sintoma: o filho começa no instante em que o pai vira done, ou continua parado quando você esperava que parasse.

Num board autônomo, uma task pending cujas deps estão todas done é despachada sozinha — inclusive no nascimento, se as deps já estavam prontas. Crie o filho antes do done do pai se quiser que o autodispatch o pegue. O outro lado: ao pausar uma frente, marque os dependentes como blocked com pergunta (update_task / pergunta estruturada); senão eles começam sozinhos assim que o pai fechar.

send_to_card só enfileira

Sintoma: a tool volta ok e o agente trata a mensagem como lida e cumprida.

A entrega entra na fila do card e o veredito real vem por get_delivery. unconfirmed é comum: o app digitou, o agente ainda não acusou. Confirme lendo o card com read_card antes de assumir efeito.

Opção de recusar exige releitura

Sintoma: o briefing diz “se não tiver contexto, diga e pare” — e o orquestrador segue como se o card estivesse ativo.

Quando a mensagem dá ao card a opção de recusar, leia o scrollback depois. Não conte o card como ativo sem ver a resposta.

read_report mira o card

Sintoma: o orquestrador passa o id da task e não acha o report, ou lê o report errado numa rodada seguinte.

O target de read_report é o id do card, não o da task. Para várias rodadas no mesmo card, use afterSeq igual ao seq anterior. Um card ligado a várias tasks pode devolver ambiguous: true: confira o taskId dentro do report. O aviso de report na tela pode nomear outra task do mesmo card — o payload é a fonte.

Review wanted exige papel de revisor

Sintoma: o implementador chama done/failed e a tool recusa; ou um card vivo “revisa” sem gravar veredito.

Com review: "wanted", só um card ligado como reviewer grava done/failed. Para reusar um revisor que já está no board, use send_to_card com linkTaskId e linkRole: "reviewer" (ou link_task_card com o mesmo papel) — sem o vínculo, a mensagem não vira julgamento.

Gates na árvore compartilhada

Sintoma: vermelho que não é seu, ou verde que some na próxima corrida.

Gates e suítes pesadas na árvore que vários cards editam misturam trabalho em voo; o report do gate nomeia os arquivos que estavam sujos. Comando pesado seu: run_locked ou acbridge gate-lock -- (mesmo lock do gate-runner; --scope machine quando mede desempenho). Ferramenta fora do repo (binário, CLI instalada): declare em gateToolPaths no contexto do board para o runner achar o caminho.

Território entre repos

Sintoma: dois cards em repos diferentes “no mesmo path relativo” e o guard colide; ou um arquivo compartilhado sem rastro.

Em board com vários repositórios, use caminho absoluto no território — o relativo colide entre repos. Para um arquivo que dois cards precisam, use shared:<caminho> (<nota>). overrideTerritory (só orquestrador, na entrega) passa o guard com motivo e fica na trilha da task — não é atalho silencioso.

Reuso de card e contexto

Sintoma: o card afim “esquece” o contrato ou mistura duas tasks.

Reutilize um card só com folga de contexto. Perto do teto da janela, abra task nova em card novo — o custo de um spawn é menor que o de um relatório contaminado.

Depois de crash ou relogin

Sintoma: o card reabre e parece o mesmo agente, mas a sessão ou o modelo mudaram.

Sessões podem voltar trocadas; um card restaurado à mão pode estar em outra sessão ou outro modelo. Confira o banner e o scrollback antes da próxima task.

Provider sem canal de report

Sintoma: o card trabalhou e o report nunca chega (ou chega sob id errado).

Alguns providers não expõem o catálogo MCP de forma confiável (ex.: daemon compartilhado). Receba o resultado por send_to_card / mensagem e feche a task como reviewer — não espere um report que o shim não consegue assinar. Ver acbridge (CLI).