Every multi-machine beads deployment hand-rolls the same shell loop around
pull/push; this ships it as `bd sync [--remote <name>] [--attempts N]`.
Three properties are the point of the verb, and each is a lesson paid for by
the reference deployment (a two-machine federation on a 60s timer):
- Conflicts are detected POSITIVELY, from the merge's own captured conflict
rows and from dolt_conflicts — never inferred from the pull's exit status.
A pull fails for reasons that are not conflicts, and a settled merge that IS
conflicted aborts and leaves dolt_conflicts empty, so an exit-status guess
both invents phantom conflicts and misses real ones. A pre-flight check also
halts on conflicts left live by an earlier halted sync, which Dolt otherwise
refuses to merge over with an opaque transport error.
- A conflict sync cannot settle is NEVER resolved by picking a side: it halts
before recomputing or pushing, with no --strategy-style override. A timer
that silently picks a side loses work on a schedule. The halt message
reports whether the conflict rows are live or were aborted away, read from
WHICH detection source fired rather than assumed — the SQL pull route aborts
and restores the working set, the CLI/git-protocol route deliberately leaves
the rows live, and an operator told the wrong one looks in the wrong place.
- The is_blocked recompute runs unconditionally, on every attempt. That is
deliberate and load-bearing: RecomputeAllBlocked is specifically the repair
that does NOT depend on a merge advancing HEAD (bd-6dnrw.37), so it is what
recovers a column left stale by a conflicted pull an operator resolved by
hand — a state this verb manufactures itself by exiting 2. Gating it on "did
this tick merge anything" re-imposes the condition it exists to escape, and
from then on no tick merges anything, so the repair would never run again
while every tick reported success. HEAD is the wrong instrument for that
question anyway: the pull's own pre-merge auto-commit (GH#2474) moves it for
purely local dirty state, and an auto-resolved merge can land in the working
set without moving it at all (bd-6dnrw.39).
Exit codes are the machine contract so a timer can branch without parsing
output: 0 synced, 1 error, 2 merge conflict (halted, nothing pushed), 3
push-race retries exhausted (transient). --json reports the same outcome.
Push-race classification is deliberately narrow — race signatures (behind /
non-fast-forward / a lost --force-with-lease: stale info, fetch first, "contains
work that you do not have"), not the word "rejected". A protected branch or a
declining pre-receive hook also rejects, permanently; treating that as a race
burns the whole attempt budget every tick and reports exit 3 ("retry next tick")
forever instead of surfacing the failure.
Also: hasNoRemoteConfigured split out of isConfirmedNoRemote so sync can reuse
the structural no-remote proof with its own (broader) error hint without
loosening it — a solo rig must not fail every tick, but a typoed or broken
remote must still exit non-zero. The command doc and the doc-flags gate are
updated: `bd sync` is live again, so the stale reference to hunt is docs still
calling it removed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>