Workflow Configuration

WORKFLOW.md is a Markdown file with YAML front matter. Front matter between --- delimiters defines runtime settings. The body after the closing --- is the default prompt template, rendered per issue with Go text/template. When the front matter defines dispatch rules, a matching rule can select a different per-rule template file in place of the body.

Complete annotated example

---
# --- Tracker ----------------------------------------------------------
tracker:
  kind: jira                          # Adapter: "jira", "github", "linear", "gitea", "gitlab", or "file"
  endpoint: $SORTIE_JIRA_ENDPOINT     # Jira base URL ($VAR expanded)
  api_key: $SORTIE_JIRA_API_KEY       # API token ($VAR expanded anywhere)
  project: PLATFORM                   # Jira project key
  api_version: "3"                    # Jira REST API version: "3" Cloud, "2" Server/DC
  query_filter: "labels = 'agent-ready'"  # JQL fragment appended to queries
  active_states:                      # Issues in these states get dispatched
    - To Do
    - In Progress
  terminal_states:                    # Issues in these states trigger cleanup
    - Done
    - Won't Do
  handoff_state: Human Review         # State set after successful agent run
  handoff_evidence: observed          # observed (default) | strict | off
  in_progress_state: In Progress       # State set when agent picks up the issue
  comments:
    on_dispatch: true                  # Post comment when agent starts
    on_completion: true                # Post comment when agent finishes
    on_failure: true                   # Post comment when agent fails

# --- Polling ----------------------------------------------------------
polling:
  interval_ms: 60000                  # Poll every 60 seconds

# --- Workspace --------------------------------------------------------
workspace:
  root: ~/workspace/sortie            # Base dir for per-issue workspaces

# --- Hooks ------------------------------------------------------------
hooks:
  after_create: |                     # Runs once, in the freshly created (empty) workspace
    git clone --depth 1 git@github.com:myorg/myrepo.git .
    go mod download
  before_run: |                       # Runs before each agent attempt
    git fetch origin main
    git checkout -B "sortie/${SORTIE_ISSUE_IDENTIFIER}" origin/main
  after_run: |                        # Runs after each agent attempt
    make fmt 2>/dev/null || true
    git add -A
    git diff --cached --quiet || \
      git commit -m "sortie(${SORTIE_ISSUE_IDENTIFIER}): automated changes"
  before_remove: |                    # Runs before workspace deletion
    git push origin --delete "sortie/${SORTIE_ISSUE_IDENTIFIER}" 2>/dev/null || true
  timeout_ms: 120000                  # 2-minute timeout for all hooks

# --- Agent ------------------------------------------------------------
agent:
  kind: claude-code                   # Agent adapter
  command: claude                     # CLI binary to launch
  max_turns: 5                        # Orchestrator turn-loop limit
  max_sessions: 3                     # Max completed sessions per issue
  max_tokens: 1500000                 # Cumulative per-issue token ceiling (0 = unlimited)
  max_concurrent_agents: 4            # Global concurrency cap
  turn_timeout_ms: 1800000            # 30 min per turn
  read_timeout_ms: 10000              # 10 s startup timeout
  stall_timeout_ms: 300000            # 5 min inactivity detection
  stop_grace_ms: 5000                 # 5 s to exit before a force kill
  max_retry_backoff_ms: 120000        # 2 min max retry delay
  max_concurrent_agents_by_state:
    in progress: 3                    # Per-state concurrency cap
    to do: 1

# --- Dispatch (rule-based routing; optional) ----------------------
dispatch:
  rules:                                # First match wins, in order
    - name: bug-fix                     # ^[a-z][a-z0-9_-]*$; logs/metric
      match:
        labels: ["bug", "bug/*"]        # glob vs lowercased labels
      agent: claude-code                # overrides agent.kind
      template: ./prompts/bug.md        # path relative to WORKFLOW.md
    - name: urgent
      match:
        priority: { lte: 2 }            # op: eq/in/lt/lte/gt/gte
      template: ./prompts/urgent.md
  default:                              # Applied when no rule matches
    template: ./prompts/default.md      # agent omitted -> agent.kind

# --- CI Feedback --------------------------------------------------
ci_feedback:
  kind: github                        # CI provider; absent = disabled
  max_retries: 2                      # CI-fix attempts before escalation
  max_log_lines: 50                   # Log lines from failing check; 0 = off
  escalation: label                   # "label" or "comment"
  escalation_label: needs-human       # Label for escalation

# --- Reactions (post-PR feedback loops) ---------------------------
reactions:
  review_comments:
    provider: github                      # SCM adapter for review polling
    escalation: label                     # "label" or "comment"
    escalation_label: needs-human         # label on escalation
    poll_interval_ms: 120000              # 2 min poll interval
    debounce_ms: 60000                    # 60s debounce window
    max_continuation_turns: 3             # hard cap per PR
  label_commands:
    provider: github                      # SCM adapter for PR label commands
    review_label: "sortie:review"         # label that triggers a read-only review
    fix_label: "sortie:fix"               # label that triggers pushed fixes
    poll_interval_ms: 60000               # 60s poll interval; floor 30000

# --- Self-Review --------------------------------------------------
self_review:
  enabled: true                           # default false; opt-in
  max_iterations: 3                        # review iteration cap
  verification_commands:                   # required when enabled
    - "go test ./..."
    - "go vet ./..."
  verification_timeout_ms: 120000          # per-command timeout
  max_diff_bytes: 102400                   # diff truncation limit
  reviewer: "same"                         # only supported value is "same"

# --- Notifications (notify_operator backends; optional) ------------
notifications:
  - kind: slack                       # Notifier backend
    webhook_url: $SORTIE_SLACK_WEBHOOK_URL  # SORTIE_-prefixed reference (required)
    max_per_session: 20               # Cap per sortie mcp-server process; 0 selects the default (20)
  - kind: webhook
    url: $SORTIE_OPS_WEBHOOK_URL      # Generic JSON POST endpoint

# --- Claude Code adapter (pass-through) ------------------------------
claude-code:
  permission_mode: bypassPermissions  # Auto-approve tool calls
  model: <model-id>
  max_turns: 50                       # CLI --max-turns (not agent.max_turns)
  max_budget_usd: 5                   # Per-invocation cost cap (x agent.max_turns per session)

# --- Server -----------------------------------------------------------
server:
  port: 9090                          # HTTP observability server (default: 7678, 0 to disable)
  host: "0.0.0.0"                     # Bind address (default: 127.0.0.1)

# --- Logging ----------------------------------------------------------
logging:
  level: info                         # debug | info | warn | error
  format: json                        # text | json (default: text)

# --- Token Rates (cost estimation) -----------------------------------
token_rates:
  claude-code:                        # Agent adapter kind string
    input_per_mtok: 3.00              # USD per million input tokens
    output_per_mtok: 15.00            # USD per million output tokens
    cache_read_per_mtok: 0.30         # USD per million cache-read tokens

# --- Database ---------------------------------------------------------
db_path: .sortie.db                   # SQLite file (relative to WORKFLOW.md)
---

You are a senior engineer working on {{ .issue.identifier }}.

## Task

**{{ .issue.identifier }}**: {{ .issue.title }}

{{ if .issue.description }}
{{ .issue.description }}
{{ end }}

{{ if .run.is_continuation }}
Resuming turn {{ .run.turn_number }}/{{ .run.max_turns }}. Review workspace state and continue.
{{ end }}

{{ if .attempt }}
Retry attempt {{ .attempt }}. Check previous failure before proceeding.
{{ end }}

tracker

Issue tracker connection and query settings.

Environment variable expansion

api_key applies full environment expansion: $VAR and ${VAR} references are resolved at any position in the string.

endpoint, project, query_filter, handoff_state, no_change_state, in_progress_state, and api_version use targeted resolution: the value is expanded only when the entire trimmed string starts with $. Literal URIs and project keys that contain $ characters elsewhere are returned unchanged.

See the environment variables reference for expansion mechanics.

Constraints

At least one of active_states or terminal_states must be non-empty. When both are empty, Sortie refuses to start. An empty active_states with non-empty terminal_states is valid but means no issues are dispatched.

handoff_state, when set, must not appear in active_states (causes immediate re-dispatch loop) or terminal_states (handoff is not a terminal outcome). Jira handoff requires write permissions on the API token: write:jira-work (classic) or write:issue:jira (granular).

no_change_state, when set, requires handoff_state to be non-empty: a declared run with no handoff path performs no transition. Compared case-insensitively, its value must equal handoff_state or name a member of terminal_states as written, with no fallback to an adapter’s default terminal list; any other value is a configuration error. Unlike its sibling target-state fields, naming a terminal state is exactly the case no_change_state exists for (a handoff with no pull request and no diff put in front of a reviewer), so a terminal no_change_state is never the default and stays an explicit opt-in.

in_progress_state, when set, must appear in active_states (otherwise reconciliation would immediately cancel the worker after the transition). It must not appear in terminal_states or collide with handoff_state. If the issue is already in the target state at dispatch time, the transition call is skipped (debug log only). Other transition failures at runtime are non-fatal: the worker logs a warning and continues to workspace preparation. Requires the same write permissions as handoff_state.

handoff_evidence, when set, must be one of observed, strict, or off. The check is a closed-set comparison that needs no network access, so an invalid value is rejected offline at startup, on dynamic reload, and by sortie validate.

Tracker comments

The comments sub-object controls whether Sortie posts plain-text comments on tracker issues at session lifecycle points. Each flag is independent. All default to false.

Comment failures are non-fatal. A failed comment logs WARN and never blocks dispatch, completion, retry, or handoff.

No comment is posted on worker cancellation (stall timeout, reconciliation, shutdown).

The comments value must be a map when present. Non-boolean values for the flags produce a configuration error at startup. The flags do not support $VAR expansion.

Example: Jira

tracker:
  kind: jira
  endpoint: https://mycompany.atlassian.net
  api_key: $JIRA_TOKEN
  project: BILLING
  query_filter: "component = 'api' AND labels = 'agent-ready'"
  active_states: [To Do, In Progress]
  terminal_states: [Done, Won't Do]
  handoff_state: Human Review
  in_progress_state: In Progress
  comments:
    on_dispatch: true
    on_completion: true
    on_failure: true

Example: file-based tracker

tracker:
  kind: file
  active_states: [To Do, In Progress]
  terminal_states: [Done]

file:
  path: /path/to/issues.json

Example: GitHub Issues tracker

tracker:
  kind: github
  api_key: $SORTIE_GITHUB_TOKEN
  project: myorg/myrepo
  query_filter: "label:agent-ready"
  active_states: [backlog, in-progress]
  terminal_states: [done, wontfix]
  handoff_state: review
  in_progress_state: in-progress
  comments:
    on_dispatch: true
    on_completion: true
    on_failure: true

GitHub state names are issue label names. Create the active_states labels before Sortie starts, since an issue can only carry a label that already exists; labels Sortie applies itself, such as handoff_state, are created on demand in default gray. State values are compared case-insensitively and stored lowercased. See the GitHub adapter reference for state derivation rules.

Example: Linear

tracker:
  kind: linear
  api_key: $SORTIE_LINEAR_API_KEY
  project: ENG
  query_filter: '{ "labels": { "name": { "eq": "agent-ready" } } }'
  active_states: [Backlog, Todo, In Progress]
  terminal_states: [Done, Canceled, Duplicate]
  handoff_state: In Review

project is the Linear team key (the prefix in identifiers such as ENG-123), not a Linear project. api_key is a Linear personal API key, sent verbatim in the Authorization header with no Bearer prefix. Linear state names match workflow states by display name, compared case-insensitively and verified against the team at startup. When active_states or terminal_states is omitted, the adapter applies the stock defaults: active ["Backlog", "Todo", "In Progress"], terminal ["Done", "Canceled", "Duplicate"]. Unlike Jira’s appended JQL, the Linear query_filter is an IssueFilter JSON object merged into the query: it must be a JSON object, and it must not contain a top-level team or state key, which the adapter reserves for its own team and state constraints. See the Linear adapter reference for field mapping, the state model, and the full IssueFilter surface.

Example: Gitea

tracker:
  kind: gitea
  endpoint: https://gitea.example.com
  api_key: $SORTIE_GITEA_TOKEN
  project: sortie-ai/sortie
  query_filter: "assigned_by=hermes-bot"
  active_states: [backlog, in-progress]
  terminal_states: [done, wontfix]
  handoff_state: review

endpoint is required for Gitea: the instance is self-hosted, so there is no default host. The adapter trims a trailing slash and appends /api/v1, and tolerates a value already ending in /api/v1. api_key is a Gitea access token, sent verbatim as Authorization: token <key> (the canonical Gitea scheme, not a Bearer prefix), so surrounding whitespace fails authentication. project is the repository in owner/repo form.

Gitea state names are repository label names, compared case-insensitively and stored lowercased. A configured label absent from the repository is created on demand the first time an issue transitions into it, so labels need not exist beforehand. When active_states or terminal_states is omitted, the adapter carries internal fallback labels (active ["backlog", "in-progress", "review"], terminal ["done", "wontfix"]) that derive an issue’s state from its labels; they do not drive dispatch, which the orchestrator gates on the workflow’s active_states and terminal_states. handoff_state and in_progress_state name repository labels too, and a transition swaps the current state label for the target, closing the issue on a terminal target and reopening it on an active one. Unlike Jira’s appended JQL, the Gitea query_filter is a URL query fragment merged into the repository issue-list query: the adapter reserves the state, type, page, and limit keys (a fragment naming any of them fails when the adapter is built), warns on an unrecognized key, and warns when a labels value does not resolve to a repository label, because Gitea’s server-side labels filter is AND-across-names, case-sensitive, and drops entirely on an unresolvable name. See the Gitea adapter reference for the state model, field mapping, and the full query_filter surface.

Example: GitLab

tracker:
  kind: gitlab
  # endpoint omitted: defaults to https://gitlab.com. Set it for self-managed GitLab.
  api_key: $SORTIE_GITLAB_TOKEN
  project: group/subgroup/project
  query_filter: "assignee_username=hermes-bot&not[labels]=blocked"
  active_states: [backlog, in-progress]
  terminal_states: [done, wontfix]
  handoff_state: review

endpoint is optional for GitLab, which ships both as SaaS and as a self-managed install: it defaults to https://gitlab.com, so a GitLab.com workflow omits it and a self-managed workflow sets the instance base URL. The adapter trims a trailing slash and appends /api/v4, and tolerates a value already ending in /api/v4, though sortie validate warns about the redundant suffix. api_key is a GitLab access token (personal, project, or group) with the api scope, sent verbatim in the PRIVATE-TOKEN header (GitLab’s own scheme, neither Authorization: Bearer nor Authorization: token), so surrounding whitespace fails authentication. project is the project’s full namespace path or its numeric project ID, quoted so YAML keeps a numeric ID a string. GitLab nests subgroups to any depth, so group/subgroup/project is as valid as group/project and the adapter enforces no one-slash rule, unlike the GitHub and Gitea owner/repo grammar. Write the path unencoded: the adapter percent-encodes it once for the API path.

GitLab state names are project labels, compared case-insensitively and stored lowercased; a group label the project inherits counts as a project label. A configured label absent from the project is created by GitLab itself on the write that names it, so labels need not exist beforehand. Because GitLab label names are case-sensitive, that same behavior would turn a configured review into a second label next to an existing Review; to prevent the duplicate, the adapter reads the project label catalog at startup and rewrites every configured state label to the casing the project already stores. When active_states or terminal_states is omitted, the adapter carries internal fallback labels (active ["backlog", "in-progress", "review"], terminal ["done", "wontfix"]) that derive an issue’s state from its labels; they do not drive dispatch, which the orchestrator gates on the workflow’s active_states and terminal_states. handoff_state names a project label too, and in_progress_state is an orchestrator-level field the GitLab adapter itself does not read; both reach GitLab through the same transition, a single request that swaps the current state label for the target and reconciles the native state, closing the issue on a terminal target and reopening it on an active one. A handoff-only target does neither.

Unlike Jira’s appended JQL and Linear’s IssueFilter JSON object, the GitLab query_filter is a URL query fragment merged into the project issue-list query, validated against a closed allowlist when the adapter is built. The adapter rejects the eight keys it owns (state, issue_type, order_by, sort, page, per_page, pagination, with_labels_details) and rejects any key outside the eighteen the issue-list route honors. That is stricter than the Gitea adapter, which warns and forwards an unrecognized key: GitLab silently ignores a parameter it does not recognize and returns an unfiltered result set with HTTP 200, so a typo such as assignee= for assignee_username= would widen the candidate set with no visible signal. Negation uses GitLab’s not[...] hash, accepted for the subset GitLab honors there. The adapter warns, without refusing to build, when a labels value names a label the project does not hold, because GitLab’s server-side labels filter is AND-across-names and case-sensitive and returns an empty result on an unmatched name. sortie validate reports the same verdict offline. See the GitLab adapter reference for the state model, field mapping, and the full query_filter allowlist.

polling

Poll loop timing.

Accepts plain integers or quoted string integers (e.g., "30000"). Reloads dynamically; changes take effect on the next tick without restart.

polling:
  interval_ms: 60000

workspace

Base directory for per-issue workspaces, and the optional age bound on how long they survive.

~ expands to the user’s home directory. All $VAR and ${VAR} references are expanded at any position. Issue identifiers are sanitized to [A-Za-z0-9._-] for subdirectory names; other characters become _.

Age-based retention

retention_days bounds how long a workspace survives when its issue never reaches a terminal state. It is opt-in and off by default: a deployment that does not set the field behaves exactly as it did before, in every observable respect, with no run-history read and no age comparison on any pass. Terminal-state cleanup stays the primary mechanism and is always on. The age bound is a backstop for what the terminal gate cannot reach: an issue parked in the handoff state with no automation to advance it, an issue moved to a state the configuration does not name, an issue abandoned in an active state after a permanent failure, and an issue deleted from the tracker, which reports no state at all.

Accepted values are 0, which disables the bound, and any integer of 30 or greater, which enables it. A value between 1 and 29 is rejected outright, neither clamped nor rounded up:

config: workspace.retention_days: must be 0 to disable or at least 30 days

A negative value is rejected as well:

config: workspace.retention_days: must not be negative

Both are configuration-shape checks that need no network access, so sortie validate reports them offline, at error severity, before a run starts.

The window is counted in days while every other duration in this file is counted in milliseconds. The departure is deliberate. The millisecond fields are poll intervals, timeouts, debounces, and backoff caps, all sub-hour timings where the unit is proportionate to the value. A retention window runs on the order of weeks, and thirty days written in milliseconds is 2592000000, a figure no operator can read back or check. Drop three digits from it and an intended thirty days becomes forty-three minutes. Days keep a misconfiguration visible on the line where it is written.

The floor of 30 is fixed by a second window rather than chosen for taste. Pending reaction recovery rebuilds runtime reaction entries after a restart by reading .sortie/scm.json out of the workspace directory, and it considers a candidate only when that workspace’s latest activity falls inside a thirty-day lookback. The retention window may not be set below the window reaction recovery honors, which makes one invariant true by construction: any workspace the bound may remove is one recovery would already have skipped as stale.

Age is measured from the later of two recorded timestamps: the most recent run completion recorded for that workspace’s identifier, and the pushed_at value in the workspace’s .sortie/scm.json. A workspace is removable when that anchor is older than the window. Directory modification time is not used, and was rejected deliberately: lifecycle hooks, agent processes, and background tooling inside the checkout all move it, so it reports filesystem activity rather than work. A workspace with neither timestamp is retained, never removed. Absence of a record is not evidence of age, and that case covers a run that never completed, a directory produced by an operator or a hook, and a directory Sortie did not create.

Two exclusions are absolute. A workspace whose issue holds an entry in the running map or the retry map is never removed, whatever its age and however large the directory. A workspace pinned by an unexpired pending reaction is excluded until that entry expires, a bound set by that reaction kind’s watch_window_ms (30 minutes by default, up to 24 hours by default for ci_failure); see the reactions reference for which reaction kinds pin a workspace and which do not. Everything else on disk is a candidate.

The bound removes directories and does nothing else. It performs no tracker write, no source-control write, and no change to reaction state, so a workspace removed by age leaves every reaction latch exactly as it found it. Removal runs through the same path as terminal cleanup, so workspace key sanitization, containment under root, and the before_remove hook all apply unchanged.

retention_days reloads dynamically. A change applies on the next sweep pass, with no restart.

The bound never removes a workspace whose latest activity is inside the window, so a deployment that processes many issues quickly still holds every workspace produced during the last window. Size the disk for that, not for the steady state.

workspace:
  root: ~/workspace/sortie
  retention_days: 30        # max age in days of latest recorded activity; 0 disables the bound

hooks

Shell scripts that run at workspace lifecycle points. On POSIX systems, each hook executes via sh -c (not bash). On Windows, hooks execute via cmd.exe /C. The working directory is always the per-issue workspace directory.

Failure behavior

Timeouts count as failures and follow the same semantics.

Hook process lifetime

When a hook’s shell exits, whatever its exit status, Sortie terminates every process still in its process group (its Job Object on Windows), resending the termination on a fixed poll interval until the group or job reports no member left or a 2-second bound elapses. A background command inside the script ends with the hook: on Linux and macOS &, nohup … &, and ( … & ); on Linux also systemd-run --scope; on Windows start /b, pg_ctl start, and pm2 start. A process meant to outlive the hook needs a supervisor outside that tree:

Prefer a supervisor that owns the service across runs, such as docker compose up -d on Linux and macOS, which recreates a service’s containers only when its configuration or image changed, or a service manager. A hook whose next step uses the service should wait until the service accepts connections, since these start commands can return before it does.

On Windows, a hook whose Job Object could not be created or assigned still runs, with the failure logged, and that teardown then reaches only the shell itself. When a hook that exits on its own leaves a process running that it did not start through one of the routes above, Sortie logs one INFO record, leftover processes terminated after the command exited, carrying hook and workspace; a termination that still cannot confirm the group or job empty once the 2-second bound elapses is logged as a warning instead.

For the practical walkthrough, see how to set up workspace hooks: start a service that outlives a hook.

Hook environment variables

Restricted environment

Hook subprocesses do not inherit the full parent process environment. They receive:

• A POSIX allowlist: PATH, HOME, SHELL, TMPDIR, USER, LOGNAME, TERM, LANG, LC_ALL, SSH_AUTH_SOCK.
• All parent environment variables prefixed with SORTIE_.
• The orchestrator-injected variables listed above.

All other parent variables are stripped. Secrets such as JIRA_API_TOKEN or AWS_ACCESS_KEY_ID are not available unless exposed under a SORTIE_ prefix in the parent environment.

hooks:
  after_create: |
    git clone --depth 1 git@github.com:myorg/myrepo.git .
    npm ci
  before_run: |
    git checkout -B "sortie/${SORTIE_ISSUE_IDENTIFIER}" origin/main
  after_run: ./hooks/post-run.sh
  timeout_ms: 120000

agent

Coding agent adapter, concurrency, timeouts, and retry behavior. These fields control the orchestrator’s scheduling decisions, not the agent process itself. Adapter-specific settings use separate pass-through blocks.

max_concurrent_agents, max_concurrent_agents_by_state, max_retry_backoff_ms, max_sessions, max_tokens, and max_consecutive_absences reload dynamically without restart; a reloaded max_tokens reaches the sessions already running from the next poll tick onward, and applies at the next retry evaluation. All other fields apply to future dispatches only, except where the per-field Dynamic reload table at the end of this document states a finer-grained answer.

Usage reporting by agent kind

Every agent kind Sortie ships declares when a session’s token figures reach the orchestrator and what those figures attribute to. The dashboard prints that declaration in the Usage reporting field of an expanded running session, and the JSON API carries it as usage_arrival and usage_attribution. The pair is resolved per session rather than fixed per kind: a kind’s own pass-through block and whether the session runs over SSH can put a different pair in force, and the Usage reporting column names every case where they do.

Four behaviors follow from a session’s declared arrival.

agent.max_tokens bounds the session in progress for a kind whose figures arrive at all, and bounds nothing for a kind that reports none: Sortie records token ceiling cannot bound this run at the dispatch that starts such a session, and agent.turn_timeout_ms is the bound that remains for it. See how to control agent costs for what the ceiling does when a session reaches it.

A session’s API request count is a count of requests only where figures arrive during each turn, the one arrival that emits a figure per model API request. The dashboard’s API Requests field and the API’s api_request_count carry a number for such a session while no turn has begun or once a figure has arrived. They carry no count for one whose first turn has begun with nothing counted, or for any other session.

token_rates prices a session from the figures it reports, so a kind reporting none has nothing to price and its estimated cost stays blank. sortie validate reports an inert ceiling as an agent.kind.no_usage_reporting warning and an unpriceable kind as an agent.kind.no_cost_estimate warning, each naming the kind, so neither has to be discovered from a budget that never fires or a blank column.

A none declaration is enforced rather than trusted. If a session’s runtime sends a usage figure anyway, Sortie discards it: the figure never reaches the dashboard, the JSON API, agent.max_tokens, or sortie stats, and Sortie logs one warning per run, naming the agent kind, the first time it happens.

agent:
  kind: claude-code
  command: claude
  max_turns: 5
  max_sessions: 3
  max_tokens: 1500000
  max_concurrent_agents: 4
  stall_timeout_ms: 300000
  max_concurrent_agents_by_state:
    in progress: 3
    to do: 1

Agents can read the remaining token budget mid-session through the cost_budget tool; see the agent extensions reference for the tool contract and how to control agent costs for budget strategy.

dispatch

Routing for the initial dispatch of each issue. Rules select an agent kind and prompt template from the issue’s tracker metadata, evaluated first-match-wins in declaration order. When the dispatch block is absent, every issue dispatches with the top-level agent.kind and the WORKFLOW.md body template. The block is additive and changes no default.

The block accepts two keys:

Each entry in rules accepts:

A session a rule routes to an agent kind other than the top-level agent.kind reads the matching adapter pass-through block and no other. With that block absent the session still dispatches, on the shared agent settings and the adapter’s own defaults for everything else; neither sortie validate nor startup preflight reports the absence.

Match predicates

The match block accepts five keys. A rule matches when every key present in the block matches (AND across keys); within a single key, a list matches when any element matches (OR within a key). Absent keys do not participate.

The priority predicate carries exactly one operator. Priority is an integer where lower values are more urgent.

Tracker support differs. GitHub supplies labels, issue_type, assignee, and identifier (the issue number) and carries no priority. Jira supplies all five, with identifier as the issue key (for example ACME-123).

Resolution and fallback

agent and template resolve independently. Each follows this chain until a value is found:

1. The matched rule’s agent or template.
2. dispatch.default.agent or dispatch.default.template.
3. The top-level agent.kind, and the WORKFLOW.md body template.

Resolution runs once, at the issue’s first dispatch. The resolved (agent, template) is frozen for the life of the claim; retries and reaction-driven continuations reuse it.

Template paths

Per-rule template paths resolve relative to the directory containing WORKFLOW.md. Per-rule template files are plain text/template bodies and carry no YAML front matter. They use the same variables and functions as the body template; see Prompt template. The following are rejected at load time:

• Absolute paths and ~-prefixed paths.
• Paths that resolve outside the WORKFLOW.md directory tree, including through symlinks or .. traversal.
• Files that begin with ---, since front matter is not permitted in per-rule templates.

Validation

sortie validate parses the dispatch block, resolves and parses every referenced template, and reports the first error before dispatch:

• dispatch.rules is not a YAML sequence.
• A rule name does not match ^[a-z][a-z0-9_-]*$.
• Two rules share a name.
• A catch-all rule (absent or empty match) precedes another rule, reported as unreachable_rules. A catch-all must be the last entry.
• A rule.agent or default.agent names an unregistered adapter kind.
• A match key is not one of labels, issue_type, priority, identifier, or assignee.
• A labels or identifier glob is malformed.
• A priority predicate carries no operator or more than one.
• A referenced template is missing, unreadable, contains front matter, or fails to parse.

A rule.agent or default.agent naming a registered kind that differs from agent.kind is checked separately, alongside every other agent block preflight validates: see dispatch.agent.missing_block.

Validation is single-pass: the first error short-circuits the run, so two unrelated dispatch errors surface across two runs.

Dynamic reload

The rule set reloads with WORKFLOW.md changes and applies to future claims only. An in-flight issue keeps the agent and template frozen at its first dispatch until its claim is released. Per-rule template files are read at WORKFLOW.md load and on every reload; a standalone edit to a per-rule template file applies on the next WORKFLOW.md change or the next dispatch, whichever comes first.

Minimal:

dispatch:
  rules:
    - name: bug-fix
      match:
        labels: ["bug"]
      template: ./prompts/bug.md
  default:
    template: ./prompts/default.md

For setup procedures, match-type recipes, and --dry-run verification, see how to configure dispatch rules.

ci_feedback

CI feedback configuration. When activated, Sortie detects CI failures on agent-created branches and dispatches continuation runs with failure context injected into the agent prompt. When retries are exhausted, Sortie escalates to a human via label or comment.

CI feedback follows the same activation pattern as other optional Sortie features. Presence of kind activates the feature; absence disables it. This is consistent with worker.ssh_hosts (absent = local mode). There is no ci_feedback.enabled boolean.

Repository coordinates (owner, repo name, API token, endpoint) are not part of the ci_feedback section. They live in the adapter pass-through block that matches the CI provider kind. When ci_feedback.kind: github, the CI adapter reads credentials from the github: top-level section in Extensions. When tracker.kind and ci_feedback.kind match (the common single-platform case), both adapters share the same credentials from the tracker config. See adapter pass-through configuration for the extension block pattern.

watch_window_ms is not a key of this block. A deployment configured through ci_feedback always gets its default; see the reactions.ci_failure field table for where it lives and what it does.

sortie validate checks ci_feedback sub-keys against the known schema. Unknown sub-keys produce an advisory warning. Adapter-specific keys nested inside ci_feedback: (e.g., ci_feedback.github.owner) are flagged as unknown because ci_feedback does not use adapter pass-through. Place adapter-specific config in a top-level extension block instead.

Escalation behavior

Both escalation actions release the claim on the issue and cancel any pending retry. The issue will not be re-dispatched until its tracker state changes.

Dynamic reload

max_retries, escalation, and escalation_label reload dynamically. Changes take effect on the next reconcile tick. kind and max_log_lines are read at startup and do not change at runtime because the CI provider is built once. Changing kind or max_log_lines requires a restart.

Minimal:

ci_feedback:
  kind: github

Full:

ci_feedback:
  kind: github            # activates CI feedback; absent = disabled
  max_retries: 2           # default 2; 0 = escalate immediately
  max_log_lines: 50        # default 50; 0 = disable log fetching
  escalation: label        # "label" or "comment"; default "label"
  escalation_label: needs-human  # default "needs-human"

For operational guidance on CI feedback setup, hook scripts that produce .sortie/scm.json, and prompt template examples with {{ .ci_failure }}, see how to configure CI feedback.

self_review

Self-review configuration. When enabled, Sortie runs an orchestrator-controlled review loop between the coding turn loop and worker exit. The orchestrator generates a workspace diff, runs verification commands, and feeds structured results to the agent for bounded iteration. Self-review is opt-in and adds zero overhead when disabled.

enabled: true with empty or absent verification_commands produces a configuration error. max_iterations outside [1, 10] produces a configuration error. reviewer values other than "same" produce a configuration error. All integer fields accept quoted string integers (e.g., "3") following the same coercion rules as other integer config fields.

Turn accounting

Each iteration runs one review turn. Non-final iterations that produce an “iterate” verdict also run a fix turn. max_iterations: N means up to 2N − 1 additional agent turns in the worst case (N review turns + N−1 fix turns). For the default max_iterations: 3, this is up to 5 additional agent turns. Factor this into token budget and wall-clock time expectations.

Verification command process lifetime

Each verification command’s process group (its Job Object on Windows) is torn down the same way a hook’s is: see hook process lifetime for the resend, the 2-second bound, and the Windows fallback when a Job Object could not be created or assigned. Two things differ here: the command’s own exit status, not its timeout or its output, decides whether it passed, and the INFO and WARN records this produces carry command in place of hook and workspace.

Dynamic reload

self_review fields take effect on future dispatches. A running worker uses the config snapshot captured at the start of the review phase. Changing enabled to false via dynamic reload stops future workers from entering review but does not interrupt a currently-running review loop.

Minimal:

self_review:
  enabled: true
  verification_commands:
    - "go test ./..."

Full:

self_review:
  enabled: true                     # default false; opt-in
  max_iterations: 3                  # default 3; range [1, 10]
  verification_commands:             # required when enabled
    - "go test ./..."
    - "go vet ./..."
    - "golangci-lint run"
  verification_timeout_ms: 120000    # default 2 min per command
  max_diff_bytes: 102400             # default 100 KB
  reviewer: "same"                   # only supported value is "same"

For operational guidance on setting up self-review, choosing verification commands, and verifying the loop, see how to configure self-review.

reactions

The reactions block configures post-PR feedback loops. Each key is a reaction kind (e.g. review_comments) with its own provider, retry budget, and escalation policy, and four of the kinds also accept an optional triage command that runs before a continuation is dispatched. Reactions are opt-in: omit the block entirely to disable all reaction types. The label_commands key is configured in the same block but is human-triggered rather than event-driven, and it carries no retry budget or escalation.

For the shared reaction lifecycle and every kind Sortie ships, with field tables and safety rules, see the reactions reference.

reactions.review_comments

Polls CHANGES_REQUESTED review comments on Sortie-created PRs and dispatches continuation turns so the agent can address reviewer feedback. Requires provider to be set. Only human reviewer comments are processed; bot and automated comments are filtered by author type.

provider is required when reactions.review_comments is present; omitting it does not produce an error, but review polling is inactive without a provider. This kind also accepts the common max_retries field and validates it like every other kind, but does not consume it: its escalation budget is max_continuation_turns instead, so a max_retries value set here has no effect. escalation must be "label" or "comment"; other values produce a configuration error. poll_interval_ms has a minimum of 30000; values below are rejected. max_continuation_turns must be positive. watch_window_ms must be non-negative and must not exceed 9223372036854. When more than one SCM reaction kind is active, every active kind must name the same provider; a mismatch is a fatal startup error.

Review feedback requires .sortie/scm.json in the workspace to contain pr_number (integer > 0), owner, and repo fields. The agent or after_run hook writes these. When any field is missing or zero, review polling is skipped for that workspace. No error is logged; the feature degrades silently.

reactions.review_comments is captured once when the orchestrator starts and is not rebuilt on a dynamic reload. Changing any field here, and adding or removing the block itself, takes effect only on the next restart. This holds for every reaction kind except ci_failure, which is folded into the CI feedback configuration and re-read on every tick, apart from its max_log_lines and its triage block.

Minimal:

reactions:
  review_comments:
    provider: github

Full:

reactions:
  review_comments:
    provider: github                    # required; registered SCM adapter
    escalation: label                   # "label" or "comment"
    escalation_label: needs-human       # label applied on escalation
    poll_interval_ms: 120000            # 2 min between API polls
    debounce_ms: 60000                  # 60s debounce after last comment
    max_continuation_turns: 3           # hard cap per PR; the escalation budget for this kind
    watch_window_ms: 1800000            # optional; shown at its default (30 min)

When a review-fix continuation dispatches, the prompt receives a review_comments template variable: a list of maps with keys id, file, start_line, end_line, reviewer, body. Templates should guard with {{ if .review_comments }}. See the .review_comments template variable reference below for the full schema, and how to write a prompt template for syntax.

For operational guidance on setting up review feedback, see how to configure PR review feedback.

reactions.merge_completion

Observes the merge state of Sortie-managed PRs and transitions the linked tracker issue to one configured terminal state once the PR merges, whoever performed the merge. This is the only reaction kind whose action is a tracker write; it performs no SCM write and dispatches no continuation turn. It is off by default, and a deployment that omits the block is unaffected. The runtime kind value is merge-completion.

Two tracker fields are required whenever provider is set, each reported as its own configuration error when absent: tracker.handoff_state must be non-empty, and tracker.terminal_states must be written out in front matter rather than left to the adapter’s default list. target_state is required, and compared case-insensitively it must not equal tracker.handoff_state, must not be a member of tracker.active_states (falling back to the adapter’s default active list only when that list is empty), and must be a member of tracker.terminal_states as written. poll_interval_ms below 30000 is rejected, not clamped. sortie validate reports all of these offline, before a run.

Every field here, target_state included, is captured once when the orchestrator starts, as the other reaction kinds are; changing any of them, or either tracker prerequisite, requires a restart. Review feedback’s .sortie/scm.json requirements apply with one exception: this kind reads pr_number, owner, and repo, and needs no branch, because it performs no checkout.

Minimal:

reactions:
  merge_completion:
    provider: github
    target_state: done

Full:

reactions:
  merge_completion:
    provider: github                    # required; registered SCM adapter
    target_state: done                  # required; member of tracker.terminal_states
    poll_interval_ms: 60000             # 60s between merge-state polls
    max_retries: 2                      # transition attempts before escalation
    escalation: label                   # "label" or "comment"
    escalation_label: needs-human       # label applied on escalation

For the lifecycle, the idempotency latch, and the failure matrix, see the merge-completion reference. For setup guidance, see how to set up PR reactions.

reactions.label_commands

Configures the PR label commands: an operator applies a configured label to a Sortie-managed PR, and Sortie dispatches an agent session in response. The review_label (sortie:review by default) dispatches a read-only review; the fix_label (sortie:fix by default) dispatches a session that pushes review-feedback fixes. Unlike the other reaction kinds, this block is human-triggered: it parses through its own path, carries no retry budget or escalation fields, and never appears as a generic reaction entry. For detection semantics, session behavior, and authorization, see the label commands reference.

Activation is by provider: with the block absent or provider empty, the feature is off and no label polling happens for either command. An absent review_label or fix_label takes its default; an explicit empty string is a deliberate disable of that command. Setting provider while both labels are empty strings is a configuration error, which sortie validate reports offline; because the defaults are non-empty, this occurs only when you empty both. A provider naming an unregistered SCM adapter is also a validate error. When more than one SCM reaction kind is active, every active kind must name the same provider, and sortie validate reports a mismatch offline.

Every reactions.label_commands field, including provider, takes effect at startup; changing any of them requires a restart.

A block using the defaults:

reactions:
  label_commands:
    provider: github
    review_label: "sortie:review"
    fix_label: "sortie:fix"
    poll_interval_ms: 60000

notifications

Notification backends for the notify_operator agent tool. While a session runs, the agent escalates decisions, reports progress, or flags blockers through these channels. The tool is registered only when the list configures at least one backend; when the list is absent or empty, the agent is never offered the tool. The value is a sequence: a second channel is a second entry. The tool contract (input schema, response shapes, error kinds) lives in the agent extensions reference.

Each entry accepts two typed fields:

Every other key in an entry passes through to the backend untyped, with $VAR and ${VAR} references resolved on string values, the same mechanism as adapter pass-through configuration. Per-backend required fields:

When more than one entry sets max_per_session, the effective cap is the maximum non-zero value across entries, falling back to 20 when every entry is 0 or unset. The cap counts notify_operator calls, not per-backend sends, and it belongs to one sortie mcp-server process: an agent runtime that starts a new tool server process for each turn starts a new count with each turn, rather than sharing one count across the whole session.

The webhook backend is an outbound POST to an operator-supplied endpoint. Sortie has no inbound webhook receiver of its own (it discovers tracker state only by polling), so this is the only kind of webhook Sortie has.

notifications:
  - kind: slack
    webhook_url: $SORTIE_SLACK_WEBHOOK_URL
    max_per_session: 20
  - kind: webhook
    url: $SORTIE_OPS_WEBHOOK_URL

Changes to this section apply to the next agent session: each session’s MCP sidecar reads the workflow file at startup, so in-flight sessions keep their backends.

db_path

SQLite database file path.

Supports ~ home directory expansion and $VAR environment expansion. An explicit empty string (db_path: "") is equivalent to omitting the field. Non-string values produce a configuration error.

db_path: /var/lib/sortie/state.db

Adapter pass-through configuration

Each adapter reads additional settings from a top-level block named after its kind value. The orchestrator forwards these blocks to the adapter as written, with two exceptions, both checked before any run starts. Either draws an error or a warning at startup, on every workflow reload, and from sortie validate. Each adapter reference page lists its own checks.

The first exception is a value that changes the permission posture an unattended launch depends on. Every agent runs unattended, so nobody is there to answer a prompt. A value that would leave the agent waiting for one is refused as an error: codex.approval_policy, claude-code.permission_mode, and kiro.trust_all_tools with kiro.trust_tools. A value that only narrows what the agent may do, without leaving a turn waiting, draws a warning instead: copilot-cli.allowed_tools and opencode.dangerously_skip_permissions.

The second exception is a value that stops the agent kind resuming a session across separate agent launches. Sortie re-dispatches an issue carrying its earlier session after a retry, a continuation, a stall, or a restart, so such a value makes every resumed turn fail. claude-code.session_persistence set to false is the only key any built-in adapter declares this way; the refusal is an agent.kind.session_resume error and carries no condition on agent.max_turns or on any other core setting.

A session that a dispatch rule routed to an agent kind other than the workflow default reads that kind’s own block, on every attempt of that session. The block named by agent.kind applies only to sessions no rule routed elsewhere.

A kind that dispatch.default.agent or a dispatch.rules[i].agent names, and that differs from the top-level agent.kind, must carry its own top-level block in the front matter. An empty one is enough, written as codex: {} or as a bare codex: key with nothing after it. A block present as a scalar or a list does not count. Its absence is a dispatch.agent.missing_block error at startup, on every workflow reload, and from sortie validate, naming the selector that introduced the kind and the block it expects; the workflow does not start until the block is added. The check is skipped for a kind Sortie does not recognize as a registered adapter, since that is already reported separately as an unknown adapter kind. agent.command stays workflow-wide regardless: a routed kind’s own block cannot override it, so adding the block satisfies this check without changing which binary the route launches.

claude-code

permission_mode and session_persistence are the keys checked before the run. The rest reach the CLI unvalidated, and what it does with an invalid value differs per flag: --effort falls back to the default effort with a warning, and an unknown model name reaches the API and fails there. A key whose YAML value has the wrong type is ignored and the default applies.

claude-code:
  permission_mode: bypassPermissions
  model: <model-id>
  fallback_model: <fallback-model-id>
  max_turns: 50
  max_budget_usd: 5
  effort: high
  allowed_tools: "Read Edit Bash(git diff *)"
  mcp_config: ./mcp-servers.json

copilot-cli

No value in this block is refused before the run; allowed_tools draws a warning only. A key whose YAML value has the wrong type is ignored and the default applies.

The adapter passes --allow-all for unattended operation unless allowed_tools is set, in which case --allow-all is omitted because the grant would otherwise subsume the allow-list. denied_tools, available_tools, and excluded_tools are forwarded alongside --allow-all rather than replacing it: a denied_tools rule still denies a matching call, and the other two still limit what the model sees. Setting allowed_tools draws the copilot-cli.allowed_tools.auto_deny warning rather than an error: every call outside the list is denied without a prompt and the session keeps going, so the narrower configuration limits what the agent may do without leaving it waiting for a person. See validate-time checks.

copilot-cli:
  model: <model-id>
  max_autopilot_continues: 100
  mcp_config: ./mcp-servers.json

codex

The Codex adapter uses a persistent subprocess model: the codex app-server is launched once, when the session starts, and kept alive across turns. This differs from Claude Code, Copilot CLI, and OpenCode, which spawn a new subprocess per turn. The runtime accepts no MCP configuration path, so instead of handing over the generated file the adapter re-expresses its servers as configuration overrides on the app-server command line. That happens on a local launch only; an SSH session receives none, and reaches no Sortie tool. See the Codex adapter reference for the full lifecycle and MCP for the delivery detail.

codex:
  model: <model-id>
  effort: medium
  approval_policy: never
  thread_sandbox: workspaceWrite
  personality: concise
  turn_sandbox_policy:
    networkAccess: true

opencode

The OpenCode runtime accepts no MCP configuration path either, so the adapter re-expresses the generated servers as the runtime’s own configuration document and sets it in the turn’s environment. That happens on a local launch only; an SSH session receives none, and reaches no Sortie tool. See MCP.

The OpenCode adapter always adds run --format json --dir <workspace> -- <prompt>. It does not expose --attach, --port, --command, --file, --title, --continue, or --fork through WORKFLOW.md.

The OpenCode adapter spawns one opencode run --format json subprocess per turn and a second opencode export --sanitize <sessionID> subprocess after the turn to recover authoritative token usage. See the OpenCode CLI adapter reference for the full lifecycle, SSH behavior, and authentication model.

opencode:
  model: <provider>/<model-id>
  variant: high
  pure: true
  dangerously_skip_permissions: true
  disable_autocompact: true
  allowed_tools:
    - read
    - edit
    - glob

kiro

The Kiro adapter spawns one kiro-cli chat --no-interactive subprocess per turn. The headless path reports no token counts, so budget enforcement is time-based through agent.turn_timeout_ms, and MCP is unavailable on the KIRO_API_KEY path. Because there is no channel, a Kiro session reaches none of Sortie’s tools and its first-turn prompt does not advertise them; sortie validate reports that as an agent.kind.no_tool_channel warning. See the Kiro CLI adapter reference for the full lifecycle.

kiro:
  model: <model-id>

agent-client-protocol

This kind names no default runtime and has no other pass-through fields: every runtime-specific setting, such as a model flag or a trust switch, is part of agent.command itself rather than a field in this block. The adapter re-expresses the generated MCP configuration’s servers on session/new, on a local launch only; an SSH session receives none, and reaches no Sortie tool. See the Agent Client Protocol adapter reference for the full lifecycle, the transport-level limits every runtime on this kind shares, and MCP for the delivery detail.

agent-client-protocol:
  mcp_config: ./mcp-servers.json

file (file-based tracker)

file:
  path: ./test-issues.json

Extensions

Unknown top-level keys are collected into an extensions map for forward compatibility. The orchestrator does not validate extension fields at runtime; each consumer defines its own schema. However, sortie validate emits advisory warnings for unknown top-level keys that are not recognized extensions or adapter pass-through blocks, catching typos before deployment.

server

Embedded HTTP observability server. Exposes a JSON API, HTML dashboard, health probes, and Prometheus metrics on a single port. See the HTTP API reference for endpoint details and the Prometheus metrics reference for metric definitions.

The CLI --port flag takes precedence over server.port, and --host takes precedence over server.host. Both require a restart to change.

server:
  port: 9090
  host: "0.0.0.0"

logging

Process-wide log verbosity and output format. Controls the minimum severity level and the serialization format for log lines emitted to stderr.

The CLI --log-level flag takes precedence over logging.level, and --log-format takes precedence over logging.format. Changing either field in the workflow file takes effect only after a restart; dynamic reload does not change the active log level or format.

Unknown values for either field cause startup failure with exit code 1.

logging:
  level: debug
  format: json

token_rates

Per-adapter token pricing for cost estimation on the dashboard. Keys are agent adapter kind strings (e.g., "claude-code", "copilot-cli", "opencode"). All rates are in USD per 1 million tokens.

Each rate field is optional. A missing field means cost is not estimated for that token type. A zero value is valid and produces $0.00. Partial rates are accepted: configuring only output_per_mtok computes cost from output tokens alone.

An entry keyed to an agent kind that reports no token usage for the sessions a workflow produces has no effect: there is nothing to price, and the dashboard’s Est. Cost field for such a session stays blank. sortie validate reports that combination as an agent.kind.no_cost_estimate warning naming the kind, so it is not something to discover from a blank column. Whether a kind reports usage can depend on the launch: copilot-cli reports it locally and none over SSH, so adding a worker.ssh_hosts pool can make a previously effective entry inert.

Validation rules:

• token_rates must be a map when present. Non-map values produce a warning (not a fatal error).
• Rate values must be non-negative numbers. Negative values produce a warning and are treated as not configured.
• An entry keyed to the empty string is dropped with a warning. It prices no kind.
• Invalid sub-values produce warnings logged at startup. They do not prevent boot.

Token rates do not reload dynamically. Changes require a process restart, consistent with server.port and server.host.

token_rates:
  claude-code:
    input_per_mtok: 3.00
    output_per_mtok: 15.00
    cache_read_per_mtok: 0.30
  copilot-cli:
    input_per_mtok: 2.00
    output_per_mtok: 8.00
    cache_read_per_mtok: 0.20
  codex:
    input_per_mtok: 2.50
    output_per_mtok: 10.00
    cache_read_per_mtok: 0.25

See how to control agent costs for operational guidance on cost monitoring.

worker

SSH remote execution. The host with the fewest active sessions is selected per dispatch. See the scale agents with SSH guide for operational setup.

When ssh_hosts is absent or empty, all agents run locally and every other field in this block is ignored; ssh_pass_env and ssh_disallow_pass_env each draw a startup warning naming the field in that case. Every field reloads dynamically: a change applies to sessions dispatched after the reload, and a session already running keeps what it started with.

ssh_strict_host_key_checking values

Invalid values produce a warning log at parse time and fall back to accept-new.

Environment variables carried to a remote agent

The system ssh binary does not hand the orchestrator’s environment to the remote shell, so a remote agent starts with the remote host’s environment and nothing else. Two fields change that.

ssh_pass_env names variables Sortie reads from its own process environment and sends with every remote launch. Each agent kind also carries a fixed set of credential variables without being listed; the environment variables reference gives the names per kind. ssh_disallow_pass_env names variables Sortie never sends, from either source.

worker:
  ssh_hosts:
    - build01.internal
    - build02.internal
  max_concurrent_agents_per_host: 2
  ssh_strict_host_key_checking: "yes"
  ssh_pass_env:
    - SENTRY_AUTH_TOKEN
    - NPM_TOKEN
  ssh_disallow_pass_env:
    - GITHUB_TOKEN

sortie validate reports none of these warnings. They are produced when the worker block is read for dispatch: at startup, after a reload that changes them, and once in --dry-run.

Prompt template

The markdown body after the closing --- is a Go text/template rendered per issue. The template engine runs in strict mode (missingkey=error): referencing an undefined variable or function fails rendering immediately.

The template receives three core top-level variables on every render, .issue, .attempt, and .run, plus six reaction continuation variables that are nil except on the first turn of the matching reaction-triggered dispatch: .ci_failure, .review_comments, .bot_review_comments, .merge_conflict, .label_review, and .label_fix. Every continuation variable defaults to nil so a template referencing it renders under missingkey=error even when the corresponding reaction is never configured.

.issue

Normalized issue object. All fields are present regardless of the underlying tracker system.

.attempt

Integer. 0 on the first try, >= 1 on retries. The value does not change on continuation turns within the same session.

In template conditionals, 0 evaluates to false: {{ if .attempt }} is true only on retries.

.run

.ci_failure

Available only on the first turn of a CI-fix continuation dispatch. nil on normal dispatches and non-CI retries.

.review_comments

Available only on the first turn of a review-fix continuation dispatch. nil on normal dispatches and non-review retries.

A list of maps, one per actionable review comment. Outdated comments (referring to code modified by a subsequent push) are excluded.

{{ if .review_comments }}
## Review Comments to Address

{{ range .review_comments }}
### {{ .reviewer }} on {{ .file }}{{ if .start_line }} (line {{ .start_line }}{{ if .end_line }}-{{ .end_line }}{{ end }}){{ end }}

{{ .body }}

{{ end }}
{{ end }}

.bot_review_comments

Available only on the first turn of a bot-review-fix continuation dispatch, triggered by reactions.bot_review. nil on normal dispatches and non-bot-review retries.

Same per-element shape as .review_comments: a list of maps with .id, .file, .start_line, .end_line, .reviewer (the bot’s login), and .body.

.merge_conflict

Available only on the first turn of a merge-conflict-resolution continuation dispatch, triggered by reactions.merge_conflicts. nil on normal dispatches and non-conflict retries.

.label_review

Available only on the first turn of a read-only label-review dispatch, triggered when an operator applies reactions.label_commands.review_label to a Sortie-managed PR. nil on every other dispatch.

The orchestrator injects only these coordinates. It never fetches the PR diff and never posts a comment itself; a template that omits {{ if .label_review }} produces no review on a label-review dispatch.

.label_fix

Available only on the first turn of a fix dispatch, triggered when an operator applies reactions.label_commands.fix_label to a Sortie-managed PR. nil on every other dispatch.

The orchestrator injects only these coordinates. It never fetches review comments and never pushes or comments itself; a template that omits {{ if .label_fix }} runs the normal work prompt against a real checkout with push capability instead of producing a fix.

Turn semantics

The full template is rendered on every turn. The runtime passes the complete rendered result to the agent regardless of turn number. Template authors branch on .attempt, .run.is_continuation, and each continuation variable to vary content.

Only the one continuation variable matching the triggering reaction is non-nil on that dispatch’s first turn; the other five are nil. On continuation turns, if the rendered prompt is empty, Sortie substitutes a built-in default continuation prompt. On the first turn, an empty rendered prompt is passed through as-is.

Template functions

join uses pipe syntax with reversed arguments: the piped value is passed as the last argument per Go template convention.

Built-in actions

Every action, control structure, and comparison function of Go’s text/template package is available unmodified. Sortie adds no restrictions and no additional actions beyond the three functions above.

Dynamic reload

Sortie watches WORKFLOW.md for filesystem changes and re-applies configuration without restart. The file watcher monitors the parent directory to detect atomic-rename saves (vim, sed -i). Invalid config after reload does not crash Sortie; the last valid configuration remains active and an error is logged.

An in-flight agent session keeps its agent and prompt template frozen at first dispatch. The exception is exit-time behavior: tracker.comments.on_completion and tracker.comments.on_failure are evaluated against the active configuration when the worker exits, so a reload during a session can change whether it posts a completion or failure comment.