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.
The epic id is the one positional, and it may come after the flags (0.44.0). --steal and --repo take no value, so claim --steal e1 --session s2 claims e1. --id e1 in its place is diagnosed with the line you meant. A token that only looks like a flag is refused rather than skipped — claim --repo --session s --Steal used to record the repo claim, and now prints conductor: unknown flag --Steal for claim — it accepts: --session, --ttl, --steal, --repo, --force. --force belongs to the state write, not to the claim, and does not override a live claim — that is --steal.

​
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. --ttl is bounded: at most 10080 minutes (7 days) (0.44.0), on claim and claim --repo alike. A larger value, zero, a negative or a non-number is refused with exit 1 and nothing is written — not the epic’s claim in state.json, not .conductor/session-claim.json:
A claim is “who owns this right now”, renewed by re-claiming, so a week is generous. Before the bound, claim --ttl 1e12 wrote the claim and then crashed with RangeError: Invalid time value, and from then on owners, integrity and every other session’s claim crashed the same way. A stored claim whose expiry cannot be read is EXPIRED — never live, never a crash. That covers a ttlMinutes above the bound (including one an earlier engine wrote before the bound existed), a claimedAt that does not parse, and a sum that is not a representable date. The writer and the reader judge a TTL with the same predicate, so nothing claim writes can be a claim no reader can read. One consequence after upgrading: a claim taken with a TTL over 7 days reads as expired, so re-claim it if the session is still working.

​
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.
A claim whose expiry cannot be read is reported STALE and expired at an unreadable time, and can be taken over without --steal. With ttlMinutes: 1000000000000 stored on e1:
integrity reports the same claim as expired at an unreadable time (claimed …, ttl 1000000000000 min), and claim e1 --session s2 answers took over 'e1' from session 's1' (its claim had expired). The repo marker is written by temp file plus rename in .conductor/, so a reader racing a write sees the whole old marker or the whole new one — never a torn file read as “no claim”. It is not locked: the marker is advisory and never guarded a read-modify-write. 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.