beads/docs/multi-agent
Steve Yegge 5a4c68a89c fix(leases): keep node_id off the committed config; tighten the replica guard (wy-jpd3.7)
Second adversarial review of the replica-aware lease work, against the opt-in
rewrite. One blocker, in the operating instruction rather than the code.

node_id was documented as "BEADS_NODE_ID, or node_id in config.yaml", and
`bd config set node_id` wrote the PROJECT .beads/config.yaml — a git-TRACKED
file (nothing in .beads/.gitignore excludes it). Commit "node_id: mini" and
every clone that pulls reads "mini", so every granted_node comparison matches
and the guard is at once fully ARMED and fully INERT: laptop reaps mini's
leases exactly as if they were local. That is the precise hazard the feature
exists to close, now happening while the operator believes they are protected
— strictly worse than the pre-feature state, where nobody thought they were.
node_id is per-machine state, the class .beads/.gitignore already excludes as
sync-state.json / push-state.json / redirect. It now routes to the user-global
~/.config/bd/config.yaml through a new exact-key arm of IsUserGlobalKey (the
prefix list only ever held "metrics."); viper already merges that file, so
config.NodeID() reads it straight back.

The docs also said to set it "on every replica sharing the queue", which on a
shared or remote dolt sql-server means every HOST — rebuilding the same
fail-closed regression this commit's parent removed the hostname fallback to
avoid. The load-bearing rule was never stated: node_id names the STORE, not
the host. Clients of one sql-server are ONE replica and must share a value or
leave it unset. Now said outright in federation.md and `bd reclaim --help`.

Also from the review:
- bd show claimed "reclaim will decline it" for any foreign node, but with an
  unnamed local node the guard is disarmed and reclaim reverts the lease
  happily. The annotation is now gated on config.NodeID() != "".
- TestNodeIDContextOverride's empty-override assertion had gone tautological
  when the hostname fallback went away: config.NodeID() is "" under test, so
  it passed whether or not WithNodeID worked at all. It now sets a non-empty
  fallback, asserts the fallback is what a no-override read returns, and only
  then asserts the empty override still beats it.
- The heartbeat backfill's bare `granted_node = ''` is COALESCE'd, matching
  the reclaim predicates; under NULL the IF took the else branch and the row
  was never backfilled. Unreachable today (0016 is NOT NULL DEFAULT ''), but
  the two sites disagreed about whether NULL was possible.
- The --any-replica audit line is skipped when localNode is "" rather than
  printing `not this node ("")`: nothing was overridden, the guard was never
  armed.
- reclaimReplicaSQL documents WHY granted_node stays unqualified — the DELETE
  splices it into a bare `DELETE FROM leases` with no alias to qualify with —
  and what to do if issues ever grows a column of that name.
- CHANGELOG entry, which this feature owed: a new flag, a new config key, two
  env vars, and two public struct fields shipped without one.
2026-07-25 02:32:31 -07:00
..
coordination.md docs: align user docs and CLI reference with the v1.1.0 release (#4874) 2026-07-17 14:17:28 -07:00
federation.md fix(leases): keep node_id off the committed config; tighten the replica guard (wy-jpd3.7) 2026-07-25 02:32:31 -07:00
index.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
multi-repo-migration.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
routing.md docs: align user docs and CLI reference with the v1.1.0 release (#4874) 2026-07-17 14:17:28 -07:00