Sometimes an agent goes quiet without finishing — it stops emitting console output, stops calling MCP tools, but its Claude session is still alive. The work might be done (it just forgot to call complete_task) or it might be genuinely stuck. Build Station has automatic recovery for both cases.
First: is it reviewing?
Before assuming a stall, check what the session says it is doing. A session that is Reviewing is not writing code — it is reading a diff and forming a verdict — and it looks quieter than a coding session because it is. Since 1.3.0 the Station shows Reviewing as its own state, distinct from an agent writing code, and the Dashboard counts working and reviewing separately.
Before that distinction existed, both appeared as ordinary running work, and a task sitting in Review with an agent apparently busy on it was the single most common reason people wondered whether the Station was stuck. If you see Reviewing, the answer is usually to wait: the review ends when the review ends, not when the task leaves the working column.
The idle heuristic
For each running agent session, Build Station watches the console output. If nothing new is emitted for 5 minutes, the session is "idle". Build Station then acts in two stages.
Stage 1: Nudge
After the first 5-minute idle window, Build Station types a message directly into the Claude session:
Note: I noticed you've been silent for 5 minutes. If you've finished the task — run
git commitand call complete_task with a summary. If you're still working, just continue.
The session is still alive at this point. The nudge often kicks the agent into completing properly — typically the case is that the work was done, the agent just forgot the workflow's final steps.
Once nudged, the idle timer resets. If new console activity follows, all is well — the agent is back on track and the task continues normally.
Stage 2: Block
If after the nudge the session goes idle for another 5 minutes (no new output at all), Build Station decides the agent is genuinely stuck and:
1. Calls block_task on the server
The task moves to Blocked with a reason explaining that the local idle heuristic fired. The agent's task queue is released so the next task can be picked up.
2. Kills the Claude session locally
The tmux window (macOS) or subprocess (Windows) is terminated. Build Station's resources are reclaimed.
3. Releases the project lock
The next queued task on that project can spawn.
Total time from "really stuck" to recovery: 10 minutes (5 idle + 5 post-nudge idle).
Why not just kill immediately on 5 minutes idle?
Earlier versions of the daemon did. The common failure mode it catches is: agent finished the work, made the commit, and got tangled in the workflow rules around calling complete_task. The work is done, the session is fine, it just needs a small prompt. Killing it loses that work — you'd lose the commit context and start over.
The nudge gives the agent a chance to land the work cleanly without losing context. Block-on-stall is the fallback for the truly stuck case.
Idle ≠ no output ever
The heuristic looks at the console stream, not just MCP activity. So even if an agent is silent on MCP for 10 minutes but happily streaming "running tests" / "reading file X" type output to its TUI, it's NOT considered idle. The check is "any console output in the last 5 minutes".
This is intentional. A long-running test suite or repo scan is real work, even when nothing's being committed. We don't want to nudge an agent halfway through a 10-minute test run.
What you see in the console stream
When the nudge fires, you see the nudge message appear in the live console — typed as if you'd sent it. The agent's response follows.
When the block-on-stall fires, the stream just ends. The task moves to Blocked on the dashboard with a reason like "Local idle heuristic fired — agent silent for 10 minutes total".
Manual recovery
If the heuristic blocks a task that you know wasn't actually stuck, just move it back to To Do on the dashboard. Build Station picks it up again on the next opportunity, spawning a fresh session.
Tuning
The 5-minute window is currently fixed and not user-tunable. If your typical workloads have very long quiet stretches that exceed this (e.g., huge test suites with no log output), please file feedback — we're considering a per-project override.
For now, the workaround is to have your agent emit a heartbeat periodically: a one-line echo "still working" between long phases keeps the idle timer alive.