* feat(remember): opt-in memories.budget-chars — refuse a write that crosses the corpus budget (wy-2pox7y)
The wheelhouse-side tripwire only REPORTS the memory-corpus size, so the corpus
re-trips red every few days and nothing has ever stopped the write that crossed
the line. This is the stop.
New config key `memories.budget-chars` (integer, default 0 = OFF), wired exactly
like `prime.max-memory-chars`: recognized in cmd/bd/config.go, routed to yaml in
internal/config YamlOnlyKeys (it is read through viper, so a DB-backed write
would be accepted and then never read), validated non-negative at set time, and
documented in docs/reference/configuration.md.
With the budget ON, `bd remember` measures the corpus as the sum over every
memory of len(key)+len(content) — BYTES, the same unit `bd prime`'s
--max-memory-chars counts in — projected to AFTER the write would apply. An
overwrite replaces that key's old content in the sum rather than adding to it,
so a memory near the ceiling can still be edited.
- over budget -> refused, nothing written, exit 1, one line on stderr
- over budget + --force -> written, and the crossing is still announced
- >= 80% and within -> written, then warned
- below 80%, or budget 0 -> silent; with the budget off the corpus is not even
read, so behavior is byte-identical to before
Every line goes to STDERR, so --json output is never corrupted; a --json refusal
additionally gets the normal machine-readable error object on stdout.
The whole decision is one pure function (rememberBudgetVerdict), which is what
lets the branches be pinned without a database.
Tests run (targeted, never ./...):
go build ./... rc 0
go vet ./cmd/bd/ ./internal/config/ rc 0
go test ./cmd/bd/ -run 'Memor|Remember|Prime|Budget' -count=1 rc 0
go test ./internal/config/ -count=1 rc 0
BEADS_TEST_EMBEDDED_DOLT=1 go test ./cmd/bd/ \
-run TestEmbeddedMemoryCorpusBudget -count=1 -v rc 0 (6/6 subtests)
golangci-lint run --config=.golangci.yml --build-tags=gms_pure_go \
./cmd/bd/... ./internal/config/... 0 issues in touched
files (one
pre-existing gosec
G304 in
internal/config/permissions_open_nonlinux.go)
New tests: cmd/bd/memory_budget_pure_test.go (byte unit incl. multibyte,
overwrite delta, budget-off silence, config read + negative clamp, the
at-budget/one-over boundary, --force, the 80% warn band and its edges,
unclamped percentage, single-line contract);
cmd/bd/memory_embedded_test.go TestEmbeddedMemoryCorpusBudget (the same five
spec points end to end against a real embedded-Dolt store, through
`bd config set`, asserting the exact stderr lines, the nonzero exit, and that a
refused write leaves the old content intact);
internal/config/yaml_config_test.go validation + yaml-only routing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013XmKxqKuXTaKivDiCoBwBV
* fix(remember): one --json refusal line, ceil on the over-budget percentage (wy-2pox7y)
Review fixes on ca9f14d65d. Three items; one review item turned out to be a
false alarm and is recorded here rather than acted on.
- BLOCKER 1 (CLI docs regeneration) — NO CHANGE NEEDED, and that is the
finding. docs/cli-reference/ and docs/CLI_REFERENCE.md are not generated
from this checkout: docs/cli-docs.pin pins them to release tag v1.2.2, and
scripts/generate-cli-docs.sh, check-cli-docs-drift.sh and check-doc-flags.sh
all resolve that pin (resolve-docs-bd.sh) and build bd from the TAG, because
the published docs site describes the latest release, not main's source. No
CI path sets BD_DOCS_IGNORE_PIN. So changing `bd remember`'s help surface on
main cannot move the generated docs, and it did not:
./scripts/generate-cli-docs.sh ran to completion ("Generated CLI docs from:
bd version 1.2.2 (dev)") and left the tree clean — zero diff. The gate is
green at this commit and was green at ca9f14d65d. The --force flag and the
Corpus budget paragraph reach the docs when the pin is bumped at release.
- NIT 1: the --json refusal said the same sentence twice, prose on stderr AND
the envelope on stdout. It now says it ONCE, the way
HandleErrorWithHintRespectJSON does it: --json gets only the stdout
envelope, every other route gets the bare sentence on stderr. New subtest
TestEmbeddedMemoryCorpusBudget/json_refusal_is_said_once asserts a nonzero
exit, EXACTLY one JSON document on stdout (a second Decode must be io.EOF),
the refusal sentence inside the envelope, a stderr with no "memory corpus"
in it, and that the refused write left the old content intact.
- NIT 2: floor arithmetic made the refusal at 201 of 200 read "(100%)" — the
exactly-at-budget value this code deliberately ALLOWS, so the refusal wore
the number of the case it is not. The percentage now CEILINGS over the
budget (101%) and still FLOORS within it. The split is on the VALUE, not on
--force, so one projection cannot report two different percentages
depending on a flag; that is why the forced over-budget line moved too.
TestRememberBudgetVerdictBoundary, TestRememberBudgetVerdictForceWrites and
TestMemoryBudgetLinePercentIsUnclamped updated; the warn band gains a
999-of-1000 case pinning the floor inside the budget, so "100%" can only
ever mean at-budget.
- NIT 5: one comment at the List/Remember seam saying the budget is ADVISORY
and not atomic — the two are separate transactions, so concurrent writers
can both measure inside the budget and both land. No locking.
Nits 3 (primeConfigInt duplication) and 4 were left alone by instruction.
Gates run from the worktree:
go build ./... rc 0
go vet ./cmd/bd/ ./internal/config/ rc 0
go test ./cmd/bd/ -run 'Memor|Remember|Prime|Budget' -count=1 rc 0
go test ./internal/config/ -count=1 rc 0
BEADS_TEST_EMBEDDED_DOLT=1 go test ./cmd/bd/ \
-run TestEmbeddedMemoryCorpusBudget -count=1 -v rc 0 (7/7)
gofmt -l cmd/bd internal/config no output
golangci-lint run ./cmd/bd/ ./internal/config/ 1 issue, all
pre-existing: gosec G304 in internal/config/permissions_open_nonlinux.go
(last touched f4d496fed, not by this branch)
./scripts/check-cli-docs-drift.sh rc 0
./scripts/check-doc-flags.sh rc 0
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JFSKdUYCTyuhBM97tHyoye
* ci: list the PR's tests in the embedded shard manifest and cmd/bd BUILD.bazel
#7156 made the embedded-Dolt shard manifests exact-once, and Bazel equivalence
requires every test file in the go_test srcs. Adds TestEmbeddedMemoryCorpusBudget
(generator output, incremental) and memory_budget_pure_test.go (the line CI's
bazel-sync patch printed).
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* fix(remember): budget the key ResolveKey writes; hint on stderr too
Review fixes for #6508 (apply-fixes iteration 1; all minor or nit):
- The budget credits an overwrite under memoryapi.ResolveKey's key, the
one rule every Remember implementation writes under, instead of a
parallel flag-else-derived copy of it. A write ResolveKey refuses
skips the budget, so a whitespace-only --key gets the role's "memory
key must not be empty" instead of an over-budget refusal that points
at --force.
- The stderr refusal now carries the same hint as the --json envelope
(raise the budget, forget a memory, or --force), printed the way
HandleErrorWithHintRespectJSON prints one.
- The memoryCorpusChars comment and `bd remember --help` no longer
imply that a budget equal to prime.max-memory-chars keeps prime from
eliding memories: the unit (bytes) is the same, but prime counts each
memory as rendered, markup included, so the budget has to sit below
that cap for that.
- New embedded pins: a write without --key that crosses the budget is
refused with exit 1 and writes nothing; a blank --key gets the
validation error; the Hint line is on stderr and not under --json.
Each pin was checked red against a mutant of the code it guards.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
* fix(gate): ordinary commands wait out maintenance, with writer fairness
Ordinary bd commands take the workspace (and physical-root) gate SHARED and
never waited for it, so while another process held it EXCLUSIVELY — bd init
(~8s), backup restore, migrate, bootstrap — they failed at once with "a
maintenance operation is running". In shared-server mode every project
shares one physical-root gate, so another project's bd init broke every bd
command on the machine for its duration.
Ordinary commands now wait:
- up to 15s by default; BEADS_GATE_WAIT_TIMEOUT (Go duration or bare
seconds, same convention as BEADS_INIT_GATE_TIMEOUT) overrides it, and 0
restores fail-fast;
- one "waiting for another bd process ..." notice after 2s (shared with bd
init's notice);
- Ctrl-C aborts the wait. A canceled wait used to fall through to the
shared fail-open path ("continuing ungated"); it is now a hard error;
- past the bound, the same error naming the holder, the wait, and the knob.
Git hooks stay fail-fast: `bd hooks run` and the bd export/import children
the hooks spawn run with BD_GIT_HOOK=1, treat failure as a warning, and must
not stall a commit or checkout for 15s.
Writer fairness (internal/workspacegate). flock/LockFileEx give no queueing,
and acquisition is non-blocking polling, so a steady stream of overlapping
shared holders could keep a waiting exclusive acquirer (bd init) out past
its bound. A per-gate intent lock (<gate>.intent) fixes that: a waiting
exclusive acquirer whose first try is busy takes the intent lock
exclusively while it polls, and waiting shared acquirers probe it before
every attempt and wait while it is held. The exclusive waiter then waits
only for in-flight holders to drain. The intent is an OS lock, so a crashed
waiter's intent dies with it; its advisory sidecar is ignored when the lock
is free, and intent-lock errors other than "busy" degrade to the old
behavior. Fail-fast acquisitions (Wait <= 0) ignore the queue entirely, so
hooks and BEADS_GATE_WAIT_TIMEOUT=0 behave exactly as before. The intent
lock is taken only while acquiring its gate, directly before it in
AcquireAll's sorted order, so it adds no lock-order cycles.
Nested bd (bd orphans running bd close, hooks fired by git that bd runs)
would deadlock against the queue: the child queues behind an exclusive
waiter that is waiting for the child's parent. A bd process holding its
gates shared exports BEADS_GATE_SHARED_HOLDER_PID; a child whose recorded
ancestor is alive skips the queue (it cannot help the waiter anyway).
Tests: workspacegate fairness (a continuous shared stream no longer starves
an exclusive waiter; verified to fail without the queue), intent lifecycle,
stale intent from a SIGKILLed process, cancellation while queued,
InheritedSharedHold. cmd/bd: holder released after ~3s lets a command
through with one notice; past-bound error text; fail-fast modes (0, hooks);
Ctrl-C is not fail-open; a new command queues behind a waiting bd init
while a child of a shared holder does not; env parsing.
TestSharedServerConcurrent runs a late bd init of a new project during the
client workloads, so both directions are exercised against a real server.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(gate): a queued exclusive waiter may delay shared commands, never fail them
Review follow-up (B1). A doomed exclusive waiter — bd init or restore
blocked behind a long-lived shared holder such as `bd list --watch`,
`bd events tail --follow`, an open `bd edit` editor, or a beads.OpenGated
embedder — held the writer-fairness intent lock for its whole budget, so
every NEW ordinary command deferred to it and failed with "queued for
exclusive access" even though nothing held the gate exclusively. Before
the fairness change those commands ran normally.
Two bounds fix it while keeping the fairness win:
- An exclusive waiter drops the intent lock after maxIntentHold (10s)
without getting the gate and keeps polling unqueued. In-flight ordinary
commands drain far faster than that.
- The final attempt of a waiting shared acquisition tries the gate even
while intent is held, so a shared acquisition fails only when the gate
itself is held exclusively.
With the final attempt ignoring intent, AcquireAll's 1ns floor for an
exhausted budget is dead code (a Wait-0 attempt behaves the same), so it is
back to 0. queuedDetail drops an intent sidecar left by a dead process (on
Windows its removal can fail while another process is reading it).
Tests: the doomed-waiter scenario (both bounds; each fails with its bound
removed), intent lock order across a two-gate set in both directions, an
exhausted AcquireAll budget, two exclusive waiters handing off the intent,
and BEADS_GATE_SHARED_HOLDER_PID inherited through a real subprocess.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(gate): 30s shared wait, 60s init wait, accurate errors, hook pinning
Review follow-ups for the shared gate wait (S1-S5 and nits), on top of the
workspacegate fix that keeps a queued exclusive waiter from failing
ordinary commands.
- Ordinary commands wait up to 30s by default (was 15s). Queued
maintenance operations run one after another (two inits fanned out
across shared-server projects hold the gate back to back, 10-15s each
under load) and a waiting command waits for all of them. Documented in
configuration.md and CHANGELOG, including BEADS_GATE_WAIT_TIMEOUT=0 for
scripts that relied on fail-fast.
- bd init waits up to 60s by default (was 30s). Safe only now that a
waiting init stops queueing others after 10s.
- Error text: a shared acquisition now fails only when the gate is held
exclusively, so "running" is accurate; in shared-server mode it says
"the shared server (possibly from another project)", and the detail
still names the holder when known.
- hooks.go: the hookSubprocessEnv / bd import comments listed BD_GIT_HOOK's
consumers without the gate wait, which now reads it to stay fail-fast.
TestHookSubprocessEnvKeepsGateFailFast pins that hook subprocesses carry
it and therefore never wait on the gate.
- bd edit's $EDITOR (which can outlive bd by hours) no longer inherits
BEADS_GATE_SHARED_HOLDER_PID.
- Test hygiene: the cmd/bd test binary never advertises the marker
(in-process command tests run beside tests that spawn bd) and clears any
inherited one in TestMain; the notice-delay test runs in 1s, not 3s.
- TestSharedServerConcurrent's late init keeps a 30s bound so the 60s
default cannot mask a fairness regression.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
In shared-server mode every project's physical root is the one shared dolt
data dir, and bd init holds that dir's gate EXCLUSIVELY for its whole run
(~8s). It waited only exclusiveGateWait (5s) for it, so two concurrent
`bd init --shared-server` runs in different projects, or an init during
another project's long command, failed with "bd init refuses to run over
live bd activity".
acquireInitMutationGate now uses its own acquisition options:
- Wait: 30s by default, overridable with BEADS_INIT_GATE_TIMEOUT (Go
duration or bare seconds, same convention as BEADS_PRIME_TIMEOUT and
BEADS_FSCK_TIMEOUT); ctx cancellation still aborts the wait.
- One stderr notice ("waiting for another bd process on the shared
server (...)...") once the wait passes 2s, instead of immediately.
- Past the bound, the same refusal, now naming the budget and the knob.
Exclusivity is unchanged. The 5s exclusiveGateWait is also used by
backup restore, bootstrap, migrate and the backup lock; those keep it, so
the change is scoped to init via acquireExclusiveWorkspaceGatesWithOptions.
TestSharedServerConcurrent goes back to fully concurrent inits (manual runs
with many dirs raise BEADS_INIT_GATE_TIMEOUT to match). New unit tests: a
holder released after 6s lets init through with one notice; a holder past
the bound gives the clear ErrBusy error; cancellation; env parsing.
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
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>
* fix(bd): cap auto-backup destination size to stop unbounded growth (ga-y6gjv)
ga-y6gjv asked for 4 fixes to bd's auto-backup subsystem. Three are already
merged and deployed (verified via git merge-base --is-ancestor against the
commit that built the currently-deployed ~/.local/bin/bd):
- interval throttle persists on failure too, per-workspace: 5f685959c
- default-off in sql-server/shared mode: 5f685959c, refined by 8b9429153
- `bd config get backup.enabled` reports the effective value: 5f685959c
This commit is only the fourth, still-open item: "prune/cap backup
archives." BackupSync/CALL DOLT_BACKUP('sync', ...) only ever transfers new
chunks into the destination — it never prunes ones that became unreachable
on the source DB (history rewrites, superseded data) — so even with the
interval fix slowing the frequency of syncs, the destination can still only
grow, never shrink. This was the actual disk-filling mechanism in the
2026-06-19 outage (43GB backup dir from a 1.7GB store).
I first tried wiring `dolt gc` into the post-sync path (mirroring
runCompactDolt's exec.Command("dolt", "gc", ...) pattern in compact.go).
That does not work: a backup destination is a bare Dolt chunk-store
directory with no .dolt repo-root marker, so the standalone dolt CLI can't
open it ("not a valid dolt repository") no matter what its working
directory is set to, and dolt_backup.go's SQL procedures only expose
add/sync/restore — never gc — for a backup destination. Confirmed this
empirically (a real dolt gc attempt against a real backup dir, outside any
test) before shipping anything, not just reasoned about it.
Given no supported way to prune a backup destination in place, this adds a
hard size cap instead: once the destination exceeds backup.size-cap-mb
(default 2048MB), maybeAutoBackup skips the sync attempt entirely rather
than letting it grow further, and prints a throttled warning
(backup.size-warn-interval, default 24h) telling the operator to free space
or raise the cap. This directly bounds the failure mode that caused the
outage — unbounded growth — without risking any operation against the
backup store's on-disk format.
Tests (cmd/bd/backup_cap_test.go): threshold check against a real
directory, warning-throttle persistence (mirrors the existing throttle
persisted on backup failure, backup_export.go), and end-to-end proof that
maybeAutoBackup never attempts BackupDatabase once capped. Confirmed each
new test fails against the pre-fix code (wiring temporarily reverted,
re-verified, restored) before treating it as green.
Verified: go build ./... clean, gofmt clean, go vet clean, full
cmd/bd + internal/config test run green (backup/config-focused subset run
with -v; no regressions in the wider package test runs either).
* fix(bd): address PR #6071 review feedback on backup size-cap (ga-y6gjv)
bee-ghosttrack's 2026-09-03 review of the size-cap fix (3d27d7a98) requested
changes before merge -- 4 major, 2 minor, all about the pause being
invisible rather than the cap mechanism itself. This addresses all six.
Major:
1. backup.size-cap-mb: 0 now means "no cap", not "use the 2048MB default."
effectiveSizeCapMB() centralizes the <=0-is-disabled interpretation;
backupSizeCapExceeded and the new status helpers all go through it.
Viper already registers a 2048 default for this key
(internal/config/config.go), so GetInt only returns <=0 when the
operator explicitly set 0 (or an unparseable value) -- the old code's
own `if capMB <= 0 { capMB = 2048 }` was silently overriding that
explicit choice, leaving no off switch for a legitimately larger
destination.
2. `bd backup status` (and --json) now report a `size_cap` object
(enabled, cap_mb, current_bytes, exceeded), and the human-text Config:
line grows a "Size cap: PAUSED (cap exceeded) -- X / Y..." line when
paused. Previously the pause was stderr-only and throttled to 24h, so
an agent/CI caller on --json or --quiet had no way to see that
auto-backup had silently and permanently stopped syncing.
3. The remediation message no longer says "delete the backup directory."
Nothing in this codebase demonstrates a deleted destination is cleanly
recreated by the next sync (the server-side Dolt backup remote stays
registered against that path), and following the old advice would
leave a zero-backup window while the next sync is itself
interval-throttled. It now points at backup.size-cap-mb / `bd backup
init <new-path>`.
4. docs/reference/configuration.md gains rows for both new keys plus an
expanded Auto-backup section (the cap mechanism, the pause, manual
backup staying uncapped, bd backup status reporting the pause);
CHANGELOG.md gets an [Unreleased]/Fixed entry referencing #6071.
Minor:
5. maybeWarnBackupSizeCap's throttle timestamp is now also cached in an
in-process map (capWarnFallback, keyed by dir) alongside the persisted
backup_state.json. The persist write targets the directory the cap
just declared full, so in the disk-full case this cap exists for, that
write fails and the timestamp never sticks -- a long-lived bd process
that keeps calling maybeAutoBackup for the same destination (e.g.
internal/storage/dbproxy's server mode) would otherwise re-warn on
every single call. The map is keyed by dir specifically so unrelated
destinations -- and unrelated tests -- never share a throttle.
6. The size-cap directory walk (getDirSize's filepath.Walk) now runs
after the interval throttle in maybeAutoBackup, not before. The
reviewer measured 65-100ms per bd invocation at 20k files in the
backup dir when the walk ran unconditionally on every command; moving
it below the throttle makes it free on the common (throttled) path and
only pays the walk cost once per interval, exactly when a sync attempt
would occur anyway.
Also noted by the reviewer: manual `bd backup` / `bd backup sync` stay
uncapped -- now documented in configuration.md.
Tests (cmd/bd/backup_cap_test.go, cmd/bd/backup_status_test.go): one new
test per review point. Each was confirmed to fail against the pre-fix code
for the expected reason before implementing -- including catching a
vacuous pass in my own first draft of the "disabled cap" JSON assertion
(zero-value Enabled:false matched whether the size_cap key existed at all
or not; fixed to assert key presence first). The disabled-cap test uses a
sparse file (Truncate, not a real write) to cross the legacy 2048MB
threshold without allocating 2GB of real disk or memory. The reordering
test is detected indirectly: if the cap check ran despite the throttle, it
would persist LastCapWarnAt; the interval-fresh case proves it does not.
Verified: go build ./cmd/bd/... clean, gofmt clean, go vet ./cmd/bd/...
clean, golangci-lint run ./cmd/bd/... -> 0 issues, targeted backup/status
test subset green (20/20, including every pre-existing backup test -- no
regressions).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(bazel): add backup_cap sources to //cmd/bd srcs lists
The contributor branched before `cmd/bd/BUILD.bazel` existed, so the two
files this PR adds were never enumerated there. After rebasing onto a base
that hand-maintains explicit srcs lists, `//cmd/bd:bd_lib` omits
`backup_cap.go` while still compiling `backup.go` and `backup_auto.go`,
which reference four symbols it defines:
backup.go:93 undefined: showSizeCapStatusJSON
backup.go:141 undefined: showSizeCapStatus
backup_auto.go:200 undefined: backupSizeCapExceeded
backup_auto.go:203 undefined: maybeWarnBackupSizeCap
`backup_cap_test.go` was likewise absent from `//cmd/bd:bd_test`, leaving
seven of the PR's nine new tests unreachable under Bazel.
`make bazel-sync-check` does not catch this: `tools/bazel/go_srcs.py --check`
only validates the `go_srcs` filegroup globs, not the `go_library`/`go_test`
srcs enumerations.
Four unrelated test files (config_leaked_secret_test.go, init_role_*_test.go,
init_git_bootstrap_routing_test.go) are also unlisted, but they are unlisted
on the base too, so they are left alone as pre-existing.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(backup): stop the size-cap walk from running on every bd command (#6071 review)
Maintainer review fixup for PR #6071 (ga-y6gjv), iterations 1 and 2.
The gating finding, filed independently by both review lanes and confirmed
empirically: the fixup that moved the getDirSize walk behind the interval
throttle does not deliver its claimed property, because state.Timestamp —
the only thing that re-arms that throttle — is written in exactly two
places, both inside runBackupExport. The two steady states that skip
before reaching it therefore pass the throttle on every single bd
invocation and pay the full filepath.Walk forever:
IDLE no new Dolt commit; the walk runs, then change detection skips
and writes nothing.
PAUSED cap exceeded; the walk has already happened by the time
maybeWarnBackupSizeCap persists LastCapWarnAt, which is the only
field it wrote.
PAUSED is the pathological case: an over-cap destination is by definition
the largest one, so the feature's terminal state was its most expensive,
persisting until an operator intervened. This landed on read-only
commands too, i.e. the 65-100ms/command agent-polling regression the walk
was moved to avoid.
Both halves of the documented remedy:
- Move the cap check after change detection, the order
docs/reference/configuration.md already describes ("If data changed and
the throttle interval has passed, bd checks the destination
directory's on-disk size"). This makes that sentence true and closes
the docs finding with no docs edit.
- Re-arm the interval throttle (state.Timestamp) on the cap-exceeded
skip, leaving LastDoltCommit untouched exactly as runBackupExport's own
failure path does, so change detection still sees pending work once the
cap is raised.
Neither half suffices alone: the reorder still walks every command in a
PAUSED workspace where data IS changing, and the persist alone still walks
forever when IDLE. Persisting on the idle skip instead would add up to one
backup.interval of backup latency, which this pairing avoids.
Also from the same review, all non-gating:
- The cap-check error path failed open behind a debug-only line, so one
unreadable entry could silently restore unbounded growth while
`bd backup status --json` reported the very same error. It now warns on
stderr, throttled by the backup interval and deliberately not by the
LastCapWarnAt slot: spending that slot here would suppress the more
important PAUSED notice for a full warn interval.
- The warn timestamp is now recorded only when the message was actually
printed, so --json/--quiet agent calls stop consuming the 24h slot
silently.
- Dropped capWarnFallback (map, mutex, two accessors). No reachable
production path can read it: both call sites are in PersistentPostRunE,
which runs once per CLI process, and the proxy child installs an empty
PersistentPostRun. Its pinning test is repurposed to the contract that
is real — a persist failure must not block the already-decided skip.
- Registered backup.size-cap-mb / backup.size-warn-interval in
YamlOnlyKeys, so the backup block is a complete inventory again.
Functionally inert: the map has no enumerator and its one predicate
consumer already matches on the "backup." prefix.
- `bd backup status` prints "Size cap: unavailable (<err>)" instead of
dropping the line, and the JSON error object carries an explicit null
`exceeded` so a consumer cannot read a missing key as "not exceeded".
The CHANGELOG's cost claim is corrected to match the shipped order; it
described the throttle as sufficient, which is the defect above.
Iteration 2, all non-gating (that review approved):
- The walk-error path re-arms the interval throttle itself before
proceeding uncapped. Iteration 1 relied on the fall-through into
runBackupExport to bound that warning to once per backup.interval,
but not every runBackupExport exit persists state.Timestamp: a failed
post-sync GetCurrentCommit returns without saving state, so the walk,
the warning and the sync itself repeated on every command. The doc
comment now states the bound the code has: once per interval whenever
backup_state.json can be written.
- `bd backup status` echoes the configured backup.size-cap-mb when the
cap is disabled instead of a literal 0. viper's GetInt also resolves
an unparseable value ("2048MB") to 0, so the line asserted a value the
operator never wrote.
- The status readers count only a destination that does not exist yet
as empty. getDirSize aborts on the first per-entry error, so a chunk
file removed mid-walk read as 0 bytes, i.e. `"exceeded": false` for a
destination that may be over its cap. It is now reported as
unavailable, like any other walk error.
- docs/reference/configuration.md no longer says `--json` reports the
string `PAUSED (cap exceeded)`; it reports `size_cap.exceeded: true`.
- TestMaybeAutoBackup_CapCheckSkippedWhenThrottled seeded the same commit
as its watermark, so after iteration 1's reorder change detection
alone stopped the walk: it passed with the interval throttle deleted,
and so did every other Backup/Throttle/Auto test in cmd/bd. It now
seeds a changed commit, and its comment names the renamed
pauseAutoBackupForSizeCap.
Tests: iteration 1's four new/updated pins are each mutation-proved.
Dropping the throttle re-arm reds the three throttle pins and leaves the
idle pin green; restoring the original ordering reds only the idle pin;
reverting both reds all four. Iteration 2's three new pins each go red
under their own mutation only: dropping the walk-error re-arm, restoring
the literal `=0`, and swallowing a walk ENOENT (dropping the root stat
reds the missing-destination case instead). Disabling the interval
throttle now reds the throttle test.
Base refresh before approval (rebased onto main 3f9561db2b, which had
made the PR CONFLICTING):
- main 8269a88cbf (#6327) moved compact onto storeSizeBytes and
deleted getDirSize from compact.go, leaving backup_cap.go its only
caller, so the merged tree failed to build (undefined: getDirSize)
although only CHANGELOG.md and backup_auto.go conflicted textually.
getDirSize is restored verbatim in backup_cap.go (plus the
path/filepath import), and the two comments that described it as
shared with, or exercised by, compact.go are corrected.
- main 4e4ebdb443 (#6879) added acquireBackupLock where this commit
places the size-cap check. Both are kept, the cap check first, as
its comment asks: a skip should not first take the lock.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
* test(feat): red — Add soft watchdog warning for long-running schema migrations (refs be-yyzzs)
* feat: green — Add soft watchdog warning for long-running schema migrations (refs be-yyzzs)
* fix(schema): address review follow-ups on migration watchdog doc citation (refs be-yyzzs, review be-sogif)
Round 1 review (be-sogif) flagged criterion 7: the soft-watchdog comment
at schema.go cited engdocs/plans/be-m65rs-migration-watchdog-scoping.md,
which was never landed to any reachable ref (only exists on PM's own
unmerged worktree branch). Replace the dangling file citation with an
inline summary of the rationale plus reachable citations: the existing
initSchema comment in store.go (migration 0047 as a concrete long-runner
example) and `bd show be-m65rs` for the full scoping decision. Comment-only
change; no functional/behavioral diff. gofmt/build/vet clean; full package
suite reconfirmed 132 PASS, 0 FAIL, 0 SKIP.
* test(schema): red — watchdog is silent off a tty, and ignores bare seconds
Both from review #5997.
TestRunMigrationsWatchdogSurvivesNonTTY drives runMigrations end to end
with a deliberately slow first migration body and a 10ms interval, with
the progress writer put in the state a non-tty caller really sees. It
fails with an empty buffer: runMigrations hands the watchdog the package
stderr var, which is io.Discard whenever os.Stderr is not a terminal, so
the warning is discarded under bd serve, systemd, CI and any piped
invocation — the exact cases where a migration running for twenty minutes
needs to be visible. On a tty it works, which is why this went unnoticed.
Asserting on the wiring rather than on a package variable, so the fix has
to actually reach the call site.
The interval table gains bare-seconds cases. store.go's parseTimeout — the
convention migrationWatchdogIntervalDuration's own doc comment claims to
follow — documents "bare numbers treated as seconds (e.g. \"90\")", and
this one does not, so an operator setting the value to 90 silently gets
5m.
Note the review's own example value, 300, cannot serve as the test input:
300s IS the 5m default, so it passes whether the value was parsed or
discarded. Using 90 and 600 instead, which distinguish.
watchdogStderr exists here but is not yet wired, so the red is behavioural
rather than a compile error.
Refs be-lotba.
* fix(schema): point the watchdog's last dangling citation at bd show be-m65rs
Review #5997 point 1. Round 2 replaced the citation on the call-site
comment but missed the one in runMigrationWithWatchdog's own doc comment,
which still named engdocs/plans/be-m65rs-migration-watchdog-scoping.md.
That path does not exist, and neither does engdocs/plans/ — so the comment
sent a reader after a file that was never committed.
Points it at bd show be-m65rs, matching what the call site already says.
This was the last engdocs/plans reference in the repo; a repo-wide grep for
that prefix is now empty, so the two comments can no longer disagree.
Refs be-lotba.
* fix(schema): send the migration watchdog WARN somewhere a non-tty caller sees
Review #5997 point 2. The package's stderr var is io.Discard whenever
os.Stderr is not a terminal (schema.go:26-37) — it was introduced for
routine per-migration progress lines, where discarding off a tty is
correct. Wiring the watchdog to it inherited that gating, so the WARN was
emitted only on an interactive terminal and silently dropped under bd
serve, systemd, CI and any piped invocation: precisely the situations
where a migration still running after twenty minutes is worth knowing
about. On a tty it worked, which is why it was not caught earlier.
Routes the watchdog through its own writer instead. This is not a new
convention for the package — remote_migrate_gate.go, smart_remote_migrate
_gate.go and both schema-skew notices in this file already write operator
warnings straight to os.Stderr, ungated, for the same reason. stderr keeps
its terminal gating and its progress lines.
Chose the writer over the alternative the review offered (scoping the doc
comment to "interactive runs"), since the feature's stated purpose in
be-m65rs is telling an operator reading logs that a migration is still
working — and logs are the non-tty case.
Turns TestRunMigrationsWatchdogSurvivesNonTTY green; it asserts through
runMigrations rather than on the package var, so the wiring at the call
site is what is under test.
Refs be-lotba.
* fix(schema): accept a bare-seconds watchdog interval, matching parseTimeout
Review #5997 nit. BEADS_MIGRATION_WATCHDOG_INTERVAL=300 fell back to the
5m default instead of meaning 300s, so an operator changing the value got
the number they were trying to change and no diagnostic.
The doc comment claimed to follow internal/storage/dolt/store.go's
timeoutFromEnv, but only its unset/invalid-falls-back shape. timeoutFromEnv
is a one-line wrapper; the contract lives in parseTimeout below it, which
retries an unparsable value as raw+"s" so bare numbers mean seconds. This
function skipped that half, so the comment promised a convention the code
did not implement. Now mirrors parseTimeout's full shape — including its
non-positive handling on both branches — and cites parseTimeout by name,
since that is where the behavior being mirrored actually is.
On the review's related note that d > 0 is the only floor: that is
deliberate and is also parseTimeout's only floor. Diverging here would
make the two disagree again, which is what produced this nit. Happy to add
a minimum on both together if you want one.
Not reused directly because parseTimeout is unexported in another package.
The interval table gains bare-seconds cases; 90 and 600 rather than the
review's 300, since 300s is the 5m default and so cannot distinguish
"parsed as seconds" from "fell back".
Refs be-lotba.
* docs(changelog): add the migration watchdog to Unreleased
Review #5997 nit: a new user-facing env var and a new WARN line earn an
Deliberately CHANGELOG only, not docs/reference/configuration.md — even
though BEADS_FSCK_TIMEOUT, the sibling this env var's parsing mirrors, has
a row in that page's table. docs/ describes the pinned release
(docs/cli-docs.pin is v1.2.2, which does not contain this feature) rather
than main, per engdocs/decisions/2026-07-17-docs-release-pin.md. The table
row belongs with the pin bump at release time; adding it now would
document a flag no released bd accepts.
Refs be-lotba.
* fix(bazel): list migration_watchdog_test.go in the schema go_test srcs
Base added internal/storage/schema/BUILD.bazel after this PR's merge base,
enumerating go_test srcs file by file. The PR's new migration_watchdog_test.go
was therefore absent from it, so under Bazel the target reported
"Executed 1 out of 1 test: 1 test passes" while running NONE of the new tests
("testing: warning: no tests to run") -- a silent green.
Measured both ways on the adopted head: without this entry 0 watchdog tests
run; with it, all 7 tests and 8 subtests execute and pass
(bazel test //internal/storage/schema:schema_test). The enumeration is
maintained at 100% repo-wide -- all 56 unlisted test files are
//go:build-tagged -- so this file would have been the only untagged omission.
Maintainer fixup applied during PR adoption's rebase gate. No contributor
code changed; the contributor could not have seen this file, which did not
exist at the merge base.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(schema): scope the watchdog promise to the migration body, stop the warner on panic
Maintainer fixup applied during PR adoption's review loop (iteration 1),
addressing the one major plus the three non-gating findings in the review
synthesis. No contributor commit was rewritten.
Major -- Change Impact / Blast Radius (scope). The watchdog wraps only
execMigrationBody, while a migration step also runs the dirty-table snapshot,
preMigrationRepair, the cursor INSERT and commitMigrationStep -- and this file
already says the per-step DOLT_ADD/DOLT_COMMIT is "the expensive, fallible part
of this step on the production embedded path". The CHANGELOG therefore
over-promised: it told users a wedged migration no longer "looked identical from
outside", which is false for a wedge in that commit. The synthesis offered two
arms and said explicitly not to do both. Taking the minimal-sufficient arm:
CHANGELOG.md now scopes the guarantee to the migration body and states that a
stall in the per-step commit is still quiet, and a comment at the call site
records that the narrow boundary is deliberate, and why. The extension arm was
declined on cost: widening the wrap means moving the snapshot/commit ordering
that carries this loop's atomic-commit contract (#4566, #4690), under a
strict-ordered sqlmock expectation set and the cross-package
migrateStepFaultHook tests -- more risk than an observability-only change should
carry. Measured: this fix leaves runMigrations at gocyclo 16 / gocognit 29,
byte-identical to before, whereas nesting the whole step in a closure would have
driven the cognitive score well past its current band.
Minor -- Resource Lifecycle & Cleanup. close(done)/wg.Wait() moved into a defer.
A panic out of fn skipped the straight-line close and orphaned the ticker
goroutine, which then went on warning about a migration that was no longer
running, for the life of the process, on the deliberately un-gated
watchdogStderr. Reachability is open rather than proven
(internal/httpapi/server.go:1406 recovers everything but http.ErrAbortHandler
and keeps serving), which is the argument for taking the one-keyword fix. Pinned
by a new test: against the pre-fix schema.go it reds with "3 WARN lines when the
panic unwound, 8 after a further 50ms"; with the defer it passes under -race.
Minor -- Test Evidence Quality. TestMigrationWatchdogIntervalDuration's
"unset_defaults_to_5m" arm never unset anything, so the ambient environment flowed
straight into the call. Two-arm control: with BEADS_MIGRATION_WATCHDOG_INTERVAL=600
exported the old arm reds ("= 10m0s; want 5m0s") and the fixed arm passes, with the
subtest confirmed to have actually run rather than being filtered out.
Nit -- Contract & Interface Fidelity. BEADS_MIGRATION_WATCHDOG_INTERVAL added to
docs/reference/configuration.md's env table, beside the BEADS_FSCK_TIMEOUT row
whose duration contract it mirrors.
Validation: go test ./internal/storage/schema/ -count=1 green (41s); 8 watchdog
tests + 8 subtests PASS, 0 SKIP, 0 FAIL; gofmt clean; go vet clean; git diff
--check clean; ./scripts/check-doc-freshness.sh PASSED.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(bazel): list golang.org/x/term in the schema go_test deps
migration_watchdog_test.go imports golang.org/x/term directly. Under Bazel
it compiled only through embed = [":schema"], but gazelle lists a test
file's own imports in the go_test's deps, so `bazel run //:gazelle`
rewrites this BUILD file. Since the base now gates PRs on the Bazel lanes,
BAZEL_TEST's "BUILD files in sync (gazelle, go_srcs, MODULE.bazel)" step
would fail on exactly this one line. This is the line gazelle produces.
Measured on the adopted head refreshed onto current main: the whole CI sync
step run locally (go_srcs.py --check, bazel run //:gazelle, go_srcs.py,
bazel mod tidy) leaves this line as the only drift in the repository.
With it, bazel test //internal/storage/schema:schema_test --config=ci
passes: 433 test cases, 0 failures, all 16 watchdog cases run (0 skipped),
and tools/bazel/check_testcases.py plus equivalence.py report no schema
divergence.
Maintainer fixup applied during PR adoption's pre-approval CI repair. No
contributor code changed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
* fix(doctor): detect test binaries with testing.Testing(), not the file name
getBdBinary refuses to return a test binary as "bd" so fix tests cannot
fork-bomb by re-running themselves. The guard matched only the `go test`
naming (<pkg>.test). Bazel names test binaries <target>_test, so under
`bazel test` every fix that shells out to bd re-ran the whole fix_test suite,
recursively (~60 levels), until the 300s timeout.
testing.Testing() is true for any binary linked as a test by `go test` or
rules_go (both set testing.testBinary=1), whatever its name. The name check
stays as a fallback. bd already links package testing, so the product binary
gains no dependency. Behavior under `go test` is unchanged.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): tag taxonomy, docker lane, and green //scripts targets (slice B5)
`bazel test //... --config=ci` is now fully green, locally and with
--config=remote-exec.
- scripts_test declares what it reads and runs: this package's own tree
(:scripts_files), .github/** (//:workflow_files, widened from the
workflows), and .buildflags/.test-skip for scripts/test.sh. The complexity
diff test builds a one-commit git fixture instead of git-archiving the
real checkout's HEAD. Under Bazel it skips the whole-repo testing.Short()
scan (it would pass vacuously over the runfiles) and the two release
formula tests (.beads is in .bazelignore). Tagged host-tools +
no-remote-exec: it runs the host's git/python3/coreutils and some subtests
skip without git.
- prlintmake_test resolves fmt-check.sh through bazeltest.CallerDir and
declares it; it needs only bash (gofmt is shimmed), so it stays untagged
and runs remotely.
- //cmd/bd/doctor/fix:fix_docker_test reruns the fix_test binary (no second
compile, tools/bazel/go_test_variant.sh) with BEADS_FIX_REQUIRE_DOLT=1, like
pr.yml's container-backed doctor/fix job. Tagged requires-docker +
no-remote-exec; `--config=docker` selects it (race, no -short, no
BEADS_TEST_SKIP=dolt). fix_test itself stays untagged: under prcore it
skips the Dolt-backed tests exactly as pr-core's `go test` does.
- scripts/bazel_policy_test.go: every BUILD `tags` value must be in the
taxonomy, be named in the comment above its rule, and host-bound tags must
come with no-remote-exec; test:prcore must exclude requires-docker,
embedded and manual.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bd): reset git's cwd cache in TestContextRoutesNameOneWorkspaceTheSameWay
The test chdirs into a fresh git repo but reset only beads' caches. git
caches the cwd's repository context process-wide, so when an earlier test in
the same process had resolved it from a non-repo directory (for example
TestCollectMetadataEntriesNoBeadsDir), GetMainRepoRoot kept answering "not a
git repository". Test order hid it under `go test ./cmd/bd`; Bazel sharding
reorders tests and exposed it. Reproduces with plain go test:
go test -run '^(TestCollectMetadataEntriesNoBeadsDir|TestContextRoutesNameOneWorkspaceTheSameWay)$' ./cmd/bd
The cache is reset on entry only. Resetting it again in cleanup changes what
later tests inherit, and TestCreateRemoteRepoSkipsLocalDatabaseGuard (which
never resets it) then fails under the unsharded go test order.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): shard bd_test and embeddeddolt_test; keep test re-execs shard-free (slice B6)
- //cmd/bd:bd_test shard_count = 16, //internal/storage/embeddeddolt:
embeddeddolt_test shard_count = 8. Remote -race under --config=ci: bd_test
max shard 61-82s (unsharded 252-264s), embeddeddolt max shard 84-122s
(unsharded 207-377s). The embeddeddolt max is a single test
(TestWithPeerAuth, ~93s), so more shards would not lower it. Every shard
runs tests (bd 161-172 top-level tests each, embeddeddolt 15-20).
protocol (4s), legacysqlite (4s) and dbproxy/server (22s) stay unsharded.
- Tests that re-exec their own binary now pass bazeltest.ShardFreeEnv
(a no-op under go test), so a helper child does not inherit
TEST_SHARD_INDEX/TEST_TOTAL_SHARDS/TEST_SHARD_STATUS_FILE and filter away
the one test it was asked to run: dolt suite_leak_linux, dbproxy
force_stop_linux, workspacegate (3 helpers), metrics spawn_reap, bd
worktree_remove, conformance role_bundle, linear synclock (windows).
scripts/test_script_test.go (child env built from scratch) and
repro-dolt-prod-timeouts (copies the binary, never runs it) need nothing.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): keep sharded bd_test off ~/.beads and keep its stdio leak guard
Two things sharding //cmd/bd:bd_test exposed:
- config.Initialize walks up from the test's cwd for .beads/config.yaml and,
under BEADS_TEST_IGNORE_REPO_CONFIG, stops at the module root (go.mod).
The runfiles tree had no go.mod, so the walk left it; with the output base
under $HOME it loaded the developer's ~/.beads/config.yaml (here
dolt.shared-server: true) and two embedded-mode autocommit tests failed
locally, though not on remote workers. bd_test now declares //:go.mod, so
the walk stops at the runfiles root as it stops at the checkout under go
test. Unsharded runs hid this: an earlier test re-initialized config first.
- TestZZStdioNotLeaked skipped in every shard, because the baseline test is
always in shard 1 and the guard in another. Without a baseline it now
checks the descriptors instead (a leaked capture leaves a pipe where fd 1
or 2 was). Under go test the baseline is always captured, so nothing
changes there.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* chore(bazel): sync BUILD files with test files added on main
Gazelle picks up cmd/bd and internal/notion tests that landed on main after
the last sync (make bazel-sync).
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(discovery): add BEADS_CEILING_DIRECTORIES; bound bazel tests' walks
bd finds its workspace by walking up from the working directory for .beads
and .beads/config.yaml. Under `bazel test` the working directory is in the
runfiles tree under the output base, usually below the developer's HOME, so
the walks left the sandbox: tests read the developer's ~/.beads/config.yaml
(results depended on it) and wrote into ~/.beads (interactions.jsonl from the
audit log, .local_version from version tracking).
BEADS_CEILING_DIRECTORIES takes git's GIT_CEILING_DIRECTORIES form (a PATH-
style list of absolute directories): a search starting inside a ceiling never
examines the ceiling or anything above it; the start itself is always
examined. Unset, nothing changes. Honored by every upward .beads/config
search: beads.AncestorDirWalk (all FindBeadsDir walks), config.Initialize
(the go.mod and config.yaml walks, and the worktree-fallback git probe, whose
routing scrub drops GIT_CEILING_DIRECTORIES), findProjectBeadsDir, the legacy
upgrade guard, the --db beads-dir walk, store reopen and findBeadsRepoRoot.
The migration-freeze marker walk is left alone on purpose: it is a write
safety gate, and BD_MIGRATION_FREEZE_FILE is already its explicit override.
tools/bazel/test_env.sh sets BEADS_CEILING_DIRECTORIES and
GIT_CEILING_DIRECTORIES to the runfiles root, TEST_TMPDIR and its own temp
root. It does not fail on an ancestor .beads: a live ~/.beads above the
output base is normal on a developer machine. bd_test no longer needs
//:go.mod as a walk stop.
Canary check: with an invalid-YAML .beads above a scratch --output_base,
compact, issueops, validation and bd_test pass under --config=ci and nothing
is written there; the previous wrapper fails on it and writes
interactions.jsonl into it.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bd): check for leaked stdio after m.Run in every process
TestZZStdioNotLeaked only sees the tests that ran before it in the same
process. Under Bazel's 16-way sharding that is ~1/16 of bd_test: the baseline
test is in shard 1, the guard in another shard, and leaks in the other shards
were never checked.
TestMain now compares os.Stdout/os.Stderr after m.Run with the streams from
before it (runTestsAndSweep, so every shard and every go test run) and fails
the process on a leak. The one allowed change is the framework's own
os.Stderr = os.Stdout under -json. TestZZStdioNotLeaked stays for its go test
report and skips when it has no baseline; the descriptor fallback added for
sharding is gone.
Verified: a test that leaks os.Stdout fails `go test -run` for it alone, with
and without -json; a clean -json run passes.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): keep host-tools results out of the remote cache; tighten tag policy
- //scripts:scripts_test (host-tools, no-remote-exec) ran locally but its
result was still uploaded to the remote cache and served to other clients,
though the action key does not cover the host's git/python3/bash. It is now
also tagged no-remote-cache (neither read nor uploaded). Checked: after a
--config=remote-exec run and `bazel clean`, a rerun without the disk cache
executes the test again instead of taking a remote cache hit.
- Under Bazel a missing git or bash now fails those tests instead of
skipping (the host-tools tag promises them); under go test they still skip.
- Tag policy: host-tools requires no-remote-exec and no-remote-cache;
`tags = [...] + X` is rejected as non-literal; every --test_tag_filters set
by test:prcore or a config that expands it (test:ci, transitively) must
exclude requires-docker/embedded/manual, not only the first prcore line.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(bazel): run go_test variants from their package directory
rules_go gives a go_test GO_TEST_RUN_FROM_BAZEL=1 (and its `env`) through
RunEnvironmentInfo; an sh_test that reruns the binary gets neither, so the
binary skipped its chdir into the package directory and ran from the
runfiles root. go_test_variant.sh now exports GO_TEST_RUN_FROM_BAZEL=1, and
its header says the variant target must repeat the go_test's `env`.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): docker-lane variants for domain/db, uow and protocol
--config=docker only ran doctor/fix. pr.yml's container jobs also run
internal/storage/domain/... + uow/... (race, no -short, Dolt image pulled)
and cmd/bd/protocol (BEADS_PROTOCOL_REQUIRE_DOLT=1). Under --config=ci those
container suites skip (BEADS_TEST_SKIP=dolt), so without variants their
coverage would vanish if Bazel replaced those jobs.
- testutil: BEADS_TEST_REQUIRE_DOLT_CONTAINER=1 makes RequireDoltContainer
and StartIsolatedDoltContainer(Handle) fail instead of skip when the Dolt
container is unavailable (the generic form of BEADS_FIX_REQUIRE_DOLT).
- db_docker_test, uow_docker_test (4 shards) and protocol_docker_test
(8 shards, BEADS_PROTOCOL_REQUIRE_DOLT=1) rerun the go_test binaries via
go_test_variant.sh, repeating their `env`; tagged requires-docker +
no-remote-exec. The other domain/tracker packages have no container tests
and already run under --config=ci.
`bazel test //... --config=docker --test_arg=-test.v`: 4/4 PASS; db 908
PASS / 0 SKIP, uow 985 PASS / 32 SKIP (conformance capabilities the backend
does not implement, as under go test), protocol 151 PASS / 2 SKIP (tracked
known gaps). With --test_env=BEADS_TEST_SKIP=dolt, db_docker_test fails.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test: shard-free env for the embeddeddolt concurrency helper; 2m bd init timeout
- concurrency_test re-execs its test binary with -test.run=^TestHelperProcess$
inside the now-sharded embeddeddolt_test; pass bazeltest.ShardFreeEnv so a
child cannot inherit TEST_SHARD_* and filter its one test away (it is
gated by BEADS_TEST_EMBEDDED_DOLT=1, so dark today).
- initBeadsWorkspace / runBDStdout (TestClose_UpdatesLastTouched and the
gemini prime hook tests) allowed 30s per bd subprocess. A -race bd on a
loaded host exceeded that for a single `bd init` (killed at 30.18s in 1 of
3 sharded remote runs; the whole test otherwise passes in ~21s), so allow
2 minutes.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bd): give TestCreateRemoteRepoSkipsLocalDatabaseGuard its own git state
The test chdirs into a fresh non-repo temp dir but used whatever git/beads
cwd caches earlier tests left. When an earlier test had reset git's cache and
a later one refilled it from the package directory, workspace discovery in
the test returned the checkout's .beads (from a git worktree: the MAIN
checkout's live .beads via the worktree fallback) and `bd create` tried to
open it, so it failed with "could not verify workspace identity" instead of
the expected downstream error. It passed only on stale state (a cache
pointing at a deleted temp repo).
It now resets the git and beads caches after its chdir and again in cleanup,
so it neither depends on nor leaks cwd state. With that fixed,
TestContextRoutesNameOneWorkspaceTheSameWay also resets git's cache in
cleanup. Reproduced with the context-test cleanup reset in place, running
every cmd/bd test declared up to this one (the failing go test order); now
passes there, alone, with the two context tests, and under -shuffle seeds
1-5 (other pre-existing order dependencies show up under shuffle; this test
is not among them).
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* build(bazel): re-sync BUILD files with main
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): pin BD_MIGRATION_FREEZE_FILE in test_env
The freeze-marker ancestor walk is intentionally not ceiling-bounded; an
explicit BD_MIGRATION_FREEZE_FILE replaces the walk, so a MIGRATION-FREEZE
above the output base can no longer change test results.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(scripts): give the complexity diff fixture a Go package
complexity.sh expands "${analyzer_paths[@]}" under set -u; with an empty
fixture tree that is an unbound-variable error on bash 3.2 (macOS runners).
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(notion): keep notion.token out of the Dolt database (#6676)
notion.token was missing from YamlOnlyKeys, so `bd config set
notion.token` (the command `bd notion status` recommends) wrote the
token to the Dolt config table, whose contents `bd dolt push` sends to
the remote. The git-tracked-config guard never fired for it either,
because checkSecretGitTracked only considers yaml-only keys.
- Add notion.token to YamlOnlyKeys, next to github.token, gitlab.token,
jira.api_token and ado.pat, so `bd config set` writes it to
config.yaml and refuses a git-tracked config.yaml.
- Map notion.token to NOTION_TOKEN in secretKeyEnvVarHints so that
refusal suggests the variable bd actually reads, not BD_NOTION_TOKEN.
- notion.ResolveAuth now reads config.yaml first, then the database,
then NOTION_TOKEN. The database read is kept only so a token stored
by an older bd keeps authenticating after an upgrade.
- resolveNotionAuth's no-store fallback goes through ResolveAuth, so a
config.yaml token is found even when no store is open.
- The proxied `bd serve` settings integration test used notion.token as
its credential-bearing key and read it back with `bd config get`,
which now reads config.yaml; it uses notes.api_token instead.
- The DB-backed-secret guard test used notion.token as its example of a
non-yaml secret key; it uses custom.api_token instead.
- Docs list notion.token with the other yaml-only secrets, and the
quickstart leads with NOTION_TOKEN because `bd init` in a git repo
leaves config.yaml tracked.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(config,notion): delete leaked secret rows on unset; name the legacy auth source
Maintainer review fixes for #6724 (GH#6676).
Finding 1 (major, PR-introduced): moving notion.token into YamlOnlyKeys made
`bd config unset notion.token` return before the store, so a workspace that had
already leaked the token into the pushed config table lost its only bd-side
remover — exactly the population the PR exists to protect. configUnsetCmd now
best-effort deletes the database row for yaml-only SECRET keys and reports which
copies it removed. It is keyed on IsYamlOnlyKey+IsSecretKey rather than on
notion.token, so it closes the gap for the whole class; measured, that is at
least ado.pat, github.token, gitlab.token, jira.api_token, linear.api_key,
linear.oauth_client_secret and notion.token, plus whatever the prefix rules
(`ai.`, `sync.`, `federation.`, ...) admit. Non-secret yaml-only keys are gated
out before the store is opened, so an ordinary `bd config unset routing.mode`
still costs no database open. It reads before deleting because DeleteConfig
reports no miss, so the common never-leaked workspace stays silent instead of
announcing a removal that did not happen.
Finding 2 (major, pre-existing class): internal/notion/auth.go asserted "It must
never be written to the database" as an unqualified invariant while
PUT /v0/beads/config/notion.token still writes that row with no refusal. Scoped
the comment to the CLI door and named the HTTP/dashboard door as the known
remaining hole. Closing that door is deliberately NOT attempted here: it is a
cross-tracker change at workapi.ValidateSettingWrite/SetSetting on a
pre-existing surface, and belongs where every tracker credential gets the rule
at once.
Finding 3 (minor): the config.yaml token and the legacy row both reported
`config_token`, collapsing the safe case with the leaked one. Added
AuthSourceDatabaseLegacy plus a `bd notion status` rotation warning — the only
signal that gives the CHANGELOG's rotation advice an addressee.
Finding 4 (minor): pinned the end-to-end shape `bd config set` actually writes.
The finding cited internal/config/config.go:653 (setNestedKey), which is
SaveConfigValue's writer and not on this path — SetYamlConfig routes through
updateYamlKey/updateNestedYamlKey — but its conclusion held: the written shape
is nested. The new test drives the real writer rather than a second fixture, and
both its assertions were proven live by mutation (breaking the config.yaml read
trips the round-trip; forcing the flat fallback trips the non-vacuity guard,
while the round-trip alone still passed, which is why that guard exists).
Finding 5 (nit): both "not configured" errors led with `bd config set
notion.token`, which the new git-tracked refusal rejects in the default
post-`bd init` layout. They now lead with `export NOTION_TOKEN`, matching the
quickstart's ordering.
Also corrected the CHANGELOG, which still claimed unset clears config.yaml only.
Validation: ./internal/notion and ./internal/config green under `env -u
BEADS_DIR`. The cmd/bd notion/config tests are green except
TestConfigValidateReadOnlyIsHermetic and
TestGetNotionConfigReadsDBPathWhenStoreUnset, which fail identically at the PR
head with these fixes stashed (A/B in this same worktree) — ambient, not
introduced here.
--- Iteration 2 review fixes (one major, three minors, one nit) ---
Finding 1 (major, introduced by the iteration-1 fixup above): the cleanup
reached the store through openWorkspaceConfig -> ensureDirectMode ->
ensureStoreActive, which is open-OR-CREATE. So `bd config unset <yaml-only
secret>` in a workspace holding only .beads/config.yaml created a 2.1 MB
embedded Dolt database and flipped it out of db-less mode for every later
command -- from a command whose contract is "edit a YAML file", silently and
with exit 0. It also contradicted configCommandCanRunWithoutStore, which
classifies this exact invocation as runnable with no store precisely when
beads.FindDatabasePath() is empty. unsetLeakedSecretRow now returns early
rather than reach an open-OR-CREATE store in a workspace that has no database to
reach. The proxied route is exempt rather than gated --
proxiedWorkspaceConfig reaches an already-connected provider and creates
nothing, and a server-mode workspace legitimately has no local database
directory for FindDatabasePath to find, so gating it on the local path would
silently disable the cleanup exactly where the row is most replicated. Iteration 3 finishes
that thought: the same is true of the DIRECT server-mode route, which this gate
still skipped.
Finding 2 (minor): the remover ran only if the YAML unset succeeded first,
which skipped it for the population it exists for -- no config.yaml, or a shape
UnsetYamlConfig refuses. Base deleted the row there and the fixup did not, while
`bd notion status` names this very command as the remover. The cleanup now runs
either way, and a failed YAML unset carries the row's fate in its error instead
of telling the user to run `bd init` while a credential sits in the pushed
table.
Finding 3 (minor): a failed DELETE of a row the read had found was rendered as
"Could not check the database ..." under a JSON key asserting unreachability --
the one outcome that is certain, reported as the inconclusive one.
removeStoredSecretRow now returns the found bit alongside the error, and the
delete-failure case gets its own message and its own JSON keys
(database_row_present / database_delete_failed), carrying the rotation warning.
Finding 4 (minor): nothing pinned the command -> cleanup wiring; deleting the
call left every test green. The yaml-only branch is now runConfigUnsetYamlOnly
and four new tests drive configUnsetCmd itself against a recording settings
surface: the row is read, deleted and reported; a non-secret yaml-only key
touches the config plane zero times; --json carries the new keys; and .beads/ is
byte-unchanged (config.yaml aside) after unsetting a secret with no database
present.
Finding 5 (nit): CHANGELOG and docs/reference/configuration.md described the
dual removal unconditionally. Both now say the database half is best effort and
name the cases where it is skipped or refused.
Every new pin proven by mutation, one at a time, each failing only with its fix
removed: dropping the FindDatabasePath gate takes the no-database test into
embeddeddolt.OpenSQL (it really does provision); re-gating the cleanup behind
the YAML unset leaves the row undeleted and unmentioned; replacing the command's
cleanup call with a zero value drops the report and the --json field; returning
false for `present` on a failed delete puts database_unreachable back.
Complexity ledger flat by construction: worst_changed stays
showConfigYAMLOverrides at cyclomatic 17 / cognitive 29, which this PR does not
touch and which measures identically at the base blob. The extracted
runConfigUnsetYamlOnly is 6/9 and the three report helpers are at most 5/2.
Iteration 2 validation: ./internal/notion and ./internal/config green under
`env -u BEADS_DIR`; all nine cmd/bd leaked-secret/notion-auth tests green, one
-run per invocation (a batched regex shares rootCmd and produces false reds);
the CGO_ENABLED=0 gms_pure_go cmd/bd test binary still compiles (the new test
file is untagged, so it carries its own tree-snapshot helper rather than the
cgo-tagged twin); scripts/check-doc-flags.sh and `go test -tags=gms_pure_go
./test/docsync` pass for the docs edit.
--- Iteration 3 review fixes (two minors, both on the gate itself) ---
Finding 1 (minor, introduced by the iteration-2 gate above): "not proxied and no
local database directory" over-fires. findDatabaseInBeadsDir answers on
metadata.json plus embeddeddolt/ and dolt/, and it skips the stat for server mode
only when metadata.json is present -- so a metadata-less server workspace, whose
host comes from config.yaml or BEADS_DOLT_SERVER_HOST (main.go, GH#3545, the
shape gc provisions on every `gc-beads-bd start`), reports "" while its row sits
on the shared server, replicated to every remote it pushed to. The skip was not
buying anything there either: PersistentPreRun has already CONNECTED that
workspace's store, and ensureStoreActive early-returns on an active store without
opening or creating anything. For notion.token this was a narrow regression of a
base capability -- at base that key was not yaml-only, so `bd config unset
notion.token` took the database branch and deleted the row. The seven
pre-existing yaml-only secrets never had a remover at base, so for them the skip
withheld only new coverage, which is what holds this at minor. The gate is now
mayProvisionDatabase, which asks about the store before the disk; each arm that
returns false is a route where the database is already open -- proxied, or a
store already active and tracked, which is provably non-provisioning because it
is ensureStoreActive's own no-op arm.
Finding 2 (minor): neither arm of that gate had a behavioral test. Deleting the
!usesProxiedServer() clause left all four command-level tests green, and it is
the only thing keeping the cleanup alive for proxied workspaces, which have no
local database directory by construction -- the clause a later simplification is
most likely to read as redundant was the one clause nothing defended.
TestConfigUnsetCleansTheRowWithNoLocalDatabaseDirectory now pins both arms as the
mirror of TestConfigUnsetDoesNotProvisionADatabase: "no local database directory"
is the state all three share, so the route to the database is the only thing that
distinguishes them.
Both arms mutation-proved, one at a time, each red on exactly one subtest while
the four pre-existing command-level tests stayed green under both mutations:
deleting the active-store arm reproduces the finding verbatim (GetSetting calls =
[], UnsetSetting calls = [] for a connected server workspace, exit 0); deleting
the !usesProxiedServer() arm leaves the proxied workspace's row never looked for.
That second half -- the pre-existing suite staying green -- is the claim Finding 2
rests on, and only a run under the mutation can state it.
The CHANGELOG's "skipped where there is no database to hold a row" and the
matching sentence in docs/reference/configuration.md asserted exactly what the
gate got wrong; both now say it is skipped only where reaching the row would mean
creating a database, and that a server-mode or proxied workspace whose database
is simply not on local disk still gets the cleanup.
Complexity ledger still flat: worst_changed stays showConfigYAMLOverrides at
cyclomatic 17 / cognitive 29 (untouched, identical at the base blob), and
extracting the gate took unsetLeakedSecretRow from 6/5 to 5/4 with
mayProvisionDatabase at 4/3.
Iteration 3 validation: gofmt clean, `go build ./cmd/bd/`, `go vet ./cmd/bd/` and
`git diff --check` clean; the six leaked-secret/notion-auth tests and the four
command-level tests all green against the real fix, one -run per invocation under
a private TMPDIR (a batched regex shares rootCmd and produces false reds; a
sibling suite's sweep deletes shared temp roots mid-run); the CGO_ENABLED=0
gms_pure_go cmd/bd test binary still compiles; scripts/check-doc-flags.sh,
scripts/check-doc-freshness.sh and `go test -tags=gms_pure_go ./test/docsync`
pass for the docs edit (no new links, anchors or headings, so the render check
does not apply).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
* fix(dolt): honor dolt.auto-commit=batch/off on the proxied-server write path (#4995)
In proxied-server mode every write minted a Dolt history commit whatever
dolt.auto-commit said. Two causes:
- cmd/bd/main.go never applied issueOpsContext(rootCtx) in the
proxiedServerMode branch of the root pre-run, so the context carried no
deferred-commit marker.
- internal/storage/uow/doltserver_tx.go: doltServerTx.Commit ignored
issueops.VersionCommitDeferred(ctx) and ran CALL DOLT_COMMIT('-Am', ?)
whenever a message was supplied.
Apply issueOpsContext to rootCtx in the proxied setup, and have
doltServerTx.Commit blank its message under a deferred context so the existing
plain-COMMIT branch persists the write to the working set without advancing
Dolt history. dolt.auto-commit=on is unchanged.
This commit alone strands batch/off writes in the working set; the explicit
flush point (`bd dolt commit`) follows in the later commits of this series.
(Originally recorded as "witness: salvage uncommitted work (ocb-ani)"; the
change itself is unmodified.)
* test(uow,cmd/bd): add regression tests for proxied dolt.auto-commit batch/off (#4995)
Add focused regression tests verifying that proxied dolt.auto-commit batch/off
defer Dolt version commits:
- cmd/bd: TestIssueOpsContextDefersByModeInProxiedServerMode verifies that
issueOpsContext defers version commits in proxied-server mode when
dolt.auto-commit is batch or off.
- internal/storage/uow: TestDoltServerTxCommitDefersDoltCommitUnderDeferredContext
and TestDoltServerTxRunTxWithDeferredContextSkipsDoltCommit verify that
doltServerTx.Commit blanks the commit message under a deferred context,
bypassing DOLT_COMMIT and status checks, and executing plain COMMIT to
persist writes into the working set without advancing Dolt history.
* fix(dolt): add the proxied flush point dolt.auto-commit=batch/off defers to (#4995)
The deferral half of this PR makes dolt.auto-commit=batch/off actually take
effect on the proxied-server write path. On its own that turns batch/off into
"never commit": proxied mode returns from the root pre-run before newDoltStore
runs, so getStore() is nil and `bd dolt commit` has no store to commit
through. Writes pile up in the sql-server working set where `dolt log`,
`dolt push` and backups never see them.
Add the missing half. cmd/bd/dolt_commit_proxied_server.go is the proxied dual
of `bd dolt commit`: it takes the uow.MaintenanceProvider route (RunNonTx) and
runs CALL DOLT_COMMIT('-Am', ?) on a pinned connection, gated on
issueops.HasPendingChanges. It deliberately does not go through
doltServerTx.Commit, which blanks its own message under the deferred context;
routing the flush through the deferral it exists to discharge would make the
flush a no-op. doltCommitCmd dispatches to it on usesProxiedServer(); the
message is built before the branch so both routes name the same default, and
the "Committed." / "Nothing to commit." contract is unchanged.
--dolt-auto-commit's help no longer claims proxied-server routes are
unaffected: it names the proxied flush point and keeps the SIGTERM/SIGHUP
flush marked embedded-only. docs/reference/configuration.md says the same.
`bd vc commit`'s proxied refusal now points at `bd dolt commit`.
Tests:
- cmd/bd/dolt_commit_proxied_integration_test.go: three batch writes leave
dolt_log unchanged and stay readable, `bd dolt commit` advances it by
exactly one, a second `bd dolt commit` reports "Nothing to commit." with
dolt_log unchanged, and one write under --dolt-auto-commit on advances it
by one. On the PR's original base it failed at the `bd dolt commit` step
with "no store available". On current main the front door refuses the
command before that code is reached, so this test is only green together
with the next commit, which moves `dolt commit` to supported in the proxy
capability registry.
- TestIssueOpsContextDefersByModeInProxiedServerMode renamed to
TestIssueOpsContextDefersByModePolicyTable and the proxiedServerMode
assignment dropped: issueOpsContext branches only on writesCommitNow(),
never on the storage mode, so the old name over-promised.
- doltserver_tx_test.go: "bd: update bd-4995" -> "bd: update GH#4995", which
no longer reads as a bead id.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(proxy): move `dolt commit` from refused to supported in the capability registry
Main's proxy capability registry (added by #6269, 24a9da6cc) declares
`dolt commit` direct-only: it has a "proxy.dolt_commit.unsupported" refusal
in proxyMaintenanceRefusals (cmd/bd/proxy_capability.go) and is classed
HistoryDirectOnly in historyCapabilityMatrix (cmd/bd/history_capability.go).
The front door therefore refuses `bd dolt commit` in proxied-server mode
before dispatch, so the proxied dual added earlier in this series is
unreachable, and dolt.auto-commit=batch/off has no way to flush.
the history/VC front-door contract, and neither the registry, its tests nor
the docs explain why `dolt commit` was listed. Nothing on main implemented
`dolt commit` for the proxied route at the time, which is consistent with the
entry being a statement of what existed rather than a design decision.
This flips a capability main had declared unsupported, deliberately: the
proxied route now has an implementation (runDoltCommitProxiedServer), and
batch/off need it as their flush point (GH#4995).
Declared the same way as the other proxied-supported command,
`dolt remote remove`: HistoryProxySupported in the history matrix, and no row
in proxyMaintenanceRefusals.
Tests follow: history_capability_test.go moves `dolt commit` from the
direct-only assertions and refusal contract to the proxy-supported ones
(including the nested front-door pass-through), and
history_remote_frontdoor_matrix_test.go drops the refusal row and adds a
`dolt commit` pass-through check to TestHistoryRemoteSupportedFrontDoorParity.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(proxy): exempt explicit commit points from the proxied deferral (#4995)
Maintainer review fixup for PR #6499, adopt-pr iterations 1-2.
Major (Contract & Interface Fidelity). The deferral is applied once, to
rootCtx, so it blanketed BOTH commit classes the direct route distinguishes by
which wrapper a verb picks: policy-honoring writes (transactHonoringAutoCommit,
per-verb issueOpsContext) and explicit commit points (transact, which passes
the caller's message whatever the policy says). Under dolt.auto-commit=batch a
proxied `bd batch -m "release batch"` therefore persisted the rows, discarded
the message and minted nothing, while the identical command and config on the
direct route committed it — and batch_proxied_server.go's own contract comment
rejects exactly that ("would persist these writes while silently bypassing
Dolt history"), as does batch.go's "the contract is the same on both backends".
issueops.WithImmediateVersionCommit clears the marker and cmd/bd's
explicitCommitPointContext applies it in the duals whose direct twin calls
transact. Scope is the intersection of the transact call sites with
proxyPermittedPaths: batch, mol bond/pour/squash, mol wisp create, and the
WISP half of mol burn (cook and migrate issues also call transact but are
refused in proxied mode, so they have no dual to exempt). The review sized the
radius at batch + 4 mol verbs; mol wisp create is the same class — its direct
twin reaches cloneSubgraph's transact through spawnMoleculeWithOptions — so it
is exempted with them.
Membership is per commit site, not per command (iteration 2). `bd mol burn` is
two classes on the direct route: wisps go through burnWisps -> transact, while
persistent molecules go through deleteBatch -> issueOpsContext ->
dolt/deleter.go, which returns before DOLT_COMMIT when the context defers.
Exempting the whole command minted one Dolt commit per persistent molecule
under batch/off — on a destructive verb, where the identical direct-route
command defers them all to `bd dolt commit`. runMolBurnProxiedServer now
applies the exemption to the wisp RunTxResult only, and the flag help,
configuration.md and the helper's own radius comment say so.
Minors:
- The flush passes '--author' like DoltStorage.CommitAll, so the one commit
batch mode keeps is attributed to the bd actor rather than the SQL session
user (without it dolt_log reads `root <root@localhost>`).
- runDoltCommitProxiedServer calls the shared runProxiedNonTx instead of
re-implementing its provider checks, so `bd --json dolt commit` keeps the
JSON error envelope; `dolt commit`'s RunE no longer re-wraps an
already-reported failure, and runProxiedNonTx's message gains the provider
%T the open-coded version had.
- The flag help and configuration.md drop two false claims: that the deferral
covers "every write" in proxied mode (the bd serve plane over the same
provider never touches rootCtx, so daemon writes still commit per write) and
that the SIGTERM/SIGHUP flush is "embedded-only" (flushBatchCommitOnShutdown
gates on an open store, which direct SQL-server mode has; only proxied mode
lacks one). Both surfaces now name the explicit-commit-point exemption.
- Both user-facing enumerations of that exemption are now derived from the
explicitCommitPointContext call sites rather than restated (iteration 2):
they had omitted mol wisp create, listed mol burn wholesale, and implied a
message-less `bd batch` defers when batch.go synthesizes a default message
and the dual exempts unconditionally, so every proxied batch commits.
- doltserver_tx.go's ephemeral-form comment names its second entry point —
RunTx/RunTxResult under a deferred context — where its
ONLY-dolt_ignored-state rationale stops applying.
Not done: regenerating docs/CLI_REFERENCE.md. Its --dolt-auto-commit drift is
base-preexisting, and the generated CLI docs are built from the release tag
pinned in docs/cli-docs.pin, not from this source, so touching them converts
the drift gate's inherited-drift warn-pass into a failure.
Tests. The uow blanking table gains the immediate-commit arm (tagless, so it
runs in every lane); the proxied integration test gains an explicit-batch-commit
step with a deferred plain create as its control, plus the flush attribution
assertions. Mutation-proved: reverting explicitCommitPointContext to a no-op
reds the new step (dolt_log 80 -> 80, no commit minted), and dropping
'--author' reds the attribution assertion with committer=root.
Iteration 2 adds the WIRING pin those left open — the mechanism was covered,
but deleting `ctx = explicitCommitPointContext(ctx)` from a dual was green in
every lane, which is why the mol burn over-application above was invisible.
dolt_autocommit_exemption_wiring_test.go is tagless and needs no server: a
uow.UnitOfWorkProvider that records the context RunTxResult hands NewUOW and
then refuses observes exactly the context each dual gives its transaction.
Mutation-proved per arm: neutering the exemption at batch/bond/squash reds
those three rows and only those; dropping it from the wisp RunTxResult reds
the wisp arm alone; and restoring the command-wide reassignment reds the
persistent arm alone, reproducing the defect this iteration fixes.
Validation: go build ./..., go vet (cgo and CGO_ENABLED=0), gofmt clean;
internal/storage/issueops; internal/storage/uow -run TestDoltServerTx; the
cmd/bd registry / history / policy / batch / mol / wisp / errors battery; and
the gated real-server lane BEADS_TEST_PROXIED_SERVER=1 green for both
TestProxiedServerBatchDefersThenDoltCommitAdvancesHeadOnce (41s) and
TestProxiedServerMolBurn (33s, all four subtests including the mixed
wisp+persistent burn this iteration changed).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
claim.pools shipped with pool-aware claiming (#4843) and is described in
`bd config docs` (cmd/bd/config.go:78-88) and on `bd update --claim`, but
docs/reference/configuration.md never mentions it, so a reader of the
published configuration page cannot find the key or learn where its
value has to live.
Add a claim.pools row to the Project-Level Settings (Database) table and
a short "Claim Pools" subsection at the end of that section. Each
statement follows the code on main:
- The value is read only from the database config table
(ClaimPoolAliasesInTx -> GetConfigInTx, internal/storage/issueops/
claim.go:310-315, config_metadata.go:25-35; cmd/bd/show_unit_helpers.go:58,70).
A config.yaml value is listed by `bd config show` as (config.yaml) but
does not make an alias claimable.
- Entries are comma-split and whitespace-trimmed (ParseClaimPools,
claim.go:323-331); membership is an exact, case-sensitive string match
(claim.go:91, internal/validation/issue.go:217).
- A pool-assigned issue is claimed through the normal CAS, which grants
the normal lease (claim.go:91, :202).
- Real-actor and unlisted-alias assignees keep anti-steal protection.
- `bd assign` / `bd update --assignee` skip the reassign fence for a
pool-held in_progress issue (validation/issue.go:217; cmd/bd/assign.go:76,
cmd/bd/update.go:504).
- `bd ready --claim` claims only unassigned issues (claim.go:256).
- An expired lease is reclaimed to open with no assignee
(internal/storage/issueops/lease.go:759), not back to the pool alias.
Fixes#6607
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Forward-ports the 38 commits that shipped on release/1.3.0 (tagged v1.3.0 at
f45b249ce) into main, as RELEASING.md mandates after a tag. None of them had
ever been forward-ported. Recorded as a merge so main becomes a superset of
the release branch and the lineage is in the history.
Migration ordinal collision (the reason this needed a human-shaped merge):
both branches independently claimed clone-local ignored slot 0026 under
different filenames, so git merged both in with no conflict and left the
series with two migrations at ordinal 26 — a single-integer cursor cannot
address that, and migrationSource.list() panics on it.
Main's ignored/0026_add_wisps_current_revision is renumbered to 0027.
Release's 0026_dep_rekey_dedup_marker is in the shipped v1.3.0 tag, so field
stores have already recorded it at 26 and it can never move; main's twin has
never shipped in any release, so it is the one that is free to move. 0027 was
unused in the ignored series (both sides topped out at 26).
This trips check-migration-hygiene.sh Check C (frozen migrations), which has
no exemption mechanism. That is expected and accepted: breaking the collision
requires a rename, and the ignored series' cursor table is itself dolt-ignored,
so its content hashes are clone-local and never participate in the cross-clone
ContentHashSkew comparison that Check C exists to protect. Main's 0067 body is
deliberately NOT edited for the same reason in reverse — it is main-plane and
its hash IS compared across clones.
Conflicts resolved:
CHANGELOG.md release's finalized [1.3.0] section kept
byte-identical; main's two unreleased
entries (#6023, #5859) moved up under
[Unreleased] where they belong
cmd/bd/init_safety.go union — release's added paragraph is
cmd/bd/init_safety_help.go accurate against the merged code (three
exit-12 sources, incl. init.go:3147)
internal/storage/uow/dolt_sql_provider.go
kept main's newProvider refactor AND
release's readOnly field/assertion;
newProvider gained readOnly: opts.readOnly
so release's read-through-refused-migration
behavior survives main's refactor
.github/workflows/main.yml single -timeout=30m per release's #6091
scripts/ci_workflow_test.go design (flag on the invocation, not in
matrix.test-flags); the shadowed 25m in
matrix.test-flags removed
scripts/migration-test/lib/versions.sh
union — main's darwin/arm64 corpus plus
release's v1.2.2 linux/amd64 entry
integrations/beads-mcp/uv.lock ruff 0.16.5 (release, newer); block is
internally consistent, uv lock --check ok
default.nix vendorHash left at main's value and is
KNOWN STALE — see below
Version stamp lands at 1.3.0 (main had been sitting at the previously-released
1.2.2, this project's between-releases pattern). check-versions.sh: 24/24.
Known follow-up: default.nix vendorHash. The merged go.mod/go.sum is a genuine
union (release's kin-openapi/oapi-codegen bumps + main's newer Dolt stack) and
matches neither side, so neither recorded hash is correct. It must be
regenerated with scripts/update-nix-vendorhash.sh. The repo's automatic fixer
(update-vendor-hash.yml) is dependabot-only and will not run on this PR.
The optional JSONL interaction sidecar at .beads/interactions.jsonl is
gated behind audit.enabled (default false, internal/config/config.go:245)
with a BD_AUDIT_ENABLED env override (internal/audit/audit.go:67-72), but
the key is absent from docs/reference/configuration.md, so there is no
documented way to discover it outside `bd audit` help text.
Two changes, both on the same page:
- Add an `audit.enabled` row to the Tool-Level Settings table covering the
default, the env var, what enabling it does, the fact that both
`bd audit record` and `bd audit label` refuse to write while it is off
(both go through audit.AppendIfEnabled -- cmd/bd/audit.go:103 and :146),
and the fact that issue history is recorded in the database regardless.
- Add `audit.*` and `storage-class.*` to the list of namespaces routed to
config.yaml. Both are in config.IsYamlOnlyKey's prefix list
(internal/config/yaml_config.go:118) but were missing from the doc; the
list now matches that prefix list exactly.
Reported by @treystout in #5904.
* fix(migration): vendor-neutral freeze marker discovery and exit code 14
The MIGRATION-FREEZE gate keyed on a gastown town root: findTownRoot walked
cwd ancestors for mayor/town.json and fell back to GT_TOWN_ROOT/GT_ROOT, and
the refusal told users to run `gt migrate thaw` — a CLI that does not ship
with bd. Key on the marker file itself instead: walk cwd to the filesystem
root looking for MIGRATION-FREEZE, with BD_MIGRATION_FREEZE_FILE as an
authoritative override (and therefore an opt-out). The on-disk contract is
unchanged, so a marker written at a town root — an ancestor of every rig cwd
— is still found with no configuration.
The refusal now names the marker's own path, so "remove that file" is always
actionable, and exits 14 (ExitMigrationFrozen) rather than 1 so scripts can
tell "someone is migrating, come back later" from a generic failure.
Fixes a real bug on the way: the root PersistentPreRunE called os.Exit(1)
from inside a function holding a live defer that closes the store and
releases the workspace gates. Both that call site and runImport now return
&exitError{ExitMigrationFrozen}; only CheckReadonly's void signature keeps
the documented flush-then-exit.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(migration): cover marker discovery, exit 14, and the returned refusal
The gate tests scaffolded a fake town root (mayor/town.json) in every
workspace; deleting that scaffolding is itself the vendor-neutrality proof at
setup level — the gate now keys on the marker file alone.
New coverage: an ancestor marker blocks a write in a nested workspace;
BD_MIGRATION_FREEZE_FILE is authoritative in both directions (existing file
freezes with no marker in the tree, missing file thaws despite one); the
refusal names the marker's real path and never prints a vendor-coupled
substring; bd import blocks too; an empty `touch`ed marker produces no
"(by )" artifact.
TestMigrationFreezeErrorReturnsInsteadOfExiting is the direct regression test
for the defer-skip bug — it calls the gate in the shape of the PersistentPreRunE
call site and asserts the caller's deferred cleanup ran. If the refusal ever
goes back to os.Exit, the test binary dies mid-run.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(configuration): document the migration freeze marker and exit code 14
Operators had no user-facing description of the freeze gate at all — the only
recovery instruction bd printed pointed at a CLI that does not ship with it.
Add a Migration Freeze section covering the marker filename, the ancestor
walk, the optional tab-separated payload, the BD_MIGRATION_FREEZE_FILE
override, and the exit code scripts branch on.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(migration): key the freeze on the target workspace, fail closed, cover the skip-store bypass
Review round on #6043. The gate had the right idea and the wrong anchor.
Target-workspace keying. Find walked the process working directory only, so
every invocation that names a workspace from outside it — BEADS_DIR=... bd
create, bd -C <dir> (which sets BEADS_DIR and never chdirs), a daemon or cron
with an unrelated cwd — walked the wrong ancestry and wrote straight through a
freeze. Find now takes the directories to cover and PersistentPreRunE passes
the resolved workspace; FindFrom walks a named tree without consulting cwd.
Skip-store bypass. init and bootstrap are in noDbCommands, so the root hook
returns before the gate and neither file calls CheckReadonly. bd init
--reinit-local destroyed and recreated the very database the marker protects,
exit 0, marker never read. Both now gate themselves, init at the one point
every destructive variant passes through (ahead of --proxied-server, which
reaches its writes without taking the init mutation gate at all).
Fail closed. A stat error on the marker or an ancestor read as "not frozen",
indistinguishable from the documented opt-out. Find now reports it and the
refusal says bd could not tell, rather than assuming an open workspace.
Marker hardening. Only a regular file is a marker (a directory named
MIGRATION-FREEZE no longer freezes a tree), the read is capped, markers found
by the walk in a world-writable sticky directory are ignored (/tmp: forgeable
by anyone, undeletable by the victim the refusal instructs), and the payload is
sanitized before it reaches a terminal. parse splits before trimming, so a
marker recording a reason but no operator keeps its fields instead of sliding
the timestamp into the operator slot.
One walk per invocation, hoisted into commandFreeze; PostRunE reads the same
answer and stands its own maintenance down, so a read run during a freeze no
longer leaves an auto-commit, tip metadata, backup, export or push in the
store being migrated.
Cobra no longer appends "Error: exit code 14" and a usage dump to the refusal
on the commands that set neither Silence flag.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(migration): add the probe and targeted-gate entry points, with coverage
migrationFreezeActive is the silent probe for diagnosis paths that keep
running while frozen but must skip their own writes; migrationFreezeErrorFor
refuses against a workspace the command was handed rather than the one it was
launched in. Both are the surface the doctor-gate work (#6056) already calls,
under the names and signatures it expects, so that merge resolves errors.go to
this branch with its own callers untouched.
Covered by a test that pins both against the gate rather than leaving them as
uncalled code.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(migration): stop the tip-freeze test leaking process globals
recordTipShown's no-freeze branch records a pending tip write in
commandDidWriteTipMetadata/commandTipIDsShown — the same globals
PersistentPostRunE reads to decide whether to apply one. Leaving them set
handed TestPersistentPostRunE_ClearsOnErrorPath a pending write and a nil
store, which it dereferenced: a panic that only appeared in a full-package run.
Restore all three globals, and assert on both of recordTipShown's branches
rather than on whichever one the resolved dolt auto-commit mode selects — the
immediate-write branch is not the one taken once an earlier test in the
package has turned auto-commit on.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(migration): honor a symlinked freeze marker on the authoritative env path
The MIGRATION-FREEZE hardening keyed "is this a marker?" on os.Lstat +
IsRegular(), which is false for a symlink. A marker that is a symlink --
including one named by the authoritative BD_MIGRATION_FREEZE_FILE -- was
therefore read as "not frozen" and writes proceeded silently at exit 0:
a fail-open in the one gate that must never fail open (review Finding 1,
PR #6043).
statMarker now takes a `trusted` flag:
- On the operator-named BD_MIGRATION_FREEZE_FILE path it follows the link
with os.Stat and freezes when the target is a regular marker, so an
indirection like `current -> releases/N` works as intended.
- On the untrusted ancestor walk it still refuses to follow a symlink
(anything the walk passed through could otherwise redirect the gate),
but now emits a one-line stderr warning so the skip is visible instead
of a silent bypass.
Adds symlink coverage to freeze_test.go (env follows to a real marker,
dangling env symlink stays unfrozen, walk symlink is ignored with a
warning) and documents the regular-file requirement plus the env-path
symlink exception in the Migration Freeze reference.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* feat(lint): configurable per-type lint sections via lint.sections.<type>
bd lint, bd create --validate, doctor conventions, and markdown import all
check issue descriptions against built-in required sections that are
hardcoded per issue type. This adds a config knob:
bd config set lint.sections.epic "Standards scorecard, Cost"
- lint.sections.<type> holds a comma-separated list of section headings,
stored in config.yaml (yaml-only key, same path as validation.*).
- The list is ADDITIVE to types.IssueType.RequiredSections: built-in
requirements are never relaxed, only extended.
- Entries are normalized to "## <heading>" (any leading '#' run and
surrounding whitespace stripped) and deduped case-insensitively against
both the built-ins and each other, so re-declaring a built-in changes
nothing.
- Consumed in internal/validation.ValidateTemplate (the single choke point
behind LintIssue and every lint consumer) via mergeLintSections.
- lint.* is a recognized config prefix and documented in bd config and
bd lint help.
* docs(config): list the lint.* namespace and lint.sections.<type> in YAML-only keys
Address review feedback: the PR routes lint.* through config.yaml
(internal/config/yaml_config.go) but the YAML-only Keys section of
docs/reference/configuration.md did not list it. Add the namespace and a
one-line key description. (The pre-existing audit. and storage-class.
omissions are left as-is, out of scope for this PR.)
* feat(doltversion): own dolt CLI discovery, hardened probe, and version policy in a leaf package
PR-1 of the dolt CLI install/version contract (design:
mybd reports/2026-07-25-psxg4-dolt-cli-contract-design.md). The dolt
executable managed proxied-server mode spawns was discovered by a bare
exec.LookPath with no override, probed nowhere, and version-checked only
by one advisory archive_level probe; a missing binary erred after
.beads/ creation and an incompatible one died opaquely.
internal/doltversion (stdlib-only) now owns:
- resolution order BEADS_DOLT_BIN env > clone-local sidecar (hook point;
the sidecar itself lands with identity threading in PR-2) > PATH.
Explicit values are absolutized before validation (a bare name would
otherwise validate the cwd file but exec a PATH lookup) and an
explicitly-named broken binary is an error, never a silent
fall-through;
- a hardened probe: timeout + process kill, 64KiB output caps,
unconditional symlink resolution recording given and real paths,
errno-based exec-format diagnostics naming the likely arch mismatch,
and file identity captured for later change detection;
- version parsing generalized from the archive_level probe, tolerating
prerelease/dev suffixes;
- policy: NO hard version floor (adversarial review rejected 2.2.0 as
policy-without-evidence); RecommendedMin 2.0.0 warns only, backed by
the 2026-07-25 cross-version matrix run (cross-read of module-written
storage requires >= 2.0.0). An unparseable version string is likewise
a warning, not a refusal - the only hard failures are a missing,
non-executable, or probe-failing binary.
Wired at the two entry points: the managed proxied UOW factory replaces
its bare LookPath and derives archive-level support from the probe it
already ran (no second dolt-version fork on the per-command hot path;
warning is printed once, suppressed under --quiet/--json), and bd init's
proxied preflight fails before any .beads/ write when the binary is
missing or broken (external proxied config is exempt - bd never spawns
that server). doltserver.Start's own bare LookPath is deliberately
untouched here; identity threading through every spawn site is PR-2.
Agent-Signature: claude-fable-5-medium on behalf of matt wilkie
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AQHiBWVPSXDCcUSG9EGw9d
* fix(doltversion): fail closed on prerelease archive_level; dedupe dolt advisory
Two review findings on this PR (see reports/2026-07-26-reviewer-dispatch-sweep.md
#5092 for the adversarial-review reasoning):
1. archive_level fail-open regression (major, re gastownhall/beads#4986).
newManagedProxiedServerUOWProvider derived archiveLevelSupported straight
from doltID.Version.AtLeast(MinDoltVersionForArchiveLevelConfig), but
AtLeast deliberately ignores Version.Prerelease (by design, for the
separate warn-only RecommendedMin check). That meant a prerelease build
at or above the floor, e.g. "1.52.1-rc1", satisfied the >= 1.52.1 gate
and had auto_gc_behavior.archive_level written into the YAML — even
though the old doltVersionAtLeast (gc_config.go) already failed closed
for any prerelease-suffixed string via strconv.Atoi. If that prerelease
build predates the field, dolt sql-server's yaml.UnmarshalStrict refuses
to start: the exact #4986 regression. Extracted the derivation into
doltArchiveLevelSupported(id) and added a Prerelease == "" gate, plus
TestDoltArchiveLevelSupported (table test covering above/at/below the
floor and prerelease-at/-above-floor) and
TestDoltArchiveLevelSupported_UnparsedVersionFailsClosed.
2. Duplicate dolt-version advisory (major, UX). `bd init --proxied-server`
probed and printed the version-recommendation warning twice: once in its
own preflight (init_proxied_server.go) and again ~90 lines later when
newProxiedServerUOWProvider reaches newManagedProxiedServerUOWProvider,
which resolved+probed again. The existing doltVersionWarnOnce didn't
cover init's own Fprintf. Extracted one shared resolveAndProbeDolt(ctx,
errPrefix) helper (uow_factory.go) that does resolve + probe +
once-gated warn, called from both sites; init_proxied_server.go no
longer needs its own copy of the Resolve/ProbeWithPolicy/error-wrapping
sequence. This also folds the two call sites' warning gates (previously
!in.quiet vs !quietFlag && !jsonOutput) into one JSON-mode-safe gate.
Verified: CGO_ENABLED=1 go build -tags gms_pure_go ./... clean;
CGO_ENABLED=1 go vet -tags gms_pure_go ./cmd/bd/... clean; gofmt -l on all
changed files empty; targeted tests pass (TestDoltArchiveLevelSupported,
TestDoltArchiveLevelSupported_UnparsedVersionFailsClosed,
TestNewProxiedServerUOWProvider_RoutesExternalConfigToExternalProvider,
TestNewExternalProxiedServerUOWProvider_*, TestBuildProxiedServerClientInfo,
and internal/doltversion's own suite).
Agent-Signature: builder-unknown-model-unknown-reasoning on behalf of maphew
* test(doltversion): resolve symlinks in RealPath expectations (macOS fix)
TestProbeNormalOutput and TestProbeSymlink failed on macOS CI because
t.TempDir lives under /var/folders, itself a symlink to
/private/var/folders. Probe derives RealPath via filepath.EvalSymlinks,
so it correctly returned the /private/var form while the tests compared
against the raw TempDir path.
Map the expected path through the same EvalSymlinks resolution (new
resolveSymlinks test helper). Verified against a symlinked TMPDIR on
Linux, which reproduced the failure before this change.
Agent-Signature: claude-fable-5-high on behalf of maphew
* refactor(cmd/bd): narrow resolveAndProbeDolt to drop the unused identity return
Upstream removed the archive-level gate from proxied-server mode
(68afa3d51), which was the only consumer of the probed identity at these
call sites; returning it now trips unparam on the PR-introduced line.
PR-2's revalidation consumer re-widens the signature when it lands.
Agent-Signature: claude-fable-5-high on behalf of maphew
* fix(doltversion): cross-process probe cache, PATHEXT completion, daily warning dedup
Review fixes (all three MERGE-AFTER-FIXES items from the 2026-08-10 review):
1. The per-command `dolt version` fork on the store-open hot path is gone
for the steady state: ProbeWithPolicyCached fronts the fork with a JSON
cache in the user cache dir, keyed by the binary's (real path, size,
mtime) fingerprint - the exact fields Identity documents for caching.
A fingerprint hit costs a stat; any change to the binary re-probes.
Hard probe errors are never cached, and every cache failure direction
fails open to the uncached behavior.
2. Windows: an explicit BEADS_DOLT_BIN spelled without its extension now
completes via exec.LookPath's PATHEXT handling (exact spelled path wins
when both exist), and the behavioral tests run on Windows through .cmd
stubs instead of skipping wholesale - plus a focused windows-latest CI
job (test-windows-liveness pattern) so those branches actually execute
at PR time. skipOnWindows remains only where the subject genuinely
doesn't exist there (exec-bit check, symlink creation).
3. The old/unverifiable-version advisory now repeats at most once per day
(warn stamp in the same cache file) instead of on every bd invocation;
troubleshooting docs state the cadence.
Nits from the same review: Ctrl-C during the probe no longer prints the
misleading install hint (call site branches on context.Canceled); Probe's
stat branch now uses validateExplicitPath's not-found/not-executable
taxonomy split; ParseVersion documents its trailing-integer laxity and the
tightening required before part-2 enforcement.
Agent-Signature: claude-fable-5-high on behalf of maphew
* fix(doltversion): honor init's local --quiet for the advisory; defer sidecar claim in docs
Cross-vendor review follow-ups: bd init defines a local --quiet that
shadows the persistent flag, so resolveAndProbeDolt now takes quiet as a
parameter (init passes in.quiet || quietFlag) instead of reading the
global; and the troubleshooting entry no longer advertises the clone-local
sidecar resolution source, which is a part-2 hook not yet wired
(SidecarValue is always empty in this PR).
Agent-Signature: claude-fable-5-high on behalf of maphew
* test: stop the Windows counting stub double-counting forks
cmd.exe includes the space before a mid-line '>>' in the written text,
so the batch stub's 'set /p =x >> file' appended two bytes ('x ') per
invocation and forkCount — which counts bytes — read every fork as two.
All four Windows failures were exactly doubled expectations; the cache
itself hit and skipped forks correctly. Lead with the redirection so
exactly one byte lands per invocation.
Agent-Signature: claude-fable-5-high on behalf of maphew
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019CwiLhLbAGZdJtKYT76CPp
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Document the rollback of direct PostgreSQL and MySQL adapters because supporting additional general-purpose server databases adds operational and maintenance complexity. Our goal is to keep Beads as simple as possible and consume as few resources as possible.
Clarify that embedded Dolt, Dolt server, and SQLite remain supported, including Dolt server use of the MySQL wire protocol.
Existing PostgreSQL and MySQL databases are not opened or modified. Migration requires an export from a supporting build, reinitialization guided by bd help init-safety, and import; JSONL remains issue-level interchange rather than a complete backup.
Refresh generated CLI reference material alongside the storage guidance.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Test User
- FAQ: fix bulk migration/export commands (tracker pull/push need explicit
IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and
correct the cross-project isolation claim (hydration + external targets)
- quickstart: replace the broken DOLT.md blob URL with site links
- installation: Quick Install Script heading matches its macOS/Linux/FreeBSD
body
- rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles
- add description frontmatter to the 55 authored pages missing it
- docs.json: wildcard redirects for the old /next/ and version-prefixed
route spaces (1.0.0, 1.0.4, 1.0.5)
Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.
The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).
Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.
Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).
Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.
git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).
Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.
Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.