Skip to content

Results from this documentation version only.

    ← Alcubi Delegator

    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.

    1. QUEUED
      Describe the work

      Waits for capacity and accepted prerequisites.

    2. RUNNING
      Agent takes over

      Works in its own branch and Git worktree.

    3. READY
      Your review starts

      Inspect the commit, run tests, and request changes.

    4. DONE
      Merge and accept

      Frees capacity and releases dependent tickets.

    READY is the handoff: the agent has completed the ticket. 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.

    View Mermaid source
    stateDiagram-v2
        direction LR
        [*] --> queued: dg ticket create
        queued --> running: a supervisor starts
        running --> ready: agent completes the ticket
        running --> failed: timeout or error
        failed --> running: dg ticket restart
        failed --> ready: agent completes the ticket after dg ticket chat
        ready --> running: changes needed
        ready --> done: dg ticket accept
        done --> [*]
    

    dg ticket cancel can move any non-terminal state to CANCELLED. Those paths are omitted to keep the diagram readable. A READY ticket can go back to RUNNING in two ways: you ask the agent for changes in dg ticket chat, or new work on the default branch conflicts with it and the agent resolves the conflict. Either way, it returns to READY once the agent completes the work. 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 The agent has completed the ticket and the work is waiting for your 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 ticket finish records a commit and makes work READY. It refuses a commit that conflicts with the project’s default branch. dg ticket accept closes reviewed, merged work as DONE. These are separate steps because the agent’s completion and your acceptance are different decisions.

    RUNNING, READY, and FAILED tickets 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. A failed ticket keeps its slot too, until you get it through to DONE or cancel it.

    Terminal window
    dg config get runs
    dg config get max_runs_per_project

    This keeps the amount of unfinished work bounded, including your review backlog and failed runs. 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.

    Delegator creates a branch and worktree for the run. If the project already has a branch with the name Delegator would use, it adds a suffix such as -2, so check dg ticket show 42 --branch-only for the actual name. 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.

    Terminal window
    dg ticket show 42
    dg ticket show 42 --worktree-only
    dg ticket show 42 --branch-only
    dg ticket runs 42

    Use an actual ticket ID in place of 42. dg ticket show displays the ticket record; dg ticket runs lists its recorded runs, newest first, including the agent, model, start and end times, and exit code when available. 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.

    dg shows the inbox. dg ticket 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.