GAIA

Appearance

Run a ticket: from claim to done ​

You'll learn what happens from the moment a conductor claims a ticket until the agent writes the next state — and what to do when the agent stops and waits for you.

A ticket is worked one state at a time, and each state is one run: a claim, a worktree, an agent session in a terminal tab, and finally a state write. Nothing you do starts a run directly; you make a ticket eligible and a conductor takes it.

Who gets to claim ​

A conductor claims a ticket when all of these hold:

  • the ticket belongs to the conductor's project and carries this conductor in its conductor_id — or has no workflow yet (an unclassified import), which any conductor of the project may pick up to qualify;
  • the ticket's state is claimable (every non-terminal state is) and, if the conductor's engine config narrows states, one of those;
  • every ticket in its blocked_by list is closed;
  • no live claim is on it, and the conductor has a free slot.

So the conductor on the ticket is the dispatch decision. The new-ticket popup preselects this checkout's conductor for exactly that reason; the edit popup lets you move a ticket to another machine by changing it. Among several eligible tickets, the conductor takes the highest priority first, then the oldest.

One run, start to finish ​

  1. Claim. The control plane grants the lease; the run exists as claimed.
  2. Worktree. The conductor ensures a git worktree for the ticket's branch under .gaia-worktrees/ in the checkout, based on the ticket's base branch, and runs the project's worktree hooks (a Drupal project brings up its own DDEV environment here).
  3. Tab. In herdr, a tab named <identifier> · <state> #<run> opens in the branch's workspace; the agent session starts in it, detached from the conductor. The run is running.
  4. Work. The agent reads the ticket and all comments, loads the skill that owns this step, and works — in the worktree, through the project's own commands.
  5. State write. The agent publishes its handoff and writes the next state. The control plane retires the run (done). The conductor's next finalise pass captures the transcript and the footprint and closes the hosted tab.
  6. Next state. If the new state is claimable, the conductor claims the ticket again — a fresh run, a fresh tab, the same worktree.

When the agent waits for you ​

A step that needs a decision asks in its tab and stops. herdr shows the tab's agent as blocked and, in the cockpit, the ticket's run stays running. Find it with:

sh
herdr tab list

and look for the tab whose label carries the ticket identifier. Answer in that tab. The three places a step asks by design are the plan confirmation at spec or diagnose, the result-and-review choice at coding, and the verdict confirmation at review; a step may also ask when the ticket leaves it a real choice.

Nothing happens for minutes?

A run that shows running with no comment appearing usually is a blocked tab nobody has looked at. Troubleshooting has the checklist.

Run states ​

StateMeaning
claimedthe lease is granted; the agent has not started yet
runningthe agent session is up
donethe state write retired the run
expireda claimed run whose lease ran out before the agent started — the ticket is claimable again
faileddispatch threw before the agent could work (a worktree hook, a missing executor); the cause is in the run's error log and the ticket is claimable again

A running run is never expired automatically: the agent may be alive and thinking, or blocked on you. Only a person can tell, which is why a stuck running run is a troubleshooting case rather than a timer.

Where things land ​

  • The run's log and footprint — on the run itself: open the ticket in gaia ui, Runs tab. The footprint (tokens, duration, turns, tool calls, model) is what billing rolls up.
  • The conductor's own log — log.txt in the checkout's .gaia/ workspace root; gaia conductor start --log-level debug makes it talk about every poll.
  • The worktree — .gaia-worktrees/<branch> in the checkout, kept across runs and torn down after done by gaia conductor reap or the conductor's own cleanup.
  • The merge request — linked on the ticket by the coding step; the review step reuses it.

Next ​