fix(backup): point the size-cap pause advice at levers that end it (#7074)

The PAUSED warning, the `bd backup status` PAUSED line, CHANGELOG and
configuration.md told operators to switch to a fresh destination with
`bd backup init <new-path>`. That never ends the pause: backupDir()
reads only backup.git-repo, while `bd backup init` registers the
separate destination that manual `bd backup sync` pushes to, so
auto-backup keeps targeting the over-cap directory and stays paused.

Name the two levers that do end it: raise backup.size-cap-mb, or point
backup.git-repo at a different git repository. Also correct the
backup.git-repo row in configuration.md, which called it a repo URL
although backupDir() requires a local path containing .git (anything
else falls back to .beads/backup/), so the new advice is actionable.

TestPauseAutoBackupForSizeCap_RemediationAdvice and the status PAUSED
line now require backup.git-repo and reject `bd backup init`.
TestMaybeAutoBackup_RemediationLevers runs all three for real: raising
the cap and switching backup.git-repo each resume a sync, while
`bd backup init` leaves auto-backup paused.

Post-merge review follow-up to #6071.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR

Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Julian Knutsen 2026-10-01 08:05:46 -07:00 • committed by GitHub
commit 8adcd25992
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 183 additions and 11 deletions

View file

@ -182,7 +182,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
advice no longer suggests deleting the backup directory — nothing
guarantees a deleted destination is cleanly recreated by the next sync, and
the server-side backup remote stays registered against that path; it now
points at `backup.size-cap-mb` / `bd backup init <new-path>` instead. The
points at raising `backup.size-cap-mb` or pointing `backup.git-repo` at a
different git repository instead — not `bd backup init`, which configures
manual `bd backup sync`'s destination and leaves auto-backup paused. The
size-cap check itself runs after both the interval throttle and change
detection, so it costs nothing on any path that is not about to sync — an
idle workspace never reaches it at all, and a paused destination re-arms

View file

@ -95,8 +95,10 @@ func showSizeCapStatus(dir string) {
}
capBytes := int64(capMB) * 1024 * 1024
if size >= capBytes {
// Same two levers as pauseAutoBackupForSizeCap's warning — see
// there for why `bd backup init` is not one of them.
fmt.Printf(" Size cap: PAUSED (cap exceeded) — %s / %s. Raise backup.size-cap-mb "+
"or run `bd backup init <new-path>` to switch destinations.\n",
"or point backup.git-repo at a different git repository to switch destinations.\n",
formatBytes(size), formatBytes(capBytes))
return
}
@ -183,6 +185,14 @@ func warnBackupSizeCapUnavailable(err error) {
// human-visible warning could effectively never fire; those callers have
// `bd backup status --json`'s size_cap field instead.
//
// The advice names only the levers that end the pause: raising the cap, or
// pointing backup.git-repo — the only setting backupDir() reads — at another
// repository, whose backup/ directory carries none of this one's size or
// throttle state. `bd backup init` registers the separate destination that
// manual `bd backup sync` pushes to; auto-backup still targets this
// directory afterwards, so it would stay paused (PR #6071 post-merge
// review).
//
// Never returns an error: a failure to persist must not block the
// (already-decided) skip of the backup attempt itself.
func pauseAutoBackupForSizeCap(dir string, state *backupState, size int64) {
@ -208,7 +218,8 @@ func pauseAutoBackupForSizeCap(dir string, state *backupState, size int64) {
fmt.Fprintf(os.Stderr,
"Warning: auto-backup PAUSED — destination %s has reached %s. "+
"No further syncs will run until you raise backup.size-cap-mb "+
"or switch to a fresh destination with `bd backup init <new-path>`.\n",
"or point backup.git-repo at a different git repository "+
"(auto-backup then syncs to a backup/ directory inside it).\n",
dir, formatBytes(size))
debug.Logf("backup: size cap exceeded (%s), auto-backup paused\n", formatBytes(size))
return

View file

@ -260,8 +260,12 @@ func TestBackupSizeCapExceeded_DisabledWithZero(t *testing.T) {
// fix: the warning must not tell operators to delete the backup directory
// — nothing confirms the destination is cleanly recreated by the next
// sync, and Dolt's server-side backup remote stays registered against that
// path. It should point at the safe levers instead: raising the cap, or a
// fresh destination via `bd backup init`.
// path. It should point at the levers that end the pause instead: raising
// the cap, or pointing backup.git-repo at another repository. It must not
// point at `bd backup init`, which the original fix suggested (PR #6071
// post-merge review): that configures the destination for manual `bd backup
// sync` and leaves auto-backup paused — see
// TestMaybeAutoBackup_RemediationLevers for all three, run for real.
func TestPauseAutoBackupForSizeCap_RemediationAdvice(t *testing.T) {
t.Chdir(t.TempDir())
t.Setenv("BEADS_DIR", "")
@ -285,8 +289,11 @@ func TestPauseAutoBackupForSizeCap_RemediationAdvice(t *testing.T) {
if !strings.Contains(stderr, "backup.size-cap-mb") {
t.Errorf("warning missing backup.size-cap-mb pointer: %q", stderr)
}
if !strings.Contains(stderr, "bd backup init") {
t.Errorf("warning missing `bd backup init <new-path>` pointer: %q", stderr)
if !strings.Contains(stderr, "backup.git-repo") {
t.Errorf("warning missing backup.git-repo pointer: %q", stderr)
}
if strings.Contains(stderr, "bd backup init") {
t.Errorf("warning points at `bd backup init`, which does not move the auto-backup destination: %q", stderr)
}
}
@ -547,6 +554,142 @@ func TestMaybeAutoBackup_PausedSkipArmsIntervalThrottle(t *testing.T) {
}
}
// dirRecordingBackupStore records the destination of every backup, so a
// test can tell a sync into the paused destination from one into a new one.
type dirRecordingBackupStore struct {
failingBackupStore
dirs []string
}
func (f *dirRecordingBackupStore) BackupDatabase(ctx context.Context, dir string) error {
f.dirs = append(f.dirs, dir)
return f.failingBackupStore.BackupDatabase(ctx, dir)
}
// TestMaybeAutoBackup_RemediationLevers runs the PAUSED advice for real
// (PR #6071 post-merge review): each lever it names must resume
// auto-backup, and `bd backup init <new-path>`, which it used to name, must
// not. backupDir() reads only backup.git-repo, so the destination init
// configures for manual `bd backup sync` never reaches auto-backup.
func TestMaybeAutoBackup_RemediationLevers(t *testing.T) {
// paused returns an over-cap destination whose pause has already been
// recorded, and the fake store a resumed sync would reach.
paused := func(t *testing.T) (string, *dirRecordingBackupStore) {
t.Helper()
t.Chdir(t.TempDir())
// A resumed sync takes the workspace-scoped backup lock, so the
// command needs a real workspace.
prepareBackupStatusTest(t)
repo := t.TempDir()
if err := os.MkdirAll(filepath.Join(repo, ".git"), 0o755); err != nil {
t.Fatal(err)
}
t.Setenv("BD_GIT_HOOK", "")
t.Setenv("BD_BACKUP_GIT_REPO", repo)
t.Setenv("BD_BACKUP_ENABLED", "1")
t.Setenv("BD_BACKUP_SIZE_CAP_MB", "1")
initConfigForTest(t)
dir, err := backupDir()
if err != nil {
t.Fatalf("backupDir: %v", err)
}
if err := os.WriteFile(filepath.Join(dir, "filler"), make([]byte, 2*1024*1024), 0o600); err != nil {
t.Fatal(err)
}
seeded := &backupState{Timestamp: time.Now().UTC().Add(-time.Hour), LastDoltCommit: "oldcommit"}
if err := saveBackupState(dir, seeded); err != nil {
t.Fatal(err)
}
oldStore := store
fake := &dirRecordingBackupStore{failingBackupStore: failingBackupStore{commit: "deadbeef"}}
store = fake
t.Cleanup(func() { store = oldStore })
stderr := captureStderr(t, func() { maybeAutoBackup(context.Background()) })
if !strings.Contains(stderr, "auto-backup PAUSED") || len(fake.dirs) != 0 {
t.Fatalf("auto-backup did not pause (synced to %q), so this test proves nothing: %q", fake.dirs, stderr)
}
return dir, fake
}
// rewindThrottle stands in for waiting out backup.interval, which the
// pause re-armed: a lever applied to the same destination takes effect
// at its next eligible sync, not on the very next command.
rewindThrottle := func(t *testing.T, dir string) time.Time {
t.Helper()
st, err := loadBackupState(dir)
if err != nil {
t.Fatalf("loadBackupState: %v", err)
}
st.Timestamp = time.Now().UTC().Add(-time.Hour)
if err := saveBackupState(dir, st); err != nil {
t.Fatal(err)
}
return st.Timestamp
}
t.Run("raise backup.size-cap-mb", func(t *testing.T) {
dir, fake := paused(t)
t.Setenv("BD_BACKUP_SIZE_CAP_MB", "10")
initConfigForTest(t)
rewindThrottle(t, dir)
maybeAutoBackup(context.Background())
if len(fake.dirs) != 1 || fake.dirs[0] != dir {
t.Errorf("synced to %q after raising the cap, want one sync to %q", fake.dirs, dir)
}
})
t.Run("point backup.git-repo at a different git repository", func(t *testing.T) {
_, fake := paused(t)
other := t.TempDir()
if err := os.MkdirAll(filepath.Join(other, ".git"), 0o755); err != nil {
t.Fatal(err)
}
t.Setenv("BD_BACKUP_GIT_REPO", other)
initConfigForTest(t)
// No rewind: the new destination has no throttle state of its own.
maybeAutoBackup(context.Background())
want := filepath.Join(other, "backup")
if len(fake.dirs) != 1 || fake.dirs[0] != want {
t.Errorf("synced to %q after switching backup.git-repo, want one sync to %q", fake.dirs, want)
}
})
t.Run("bd backup init leaves auto-backup paused", func(t *testing.T) {
dir, fake := paused(t)
oldCtx, oldWrote := rootCtx, commandDidWrite.Load()
rootCtx = context.Background()
t.Cleanup(func() {
rootCtx = oldCtx
commandDidWrite.Store(oldWrote)
})
stdout := captureStdout(t, func() error {
return backupInitCmd.RunE(backupInitCmd, []string{t.TempDir()})
})
if !strings.Contains(stdout, "Backup destination configured") {
t.Fatalf("`bd backup init` did not configure a destination, so this test proves nothing: %q", stdout)
}
rewound := rewindThrottle(t, dir)
maybeAutoBackup(context.Background())
if len(fake.dirs) != 0 {
t.Fatalf("synced to %q after `bd backup init`, want auto-backup still paused", fake.dirs)
}
st, err := loadBackupState(dir)
if err != nil {
t.Fatalf("loadBackupState: %v", err)
}
if !st.Timestamp.After(rewound) {
t.Errorf("timestamp = %v, want it re-armed past %v by the size-cap skip: the cap check never ran, so this proves nothing",
st.Timestamp, rewound)
}
})
}
// TestWarnBackupSizeCapUnavailable_IsOperatorVisible pins the PR #6071
// review's error-handling minor: getDirSize aborts its whole walk on the
// first unreadable entry, and maybeAutoBackup then proceeds UNCAPPED. That

View file

@ -228,8 +228,24 @@ func TestBackupStatusShowsSizeCapPaused(t *testing.T) {
if stderr != "" {
t.Errorf("stderr = %q, want empty", stderr)
}
if !strings.Contains(stdout, "PAUSED (cap exceeded)") {
t.Errorf("status text missing PAUSED indicator: %s", stdout)
var pausedLine string
for _, line := range strings.Split(stdout, "\n") {
if strings.Contains(line, "PAUSED (cap exceeded)") {
pausedLine = line
}
}
if pausedLine == "" {
t.Fatalf("status text missing PAUSED indicator: %s", stdout)
}
// Same levers as the pause warning — see
// TestPauseAutoBackupForSizeCap_RemediationAdvice.
for _, want := range []string{"backup.size-cap-mb", "backup.git-repo"} {
if !strings.Contains(pausedLine, want) {
t.Errorf("PAUSED line missing %s pointer: %q", want, pausedLine)
}
}
if strings.Contains(pausedLine, "bd backup init") {
t.Errorf("PAUSED line points at `bd backup init`, which does not move the auto-backup destination: %q", pausedLine)
}
})
}

View file

@ -125,7 +125,7 @@ Any key whose name contains `api_key`, `api-key`, `secret`, `token`, or `passwor
| `backup.enabled` | — | `BD_BACKUP_ENABLED` | `false` | Enable periodic Dolt-native backup to `.beads/backup/` (see [below](#auto-backup)) |
| `backup.interval` | — | `BD_BACKUP_INTERVAL` | `15m` | Minimum time between auto-backups |
| `backup.git-push` | — | — | `false` | Auto-push backup repo |
| `backup.git-repo` | — | `BD_BACKUP_GIT_REPO` | (none) | Backup git repo URL; when set, backups go to a `backup/` directory inside that repo |
| `backup.git-repo` | — | `BD_BACKUP_GIT_REPO` | (none) | Path to a local git repository (`~/` expands); when set, auto-backup syncs to a `backup/` directory inside it. A path without `.git` falls back to `.beads/backup/` with a warning |
| `backup.size-cap-mb` | — | `BD_BACKUP_SIZE_CAP_MB` | `2048` | Pause auto-backup once the destination directory reaches this size; `0` disables the cap (see [below](#auto-backup)) |
| `backup.size-warn-interval` | — | `BD_BACKUP_SIZE_WARN_INTERVAL` | `24h` | Minimum time between repeated "auto-backup paused" warnings |
| `audit.enabled` | — | `BD_AUDIT_ENABLED` | `false` | Enable the optional JSONL interaction sidecar at `.beads/interactions.jsonl`, written by `bd audit record` / `bd audit label`. While disabled, `bd init` does not create the file and `bd audit record` / `bd audit label` refuse to write. Issue history is always recorded in the database either way — see `bd history <id> --events` |
@ -235,7 +235,7 @@ backup:
How it works:
- After each write command, `bd` compares the Dolt HEAD commit hash against the last backup state.
- If data changed and the throttle interval has passed, `bd` checks the destination directory's on-disk size against `backup.size-cap-mb`. `CALL DOLT_BACKUP('sync', ...)` only ever adds new chunks to the destination — it never prunes ones that became unreachable on the source (history rewrites, superseded data), and Dolt exposes no supported way to GC a backup destination in place. Left uncapped, the destination can only grow until disk fills; this was the root cause of a 2026-06-19 outage where a 1.7GB store produced a 43GB backup directory. Once the cap is reached, auto-backup pauses — nothing is deleted, but no further syncs run until you raise `backup.size-cap-mb` or point to a fresh destination with `bd backup init <new-path>`. Set `size-cap-mb: 0` to disable the cap entirely.
- If data changed and the throttle interval has passed, `bd` checks the destination directory's on-disk size against `backup.size-cap-mb`. `CALL DOLT_BACKUP('sync', ...)` only ever adds new chunks to the destination — it never prunes ones that became unreachable on the source (history rewrites, superseded data), and Dolt exposes no supported way to GC a backup destination in place. Left uncapped, the destination can only grow until disk fills; this was the root cause of a 2026-06-19 outage where a 1.7GB store produced a 43GB backup directory. Once the cap is reached, auto-backup pauses — nothing is deleted, but no further syncs run until you raise `backup.size-cap-mb` or point `backup.git-repo` at a different git repository, whose `backup/` directory then becomes the destination. `bd backup init` does not end the pause: it configures the separate destination that manual `bd backup sync` pushes to. Set `size-cap-mb: 0` to disable the cap entirely.
- If the destination is under its cap, a Dolt-native backup is synced to `.beads/backup/` (or to a `backup/` directory inside `backup.git-repo` when configured).
- State is tracked in `backup_state.json` inside the backup directory. `bd backup status` prints `PAUSED (cap exceeded)` when the destination is over its cap, and its `--json` output reports the same state as `size_cap.exceeded: true` — so an agent/CI caller relying on `--json` or `--quiet` can see that auto-backup has stopped instead of reading a reassuring "Last backup" line while nothing further syncs.
- The cap applies only to auto-backup; manual `bd backup` / `bd backup sync` are not capped.