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, and its error becomes no available orchestrator slots. A fire that a retry now request brought forward is the exception: the entry keeps its attempt number and its earlier due time.

The worker runs the agent kind and template recorded on the entry, unless the configuration in force no longer reaches that kind or no longer holds that template; then the current dispatch rules route the issue again and the worker starts a new session instead of resuming the earlier one. An entry whose agent kind has no adapter is rescheduled with backoff and keeps its claim.

While an instance spend ceiling holds, the fire dispatches nothing and the entry is re-armed one polling.interval_ms ahead, unchanged: it keeps its attempt number, its error, and its stored row, and the wait adds no backoff step. An entry that then finds no slot or no SSH host also keeps its attempt number, where other entries advance to the next attempt.

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

• Reconciliation detects the tracker state is terminal or no longer in active_states. On a label-modelled tracker, an issue that reads no state label counts only at the second consecutive reading.
• 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 when its cancellation is what ends the running session.
• The max_cost_usd money budget is reached, at the same two points as the token budget.
• 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.
• A stage hop is made: the claim is released with no handoff transition, and the issue stays in its active state for the next stage.

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. A stage hop does the opposite: it cancels the queued retry and the issue’s pending reactions along with the claim.

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. The one exception is a stage hop record, which holds the issue until a read shows the label the hop added (see candidate eligibility).

Run attempt phases

Each worker attempt progresses through a linear sequence of phases. Terminal phases end the attempt and report the outcome 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 writes the orchestrator makes

A write belongs in the table below when it decides where the issue goes next: it moves the issue to a single named state drawn from configuration, or, for a stage label, selects the dispatch rule that runs on the issue next. A stage label is a label, not a tracker state, and writing it leaves the issue’s state unchanged.

Any other write the orchestrator makes decides nothing about where the issue goes: 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.

The stage-label write is of the first kind as well: it follows a successful exit the orchestrator observed, and the stage it selects is the one you named in next. 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 writes: 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, and the stage-label write until a rule carries next. The terminal write 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 last recorded for the run. 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. A stage hop is decided only after this read, so a terminal result suppresses the hop as well.

Handoff evidence

The handoff write is subject to one further condition beyond those 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: a workspace that is not a Git work tree, and a workspace inspection that itself fails, which includes one still waiting on output a descendant process kept open past a bounded wait.

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.

On a rule that carries next, that target applies only when no stage hop is made. 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, handoff, and stage-label writes, while a session dispatched by a label command performs none of them.

Stage hop

A rule that carries next makes a stage hop in place of the handoff write (see dispatch configuration for stage, next, and dispatch.max_consecutive_hops). A hop is due on exactly the exits that would otherwise take the handoff write, after the terminal tests and the evidence verdict above have let the exit through.

A needs-human-review soft stop and a no-change-needed declaration that stood both qualify. A blocked soft stop, a failed, timed-out, stalled, or cancelled run, a terminal exit, a withheld verdict, a label-command session, and an issue no longer in an active state never hop.

A hop that is made:

1. Adds the stage label of the rule next names.
2. Records the hop in the database and increments the issue’s consecutive hop count.
3. Cancels the issue’s queued retry, including its persisted entry, and its pending reactions, and releases the claim. The run that hopped seeds no new reaction.
4. Removes every other configured stage label the issue carried when the run was dispatched. A stage label added to the issue during the run is not removed.

The hop writes no tracker state. The issue stays in its active state, tracker.handoff_state and tracker.no_change_state are not written, and sortie_handoff_transitions_total is not incremented. The next stage’s dispatch performs the in-progress write like any dispatch. From the hop until a run of the issue is dispatched, the status API lists the issue under between_stages; the stored hop record keeps that listing across a restart.

The run that reaches a hop decision records the target rule and one of these results on its run history row:

A hop that is not made leaves the exit on the handoff write, with that write’s own outcomes: a failed write schedules a continuation retry, or releases the claim after a soft stop. When the configuration in force at the exit no longer holds the run’s rule or no longer gives it a next, or the rule next names no longer exists or no longer carries stage, no hop is due: the exit takes the handoff write, records no result, and publishes no stage event.

The consecutive hop count is kept per issue and survives a restart. It resets when:

• an exit writes tracker.handoff_state or tracker.no_change_state, or finds the issue terminal or no longer in an active state;
• reconciliation, a retry timer’s read, or the stage-hop hold’s direct read finds the issue terminal or outside the active states;
• the issue is parked, or its park is released.

Each reset logs stage hop count reset with a trigger of handoff, terminal, not_active, parked, or unparked. Moving a stage label while the issue stays active does not reset the count, and neither does a failed handoff write, a withheld verdict, or a reload.

Transition triggers

These events drive state transitions. Each is processed in order, one at a time.

Candidate eligibility

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

Issues are sorted for dispatch: priority ascending (issues with no priority sort 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 increments the sortie_candidate_holds_total counter with a reason label, and a candidate held by a blocker also logs one record. The reason is one of:

sortie --dry-run reports the blocker reasons (blocked_by, blockers_unresolved, blockers_not_read, and blockers_incomplete) per candidate as skip_reason (see the CLI reference) and does not evaluate the spend ceiling, and the Prometheus metrics reference documents the counter in full.

The dashboard’s Not dispatched block and the held list of GET /api/v1/state show each held candidate with its reason and what releases it. They also cover holds the counter does not count: a full agent slot limit, no free SSH host, and an unconfirmed stage hop.

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 if too many arrive at once. 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 and labels for all running issue IDs, for every issue carrying a pending reaction, and for every issue holding a stage hop record, running or not.

An issue with no worker whose pending reaction holds a standing escalation is also acted on when the tracker reports it outside tracker.handoff_state in a non-terminal state while Sortie does not run, retry, claim, or park it. A direct read of the issue confirms the state, and then every standing escalation of the issue ends and its entries and attempt counters drop. A reading with no state ends them at the second consecutive reading. The same read runs just before the dispatch of a poll candidate that holds a standing escalation. A terminal state releases the issue’s escalation records with its pending reactions.

A terminal state, or one that is neither active nor terminal, also resets the hop count of an issue holding a stage hop record. A reading with no state resets it only at the second consecutive such reading. A queued retry whose per-issue read shows no state is likewise rescheduled at the first reading and released at the second.

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, the park records that hold issues out of dispatch, and the stage hop records, which restore each issue’s hop count and whether its stage-hop hold has been released. A read failure for any of these 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. Restore the stored escalations onto the rebuilt entries, and rebuild an entry from its stored escalation for an issue that step 6 did not reach. A stored escalation whose reaction kind is not configured, or whose issue has no successful run, ends. A failure here is logged as an error and startup continues.
8. 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.