beads/docs/cli-reference/unclaim.md
Steve Yegge bd73c75292 fix(claim): stop the refusal copy from teaching claim eviction (bd-at6rc)
The --claim refusal for an issue assigned to another actor said "Use
bd unclaim <id> to release it before re-claiming". In a multi-agent
fleet that copy taught exactly the wrong move: an agent's silenced
'unclaim; claim' batch loop evicted another agent's live, heartbeated
claim mid-review (wyvern incident wy-yuclk, ask wy-zs5s2).

The ownership check itself (foreign unclaim requires --force) already
landed in #4675; this completes the ask by fixing the guidance around
it:

- The open-but-assigned --claim refusal now says to coordinate with
  the holder and notes that releasing another actor's claim requires
  bd unclaim --force.
- Unclaim's ErrNotOwner rejection frames --force as an abandoned-claim
  escape hatch (crashed agent, expired lease), not a routine override.
- bd unclaim's help documents the ownership rule and points at lease
  expiry for genuinely abandoned work.

Tests pin the new coordinate-with-holder copy and assert the old
release-before-reclaiming suggestion stays gone. CLI reference
regenerated; picks up the same pre-existing auto-backup help drift
hunk as #4839 (identical content, merges cleanly either order).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-15 23:03:34 -07:00

949 B

title description
bd unclaim Release a claimed issue

{/* AUTO-GENERATED: do not edit manually */}

Generated from bd help --doc unclaim.

Release a claimed issue by clearing the assignee and resetting status to 'open'.

Use this when an agent crashes mid-work or you need to abandon a claimed task. The issue becomes available for re-claiming by other agents.

Only the current assignee can release its own claim. Releasing another actor's claim requires --force and should be coordinated with the holder first — their claim may be live even if the issue looks idle. Prefer letting lease expiry reclaim genuinely abandoned work.

Examples: bd unclaim bd-123 bd unclaim bd-123 --reason "Agent crashed" bd unclaim bd-123 bd-456

bd unclaim [id...] [flags]

Flags:

      --force           Release the claim even if held by a different actor (admin/reaper use)
  -r, --reason string   Reason for unclaiming