Scheduling
How a queued task reaches a worker — eligibility, offers, atomic claims and leases — and why a task can wait.
Eligibility
A worker is eligible for a task when it:
- is connected and approved, with free capacity;
- has the task's project (every repository, for multi-repository projects) mapped;
- matches the task's requirements — OS, labels, tools such as
dockerorpnpm,mcp:<id>tags,os-sandbox; - has a compatible (agent, provider, model) target allowed by policy.
If none qualifies, the task stays QUEUED with a reason that lists what each worker is missing.
Offer and claim
- The scheduler selects a candidate worker by policy and pushes an offer over the worker's WebSocket.
- The worker claims the task. The control plane performs one atomic MongoDB update from
QUEUEDtoCLAIMINGthat also checks dependencies — exactly one claimant can win. - The worker renews the lease with every heartbeat (default lease 5 minutes, heartbeat 15 seconds).
Leases and lost workers
A sweeper finds tasks whose lease expired and, by policy (onWorkerLost), requeues them from the last checkpoint
(REQUEUE, default) or marks them RECOVERY_REQUIRED. A worker that comes back later is fenced off
(LEASE_LOST) and cannot change the task any more.
Order
Among eligible tasks, higher priority goes first, with aging so nothing starves. Concurrency limits and dependencies can hold a task back.