Orchestrating in practice

The tools live in MCP tools and the contract in Writing a contract. This page is what an orchestrator needs to remember while the board is running — each item has already cost a wasted round when ignored.

deps fire by themselves

Symptom: the child starts the moment the parent becomes done, or stays idle when you expected it to stop.

On an autonomous board, a pending task whose deps are all done is dispatched on its own — including at birth, if the deps were already ready. Create the child before the parent’s done if you want autodispatch to pick it up. The other side: when you pause a front, mark dependents as blocked with a question (update_task / structured question); otherwise they start by themselves as soon as the parent closes.

send_to_card only enqueues

Symptom: the tool returns ok and the orchestrator treats the message as read and done.

Delivery enters the card’s queue; the real outcome comes from get_delivery. unconfirmed is common: the app typed, the agent has not acked yet. Confirm by reading the card with read_card before assuming effect.

A chance to refuse needs a re-read

Symptom: the brief says “if you lack context, say so and stop” — and the orchestrator keeps treating the card as active.

When the message gives the card the option to refuse, read the scrollback afterward. Do not count the card as active without seeing the reply.

read_report targets the card

Symptom: the orchestrator passes a task id and finds no report, or reads the wrong report on a later round.

read_report’s target is the card id, not the task’s. For several rounds on the same card, set afterSeq to the previous seq. A card linked to several tasks may return ambiguous: true: check the taskId inside the report. The on-screen report notice may name another task on the same card — the payload is the source.

Review wanted needs a reviewer role

Symptom: the implementer calls done/failed and the tool refuses; or a live card “reviews” without writing a verdict.

With review: "wanted", only a card linked as reviewer writes done/failed. To reuse a reviewer already on the board, use send_to_card with linkTaskId and linkRole: "reviewer" (or link_task_card with the same role) — without the link, the message is not a judgment.

Gates on a shared tree

Symptom: a red that is not yours, or a green that vanishes on the next run.

Gates and heavy suites on a tree several cards are editing mix in-flight work; the gate report names the dirty files. Heavy command of your own: run_locked or acbridge gate-lock -- (same lock as the gate-runner; --scope machine when measuring performance). A tool outside the repo (binary, installed CLI): declare it in gateToolPaths on the board context so the runner can find the path.

Territory across repos

Symptom: two cards in different repos on the “same relative path” and the guard collides; or a shared file with no trail.

On a board with several repositories, use an absolute path for territory — a relative one collides across repos. For a file two cards need, use shared:<path> (<note>). overrideTerritory (orchestrator only, on deliver) passes the guard with a reason and stays on the task trail — it is not a silent shortcut.

Card reuse and context

Symptom: the affine card “forgets” the contract or mixes two tasks.

Reuse a card only with context headroom. Near the window ceiling, open the new task on a new card — the cost of a spawn is lower than a contaminated report.

After a crash or re-login

Symptom: the card reopens and looks like the same agent, but the session or model changed.

Sessions can come back swapped; a hand-restored card may be on another session or model. Check the banner and the scrollback before the next task.

Provider without a reliable report channel

Symptom: the card worked and report never arrives (or arrives under the wrong id).

Some providers do not expose the MCP catalog reliably (e.g. a shared daemon). Take the result by send_to_card / message and close the task as reviewer — do not wait for a report the shim cannot sign. See acbridge (CLI).