Skip to main content
When more than one session works the same repository — a fan-out across agents, two terminals, a teammate — nothing recorded who was on what. claim records it.

​
Advisory, and what that actually means

An advisory marker nobody honours is worse than none, because it looks like coordination. So the line is drawn precisely: Exactly one surface refuses — claiming over another session’s live claim exits non-zero having written nothing. That is what gives “two sessions both claim” a defined outcome instead of a silent race: the loser performs no write at all. Everything else writes to a claimed epic unchanged. A tool that refused to work over an advisory marker would not be advisory — it would be a lock wearing the wrong name, and it would strand work the moment a session died holding one.
The override is --steal, and the name is load-bearing. The state writer reads --force globally off the argument list to bypass its revision guard, so spelling this override that way would have silently disabled optimistic concurrency as a side effect of a cooperative feature. claim --steal still exits with the conflict code if the state moved underneath it.

​
What expires a claim

A stated TTL, carried on the record — not a heartbeat. A heartbeat nothing beats is a creation timestamp in costume, and it makes staleness wrong in both directions: a live session reads stale after a stretch of honest quiet work, and a crashed one reads live until its TTL runs from its last write. The only place a heartbeat could be bumped automatically is the state writer, which does not know which epic is being written. Defaults are 120 minutes for an epic and 30 for the repository marker — shorter on purpose, because a crashed session holding “someone is working here” for two hours is exactly the false signal this feature exists to avoid. The TTL is read, never swept. Nothing rewrites state to expire a claim, which is what lets owners and integrity agree without either of them writing.

​
What reports a stale one

  • owners when you ask — and owners --json answers quiescent: true when nothing is claimed, which is the “is anyone working in this repo” question.
  • integrity when nobody thinks to ask. That is the case that matters: a stale claim is left by a session that is no longer there to ask.
Archiving an epic clears its claim rather than refusing the archive — refusing would be the conductor declining to finish work over an advisory note.

Activity log

The companion question — not who owns work now, but what happened and when.

Related topics

Changelog — What's New in Each pm Release/pm:status — Display the Current Project BriefingPM's Perfect Quartet: OpenSpec, Superpowers, and HonchoState Files: How PM Persists Project Context/pm:upgrade — Migrate State and Refresh PM Rules