Claims and identity
A claim is how one agent takes a task and every other agent sees that it is
taken. It is a git ref rather than a field, it lasts as long as somebody is
working, and it is held by an identity the caller declares. This page is the
whole lifecycle, from claim to release or done.
What a claim does
$ ank claim 820d
claimed TASK-820d259af6a7 migrate-auth-to-opaque-sessions -> HEAD
Three things happened. The task moved to in_progress. A claim ref appeared at
refs/ank/claims/TASK-820d259af6a7, which is what arbitrates two people or two
agents reaching for the same task: git’s compare-and-swap, one winner. And the
done_criteria was frozen: its hash went into the claim record, where the
file’s editor cannot reach it.
The freeze is the rule worth internalising. Editing the criterion to make the
work fit does not unblock anything; done compares against the recorded hash
and refuses, and check reports the divergence. If the criterion is genuinely
wrong, hand the task back and say so. A subtask you discover is a new task with a
blocked_by, never a softened criterion.
claim also sets HEAD, so the commands that follow need no id. One claim at a
time, per identity.
One identity per session
Claiming a second task while you already hold one is refused:
$ ank claim 51c2
error[7]: human:marie holds a live claim on TASK-820d259af6a7 (expires in 30m)
-> ank release --reason "<why>" (a second session on this machine sets its own ANK_AGENT)
If you meant it, the first way out is the one to take: finish the task you hold
or hand it back. If the refusal surprises you, it is almost certainly two
terminals. $ANK_AGENT names the session, and unset it falls back to
<user>@<hostname>, so two sessions on one machine are the same agent as far as
the refs can tell. Give every concurrent session an identity of its own:
$ ANK_AGENT=human:marie-2 ank claim 51c2
claimed TASK-51c2a0f6d418 say-in-the-readme-what-a-session-is-now -> HEAD
Two sessions sharing an identity are not arbitrated, they are merged.
Claiming the task the identity already holds is granted again at exit 0, so a
second session with no ANK_AGENT of its own silently starts work the first one
is already doing:
$ ank claim 820d
claimed TASK-820d259af6a7 migrate-auth-to-opaque-sessions -> HEAD
So the failure mode is not a message nobody sees. It is two sessions writing the same perimeter under one name, which the refs cannot tell apart and no reader can untangle afterwards. That is why the refusal above names the identity rather than calling you its holder: under a shared identity, the session being refused may have claimed nothing at all.
Write the identity typed. An identity that goes into an entity says what
kind of actor it is (ADR-3877fef1d662): human:<id> is a person,
<producer>/<version> an agent – claude-code/opus-5, and a suffix after +
for one session of it – and process:<id> something automated, which is the
form a pipeline uses. The convention is what lets check say that an entity was
written by an agent and read by no human; the fallback <user>@<hostname>
carries no type and so answers that question with nothing. It is a signal and
not a wall – anyone can type human: in front of a model – and what it buys is
that the ordinary case is legible.
Identity is declared, never proved, and it is deliberately not bound to the
session: a PID or a TTY in it would mean losing your claim to a restarted
terminal. $ANK_AGENT records who was working rather than restricting who may.
Nothing in ank refuses on identity; the refusals are on state, and the one hard
authority line is the signed ratification ank accept writes at
refs/ank/ratify/<id>.
The lease, and what renews it
A claim lasts 30 minutes by default and is renewed by working, not by reporting
(ADR-0bb7ea8991bc). Three verbs move the lease, measured by reading the expiry
out of ank status --json before and after each call:
ank context, in every form – bare, with a path, with--json.ank show <id>, when<id>is the task this identity holds.ank showover any other entity leaves the lease alone, so it is the subject that renews and not the verb.ank log "<message>", the appending form.ank log <id>, which reads, does not.
find, status, scope, graph, check, review and help leave the expiry
untouched. So there is no heartbeat command to remember: writing down what you
learned is what keeps the lock. A tool that shows a corpus to somebody must not
put context or show on a timer, and the machine surface
says what to poll instead.
An expired claim is not a live one. If a build ran long and the lease ran out,
the task stays in_progress and you re-acquire it silently, provided nobody
took it over; and nothing stands between anybody and a task whose lease ran out,
yours or another’s. A task that is in_progress in its file with no ref behind
it is simply one whose claim expired.
Handing a task back
$ ank release --reason "the criterion names a test that does not exist yet"
released TASK-820d259af6a7 -> open
The reason is recorded in the task’s log, where the next holder reads it with
ank log <id> before repeating what you tried. Never let a claim lapse in
silence: an expired lease tells the next agent nothing about why.
When done, the claim becomes a completion
done does not delete the claim ref. It turns it into a completion record naming
the commit and the branch the task was finished on, because status: done lives
in the file, therefore on your branch alone until the merge, and during all that
time the task would look free to everyone else. Anyone who tries to claim it
meanwhile is refused with the commit and the branch named, and every other tree
answers finished on another branch (commit …, branch …), not merged here yet.
check prunes the record once the default branch says the task is done:
Reading ank check shows both states.
Where claims travel
Coordination between clones needs a remote named origin, and nothing
else. Whether claims travel is not configured: a repository with an origin
pushes every claim to it as a compare-and-swap, and one without keeps them as
local refs. GitHub is not required. A bare repository reachable over file://
or ssh on the same network is a remote named origin like any other: claim
reads it first, so the second clone to take a task is refused with code 4 and
the holder named, and the push settles a race the read misses. ank init adds
the refspec that makes refs/ank/* travel, since hosts do not fetch
non-standard refs on their own.
A remote named ank takes the claims, and only the claims. git remote add ank <url> is the whole setup, and there is no key to set: from then on every
read and write of refs/ank/claims/* (claim records and completion records
alike) goes to ank, while ratifications, proofs, the default branch and
everything else stay on origin, where CI and every fork read them
(ADR-b6fe84504ff2). Losing that remote costs leases and nothing else. status
names it on a line of its own, coordination ank carries refs/ank/claims/*, everything else stays on origin, and as coordination_remote in --json, so a
remote given that name for another reason is seen at once; status --remote
reads the claims off it. With ank and no origin, claims are arbitrated
through ank and every other ref stays local, as with no remote at all.
A fetch from origin never touches the claims ank carries. origin’s
+refs/ank/*:refs/ank/* matches refs/ank/claims/* too, so left alone a git fetch origin would write whatever claims origin still holds and git fetch --prune origin would delete every live claim it does not. init therefore
gives ank the fetch refspec +refs/ank/claims/*:refs/ank/claims/* and origin
the negative refspec ^refs/ank/claims/*, which keeps the claims out of its
fetch and its prune while ratifications and proofs still come; where ank was
added after init, the first status or check writes both and says so on
standard error, one line per refspec (ADR-b6fe84504ff2). Removing ank gives
origin the claims back, and the same repair takes the negative refspec away, so
a clone with origin alone ends with exactly the two refspecs above. Where a
refspec could not be written, status warns and check reports a signal of
kind claims-refspec, each naming the remote whose fetch lacks it.
An origin without the refspec is repaired by the first verb that asks.
In a repository with no origin, init adds nothing and says so: refspec +refs/ank/*:refs/ank/* not added: no remote named origin yet, run this once it exists (ank init), and it says the same on every re-run until there is one.
Once origin exists without the refspec, which is also the state of every
fresh clone since git clone does not carry remote.origin.fetch, the first
status or check adds it, fetches refs/ank/* once, and says both on
standard error (ADR-1b030fe70442):
$ ank status
refspec added: +refs/ank/*:refs/ank/*, and refs/ank/* fetched from origin
$ ank check
1 signal(s) owe nothing: settled work, and no command clears them (ank check --all lists them)
check: ok — 0 tasks, 0 adr, 0 signal(s)
A clone that already has the refspec pays nothing for it, and with no origin
nothing is written, so git remote add origin keeps working. An origin that
cannot be reached still gets the refspec, and the next git fetch brings the
refs. Where the refspec itself could not be written, status warns and check
reports a signal, both naming ank init, which writes it the same way. A
re-run of init leaves AGENTS.md and CLAUDE.md as it finds them: the
agent bootstrap block and its @AGENTS.md import are written by the run that
creates .ank/ and by no later one, so a repository that dropped them on
purpose keeps them dropped through every repair (ADR-1f5a45d43f82,
ADR-5eb0f65c75da).
Without a remote, git worktrees of a single clone are still arbitrated,
because they share refs/ank/. Two clones with no common origin are not
arbitrated: both claims of one task succeed, both agents work, and nothing
reports it, not status, not check, not later.
A push that cannot reach the remote leaves the claim standing in your clone and
says so on stderr: the claim holds there only, and another clone can take the
same task. A remote that is reached and refuses the write for a reason of its
own (a hook, a ruleset, a credential) is reported with that reason, exactly as
git push --porcelain printed it: claim exits 9 and keeps nothing, since a
claim the remote refused is not one your clone may believe in, while log,
done, release and close keep what they wrote and warn with the reason.
Neither is ever reported as a task held by somebody else. A contributor working
from a fork is in the first position, and
CONTRIBUTING.md
says how coordination happens instead.