switchyard

for agents: this page is markdown at https://switchyard.so/docs/queue-health.md; every page is listed in llms.txt.

Read the merge queue's health

Read, in one answer, whether the merge queue is merging, how long a task takes from submit to merged, what waits, and whether a person has to do something.

You will have: the merge queue's state in a word, one sentence that says it, and the one thing that needs a person when there is one. Works with: the board, yard, MCP (yard_queue_health), REST. Any key of the project reads it, and reading it changes nothing.

What one read answers

Switchyard works the answer out from the project's own history, over a window: the newest 200 decisions, none older than 24 hours. A decision is a task merged or a task sent back. Every reader of a project gets the same answer.

The answer carries:

The REST API page has the route, and the OpenAPI document has every field.

Read it on the board

Open the project's merge queue page. A strip under the page's title shows the state as a mark and a word, Switchyard's sentence, and four numbers: submit to merged, sent back, waiting, and check machines. A quiet merge queue, where each of the four would read none, shows the sentence alone; a number that is not known always keeps its place.

The strip is one button. A click, Enter or Space opens the numbers in full below it: the window, each number with its counts, what merging is doing, a row for each lane, what each level means, and a list headed not known from the records. Escape or close closes it.

When something needs a person, a line headed needs a person under the strip shows Switchyard's sentence, a link to the place that shows it, and the command to copy when there is one. On app.switchyard.so, the link for a spending limit or a card opens the organization's billing page.

The project's overview shows the state and the sentence on one line in its merge queue box.

Read it from the terminal

In a clone of the project, run:

yard queue health
Output
merge queue: healthy
  14 tasks are in the merge queue; submit to merged is typically 1m 36s.
  needs a person: nothing

  submit to merged   typical 1m 36s · 99th percentile 4m 11s         healthy
                     193 tasks merged since 10:26 UTC on 17 November · 6 waited for an approval
  sent back          7 of 200 (3.5%)                                 healthy
                     causes not known
  waiting            14 tasks · oldest 44m (task 790)
                     14 free, oldest 44m (task 790) · 0 held · 6 under test
  check machines     22 of 193 finished tests waited · typical 35s · slowest 58s
  merging            not paused · not held

  lane       waiting   oldest   merged      typical     high
  hotfix     0         none     not known   not known   not known
  priority   0         none     not known   not known   not known
  normal     14        44m      not known   not known   not known

  not known, not zero: spending holds in window, lane of merged, send back cause

The first line is the state in a word. The second is Switchyard's sentence. The third is the one thing that needs a person, or nothing. The last line lists what is not known.

When a person has to act, the third line says who, and a fourth gives the command when there is one:

Output
merge queue: held
  Nothing merges: the organization is at its spending limit, which an owner, admin or billing member can raise; new work is still taken until 09:00 UTC on 20 November; 3 tasks wait.
  needs a person: An owner, admin or billing member of the organization can raise the spending limit.
  command: yard org limit

yard queue health --json prints the answer as Switchyard sent it. The exit status is 0 for any state, because a slow merge queue is not a failed command. A script reads state from the JSON.

Read it as an agent or a script

Over MCP, call yard_queue_health. It takes no input and returns the answer unchanged.

Over REST, send a key of the project. A task's key, an agent group key and the project admin key all read it:

curl -sS https://app.switchyard.so/v1/projects/your-project/queue-health \
  -H "Authorization: Bearer $SWITCHYARD_TOKEN"

Durations are whole milliseconds, and times are ISO 8601 in UTC. The answer holds no age: work an age out from a time in the answer and your own clock.

The states

The state is the first of these that is true, from top to bottom.

StateWord on the board and in yardWhat it meansWhat to do
frozenfrozenNothing merges: main failed its checks after a merge. merging.frozen.since says whenWait. When Switchyard could not put main right automatically, needsPerson says that a project admin decides what main becomes
heldheld; held, work refusedNothing merges: the organization is at its spending limit, needs a card on file, or has a payment that failed. While merging.held.state is held, new work is still taken until merging.held.graceEndsAt. Once it is refused, new work is refusedTell the person that needsPerson names. Do not send a refused submit again in a loop
pausedpausedA project admin paused merging. merging.paused says who, why and until when. Hotfix tasks still mergeKeep working. With no end set, a project admin runs yard resume
stallednot movingThe merge queue has not moved on since merging.stalled.since, and merging.stalled.reason says whyA project admin looks at what holds it on the merge queue page
quietquietNo task waits, and no task merged or was sent back in the last 24 hoursNothing
not_knownnot knownThe submit time of a merged task in the window can no longer be read, so submit to merged is not known. It is never shown as healthyRead the other numbers. submitToMerged.submitNotKnown counts the tasks
too_fewtoo few to judgeFewer than 10 tasks merged in the window, so submit to merged gets no levelNothing. The sentence still gives the typical time when there is one
slowslow; very slowSubmit to merged is past a threshold. The sentence names the number that set the levelRead machineWait, window.overlap and lanes for where the time went
many_sent_backmany sent back; very many sent backThe share of decisions that were tasks sent back is past a thresholdRead sentBack.causes, and fix the cause before you submit more
healthyhealthySubmit to merged is judged and within the first threshold, and few tasks are sent backNothing

A state at level red has the stronger word: very slow, very many sent back, or held, work refused. frozen and stalled are always red. paused, quiet, too_few and not_known have the level none.

When submit to merged and the share sent back are both past a threshold, the state is slow and its sentence says both. When the share sent back is at the worse level of the two, the state is many_sent_back.

The answer's limits carries the thresholds, so a client never hard-codes them. Today they are:

LevelTypical submit to mergedSlowest or 99th percentileSent back
healthyup to 2mup to 5munder 5%
slow, or many sent backup to 4mup to 10m5% to 15%
very slow, or very many sent backbeyond thatbeyond thatover 15%

Submit to merged is healthy only when both its typical value and its high value are within the healthy threshold.

Small samples

Switchyard does not judge a handful of tasks:

Each lane (hotfix, priority, normal) is judged from its own merged tasks in the same way. Move a task ahead in the merge queue says what each lane does.

What is not known

A number that Switchyard's records cannot give is null, and its code is in notKnown. It is never 0. The board says not known, and yard prints not known and lists the codes on its last line. A null that means "none" has no code: no task waits, or nothing is held.

CodeWhat is not known
under_testhow many waiting tasks are under test
oldest_freewhich is the oldest waiting task that nothing holds
for_personhow many held tasks wait for a person
paused_timehow long merging was paused in the window
spending_holds_in_windowwhether a spending limit, a card or a payment held merging in the window, and for how long
hold_sincesince when the hold that runs now has held merging
waited_for_approvalhow many merged tasks waited for an approval
lane_of_mergedwhich lane each merged task merged in
send_back_causewhy the tasks sent back were sent back
machine_waithow long finished tests waited for a check machine
submit_timewhen some merged tasks were submitted, and so how long submit to merged took
oldest_waitingwhen the oldest waiting task was submitted
held_counthow many waiting tasks are held

A field that is known in part is not null and has no code. sentBack.causeNotKnown counts the tasks sent back with no cause recorded, and laneNotKnown counts the merged tasks with no lane recorded. waitingLaneNotKnown counts the waiting tasks whose lane is not known.

These limits are the ones you are most likely to meet:

The one thing that needs a person

needsPerson is null, or the first of these that applies:

kindWhenplacecommand
frozenmain failed its checks after a merge and could not be put right automaticallymerge_queuenone
heldthe organization is at its spending limit, needs a card, or has a payment that failedspending_limityard org limit at the spending limit; yard org card for a card and for a payment that failed
stalledthe merge queue has not moved onmerge_queuenone
pausedmerging is paused with no end setmerge_queueyard resume

Its fields:

The answer carries no amount of money, no person's name from billing and no link that acts. The hold's whole reason, said by role, is in merging.held.reason.

yard org limit and yard org card show a person where the limit and the card stand. Only a person signed in in a browser raises a limit or adds a card. No agent and no key does.

The answer's type also has the kind waiting, with the place overview, for tasks that wait for a person. No answer gives it, because that count is not known (for_person). Pay and set a spending limit has the steps.

How fresh the answer is

For agents

Read the merge queue's health before you bring more agents to a project, and when a submit of yours waits longer than you expect.

  1. Read state, sentence and needsPerson first. Pass sentence on unchanged.
  2. When needsPerson is not null, tell your person its sentence and its command. Run the command only when your key has the role that who names. An agent never raises a limit or adds a card.
  3. Check notKnown before you use a number. A field listed there is not 0.
  4. Then act on the state:
StateWhat an agent does
healthy, quiet, too_fewSubmit as usual
not_knownSubmit as usual. Do not report the merge queue as healthy
slowSubmit as usual, and expect a longer wait. When machineWait shows tests waiting for a check machine, more agents wait for the same machines
many_sent_backRead sentBack.causes. Fix that cause in your own task before you submit
pausedKeep working and submit. Submitted tasks are still tested, and they merge when merging resumes
held, with merging.held.state heldKeep working. Switchyard takes and keeps new work until merging.held.graceEndsAt. Tell your person
held, with merging.held.state refusedStop submitting. Keep your commits in your checkout, tell your person, and read again later. Never retry a refused submit in a loop
frozen, stalledDo not start more agents. Tell a project admin, and read again later

Next