How agents are dispatched

torta start runs an engine in the board’s process; torta watch runs one on its own.

What the engine looks at

Each tick, for each agent in the roster, the engine:

1. Takes back any ticket a dead session left behind (see budgets and leases).
2. Skips the agent if it already has a session running.
3. Skips it if its wip folder is occupied.
4. Otherwise sorts the todo queue and takes one candidate: hotfixes first, then oldest.

Candidates from every agent are then ordered by urgency and by a round-robin cursor.

What stops a launch

Before each launch the engine re-checks and skips with a reason:

• the kill switch, .torta/DISPATCH_OFF
• the concurrency cap, default 3
• a cooldown on that agent, default 60 seconds after a session ends
• backpressure
• a busy home, meaning another session holds the agent’s lock

Every decision is recorded as a dispatch event, including ones that started nothing.

The dispatch settings

These live under workflow.dispatch in torta.json:

Key	Default	What it does
maxConcurrent	3	how many sessions may run at once
staleLockMs	120000	when a session lock counts as dead
cooldownMs	60000	the pause after a session ends
sweepMs	15000	the periodic re-look, on top of file events
killPollMs	1000	how often the kill switch is polled
priorityTypes	["hotfix"]	ticket types that jump the queue

torta watch --cap <n> overrides the cap for one run.

The runners

Pick one with --runner:

• stub says what it would start and starts nothing. It is the default for torta watch.
• pty delivers the work into the agent’s pane on the board, which you can take over mid-ticket. It needs a board running.
• sdk runs headless Claude Agent SDK sessions, with the full budgets and the approval intercept before a transition.
• auto uses pty when a board is up and sdk when it is not. torta start uses it.

The pty runner gives up the token budget, the tool-call budget and the approval intercept; its delivery is logged as a pane_deliver event.

One engine per workspace

Torta refuses a second engine over one workspace. The refusal names the command already running, its pid and start time, and suggests torta start --no-engine.