beads/docs
Stephanie Jarmak 65078a93ea
fix(claim): enforce unclaim ownership, stamp lease on proxied claim, non-zero exit on lost batch claim (#4675)
* fix(unclaim): enforce claim ownership and rewrite row_lock/lease on release

bd unclaim accepted an actor argument but never compared it to the current
assignee, so any process could release another agent's claim. It also wrote
only status/assignee, leaving lease_expires_at/heartbeat_at/started_at set and
row_lock unchanged, violating the row_lock invariant (lease.go): a concurrent
heartbeat or reclaim on the released row would silently cell-merge instead of
conflicting.

UnclaimIssueInTx now:
- rejects a non-owner with storage.ErrNotOwner (typed, not a silent no-op);
- accepts force to bypass the ownership check (admin/reaper), threaded from a
  new `bd unclaim --force` flag;
- clears lease_expires_at/heartbeat_at/started_at and rewrites row_lock so a
  racing heartbeat/reclaim conflicts.

DoltStore.UnclaimIssue is now wrapped in withRetryTx like the other
claim-family writes, so a lost optimistic merge (1213/1205) is retried rather
than surfaced as a hard failure.

Tests (dolt/lease_test.go): non-owner unclaim is rejected and leaves the claim
intact; owner unclaim clears the lease columns and rewrites row_lock; --force
overrides the ownership check.

* fix(claim): stamp lease and row_lock on the proxied-server (uow) claim path

The uow claim path (internal/storage/domain/db Claim, used in proxied-server
mode) ran the compare-and-swap but omitted lease_expires_at, heartbeat_at, and
the row_lock rewrite that issueops.ClaimIssueInTx writes. A claim made through
this path left the lease columns NULL, so it was invisible to bd reclaim (dead
workers never recovered) and reintroduced the cell-merge class the row_lock
invariant guards against.

Both claim branches now append the shared lease SET-clause and rewrite
row_lock, reusing the same fragment as claim.go via new exported
issueops.LeaseSetClause/LeaseTTL wrappers so the two paths stay in lockstep.
Existing claim behavior (started_at handling, idempotency, conflict surfacing
via ClaimRowResult) is unchanged.

Test (domain/db/issue_test.go): a proxied-mode claim stamps lease_expires_at,
heartbeat_at, and a non-zero row_lock, and is subsequently reclaimable.

* fix(update): exit non-zero when a --claim in a batch is lost

`bd update <a> <b> --claim` set firstUpdatedID from any winner, so a mixed
batch where one claim won and another was lost to a different owner exited 0 —
hiding the lost claim from exit-code automation (beads audit finding #10). Track
a requested-but-lost claim separately and return a non-zero exit while still
committing the winners.

Scoped to the exit-code half of the defect. The `--json` lost-claim surface
(a conflict currently emits nothing on stdout, only stderr) is left as a
follow-up: emitting a structured error object there would change the stdout
contract from a plain issue array and needs its own design.

Test (gated cmd/bd embedded suite): a partial-loss batch exits non-zero, the
winning claim still lands in_progress, and the lost issue is untouched.

* fix(update): exit non-zero when a proxied-server --claim in a batch is lost

The batch exit-code fix (bd4dee4a4) only covered the non-proxied path in
update.go. On the proxied-server runtime, runUpdateProxiedServer set anyUpdated
from any winner, so a mixed batch where one --claim won and another lost to a
different owner still exited 0 — masking the lost claim from exit-code
automation, the same defect as beads audit finding #10 but on the other runtime.

applyUpdateProxiedOne now reports a requested-but-lost claim (already-claimed /
not-claimable while --claim was set) via a new return value; the caller tracks
it in a claimFailed flag and returns SilentExit() at the end, matching the
non-proxied semantics exactly: winners still commit (each ID commits its own
UOW), a lost claim in the batch flips the exit code. No other proxied behavior
changes.

Test (proxied integration suite): a partial-loss batch exits non-zero, the
winning claim lands in_progress under the winning actor, and the pre-claimed
issue is untouched — parity with update_claim_batch_partial_loss_exits_nonzero.
The proxied harness currently can't run because `bd init --proxied-server` is
stubbed upstream (init.go: "not yet implemented"), so this test is wired to the
same contract as its ~20 sibling proxied tests and executes once init lands.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(unclaim): cover ownership rejection and --force at the CLI level

The unclaim ownership fix (fe908d40b) enforced ErrNotOwner and added
`bd unclaim --force`, but was only covered by storage-layer tests
(dolt/lease_test.go) — no CLI-level e2e test, unlike the sibling batch-claim
fix. Add gated embedded-dolt CLI tests:

- unclaim_non_owner_rejected: a non-owner release exits non-zero with the
  ownership error and leaves the claim (assignee + in_progress) intact.
- unclaim_non_owner_force_succeeds: --force lets a non-owner release the claim.

Also assert the new --force flag is registered (TestUnclaimCommand_Flags).

Fix a pre-existing breakage the ownership enforcement introduced but did not
update: unclaim_from_open_stuck_claim released alice's assignment as the default
actor, which now fails ErrNotOwner. Release as the owner (--actor alice),
preserving the open+assigned "stuck claim" dimension the test exercises.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(unclaim): route wisp tables in UnclaimIssueInTx (Copilot #4675)

UnclaimIssueInTx hardcoded issues/events while ClaimIssueInTx routes via
WispTableRouting(IsActiveWispInTx). bd unclaim on an active wisp read the wisp
via GetIssueInTx but UPDATE'd the permanent issues table -> 0 rows / no event
for wisps. Mirror the claim path so a wisp release updates the wisp tables.
The nolint(gosec) comment is now accurate: table names do come from
WispTableRouting. Regular-issue unclaim is unchanged (TestEmbeddedUnclaim).

* docs(cli): regenerate CLI reference for bd unclaim --force flag

The new --force flag on bd unclaim was not reflected in the generated CLI
docs, failing the doc-freshness CI gate. Regenerate docs/CLI_REFERENCE.md and
website/docs/cli-reference/unclaim.md.

---------

Co-authored-by: sjarmak <sjarmak@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-12 13:50:00 -07:00
..
adr fix(init): guard JSONL init against remote history 2026-06-22 15:28:38 -07:00
design Consolidate docs evidence review inventory 2026-05-09 07:21:46 -07:00
staged-for-removal docs: inventory hygiene - add missing rows, remove stale superpowers artifacts (#4659) 2026-07-08 12:21:21 -07:00
ADAPTIVE_IDS.md feat: support issue_id_mode=counter for sequential IDs (#2013) 2026-02-22 23:49:46 -08:00
ADO_CONFIG.md Consolidate docs evidence review inventory 2026-05-09 07:21:46 -07:00
ADVANCED.md docs: fix broken xref to docs/EXTENDING.md in extension example (#3713) 2026-05-05 13:18:43 -07:00
AGENT_SIGNING.md docs: align agent maintainer conventions (#4237) 2026-06-20 20:44:08 -07:00
AIDER_INTEGRATION.md Document supported go install modes (bd-o5a) (#3480) 2026-04-25 11:30:19 -07:00
ANTIVIRUS.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
ARCHITECTURE.md docs: link canonical SYNC_CONCEPTS.md from deeper docs (#4248) 2026-05-29 22:44:54 -07:00
ATTRIBUTION.md fix: remove dead 3-way merge config remnants (GH#2353) 2026-03-05 15:57:33 -08:00
CI_CLEANUP_PLAN.md Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -07:00
CI_REQUIRED_CHECK_TOPOLOGY.md Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -07:00
CI_TEST_SURFACE_AUDIT.md Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -07:00
CLAUDE.md Consolidate docs evidence review inventory 2026-05-09 07:21:46 -07:00
CLAUDE_INTEGRATION.md fix(setup): finish hook JSON migration 2026-05-08 09:21:39 -07:00
CLI_REFERENCE.md fix(claim): enforce unclaim ownership, stamp lease on proxied claim, non-zero exit on lost batch claim (#4675) 2026-07-12 13:50:00 -07:00
CODEX_INTEGRATION.md fix(codex): ship hook release safely 2026-05-27 13:19:41 -07:00
COLLISION_MATH.md docs: fix broken relative links across documentation 2025-12-16 00:46:08 -08:00
COMMUNITY_TOOLS.md docs: add BeadSpec to Native Apps in COMMUNITY_TOOLS (#3922) 2026-07-06 22:12:33 -07:00
CONFIG.md fix(dolt): report pre-push fsck timeout as timeout, not dangling chunk reference (#4650) 2026-07-07 23:10:16 -07:00
CONTRIBUTOR_NAMESPACE_ISOLATION.md cleanup: remove remaining Gas Town terminology from help text, docs, and comments 2026-03-22 13:27:43 -07:00
COPILOT_CLI_INTEGRATION.md feat: add Copilot CLI setup recipe (#3839) 2026-05-14 10:51:38 -07:00
COPILOT_INTEGRATION.md feat: add Copilot CLI setup recipe (#3839) 2026-05-14 10:51:38 -07:00
DEPENDENCIES.md docs(deps): add DEPENDENCIES.md covering dependency system and gates 2026-02-27 10:09:05 -08:00
DOC_INVENTORY.md docs: inventory hygiene - add missing rows, remove stale superpowers artifacts (#4659) 2026-07-08 12:21:21 -07:00
DOLT-BACKEND.md Consolidate docs evidence review inventory 2026-05-09 07:21:46 -07:00
DOLT.md docs: deduplicate release/testing/federation seams (#4660) 2026-07-08 08:12:46 -07:00
ERROR_HANDLING.md /{cmd,docs}: remove FatalError* use HandleError* 2026-07-07 14:51:51 -07:00
EXCLUSIVE_LOCK.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
FAQ.md docs: remove stale sync-branch worktree guidance (#4593) 2026-07-07 13:00:12 -07:00
FEDERATION.md docs: deduplicate release/testing/federation seams (#4660) 2026-07-08 08:12:46 -07:00
GIT_INTEGRATION.md docs: link canonical SYNC_CONCEPTS.md from deeper docs (#4248) 2026-05-29 22:44:54 -07:00
graph-links.md refactor: remove Gas Town references from codebase 2025-12-30 14:13:32 -08:00
ICU-POLICY.md Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -07:00
INSTALLING.md docs: surface upgrade checklist 2026-07-09 16:47:52 -07:00
INTEGRATION_CHARTER.md Document project scope boundaries (mybd-1fn) (#3842) 2026-05-13 06:49:11 -07:00
INTERNALS.md refactor: remove gastown/Gas Town string references from beads code and docs (bd-1ue8) 2026-03-20 18:39:50 -07:00
JSON_SCHEMA.md Consolidate docs evidence review inventory 2026-05-09 07:21:46 -07:00
LABELS.md fix(label): support comma-separated multi-label add/remove; fail hard on bad issue IDs (#4713) 2026-07-12 08:23:52 -07:00
LINTING.md Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -07:00
messaging.md fix(create): commit labels during initial issue creation (#4149) 2026-05-24 19:23:46 -07:00
METADATA.md docs(metadata): document portability of execution model/effort hints (#4358) 2026-06-10 09:30:41 -07:00
MOLECULES.md Keep regular epics open after the last child closes (#3276) 2026-04-17 15:10:38 -07:00
MULTI_REPO_AGENTS.md Consolidate docs evidence review inventory 2026-05-09 07:21:46 -07:00
MULTI_REPO_MIGRATION.md Consolidate docs evidence review inventory 2026-05-09 07:21:46 -07:00
OBSERVABILITY.md docs: clarify reserved log export (#4588) 2026-07-07 13:32:54 -07:00
PERFORMANCE_TESTING.md docs: update stale SQLite references to Dolt across 10 documentation files 2026-02-16 01:22:58 -08:00
PLUGIN.md fix(init): use git origin as default Dolt remote (#3909) 2026-05-13 07:02:39 -07:00
PROJECT_CHARTER.md feat: choose your own storage backend (Postgres / MySQL / SQLite) — rebased on main 2026-07-10 17:44:37 +00:00
PROTECTED_BRANCHES.md docs: remove stale sync-branch worktree guidance (#4593) 2026-07-07 13:00:12 -07:00
QUICKSTART.md feat: add bd unclaim command to release stuck issues (replaces #3694) (#4614) 2026-07-06 22:51:35 -07:00
README_TESTING.md Consolidate docs evidence review inventory 2026-05-09 07:21:46 -07:00
RECOVERY.md feat(migrate): add --force flag as CLI twin of BD_ALLOW_REMOTE_MIGRATE (#4654) 2026-07-07 15:58:18 -07:00
RELATED_PROJECTS.md docs: add Related Projects pointer (scry) (#4101) 2026-07-06 22:12:37 -07:00
RELEASE-STABILITY-GATE.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
RELEASING.md Consolidate docs evidence review inventory 2026-05-09 07:21:46 -07:00
REPO_CONTEXT.md docs: replace stale bd sync references with bd dolt push/pull (GH#2442, GH#2435) 2026-03-08 10:12:08 -07:00
ROUTING.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
RULES_AUDIT_DESIGN.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
SECURITY-DEPENDENCY-EXCEPTIONS.md chore: harden release and dependency security 2026-04-28 08:45:22 +00:00
SETUP.md feat(prime): add agent.profile config + BD_AGENT_PROFILE runtime knob (#4585) 2026-07-07 13:23:21 -07:00
STORAGE-BACKENDS.md feat: choose your own storage backend (Postgres / MySQL / SQLite) — rebased on main 2026-07-10 17:44:37 +00:00
SYNC_CONCEPTS.md docs: clarify export versus database backup (#4048) 2026-05-20 16:19:23 -07:00
SYNC_SETUP.md /{.github,docs,go,internal,scripts}: bump dolt min version and driver 2026-07-06 16:04:11 -07:00
TESTING.md /{.github,docs,go,internal,scripts}: bump dolt min version and driver 2026-07-06 16:04:11 -07:00
TESTING_PHILOSOPHY.md Consolidate docs evidence review inventory 2026-05-09 07:21:46 -07:00
TODO.md docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4) 2026-02-22 22:18:02 -08:00
TROUBLESHOOTING.md docs: remove stale sync-branch worktree guidance (#4593) 2026-07-07 13:00:12 -07:00
UI_PHILOSOPHY.md docs: consolidate duplicate UI_PHILOSOPHY files (GH#745) 2025-12-27 18:01:59 -08:00
UNINSTALLING.md docs: publish community tools on website (#4299) 2026-06-03 13:44:47 -07:00
WORKTREES.md docs: remove stale sync-branch worktree guidance (#4593) 2026-07-07 13:00:12 -07:00