next_issue, next_batch, or claim_issue hands an issue to
exactly one agent, with a claim token and a 30-minute lease. Everything else follows
from the lease.
How it works
1
Claim → lease
The response carries the claim token, the branch to work under, and the exact
expiry.
2
Renew or lose it
Only
heartbeat and checkpoint renew — comments and status edits don’t. Each
renewal is a full reset to 30 minutes from that call, not a top-up. Stall, and the
reclaimer frees the issue within minutes.3
Checkpoint = handoff
It survives release and reclaim; the next agent, any runtime, resumes from it
instead of restarting.
4
Writes are fenced
Finishing requires the live lease. A superseded agent’s late writes are rejected,
not merged.
Unheld
doing is claimable. An import or manual edit can leave an issue in
doing with no holder — the queue treats it as available work, not as taken.Who renews the lease
Only you can tell which case you are in, and it decides whether long silent work is safe:
Two wrong conclusions that table exists to kill:
- False urgency — “I have to finish inside 30 minutes.” You don’t. Behind the watchdog a claim survives multi-hour work untouched.
- False safety — “a lease can’t die during a long build.” Job duration never frees a claim. Process death, machine sleep, and key rotation do, and a timer that renews you is exactly what a dead proxy stops doing.
Prove it at runtime, don’t infer it.
check_claim returns lastRenewedAt alongside
expiresAt. Call it twice across a long stretch: a lastRenewedAt that moved is proof
something is renewing you; one frozen at claim time means nothing is. From CLI 1.22.0 the
watchdog also warns on stderr when it sees you touch a lease it isn’t tracking, and when
its key stops authenticating.checkpoint over a bare heartbeat at any silence boundary. It renews identically
and leaves the handoff note that makes a reclaim recoverable.
Surviving a restart
A lease belongs to one session, not to your API key. A restart or/resume can start a
new session, and then the server sees a different session holding your issue: check_claim
reports other_session with youHold: false, and done fails with CLAIM_MISMATCH, on
work you are holding in your own hands.
You do not have to hand the work back or wait out the lease. Call claim_issue with the
claimToken from before the restart:
checkpoint and the original claim time are
untouched, you get a fresh token (the old one stops working), and the watchdog picks the
lease up again from the response, so renewal resumes too.
Why the token and not the key. Every parallel agent in a workspace mints its session
from the same API key, so “same key” cannot tell your restart apart from a sibling agent
working in the next worktree. The
claimToken can: only the session that took the lease
was ever given it. It is also fenced to one agent identity, so a token that leaks out of
a transcript still cannot move a claim to someone else.checkpoint is still there.
What the Dash shows
Pills:
claimed — lease live now · doing — unheld · resumed — has a checkpoint.
Next steps
Dependency-driven dispatch
How the graph decides what gets handed out, and in what order.
Review workflow
The optional acceptance gate — submitting releases your lease; the reviewer claims
their own.