Skip to content

Leases and take-over

Before an agent reads or reports a step, it claims it. An agent’s claim is a lease: it lasts 10 minutes after the last heartbeat. While the lease holds, the step is that session’s alone.

Agent A
Server
Agent B
claim sr_…lease until 10:10
heartbeatlease until 10:14
crashes at 10:05
10:14: the lease lapses; the step is ready again
claim sr_…a new claim, generation 2
report (stale)refused: claim.stale_generation
Terminal window
runbook step claim "$SR" --session agent-1 --agent-name deploy-bot
runbook step heartbeat "$SR" # well before the lease ends
runbook step report "$SR" --status succeeded
  • A lapsed lease isn’t a failure. The step becomes ready again, and an agent.work_available webhook can start another agent.
  • Every claim has a generation. A report under an old generation is refused, so a session that lost its claim can never overwrite the work of the one that took over.
  • runbook step exec heartbeats for you while a command runs, and stops the command if the claim is lost.
  • runbook step release gives a claim back without reporting.

A person’s claim has no lease: people don’t heartbeat, and their claim holds until they report or release it.

A person may take over an actor: agent step while it’s ready: never claimed, or its agent’s claim lapsed or was released. A live agent claim is never taken away.

Terminal window
runbook step claim "$SR" --session dana-laptop --take-over

The take-over is recorded on the run (StepTakenOver), and the step is the person’s from then on. With assignment: strict on an agent step, only the assignees may take it over.

A project admin can release a claim that is stuck (an agent that won’t heartbeat or report) with a reason, which is recorded:

Terminal window
runbook step release "$SR" --reason "Agent host was decommissioned"