Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.risolu.to/llms.txt

Use this file to discover all available pages before exploring further.

How Risoluto manages agents from dispatch to completion.

​
Detection & Work Selection

Risoluto receives issue changes via Linear webhooks in real time. Polling runs as a safety net every 15 seconds by default (polling.intervalMs) — when webhooks are active, polling stretches to 2 minutes (webhook.pollingStretchMs). Candidates are filtered using tracker.activeStates and dispatched based on:
  1. Priority — higher priority issues first (lower number = higher priority)
  2. Age — oldest creation time within the same priority
  3. Identifier — alphabetical as a final tiebreaker
During startup, active issues emit lifecycle events through the SSE stream so operators can see where time is being spent:
EventDescription
issue_queuedIssue waiting for an available slot
workspace_preparingGit clone or worktree creation in progress
workspace_readyWorkspace available, preparing container
container_startingDocker container being created
container_runningContainer started, Codex initializing
codex_initializingJSON-RPC handshake in progress
thread_startedAgent has begun working

​
Timeouts & Retries

SettingConfig keyDefaultPurpose
Poll intervalpolling.intervalMs15000 (15 s)Time between Linear polls (no webhook)
Webhook stretchwebhook.pollingStretchMs120000 (2 min)Poll interval when webhooks are active
Webhook health checkwebhook.healthCheckIntervalMs300000 (5 min)Interval to verify webhook health
Hook timeouthooks.timeoutMs60000 (1 min)Max time for lifecycle hooks
SettingConfig keyDefaultPurpose
Read timeoutcodex.readTimeoutMs5000 (5 s)JSON-RPC read timeout
Turn timeoutcodex.turnTimeoutMs3600000 (1 h)Max time per agent turn
Turn stallcodex.stallTimeoutMs300000 (5 min)Detect silent turns
Startup timeoutcodex.startupTimeoutMs30000 (30 s)Container startup limit
SettingConfig keyDefaultPurpose
Agent stallagent.stallTimeoutMs1200000 (20 min)Kill silent agents
Max turnsagent.maxTurns20Conversation turns per run
Max retriesagent.maxContinuationAttempts5Continuation turns per issue
Retry backoffagent.maxRetryBackoffMs300000 (5 min)Max retry delay
For safer live proving, set codex.turnTimeoutMs to something short like 120000 (2 minutes).

​
Container Lifecycle

​
Startup

Risoluto creates a fresh per-attempt CODEX_HOME with generated config.toml, injects auth credentials, and launches the container with resource limits.

​
Normal Shutdown

​
Abort / Shutdown

​
OOM Detection

Exit code 137 with OOMKilled=true is surfaced as container_oom — a retryable failure. Increase codex.sandbox.resources.memory (default: 4g) if this occurs frequently.

​
Model Overrides

Override the model for any issue via the dashboard or API: 
curl -s -X POST http://127.0.0.1:4000/api/v1/MT-42/model \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-5.4","reasoning_effort":"medium"}'
Model changes do not interrupt the active worker — they apply on the next run.

​
State Machine

Risoluto tracks issues through configurable workflow stages.
StageKindDescriptionDispatch eligible?
BacklogbacklogNot yet triagedNo
TodotodoReady for workNo
In ProgressactiveBeing worked onYes
In ReviewgateAwaiting review or approvalNo
Done / CanceledterminalFinished — triggers cleanupNo
When stateMachine.stages is empty (the default), Risoluto derives stages from Linear’s workflow configuration automatically. You only need to configure stages explicitly if you want custom behavior.

​
What’s Next

Trust Model

Sandbox policies, credential handling, and security posture.

Configuration

Customize every timeout, limit, and behavior shown on this page.

Observability

SSE events, Prometheus metrics, and structured logs.

Troubleshooting

Diagnose OOMs, stalls, and failed deliveries.
Last modified on April 3, 2026