Architecture Overview

1. Tick timer fires (every polling.interval_ms)
   ↓
2. Reconcile running issues
   - Check for stalled sessions (no activity > stall_timeout_ms)
   - Refresh tracker state for all running issues
   - Terminate workers for terminal/inactive issues
   ↓
3. Validate configuration
   - Ensure tracker.kind, api_key, project_slug present
   - Ensure codex.command configured
   ↓
4. Fetch candidate issues from tracker
   - Filter by active_states
   - Sort by priority, created_at, identifier
   ↓
5. Dispatch eligible issues
   - Check: not already running/claimed
   - Check: global concurrency slots available
   - Check: per-state concurrency slots available
   - Check: Todo issues not blocked by non-terminal blockers
   ↓
6. Schedule next poll tick

1. Create/reuse workspace directory
   - Sanitize issue identifier for path safety
   - Run after_create hook if newly created
   ↓
2. Run before_run hook (if configured)
   ↓
3. Start Codex app-server session
   - Send initialize, initialized, thread/start messages
   - Configure approval policy and sandbox settings
   ↓
4. Run first turn
   - Render prompt from WORKFLOW.md template + issue data
   - Send turn/start with full task description
   - Stream events back to orchestrator
   ↓
5. Check for continuation (if turn succeeds)
   - Refresh issue state from tracker
   - If still active AND turn_count < agent.max_turns:
     → Start next turn with continuation guidance
   - If max_turns reached:
     → Return control to orchestrator for retry
   ↓
6. Run after_run hook (always, even on failure)
   ↓
7. Report completion to orchestrator

Worker exits abnormally
   ↓
Orchestrator schedules retry with exponential backoff
   delay = min(10000 * 2^(attempt-1), max_retry_backoff_ms)
   ↓
Retry timer fires
   ↓
Fetch candidate issues (active states only)
   ↓
Find issue by ID
   ↓
Check issue state:
   - Terminal? → Clean workspace, release claim
   - Active + slots available? → Re-dispatch
   - Active + no slots? → Requeue retry
   - Not found/inactive? → Release claim

For each running issue:
   ↓
1. Stall detection
   - elapsed_ms = now - (last_codex_timestamp || started_at)
   - If elapsed_ms > stall_timeout_ms:
     → Terminate worker, schedule retry
   ↓
2. Tracker state refresh
   - Fetch current state from tracker by issue ID
   - If terminal state:
     → Terminate worker, clean workspace
   - If still active:
     → Update in-memory issue snapshot
   - If neither active nor terminal:
     → Terminate worker (no cleanup)

%State{
  poll_interval_ms: integer(),
  max_concurrent_agents: integer(),
  running: %{issue_id => running_entry},
  claimed: MapSet.t(issue_id),
  retry_attempts: %{issue_id => retry_entry},
  completed: MapSet.t(issue_id),
  codex_totals: %{
    input_tokens: integer(),
    output_tokens: integer(),
    total_tokens: integer(),
    seconds_running: integer()
  },
  codex_rate_limits: map() | nil
}