Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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 show over 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.