A claim lease is only meaningful on the replica that granted it. Every other
replica's view of the holder's liveness is stale by up to one sync interval,
so a reaper over there can revert a unit that is very much alive here. Until
now the only defense was operator discipline: partition every supervisor's
reclaim by label and hope nobody runs an unscoped sweep.
Leases now record WHICH replica granted them (leases.granted_node, ignored
migration 0016, stamped from config.NodeID(): BEADS_NODE_ID / node_id config,
falling back to the hostname). bd reclaim skips a lease that positively names
another replica — on both the snapshot SELECT and the per-row DELETE
re-check — and names each skip on stderr, since silence there is
indistinguishable from "nothing to recover" while a genuinely dead remote
worker's unit sits in_progress forever. bd reclaim --any-replica is the
operator escape hatch for a replica that is gone for good.
The guard is deliberately fail-open on unknown provenance: granted_node ''
(a row predating the column, or a deployment whose NodeID is empty) is
treated as local, so the upgrade itself can never strand a stale lease the
reaper could previously recover. A heartbeat backfills an unknown row with
the local node and never overwrites a known one.
The one path that can materialize a FOREIGN lease row locally is
RestoreLeaseOnImportInTx — lease fields round-trip the JSONL interchange — so
the granting replica rides types.Issue.LeaseGrantedNode and a restored lease
keeps the replica the snapshot names, never this node. A snapshot from an
older binary carries none, restores as unknown, and behaves exactly as before.
What the guard cannot enforce is documented instead, in both bd reclaim --help
and docs/multi-agent/federation.md: grace window > sync interval, and lease
TTL > sync interval. A TTL shorter than the cadence at which replicas exchange
state is meaningless across the bridge — the remote view is a full interval
old by construction.
doc/beads-upstream-asks.md section 5.