beads/website/docs/cli-reference
Steve Yegge e97839a2e1
feat(lease): land the leasing stack + schema v54 (claim-TTL, heartbeat, reclaim) (#4537)
* fix(dolt): retry mutate+commit methods on serialization conflict (1213/1205)

ClaimIssue, ClaimReadyIssue, UpdateIssue and CloseIssue each hand-rolled
their own tx (BeginTx + DOLT_ADD/DOLT_COMMIT + Commit) outside
withRetryTx, so a concurrent writer that lost Dolt's optimistic
commit-time merge surfaced MySQL 1213/1205 as a hard failure instead of
retrying. Dolt has no real row locking — FOR UPDATE / SKIP LOCKED are
parse-only no-ops (https://www.dolthub.com/blog/2023-10-23-hold-my-beer/)
— so retry is the only safety net under N concurrent workers. These four
are the work-queue hot paths: `bd ready --claim`, claim, update, close.

Move each body into a withRetryTx closure (which owns BeginTx and the
final Commit and retries serialization failures with backoff), preserving
the single-tx CAS/mutation + DOLT_COMMIT atomicity exactly. On retry,
ClaimReadyIssue re-scans the ready front from a fresh snapshot and claims
the next available issue.

Tested: TestEmbeddedReadyClaimConcurrent, TestEmbeddedReadyConcurrent,
TestEmbeddedCloseConcurrent, TestEmbeddedUpdateConcurrent and the
non-concurrent embedded Update/Close/Ready tests pass; build + vet clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(dolt): add concurrent work-queue drain test (Gas Station claim invariant)

N workers concurrently dequeue one shared ready-front via ClaimReadyIssue
until empty; asserts every issue claimed exactly once, none stranded, no
double-claims, and no serialization error ever surfaces (withRetryTx absorbs
the 1213/1205 from the claim-CAS cell collision). This is the regression guard
for the multi-agent claim queue that #4491 makes safe.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(lease): claim-TTL + heartbeat + reclaim for dead-worker recovery

Gas Station v1.1 (wy-5r9j). A claim was previously permanent: a worker that
died mid-task stranded its issue in_progress forever. This adds a lease so a
claim can expire and be recovered.

Schema (migration 0054): add lease_expires_at, heartbeat_at (DATETIME) and
row_lock (BIGINT) to issues (and wisps, for uniform issueops routing), plus
idx_issues_lease for the reaper scan. assignee doubles as the lease owner.

Lifecycle (shared issueops, so both server-mode DoltStore and EmbeddedDoltStore
get it):
  - Claim stamps lease_expires_at = now + TTL (default 5m, WithLeaseTTL to
    override), heartbeat_at = now, and a fresh row_lock.
  - bd heartbeat <id> — owner-only; pushes the lease forward and rewrites
    row_lock. Fails (ErrNotClaimable/ErrAlreadyClaimed) once the lease is gone.
  - bd reclaim --older-than <dur> — reverts in_progress issues whose lease
    expired more than <dur> ago back to ready (clears assignee/started_at,
    records a lease_reclaimed event). Default grace 2×TTL.

The row_lock trick: Dolt has no row locking and merges concurrent commits
cell-by-cell, so a heartbeat (writes heartbeat_at) racing a reclaim (writes
status) would silently cell-merge into a zombie — an open/unassigned issue that
still carries the worker's fresh heartbeat. Every mutating path (claim, close,
update, heartbeat, reclaim) now rewrites the shared row_lock cell, forcing the
loser to a 1213/1205 serialization conflict that withRetryTx replays. All lease
paths are withRetryTx/withConn wrapped.

Tests (real Dolt): TestRowLockForcesConflictOnDisjointCellWrites proves the bug
without row_lock (silent merge to zombie) and correctness with it (conflict);
TestConcurrentHeartbeatReclaimClose is the integration race (live workers
heartbeat+close vs a continuous reaper vs dead workers) asserting exactly-once,
no lost close, no zombie; plus claim/heartbeat/reclaim unit coverage on both
backends.

Note: lease columns are second-granular DATETIME (Dolt rounds), so sub-second
TTLs are meaningless — production TTL is minutes. Heartbeat writes a Dolt
commit, so cadence must stay ≪ claim cadence to avoid history bloat.

Fixes the test coupling in TestMigration0053PromotesRigWisps, which assumed the
rig-wisp repair was always LatestVersion().

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci+docs: allowlist lease stress tests; scope the row_lock invariant comment

- Add TestConcurrentWorkQueueDrain and TestConcurrentHeartbeatReclaimClose
  to the check-testing-short.sh allowlist; both are real-Dolt runtime/stress
  skips and were failing ci-pr-policy.
- freshRowLock doc said "EVERY mutating path" rewrites row_lock, which
  overstates it. Scope it to status/ownership/lease-mutating paths (the set
  the reclaim/heartbeat races care about) and document the invariant + why
  orthogonal-cell writers (is_blocked, compaction, deps, rename, reopen) are
  intentionally exempt, so a future writer does not silently reintroduce the
  zombie-merge bug.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(show): surface lease_expires_at/heartbeat_at in bd show (--json + text) (wy-9cdw)

Migration 0054 added lease_expires_at/heartbeat_at (and internal row_lock) to
the issues/wisps tables for the claim/heartbeat/reclaim leasing feature, but
bd show could not observe lease state — you had to drop to raw SQL.

- types.Issue: add LeaseExpiresAt/HeartbeatAt (*time.Time, omitempty), matching
  the StartedAt nullable-timestamp convention. row_lock stays unexported.
- sqlbuild.IssueSelectColumns: append lease_expires_at, heartbeat_at to the
  canonical hydration list (flows to every stack via the shared constant).
- issueops.ScanIssueFrom: scan + map the two nullable columns (before the
  trailing extra dests, keeping positional parity across all scan sites).
- bd show text view: emit a muted 'Lease: expires <rel> (heartbeat <rel> ago)'
  line only for in_progress issues holding an active lease; add formatTimeUntil
  as the forward-looking mirror of formatTimeAgo.
- types_test: assert lease keys appear when set, are omitted when nil, and that
  row_lock is never surfaced.

* fix(lease): settle v54 review blockers

Address #4537 review blockers before landing v54: keep heartbeat off wisps in both backends, keep direct status/assignee updates from leaving stale leases, guard the down migration, and emit reclaim JSON as snake_case.

Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie

* fix(lease): cover lease fields in tests and hooks

Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-03 23:28:55 -07:00
..
admin.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
ado.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
assign.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
audit.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
backup.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
batch.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
blocked.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
bootstrap.md fix(init): use git origin as default Dolt remote (#3909) 2026-05-13 07:02:39 -07:00
branch.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
children.md fix(cli): implement children pretty and defer reason 2026-06-13 21:22:38 -07:00
close.md fix(close): support per-id reasons (#4194) 2026-05-27 20:41:07 -07:00
comment.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
comments.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
compact.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
completion.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
config.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
context.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
cook.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
count.md feat(count): add --include-infra for exact bd list cardinality parity (#4389) 2026-06-13 04:14:28 -07:00
create-form.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
create.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
defer.md fix(cli): implement children pretty and defer reason 2026-06-13 21:22:38 -07:00
delete.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
dep.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
diff.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
doctor.md fix(init): use git origin as default Dolt remote (#3909) 2026-05-13 07:02:39 -07:00
dolt.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
duplicate.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
duplicates.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
edit.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
epic.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
export.md Fix rig bead durability (#4373) 2026-06-22 17:06:35 -07:00
federation.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
find-duplicates.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
flatten.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
forget.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
formula.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
gate.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
gc.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
github.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
gitlab.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
graph.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
heartbeat.md feat(lease): land the leasing stack + schema v54 (claim-TTL, heartbeat, reclaim) (#4537) 2026-07-03 23:28:55 -07:00
history.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
hooks.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
human.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
import.md feat(count): add --include-infra for exact bd list cardinality parity (#4389) 2026-06-13 04:14:28 -07:00
index.md feat(lease): land the leasing stack + schema v54 (claim-TTL, heartbeat, reclaim) (#4537) 2026-07-03 23:28:55 -07:00
info.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
init-safety.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
init.md fix(init): guard JSONL init against remote history 2026-06-22 15:28:38 -07:00
jira.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
kv.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
label.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
linear.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
link.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
lint.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
list.md Fix rig bead durability (#4373) 2026-06-22 17:06:35 -07:00
mail.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
memories.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
merge-slot.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
metrics.md fix(cli): handle unchecked output-helper errors + regen metrics CLI docs (#4482) 2026-06-23 02:18:01 -07:00
migrate.md /{cmd,docs,website}: gen docs again 2026-05-26 10:13:11 -07:00
mol.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
note.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
notion.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
onboard.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
orphans.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
ping.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
preflight.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
prime.md fix(setup): finish hook JSON migration 2026-05-08 09:21:39 -07:00
priority.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
promote.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
prune.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
purge.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
q.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
query.md /docs: regen CLI reference for bd query --offset flag 2026-06-24 14:47:29 -07:00
quickstart.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
ready.md docs: regenerate CLI reference for bd ready --offset 2026-06-18 13:55:12 -07:00
recall.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
reclaim.md feat(lease): land the leasing stack + schema v54 (claim-TTL, heartbeat, reclaim) (#4537) 2026-07-03 23:28:55 -07:00
recompute-blocked.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
remember.md docs(cli): regenerate CLI reference for bd remember bare-key reads (#4545) 2026-07-02 09:14:33 -07:00
rename-prefix.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
rename.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
reopen.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
repo.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
restore.md fix(compact): archive content before destructive compaction; make restore work (#4464) 2026-06-20 14:12:07 -07:00
rules.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
search.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
set-state.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
setup.md init: run Codex project setup by default 2026-05-26 13:03:37 -07:00
ship.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
show.md feat(show): count-only JSON details with opt-in streamed payloads 2026-05-22 16:54:15 -07:00
sql.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
stale.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
state.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
status.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
statuses.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
supersede.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
swarm.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
tag.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
todo.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
types.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
undefer.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
update.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
upgrade.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
vc.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
version.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
where.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
worktree.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00