Fleet docs v0.2.0-rc.448

A stuck worker: retry, hold, ask a person

A worker can stop without progress in four ways. It goes silent (watched, not stopped). It ends turns that do nothing. It ends a turn with no done. It asks a question. fleet answers each one differently.

Silent: watched, never stopped

Nothing stops a turn for being silent, and no turn has a default time or budget limit (owner ruling 2026-11-05, #230). The node watches the output of the turn stream and the CPU of every process of the turn, and the agent has one of three states, which the page and fleet ls show:

  • active: the turn has output.
  • busy: no output, but the tools of the turn (the processes below the model CLI, whose own idle CPU is ignored) use CPU, such as a long test run.
  • silent: no output and no CPU for --silent-after (20 min). The node writes one SILENT: ... status report. The turn keeps running. When it moves again one more report says so (fleet/internal/node/hang.go).

A process that dies is a crash, not silence: the supervisor tries again after 30 s, 2 minutes and 8 minutes. A time limit exists only when a person asks for one with --time-cap-s.

Each done, failed, blocked, needs_input and silent is pushed to the one who started the worker: a parent agent gets a note from fleet in its inbox, which wakes it. A worker started by a Claude session (CLAUDE_CODE_SESSION_ID) goes to the webhook in push_webhook_file of the serve config, as JSON. A worker started by a person goes to their Telegram chat (fleet/internal/push/). A chief subscribes with fleet watch <url>, which sets that webhook on the server (an admin only; it is kept in the server's dir as push-webhook and wins over the config file; fleet watch --off stops it).

Turns that do nothing: the hold

A turn ends with no done

A question to a person

End of a turn State What wakes it
fleet status --blocked in the turn blocked A message, or resume
An ask in the turn needs_input The answer
Tool denials needs_input "denied: ..." A message
Messages wait for it working It starts again at once
None of these, and no done needs_input A message
  • The model ladder is DefaultLadder in supervisor.go. An agent with a model that is not on the ladder goes to blocked after the second stuck retry.
  • Code: fleet/internal/supervisor/supervisor.go, watchdog.go, guard.go, fleet/internal/api/lifecycle.go, fleet/internal/notify/.
  • If the owner has no linked Telegram chat, the question waits in fleet asks.
  • An ask to parent or to an agent name goes through the mailbox, not Telegram.
  • A plain Telegram message with no reply goes to the only agent that waits. If more than one agent waits, the bot tells you to reply to the question.
  • Not built: a limit on the number of turns of one agent.
  • The page shows each case in the workers panel and the supervisor log.