Loops

A loop is an edge pointing back at an earlier node. Nothing else marks it, so the interesting question is never how to write one. It is how the loop stops.

Orbital gives you four ways to bound a loop, and they solve different problems.

Repair rounds

A repair budget bounds corrections of one episode of work. Put repair_budget="answer" and repair_round="retry" on the edge that sends work back for repair, and give it an exhausted partner with the same condition, the same budget and a different weight. After five unsuccessful rounds the exhausted edge runs once instead. A reset edge on demonstrated success clears the budget so the next episode starts fresh.

This is the bound to reach for when an agent may need several corrections but must not correct forever. How to do looping shows a complete graph with all three rounds.

Visit caps

max_visits on a node caps every visit to that node for the life of the run, whatever the reason. max_visits on the graph caps total agent turns and defaults to 200; commands and waits do not spend it. Exceeding either limit holds the run for an operator rather than routing anywhere, so treat both as a guard rather than as the design.

Waits

A poll loop watches something outside the run: a pull request, a build, a queue. Put an insulator in it. Waiting spends no agent visits and the operator can skip the remaining time when the observation should run again now.

Loop restart

loop_restart="true" on the edge back clears iteration context, completed stage history and thread sessions, while keeping the original inputs, run identity, visit accounting and repair budget state. Use it when the next pass is a new episode rather than another attempt at the same one. Without it, the loop accumulates the whole history of every previous pass in each prompt.

Failure is not a loop

A failed stage takes a matching conditioned edge and never the ordinary fallback. Route outcome == 'failed' to a repair prompt that reads {{ context.failure_reason }}, and return to the observation or review that proves recovery. Read the failure reason before deciding to retry: an authentication failure needs credentials, and asking the same unauthenticated harness again cannot repair it.

Make exhaustion visible with a terminal or a reassessment step. A failed terminal ends the run; an unrouted failed stage holds for an operator. Troubleshooting explains how to tell them apart in the interface.