Tickets, runs, and review

A ticket describes an outcome. A run is an agent’s attempt to deliver it. The ticket keeps its identity when you restart a failed run, so you can inspect the history without creating another task.

Follow the lifecycle

The normal ticket lifecycleAgent work → human review

1. 01QUEUED
   Describe the work

   Waits for capacity and accepted prerequisites.

   Your ticketdg ticket
2. 02RUNNING
   Agent takes over

   Works in its own branch and Git worktree.

   Agent at workdg show ID
3. 03READY
   Your review starts

   Inspect the commit, run tests, and request changes.

   Your reviewdg chat ID
4. 04DONE
   Merge and accept

   Frees capacity and releases dependent tickets.

   Accepted by youdg accept ID

READY is the handoff: the agent has reported a commit. You review and merge it before accepting the ticket.

A run that ends without reporting completion becomes FAILED. Restarting that ticket reuses its worktree and session; cancelling work closes it as CANCELLED.

State transitions

View Mermaid source

stateDiagram-v2
    direction LR
    [*] --> queued: dg ticket
    queued --> running: a supervisor starts
    running --> ready: dg finish
    running --> failed: timeout or error
    failed --> running: dg restart
    failed --> ready: dg finish after dg chat
    ready --> done: dg accept
    done --> [*]

dg cancel can move any non-terminal state to CANCELLED. Those paths are omitted to keep the diagram readable. DONE and CANCELLED are terminal states.

State	What it means	What you do next
QUEUED	Waiting for capacity and completed dependencies.	Check the queue or adjust queued work.
RUNNING	An agent is working in the ticket worktree.	Let it work, or cancel if the task should stop.
READY	A commit has been reported for review.	Review, test, merge, and accept.
FAILED	The run ended without successfully reporting completion.	Inspect the result; restart or continue the session.
DONE	A person accepted the merged work.	Nothing further is required for this ticket.
CANCELLED	A person closed the task.	Inspect the retained worktree if needed.

dg finish records a commit and makes work READY. dg accept closes reviewed, merged work as DONE. These are separate steps because the agent’s completion and your acceptance are different decisions.

Capacity includes work waiting for review

Both RUNNING and READY consume capacity. If runs is 2, one running ticket and one ready ticket fill the queue’s two slots. Another ticket waits even though only one agent is actively working.

dg config get runs
dg config get max_runs_per_project

This keeps the amount of unfinished work bounded, including your review backlog. Accepting reviewed work frees a slot. The per-project limit can further constrain a repository within the shared queue.

A dependency is satisfied only when its ticket becomes DONE. READY is not sufficient, and cancellation does not satisfy a dependency.

Each ticket has its own checkout

Delegator creates a branch and worktree for the run. Your primary checkout remains the place where you integrate reviewed changes. The ticket record connects the worktree to the agent session, reported commit, and run history.

dg show 42
dg show 42 --worktree-only
dg show 42 --branch-only

Use an actual ticket ID in place of 42. Worktrees share Git history but have separate checked-out files. They still share machine resources such as ports, databases, credentials, and processes; they are not sandboxes.

Accepting removes the worktree. Cancelling keeps it for inspection. Neither action is a general cleanup policy for branches, logs, or historical ticket records.

The inbox and the full history

dg shows the inbox. dg list includes every ticket, across all statuses and projects. The done_hours setting controls how long accepted tickets remain in the inbox’s DONE section; it does not delete their records.

Next: reviewing work, dependencies, or multiple projects.