Runtime Behavior

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:

Priority — higher priority issues first (lower number = higher priority)
Age — oldest creation time within the same priority
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:

Event	Description
`issue_queued`	Issue waiting for an available slot
`workspace_preparing`	Git clone or worktree creation in progress
`workspace_ready`	Workspace available, preparing container
`container_starting`	Docker container being created
`container_running`	Container started, Codex initializing
`codex_initializing`	JSON-RPC handshake in progress
`thread_started`	Agent has begun working

Timeouts & Retries

Polling, Webhooks & Hooks

Setting	Config key	Default	Purpose
Poll interval	`polling.intervalMs`	`15000` (15 s)	Time between Linear polls (no webhook)
Webhook stretch	`webhook.pollingStretchMs`	`120000` (2 min)	Poll interval when webhooks are active
Webhook health check	`webhook.healthCheckIntervalMs`	`300000` (5 min)	Interval to verify webhook health
Hook timeout	`hooks.timeoutMs`	`60000` (1 min)	Max time for lifecycle hooks

Codex Communication

Setting	Config key	Default	Purpose
Read timeout	`codex.readTimeoutMs`	`5000` (5 s)	JSON-RPC read timeout
Turn timeout	`codex.turnTimeoutMs`	`3600000` (1 h)	Max time per agent turn
Turn stall	`codex.stallTimeoutMs`	`300000` (5 min)	Detect silent turns
Startup timeout	`codex.startupTimeoutMs`	`30000` (30 s)	Container startup limit

Agent Lifecycle

Setting	Config key	Default	Purpose
Agent stall	`agent.stallTimeoutMs`	`1200000` (20 min)	Kill silent agents
Max turns	`agent.maxTurns`	`20`	Conversation turns per run
Max retries	`agent.maxContinuationAttempts`	`5`	Continuation turns per issue
Retry backoff	`agent.maxRetryBackoffMs`	`300000` (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.

Stage	Kind	Description	Dispatch eligible?
Backlog	`backlog`	Not yet triaged	No
Todo	`todo`	Ready for work	No
In Progress	`active`	Being worked on	Yes
In Review	`gate`	Awaiting review or approval	No
Done / Canceled	`terminal`	Finished — triggers cleanup	No

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.

Get Started

Core Concepts

Guides

Recipes

Operating

Detection & Work Selection

Timeouts & Retries

Container Lifecycle

Startup

Normal Shutdown

Abort / Shutdown

OOM Detection

Model Overrides

State Machine

What’s Next

Trust Model

Configuration

Observability

Troubleshooting

​Detection & Work Selection

​Timeouts & Retries

​Container Lifecycle

​Startup

​Normal Shutdown

​Abort / Shutdown

​OOM Detection

​Model Overrides

​State Machine

​What’s Next

Trust Model

Configuration

Observability

Troubleshooting

Detection & Work Selection

Timeouts & Retries

Container Lifecycle

Startup

Normal Shutdown

Abort / Shutdown

OOM Detection

Model Overrides

State Machine

What’s Next