How Dispatch Decides

TL;DR

Auto-dispatch turns free capacity into Project work, starting with the highest-priority active Project and resuming stranded attempts before choosing fresh Issues from the Frontier. Targeted work and people waiting on live replies receive slots before fleet work, while Suspend stops new selections after work already in flight finishes.

Dispatch is the activity that takes eligible Issues and drives their work through the Harness. It can target one named Issue or select work across every active Project in the fleet.

The selection and admission steps answer different questions. Selection chooses the next Issue. Admission decides which kind of work receives the next available slot.

Three Ways to Start Work

Auto-dispatch

Auto-dispatch is a standing fleet mode. While it's enabled, one fleet Dispatch stays available to turn free capacity into work. It parks when no Issue can be selected and wakes when the selection picture may have changed.

Three signals re-arm it:

• The interval tick runs every 5 minutes by default. It checks GitHub for changes that may make work selectable, including an Issue newly placed on the Frontier or one that can rejoin because its last blocker was resolved.
• A freed fleet slot re-arms Auto-dispatch as soon as a fleet Run concludes, so available capacity can take the next Issue immediately.
• A concluded Landing re-arms Auto-dispatch after a Pull Request lands or becomes blocked. This immediately revisits Projects whose selection may have changed.

Every re-arm uses the same selection path. It also reads the latest Project configuration, including rotated GitHub Credentials and changes to Project activity or priority. When a new Thread selects a Credential, it also selects that Credential's model and effort for the activity. Runs already in flight keep the configuration snapshot they started with.

If the primary Credential can't serve new work, a configured fallback brings its own billing identity, model, and effort. The fallback can therefore run at different tuning from the primary.

Manual Fleet Dispatch

Auto-dispatch is the recommended way to keep fleet work moving. When it's off, you can start a manual fleet Dispatch from the Dashboard for one on-demand pass. The pass keeps selecting as capacity becomes available, then returns when it finds no selectable Issue.

With Auto-dispatch enabled, the same Dashboard control becomes Scan now. It wakes the standing fleet Dispatch immediately, while keeping a single fleet Dispatch in control of selection.

Targeted Dispatch

A targeted Dispatch lets you choose one named Issue instead of leaving the next pick to fleet selection. The Dispatcher records the request against that Issue immediately. If a work slot is available, it checks that the Issue is still eligible and begins the attempt. If every slot is occupied, the request appears as queued and receives a newly freed slot before fleet work.

Targeted Dispatch normally follows the Project's Pacing setting, but you can choose Start anyway to override Pacing for that Issue.

Fleet States

The fleet reports one of five states:

State	Meaning
idle	Auto-dispatch is off and the fleet has no Runs in flight.
watching	Auto-dispatch is on, capacity is available, and no Issue can be selected.
paced	At least one active Project has eligible work held by an Outstanding Pull Request, and every other active Project is also out of selectable work.
running	The fleet has at least one Run in flight.
suspending	Suspend is active while the remaining fleet Runs finish.

A brief selection pass keeps the state implied by the Auto-dispatch setting: watching when enabled or idle when disabled. When one Project is Paced and another has work in flight, running takes precedence. The Dashboard shows the Paced Project and its Outstanding Pull Request separately.

Selection Order

Fleet selection scans active Projects by numeric priority, lowest number first. It takes the first available Issue and begins the next selection from the same ordered Project list. Inactive Projects stay outside fleet selection.

Within a Project, the order is:

1. Resume a stranded attempt. An Issue carrying agent-in-progress with no live Run resumes before fresh work starts.
2. Refresh Frontier membership. The selector rechecks dependency state so recently resolved blockers can move an Issue back to ready-for-agent.
3. Choose fresh work. Eligible Issues carrying priority-next come first. The remaining Issues are ordered oldest first.

Joining the Frontier and becoming selectable are related but distinct. The ready-for-agent label places an Issue on the Frontier. Claim state, Pacing, and other promotion vetoes determine whether the Dispatcher can select it at that moment.

Slot Priority

Admission grants each available general-concurrency slot in this order:

1. Targeted work. A targeted Dispatch or targeted Resume receives the next general slot first.
2. Interactive Turns. A person waiting synchronously in an Intake Session, Charting, Ticketing, or another live session comes next.
3. Fleet work. Auto-dispatch and manual fleet passes use the remaining general capacity.

Interactive Turns can also use the separately sized Interactive Reserve after general capacity fills. The reserve is dedicated to people waiting on a live reply. Targeted and fleet Dispatch use general capacity.

How Blocked Issues Rejoin the Frontier

Two checks keep dependency state current:

• The Frontier reconciler checks every open Issue on every watched Project every 1 minute by default. When the last blocker resolves, it moves the Issue to ready-for-agent even while Auto-dispatch is off.
• The pre-selection check refreshes dependency state immediately before each pick. An Issue whose blocker resolved seconds ago can participate in the selection already under way.

The background check keeps GitHub labels current over time. The pre-selection check closes the timing gap at the moment work starts.

How Fleet Dispatch Stops or Recovers

Suspend

Suspend stops new fleet selections and lets Runs already in flight finish. The fleet moves to idle after the last Run concludes. Turning Auto-dispatch off performs the same graceful transition.

Circuit Breaker

Three consecutive fleet attempts that fail for exactly the same reason trip the circuit breaker and stop the current pass from selecting more work. The Dispatcher returns any selected but unstarted Issue to ready-for-agent.

With Auto-dispatch enabled, each failed Run frees its slot and requests another scan. That scan starts immediately after the breaker stops the current pass, with its failure count reset to zero. A manual fleet pass ends instead when Auto-dispatch is off.

Project Fault Isolation

If GitHub can't be read while scanning one Project, Auto-dispatch skips that Project for the current pass and continues selection across the rest of the fleet. The next interval tick tries the affected Project again.

Selection Pass Diagnostics

When Auto-dispatch is enabled and no Selection Pass completes for at least one full tick interval, the Dispatcher writes one diagnostic log with the elapsed time, interval, and occupied-slot count. It writes a matching recovery log when a Selection Pass completes again.

These logs are for stack operators and don't require a Dashboard action. A fully occupied fleet can produce the same signal while healthy Runs are working. In that case, the signal clears automatically after work frees capacity and the next Selection Pass completes.

Related

• The Core Loop: how an idea becomes Issues, Runs, and a Pull Request.
• Work Model: why the Dispatcher watches Projects and bounds concurrent work.
• Watch a Project: how Priority, Active, Pacing, and labels affect selection.
• Abort, Pause, Resume, Delete: how controls affect an attempt already in flight.
• Label Reference: every Control and Classification Label and its effect on a pick.