State Machine

Sortie maintains two layers of state for every issue it processes. The orchestration state tracks whether the orchestrator has claimed the issue and what it is doing with it. The run attempt phase tracks where a single agent invocation stands within its lifecycle. These are independent from tracker states (To Do, In Progress): they are Sortie’s internal bookkeeping.

See also: WORKFLOW.md configuration for active_states, terminal_states, handoff_state, and in_progress_state; error reference for error kinds that trigger retries; CLI reference for --dry-run mode that simulates dispatch without launching agents; dashboard reference for real-time visibility into orchestration state.

Orchestration states

Every issue known to the orchestrator is in exactly one of five states. The orchestrator is the single authority for these transitions: no other component mutates scheduling state.

flowchart TD
    UC([Unclaimed]) --> RN

    subgraph Claimed
        RN[Running] --> RQ[RetryQueued]
        RQ --> RN
    end

    Claimed --> RL([Released])
    RL --> UC

    classDef idle fill:#f0f0f4,stroke:#8b8fa3,color:#3a3d4a
    classDef active fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f,stroke-width:2px
    classDef waiting fill:#fef3c7,stroke:#d97706,color:#78350f
    classDef released fill:#f0f0f4,stroke:#8b8fa3,color:#3a3d4a,stroke-dasharray:5 5

    class UC idle
    class RN active
    class RQ waiting
    class RL released

    style Claimed fill:none,stroke:#3b82f6,stroke-width:2px,rx:8,color:#3b82f6

Transition details

Unclaimed → Claimed. Occurs during the dispatch phase of a poll tick. The issue must pass all candidate eligibility checks and a global or per-state concurrency slot must be available. Dispatch claims and launches in one step, so this path never leaves an issue claimed without a worker; RetryQueued and the retry entries rehydrated at startup are the two ways an issue is claimed with no worker running.

Running → RetryQueued. Five worker exit outcomes lead here (the first two do not apply when a soft-stop signal is active; see Claimed → Released below):

• Normal exit, issue still active, no soft-stop: continuation retry after 1 000 ms fixed delay.
• Normal exit, handoff fails, no soft-stop: continuation retry after 1 000 ms.
• Normal exit, handoff withheld by the evidence policy, no soft-stop, and the issue not found terminal by the read that outcome performs: exponential backoff retry (see backoff formula), the only one of these five outcomes that takes exponential backoff from a normal exit rather than the fixed continuation delay.
• Error exit, retryable: exponential backoff retry (see backoff formula).
• Stall timeout: worker is killed; exponential backoff retry is scheduled.

A worker exit is not the only way an entry gets queued: a reaction reconcile pass writes one directly for an issue whose session has already ended, which is how a CI fix, a review response, or a rebase reaches the dispatch path.

An issue holds at most one queued retry. When any of these outcomes finds one already queued (a reaction continuation scheduled while the session was still running, for example), the queued entry is left in place and the claim is kept, rather than the queued work being replaced. The queued entry runs on its own timer, and the outcome that deferred to it takes no further action.

RetryQueued → Running. The retry timer fires. The orchestrator reads that one issue from the tracker by ID (not the candidate list), confirms it is still eligible, acquires a slot, and launches a new worker. If no slot is available, the entry is rescheduled at the next attempt number, so its delay grows by one backoff step rather than repeating.

Claimed → Released. The claim is removed and no retry is scheduled:

• Reconciliation detects the tracker state is terminal or no longer in active_states.
• The retry timer fires and the per-issue tracker read reports the issue missing, terminal, or no longer in an active state. A reaction-kind entry is rescheduled instead of released.
• The max_sessions budget is reached.
• The max_tokens token budget is reached, either at a dispatch decision or by the in-flight check that cancels the running session.
• The worker error is classified as non-retryable.
• A handoff_state transition succeeds (the tracker now owns the issue). A run that declared no change was needed targets tracker.no_change_state instead where that field is configured; see handoff evidence.
• Soft-stop blocked: worker exits normally, claim released. No handoff transition, no continuation retry. Where the dispatch drives issue state, the issue is also parked with the escalation label and held out of dispatch until a release gesture. See the parked-issue release rules.
• Soft-stop needs-human-review, handoff succeeds: worker exits normally, handoff transition performed, claim released.
• Soft-stop needs-human-review, handoff fails: worker exits normally, handoff fails, claim released without retry.
• The consecutive handoff-absence ceiling is reached: the claim is released and the issue is held out of dispatch until a release gesture. See park issues stuck in a loop of empty runs for the ceiling and the three release gestures.

Two of these release only when the issue has no retry already queued: a successful handoff_state transition, and a normal exit on an issue that has since left the active states. A queued retry keeps the claim in both cases, so work queued while the session was running is not stranded.

Released → Unclaimed. A released issue can be re-dispatched on a future poll tick if its tracker state returns to an active state. The orchestrator does not remember previous releases: each poll tick evaluates eligibility from scratch.

Run attempt phases

Each worker attempt progresses through a linear sequence of phases. Terminal phases end the attempt and produce a WorkerResult delivered to the orchestrator.

flowchart TD
    DT[DispatchTransition] --> DC[DispatchComment]
    DC --> PW[PreparingWorkspace]
    PW --> BP[BuildingPrompt]
    BP --> LA[LaunchingAgent]
    LA --> IS[InitializingSession]
    IS --> ST[StreamingTurn]
    ST --> FN[Finishing]
    ST --> SR[SelfReviewing]
    SR --> FN

    FN --> ST
    FN --> OK([Succeeded])

    ST --> TO([TimedOut])
    SR --> TO
    ST --> SL([Stalled])
    ST --> CR([Canceled])

    classDef phase fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
    classDef active fill:#bfdbfe,stroke:#2563eb,color:#1e3a5f,stroke-width:2px
    classDef success fill:#d1fae5,stroke:#059669,color:#064e3b,stroke-width:2px
    classDef failure fill:#fee2e2,stroke:#dc2626,color:#7f1d1d

    class DT,DC,PW,BP,LA,IS,SR,FN phase
    class ST active
    class OK success
    class TO,SL,CR failure

Any phase from PreparingWorkspace through StreamingTurn can also transition to Failed on error; SelfReviewing can also transition to TimedOut, but only when a review or fix turn exceeds agent.turn_timeout_ms.

Multi-turn behavior

A single worker attempt can execute multiple agent turns. After each turn:

1. The worker checks the tracker for the issue’s current state.
2. If the state is still active and the turn count has not reached agent.max_turns, the worker loops back to StreamingTurn.
3. The first turn uses the full rendered prompt. Continuation turns send only continuation guidance to the existing agent thread.

Tracker states the orchestrator writes

The orchestrator writes tracker state at exactly three points in an issue’s life, each one a single named state drawn from configuration.

There are no other orchestrator-initiated tracker writes. What the orchestrator does besides these three carries no state semantics: the dispatch comment, the completion and failure comments, the auto-merge success comment, and a reaction’s escalation label or comment are not transitions. The governing boundary is not between reading and writing, it is between a write that reports an event the orchestrator observed and a write that expresses a judgment about the work; the orchestrator makes only the first kind, so a case that turns on judgment, such as choosing between a completion state and an abandonment state for a pull request closed unmerged, is left to you or to the coding agent.

The coding agent has a path of its own, separate from these three: the tracker_api tool performs a transition_issue the agent asked for, within the configured project scope.

Each write stays off until its field is configured. The third is the newest and needs reactions.merge_completion.provider on top of its target state; a deployment that does not configure it sees no terminal write from the orchestrator at all.

The handoff write carries one extra guard, because it is the write most likely to race a person. If you close or cancel an issue while its final turn is still finishing, the handoff write would otherwise overwrite your decision with handoff_state. So the exit path tests the issue against terminal_states using the freshest observation it has, preferring one made by reconciliation, then one made by the worker’s own per-turn refresh, then the state recorded at dispatch. A terminal observation suppresses the write, releases the claim, and cancels any pending retry. Because that observation can itself go stale while the worker tears down, Sortie performs one more state read immediately before the write and applies the same test. If that read fails, the write proceeds: an unreachable tracker is not evidence that the issue is closed. The read is skipped entirely when terminal_states is empty, since with no terminal state configured no value could classify as one and the call would cost a tracker request without ever suppressing anything. Only a terminal state suppresses. Any other state, including handoff_state itself when the agent already applied it through the tracker_api tool, leaves the write and everything downstream of it unchanged.

Handoff evidence

The handoff write is subject to one further condition beyond the four in the table above: the run’s handoff-evidence verdict, governed by tracker.handoff_evidence (default observed). Sortie inspects the workspace the run used and returns one of three verdicts: work was observed, absence of work was observed, or evidence was not determinable. Work observed never withholds the write. Absence observed always withholds it, unless the policy is off. Not determinable withholds it only under strict.

The default withholds only on a positively observed absence and abstains everywhere it cannot measure the workspace, the case a workspace that is not a Git work tree produces. A deployment whose workspaces are never version-controlled trees sees no behavioral change under the default and configures nothing. strict has no partial form: in such a deployment it withholds every transition and stops the pipeline, which is the operator’s own choice to make.

One legitimate configuration is misread by the default. A primary dispatch whose entire product is a write to the tracker presents a measurable workspace and no movement in it, so it reads as an absence. A write made through the tracker_api tool goes straight to the tracker, not to the workspace, so it is invisible to the inspection above and cannot rescue the case. That is the case off exists for.

The verdict describes what survived the run, not whether the agent acted: it can withhold a handoff write and it can never cause one, and it cannot see work that was produced and then reverted.

A verdict that withholds the handoff is checked against the tracker once before it takes effect, the same guard the handoff write itself carries. Immediately before recording anything, Sortie reads the issue’s state and tests it against terminal_states. A terminal result discards the verdict and routes the exit into the terminal disposition instead: the claim is released, any pending retry is cancelled, no failed run is recorded, no failure comment is posted, no retry is scheduled, and the consecutive-absence count does not advance. Any other state leaves the withheld outcome exactly as it was, and so does a read that fails, because an unreachable tracker is not evidence that the issue is closed. Like the write path’s read, this one is skipped entirely when terminal_states is empty, since no value could then classify as terminal. It is what keeps Sortie from reporting a failure and promising a retry on an issue that finished during the run (through the agent’s own tracker_api tool, through an after_run hook, or through a person moving it).

A withheld handoff that survives that check records the run as failed, naming the verdict as the reason, even though the agent process exited normally.

This bears on what a recorded run status of succeeded asserts on the handoff path. It means the worker exited without error and the evidence policy did not withhold the transition, or withheld it and the read above then found the issue terminal. It does not assert that work was positively observed: an undeterminable verdict under observed, every normal exit under off, and a withheld verdict discarded by that read all record succeeded. So does a no-change declaration that stood, which asserts a claim the agent made and self-review checked where enabled, not a positive workspace observation. Rows written before the evidence policy took effect keep the older exit-kind-only meaning and are not rewritten, so a success rate computed across the whole history spans three definitions of succeeded rather than one.

Declaring that nothing needed changing

A run can also state the verdict directly instead of leaving it to the workspace inspection above. Writing no-change-needed to .sortie/status declares that the requested outcome already held and the agent changed nothing. The declaration is admitted to the self-review phase on the same terms as needs-human-review. If that phase does not confirm it (anything other than exactly one iteration ending on a pass verdict, with no failing verification result), the declaration is retracted and the run falls back to the ordinary evidence-based verdict above, as if it had made no declaration. On a deployment with self-review disabled, no such check runs and the declaration stands unverified.

A declaration that stands always yields work observed, ahead of and bypassing the workspace inspection above entirely: it cannot be withheld and cannot be undeterminable. Under observed and strict, it resets the consecutive-absence count and releases a park held for consecutive absences. Under off, no verdict is computed and neither the reset nor the park release happens; resolving the transition target is the declaration’s only effect there. In every case, including off, the target is tracker.no_change_state where that field is configured, falling back to tracker.handoff_state otherwise; see the tracker.no_change_state field. Where no handoff path applies (the dispatch does not drive issue state, or tracker.handoff_state is unset), the declaration changes no issue state.

A run that produces nothing and declares nothing keeps the ordinary absence outcome above in full: handoff withheld, failure recorded, consecutive-absence count advanced. An undeterminable run that declares nothing keeps its policy-dependent outcome: proceeds under observed, withheld under strict. A terminal state observed at exit is not a declaration and is tested first, so a declaration on an already-terminal issue changes nothing.

A continuation turn dispatched by a reaction runs as an ordinary agent session and so performs the same in-progress and handoff writes, while a session dispatched by a label command performs neither.

Transition triggers

These events drive state transitions. Each is handled by the orchestrator’s single-writer event loop, which serves exactly one at a time.

Candidate eligibility

An issue is eligible for dispatch when all conditions are true:

Issues are sorted for dispatch: priority ascending (nil last), created_at oldest first, identifier lexicographic tiebreaker.

Blocker resolution

Jira and Linear return each issue’s blockers together with the candidate list, so nothing extra is read. GitHub and Gitea do not: a candidate from either tracker is held until a separate per-issue read resolves its blocker list, and that read is bounded to four per poll, shared across every candidate that needs one. GitHub’s candidate payload can prove an issue has zero dependencies without spending a read; Gitea’s cannot, so every Gitea candidate needing resolution costs one. GitLab declares that it has no blocking relation to read at all, so its issues carry an authoritative empty list from the candidate fetch and are never held for this reason. See the GitHub and Gitea adapter references for the read cost and how a failed read is handled.

A held candidate is not silent: it logs one record and increments the sortie_candidate_holds_total counter with a reason label, one of:

sortie --dry-run reports the same reason per candidate as skip_reason (see the CLI reference), and the Prometheus metrics reference documents the counter in full.

Backoff formula

Sortie uses two retry delay strategies depending on the exit type.

Continuation retry (normal worker exit, issue still active):

Error retry (worker failure, stall timeout):

Default max_retry_backoff_ms: 300 000 (5 minutes). Configurable via agent.max_retry_backoff_ms.

When a retry fires but no concurrency slot is available, the entry is rescheduled at the next attempt number (one backoff step longer, not a repeat of the same delay) with error no available orchestrator slots. A failed tracker read for the issue reschedules the same way.

Reconciliation

Reconciliation runs at the start of every poll tick, before dispatch, as one fixed sequence.

Part A: Overdue retry re-arm. A retry timer event can be dropped when the retry timer channel is full. An entry whose due_at lags the current tick by more than 60 seconds is re-armed with a zero delay, so an undeliverable entry cannot hold the retry slot for the life of the process.

Part B: Stall detection. For each running issue, compute elapsed time since the last agent event (or started_at if no event has arrived). If elapsed exceeds agent.stall_timeout_ms, the worker is killed and an exponential backoff retry is scheduled. Disabled when stall_timeout_ms is zero or negative.

Part C: Tracker state refresh. Fetch current tracker states for all running issue IDs, and for every issue carrying a pending reaction.

Part D: Reaction passes. The eight reaction kinds each get one pass, in this order: CI failure, review comments, bot review, merge conflicts, auto-merge, review label command, fix label command, merge completion. The order is load-bearing in two places: merge-conflict detection runs before auto-merge so a fresh conflict is acted on before auto-merge re-confirms its deferral, and merge completion runs last so a merge performed earlier in the same tick is observed on the same pass. See the reactions reference for what each pass does.

Periodic workspace sweep. Separately from the per-tick reconciliation above, a sweep runs once every 60 poll ticks and applies two grounds in one pass. The terminal check runs first: it asks the tracker for the state of every workspace key on disk that does not belong to in-flight work, and removes those reported terminal. Whatever it leaves is then evaluated against workspace.retention_days, an opt-in age bound that is off by default and needs no answer from the tracker, so it still removes on a pass where the tracker read failed.

Recovery at startup

When Sortie starts (or restarts after a crash), it reconstructs orchestration state from SQLite and the tracker.

1. Open SQLite database and apply schema migrations.
2. Load persisted retry entries. Reconstruct retry timers from stored due_at timestamps. Each rehydrated entry marks its issue claimed, so the first poll tick cannot dispatch it a second time.
3. Load the cumulative token and runtime totals, and the park records that hold issues out of dispatch. A read failure for either is logged as a warning and startup continues with none.
4. Enumerate workspace directories on disk and map directory names to issue identifiers.
5. Query the tracker for the states of those identifiers and remove the workspace directories of issues reported terminal. Only keys whose state is both known and terminal are removed, so a workspace whose issue is missing from the response or sits in a non-active, non-terminal state survives the pass. No age-based removal runs at startup.
6. Rebuild the pending reaction set from recent run history, so a watch that was in flight when the process stopped is not lost. Runs whose recorded activity is older than the recovery lookback are skipped. A failure here is logged as a warning and startup continues.
7. Begin the normal poll loop. The first tick fires immediately, and it is that tick, not a separate recovery step, that reads the tracker’s active issues and reconciles them with the restored state.

If the workspace listing or the terminal-state query fails at startup, Sortie logs a warning, cleans nothing on that pass, and continues. For an issue with no running worker, terminal cleanup then waits for the periodic sweep, which is also where the opt-in age bound in workspace.retention_days applies.