Build Station has two independent paths for getting tasks from the backend to your machine. They run in parallel and back each other up.
Path 1: SSE push (live)
While Build Station is running and signed in, it keeps a long-lived Server-Sent Events stream open to the backend, one per enabled agent. When a task gets assigned to one of those agents and lands in To Do, the backend pushes the event over the SSE stream within milliseconds.
Build Station then:
- Checks if there's already a Claude session running for that project (the project lock).
- If free, spawns a new session immediately. Latency from task creation to spawn: sub-second.
- If busy, queues the task locally. The local queue drains as soon as the running task completes.
SSE is the primary path. It's how 99% of tasks get picked up in normal operation.
Path 2: The poller (every 30 seconds)
A backup mechanism that fetches each enabled agent's queue from the backend on a fixed 30-second tick.
The poller exists because:
- Build Station was offline when the task was created. SSE doesn't help here — there was no stream. The next poller tick after Build Station comes online finds the task.
- The SSE stream broke and silently reconnected. Some networks drop long-lived streams; reconnection is automatic but events during the gap could be missed. The poller catches them.
- A task slipped past somehow. Defense in depth.
The poller fires every 30 seconds while Build Station is running. It doesn't make extra noise when there's nothing queued — just one quick API call per agent per tick.
What both paths check before spawning
When either path finds a task to handle, it goes through the same gates:
1. Is the project enabled here?
If you've disabled the project locally, the task gets ignored. It'll be picked up by some other Build Station you have signed in, or sit on the server queue.
2. Is the agent enabled here?
Same logic, per agent.
3. Is the project's working directory busy?
The project lock. If another agent is already running a Claude session in this project's directory, we queue. See One task at a time per project.
4. Is THIS agent at its per-agent concurrency limit?
Max concurrent setting. See Per-agent concurrency.
5. Spawn
All gates pass → Build Station generates a per-spawn MCP config and launches Claude Code in the project's working directory.
Why a task might not pick up
When you expect a task to start and nothing happens:
| Symptom | Likely cause |
|---|---|
| Task in To Do but never moves | Agent not enabled here, OR project disabled here, OR project lock held by another agent. |
| Picked up by a different Build Station | You're signed in on another machine and that one grabbed it first. |
| Task sits for ~30 seconds then moves | Polling cadence, not real-time. Either SSE wasn't connected at the moment or the SSE event was missed and the poller caught it. |
| Tray icon stays grey | Build Station is offline — check network, instance URL, sign-in. |
See Troubleshooting for fixes.
Backpressure
There's no explicit backpressure — if the backend dispatches faster than Build Station can spawn, tasks pile up locally and on the server queue. In practice this almost never matters: tasks take orders of magnitude longer than spawn setup, so the queue stays short.
The one place backpressure shows up is the project lock: with many agents on one project, you can have a long local queue waiting for the active task to finish.