* 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(worktree): scrub inherited Git routing state
Establish CWD as the worktree repository boundary before discovery can consume inherited Git routing. Fence the startup config probe, clear routing in-process before root pre-run discovery, and retain command-owned subprocess scrubbing as defense in depth without changing PID or signal semantics.
Fixes#5531
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
* refactor(worktree): explain owned filtering and remove an unused shim
Document why filtering the fresh routing slice in place is safe and call
the shared routing-key classifier directly from tests. Retain the two
forwarders used by production worktree subprocess/removal paths.
Review: https://github.com/gastownhall/beads/pull/5623#pullrequestreview-5098421671
Bead: saa-cgh.23
Agent-Signature: unknown-model/unknown-reasoning
* fix(config): isolate identity and tracked-file Git probes from routing
Reuse the worktree routing owner for GetIdentity and isGitTracked so
explicit cwd/path selection is not displaced by inherited repository,
index or injected config state. Preserve identity precedence and the
tracked-secret refusal contract, with real target/decoy regressions.
Follow-up: https://github.com/gastownhall/beads/issues/6222
Dependency: https://github.com/gastownhall/beads/pull/5623
Reported-by: bee-ghosttrack
Bead: saa-cgh.93
Agent-Signature: unknown-model/unknown-reasoning
* fix(config): share subprocess key identity for Git routing (saa-cgh.93)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(exec): match Windows environment key identity (#5618)
Centralize os/exec-compatible environment-key comparison and use it for credential, metrics, Git-hook, trace, and repro subprocess filters. Preserve exact Unix semantics and Unicode near-collisions.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>
* test(execenv): exercise every environment operation under both host rules
Thread the host choice through narrow private helpers behind the existing
exported functions. Keep one normalization owner and retain native wrapper
tests; the additional table covers both host branches for equality, prefix
matching, last-wins lookup, filtering and input preservation.
Review: https://github.com/gastownhall/beads/pull/5672#pullrequestreview-5096948965
Bead: saa-cgh.78
Agent-Signature: unknown-model/unknown-reasoning
* test(execenv): exercise exported host policy wiring (saa-cgh.78)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* docs(worktree): explain startup Git environment scope (saa-cgh.23)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(config): isolate role commands from Git routing (saa-cgh.99)
Follow-up to bee-ghosttrack's review of gastownhall/beads#6322; refs #6357.
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(env): exercise shared key helpers on native Windows (saa-cgh.78)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* refactor(gitenv): share key parsing and normalize routing membership once (saa-cgh.93)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* docs(config): explain role command routing policy (saa-cgh.99)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(git): isolate domain role configuration from inherited routing (saa-cgh.109.5)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): probe the selected repository before configuring roles (saa-cgh.109.8)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* docs(init): explain role probe discovery ceiling behavior (saa-cgh.109.8)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): bind proxied tail Git operations to selected directory (saa-cgh.109.14)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(gitignore): preserve CRLF when appending project rules (saa-cgh.96)
Reported by bee-ghosttrack in gastownhall/beads#6343.
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(gitignore): pin detector edge cases and clarify append behavior (saa-cgh.96)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(gitignore): preserve line endings in Git exclude appends (saa-cgh.104)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(gitignore): clarify exclude fixture path variable (saa-cgh.104)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(gitignore): refuse exclude writes after read errors (saa-cgh.110)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* refactor(gitignore): share append byte composition (saa-cgh.105)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* docs(gitignore): explain append aliasing and trailing CR completion (saa-cgh.105)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* refactor(gitignore): use shared composition for exclude rules (saa-cgh.111)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(gitignore): omit the empty exclude leading separator (saa-cgh.112)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): bind exclude writers to the selected Git directory (saa-cgh.109.16)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(hooks): isolate tracked-file guard from Git routing (saa-cgh.98)
Follow-up to bee-ghosttrack's review of gastownhall/beads#6322; refs #6356.
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(hooks): retain legitimate inherited tracking context (saa-cgh.98)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(hooks): isolate trusted global configuration fixture (saa-cgh.98)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* docs(hooks): explain conservative tracked-file guard (saa-cgh.98)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* refactor(git): resolve hooks paths in an explicit read-only context (saa-cgh.109.17.1)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* Bind init hook operations to the selected repository (saa-cgh.109.17)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* Give the hooks tail fixture an explicit remote context (saa-cgh.109.17)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(git): canonicalize the hooks fixture repository root (saa-cgh.109.17.1)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): complete selected hook options and alias handling (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Clarify hooks resolver ownership and preserve work-tree diagnostics (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Explain restoration of absent routing variables in selected exclude tests (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Keep init role operations on the captured selected Git context (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Align selected-tail fixtures with captured role authority (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Identify the Git index behind tracked-hook refusals (saa-cgh.120.13)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(review): repair work-tree-less hook install and the fail-open secret guard
Maintainer adoption-review fixes for #6457 (iterations 1 and 2).
Blocking:
- cmd/bd, internal/git: `bd init` in a repository with no work tree stopped
installing hooks and printed "Failed to resolve git hooks".
git.ResolveHooksContext requires a work tree and deliberately errors without
one, so routing the selected-init path through it lost a capability base had
via beads.FindBeadsDir(). Add git.ResolveWorkTreelessHooksContext as the
explicit counterpart (empty RepoRoot/MainRepoRoot, relative core.hooksPath
anchored to the common directory) and fall back to it, so the install keeps
the selected, scrubbed context rather than the inherited one. It keys on "the
common directory resolved but the work tree did not", so it covers a bare
repository and a cwd inside a repository's own .git alike, and still refuses
non-repositories and directories inside a work tree. The `bare` and
`git_dir_cwd` rows in the hooks table test pin both shapes and assert the
install lands in the selected storage and configures the selected repository.
- internal/config: isGitTracked scrubbed Git routing with no fallback, so in a
checkout reachable only through legitimate GIT_DIR/GIT_WORK_TREE routing the
probe found no repository at all, the guard concluded "untracked", and
`bd config set <secret-key>` wrote the credential into a git-tracked
config.yaml where base refused. Give it the same two-probe shape as
hooks.gitTrackedFileContextWithEnv, with a legitimate-routing test.
- internal/config, internal/gitenv, docs: state the GIT_CEILING_DIRECTORIES
widening plainly rather than pairing it with a containment clause that is
false at every live call site. `-C`/cmd.Dir fixes where discovery starts, not
where it stops, so with the ceiling scrubbed the walk can reach a containing
repository above cwd; all three gitDirsForRepo call sites pass the process
working directory, which need not be a repository root. This mirrors the
wording init_proxied_server.go already had, so the tree no longer holds
contradictory statements about the same primitive.
- cmd/bd/config.go: the policy comment claimed all role commands ignore
inherited Git routing. Name the scrubbed paths without asserting a closed set
-- `bd config set/get/unset/set-many beads.role`, and the proxied-init role
tail, which goes through domain.GitUseCase.BeadsRole/SetBeadsRole and is
scrubbed on both of that repository's constructor arms -- and say that a path
which does not scrub still goes through the inherited environment: such readers
include internal/routing.roleFromGitConfig, RepoContext.Role,
doctor.CheckBeadsRole, `bd config show` and init.getBeadsRole; such writers
include init.setBeadsRole, `bd init --contributor` and `bd hooks --uninstall`.
The earlier wording framed the exception as role *resolution* only, which reads
as isolating the write plane when it is not isolated; a quantifier over "every
other" reader and writer goes stale in the opposite direction, since set-many
and the proxied-init tail are scrubbed, so neither list is exhaustive here.
Non-blocking:
- Scope the worktrees.md paragraph to the one startup probe that is scrubbed.
- Replace normalizeWorktreeGitEnvKey's ToUpper fold with execenv.KeyEqualForOS
so one subprocess key identity survives the PR.
- Compare beads.role against domain.BeadsRoleConfigKey with strings.ToLower
rather than strings.EqualFold, matching execenv.keyIdentityForWindows and
git's ASCII-only key folding, and pin it with Beads.Role/BEADS.ROLE rows
through GetConfig/SetConfig.
- Share the HooksContext workDir anchoring and symlink/case normalization
between both resolvers, so no producer of that type emits a spelling the
others do not.
- Branch the tracked-hook remediation hint on the proof label, so the inherited
case points at the routing rather than at `git rm --cached`.
- Restore the hook-status gate on the pure-JJ alias hint (base parity).
- Note that the boolean tracked-file wrappers are test-only.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(review): reconcile the beads.role scrub with base #6477 on the refreshed base
Refreshing onto main 511849496 pulled in cf683435e (#6477), which makes
domain/git GetConfig propagate Git's exit error instead of mapping every
*exec.ExitError to absence. That collides with this stack's beads.role scrub in
both directions, and neither lane's CI could see it: the PR lane builds against
a base where #6477's test does not exist, and main's lane never has the PR.
Only the merged tree fails (each half passes on its own side alone).
The test half is taken byte-identically from stack parent #6464, which already
pushed this resolution against the same base commit (head 0fe936944). Both PRs
target main with every parent still open, so a divergent-but-equivalent fix here
would collide in the same file when the stack lands; copying theirs means the two
auto-merge. Re-validated and re-mutation-proven here rather than assumed:
- TestConfig_ReadFailuresAreNotMissing drops its "invalid_routing_boolean" row,
whose poisoned GIT_CONFIG_NOSYSTEM can no longer reach git for beads.role
(IsRoutingKeyForOS scrubs the whole GIT_CONFIG* prefix for that key), and gains
TestConfig_BeadsRoleScrubsInheritedRoutingEnv, which pins both halves: the role
key ignores the poison, and a key outside the scrub (user.name) still surfaces
it as exit 128 rather than as an absent key. #6477's read-failure contract for
beads.role itself is untouched, still proved by malformed_config through the
repository's own config file.
- TestInitGitRepositoryUsesSelectedDirectory/captured_home asserted
require.NoError with the comment "The existing reader maps Git exit errors to
absence" -- the premise #6477 deleted. It now requires the exit-128 error,
which is itself the proof that the generic constructor read the *current*
caller environment: only that environment can see the planted .gitconfig.
Mutation proofs at this head: deleting the beads.role carve-out reds
TestConfig_BeadsRoleScrubsInheritedRoutingEnv; reverting #6477's classification
reds both that test and captured_home. So neither retargeted fixture is vacuous.
Also silence two gosec G702 findings that only appear with this branch present.
Unscoped `make ci-pr-lint` at CI's v2.10.1 pin scores 0 on the old base and 0 on
current main, 1 on the pre-refresh adopted head (cmd/bd/worktree.go:22) and 2 on
the refreshed head (+ cmd/bd/hooks.go:1823). pr.yml scopes golangci-lint to the
PR's own diff so it can never report them, but main.yml deliberately sweeps the
whole tree, so they would red main's Lint job on the first push after merge.
Production reachability is identical on all three trees, so this is taint
widening rather than a new call path. Both sinks run a fixed "git" binary with
constant subcommands, matching the justification at init_stealth.go:84.
cmd/bd/worktree.go is the only file this adds beyond the branch's own 50; #6464
does not touch it, so the annotation cannot collide with the parent either.
---------
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* fix(exec): match Windows environment key identity (#5618)
Centralize os/exec-compatible environment-key comparison and use it for credential, metrics, Git-hook, trace, and repro subprocess filters. Preserve exact Unix semantics and Unicode near-collisions.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>
* fix(worktree): scrub inherited Git routing state
Establish CWD as the worktree repository boundary before discovery can consume inherited Git routing. Fence the startup config probe, clear routing in-process before root pre-run discovery, and retain command-owned subprocess scrubbing as defense in depth without changing PID or signal semantics.
Fixes#5531
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
* refactor(worktree): explain owned filtering and remove an unused shim
Document why filtering the fresh routing slice in place is safe and call
the shared routing-key classifier directly from tests. Retain the two
forwarders used by production worktree subprocess/removal paths.
Review: https://github.com/gastownhall/beads/pull/5623#pullrequestreview-5098421671
Bead: saa-cgh.23
Agent-Signature: unknown-model/unknown-reasoning
* fix(config): isolate identity and tracked-file Git probes from routing
Reuse the worktree routing owner for GetIdentity and isGitTracked so
explicit cwd/path selection is not displaced by inherited repository,
index or injected config state. Preserve identity precedence and the
tracked-secret refusal contract, with real target/decoy regressions.
Follow-up: https://github.com/gastownhall/beads/issues/6222
Dependency: https://github.com/gastownhall/beads/pull/5623
Reported-by: bee-ghosttrack
Bead: saa-cgh.93
Agent-Signature: unknown-model/unknown-reasoning
* test(execenv): exercise every environment operation under both host rules
Thread the host choice through narrow private helpers behind the existing
exported functions. Keep one normalization owner and retain native wrapper
tests; the additional table covers both host branches for equality, prefix
matching, last-wins lookup, filtering and input preservation.
Review: https://github.com/gastownhall/beads/pull/5672#pullrequestreview-5096948965
Bead: saa-cgh.78
Agent-Signature: unknown-model/unknown-reasoning
* docs(worktree): explain startup Git environment scope (saa-cgh.23)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(execenv): exercise exported host policy wiring (saa-cgh.78)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(config): share subprocess key identity for Git routing (saa-cgh.93)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(config): isolate role commands from Git routing (saa-cgh.99)
Follow-up to bee-ghosttrack's review of gastownhall/beads#6322; refs #6357.
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(env): exercise shared key helpers on native Windows (saa-cgh.78)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* refactor(gitenv): share key parsing and normalize routing membership once (saa-cgh.93)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* docs(config): explain role command routing policy (saa-cgh.99)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(config): isolate role readers from inherited Git routing (saa-cgh.109.1)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(doctor): isolate role lookups from inherited Git routing (saa-cgh.109.2)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(git): isolate domain role configuration from inherited routing (saa-cgh.109.5)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(doctor): isolate explicit-path worktree fallback from Git routing (saa-cgh.109.6)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): probe the selected repository before configuring roles (saa-cgh.109.8)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(beads): cover common-directory role routing (saa-cgh.109.1)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(git): explain system config routing flags (saa-cgh.109.6)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* docs(init): explain role probe discovery ceiling behavior (saa-cgh.109.8)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(beads): scope stable worktree probes to selected path (saa-cgh.109.13)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): bind proxied tail Git operations to selected directory (saa-cgh.109.14)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* Clarify selected discovery probes and cover separate routing vectors (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Keep init role operations on the captured selected Git context (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Observe inline Git configuration directly in linked-worktree fixture (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Align selected-tail fixtures with captured role authority (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* fix(beads): select explicit directory discovery context (GH#6384) (saa-cgh.120.6)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* fix(gitenv): retain explicit Git config suppression (saa-cgh.120.7)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(config): pin identity under null config suppression (saa-cgh.120.7)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(gitenv): keep role authority off inherited config suppression
Maintainer review fixes for PR #6461 (adopt-pr iterations 1-2). Addresses the
three major findings raised against the contributor branch, plus the major,
three minors and nit that iteration 2 raised against the first fixup; each fix
is pinned by a test that was mutation-proved against the pre-fix source.
F1 (major, security) — the leaf exempts GIT_CONFIG_GLOBAL=/dev/null,
GIT_CONFIG_SYSTEM=/dev/null and GIT_CONFIG_NOSYSTEM from ScrubRouting. Null
suppression cannot redirect a read, but it can blind one, and DetectUserRole
answers a missed read with detectFromURL, whose no-remote and SSH arms both
return Maintainer. Reproduced on this branch: a global beads.role=contributor
with GIT_CONFIG_GLOBAL=/dev/null resolved to maintainer, where the leaf's
parent fb7a93ad4 scrubbed the entry and read contributor.
Taken the synthesis's alternative arm (a): keep the exemption where the value
has no authority, drop it where it does. New ScrubRoutingAndSuppression
applies at every beads.role reader — internal/routing, doctor/role.go,
config_show.go, RepoContext.Role, bd config get/set/unset/set-many, and the
domain adapter's key-specific arms (see A1: iteration 1 claimed that last site
and did not actually reach it). Arm (b), making roleFromGitConfig's miss
non-permissive, was declined: "no beads.role and no remote implies maintainer"
is documented base behavior for local projects, so closing it there would
reclassify every such user rather than the blinded slice this PR introduced.
F2 (major, blast radius) — the stack hardened every role reader and left four
writer/reader sites fully inherited, a divergence that did not exist at base:
an inherited GIT_DIR sends setBeadsRole's write to another repository while
the scrubbed readers look at the one the user is standing in. All four now
share the same boundary (init.go's getBeadsRole/setBeadsRole,
init_contributor.go, hooks.go's uninstall --get/--unset pair).
The required fix also asked for cmd.Dir = repoRoot on the init.go pair. Still
not taken, but not on the grounds iteration 1 recorded (see A2). What holds is
the measurement against the vector the fix targets: with GIT_DIR, GIT_WORK_TREE
and GIT_COMMON_DIR gone, no production path chdirs away from the invocation
directory — `grep -rn 'os\.Chdir' --include='*.go'` over production cmd/bd
returns nothing and `bd init` takes no path argument — so threading a repoRoot
through both signatures and their eight call sites buys no behavior change
against a redirect.
F3 (major, security) — this PR converted internal/config's isGitTracked probe
from inherited to scrub-only. The guard is fail-open by construction, so in a
legitimately routed checkout (bare repo.git, GIT_DIR/GIT_WORK_TREE exported,
no in-tree .git) the probe stopped answering and `bd config set
linear.api_key` would have written the credential into a tracked file.
Restored the two-probe shape sibling #6464 applied to the structural twin:
scrubbed probe first, inherited second, either "tracked" refuses.
F5 (minor) — disclose that scrubbing GIT_CEILING_DIRECTORIES widens upward
discovery rather than bounding it, in the worktree comment and the docs
paragraph that asserted only the narrowing effect. F2's fix extends that
trade-off to two more sites, so the disclosure is now load-bearing.
F7 (minor) — renamed isConfigSuppression to isConfigSuppressionControl and
documented why the NOSYSTEM arm is deliberately value-blind. Took the
rename/document arm rather than restricting the arm to git-true values, which
would have contradicted the PR's own pinned table.
F10 (nit) — pinned both suppression tables in the windows-latest required
list; verified each name matches the gate's grep exactly once.
--- Iteration 2 ---
The first fixup's F1 census named a site it did not reach, and its cmd.Dir
rationale named a mechanism that does not hold. Both are corrected here.
A1 (major, security) — the domain adapter's key-specific arm was guarded by
`key == "beads.role" && r.env == nil`, which is dead on the only production
role path: runInitProxiedServerTail rebinds the use case to
NewInitGitRepository whenever t.workDir != "" (its sole construction site
passes cwd), and that constructor captures ScrubRouting(os.Environ()) —
non-nil, suppression retained. The nil-env constructor has no
BeadsRole/SetBeadsRole caller, so the arm could only fire from tests, while
`bd init` under an inherited GIT_CONFIG_GLOBAL=/dev/null still missed a global
role, took hasRole=false, and persisted beads.role=maintainer into
repository-local config, where it outranks the global value for every later
read in a clean environment. Iteration 1 therefore left F1's escalation not
just alive but durable, on the one path the fix was supposed to close.
Fixed by keying the strict scrub on the config key alone and applying it to
whichever environment the repository already carries (roleAuthorityEnv). That
preserves capture semantics — NewInitGitRepository keeps its captured HOME,
the property git_test.go's captured_home case pins — and removes only the
suppression entries. Codex's alternative of rebuilding the constructor's whole
env was declined: it moves every key for no gain on this finding.
A2 (minor, contract fidelity) — iteration 1 justified declining cmd.Dir with
"repository selection is left to the working directory — the one input the
scrub keeps". That is false, and false in the file a future reader consults
before deciding whether to bound the pair: GIT_CEILING_DIRECTORIES is a routing
key too, so the scrub removes a bound rather than installing one. Measured from
a non-repository directory nested under a repository: `git config beads.role
<value>` fails "not in a git directory" while a ceiling below that repository is
inherited, and writes that repository's local config once the ceiling is
scrubbed. The decline itself stands, since the measurement behind it was made
against the GIT_DIR vector; getBeadsRole now records selection as the working
directory *or a containing ancestor*, which is also what makes
clearWorktreeGitRoutingEnv's existing cross-reference to "init's role probe"
true.
A3 (minor, consistency) — `bd config unset beads.role` and `bd config set-many
beads.role=` were the two spellings of that mutation still on ScrubRouting, in
the same file as the two that moved. Both measured inert: `git config <key>
<value>` and `--unset <key>` target the repository-local file, which the
suppression variables cannot select. Moved for parity rather than annotated,
because a divergence inside one file is how the next one starts.
Test evidence (minor) — the writer pair's two subtests both pass on the
redirect alone, so downgrading getBeadsRole back to ScrubRouting left them
green even though suppression is the load-bearing half at those sites
(init.go treats a getBeadsRole miss as permission to write a default role).
Added a global_null blinding subtest with the same unblinded fixture guard.
A4 (nit) — doctor/role.go's isGitRepo was the last probe in that file on the
suppression-retaining scrub, and it gates the "beads.role not configured"
warning. rev-parse is config-sensitive through safe.directory, which lives in
global config, so a retained GIT_CONFIG_GLOBAL=/dev/null can downgrade that
warning to "N/A (not a git repository)". Moved onto the same boundary as its
two siblings. As the finding records, the safe.directory precondition was not
reproduced end to end; the change is uniformity within the file.
Tests. Every pin reds only on its own defect:
- routing: reverting to ScrubRouting reds only the blinded-read subtest; the
unblinded fixture guard and the PR's inject-vector table stay green.
- gitenv: keeping suppression reds 10 of 16 new subtests, none of the PR's.
- cmd/bd: restoring the inherited env reds both redirect subtests and names
both halves ("the write did not land where bd is standing" / "an inherited
GIT_DIR captured the write"), while the PR's own role roundtrip stays green
— it followed the same redirect on both sides, so it never saw this.
- config: the two arms are proved separately. Scrub-only reds only the
legitimate-routing subtest; inherited-only reds only the poisoned-routing
subtest, so the new fallback cannot be read as a way around the scrub.
- domain/git (A1): restoring the r.env == nil provenance guard reds
global_null only; unblinded stays green, and no other test in the package
moves — which is the same measurement that confirms the arm had no coverage
before this iteration.
Deferred to follow-up, recorded for the approval summary: F4 (delete
isRoleGitRepo and resolve the dead else-if), F6 (user.name degrading to
hostname, which needs the PR's own subtest re-pointed), F8 (execenv fold
divergence), F9 and F11 (GetIdentity hostname degradation under inherited
suppression). F9's mechanism is confirmed — identity supplied only via
GIT_CONFIG_COUNT is lost when GIT_CONFIG_* is stripped, git reports "Please
tell me who you are", while GIT_AUTHOR_*/GIT_COMMITTER_* survive — but its
"leave artifact commits on the inherited environment" arm would re-open the
GIT_DIR redirect this PR's tail swap closed, and the non-regressing arm
(re-injecting inline identity pre-scrub) is a design change with no observed
victim in this repo.
Validation (iteration 2): internal/{gitenv,routing,storage/domain/git} full
packages green; cmd/bd/doctor full package run; targeted cmd/bd run over the
role, config and init blast radius green at 54 tests; go build ./... clean; go
vet plus CGO_ENABLED=0 and GOOS=windows CGO_ENABLED=0 vet clean on every
changed package. Remaining local reds are base-parity, each matching the
recorded cause: cmd/bd/doctor's seven (the launcher's global
beads.role=maintainer short-circuits CheckBeadsRole before isGitRepo is
reached, plus Dolt server availability) and
TestInitContributorSetsBeadsRoleContributor ("--contributor requires
interactive prompts", this session's stdin is not a TTY).
--- Iteration 3 ---
Iteration 3 reviewed 0220eed32 and approved it: claude filed no findings,
codex's six fix validations all came back correct, synthesis recorded
Decision: approve, and the scorecard scored 881/1000 with Required Changes:
None. The residual was two minors and a nit, none of them merge gates. All
three are taken here because they are comment-and-constant scope, so nothing
in the approved behavior moves.
B1 (minor, blast radius; codex filed it as major, demoted at synthesis) — the
isGitRepo() gate that decides whether the role pair runs is still fully
inherited while the pair it guards is now strict, so from a non-repository
directory with an inherited GIT_DIR the gate opens, the scrubbed read misses,
and the safety-net write fails "not in a git directory". Recorded at the
GH#2950 safety net rather than restructured, for the three reasons the
demotion rests on. The achievable outcome is base parity: sync_git.go is
byte-identical at base and the pair was inherited there too, so a GIT_DIR
holder already reached Maintainer before this PR — more directly, by pointing
at a repository whose beads.role is maintainer. The failure is not silent:
init prints "Warning: failed to set beads.role" unless --quiet, and every
later detection prints "beads.role not configured (GH#2950)" with two Fix
lines. And the prescribed roleRepoAvailable() gate provably does not close it:
all five gate sites are bare `if isGitRepo()` with no else, so a strict gate
answers false in exactly the described band, nothing is written, the role
stays unset, and detection still falls to detectFromURL. The optional
hardening is therefore declined rather than deferred — it would delete a
warning and change no role — and the comment says so, so the next reader does
not mistake a gate change for closing the fail-open path.
B2 (minor, contract fidelity) — the getBeadsRole rationale iteration 2 wrote
to close A2 introduced a new overstatement in its closing sentence: "bd init
takes no path argument — the residual is upward discovery from an unintended
cwd, not a redirect". `bd -C <dir>` is a redirect and takes no path argument.
Verified in tree rather than from the finding: applyChangeDirSelection
(main.go) resolves the target's .beads dir and sets BEADS_DIR with no chdir,
it runs from the root PersistentPreRunE ahead of every init-related early
return in that hook, and init honors BEADS_DIR for workspace selection — so
`bd -C other init` acts on other/.beads while the pair reads and writes
beads.role in the invocation repository. init.go's own "PersistentPreRun
doesn't run for init command" note is about the later skipsStoreInit return,
not about -C, which is what made this vector easy to miss twice. Reachability
is bounded: -C requires an existing beads project at the target, so the
pairing arises on re-init rather than first init. Comment narrowed to name the
residual; threading init's resolved project root through the pair is the
stronger arm and stays out of scope as a behavior change.
B3 (nit, architectural consistency) — the adapter selected the role-authority
boundary on a bare "beads.role" literal while the use case passed the
unexported beadsRoleConfigKey, two spellings of one contract the compiler
could not couple. Exported it as domain.BeadsRoleConfigKey and compared
against it at both adapter arms; no new import edge, since package git already
imports domain. Mutation-proved rather than asserted: replacing the
comparison with the case-variant "Beads.Role" the finding names reds
TestInitGitRepositoryRoleIgnoresInheritedConfigSuppression/global_null alone
while unblinded stays green, so the drift the nit describes is caught by an
existing pin. The comparison is still exact, not case-folded: git config names
are case-insensitive, so a caller hand-writing a variant spelling would bypass
roleAuthorityEnv, but folding widens which keys take the strict environment
and no production caller passes anything but the const — a behavior change the
nit did not ask for.
Validation (iteration 3): go build ./... clean; go vet plus CGO_ENABLED=0 and
GOOS=windows CGO_ENABLED=0 vet clean on cmd/bd, cmd/bd/doctor,
internal/storage/domain, internal/storage/domain/git and internal/gitenv;
internal/storage/domain/... full packages green (domain, db, fs, git); targeted
cmd/bd role run green at 19 subtests with no skips
(TestBeadsRoleCommandsIgnoreInheritedGitRouting and
TestBeadsRoleWriterIgnoresInheritedGitRouting, including the suppression
subtest added in iteration 2); gofmt and git diff --check clean. Full cmd/bd is
still not run locally: it times out at base as well. The iteration-1 deferrals
are unchanged and still owed follow-up bead ids at finalize (F4, F6/F11, F8,
F9).
---------
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>
Co-authored-by: Bee <bee@ghosttrack.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* fix(worktree): scrub inherited Git routing state
Establish CWD as the worktree repository boundary before discovery can consume inherited Git routing. Fence the startup config probe, clear routing in-process before root pre-run discovery, and retain command-owned subprocess scrubbing as defense in depth without changing PID or signal semantics.
Fixes#5531
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
* refactor(worktree): explain owned filtering and remove an unused shim
Document why filtering the fresh routing slice in place is safe and call
the shared routing-key classifier directly from tests. Retain the two
forwarders used by production worktree subprocess/removal paths.
Review: https://github.com/gastownhall/beads/pull/5623#pullrequestreview-5098421671
Bead: saa-cgh.23
Agent-Signature: unknown-model/unknown-reasoning
* fix(config): isolate identity and tracked-file Git probes from routing
Reuse the worktree routing owner for GetIdentity and isGitTracked so
explicit cwd/path selection is not displaced by inherited repository,
index or injected config state. Preserve identity precedence and the
tracked-secret refusal contract, with real target/decoy regressions.
Follow-up: https://github.com/gastownhall/beads/issues/6222
Dependency: https://github.com/gastownhall/beads/pull/5623
Reported-by: bee-ghosttrack
Bead: saa-cgh.93
Agent-Signature: unknown-model/unknown-reasoning
* fix(config): share subprocess key identity for Git routing (saa-cgh.93)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(exec): match Windows environment key identity (#5618)
Centralize os/exec-compatible environment-key comparison and use it for credential, metrics, Git-hook, trace, and repro subprocess filters. Preserve exact Unix semantics and Unicode near-collisions.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>
* test(execenv): exercise every environment operation under both host rules
Thread the host choice through narrow private helpers behind the existing
exported functions. Keep one normalization owner and retain native wrapper
tests; the additional table covers both host branches for equality, prefix
matching, last-wins lookup, filtering and input preservation.
Review: https://github.com/gastownhall/beads/pull/5672#pullrequestreview-5096948965
Bead: saa-cgh.78
Agent-Signature: unknown-model/unknown-reasoning
* test(execenv): exercise exported host policy wiring (saa-cgh.78)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* docs(worktree): explain startup Git environment scope (saa-cgh.23)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(config): isolate role commands from Git routing (saa-cgh.99)
Follow-up to bee-ghosttrack's review of gastownhall/beads#6322; refs #6357.
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(env): exercise shared key helpers on native Windows (saa-cgh.78)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* refactor(gitenv): share key parsing and normalize routing membership once (saa-cgh.93)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* docs(config): explain role command routing policy (saa-cgh.99)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): isolate role configuration from inherited Git routing (saa-cgh.109.3)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): use the selected origin in contributor setup (saa-cgh.109.7)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): isolate Git writes in planning repositories (saa-cgh.109.9)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(init): retain inherited planning commit author (saa-cgh.109.9)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): align embedded role gates with selected Git context (saa-cgh.109.12)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): scope embedded artifact Git operations to selected directory (saa-cgh.109.15)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(init): cover selected optional artifacts and explain refused commits (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Honor role-probe cancellation and exercise actual fork planning (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): warn when automatic contributor role write fails (saa-cgh.109.3)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(init): cover successful nonquiet contributor role writes (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Assert the automatic contributor setup banner alongside warnings (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* test(init): read persisted role routing from the store (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* fix(git): isolate domain role configuration from inherited routing (saa-cgh.109.5)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): probe the selected repository before configuring roles (saa-cgh.109.8)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* docs(init): explain role probe discovery ceiling behavior (saa-cgh.109.8)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): bind proxied tail Git operations to selected directory (saa-cgh.109.14)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(gitignore): preserve CRLF when appending project rules (saa-cgh.96)
Reported by bee-ghosttrack in gastownhall/beads#6343.
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(gitignore): pin detector edge cases and clarify append behavior (saa-cgh.96)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(gitignore): preserve line endings in Git exclude appends (saa-cgh.104)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(gitignore): clarify exclude fixture path variable (saa-cgh.104)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(gitignore): refuse exclude writes after read errors (saa-cgh.110)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* refactor(gitignore): share append byte composition (saa-cgh.105)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* docs(gitignore): explain append aliasing and trailing CR completion (saa-cgh.105)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* refactor(gitignore): use shared composition for exclude rules (saa-cgh.111)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(gitignore): omit the empty exclude leading separator (saa-cgh.112)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): bind exclude writers to the selected Git directory (saa-cgh.109.16)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* Explain restoration of absent routing variables in selected exclude tests (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Keep init role operations on the captured selected Git context (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Align selected-tail fixtures with captured role authority (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): write embedded excludes in the selected project (saa-cgh.120.11)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): scrub the fork auto-detect gate; scope the startup-scrub claims
Maintainer review fixup for PR #6462 (adoption review iterations 1-2).
Gating major — hardened startup probe with an unhardened twin
------------------------------------------------------------
config.gitDirsForRepo (internal/config/config.go:419-424) is scrubbed by this
stack, but its byte-identical database-path twin
beads.worktreeFallbackBeadsDirForRepo (internal/beads/beads.go:1054-1058) runs
the same `git -C <repoPath> rev-parse --git-dir --git-common-dir` for the same
purpose and is not. Two claims added in this range asserted the boundary was
universal:
- docs/reference/worktrees.md:15 "Startup Git discovery probes for every `bd`
command scrub inherited Git routing variables" (false universal)
- cmd/bd/worktree_cmd.go:712 "Startup config discovery applies the same
boundary to its one pre-hook Git probe" (false singular)
Both are narrowed here to name only the plane that is actually scrubbed, and to
state that the `.beads` database-discovery probes still honor inherited routing.
The review offered a code arm (scrub beads.gitOutput,
beads.worktreeFallbackBeadsDirForRepo, and internal/git/gitdir.go:32) as the
alternative. That arm is DECLINED for this leaf, measured rather than assumed:
- Open sibling PR #6461 already carries it. At refs/pull/6461/head,
internal/beads/beads.go:293 routes gitOutput through
gitOutputEnv(gitenv.ScrubRouting(os.Environ())) and :1069 sets
cmd.Env = gitenv.ScrubRouting(os.Environ()) in the ResolveBeadsDirForRepo
twin, with internal/beads/{beads,context}_test.go coverage. Our head has
zero gitenv references under internal/beads (grep control).
- internal/git/gitdir.go is restructured wholesale by open sibling PR #6464
(loadGitContext/ResolveHooksContext), which documents "Routing variables are
honored, not filtered" as a deliberate choice.
- internal/beads/ and internal/git/ are not among this PR's 47 files, so the
code arm would rewrite two functions an open, non-ancestor sibling is
already rewriting in files this PR does not otherwise touch.
The twin is filed as bd-p4che with the failure scenario, the three unhardened
sites, the required decoy test, and the #6461 merge-order note, so the work is
tracked whether or not #6461 lands.
Minor — fork auto-detect gate left on inherited routing
------------------------------------------------------
cmd/bd/init.go:2002 gated the fork auto-detect block on the unscrubbed
isGitRepo() while the same single hunk hardened three setupForkExcludeAt(cwd, …)
call sites around it, and five sibling role gates in this PR already use the
scrubbed isInitRoleGitRepo(ctx). Under the invalid inherited GIT_DIR this PR's
own matrix uses, that gate returns false in a real fork clone and silently
suppresses the whole block — prompt, non-interactive auto-configure, and the
hardened writer at :2007/:2019. Switched to isInitRoleGitRepo(ctx) (same argv,
plus the scrub).
Pinned by a new fork_auto_invalid row in
TestEmbeddedInitSelectedExcludeRouting: it drops --setup-exclude so the exclude
write is reachable only through the gate, adds an upstream remote so the
already-scrubbed detectForkSetup reports a fork, and keeps --role=maintainer so
autoConfigureForkContributor stays an early return and the gate is the only path
that can add the pattern. The row carries the same fixture guard the sibling
role test uses, asserting the inherited probe really is refused.
Mutation-proved: with the gate reverted to isGitRepo() and the row in place,
only fork_auto_invalid fails ("selected exclude = "# owned project
exclude\nkeep-me/\n"; want ... "**/RECOVERY*.md"") while all six incumbent
subtests stay green — so the row adds coverage rather than duplicating an
existing fixture.
Not taken (non-gating, recorded so the next pass grades the call rather than
re-filing it)
----------------------------------------------------------------------------
- per-key `beads.role` scrub inside the generic accessor
(internal/storage/domain/git/git.go:110,133): the constructor contract it
straddles is owned by the parent legs; #6464 also edits this file.
- splitting gitenv.routingKeys into redirect vs fence sets
(internal/gitenv/routing.go): the class was filed on the parent PRs and the
set is shared by the whole family; changing it here would fork a primitive
five open branches consume.
- deleting the three zero-caller wrappers in cmd/bd/init_stealth.go:
cmd/bd/init_stealth.go is concurrently rewritten by open sibling #6461,
which does not carry this leg's setupStealthModeAt/setupGitExcludeAt split
(base 566c84ba8 greps 0 for those names; this head greps 5), so deleting
them here would conflict that rewrite.
Correction (iteration 2): the earlier reason for this bullet — "the file is
byte-identical across the open siblings at this head" — does not reproduce
and is withdrawn. git diff --name-only HEAD refs/adopt/pr6461 --
cmd/bd/init_stealth.go is NON-empty precisely because this PR created the
...At split; byte-identity with a sibling is only obtainable for siblings
that already carry this leg (empty against refs/adopt-pr-probe/6464). The
decision stands on the concurrent-rewrite reason above.
- nit, non-git `bd init` note (cmd/bd/init.go): no code change is owed on the
merits, which is its own reason rather than the execenv one it previously
borrowed. commitEmbeddedInitArtifacts (cmd/bd/init.go:3477-3483)
re-establishes the dropped repo gate as its own SCRUBBED
`rev-parse --git-dir` probe via initArtifactGitCommand (:3537-3541); only
the added stderr line is new.
- nit, unexporting execenv.KeyHasPrefixForOS: internal/execenv/execenv.go is
byte-identical to both siblings resolvable at this head
(refs/adopt/pr6461 and refs/adopt-pr-probe/6464 both diff empty), so
unexporting it here would fork a file they share.
Correction (iteration 2): the earlier "across all four open siblings"
quantifier overstated what is measurable — iteration 1's other two probe
refs no longer exist in this worktree, so the claim is scoped to two.
Iteration 2 (non-gating cleanup; no code, test, or behavior change)
------------------------------------------------------------------
The iteration-2 review found zero blockers and zero majors in this fixup's
delta and the quality scorecard decided approve. All three of its items were
documentation or record-keeping and are discharged here:
- Contract fidelity nit: the narrowed worktrees.md sentence had fixed WHICH
PLANE scrubs but kept the original's unconditional frequency ("on every
`bd` command"), while the probe its appositive names —
worktreeFallbackConfigPath — runs only under
`primaryConfigPath == "" && beadsEnvConfigPath == ""`
(internal/config/config.go:183). Reworded to separate the two: the scrub is
unconditional FOR THAT PROBE, and the probe itself is a fallback that runs
only when nothing earlier in startup already resolved a config path, with
an ancestor .beads/config.yaml or an explicit BEADS_DIR as the
short-circuits. Stated as a general condition plus examples rather than
swapping one unconditional claim for another. The review's suggested
wording cited internal/config/config.go:183; the line number is dropped
because no file under docs/reference cites Go line numbers (6 Go-path
mentions across that tree, none with :NNN) and a line citation in a doc
rots. The file reference is kept so the claim stays checkable.
- Release-safety minor: bd-p4che's required-fix section now also names the
two PROSE sites that assert the unhardened state (this worktrees.md
paragraph and clearWorktreeGitRoutingEnv's doc comment), with a
drift-proof `git grep "still honor inherited routing"` anchor, because its
close-out instruction previously named only the three code sites. If #6461
merges first, it adds the byte-for-byte pre-image of this paragraph at the
same location, so this fixup's hunk applies CLEANLY and would leave the
falsified wording behind silently; nothing in CI pins the file (absent from
scripts/check_doc_freshness_test.go). Only that merge order is silent, and
the direction is safe either way since stale wording under-claims
protection.
- Debuggability nit: the two "Not taken" bullets above are corrected, see the
inline "Correction (iteration 2)" notes.
Validation
----------
- git diff --check clean; go build + go vet ./cmd/bd ./internal/config green.
- 25 blast-radius cmd/bd tests green with BEADS_TEST_EMBEDDED_DOLT=1 and
BEADS_TEST_REQUIRE_EXCLUDE_PERMISSION=1 (exclude/stealth writers, fork
auto-detect, init-role and worktree routing), incl.
TestEmbeddedInitSelectedExcludeRouting 7/7. The one skip
(TestInitPromptNonGitRepo) is the pre-existing "Dolt test server not
running" opt-in.
- An initial run showed 21 reds at 0.00s from a concurrent session sweeping
the shared /tmp/beads-bd-tests-* root; all pass under an isolated TMPDIR.
- Iteration 2 touches one Markdown file and no Go source, so the code
validation above still stands at this tree: git diff --name-only for the
iteration-2 delta is docs/reference/worktrees.md alone. git diff --check
clean. worktrees.md is not in scripts/check_doc_freshness_test.go's
freshnessDocuments and is named by no workflow, Makefile target, or test,
so no gate covers it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(git): reconcile role-config tests with the preserved read-error contract
Base advanced 11 commits during finalize and #6477 ("preserve config read
errors instead of treating them as absent", cf683435e) landed in the one
package this PR co-edits, internal/storage/domain/git. The rebase was clean
and no production code conflicts, but the two changes falsify each other's
test expectations in opposite directions:
- #6477's invalid_routing_boolean row injects GIT_CONFIG_NOSYSTEM to force a
beads.role read failure. This PR scrubs routing for beads.role, and
gitenv.IsRoutingKeyForOS classifies every GIT_CONFIG* key as routing, so the
injector can no longer reach that read. Retarget the row to test.marker so it
still proves a routing-induced failure is surfaced rather than swallowed, and
narrow the BeadsRole propagation assertion to malformed_config, which breaks
the repository's own config and is therefore immune to the scrub. Add a
positive pin that beads.role now resolves as absent without error under the
same poison.
- This PR's captured_home asserted NoError on the strength of "the existing
reader maps Git exit errors to absence", which is exactly the contract #6477
removed. Expect the error instead, matching the adjacent assertion that the
inherited writer fails on the same broken HOME.
#6477's guarantee is unchanged: the merged GetConfig keeps its classification
block and still uses cmd.Output(), which is what populates exitErr.Stderr.
Only this one injector for this one key stopped producing a failure.
internal/storage/domain/git 45/45 pass; removing the scrub from GetConfig makes
the new pin fail, so it is non-vacuous. cmd/bd blast radius 28/28 pass with
BEADS_TEST_EMBEDDED_DOLT=1, covering all six base-added init/temp-root tests.
---------
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <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(worktree): scrub inherited Git routing state
Establish CWD as the worktree repository boundary before discovery can consume inherited Git routing. Fence the startup config probe, clear routing in-process before root pre-run discovery, and retain command-owned subprocess scrubbing as defense in depth without changing PID or signal semantics.
Fixes#5531
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
* refactor(worktree): explain owned filtering and remove an unused shim
Document why filtering the fresh routing slice in place is safe and call
the shared routing-key classifier directly from tests. Retain the two
forwarders used by production worktree subprocess/removal paths.
Review: https://github.com/gastownhall/beads/pull/5623#pullrequestreview-5098421671
Bead: saa-cgh.23
Agent-Signature: unknown-model/unknown-reasoning
* fix(config): isolate identity and tracked-file Git probes from routing
Reuse the worktree routing owner for GetIdentity and isGitTracked so
explicit cwd/path selection is not displaced by inherited repository,
index or injected config state. Preserve identity precedence and the
tracked-secret refusal contract, with real target/decoy regressions.
Follow-up: https://github.com/gastownhall/beads/issues/6222
Dependency: https://github.com/gastownhall/beads/pull/5623
Reported-by: bee-ghosttrack
Bead: saa-cgh.93
Agent-Signature: unknown-model/unknown-reasoning
* fix(config): share subprocess key identity for Git routing (saa-cgh.93)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(exec): match Windows environment key identity (#5618)
Centralize os/exec-compatible environment-key comparison and use it for credential, metrics, Git-hook, trace, and repro subprocess filters. Preserve exact Unix semantics and Unicode near-collisions.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>
* test(execenv): exercise every environment operation under both host rules
Thread the host choice through narrow private helpers behind the existing
exported functions. Keep one normalization owner and retain native wrapper
tests; the additional table covers both host branches for equality, prefix
matching, last-wins lookup, filtering and input preservation.
Review: https://github.com/gastownhall/beads/pull/5672#pullrequestreview-5096948965
Bead: saa-cgh.78
Agent-Signature: unknown-model/unknown-reasoning
* test(execenv): exercise exported host policy wiring (saa-cgh.78)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* docs(worktree): explain startup Git environment scope (saa-cgh.23)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(config): isolate role commands from Git routing (saa-cgh.99)
Follow-up to bee-ghosttrack's review of gastownhall/beads#6322; refs #6357.
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(env): exercise shared key helpers on native Windows (saa-cgh.78)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* refactor(gitenv): share key parsing and normalize routing membership once (saa-cgh.93)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* docs(config): explain role command routing policy (saa-cgh.99)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): isolate role configuration from inherited Git routing (saa-cgh.109.3)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): use the selected origin in contributor setup (saa-cgh.109.7)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): isolate Git writes in planning repositories (saa-cgh.109.9)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(init): retain inherited planning commit author (saa-cgh.109.9)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): align embedded role gates with selected Git context (saa-cgh.109.12)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): scope embedded artifact Git operations to selected directory (saa-cgh.109.15)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(init): cover selected optional artifacts and explain refused commits (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Honor role-probe cancellation and exercise actual fork planning (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* fix(init): warn when automatic contributor role write fails (saa-cgh.109.3)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(init): cover successful nonquiet contributor role writes (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Assert the automatic contributor setup banner alongside warnings (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* test(init): read persisted role routing from the store (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Bind early embedded Git bootstrap to the selected project (saa-cgh.120.9)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* Create the owned separate-storage parent in the bootstrap fixture (saa-cgh.120.9)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(init,gitenv,config): maintainer fixup for #6459
Review iteration 1, blocking:
- cmd/bd/init_stealth.go: scope the fork exclude writer the way this PR
scoped the fork detector. detectForkSetup now scrubs inherited Git
routing, but resolveGitExcludePath still ran `git rev-parse
--git-common-dir` with no Dir and no Env, so with GIT_DIR inherited
toward another repository bd detected the fork in the selected repo and
then appended `.beads/`, `**/RECOVERY*.md` and `**/SESSION*.md` to the
*inherited* repository's .git/info/exclude - automatically, with no
prompt, in non-interactive mode. At base the two halves agreed (both saw
the inherited repo, found no upstream, wrote nothing), so the PR is what
creates the disagreement. Scrubbing the probe is the whole remedy: no
cmd/bd caller chdirs, so `repoPath == ""` already means the selected
project directory once inherited routing is gone. The new test asserts
both halves - the selected repo is written, the inherited one is
byte-unchanged - and reverting the scrub reds it while every existing
exclude test stays green.
- cmd/bd/config.go: the new comment claimed "All role commands ignore
inherited Git routing". Only bd config's own role paths were hardened -
routing.DetectUserRole, `bd config show`, `bd doctor` and `bd hooks
uninstall` still resolve beads.role through the inherited environment,
and beads.RepoContext.Role pins GIT_DIR/GIT_WORK_TREE last-wins but still
inherits GIT_CONFIG_*. So `bd config get beads.role` and `bd config show`
can disagree in one shell, and `bd config unset beads.role` and `bd hooks
uninstall` can target different repositories. Narrow the comment to the
command set it covers; widening the boundary to the deciders is a
separate, permissions-adjacent change. The same root cause is filed on
#6460 and #6464, where it is broader - fix it once, on whichever merges
first.
Review iteration 1, non-blocking:
- docs/reference/worktrees.md: the new prose claimed startup Git discovery
probes for every bd command scrub inherited routing. Only internal/config's
gitDirsForRepo does; internal/git's process-cached context does not. Narrow
the sentence to config discovery and name both sides.
- internal/gitenv/routing.go: say in the contract comment why
GIT_CEILING_DIRECTORIES is a routing key even though it narrows rather
than redirects, and disclose that removing it widens the upward search.
Pin the membership with a ceiling entry in the existing scrub table.
- cmd/bd/worktree_cmd.go: route the removal pass's key identity through
execenv.KeyIdentityForOS instead of the last hand-rolled fold. ToUpper is
the opposite direction from the shared primitive and provably
non-equivalent: on Windows it collapsed GıT_OPTIONAL_LOCKS (U+0131) onto
GIT_OPTIONAL_LOCKS and stripped an unrelated variable that
gitenv.ScrubRoutingForOS, one line earlier, keeps.
Validation: go build ./..., go vet, CGO_ENABLED=0 vet and
GOOS=windows CGO_ENABLED=0 vet all clean; internal/gitenv green; cmd/bd
filtered run green except TestGetNotionConfigReadsDBPathWhenStoreUnset and
TestConfigValidateReadOnlyIsHermetic, which fail identically at the
unmodified head. All three new pins mutation-proved.
Review iteration 2, non-blocking:
- internal/config/worktree_config_test.go, cmd/bd/init_git_bootstrap_routing_test.go:
finish the conditional half of iteration 1's GIT_CEILING_DIRECTORIES item.
That item offered "drop the key" or "keep it and say so - and if kept, add
a legitimate-ceiling case to the two cited tests". The docs arm was taken
but only one of the two tests got a case, and the half left unpinned is the
widening the new contract comment now promises. Both new cases set a
*legitimate* ceiling - an operator fencing off an ancestor - and assert the
scrub widens past it: startup config discovery still resolves the main
repository's shared config, and `bd init`'s bootstrap probe still resolves
the containing repository. Each carries a control that fails the test if the
ceiling did not bite, so neither can pass vacuously. Dropping
GIT_CEILING_DIRECTORIES from routingKeys reds both new pins while
TestWorktreeFallbackConfigPathIgnoresInheritedGitRouting and
TestSetupForkExcludeIgnoresInheritedGitRouting stay green, so they cover an
arm the poisoned-routing pins do not.
The review prescribed this assertion in the inverted direction ("a
fenced-off ancestor does not suppress the fresh git init"). Measured
against git 2.43.0: a ceiling at a repository root does fence off a probe
run from a subdirectory, so scrubbing it makes the ancestor visible and the
fresh `git init` is suppressed. The tests pin the measured direction.
- cmd/bd/init_stealth.go: the scrub makes resolveGitExcludePath's "not a git
repository" newly reachable from `bd init --setup-exclude` exactly where the
cause is interesting, but the probe's error was discarded. Thread git's own
reason through, reusing firstNonEmptyLine from sync_git.go, which already
exists for this failure shape. exec.ExitError.Error() is only "exit status
128", so a bare %w would have added nothing readable. The "not a git
repository" prefix is load-bearing - setupStealthMode matches it with
strings.Contains to treat this as a skip - and is preserved. Rendered:
Warning: failed to configure git exclude: not a git repository (inherited
Git routing is ignored here): fatal: not a git repository (or any of the
parent directories): .git
Validation (iteration 2): gofmt clean; go build ./...; go vet, CGO_ENABLED=0
go vet and GOOS=windows CGO_ENABLED=0 go vet clean on cmd/bd and
internal/config. Both new pins green and mutation-proved as described; the
nine existing cmd/bd exclude/routing/fold pins, the internal/config
worktree-fallback set, and the internal/gitenv and internal/execenv suites all
stay green. No production behavior change beyond the error text.
---------
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Julian Knutsen <julian@example.com>
* test(docs): red — Docs: init-safety re-clone playbook must say damaged stores go OUTSIDE data_dir and a fresh clone needs bd migrate schema (refs be-wv0d0)
* feat: green — Docs: init-safety re-clone playbook must say damaged stores go OUTSIDE data_dir and a fresh clone needs bd migrate schema (refs be-wv0d0)
- docs/recovery/init-safety.md: new re-clone-gotchas section covering both
live gotchas from ga-vrq5pu (damaged/set-aside stores must move OUTSIDE
data_dir; a fresh clone needs `bd migrate schema` for dolt-ignored
clone-local tables), with cross-reference pointers from the two existing
bd bootstrap mentions and a pointer (not a duplication) to bd doctor
--fix's automated corrupt-manifest convention. Freshness markers bumped.
- cmd/bd/init_safety_help.go: RECOVERY section of the init-safety Long help
gets a brief RE-CLONE GOTCHAS addendum with both symptom signatures and
the fix command.
- test/docsync/init_safety_recovery_test.go: retargeted
TestInitSafetyCLIReferenceCoversReCloneGotchas (written during RED) to
TestInitSafetyCLIHelpCoversReCloneGotchas, asserting on
cmd/bd/init_safety_help.go's Long field instead of the generated
docs/cli-reference/init-safety.md. That generated page is pinned to a
released bd (docs/cli-docs.pin = v1.2.2, built in a detached worktree per
scripts/resolve-docs-bd.sh) and does not pick up a Long-field edit at
HEAD until a maintainer bumps the pin at the next release — confirmed
empirically (`git show v1.2.2:cmd/bd/init_safety_help.go` still points at
the deprecated docs/RECOVERY.md path, and a full
./scripts/generate-cli-docs.sh run here produced zero diff to the
committed docs/cli-reference/). CI's own drift gate
(scripts/check-cli-docs-drift.sh) is blame-scoped for exactly this
reason. The original RED test was asserting on an artifact this PR
cannot legitimately change without fighting that pin.
* fix(docs): address review feedback on init-safety re-clone playbook
Three fixes per bee-ghosttrack's REQUEST-CHANGES on PR #6431:
- Correct Gotcha 1's "The fix" paragraph: bd doctor --fix's
corrupt-manifest repair renames the whole data_dir directory to a
sibling .<ts>.corrupt.backup path, not a backup nested inside the
database's own directory. Verified against
cmd/bd/doctor/fix/database_integrity.go and
cmd/bd/doctor/tracked_runtime.go.
- Replace the hardcoded "Schema already at v64" literal with
version-agnostic "Schema already at v<N>" in the doc and CLI help
text, and narrow the docsync test assertion to the prefix "schema
already at v" so it survives future version bumps instead of
rotting again.
- Drop the dead GitHub-issue-style link around ga-vrq5pu (a Gas City
bead id, not a GitHub issue) — keep it as plain text.
Ref: be-hobyw
* review: correct re-clone gotchas and tighten their guards (PR #6431 iters 1-2)
Maintainer review fixup for the adopted PR. This is a docs-only PR whose
entire deliverable is factual accuracy, so every finding here is about a
claim the doc makes rather than about code behaviour.
=== Iteration 1 ===
[major] Gotcha 1's "The fix" paragraph misattributed the automated repair
and pointed an operator mid-crash-loop at a path that cannot run. Verified
first-hand in the worktree:
- internal/doltserver/manifest_recovery.go:231-235 renames
<data_dir>/<db>/.dolt -> <db>/.dolt.<ts>.corrupt.backup, i.e. IN PLACE,
not the whole data_dir to a sibling as the doc claimed. It also only
fires behind nomsDirLooksCorrupt, whose own comment is "recovery only
fires when we can prove there is nothing the user would want to keep"
(:94-100) - so it never touches the superseded-but-populated store the
gotcha is about.
- The whole-data_dir -> sibling rename is a different fix:
cmd/bd/doctor/fix/database_integrity.go:35,43-45 over
getDatabasePath(beadsDir) (validation.go:15-21).
- That fix opens with serverModeIntegrityRecoveryGuard, which refuses
outright in Dolt server mode (:79-96).
Rewritten to state all three facts and to tell the reader plainly that the
move is theirs to make by hand. Kept the correct headline sentence. The
paragraph deliberately does not assert anything about where the in-place
backup lands under the legacy single-database layout (data_dir/.dolt), the
one premise the review left unproven - the wording is scoped to the standard
<data_dir>/<db>/ layout instead of minting a fresh unverified claim.
[minor] Gotcha 2's mechanism sentence ("bd's ordinary open does not recreate
them") is false for embedded mode: newStore -> initSchema (store.go:285,470)
calls schema.MigrateUp (:574), and migrationWorkNeeded returns true whenever
!ignoredSource.atLatest (schema.go:866-867) - and ignored_schema_migrations
is itself in doltIgnorePatterns, so a fresh clone always qualifies. Replaced
the universal with the actual condition. The replacement list of opens that
do NOT self-heal was itself wrong on its first item; see iteration 2 below.
The prescribed remedy was already correct and is unchanged.
[minor] The doc's prose Freshness source list gained cmd/bd/init_safety_help.go
but the enforcing DOCS array did not. Added to both scripts/check-doc-freshness.sh
and the pinned row in scripts/check_doc_freshness_test.go - a coupled pair:
editing only the script reds the pinned test with "Freshness source does not
name cmd/bd/init_safety_help.go" (verified by running exactly that mutation).
[nit] The docsync guard for the headline rule was two independent whole-file
substring checks. Scoped it to Gotcha 1's own section and matched the advice
as a phrase, and pinned both ends of the help text's #re-clone-gotchas
cross-reference, which neither markdown link checker can see because it lives
in a Go string. Five mutation legs, each reddening only its own assertion:
inverting the advice, moving the phrase outside the section, renaming the
heading, breaking the help anchor, and removing the Gotcha 1 heading. The
inversion leg is the one that matters - the file still contained "outside"
(2x) and "data_dir" (13x), so the old form stayed green on inverted advice.
[nit] Bumped Last reviewed: to the revision date.
=== Iteration 2 ===
Both lanes verified all five iteration-1 fixes. Three prose findings remained,
none a merge gate (scorecard: approve, Required Changes: none). All three are
the same defect class - a sentence that quantifies over a set the author did
not census - so each is fixed by removing the quantifier rather than by
restating it more carefully.
[minor] Gotcha 2's replacement enumeration was false on its first item: a
server, shared or proxied open DOES replay the clone-local series in this
doc's own scenario. Re-derived at head, both lanes independently:
- internal/storage/uow/dolt_sql_provider.go:267-287 calls
MigrateUpWithLock UNCONDITIONALLY on the non-team-server, non-preview
arm; p.readOnly is consulted only after a RemoteMigrateGateError comes
back (:288-296), so it cannot suppress the pass.
- The gate cannot refuse a main-current clone: PendingVersions is
mainSource.pendingVersions only (schema.go:525-527) and the gate
early-returns nil on len(pending)==0 (remote_migrate_gate.go:731-737),
so the ignored series is invisible to it.
- migrationWorkNeeded is true whenever !ignoredSource.atLatest
(schema.go:866-869), so the locked pass runs the full MigrateUp
including ignoredSource.migrate (schema.go:822). DoltStore.initSchema
reaches the same call on the writable-open path (dolt/store.go:3076).
So the positive clause is widened to any writable open (embedded, server or
proxied), and the negative clause is rewritten as a tautology plus an open
list: the open that hit the error was not self-healing, and the kinds that
skip or only verify "include" read-only/preview opens, team-server opens
(verifyTeamServerSchema only checks - dolt_sql_provider.go:342-371), the
preview-attach arm, and gate-refused opens. Each named arm was verified
individually; the list deliberately does not claim to be exhaustive, which
is what the previous wording got wrong. Nothing in docsync can enforce this
paragraph, so an open list is also the honest shape.
[minor] Gotcha 1's data_dir locator omitted the mode that overrides both
knobs it names. ResolveDoltDir checks IsSharedServerMode() FIRST and returns
SharedDoltDir() before it ever reaches projectDoltDirPath
(doltserver.go:316-330); the knobs are BEADS_DOLT_SHARED_SERVER=1|true or the
dolt.shared-server config key (:117-122), and the directory is
~/.beads/shared-server/dolt/, overridable via BEADS_SHARED_SERVER_DIR
(:248-257, :275-285). Added as its own paragraph rather than growing the
parenthetical, with the reason it matters most there: one shared data_dir
holds every project's database, so a single stray subdirectory crash-loops
the server for all of them.
[nit] "neither of bd doctor --fix's TWO Dolt-database repairs" made a numeric
claim the sentence does not need, and the count is wrong:
cmd/bd/doctor/fix/repo_fingerprint.go:135-161 os.RemoveAll's
cfg.DatabasePath(beadsDir) behind an interactive "This will DELETE %s. [y/N]",
and cleanCruftBeadsDirFiles (artifacts.go:238) can remove a .beads
subdirectory too when a redirect is expected. Dropping the word "two" would
have left "neither", which is itself a two-quantifier, so the count is
removed instead: "no bd doctor --fix repair performs this move here. The two
that come closest are:" - now a statement about the two bullets that follow,
not a census of the repairs. The operative universal survives the census
(the move-performing rename sites are only database_integrity.go:46,54; the
others delete or rename in place), so the reader's action is unchanged.
Validation (iteration 2): go test -tags=gms_pure_go ./test/docsync (8 tests,
green, zero skips, both InitSafety tests among them); go test -tags=integration
-count=1 -run Freshness ./scripts (33 pass, 1 Windows-only skip);
./scripts/check-doc-freshness.sh PASS with docs/recovery/init-safety.md at 0
days old and all five of its Freshness sources resolving; git diff --check
clean. Prose-only: no code, test or freshness-pair file changed this
iteration.
---------
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
* Accept uutils coreutils timeout in generated hooks
The generated hook selects a timeout helper only when its --version
banner starts with "timeout (GNU coreutils) ". uutils coreutils reports
"timeout (uutils coreutils) " with the same command line and the same
exit 124 on expiry, so hosts that ship it (Ubuntu 25.10+, NixOS with
uutils-coreutils-noprefix) silently fell through to the Perl alarm, or
to the unbounded direct run when Perl is absent. Follow-up from #5522,
tracked in #5541.
- Widen the identity allowlist to uutils; the match stays by banner so
Windows timeout.exe is still never probed (#5503).
- Add a backend-selection case using the GNU stub with the uutils
banner: fails on the old shim (selects gtimeout), passes with the
widening.
- Regenerate the managed sections in the tracked .githooks/* so
TestTrackedManagedHookSectionsMatchGenerator stays green.
- Update the hook-timeout passages in docs/reference/git-integration.md
and troubleshooting.md, which described the probe as GNU-only.
Verified on NixOS with uutils 0.10.0 as /run/current-system/sw/bin/timeout:
with Perl removed from PATH and a bd that hangs, the old shim runs
"without timeout" for the full duration; the new shim expires at
BEADS_HOOK_TIMEOUT and continues.
Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik
* Regenerate tracked .githooks managed sections with make githooks-regen
TestTrackedManagedHookSectionsMatchGenerator holds the managed section in
each tracked .githooks/* byte-equal to the cmd/bd/hooks.go generator, but
nothing regenerated them: after a generator change a contributor had to
splice the new section in by hand, and the failure only dumped both
texts. The v1.2.0 bump reddened main this way (ce20a64bb), and #6561 shipped
its first revision with the five hooks stale.
- BD_UPDATE_GOLDEN=1 makes the test rewrite the section in place, keeping
everything around the markers (the project's own hook logic) untouched.
Same switch the package's events golden already uses.
- `make githooks-regen` wraps it, next to `corpus-regen`.
- The drift failure now names that command.
- The exactly-one-section check runs before any rewrite.
Verified: drifting one byte inside .githooks/pre-push fails the test with
the hint; `make githooks-regen` restores the file to the same blob SHA;
the test is green again.
Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik
* Check the tracked hook shims against real timeout implementations
The Go tests pin the shim's helper selection with scripted stand-ins, so
they can only encode what the author believes each real `timeout` does.
That is where the last two defects lived: uutils prints a banner the
allowlist did not know (#5541), and busybox — which #5541 suggests
adding — exits 143 on expiry rather than 124, so allowlisting it would
turn every deadline into a failed hook and a blocked push.
checks.nix adds a flake check that runs the tracked .githooks/* managed
sections (held equal to the generator by
TestTrackedManagedHookSectionsMatchGenerator) against the binaries
themselves: GNU coreutils, uutils, busybox and toybox `timeout`, each
with and without perl, under dash, bash and busybox ash, for all five
hooks — 150 cases. Expectations come from a model of the contract (the
allowlist as data), so widening it is one line here and the binaries
either agree or they do not.
A fake bd on the shim's restricted PATH blocks on a held-open fifo until
a helper kills it, records the signal and re-raises it, so each case
asserts the backend that ran (TERM from timeout, ALRM from perl's alarm)
and not merely that the shim finished. No clock: a helper that fails to
kill the fake trips the harness's own `timeout 10`. Every case asserts
exit 0, since anything else blocks the user's push. Reading .githooks/*
instead of building bd keeps it at ~1 s and off the Go build's critical
path; CI's test-nix job runs it after its existing help-text smoke test.
Mutation-checked: restoring main's GNU-only sections fails all 30 uutils
cases (15 unbounded, 15 on the perl backend); allowlisting busybox with
a loosened probe fails all 30 busybox cases with hook exit 143.
Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik
* Run the hook-timeout check under the gtimeout candidate name too
The shim probes `timeout` and then `gtimeout`, but the matrix only ever
put a binary named `timeout` on PATH, so the second candidate was never
run against a real implementation. Whether a helper is accepted under
that name depends on what its banner does with argv[0].
Measured: the uutils multicall dispatches on the argv[0] SUFFIX
(src/bin/coreutils.rs, `binary_as_util.ends_with(util)`) and then prints
the canonical utility name — invoked as gtimeout it reports
"timeout (uutils coreutils) 0.8.0" (this flake's nixos-25.11 pin; 0.11.0
identical), which the allowlist accepts. busybox and toybox know no
gtimeout applet and fail the probe outright, rejected as before. GNU is
immune by construction: Homebrew's gtimeout is a separate binary whose
banner is the fixed "timeout (GNU coreutils) 9.11"; nixpkgs' coreutils
is a single-binary multicall that refuses a foreign name ("unknown
program 'gtimeout'"), so it gets no variant here.
Each multicall is now also installed on a case PATH as `gtimeout` ALONE
(`installs`, derived from `implementations`; `backendFor` stays keyed on
the implementation, so the model's claim is "uutils is allowlisted
whatever it is called"). 240 cases on Linux, 80 on darwin (no busybox or
toybox there, and no busybox-ash shell). The shadowed
`out=` inside run_case is `case_out` now: it only survived because every
case is a backgrounded subshell, and a de-backgrounded case would have
died on the final `touch "$out"`.
Mutation-checked: installing the variant as `xtimeout` (a name the shim
never probes) fails exactly the 30 uutils-as-gtimeout cases — 15 with
nothing killing the fake bd, 15 on the perl backend (ALRM) instead of
coreutils; restored, 240 of 240 pass. The busybox/toybox variants cannot
distinguish (their expectation is rejection either way); their weight is
that the probe does not blow up on a foreign name.
* Run the flake checks on main too, by nix flake check; docs wording
pr-risk.yml's test-nix job ran the hook-timeout check on PRs only; the
byte-identical job in main.yml never got the step, so post-merge main
never ran it. Both jobs now run `nix flake check -L`: no hardcoded
`x86_64-linux` (the step beside it, `nix run .#default`, was already
system-agnostic), and a check added to checks.nix runs without a
workflow edit. checks.aarch64-darwin and .x86_64-darwin evaluate.
Measured on ubuntu-latest with a cold Nix store (fork run 35700791032,
this tree, 240 cases): `nix flake check -L` 3.6 s including substitution
of uutils, busybox, toybox, dash and perl; 0.08 s warm — beside the
4 min 9 s the existing `nix run .#default` step spends building bd in
the same job. The 10-minute timeout is not in question.
git-integration.md: on Git for Windows the preferred deadline backend is
"a coreutils timeout (GNU or uutils)", not GNU alone, since both now
qualify. troubleshooting.md: reflow a ragged paragraph.
* review: close the duplicated contracts around the uutils timeout accept
Maintainer review fixes for #6561. No change to the shim's behavior or to the
generated/tracked hook sections.
- cmd/bd/hooks_timeout_process_test.go: the uutils fixture was built with
strings.Replace, which returns its input unchanged when the pattern is
absent, so a later edit to the GNU stub's banner would silently degenerate
the uutils case into a second copy of the GNU one — still green, no longer
testing the new accept. Hoist the derivation and fail loudly when the banner
no longer matches.
- cmd/bd/hooks_timeout_process_test.go: findHookProcessGNUTimeout held a second,
un-widened copy of the identity allowlist, so on exactly the hosts this PR
exists for (uutils timeout, no gtimeout) the only Go test that drives a real
timeout binary skipped with a reason the fix had just made false. Widen the
probe's case, rename it findHookProcessCoreutilsTimeout, and reword the skip
and the subtest. Measured against stub PATHs: uutils goes rc=1 -> rc=0, GNU
stays rc=0, a busybox banner stays rc=1.
- cmd/bd/init_hooks_test.go: TestGenerateHookSection_Timeout asserted only the
GNU alternative, so deleting the new uutils one from the generator left the
structural contract green (verified: it passes under that mutation before
this change, and reports "section missing uutils coreutils identity check"
after). Add the companion assertion.
- cmd/bd/init_hooks_test.go, Makefile: the regen arm rewrites tracked source
files, so give it its own BD_UPDATE_HOOKS_GOLDEN rather than the package's
shared BD_UPDATE_GOLDEN — an unscoped `BD_UPDATE_GOLDEN=1 go test ./cmd/bd/`
used to turn genuine hook drift into a silent working-tree rewrite that
reported PASS.
- cmd/bd/init_hooks_test.go: locate the managed section by marker prefix
instead of the versioned marker line. Tracked hooks drift both from generator
content and from the release version stamp; the exact-line lookup made the
second class fatal ("tracked hook missing ...") before the regen arm was
reachable, so `make githooks-regen` failed at exactly the moment a release
engineer reaches for it. The versioned markers are still verified — they are
part of the byte compare.
- checks.nix: the `rc -eq 124` safety-net verdict discarded both $case_out and
the already-captured $signal, so the one failure mode that is intermittent
and not locally reproducible was also the only one with no diagnostics.
Report them like the `rc -ne 0` branch below it.
- docs/reference/troubleshooting.md, docs/reference/git-integration.md: mirror
the coreutils wording across both docs this PR touches, and generalize the
re-install guidance in both. Managed sections are never reported Outdated
(getHookVersion returns IsShim for them and computeHookStatuses gates on
!IsShim), so nothing tells an existing install it is stale; the sentence was
still scoped to the older name-only check (#5503).
- CHANGELOG.md: add the [Unreleased] entry for #5541, worded to the actual
scope — with Perl installed the shim still reached the Perl alarm arm, so the
lost deadline bit uutils hosts without Perl — say that existing installs must
run `bd hooks install` once, and drop the claim that stock NixOS ships uutils
(this PR's own checks.nix takes GNU from pkgs.coreutils).
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* fix(exec): match Windows environment key identity (#5618)
Centralize os/exec-compatible environment-key comparison and use it for credential, metrics, Git-hook, trace, and repro subprocess filters. Preserve exact Unix semantics and Unicode near-collisions.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>
* fix(worktree): scrub inherited Git routing state
Establish CWD as the worktree repository boundary before discovery can consume inherited Git routing. Fence the startup config probe, clear routing in-process before root pre-run discovery, and retain command-owned subprocess scrubbing as defense in depth without changing PID or signal semantics.
Fixes#5531
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
* refactor(worktree): explain owned filtering and remove an unused shim
Document why filtering the fresh routing slice in place is safe and call
the shared routing-key classifier directly from tests. Retain the two
forwarders used by production worktree subprocess/removal paths.
Review: https://github.com/gastownhall/beads/pull/5623#pullrequestreview-5098421671
Bead: saa-cgh.23
Agent-Signature: unknown-model/unknown-reasoning
* fix(config): isolate identity and tracked-file Git probes from routing
Reuse the worktree routing owner for GetIdentity and isGitTracked so
explicit cwd/path selection is not displaced by inherited repository,
index or injected config state. Preserve identity precedence and the
tracked-secret refusal contract, with real target/decoy regressions.
Follow-up: https://github.com/gastownhall/beads/issues/6222
Dependency: https://github.com/gastownhall/beads/pull/5623
Reported-by: bee-ghosttrack
Bead: saa-cgh.93
Agent-Signature: unknown-model/unknown-reasoning
* test(execenv): exercise every environment operation under both host rules
Thread the host choice through narrow private helpers behind the existing
exported functions. Keep one normalization owner and retain native wrapper
tests; the additional table covers both host branches for equality, prefix
matching, last-wins lookup, filtering and input preservation.
Review: https://github.com/gastownhall/beads/pull/5672#pullrequestreview-5096948965
Bead: saa-cgh.78
Agent-Signature: unknown-model/unknown-reasoning
* docs(worktree): explain startup Git environment scope (saa-cgh.23)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(execenv): exercise exported host policy wiring (saa-cgh.78)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(config): share subprocess key identity for Git routing (saa-cgh.93)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(hooks): isolate tracked-file guard from Git routing (saa-cgh.98)
Follow-up to bee-ghosttrack's review of gastownhall/beads#6322; refs #6356.
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(config): isolate role commands from Git routing (saa-cgh.99)
Follow-up to bee-ghosttrack's review of gastownhall/beads#6322; refs #6357.
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(env): exercise shared key helpers on native Windows (saa-cgh.78)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* refactor(gitenv): share key parsing and normalize routing membership once (saa-cgh.93)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* docs(config): explain role command routing policy (saa-cgh.99)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(hooks): retain legitimate inherited tracking context (saa-cgh.98)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(hooks): isolate trusted global configuration fixture (saa-cgh.98)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(hooks): isolate role cleanup in the selected repository (saa-cgh.109.4)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(hooks): reset only common local role configuration (saa-cgh.109.10)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(hooks): scope hooks-path cleanup to selected common config (saa-cgh.109.11)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(hooks): make worktree role preservation independent (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* Report selected config read failures during hook reset (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* fix(hooks): keep successful config stdout separate from diagnostics (saa-cgh.120)
Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* fix(config): pin role writes to fresh common context (GH#6384) (saa-cgh.120.3)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(config): retain Git diagnostics from role writes (saa-cgh.120.3)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* test(config): assert the actual Git lock diagnostic (saa-cgh.120.3)
Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell
* fix(config,hooks): restore the inherited-tracking fallback in the secret guard
Maintainer review fixes for PR #6454 (adopt-pr iteration 1). The scorecard
approved at 913/1000 with no blocker or major surviving synthesis; these are
the non-gating findings that were cheap to close while the fixup was open.
Finding 1 (minor, security) is the only in-range regression in the report. The
range switched internal/config.isGitTracked from the inherited environment to
gitenv.ScrubRouting only, so a config.yaml tracked solely through legitimate
routing -- a bare repository whose work tree is named by GIT_DIR/GIT_WORK_TREE
-- reported untracked, and a secret-key write that upstream-base refused was
silently allowed. Restores the scrubbed-then-inherited union the same stack
already gave cmd/bd.isGitTrackedFile.
Finding 4 (nit) composes with it rather than conflicting, so both land as one
change: the inherited probe now runs only when the scrubbed probe failed for a
configuration reason. git's exit codes discriminate exactly -- 0 tracked, 1
repository reached but path untracked (final), 128 no reachable repository --
so the ordinary untracked-hook miss no longer spawns a second `git ls-files`
while the bare-work-tree fallback is preserved.
Finding 2 (minor). scrubWorktreeRemovalGitEnvForOS keyed its stricter
no-optional-locks policy on strings.ToUpper while the rest of the PR uses
execenv key identity. The two disagree in both directions on Windows:
GIT_OPTIONAL_LOCKS with a dotted capital I (U+0130) survived the scrub although
Git honors it, and GIT_OPTIONAL_LOCK with a long s (U+017F) was dropped
although os/exec keeps it distinct. normalizeWorktreeGitEnvKey is deleted in
favour of execenv.KeyEqualForOS. Base applied ToUpper on all platforms, so this
is a consistency fix in newly rewritten code, not a regression.
Finding 5 (nit). The comment above resetHooksPathIfBeadsManaged's probe
asserted that repoRoot and commonDir share the cached Git context. Probed
false: with cwd A and GIT_DIR=B/.git, `git rev-parse --git-common-dir
--show-toplevel` prints B/.git and A. Restated as intent.
Finding 3 (scrubGitHookEnv is a fifth, strictly weaker routing scrubber) is
deliberately not taken here: cmd/bd/export_auto.go is untouched by this range,
so the hazard is byte-identical at base, and the synthesis scoped it to a
follow-up bead rather than growing this stack.
Each fix is mutation-proved. Reverting isGitTracked reds only the new
TestSecretGitTrackingHonorsInheritedBareWorkTree -- including "refusal = <nil>",
the actual security consequence -- while the incumbent decoy test stays green,
so the pin adds coverage rather than duplicating it. Restoring ToUpper reds
only the new Windows row, showing both directions at once.
TestGuardHookWritePathHonorsInheritedRepository gains a fixture guard asserting
its scrubbed probe fails for a configuration reason rather than exit 1, so a
future fixture change cannot silently make the fallback unreachable.
scrubWorktreeRemovalGitEnvForOS had no test at all before this.
Green locally: ./internal/config, ./internal/execenv, ./internal/gitenv,
./internal/githooksenv, ./internal/gittraceenv, ./internal/metrics, ./scripts,
./internal/beads (the GIT_CONFIG_GLOBAL blast radius neither reviewer ran), and
a blast-radius cmd/bd run over the hooks, worktree, role and uninstall suites.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>
Co-authored-by: Bee <bee@ghosttrack.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.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>
* docs: add beady-eye to community tools
* docs: add beady-eye to community tools
* docs: add beady-eye to community tools
* docs: add beady-eye to community tools
* docs: add beady-eye to community tools
* docs: add beady-eye to community tools
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>
Post-merge review of #6658 (landed as 5b9e938b5) found two guidance defects
in the #6575 data-behind stop. The gate itself is correct; both are in the
remedy chain it prints.
1. The shared arm prescribed `bd migrate schema`, which cannot succeed in the
state that prints it. A data-behind refusal has a remote by construction —
behind-ness is read from `remotes/<name>/<branch>` — and the verb consent
(`sharedMigrateConsent`) has exactly one reader, inside `sharedNoRemoteGate`,
reachable only on the `!hasRemote` branch. So after the pull the retry routed
`smartAutoMigrate -> shared -> fallbackReasonSharedStore`, whose blunt body
prescribes the `bd migrate --force` the data-behind body explicitly says not
to use. The option, `dataBehindBody`, `AgentDirective`, `fallbackReasonNote`
and both `--global` retargets now name `bd migrate schema --force`, which
trips `forceOrEnvConsent` via `isForcedMigrate`.
Retargeting the command rather than widening the consent read is deliberate:
with a remote configured, #4259's cross-clone fork risk still demands the
designated-migrator confirmation, which is what `sharedNoRemoteGate`'s own
comment says the scoping is for.
2. The JSON payload's `docs` pointer stayed on the migrate-or-adopt anchor,
whose ordering rule says `bd dolt pull` is refused on every
pending-migration open — contradicting the `pull-first` option in the same
payload. The `IsDataBehind()` arm now points at a new "Clone behind the
remote" section, and the two living ordering rules (upgrading.md,
init-safety.md) record the exception.
Tests: the consent step is now checked by running it — the command is taken
from `Options()`, resolved through the same cobra lookup and predicates the
root pre-run uses, and fed to the real gate against a remote-backed shared
fixture, with the shipped bare verb as the counterfactual. Asserting the
option's wording is what let the dead command ship. `docs` is pinned in
`TestHandleRemoteMigrateGateJSON_DataBehind`.
Co-authored-by: Claude Opus 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.
* docs: supersedes is a replacement link, not a version chain
Reword the DepSupersedes comment (internal/types/types.go), the
`bd supersede` help text, and the graph-links doc: `supersedes` marks an
old issue as replaced by a different issue. It is not a version relation
and does not imply a version chain. The behavior is unchanged.
Promised on #5898 (Q8, quad341 revision 4): a replacement link, not a
version-chain link. docs/CLI_REFERENCE.md is pinned to v1.2.2 and picks
this up at the next release bump (generate-cli-docs.sh --check passes).
Wyvern bead wy-h4xd6f.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PvjeDsoyDfjptvjKZWzcqA
* docs: finish the supersedes rewording pass in graph-links + dependencies
Maintainer review fixup for PR #6212.
The PR's new assertion "This is a replacement link, not a version relation"
left the rest of graph-links.md still telling the version-chain story, so
the page contradicted itself. Each residual line is byte-identical to base,
but the contradiction is new with this commit. Extends the same wording pass
to the sites that actually assert version semantics:
- frontmatter description: "supersedes chains" -> "supersedes (replacement)
links" (this is the rendered page description)
- the example comment "# View shows the chain" -> "# View shows the
replacement"
- "### Version History" -> "### Replacement History" and "# bd-rfc3 is now
the current version" -> "# bd-rfc3 is now the live issue"
- Best Practice 4 "Document supersedes chains - Note why version changed" ->
"Document replacements - Note why the issue was replaced"
The use-case list ("Design document versions", "Artifact versioning", "RFC
chains") and "Track document evolution" are deliberately left alone:
chained replacements legitimately model document evolution without the link
itself being a version relation.
Also rewords the sibling core-concepts table, docs/core-concepts/
dependencies.md:56, from "Replaced by a newer issue" to "Replaced by a
different issue" so both hand-written pages frame the edge the same way.
No in-repo reference targets the renamed #version-history anchor.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
* release: prep v1.3.0-rc.2
Sanctioned RC bump per RELEASING.md "Cut an RC":
./scripts/update-versions.sh 1.3.0-rc.2
The Windows PE numeric fields (winres file_version/product_version and
the manifest <assemblyIdentity> version) stay at the base version 1.3.0
because PE versions must be purely numeric; the FileVersion/ProductVersion
strings carry the full 1.3.0-rc.2, and uv.lock carries the PEP 440
normalization 1.3.0rc2. scripts/check-versions.sh passes all 24 gates.
Also adds the three user-facing fixes found by testing rc.1 against
gascity to the [1.3.0] Fixed section: #6118 (an env-pointed server was
classified as workspace-owned, bypassing the shared-store migrate gate),
#6119 (a config.yaml server-mode workspace was refused as legacy), and
#6120 (a metadata-less server-mode workspace opened a phantom embedded
database and returned a false-empty list). #6121 is CI-only and takes no
changelog entry, matching #6091.
The [1.3.0] date is deliberately left alone — the stamp-changelog step
owns it at final-release time.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(release): complete the rc.2 rollup and add the info.go RC digest
Review fixups on top of the rc.2 prep. Two release-notes surfaces were
incomplete for this PR's own commit range, which grew when the prep patch
was rebased onto a base that already shipped #6269.
CHANGELOG rollup (gating). The `bd ready --claim` row-cap refusal sits under
`[Unreleased]`, which by Keep-a-Changelog semantics means it ships in no
release — but `git merge-base --is-ancestor 24a9da6cc HEAD` says rc.2 ships
the behavior, and it is the only breaking change in the range. Moved it into
`[1.3.0] ### Changed`, leaving `[Unreleased]` empty exactly as it was at the
`v1.3.0-rc.1` tag, and tagged it `(#6269)` so the rollup audit RELEASING.md
prescribes can identify its commit. This is the verbatim Release Checklist
item at RELEASING.md:150-153; `cmd/bd/info.go:227` points users at "the
[1.3.0] section", so section placement is the authoritative surface.
info.go digest. `versionChanges` had no RC entry, so `bd upgrade review` and
`bd info --whats-new` never surfaced #6118/#6119/#6120 to a 1.2.2 upgrader,
and the stale `1.3.0` SHARED SERVER item describes the #5920/#6048 gate
without the #6118 bypass fix. Added a `1.3.0-rc.2` entry per the
`1.1.0-rc.2` precedent (info.go:282), covering the three fixes plus the
ready-claim change, per RELEASING.md:154 and "Cut an RC" step 1. This also
stops the unknown-`since` fallback from dumping the whole release history at
an rc.2 user. Known residual: `1.3.0-rc.1` still has no entry, so an
rc.1->rc.2 upgrader keeps hitting that fallback; pre-existing, out of scope
for this bump.
Correction to the prep commit message: "the stamp-changelog step owns [the
CHANGELOG date] at final-release time" is not what that step does.
`.beads/formulas/beads-release.formula.toml:428-440` sed-inserts a new
`## [{{version}}] - $DATE` header beneath `## [Unreleased]`; it never
re-dates an existing section. With `## [1.3.0] - 2026-08-28` already dated,
running it at final release produces a duplicate `## [1.3.0]` heading. Final
1.3.0 prep must hand-restamp instead, or that step needs fixing first.
Validated: ./scripts/check-versions.sh 24/24 at 1.3.0-rc.2; go build/vet
./cmd/bd; go test ./cmd/bd -run
'TestVersionChanges|TestGetVersionsSince|TestDisplayVersion'; git diff
--check clean; `[Unreleased]` confirmed empty.
* docs(recovery): re-review init-safety playbooks; refresh the 90-day marker (#6411)
* docs(recovery): re-review init-safety playbooks; refresh the 90-day marker
The Last-reviewed marker crossed the 90-day freshness threshold on Sep 7,
turning 'Check doc flags freshness' (and with it PR Policy and the required
CI Gate) red for EVERY open PR — #6262 is merge-queued and UNSTABLE on
exactly this.
Reviewed against the declared freshness sources (init.go, init_safety.go,
init_safety_test.go, dolt.go), which changed materially since June
(notably the destructive-preflight replacement in #5310 and the
server-flag precedence work): the four playbooks' premises still hold —
--destroy-token/--reinit-local/--discard-remote all exist and are the
refusal remedies, the force-refusal-on-origin-history invariant is intact,
and the pk-fork-refused deep link from dolt.go:416 resolves. One drift
noted, not a correctness issue: the three init-* anchors are no longer
deep-linked from refusal messages post-#5310 (bd help init-safety links
the doc generically); a fuller playbook revalidation against the new
preflight wording is follow-up material, not a blocker.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(recovery): correct the init-safety exit-code mapping under the renewed marker
Maintainer review fixup for #6411. The marker bump renews a 90-day freshness
warranty asserting the four playbooks' premises still hold; review found one
that does not, so fix it rather than reset the clock over it.
init-local-exists was headed `Exit code: 11 (ExitLocalExistsRefused)` but led
with the "Refusing to destroy N issues in non-interactive mode." symptom,
which returns 12 (ExitDestroyTokenMissing, cmd/bd/init.go:2712-2715). Exit
11's only non-test site is the interactive typed-confirm decline
(cmd/bd/init.go:2696) — the same split cmd/bd/protocol/exit_codes_init_test.go
already documents. The section's recovery (`bd init --reinit-local`) also
dead-ended: runInitReinitPreflight gates on reinitLocal alone, so the
non-interactive caller the symptom names re-triggers the identical exit-12
refusal.
- doc: head init-local-exists with both codes, lead with the true exit-11
interactive symptom, append --destroy-token to the non-interactive recovery,
and add the refusal as a second symptom under init-token-missing, whose
"Why this happens" attributed the token to --discard-remote alone.
- doc: scope the intro's "points here to a labeled anchor" claim to the
post-#5310 reality the marker commit itself disclosed (only pk-fork-refused
is still deep-linked).
- code: correct the ExitLocalExistsRefused and ExitDestroyTokenMissing
comments, which are where the doc inherited its mapping error from, and
widen the same --discard-remote-only framing in `bd help init-safety`.
- gate: add cmd/bd/dolt.go to check-doc-freshness.sh — the doc declares it a
freshness source but the script did not enforce it, so drift in the pk-fork
playbook's source never tripped the re-review duty.
Comment, doc, and help text only; no behavior change. Verified:
check-doc-freshness.sh PASSED 10/10 with the added source, go test ./scripts/,
the cmd/bd init-safety tests, and the cmd/bd/protocol exit-code contract tests.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(ci): sync the doc-freshness test fixture with the init-safety source list
The maintainer review fixup for #6411 added `cmd/bd/dolt.go` to the
`docs/recovery/init-safety.md` entry of the DOCS array in
scripts/check-doc-freshness.sh (and to the doc's own `Freshness source:`
marker), but scripts/check_doc_freshness_test.go pins the same list in
`freshnessDocuments`, which it uses to build the fixture tree every
subtest runs the real script against. The fixture doc's marker line is
written from that pinned list, so the script -- correctly -- reported
`FAIL: Freshness source does not name cmd/bd/dolt.go` for every case.
That reds `.github/workflows/pr.yml`'s check-doc-freshness-platforms
matrix, which runs
`go test '-tags=integration,gms_pure_go' -count=1 -run '^TestDocFreshness' ./scripts`.
GitHub CI never saw it: the six workflows are green on the pushed head
94d76b5a4, which is the one-line marker bump alone, while the fixup that
edits the DOCS array has been local-only through the review loop.
Add `cmd/bd/dolt.go` to the pinned list so the mirror matches the script.
Validated in the adopted worktree:
- `go test '-tags=integration,gms_pure_go' -count=1 -run '^TestDocFreshness' ./scripts` -> ok
(fails without this commit; passes at 94d76b5a4, so the break is fixup-introduced)
- `./scripts/check-doc-freshness.sh` -> PASSED against the real tree
- `go build ./...`, `go vet ./cmd/bd/... ./scripts/...` -> clean
- `go test ./test/docsync` (Mintlify nav/link guard) -> ok
- `go test ./cmd/bd/protocol -run Exit` -> ok
- the 14 `cmd/bd/init_safety_test.go` tests -> ok
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(release): key rc.1 in versionChanges; admit exit 12's interactive decline
Maintainer review fixups for the v1.3.0-rc.2 prep adoption. Both findings
are minor and non-gating; both are cheapest to fix before the tag.
versionChanges gained a 1.3.0-rc.2 key but has no 1.3.0-rc.1 key, so the
one upgrade hop this RC creates -- rc.1 testers (the reporters of
#6118-#6120) moving to rc.2 -- misses the exact-string index scan in
getVersionsSince and falls through to its "upgrading from a very old
version" branch, which returns the ENTIRE list. `bd upgrade review` then
dumps all 81 release entries instead of the one-entry rc.2 digest written
for exactly that audience -- while the shipped [1.3.0] entry tells users
to prefer it to `bd info --whats-new` "which dumps the whole release
history". The lookup runs in the NEW binary, so an rc.1 key can only
reach an rc.1 user by shipping inside rc.2; it cannot be added later.
The 1.1.0 line carries both of its rc keys (info.go:293,305) and this
restores that pattern. Placement is immediately below the rc.2 entry:
getVersionsSince cuts by index, and the 2026-08-31 date keeps the array
monotonic for TestGetVersionsSinceOrder. Verified with the built package:
getVersionsSince("1.3.0-rc.1") now returns exactly the rc.2 entry, and
the 1.2.2 hop still resolves, now as [1.3.0, rc.1, rc.2].
The ExitDestroyTokenMissing doc comment and the `bd help init-safety`
exit table say 12 means a destructive re-init "in non-interactive mode",
but handleRemoteSafetyDecision returns 12 from a branch guarded by
term.IsTerminal (cmd/bd/init.go:3147) when the interactive
--discard-remote typed-token confirmation is declined -- a third producer
alongside init.go:2744 and init_safety.go:162. A script or playbook
branching on "12 => we were non-interactive" can misdiagnose an
interactive decline. The clause is verbatim pre-existing, but the commit
it rides on re-audited exactly this exit-code documentation and made the
sibling exit-11 "sole source" claim exactly precise, so it is corrected
here rather than re-asserted. Both sites gain one clause.
Comment, help text, and release-metadata only; no behavior change and no
constant values changed. Verified: check-versions.sh in sync at
1.3.0-rc.2, check-doc-freshness.sh PASSED, gofmt clean, git diff --check
clean, and the cmd/bd version-tracking and init-safety tests green.
Follow-up (not this PR): no test pins the RC-key chain, which is how the
missing key passed CI silently; a presence-pin would close the class.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* docs(recovery): re-review init-safety playbooks; refresh the 90-day marker
The Last-reviewed marker crossed the 90-day freshness threshold on Sep 7,
turning 'Check doc flags freshness' (and with it PR Policy and the required
CI Gate) red for EVERY open PR — #6262 is merge-queued and UNSTABLE on
exactly this.
Reviewed against the declared freshness sources (init.go, init_safety.go,
init_safety_test.go, dolt.go), which changed materially since June
(notably the destructive-preflight replacement in #5310 and the
server-flag precedence work): the four playbooks' premises still hold —
--destroy-token/--reinit-local/--discard-remote all exist and are the
refusal remedies, the force-refusal-on-origin-history invariant is intact,
and the pk-fork-refused deep link from dolt.go:416 resolves. One drift
noted, not a correctness issue: the three init-* anchors are no longer
deep-linked from refusal messages post-#5310 (bd help init-safety links
the doc generically); a fuller playbook revalidation against the new
preflight wording is follow-up material, not a blocker.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(recovery): correct the init-safety exit-code mapping under the renewed marker
Maintainer review fixup for #6411. The marker bump renews a 90-day freshness
warranty asserting the four playbooks' premises still hold; review found one
that does not, so fix it rather than reset the clock over it.
init-local-exists was headed `Exit code: 11 (ExitLocalExistsRefused)` but led
with the "Refusing to destroy N issues in non-interactive mode." symptom,
which returns 12 (ExitDestroyTokenMissing, cmd/bd/init.go:2712-2715). Exit
11's only non-test site is the interactive typed-confirm decline
(cmd/bd/init.go:2696) — the same split cmd/bd/protocol/exit_codes_init_test.go
already documents. The section's recovery (`bd init --reinit-local`) also
dead-ended: runInitReinitPreflight gates on reinitLocal alone, so the
non-interactive caller the symptom names re-triggers the identical exit-12
refusal.
- doc: head init-local-exists with both codes, lead with the true exit-11
interactive symptom, append --destroy-token to the non-interactive recovery,
and add the refusal as a second symptom under init-token-missing, whose
"Why this happens" attributed the token to --discard-remote alone.
- doc: scope the intro's "points here to a labeled anchor" claim to the
post-#5310 reality the marker commit itself disclosed (only pk-fork-refused
is still deep-linked).
- code: correct the ExitLocalExistsRefused and ExitDestroyTokenMissing
comments, which are where the doc inherited its mapping error from, and
widen the same --discard-remote-only framing in `bd help init-safety`.
- gate: add cmd/bd/dolt.go to check-doc-freshness.sh — the doc declares it a
freshness source but the script did not enforce it, so drift in the pk-fork
playbook's source never tripped the re-review duty.
Comment, doc, and help text only; no behavior change. Verified:
check-doc-freshness.sh PASSED 10/10 with the added source, go test ./scripts/,
the cmd/bd init-safety tests, and the cmd/bd/protocol exit-code contract tests.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(ci): sync the doc-freshness test fixture with the init-safety source list
The maintainer review fixup for #6411 added `cmd/bd/dolt.go` to the
`docs/recovery/init-safety.md` entry of the DOCS array in
scripts/check-doc-freshness.sh (and to the doc's own `Freshness source:`
marker), but scripts/check_doc_freshness_test.go pins the same list in
`freshnessDocuments`, which it uses to build the fixture tree every
subtest runs the real script against. The fixture doc's marker line is
written from that pinned list, so the script -- correctly -- reported
`FAIL: Freshness source does not name cmd/bd/dolt.go` for every case.
That reds `.github/workflows/pr.yml`'s check-doc-freshness-platforms
matrix, which runs
`go test '-tags=integration,gms_pure_go' -count=1 -run '^TestDocFreshness' ./scripts`.
GitHub CI never saw it: the six workflows are green on the pushed head
94d76b5a4, which is the one-line marker bump alone, while the fixup that
edits the DOCS array has been local-only through the review loop.
Add `cmd/bd/dolt.go` to the pinned list so the mirror matches the script.
Validated in the adopted worktree:
- `go test '-tags=integration,gms_pure_go' -count=1 -run '^TestDocFreshness' ./scripts` -> ok
(fails without this commit; passes at 94d76b5a4, so the break is fixup-introduced)
- `./scripts/check-doc-freshness.sh` -> PASSED against the real tree
- `go build ./...`, `go vet ./cmd/bd/... ./scripts/...` -> clean
- `go test ./test/docsync` (Mintlify nav/link guard) -> ok
- `go test ./cmd/bd/protocol -run Exit` -> ok
- the 14 `cmd/bd/init_safety_test.go` tests -> ok
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
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.
External (cross-project) dependency blockers are now enforced everywhere a bead's readiness or closability is decided: `bd ready` / `--claim`, `bd blocked`, `bd close` / done-status `bd update` (direct and proxied), `bd dep tree`, and served HTTP ready/claim. The policy is a storage-boundary decorator (`internal/storage/externaldeps`) applied on both the DoltStorage chain and the UOW provider, with full capability-forwarding parity, `Unwrap` at every level, and the backend's advisory defer-wake preserved on the claim path.
Review trail: maphew rounds 1–4 (Jul–Aug), bee rounds 1–4 (Sep 2): D1 recording-parity exemption, D2 ready-filter goldens, D3 UOW-level Unwrap for the proxied importer, D4 claim-path defer wake. Verified at head 3468d62f on a clean merge with current main; CI fully green at that head.
Fixes#4769.
* chore: bump version to 1.3.0
Runs scripts/update-versions.sh 1.3.0, the sanctioned path per RELEASING.md.
Covers everything scripts/check-versions.sh gates: cmd/bd/version.go, the
three plugin manifests plus the marketplace, the MCP pyproject/__init__/
uv.lock pin, npm-package/package.json, the tracked .githooks managed-section
markers, default.nix and the Windows PE resource metadata.
scripts/check-versions.sh passes at 1.3.0.
* docs(changelog): roll up [1.3.0] for 2026-08-28
Creates the [1.3.0] section dated 2026-08-28 and leaves [Unreleased] empty
but present.
- Rolls up everything that was under [Unreleased].
- Adds a 'Breaking changes for v1.2.2 users' section. v1.2.2 shipped the
v1.1.2 tree, so its users never received [1.2.1]; the five behavioral
breaks documented there are restated (close policy on bd update -s, search
including closed, the interactive-only last-touched fallback, bd human list
status handling, dolt push/sync remote-adoption consent) with a pointer to
the historical section rather than a copy of it. The two breaks new in
1.3.0 (BEADS_DOLT_PORT precedence, actor '--' decoding) are indexed here
and written up in full under Changed.
- Adds upgrade notes: first invocation auto-migrates v53 -> v66 (13
migrations, 0054..0066, verified against the embedded migrations dir);
per-step progress on stderr is TTY-gated, so CI sees nothing; back up
first; the forward skew guard means co-resident older binaries refuse the
store, so a shared-store fleet upgrades together; rollback via the recovery
runbook's cursor-rollback procedure.
- Adds entries for eight changes that had no changelog line at all, each
verified against the code on this branch: --profile -> --cpu-profile with
no alias (#5126); the one-time content-derived aux-row id rekey, main 0061
(#5150); events becoming clone-local, 0062 (#5162); the interactions.jsonl
sidecar becoming opt-in behind audit.enabled (#4688); bd import erroring on
redirected stdin with no source (#5171); auto-backup defaulting off under a
sql-server (wy-zrmqr); bd hooks install --chain/--force becoming no-ops
under marker sections (#5284); the new *.gate.lock workspace/physical-root
gate files (#5046, #5093); and purge/prune tier selection (#5995).
- Moves the 'sort on listIssues' entry (#5666) out of [1.2.2] and into
[1.3.0]. Its commit 8aaefe2d4 is not an ancestor of the v1.2.2 tag, so it
never shipped in that release.
* feat(info): add the 1.3.0 versionChanges entry
RELEASING.md makes cmd/bd/info.go a required release step: versionChanges is
the channel 'bd info --whats-new' uses to tell an agent what changed under it.
The entry matches the existing format and carries the same upgrade notes as
CHANGELOG's [1.3.0] — the v53->v66 migration and its cost, the fleet
implication of the forward skew guard, the rollback pointer, the seven
behavioral breaks a v1.2.2 user meets, and the headline changes.
* docs(releasing): document the release-branch process, fix the semver wording, close the audited checklist gaps
Release-branch process (now in use for 1.3.0): a new 'Release Branches'
section covers cutting release/x.y.z from a SHA green on both Main and
Nightly Full Tests, landing every release-targeted change as a PR based on
the release branch and labeled status/needs-review-auto, tagging from the
branch, and forward-porting to main afterwards. Hotfixes are folded into the
same shape rather than a parallel one.
Semver: MAJOR is now removals and incompatible interface changes; documented
behavioral breaks that ship with migration notes are a MINOR bump, with the
obligation that makes that legitimate (CHANGELOG entry naming the override,
plus an info.go summary). 1.3.0 is cited as the worked example.
Checklist gaps the audit found: cross-compiling every goreleaser target
before tagging (GH#5662 — PR CI builds none of them, and the freebsd break
burned the v1.2.0 tag), the docs cutover (cli-docs.pin bump plus regen, and
the hand-maintained release line on docs/index.md, which had gone stale at
1.1.0), a release-notes rollup check for both an unemptied [Unreleased] and
entries misfiled under a previous tag, an explicit check-versions.sh gate,
and the info.go entry.
Also retires the bump-version.sh instructions: that script has been a
deprecation stub that exits 1 for some time, so the document's primary
version-bump instruction could not work. Replaced with update-versions.sh
plus check-versions.sh, and the file list corrected against what the script
touches now (uv.lock, the copilot plugin, the .githooks markers, winres) —
the old list named cmd/bd/templates/hooks/* and PLUGIN.md, neither of which
it writes. 'The Easy Way' now names the release molecule; release.sh is a
gateway that prints it.
Fixes the drifted table of contents while in the area.
* fix(release-formula): bump via update-versions.sh, verify via check-versions.sh
The formula carried its own hand-rolled copy of the version bump, and it had
drifted from the scripts it was copied from. bump-plugin-json pointed at
claude-plugin/.claude-plugin/plugin.json, a path that has not existed since
the plugins moved under plugins/beads/ — so the step would have failed
outright — and the copy covered none of the files added to the gate since:
the codex and copilot plugin manifests, integrations/beads-mcp/uv.lock, and
the BEADS INTEGRATION markers in .githooks/*. A release driven by this
formula would either die on the stale path or ship inconsistent versions,
which is how the v1.1.1 tag burned (stale uv.lock, discovered only in the
tag-triggered run) and how the v1.2.0 bump reddened main (stale hook
markers).
Replaces the seven hand-rolled bump steps with one that runs
scripts/update-versions.sh, which is the sanctioned path and cannot drift
from itself, and turns verify-versions into scripts/check-versions.sh — the
same gate the release-tag pre-push hook and CI run — instead of a grep list
that has to be maintained in parallel with the real one. Both steps carry the
two failure modes worth knowing about: uv missing (leaves uv.lock stale, fails
only after the tag exists) and the hook markers being rewritten wholesale
rather than matched.
Also renames push-main to reflect the release-branch process now documented
in RELEASING.md, and adds the forward-port reminder there.
Verified: each listed file checked against scripts/update-versions.sh and
scripts/check-versions.sh as they exist on this branch, and against a real
./scripts/update-versions.sh 1.3.0 run. go test ./scripts/ -run Release
passes (the formula still parses, and the cleanup-stale-dolt-orphans,
verify-homebrew-core and local-install assertions are untouched).
* docs: point the release banner at 1.3.0 and tell 1.2.2 users what this upgrade costs
The docs homepage carries a hand-maintained 'These docs are for the X.Y.Z
release' line that nothing generates or validates, so it had gone stale at
1.1.0 while the CLI docs pin had already moved to v1.2.2. It now names 1.3.0
and sends the reader to Upgrading first, since this upgrade crosses a schema
migration. RELEASING.md now carries a checklist item for it.
docs/getting-started/upgrading.md was entirely version-agnostic: strong on
mechanism (install methods, hooks, the remote-migrate gate, backup-first,
the multi-clone flow) and silent on which release you are coming from. A
1.2.2 user could read the whole page without learning that their database is
at v53 and that this step crosses 13 migrations. Adds an 'Upgrading to 1.3.0'
section covering the v53->v66 jump and why it is bigger than a routine one,
the slower first invocation and its TTY-gated per-step progress, the
forward-skew consequence for a shared store (upgrade every client together),
and the cursor-rollback runbook. It links to the backup and multi-clone
procedures already on the page rather than restating them.
Also adds the schema-version-mismatch runbook to the Recovery index table.
It was reachable only from the sidebar and the CHANGELOG, and the new
Upgrading section links to it.
Generated docs untouched: scripts/check-cli-docs-drift.sh passes against the
v1.2.2 pin, and the pin bump is a post-tag step (generate-cli-docs.sh builds
bd from the pinned tag, which does not exist until v1.3.0 is pushed).
go test ./test/docsync and scripts/check-doc-freshness.sh pass.
* fix(release-notes): correct the backup advice, the migration count, and the breaks undercount
Review round on #6038. Four findings, all of which made the upgrade notes
actively misleading rather than merely incomplete.
CRITICAL — bare 'bd backup' takes no backup. backupCmd is a runless cobra
parent (no Run/RunE, children init/sync/restore/remove/status, no default),
so cobra prints usage and exits 0 without writing anything. A user following
'bd backup' before an irreversible 27-migration upgrade sees help text and
proceeds believing a snapshot exists; in a script, 'bd backup && ...' proceeds
on exit 0. Replaced with 'bd backup init <path>' then 'bd backup sync' in
CHANGELOG, info.go and upgrading.md, and said in each place that bare
'bd backup' takes no backup.
Also CRITICAL, same class: the backup had no ordering rule. Under 1.3.0
'bd export' triggers autoMigrateOnVersionBump before it exports, so a backup
taken after installing is a post-migration snapshot that cannot protect
against the migration going wrong. All three copies now say to back up with
the OLD binary before installing, and carry the neighbouring rule that
remote-backed stores must finish 'bd dolt push' first, since the
pending-migration gate refuses push/pull too.
Migration count: '13' was the main series only. schema.go runs the main
source then the ignored source through the same 'Applying migration %04d'
printer, and the ignored series moves 0011 -> 0025 here, so the run is ~27
migrations and the counter visibly restarts from 0066 back to 0012. That
backwards jump is exactly the signature an operator reads as a loop and
kills — while these same notes say 'do not interrupt it'. All three copies
now state ~27, show the restart in sample output with real migration names,
and label it as not a restart.
Breaks undercount: 'seven' read as an enumeration, but [1.2.1] carries three
more entries explicitly labelled BREAKING that a v1.2.2 user also meets.
Retitled as highlights with an explicit pointer to the full [1.2.1] section,
and added the three: '--readonly serve' now refused (load-bearing next to the
'restart any long-running bd serve' advice — it will not come back up), the
config kv-plane drop, and the backend package's orphan-handling removal. The
info.go entry gets the same pointer and the same three, since 'bd info' is the
only copy reachable after installing.
Upgrade-time reader is now pointed at 'bd upgrade review', which computes the
delta since the previously-run version via getVersionsSince, instead of
'bd info --whats-new', whose showWhatsNew loops the entire versionChanges
array with no cap (~80 entries) to deliver the ~11 relevant bullets.
* fix(check-versions): gate the copilot manifest and the winres files, stop overclaiming
Three review findings, all cases where the gate said more than it checked.
Copilot manifest was bumped but never gated. update-versions.sh:101 rewrites
plugins/beads/.copilot-plugin/plugin.json with a sed anchored on the OLD
version, and check-versions.sh never read the file — the string 'copilot' did
not appear in it. That is the same drift class that carried stale .githooks
markers through v1.2.0: once the file drifts the bump silently no-ops on it,
the green line prints, the pre-push hook and CI pass, and the Copilot plugin
ships advertising the previous version. Now gated. Verified it fails: drifting
the file to 1.2.2 reddens the run and exits 1.
winres was verified by nothing after the formula rewrite deleted the steps
that grepped it. Restored as real gates rather than formula prose, since
manifest.xml's <assemblyIdentity> version has no backstop at all —
gen-winres.sh re-derives winres.json's numeric fields from version.go at build
time, but the manifest's version is embedded verbatim, and update-versions.sh
rewrites it with a sed anchored on the old base version. Prerelease-correct:
file_version/product_version and the manifest's four-part version are checked
against the BASE version while FileVersion/ProductVersion are checked against
the full string, which is what update-versions.sh writes. The manifest grep is
anchored at line start because the XML declaration also carries a version=
attribute. Verified it fails on drift.
The success line claimed a 'released-docs policy pass' for a check that no
longer exists — the script reads no docs file — while this same release adds
a MANUAL docs-cutover checklist item precisely because nothing automated
covers docs. An operator reading that line would reasonably skip the manual
checks. Now says version files only, and names the manual steps. The two
vestigial echoes left behind by the deleted check are gone.
The failure remedy was also wrong, and wrong in the direction that loops the
operator: it said to re-run update-versions.sh, which derives CURRENT_VERSION
from cmd/bd/version.go (line 70) and substitutes old->new literally. After the
first bump version.go already holds the new version, so a re-run rewrites
new->new and no-ops on exactly the drifted file the gate just named. Verified
empirically — with the copilot manifest and manifest.xml drifted to 1.2.2,
'update-versions.sh 1.3.0' prints 'Bumping: 1.3.0 → 1.3.0' and leaves both at
1.2.2. Only the githooks markers (wholesale regex) and uv.lock (uv lock) heal
on a re-run, and the message now says so and gives the three remedies that
actually work.
shellcheck clean.
* docs(releasing): make the release-branch policy internally consistent
The policy landed in the previous commit but three procedures in the same
files still contradicted it, and the formula implemented the wrong one.
RELEASING.md said 'Nothing is pushed straight to the release branch' and then,
150 lines down, direct-pushed the release branch and minted the tag before the
merge. Two concrete failures: with branch protection the push is rejected
after the tag already exists locally, and with a squash merge the tag points
at a commit that is not an ancestor of release/x.y.z — goreleaser packages
CHANGELOG.md FROM THE TAG into every published archive, so the release ships
the pre-review notes. Both the CHANGELOG-commit block and the bump block now
open a PR, and tagging is a separate step against the merged commit. The
literal 'git push origin main' under the substitution blockquote is gone, as
is the direct push in the docs-pin block.
The formula implemented the wrong order too: commit-release -> create-tag ->
push-main. Reordered to commit-release -> push-main (land the PR) -> create-tag
(on the merged commit) -> push-tag, and create-tag now states why the order
matters.
preflight-pull was untouched by the last commit and still hard-coded main:
divergence recovery was 'git reset --hard origin/main'. Running the molecule on
a release branch and following that destroys the reviewed release-prep commit
and leaves the operator tagging an untested main SHA — precisely the failure
the policy exists to prevent. It now pins the release branch into a variable
first and resets to that; the backup branch moved to Option 1 rather than
Option 3.
'git push origin release/{{version}}' broke every prerelease run: the branch
convention is release/x.y.z, so an RC rendered release/1.3.0-rc.1 and failed
with 'src refspec does not match any', and the forward-port 'git log
main..release/{{version}}' then died on an unknown revision. Now derives the
base version and says why.
The RC workflow still cut tags from the tip of main, which is what the new
policy calls 'a SHA nobody has fully tested' — and worse, an RC exists to
validate the SHA the stable release ships, while the stable tag now comes off
the release branch, so it validated a different SHA by construction. RCs are
now cut on the base version's release branch, and promotion stays on it.
Accuracy fixes in the same pass: verify-versions no longer claims the (now
corrected) 'released-docs policy' string or tells the operator to re-run the
bump — a no-op after the first run, proven in the previous commit — and no
longer prints a prerelease-broken 'grep -c {{version}} winres.json # 4', which
yields 2 for an RC because the numeric PE fields carry the base version. It
now points at check-versions.sh, which gates winres correctly. The 'three
plugin manifests' and 'compares everything else against it' claims are
corrected to match what the script actually reads, and RELEASING.md names
default.nix and README.md as bumped-but-ungated.
go test ./scripts/ and ./test/docsync/ pass; formula still parses and the DAG
is acyclic.
* ci: run PR workflows on release/** branches
Release-targeted PRs currently run almost no CI. pr.yml, pr-risk.yml,
conformance.yml, regression.yml and cross-version-smoke.yml all declare
'pull_request: branches: [ main ]', and every push trigger in the repo is
'branches: [main]' or 'tags: v*'. So a push to release/1.3.0 fires zero
workflows, and a PR based on it gets only the three workflows with no branch
filter (migration-test, nix-build on its paths, docs-mintlify).
That puts the new release-branch policy on a contradiction: it routes the
version bump and 'any fix the release validation turns up' onto a branch where
they land with no unit, lint, conformance or regression coverage, and the
first full signal is the tag build — where a failure burns the tag by this
document's own rule. The policy was written to stop tagging untested SHAs and
was quietly producing them.
Adds release/** to the pull_request branch filter of those five. Push triggers
are deliberately left alone: release branches take changes through PRs, so the
pull_request event is the one that matters, and widening push would double
every run on merge.
cross-version-smoke is the highest-value of the five here — a release-targeted
PR is exactly where cross-version upgrade breakage is most expensive to find
at tag time.
This PR is the vehicle because it targets release/1.3.0, so the new filters
take effect for its own subsequent pushes.
All five files parse; go test ./scripts/ (which includes the workflow lint
tests) passes.
* docs: reconcile the 1.3.0 upgrade notes with the merged release set
Merging origin/release/1.3.0 changed three facts the upgrade notes assert.
Migration count. The merge added ignored/0026_dep_rekey_dedup_marker (#6045),
so the clone-local series now runs 0012 -> 0026, not 0012 -> 0025. Recounted
from the tree: 13 main-series (0054..0066, unchanged) + 15 clone-local = ~28,
not ~27. Corrected in CHANGELOG, cmd/bd/info.go and upgrading.md, including
the trailing line count in the 'counter restarts' explanation.
Shared servers. #6048 (#5920, #5043) means a shared dolt sql-server is no
longer auto-migrated at all — it waits for explicit consent via
'bd migrate schema'. The notes said flatly that 'the first invocation migrates
your schema in place', which is now true only for embedded/local stores and
would have sent a shared-server operator looking for a migration that never
runs. All three copies now scope that claim and point at the new 'Shared
servers' section upgrading.md gained in the same merge. Verified
'bd migrate schema' exists (cmd/bd/migrate.go:848) and that --global is a root
persistent flag (main.go:818), so the cited invocations are real.
#5896. The auto-export entry said #5896 'stays open for embedded mode, where
bd delete still wedges auto-export'. #6059 closed exactly that. Reworded to
point at the store-history heal rather than claiming a live bug.
check-versions.sh 25/25 green, go build ./... clean, go test ./scripts/... and
./test/docsync/ pass, check-cli-docs-drift and check-doc-freshness pass.
* docs(changelog): fold in the proposed changelog lines from the merged 1.3.0 set
Adds the 'proposed changelog' text carried in the bodies of the PRs that
merged into release/1.3.0 after this rollup was first written. Text is the
authors' own; where a body gave it in conventional-commit form rather than as
a bullet, the sentence is preserved and only the 'fix(scope):' prefix dropped
and a bold lead added to match the section.
Changed: #6048 (two bullets — shared-store consent, and the smart gate's
first-mover/fast-forward arms going embedded-only), #6036 (exported packages
marked EXPERIMENTAL), #6053's revision-token bullet, #6049 (migration-test and
upgrade-smoke wisp-plane coverage).
Fixed: #6040 (server-mode lost updates), #6044 (removed-backend rejection),
#6045 (convergent dependency rekey), #6046 (tracked ignored_schema_migrations
heal), #6054 (ignored-cursor floor clamp), #6059 (delete-wedge heal), #6057
(full GC after flatten/compact), #6060 (--storage-class routes), #6061
(journal actor attribution), #6062 (proxied/gateway init errors), and #6053's
two typed-JSON bullets.
Security: new subsection for #6047 (Go 1.26.7 toolchain bump closing seven
reachable stdlib advisories, plus the dependency bumps clearing all 25).
Placed after Fixed per Keep a Changelog ordering.
Documentation: #6052's multi-rig/proxied gate limitation. Its body calls it a
release-notes line rather than a changelog line, so it may want moving.
Contributor credit carried where the PR body gives it: #6040 keeps its
'Reported and fixed by @nova-submodules' sentence, and #6044 gains a note that
its detection helper is ported from @steveyegge's #4740. NOTE: #5064 (aux
row-key encoding drift) carries credit to @marcodelpin in its body but no
proposed changelog line, so it has no entry here — flagging rather than
inventing one.
#6043 was a REPLACEMENT, not an addition: it asked for the existing
MIGRATION-FREEZE bullet to be swapped for vendor-neutral text. Done — the old
bullet named the gt CLI, 'town root' and 'gt migrate thaw'; the new one
describes the generic marker discovery, exit code 14, and the wider set of
maintenance that stands down.
#6055 and #6056 were still OPEN at the time of writing. Their four proposed
lines are included but fenced in a PROVISIONAL HTML comment block that says to
delete it before tagging if either PR does not land.
check-versions.sh 25/25, go build clean, go test ./scripts/... and
./test/docsync/ pass, check-cli-docs-drift and check-doc-freshness pass.
* docs(changelog): credit the three carried contributor fixes
Adds the entries for the merged PRs that carried contributor work but shipped
no proposed changelog line of their own, in the maintainer's supplied wording,
expanded to the surrounding entries' voice.
ATTRIBUTION CORRECTED on #5064. The supplied wording read 'Reported by
@marcodelpin, fixed by @maphew'; the PR body says the opposite. Its '## Credit'
section: 'The fix is @marcodelpin's, from 767d5dcd on their fork... The
diagnosis behind it — the chunk-level characterisation, the negative result on
the minimised fixture, the dolt 2.1.10 re-test, the recover-rows verification —
is theirs too... isSchemaEncodingDriftErr and its table-driven test come from
that commit.' @maphew (the PR author) absorbed it with a review-requested
semantic rework. Written as 'Diagnosis and fix by @marcodelpin, carried and
reworked by @maphew' so the contributor is not demoted to reporter of a bug
they also fixed.
Scope corrected on the same entry. The supplied wording reads as new behavior,
but git grep against the v1.1.2 tag finds both isSchemaEncodingDriftErr and
aux_row_rekey_drifted already present in internal/storage/schema/
aux_row_id_backfill.go — v1.2.2 is the v1.1.2 tree, so v1.2.2 users already
have this fix, and it is already documented under [1.1.2]. #5064 carries it
onto the main line. The entry says so, so a v1.2.2 reader does not conclude
they were exposed and go looking for a migration that does not concern them.
#5783 and #6037 verified against their PR bodies before writing; both supplied
claims hold. #5783: Config.LenientOpen reached server mode but newServerMode
never read it and the field's doc comment said 'Ignored in server mode', so the
dirty-table refusal's own recovery command could not run — and server mode has
no 'move the directory aside and re-bootstrap' alternative. #6037: bd init
persists a git-origin-derived sync.remote into the tracked config by design,
bootstrap rejected exactly that shape before the origin auto-detect, and
Action=='none' conflated 'already exists' with 'refused', printing a success
tick and exiting 0 having created nothing.
Also notes in the PROVISIONAL fence that the RC is gated on #6055/#6056
merging, so the fence comes off at RC-prep time rather than being an open
question.
check-versions.sh 25/25, go test ./test/docsync/ passes.
* fix(release): create release-prep branch before pushing it
The new release-branch/prep-PR flow pushed `release-prep/v<version>`
without ever creating that branch, so `push-main` (and the RELEASING.md
runbook) failed on first run with
`error: src refspec release-prep/v<version> does not match any`.
Add `git checkout -b` before each prep-branch push — the formula
`push-main` step and both RELEASING.md landing snippets — so the branch
exists before it is pushed, mirroring the existing `REL_BRANCH` guard in
the same step.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* fix(storage): run the shared-store migration gate on the proxied open path
The proxied-server / `bd serve` provider called MigrateUpWithLock with no
CheckRemoteMigrateGate variant at all, so it migrated a shared database on
every open — silently, since v1.2.2 (gastownhall/beads#5043, #5079). It now
passes the shared-store gate as a lock option, which puts it after the
converged fast path (a steady-state open still pays zero extra statements)
and after locked preparation (a fresh bootstrap reads version 0 and
passes). Because the gate reads dolt_remotes over SQL, a proxied database
that DOES have a remote now gets the full #4259 flow too.
Read commands opened with the new uow.WithReadOnly() warn and attach at the
current schema instead of failing, mirroring what embedded mode has done
for its read-only intent since bd-578h9.5 — extending the gate here without
that would newly brick every read on a workspace waiting for its operator,
which is the opposite of what the gate's own message promises. Writes still
refuse: they open without the option.
`bd migrate schema` on proxied mode flips from "not supported" to a success
report: the root pre-run's verb consent is set before the provider opens,
so the open itself performs the consented migration and RunE has nothing
left to do but say so. Gate refusals now render as the full typed block
(text and --json) on the proxied open and on `bd serve` startup, via a
renderTypedOpenError helper extracted from the store path — a daemon
refusing to start is the case with no operator watching, so its log is the
only place the remediation can appear.
One fix to the gate placement itself, found by uow's #5012 self-heal test:
skip the gate when the caller holds fresh-bootstrap heal authority. Gating
on the version alone was not enough — an init whose first migration pass
died part-way leaves a non-zero cursor, so its retry read "existing
database, migrations pending" and refused to finish migrating the database
it had just created. The capability is the durable proof of creation, so
the skip keys on it.
* fix(storage): restore the proxied claims with the code that delivers them
The migration gate's user-facing text described the proxied / `bd serve`
plane while only the sql-server store was gated, so PR #6048 stripped those
claims. This commit is where the code arrives, so the text comes back with
it: the shared-no-remote body names proxied-server mode again, as do the
decision constant, CheckSharedStoreMigrateGate's doc, and
WithMigrationGate's; upgrading.md regains a proxied subsection covering the
read-through warning and `bd serve`'s refusal to start.
This also closes the loop the review flagged on the remedy itself. The
refusal prescribes `bd migrate schema`, which this PR makes work in proxied
mode — previously it hard-refused there, so the gate's only offered remedy
was a dead end, and the root pre-run would have consumed the consent on the
open before RunE printed "not supported". With consent now scoped to that
one verb (#6048), bare `bd migrate`'s surviving proxied refusal grants
nothing on the way past. A test pins the pairing structurally: the command
the gate prescribes is the command that grants consent.
The read-through warning and the gate's own text now share one constant, so
they cannot drift apart.
* 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(schema): add the shared-store migration gate and a locked migration gate hook
Grows checkRemoteMigrateGate with a `shared` flag, exposed as
CheckSharedStoreMigrateGate. On a shared store (a database served to
co-resident bd clients) the gate:
- refuses a version-bump migration when there is NO remote and the
operator has not consented, with the new "shared-no-remote" decision
on the existing RemoteMigrateGateError. Promoting the schema cursor
on a shared server locks out every client still on an older bd —
gastownhall/beads#5920;
- suppresses the smart gate's two auto-EXECUTE arms with a remote
configured. The safe-first-mover argument is about clones, not
clients; it firing on a shared server IS the #5920 mechanism.
A fresh database (current == 0) still migrates: creating a database is
consent for its schema. Consent surfaces are the migrate verb (new
process-local SetSharedMigrateConsent, unlocking only the no-remote arm),
--force, and the reused BD_ALLOW_REMOTE_MIGRATE.
schema.WithMigrationGate gives MigrateUpWithLock a pre-migration hook for
callers whose migration runs entirely inside it. It sits after locked
preparation and before MigrateUp, so the 4a3c02abc converged fast path
still costs it zero statements.
No call site changes behavior yet: every existing exported variant passes
shared=false, so embedded recompiles untouched.
* fix(storage): refuse version-bump migration on shared dolt sql-server stores
Switches internal/storage/dolt's writable-open gate to the shared variant.
A DoltStore is always a sql-server client, and a sql-server accepts
co-resident clients by construction — the property that distinguishes it
from the flock-guarded single-writer embedded store — so this open must
never promote the schema cursor on its own.
This closesgastownhall/beads#5920 at its mechanism: the version-bump
reconciliation (autoMigrateOnVersionBump) opens its OWN writable store for
every non-preview command, including read-only ones, and that open is what
migrated a shared database out from under a team of co-resident v1.2.2
clients. It now refuses, and the refusal — previously swallowed to
debug.Logf with everything else — prints a one-shot stderr notice saying
nothing was applied and what to run instead.
`bd migrate` / `bd migrate schema` set the new verb consent in the root
pre-run (withheld under a preview flag), so the typed verb still migrates.
Tests: a full-CLI #5920 regression (server mode, no remote, stale
.local_version, `bd list` must not promote MAX(version) — it does promote
it, 65 -> 66, with this commit's one-line gate swap reverted), the
server-mode open matrix on a real sql-server (writable refuses, read-only
succeeds, verb consent migrates), refusal permanence in the retry loop,
and the agent-facing JSON block.
* docs(upgrading): document the shared-server upgrade path
Adds a "Shared servers" section: a version bump never auto-migrates a
database served to co-resident clients, upgrade every client first, then
consent once with `bd migrate schema`, and `bd serve` refuses to start
until the schema is reconciled.
Two corrections to what was already there:
- the smart gate's "auto-migrates as a safe first-mover" arm is now
embedded-only, so the bullet says so and links to the new section;
- the literal `BD_ALLOW_REMOTE_MIGRATE=1 bd migrate` recipe is removed
in favor of "run bd migrate as an explicit step in exactly one job; if
the gate blocks a run it prints the options and the scripted
override". Per settled decision 4
(engdocs/decisions/2026-07-17-docs-release-pin.md), the escape hatch
is not documented as a recipe — the gate prints its own guidance and
the docs defer to it. This brings the page back into compliance
rather than amending the decision.
* fix(storage): address review of the shared-store migration gate
CI blocker: cmd/bd/shared_store_migrate_gate_test.go uses cgo-tagged
helpers but carried no build tag, so the required pure-Go compile lane
(CGO_ENABLED=0 go test -tags gms_pure_go -c ./cmd/bd) failed on undefined
symbols. Tagged //go:build cgo, like every sibling Dolt-server test.
Truth at the merge point. This PR gates the sql-server store; the proxied /
`bd serve` plane is #6055. So its text no longer claims that plane: the
shared-no-remote body, the gate's doc comment, the decision constant, and
WithMigrationGate's doc all describe a dolt sql-server, and upgrading.md
drops the `bd serve` paragraph. #6055 adds them back with the code.
Remedies now match the refusal they are attached to:
- the one-shot version-bump notice keyed only on the error TYPE, so an
"adopt" refusal (another clone already migrated) told the operator to
run `bd migrate schema` — a command the verb consent deliberately does
not unlock for that arm. It now picks the line per Decision, and stays
silent under --json, where it was corrupting the gate's own JSON block
on the same stream;
- a new Shared flag marks refusals that came from a shared store, so the
adopt and adopt-ff options can say that adopting promotes the schema
for every co-resident client. adopt-ff previously advertised
"Risk: none", which is true only of local data;
- handleRemoteMigrateGateJSON gains the missing adopt-ff case (now a
routine outcome, since the auto-execute arm is suppressed), and
shared-no-remote points at the #shared-servers docs anchor instead of
inheriting the migrate-or-adopt one;
- `bd init` joining a behind shared server exits before writing
metadata.json, so its refusal now says where the prescribed command
can actually be run;
- the beads_global refusal names `bd migrate schema --global`, in the
init warning and under --global at the store open — the unflagged
command migrates the project database and leaves the refusal in place;
- a consented `bd migrate schema` that hits the dirty-table guard names
the recovery that terminates, instead of pointing at `bd dolt commit`,
which is itself gated in server mode and points back.
Behavior: consent is now scoped to `bd migrate schema` alone. Bare
`bd migrate` never applies a schema migration itself, and
`bd migrate --update-repo-id` is repo-fingerprint surgery — neither should
promote the schema for a whole server as a side effect. A consented
`bd migrate schema` now also stamps the version marker the refused
reconciliation could not, so `bd doctor` stops reporting a permanent
mismatch after the operator has done exactly what the refusal asked.
Library API: beads.AllowSharedSchemaMigration is the programmatic consent
embedders had no way to give except os.Setenv, which is process-global and
inherited by every child.
Cleanup: the force/env consent ladder was hand-copied into both arms; it is
now one helper that also names the surface that granted consent, so the
warning can stop hardcoding a command the operator may not have typed. Two
gate wrappers left with no callers at all are deleted.
* fix(cli): make --json shared-store migrate gate --global-aware
The shared-no-remote refusal's JSON gate block hardcoded the project-scoped
`bd migrate schema` consent command, so a --json/agent consumer operating on
the global database (--global) was handed a command that consents the wrong
database and leaves the refusal in place. The human/text path was already
--global-aware (printGlobalDatabaseConsentHint, noticeSharedMigrateRefusal),
but the notice self-suppresses under --json, making the gate block the sole
channel for that consumer.
Mirror the human-path consent idiom in handleRemoteMigrateGateJSON: retarget
both the top-level `expected` directive and the runnable migrate-shared option
command to `bd migrate schema --global` when the refused open targeted the
global database, scoped strictly to the shared-no-remote decision. Add a JSON
--global regression test at parity with TestPrintGlobalDatabaseConsentHint.
Also tighten the AllowSharedSchemaMigration doc to state it authorizes only the
no-remote shared arm (a remote-backed shared store still needs --force /
AllowRemoteMigrateEnv), matching the exported API's actual reach.
Maintainer review fixup for PR #6048.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* fix(events): thread the request actor through the issueops delete door
`bd delete --actor A` journaled its `delete` row and every cascade
`dep_remove` row with actor='' — the #5985 finding. The actor was in hand
at the role body (DeleteInTx already passes req.Actor to the reference
rewrite) and dropped one call below it.
Widen the delete workers with an explicit `actor string` parameter, the
house style PR #5908 used for the rest of the journal (never ambient
context): DeleteResolvedSetInTx, DeleteIssue(s)InTx, deleteIssueRowInTx,
and the RecordDependencyRemovals* family. DeleteInTx passes req.Actor and
SweepInTx passes SweepRequest.Actor, so sweep deletions become attributable
for free.
The genuinely actorless system surfaces — storage.DeleteIssue(s),
Tx.DeleteIssue, the dolt wisp deletes, the source-repo wipe behind
`bd repo remove` — pass "" explicitly, which the 0066 contract reads as
system/unknown. Their comments now say why rather than claiming the
plumbing cannot carry an actor.
No storage.Storage interface change and no migration: 0066 already added
`actor VARCHAR(255) NOT NULL DEFAULT ''`.
The domain/db repository call sites keep their existing "" for now; the
next commit threads the UOW door's actor to them.
Refs #5985
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(events): thread the request actor through the domain repository delete seam
The UOW door (proxied-server `bd delete`, HTTP API deleteIssues, `bd sweep`
over a unit of work) had the actor as far down as domain.deleteMany and lost
it at the repository interface, so its `delete` and cascade `dep_remove` rows
landed with actor=''.
Widen the seam the way PR #5908 widened IssueRepository.MovePersistence, for
the same reason: an explicit trailing `actor string` on
IssueSQLRepository.Delete / DeleteByIDs and DependencySQLRepository.
DeleteAllForIDs. deleteMany passes the actor its use case was already given,
so DeleteIssue / DeleteWisp / DeleteIssues / DeleteWisps keep their surfaces
unchanged and both doors now agree.
No variadic and no default: a new caller has to say whose delete this is, or
say "" and mean it.
Refs #5985
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(events): say when the journal being read is disabled; correct the actor docs
Zero rows is indistinguishable from caught-up. A consumer polling a workspace
whose writers never enabled the journal gets a successful, empty read forever
and concludes it is up to date — the "nothing to read and no way to tell why"
trap behind the field report's "0 rows" claim, which was default-off
activation and not a write-path gap.
`bd events export` and `bd events tail` now print a one-line stderr notice when
the target workspace resolves to disabled, and still serve whatever rows exist:
exporting the ledger a now-disabled workspace recorded while it WAS enabled is
legitimate, so this is a notice and not a refusal. It is the CLI mirror of the
HTTP API's EventsJournalDisabled 409, which can refuse because it has no
historical-export case. stderr, not the JSONL stream, and the exit code is
unchanged.
The default stays off. Flipping it changes write amplification and retention
for every workspace, which is not release-branch material.
Also fixes two now-false statements about attribution — the `bd events tail`
record contract and the docs page both said deletes never carry an actor — and
documents the requirement that every WRITER workspace enable the journal, not
just the one a consumer reads.
The golden gains the delete/dep_remove attribution, regenerated deliberately.
It keeps an actorless delete alongside the attributed one: the fixture used to
be the only evidence a consumer had, and reading it as "deletes are never
attributed" would mis-resolve every delete conflict.
Refs #5985
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(events): pin delete/cascade attribution at the DB on every plumbing
Four levels, because the drop happened at a seam no single one of them can
see:
- internal/storage/dolt: a ROLE-path delete (store.Deleter(), Force, an
explicit actor) reads back `deleter-1` on both the delete row and the
cascade dep_remove row. The store.DeleteIssue stanza in
TestEventsJournal_ActorAttribution keeps asserting '' and its comment now
says WHY — that surface is the actorless system interface, so the pin is
meaningful instead of aspirational.
- internal/storage/domain/db: the repository seam itself — Delete,
DeleteByIDs and DeleteAllForIDs each journal under the actor they are
handed — plus the cascade through the use case. journalRow gains Actor, so
the existing suite can see the column at all.
- internal/storage/uow: the same promise through the unit-of-work Deleter,
the door #5908's review caught drifting once already.
- internal/storage/embeddeddolt: a per-op matrix over the DEFAULT LOCAL
WORKSPACE. One mutation of every journaled kind, asserted at the DB, both
directions — every attributed op names its actor, and the only rows that
may carry none are the derived is_blocked updates.
- cmd/bd: #5985's repro verbatim through the real binary, and the
disabled-journal notice (present on export and tail, on stderr, absent
when enabled).
Also corrects the two remaining "actorless delete plumbing" claims in the
journalops.Row and issueops.RecordEventInTx contract comments.
Closes#5985
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(events): fix the CLI repro's flag and read stdout where stderr now speaks
`bd delete` has no --yes; --force is what makes it a real delete rather than
a preview.
TestRoutedCreateJournalsIntoTheTargetWorkspace asserted "the launching
workspace journaled nothing" against COMBINED output, which the new
disabled-journal notice now legitimately writes to. Its subject is journal
ROWS, so it reads stdout.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
The gate-types table claimed bead gates cannot be checked at all, which has
been wrong since local bead-gate evaluation was restored — only the cross-rig
`<rig>:<bead-id>` form stays pending. Fix the row and add a "Known
limitations" subsection covering the three behaviors users actually hit, each
quoting its verbatim error string so the text is searchable:
- cross-rig bead gates: `cannot be checked (multi-rig routing removed)`
- `bd close` of a bead gate in proxied-server mode: `no local store available`
- routed reads of a proxied-server target: `proxy server store needs to be
uow provider`
Two matching troubleshooting entries under "Dolt Server Issues" give the
symptom, the cause, and the workarounds (`bd gate check`, `bd close --force`,
or running from the owning rig's workspace).
Docs only — no code or behavior change. 1.3.0 does not advertise multi-rig
proxied-server operation, so this documents the limitation rather than
fixing it.
Refs #5861
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(metadata): restore v1.2.2 scalar typing for --set-metadata values
8ebd53e88 moved the CLI's metadata-edit helpers into
internal/storage/metadata.go and, in the move, replaced v1.2.2's
toJSONValue inference with a MetadataEditValue that always json.Marshals
the value as a string. The intent was GH#4146 (a numeric-looking id or a
version like "1e3" came back as a JSON number, breaking map[string]string
Go consumers), but it silently changed the shipped CLI contract:
`bd update --set-metadata k=5` started storing "5" instead of 5. That
regression shipped only in the deprecated/superseded v1.2.1, never in
v1.2.2, and 1.3.0 would freeze it.
Restore v1.2.2's inference body-for-body inside MetadataEditValue, so the
parity claim stays checkable against `git show v1.2.2:cmd/bd/update.go`:
"null" is JSON null, "true"/"false" are booleans, a spelling that scans
as a float AND is valid JSON on its own is emitted as that literal
(5 -> 5, 1e3 -> 1e3, 0.50 -> 0.50, while 05, +5 and NaN stay strings),
and everything else is a string. Every --set-metadata caller funnels
through this one function: embedded (cmd/bd/update.go ->
storage.ApplyMetadataEdits), proxied (parseSetMetadataFlags) and the
update executor's []string path.
GH#4146's concern is served by the explicitly typed routes, which are
untouched: --metadata / --metadata-json on the CLI (MergeMetadataJSON)
and the typed set map on the HTTP/Go path (applyTypedMetadataEdits).
No data migration: a "5" written by an in-window build is
indistinguishable from a string a user set intentionally through the
typed paths, so normalizing stored metadata would corrupt intended data.
Re-running the same --set-metadata k=5 retypes any given key.
Tests: new table in internal/storage/metadata_edit_value_test.go pinning
the v1.2.2 matrix plus an ApplyMetadataEdits end-to-end; the tests that
pinned the string-always behavior are flipped (domain/db mergeops suite,
update_lifecycle patch mapping, cmd/bd toJSONValue table) and the
embedded + proxied CLI suites now assert a stored JSON number. The
contract corpus is regenerated: its update/list/ready goldens run
`--set-metadata phase=2`, so `"phase": "2"` becomes `"phase": 2` and
nothing else moves.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(create): echo full-precision timestamps from bd create, not the DATETIME(0) re-read
b92442d1a routed `bd create` through issueops.Lifecycle, whose executors
build their result by re-reading the row they just wrote
(HydrateIssueOperationResult -> GetIssueInTx). created_at/updated_at are
DATETIME(0) columns, so that snapshot comes back at whole-second
precision and cmd/bd/create.go echoes it. v1.2.2 returned the caller's
own in-memory struct, which PrepareIssueForInsert stamps with
time.Now().UTC() including nanoseconds, so `bd create --json` used to
print e.g. 2026-08-28T12:34:56.789012345Z. Agents that create several
issues in a burst order them by exactly that fraction; rounded to the
second they all tie.
Restore the echo with OverlayCreateTimestamps: after hydration, put back
the created_at/updated_at (and closed_at, when the write set one) the
INSERT actually sent. Everything else on the snapshot stays DB-truth,
which is the facade's contract — only create, and only these fields.
Applied at every create body, not just the two the CLI reaches:
issueops.ExecuteCreate and ExecuteCreateBatch behind the dolt and
embedded-dolt stores, and the unit-of-work provider's own Create,
CreateBatch and batch-apply create item, which is what the proxied server
and POST /v0/beads/issues run on. Fixing only the shared executors would
have left the two bodies disagreeing about the same promise.
What is NOT changed, because it is not a regression: `bd show --json` and
`bd list --json` answered whole seconds in v1.2.2 too — they read the
column — and update/close/reopen re-read after writing there as well.
Widening the columns to DATETIME(6) would give reads sub-second times
too, but that is a schema migration on user Dolt DBs and touches paths
that deliberately compare at second precision; it is a 1.4 change.
The accepted skew, which predates this and stays: the engine ROUNDS to
the column rather than truncating, so a later read of the same row can
sit up to half a second either side of the create echo.
Tests: two new conformance cases, run on all three backends —
RunLifecycleCreateEchoesSubSecondTimestamps (a caller-supplied
nanosecond stamp must survive to the result exactly; the auto-stamped arm
stays a bounded smoke check, since requiring a non-zero fraction off the
clock is flaky by a billionth) and RunBatchCreatorEchoesSubSecondTimestamps
(per item, since both bodies build the result one snapshot at a time).
Plus a cmd/bd embedded test asserting `bd create --json` prints a
fractional part, and one httpapi assertion that the wire does not round
the role's snapshot on the way out. All four fail on the pre-fix tree.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(httpapi,types)!: revision / expected_version tokens are opaque JSON strings
The optimistic-concurrency token is minted by freshRowLock over the FULL
int64 range (crypto-random, non-zero) and published on the wire as a JSON
number: `revision` on responses, `expected_version` on guarded requests.
A JSON number does not survive a consumer that decodes into an IEEE-754
double — JavaScript's JSON.parse, Go's `any`, Python's `float`, jq. Live
tokens run past 5e17, where a double's ulp is already 64, so such a
client reads back a value NEAR the token, echoes that as its guard, and
earns a 409 against a row nobody else touched. The spec already carried
"DECODE IT AS A 64-BIT INTEGER" paragraphs telling clients to work around
this; that is a workaround for a wire type that should not have been a
number.
Emit and accept the token as a decimal STRING instead. It is documented
as opaque and EQUALITY-ONLY — compare it, never order or interpret it —
and a string round-trips exactly in every JSON consumer. It also leaves a
future backend free to mint a token that is not an int64 at all.
Internals are untouched: freshRowLock, the row_lock BIGINT column, its
migration, types.Issue.RowVersion and the ExpectedVersion *int64 guards
on the issueops requests all stay int64. Only the wire projection moves,
through the one spelling of the encoding — types.RevisionToken and
types.ParseRevisionToken.
STRICT STRING ONLY, with no transitional number-or-string acceptance.
This API already refuses unknown members by name and keeps one spelling
of the guard, and a number is precisely the shape a double-based client
has already rounded before it left the client — accepting it would
preserve the defect. A numeric guard is a 400 naming the member.
Chosen over clamping freshRowLock to 53 bits: a clamp does not fix rows
already minted with full-range tokens by in-window builds, so a JS
consumer reading one still rounds past 2^53 — repairing that would need a
row_lock normalization sweep over issues and wisps, a migration days
before a tag.
Surface: types.IssueDetails.Revision (what `bd show --json` prints and
GET /v0/beads/issues/{id} returns), the five hand-assigned httpapi
response fields, applyVersionGuardMember (now the reader for the batch
update item too, ahead of its typed decode, so a mistyped token still
earns a 400 naming the member), Problem.expected_version, and 14 OpenAPI
members regenerated through `make api-gen`. actual_version goes with them
— it is documented as "the `revision` the row was found holding", so
leaving it an integer would make the expected/actual pair disagree about
its own type; it is declared but never populated, so nothing changes
behaviorally.
Nothing shipped in a tagged release ever carried this member: v1.2.2 has
no internal/httpapi at all and no `revision` anywhere on the wire, so the
whole surface is in-window and can still be changed compatibly. Legacy
migration-0054 rows read as the string "0" with the same CAS semantics.
Corpus goldens are UNCHANGED: the canonicalizer already replaced any
`revision` value with the string "<REVISION>" whatever its JSON type.
Tests: types-level pins that the marshaled member matches `"revision":
"-?\d+"` and that RevisionToken/ParseRevisionToken round-trip MinInt64,
MaxInt64 and 2^53+1, plus a JS-realistic decode of 2^53+1 with a float64
control proving the token really is one a number would corrupt; httpapi
refusal tests for a numeric guard on update, close, reopen, delete and
both batch item kinds; a 409 echo asserted as the string; and the proxied
serve integration tests now splice the response's own token back in
verbatim rather than re-rendering a parsed one.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* feat(storage): add DoltGCFull for full, all-generation Dolt GC
Dolt GC is generational: every pass promotes the chunks reachable at that
moment into the old generation, and a default pass only visits the new
generation. Callers that rewrite history need a collection that revisits
the old generation too.
Adds versioncontrolops.DoltGCFull (CALL DOLT_GC('--full', '--archive-level',
'0')), the optional storage.FullGarbageCollector capability, and
implementations on both in-tree Dolt stores. No call sites change yet.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(gc): run a full Dolt GC after flatten and compact
The post-rewrite GC was Dolt's default, generational pass. Any earlier GC —
bd gc, or a previous flatten or compact — has already promoted the commit
chain into the old generation, which a default pass never revisits. The
rewrite orphans that chain, so the follow-up GC freed ~nothing on every
mature store and orphaned --as-of addresses kept resolving.
flatten, compact, and the proxied-server compact now finish with a full
collection, which frees everything a default pass frees plus the old
generation. Text mode prints a notice first (a full pass can take minutes on
large stores) and the JSON result reports gc_mode.
Unchanged: bd gc's own phase 3, bd admin compact --dolt, and the
managed-server shutdown GC all stay generational.
Fixes#5907
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(gc): add bd gc --full and hint when a default pass reclaims little
Periodic hygiene stays generational by default — a full pass costs minutes on
a large store and usually reclaims nothing extra. But phase 3 has flatten's
blind spot too: row data from decayed issues was promoted to the old
generation by an earlier GC, so a default pass cannot reclaim it. --full
selects a full collection on the embedded, server, and proxied paths.
When a default pass leaves a non-trivial store (>= 64 MiB) barely smaller
(< 1% freed), print a tip explaining the generational model and pointing at
--full. Unmeasurable sizes disable the hint.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(gc): cover suggestFullGC thresholds, GC help text, and bd gc --full
The threshold table includes the two field datapoints behind the
calibration: a large store that freed nothing hints, and the 1276 -> 971 MB
run that freed 24% does not.
The help-text assertions pin the wording in the three Cobra Long strings,
which are the source the CLI reference pages are generated from. One of them
also caught a line wrap that split "old generation" across a newline.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: explain why a Dolt garbage collection can reclaim nothing
Adds a subsection to the Dolt backend page covering the generational model —
promotion to the old generation, why a default pass never revisits it, and
why a full collection is a strict superset — and extends the History Bloat
runbook's Prevention advice with an occasional full pass.
Both pages describe the pinned release (v1.2.2), so they stay on the dolt CLI
and do not name the bd behavior this branch adds; the generated CLI reference
picks that up when the pin is bumped.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(upgrade-guard): parse the version witness as semver, and stop reading "unreadable" as "legacy"
The cross-era upgrade guard (#4907) refused five production workspaces
outright:
legacy Dolt server workspace detected; explicit migration is required
before this bd version can open or modify the workspace.
Every one was current-era. The witness was a Go pseudo-version,
`v1.1.1-0.20260805093327-bf97b73749ac`, and `currentVersionWitness` split
it on "." expecting exactly three fields. It got four. Measured blast
radius before the operator hand-rewrote nine `.local_version` files to
`1.1.0`: every `bd` invocation against five cities failed, taking every
order that shells out to bd with it — one gate sweep alone logged 644
failures in 6 hours, which froze PR review gates entirely (no bead ever
left `needs-review`), stalled triage, and left demand-driven pools at
zero (one city ran 1 session against 8 declared agents). Rewriting the
witness files took the sweep to 0 failures/6h immediately.
Two defects, one in the parse and one in the policy.
## The parse
`.local_version` holds `main.Version` verbatim, and release tooling
injects that by ldflags: goreleaser passes `{{.Version}}`, the release
workflow passes `steps.version.outputs.version`, and other build paths
pass whatever they resolved. So the writer can emit a plain release, a
release candidate, a build carrying metadata, or a Go pseudo-version —
all valid semantic versions, none of them three bare numeric fields. bd
could not read what bd wrote. The writer is right; recording anything
but the true version would destroy the ordering `CompareVersions` needs.
The reader was counting dots.
`classifyVersionWitness` now parses with `golang.org/x/mod/semver`
(already an indirect dependency) and reports an era. `legacyVersionMinor`
shares the parse, so a pre-1.0 pseudo-version or release candidate is now
*correctly* classified as legacy where it used to fall through
unrecognized. Shapes strict semver rejects but a distributor could still
stamp on a legacy build — zero-padded or four-component versions — are
still read as legacy from their major component alone, so the pre-1.0
guard only tightens.
## The policy
Before this change an unparseable witness meant "legacy workspace, refuse
every command". That is the part that turned a trivial parse bug into a
fleet outage, and it is wrong on its own terms: every pre-1.0 bd wrote a
plain X.Y.Z through this same writer, so a string that fails a real semver
parse is affirmative evidence *against* a legacy workspace. The guard was
inferring "legacy" from data that positively excludes it, using a file the
codebase treats as advisory everywhere else — `.local_version` is
gitignored, clone-local, written best-effort, and `bd doctor` downgrades a
bad value to a warning whose suggested fix is "run any bd command", which
the guard made impossible.
So a witness that is *present but unreadable* is now its own era,
unknown: bd warns and opens the workspace. A *missing* witness is
unchanged and still refused — a workspace that never announced itself is
genuinely ambiguous — as is any witness that reads as pre-1.0.
The warning is self-healing rather than permanent noise: the guard runs
in PersistentPreRunE immediately before `trackBdVersion`, which rewrites
the witness whenever it differs from `Version`, so the admitted command
leaves a readable witness behind and the next command is silent.
## Coverage
`TestClassifyVersionWitness` pins the production string, plain and
v-prefixed releases, release candidates, build metadata, the pre-1.0 side
of each, empty, and garbage. `TestVersionWitnessRoundTrip` pins the
contract the guard depends on — everything bd can write, including
`Version` itself, bd reads back and recognizes as current, which also
holds the writer inside the witness reader's bounded size.
`TestLegacyUpgradeGuardStillRefusesPreOneWorkspaces` and the missing-
witness test prove the cross-era guard did not relax. Red before the
parse fix on 15 cases across 5 tests.
Refs GH#5603. That report reaches the same conclusion from a different
writer — Homebrew stamps `HEAD-<shortsha>` into `main.Version` for
`--HEAD` installs — and the unknown era admits those workspaces too
(`TestLegacyUpgradeGuardAdmitsBrewHeadStamp`). It does not silence their
warning: a HEAD stamp is rewritten identically every run, so it never
heals. Silencing it wants the shape recognizer in GH#5625 (anisoptera),
which this deliberately does not duplicate; the two changes compose.
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(upgrade-guard): warn+open on a present-but-blank version witness
The legacy-upgrade guard's witness reader collapsed a present-but-blank
`.local_version` (0-byte or whitespace-only, e.g. from an interrupted or
disk-full best-effort write) into the same ("", false) result as a
genuinely missing witness. In server mode with a local Dolt root the
`if ok` reader-gate then routed present-blank onto the missing->refuse
path, hard-refusing a possibly-current workspace as "legacy Dolt server
workspace" with no self-heal -- the exact false-refusal class this PR
removes, left open for the blank-witness shape.
Make legacyUpgradeVersionWitness report presence independently of blank
contents: a present, bounded, regular witness returns ("", true) so the
guard classifies it witnessEraUnknown and warns-and-opens (matching the
present-but-unparseable case and the documented upgrading.md contract),
while a missing, non-regular, or oversized witness stays ("", false) and
still refuses, preserving the pre-1.0 guard safety invariant.
Adds guard-level tests for present-blank (0-byte / newline-only /
spaces+tabs) -> warn+open and missing -> refuse, plus a reader-contract
test pinning present-blank->present and missing/oversized->absent.
Addresses the maintainer review's one major finding (Codex).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Julian Knutsen <ci@beads.test>
Co-authored-by: Claude <noreply@anthropic.com>
* feat(events-journal): record the mutating actor on every journal row (bd-mbrxm)
The bd_events_journal row recorded op/ts/issue_id/payloads but never WHO
performed the mutation, so downstream attribution (e.g. same-field,
different-actor conflict detection over the journal) had nothing to key on.
- Schema: `actor VARCHAR(255) NOT NULL DEFAULT ''` on bd_events_journal, on
both migration planes (0066 + ignored/0025) so the two-door shape converges.
- Record*InTx takes the actor explicitly (no ambient ctx) — every call site
already sits beside an audit-event emit that has the actor in hand; thread
that same value (incl. the UOW door's MovePersistence). Comment rows carry
the comment's author. Blank = unattributed (derived maintenance, deletes —
follow-up bd-zxt49 — and pre-column rows); never user attribution.
- `bd events tail/export` JSON gains an additive, omitempty `actor` field;
the wire vocabulary is otherwise untouched (openapi spec, reference doc,
CHANGELOG; golden regenerated deliberately).
- CLI bundle: direct-DDL override for 0066 in cliCompatibleMigrationSQL —
dolt 2.2.0 (CI's pin) no-ops the prepared ALTER (dolthub/dolt#11345), so
without it the parity oracle sees actor only on the runtime side. Measured:
AllMigrationsSQL() through 2.2.0 lands bd_events_journal WITHOUT actor and
2.3.1 WITH; with the override both land it. String assertions + a
requireDoltColumnShape guard pin it without a Dolt binary.
Verified (enumerated): go build ./...; gofmt; go vet; migration hygiene
(BASE_SHA=07c163df0); internal/storage/schema (string test + CLI-apply test
under dolt 2.3.1 AND 2.2.0); internal/storage/domain/...; eventsjournal;
journalops; httpapi (wire-tag bijection incl. actor); storage/dolt
-run 'Journal|EventsJournal|ActorAttribution' against real dolt;
cmd/bd -run Events (golden); storage/uow -p 1 (-timeout 90m): every test green except 3
timeout-shaped reds (ConcurrentInstantiation lock-acquire, EndToEnd 30s
init-schema, PreexistingDirty docker reaper) in a /private/tmp worktree
under box load 40-68; the same 3 at origin/main in that worktree also
red, and at THIS commit in the primary clone all 3 PASS (130s) — box
flake, not the diff.
* docs(events-journal): align seq:4 example with the actorless golden fixture
Maintainer review follow-up on PR #5908 (bd-mbrxm). Both reviewers flagged that
the reference JSONL example's seq:4 is_blocked derived-maintenance row carried
"actor":"worker-1", contradicting the record-contract field table (derived
is_blocked recomputes are actorless) and the golden fixture
cmd/bd/testdata/events_journal_records.jsonl, which emits that same seq:4/bd-100
row without an actor. Drop the actor member so the doc example mirrors the
fixture byte-for-byte and consumers do not misclassify a system recompute as a
user write.
The other, optional review nit (the "stray typographic quote" in the
insertEventRow doc comment) is intentionally left as-is: that glyph is gofmt's
canonical rendering of '' in a Go 1.19+ doc comment (TeX-style quoting turns two
ASCII apostrophes into U+201D), so the reviewers' literal '' suggestion is a
no-op the enforced pre-commit gofmt reverts on every commit. It is cosmetic and
non-gating; the DDL and INSERT are already correct.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
The install instructions told users to run the upstream install.sh from
releases/latest, which today resolves to Dolt 2.3.1. Dolt 2.3.0 regressed
CALL DOLT_RESET('--hard'): a few percent of freshly created databases come
up with that procedure answering "Error 1105 (HY000): context canceled" for
the life of the server process. bd flatten and the Dolt-history compaction
in bd admin compact both finish by hard-resetting main onto a temporary
branch, and the merge-settle path behind bd dolt pull falls back to a hard
reset when it abandons a merge — so the documented happy path installed a
Dolt that breaks those operations on a database that otherwise looks fine.
Point the docs at a pinned version instead, with the measurements and the
raise criterion, and tell anyone already on 2.3.x how to check a database
and what to do about it. The pin and its rationale live in
scripts/ci/install-dolt.sh; the docs name the version once, on the Dolt
page, and everything else links there.
Also note that releases/latest resolves to the most recently created
release rather than the highest version, so it can move backwards — v1.88.2
was created after v2.2.4 and v2.3.0 — which makes "install latest" unsafe
independently of this defect.
test/docsync/doltpin_test.go keeps the documented pin, the copy-paste
install snippet and testutil.DoltDockerImage from drifting apart, which is
how the docs ended up on a broken release in the first place.
This documents the pin that gastownhall/beads#5894 applies to CI; land
after it so the reference to scripts/ci/install-dolt.sh resolves.
* fix(labels): normalize labels on write, as read paths already do (#5812)
bd applies utils.NormalizeLabels (trim, drop empty, dedupe) to every label
FILTER path -- list, search, ready, orphans, count and the workapi
equivalents -- but to no label WRITE path.
That asymmetry stores labels no filter can match:
bd create "T" --labels 'theme:a, theme:b' # stores "theme:a", " theme:b"
bd list --label theme:b # filter trims -- no match
--labels 'a, b' is the comma-space form most people type, and pflag's CSV
split leaves the leading space on the second element, so the split looks
like it worked. A filtered list that is silently short is
indistinguishable from a complete one.
Two more everyday inputs corrupt just as quietly: --labels 'a,,b' stores
an empty label, and --labels 'a,a' stores the same label twice.
Apply the existing helper on the write paths so write and read agree:
create (--labels and its --label alias, normalized after merging the two
so dedupe spans both), quick, and update (--add-label, --remove-label,
--set-labels). --remove-label matters as much as the additive flags: an
untrimmed ' theme:a' fails to match the stored label and silently removes
nothing. The --set-labels '' clear-all signal is preserved -- it is gated
on pointer identity, not slice length.
Also add a warn-only 'Label Whitespace' doctor check, since the write-path
fix does nothing for labels already stored and nothing else surfaces them.
It reports leading/trailing and blank labels only. A label whose trimmed
form still contains whitespace is deliberately not reported: that turns on
what a space between labels should mean, which this change does not
settle, and "good first issue" is a legitimate multi-word label.
Not auto-fixable by design -- trimming a damaged label can collide with a
correct label already on the same issue, which needs a human decision.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* feat(labels): warn when a stored label contains a space (#5812)
A label containing a space is almost always a comma that was meant and
missed. That is the failure behind #5812's evidence: 150 corrupt label
rows across 111 issues, found months later only because theme-by-theme
counts failed to reconcile.
The issue proposed splitting labels on whitespace as well as commas. This
deliberately does NOT do that, and the reasoning is worth recording.
A shell has exactly one mechanism for "is this one word or two", and it is
already unambiguous. All three of these send ONE argument:
bd create T --labels 'one two'
bd create T --labels "one two"
bd create T --labels one\ two
They are byte-identical by the time bd sees them: quoting and backslash-
escaping are consumed by the shell, which reports only the resulting word
boundaries. It is the same mechanism that makes 'cd my\ dir' work.
Splitting on whitespace would therefore override a boundary the caller has
already explicitly set, making labels the one place on the command line
where quoting does not mean what it means everywhere else. It is also
undoable: with splitting there is no way left to ask for a label containing
a space except a second, nested layer of quotes. And it cannot deliver what
it appears to promise, since 'one two' and "one two" are indistinguishable
by the time any code could act on them.
So honor the shell's boundaries, which bd already does, and warn instead:
⚠ Stored "theme:a theme:b" as ONE label — it contains a space.
If you meant several labels, separate them with commas (a,b) or
repeat the flag.
The 150 rows would have produced 150 warnings at the keystroke, while
--labels 'good first issue' still does exactly what it says. A warning
rather than an error, because a space-containing label is a legitimate
thing to ask for and the shell has just been used to ask for it; --quiet
silences it. No command changes meaning.
Applied to the paths that write labels: create, q, --add-label and
--set-labels. Deliberately not --remove-label, because removing a
space-containing label is how the damage gets repaired and warning on the
repair is noise.
The Label Whitespace doctor check gains a matching third class so an
existing database can find the ones already in it. It is reported
separately from the untrimmed/blank classes and is not called corruption:
bd cannot tell "good first issue" from a missed comma, so it surfaces them
and a human decides.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(labels): close the last raw label write, bd tag (#5812)
Review feedback on #5813. `bd tag` describes itself as "Shorthand for
'bd update <id> --add-label <label>'" and was not: update normalizes and warns,
tag passed the positional straight to AddLabel, and the proxied route passed it
to ApplyLabelPatch, which drops "" but does not trim.
Verified on a scratch DB against binaries built either side of this commit:
before: bd tag t-fap ' theme:spaced' -> stored " theme:spaced"
bd list --label theme:spaced -> 0 rows
after: bd tag t-wjz ' theme:spaced' -> stored "theme:spaced"
bd list --label theme:spaced -> 1 row
That is the unfilterable class this PR set out to close, written by the command
whose help text promises equivalence with the one that already closed it.
Normalization happens in tag.go BEFORE the route split, so the direct and
proxied paths cannot diverge on it; runTagProxiedServer now takes the resolved
id and label rather than raw args, which removes the second entry point.
A whitespace-only label is refused (exit 1) rather than dropped. The plural
flags can discard an empty element and still honor the rest of the request;
bd tag has exactly one label to add, so dropping it would report success having
written nothing.
Also here, both from the same review:
- `bd label add` now warns too. splitLabelArg already trimmed, so it never
stored the untrimmed class, but it could not tell a caller that
`bd label add bd-1 'theme:a theme:b'` is ONE label. Verified firing.
- docs/core-concepts/labels.md: says plainly that import and batch ingest are
deliberately NOT normalized (round-trip fidelity; the doctor check is what
finds legacy damage), so the next reader does not "fix" it. Also notes that
bare `bd doctor` is not yet supported in embedded mode (GH#3794), so the new
Label Whitespace check reaches classic and server-mode databases only --
"run bd doctor" was overselling to embedded users.
- CHANGELOG entries under Fixed and Added.
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
* docs(troubleshooting): document the two native-Windows integration traps
bd.exe is a native Windows binary, and two consequences of that are
undocumented. Both cost real debugging time because neither fails loudly.
- npm installs bd as a generated bd.cmd shim, so Node's execFile/spawn --
which run their target directly, without a shell -- never resolve it and
die with "spawn bd ENOENT" while bd works in the same terminal.
- Git Bash resolves /tmp to its own temp directory; bd, being native,
resolves it against the current drive root. `bd export -o /tmp/x.jsonl`
reports success and writes C:\tmp\x.jsonl.
Adds a subsection for each under Platform-Specific Issues, following the
symptom/solution shape already used there, plus cross-links from the FAQ
Windows entry and the installation Windows notes.
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of CuongBPV
* Update troubleshooting for Windows `/tmp` path issues
Clarify behavior of `/tmp` paths in Git Bash and provide solutions for Windows path handling.
* Update FAQ for Windows integration details
Clarify integration details regarding `bd.exe` and `/tmp` paths in Windows.
---------
Co-authored-by: CuongBPV <cuongbpv@fpt.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.)
Adversarial review of the previous commit refuted three of its claims:
F1 (HIGH) "a heartbeat never re-homes a foreign lease" is false on a
reachable path INSIDE the function the comment annotates: the ga-v2k49
disambiguation fallback fires when the lease row spells the holder
differently, re-arms through UpsertLeaseInTx, and its ON DUPLICATE KEY
UPDATE stamps the local node over the foreign one (reviewer confirmed it
against embedded dolt). The invariant is a property of the fast path, not
of the lease row; say so, and name the fallback.
F2 (MED) RestoreLeaseOnImportInTx takes granted_node from the snapshot
when the local row is EXPIRED, so an import can relabel this node's own
stale lease with a remote name — a third stranding state the enumeration
missed.
F3 (MED) the prose named only bare --any-replica, which reverts EVERY
foreign stale lease including live peers'. All three sites (summary line,
federation.md, reclaim --help) now name the narrow levers first:
--any-replica --id <id>, or bd unclaim --force <id>.
Also F5/F8 (LOW): -v shows the first foreignSkipDetailRows, not "the
individual leases" — the summary and both doc sites now say so.
F5: a lease granted by another replica is by construction never reclaimed
here, so reportForeignSkips was not a one-off — it re-emitted one stderr line
per stranded remote lease on EVERY reclaim run. A supervisor on a 1-minute
timer against a federated store with N of them printed N lines/minute forever.
The default is now ONE summary line per run (total exact, at most three
granting replicas named, the rest collapsed into a count), with the per-lease
detail behind `bd -v` / BD_DEBUG and itself capped at 20 with a collapsed tail.
The summary query groups by granting replica, so its row count is bounded by
the deployment's topology rather than by the amount of stranded work. Under
--quiet the audit now skips its queries entirely instead of running them to
discard the output. Still stderr-only: `bd reclaim --json` owns stdout and its
payload is unchanged.
F4: reviewed and KEPT the backfill-never-overwrite invariant. Re-homing
granted_node on heartbeat would clear both stranding states (a renamed replica
seeing its own leases as foreign; an imported foreign lease heartbeated
locally), but it would also let a heartbeat arriving here silently reassign
enforcement of a lease another replica granted — the exact robbery the guard
exists to prevent, since a remote liveness view is stale by up to one sync
interval. The trap is now documented where the code lives (HeartbeatIssueInTx),
in docs/multi-agent/federation.md, and in `bd reclaim --help`, with
--any-replica named as the escape hatch.
* 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>
The gs:// remote path works — full clone of a 115k-chunk production DB in
5 seconds, incremental syncs in ~4s, ADC auth, zero servers — but nothing
in the docs said "point two machines at a bucket and you have a
federation", so discovering it meant reading Dolt internals.
New page docs/multi-agent/bucket-federation.md walks the whole path:
create the bucket path -> bd dolt remote add + bd dolt push to seed ->
bd init --remote to birth the second replica -> bd sync on a timer, with
the exit-code table a timer branches on and the three rules that set the
interval (staleness is the interval; lease TTL and reclaim grace must
exceed it; a longer interval means more conflicts, because updated_at is
touched by every mutation).
Carries the measured cost from a production two-machine deployment
(28s cold push, 5s clone, ~4s incremental push, ~1s pull+merge at ~1.3k
issues / ~115k chunks) and the failure modes that path actually hits:
raw `dolt remote add` leaving the SQL server blind to the remote, a
fresh machine with no Dolt commit identity failing even a no-op merge,
server-mode credentials being whatever the server inherited at startup
(GH#6), remote-name drift between replicas, conflict resolution through
the dolt_conflicts tables, and one bucket path per database.
Registered in the Mintlify nav and cross-linked from the multi-agent
index and from the federation guide, which keeps DoltHub as the
zero-config default and points here for the BYO-cloud story.
Select timeout or gtimeout only after a successful GNU coreutils identity probe, validate BEADS_HOOK_TIMEOUT as positive whole seconds, and preserve the Perl and warned direct fallbacks under inherited shell options.
Keep GNU and Perl deadlines soft and backend-scoped, preserve natural status 137, regenerate every tracked hook artifact, and exercise the real process boundary through the required three-host preflight.
Fixes#5503
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
Three beads (ga-uwix0.1, ga-2yaqp.5, ga-2yaqp.6) plus a fable review round.
Docs and spec prose only: all 19 touched .go files are gofmt-normalized,
comment-stripped byte-identical to main. The one exception is deliberate and
reviewed — scripts/check_doc_freshness_test.go gains a data row, because the
delegated gate ruling required it.
ga-uwix0.1 — #5516 gave bd serve optional bearer auth and made it MANDATORY
beyond loopback; fifteen prose sites still said the opposite. The three the
council named are reworded to the stronger true form (the actor is not the
authenticated principal even where a bearer is required; a shared token admits
a client to the WHOLE surface and grants no narrower right). The sweep for a
fourth found eight more in five spellings the audit's grep could not reach,
including claim.go's "any client can claim as any name", release.go's
no-AUTHORIZATION variant, and six memory/settings-plane sites where the true
statement is sharper: a bearer decides WHO may call, never what a caller who
is let in may read. The review round found four more in the CHANGELOG's
UNRELEASED section, which round one had misclassified as released history —
they would have shipped false in the same release as the auth entry.
The serve runbook's "Binding beyond loopback" section was actionably wrong: it
said the flag "prints a warning and changes nothing else", and its refusals
table quoted a string not in the binary. Rewritten against a build, with every
flag, error string, event name and reason value produced by running the
command. It gains the operational trap nobody had written down: /healthz is
auth-exempt and GET /v0/beads/ready is not, so an unauthenticated readiness
probe earns a 401 forever while liveness stays green. The runbook is now IN
scripts/check-doc-freshness.sh, pinned to the four files it is read against.
ga-2yaqp.5 — nine prose defects, every count re-derived rather than trusted;
three of the audit's own numbers had moved again. 38 route rows and 36
capability-bearing ones; thirteen pinned schemas, not twelve or seven; six
missing entries in the no-query-parameter list, not five; twenty-eight role
accessors, not twenty-seven; nineteen patch members, not thirteen. Two prose
"code counts" were counting paragraphs. CodeAlreadyClaimed claimed the holder
is always attached when only one of four producers always attaches it and
releaseIssue never does. MetadataCAS's leaf contradicted its own shipped wire.
The path/operationId inversion is now recorded where a spec author looks.
ga-2yaqp.6 — the role checklist refreshed against what this wave's additions
actually cost, traced to real commits. Step 10 sent people to a name list
#5460 deleted. The "four more edits" claim was stated twice and undercounted
both times: the two freshest wire slices share a nine-file core plus
roles_test.go. The step-with-no-number gained the fact that explains its
instances — write-role decorators wrap, read-role decorators recurse, so the
call lands on the stub, and both real instances are reads. The wave got its
first CHANGELOG entry: six new public operations, not three, and zero new role
accessors in the window.
Review verdict: FIX-REQUIRED then all items addressed. The reviewer
live-falsified the strong auth form and failed to break it, and confirmed
every recount re-derives exact.
Priority used the filled circle also mapped to status-blocked, so agents
misread ready work as blocked (GH#4996). Render P-labels only; document
the convention for agents; keep ● for blocked status alone.
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
`bd show` printed "DEPENDS ON" on an issue that another supersedes, and
"BLOCKS" on its replacement instead of the obvious "SUPERSEDED BY" and
"SUPERSEDES." "BLOCKS" was doubly wrong since supersedes takes no part
in ready-work calculation.
Only blocks, parent-child, related and discovered-from had verbiage of
their own; duplicates, replies-to, tracks, attests and every other type
fell through to a `default: blocks` fallback, while conditional-blocks
and waits-for do block but lost the distinction.
One table now names each type from both ends of its edge and all three
renderers share it.
Type names have no consistent left-to-right reading, so each entry takes
its direction from the command that writes the edge: `bd supersede old
--with new` stores (old, new), making the source the replaced issue.
Same bug elsewhere, also fixed: `bd show --refs` headed groups with the
bare type name, so a canonical issue announced itself as the copy; `bd
dep add` and `rm` said "depends on" whatever the type; `bd dep list`'s
batch header said "X depends on:"; `bd list --deps` had supersedes and
conditional-blocks backwards; and the dependencies doc described
supersedes in reverse.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
BatchCreateOptions.OrphanHandling had four modes and one behavior. Every
production call site passed OrphanAllow (or left the field at its zero
value, which took the same branch), so CheckOrphan returned (false, nil)
on every path it could reach — after paying a SELECT COUNT(*)
parent-existence probe on every hierarchical-ID create to feed a switch
whose only reachable arm ignored the answer.
OrphanStrict and OrphanSkip were reachable from exactly one conformance
case, testAuditCreateOrphanHandling, which existed to execute them.
OrphanResurrect was never a branch at all: it shared the default arm with
OrphanAllow, and the "auto-resurrects missing parents from database
history" behavior its doc comment described left with the JSONL sync
layer. internal/beads' TestImportWithDeletedParent still asserted that
removed behavior; it goes too.
This removes the type, the four constants, the field, CheckOrphan and its
call site, the backend package's alias and re-exports (a breaking change
to a published package, signed off by the owner), the dead
ImportOptions.OrphanHandling, and the import.orphan_handling row in the
yaml-only-key test — replaced with import.unlisted-key, which keeps the
"import.* is exact-match, not a prefix namespace" assertion the row was
actually providing.
The behavior that remains is what OrphanAllow always did: a hierarchical
create whose parent is missing is accepted, and the child's auxiliary
counter row is skipped because it would have no owner
(TestReconcileChildCountersSkipsMissingParent pins that). The wasted
query is gone from the create path.
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
GET /v0/beads/events:watch holds a text/event-stream response open and emits
each committed mutation as it lands, so a consumer learns about a write when it
happens instead of on its next interval. It is a SIBLING of the paged read, not
a mode of it: `follow=true` would have given one operationId two media types,
two lifetimes, two limit rules and two capacity stories, and a client generated
from the document could not have described either.
THE CURSOR IS STILL THE CONTRACT, which is what makes this cheap to publish.
The server keeps no per-consumer state and remembers no subscription; a stream
is the `since` reads a poller would have performed, performed on its behalf
against the same ReadEventsJournalPage through the same read-only cursor. Every
event carries `id: <seq>`, so the checkpoint a client holds while streaming is
the number it would have held while polling, and `Last-Event-ID` — the header a
browser's EventSource resends by itself — takes exactly the value `since` takes.
That header WINS over the parameter, because the client that sends it did not
choose to: an EventSource reconnects to the URL it was built with, so honoring
`since` there would replay every record since the consumer started, on every
reconnect, forever. A nonempty unparseable one is a 400 naming the header rather
than a silent fallback, which would start a stream somewhere the client did not
ask for and never tell it; an EMPTY one means "no id yet" and defers to `since`,
because a client that always sets the header sends it empty on its first
connect and refusing that would break the request the header exists to serve.
Delivery is at-least-once against the client's own checkpoint: exactly once and
in order within a stream, duplicates only across a reconnect. No engine or
storage change — this consumes the poll read path.
EVERY REFUSAL IS DECIDED BEFORE THE FIRST BYTE — validation, the disabled 409,
the flush check, the stream cap, and then the first read, which is what turns a
pruned-past cursor into the paged read's own 410 rather than a 200 that
immediately reports its own failure. Exactly one failure can arrive after the
status is spent: a prune racing an open stream, emitted as a NAMED `truncated`
event carrying the 410's own body in the same encoding on one line (asserted
against Write's output, not merely agreeing with it), behind a raised `retry`
and followed by a close. Naming only the exception is what lets a bare
`onmessage` consumer treat an unrecognized event as "stop, this is not a
record"; one that ignores it does not lose records silently, it stalls loudly on
connect-time 410s, slowly. The other unreportable failure — a stored payload
that will not encode — ends the stream too, and names its seq in the log,
because it will end every stream that reaches that row and nothing else would
say which one it is.
THREE LIMITS HAD TO MOVE, and the middle one is the trap.
- requestDeadline (60s) does not apply to a streaming row. For every other
operation it is the backstop against a request holding resources forever;
here it would do nothing but sever the stream. Each READ carries a 15s
deadline instead — a liveness budget rather than a database one, since it
also bounds how long a stream can go without a heartbeat and how long it can
ignore a shutdown.
- http.Server.ReadTimeout (30s) had to be cleared per request, BEFORE the
connect read. There is no WriteTimeout on this server — statusWriter rolls a
deadline forward before every write, which bounds one stalled write rather
than a stream, and needs nothing here — but ReadTimeout is a deadline on the
WHOLE request, and net/http keeps a background read running while a handler
writes: the read that notices a disconnect. Its expiry cancels the request
context, so an idle stream would end itself at thirty seconds with no client
involved, and a database wedged during the connect read would be booked as
`client_closed`. Clearing it costs no disconnect detection — a client that
leaves still produces a read error — and a peer that vanishes without a FIN
is reaped by TCP keepalive, which Go's listener enables by default
(measured: 15s idle, 15s interval, 9 probes; ~150s).
- The database slot moves from the request to the read. Sixteen slots and
forty-eight stream places means one slot per open stream would let a handful
of idle consumers starve every other operation for hours with /healthz
green; a stream now takes a slot for the moment of each poll and gives it
back, and slot pressure delays a pass instead of ending a stream.
Streams are capped at 48, SIXTEEN BELOW the 64-connection limit, and the gap is
load-bearing arithmetic rather than caution: LimitListener returns a connection
slot only when the connection closes, which is after the handler returned and
after this counter came down, so a cap at maxConns could never be observed — the
connect that should earn the 503 would never be accepted, and neither would the
poll it is told to fall back to, nor a mutation, nor a fresh-connection
/healthz. The headroom makes the refusal deliverable; `events_watch_admitted`
carries the live gauge on every connect so accumulation is visible before the
cliff. Each stream jitters its own poll phase by ±10%, because consumers
reconnect together after a restart on one shared `retry` and a fixed interval
would march them into a single read burst per second forever. And a graceful
shutdown signals its streams (RegisterOnShutdown) rather than waiting them out;
the loop consults that signal and the client on EVERY pass, including the
draining ones, so a week-old backlog stays cancellable within one batch.
Tests: handler-level over live delivery (mutations land AFTER the connect),
id=seq, heartbeats, Last-Event-ID precedence including a stale header against a
live `since` and the empty-header polarity, the 400/409/410 connect legs, a
prune under an open stream, the cap and its 503, the cap's headroom against
maxConns, backlog drains cancelled by both a hangup and a shutdown, slot release
on every exit, a stream sharing a single-slot semaphore with a paged read, the
flusher refusal, the read-deadline clear and its ordering against the connect
read, jitter spread, and a clean drain with a stream open — all under -race.
Framing is pinned against a record whose payload carries literal newlines, a CR
and a `data:` line of its own. Two e2e legs through a real `bd serve`: mutate on
one connection while streaming on another under a 10s arrival bound, then
reconnect with Last-Event-ID and require the resume, plus the disabled refusal.
Mutated and each caught: the mid-stream truncated event, Last-Event-ID
precedence, the empty-header polarity, the cap decrement, the cap's headroom,
the drain-cancel fast path, the read-deadline clear and its ordering, the poll
jitter, the shutdown exit, and the deadline exemption.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
GET /v0/beads/events pages the durable mutation journal from a caller-held
checkpoint, so a hosted consumer stops shelling out to `bd events tail`. The
journal and its retention contract already landed; this is the consumption
surface for them.
THE RECORDS ARE THE CLI'S RECORDS, and that is a machine fact rather than a
promise. The envelope and its projection moved out of cmd/bd into
internal/eventsjournal, beside the activation and auto-prune logic that already
had to be reachable from two binaries; the spec pins EventRecord to that struct
with x-go-type, pinning.go proves the generator emitted an alias, and the
committed golden fixture now renders through the same function the handler
serves from. A second wire struct in internal/httpapi would have passed its own
tests while quietly shipping a different `ts` shape or a `dep` that appeared
when empty, and the consumer who notices is the one reconciling an HTTP mirror
against a CLI export.
THREE ANSWERS THE DATA CANNOT TELL APART, which is most of the design:
- CAUGHT UP is a 200 with an empty list. "Nothing new yet" is an ordinary
answer about a log, and a poller whose steady state was a 404 would have to
treat this surface's miss vocabulary as its happy path.
- DISABLED is a 409 `events_journal_disabled`. A journal that is off reads as
zero rows and a head of zero — byte-identical to an enabled journal nothing
has written yet — so without this gate a consumer would poll a workspace
that will never emit a record and call itself caught up forever. Activation
is workspace state, so it is resolved by cmd/bd (eventsjournal.EnabledFor)
and handed in; this package resolves no workspace state of its own. A 409
for CodeNotClosable's reason: a statement about state the client cannot see,
which the same request stops earning once an operator changes it.
- PRUNED PAST is a 410 `events_journal_truncated` carrying `since`, `floor`
and `head`. It is the surface's only 410 and it is the right one: those
records existed, were addressable by exactly this request, and were
deliberately deleted — retrying the same `since` can never succeed, which is
what a 404 would wrongly invite. The mapping lives in ClassifyError, keyed
on the typed error with errors.As, so neither database source can forget it;
the code is storage's own constant, so the CLI's `--json` failure and this
body cannot drift to two spellings of one condition.
`head` is why the read seam grew. ReadEventsJournal answers what came next and
cannot answer "keep asking, or wait?", so ReadEventsPageInTx returns the rows
and the counter head from ONE transaction, read in that order — a head taken
first could land below the last row served, which a consumer reads as "past the
end" and stalls on. `bd events tail --follow` keeps the cheaper path: it runs
the truncation decision every second and pays for a head read only in the
ambiguous cases.
The handler holds storage.EventsJournalCursor, a read-only interface, not the
wider accessor the CLI takes. There is no prune, no acknowledge and no
truncate over HTTP: retention stays a workspace decision, and a surface
documented to publish the journal should not be one line from a delete.
EventsJournal is the first CONDITIONAL role on httpapi.Config — required
exactly when the workspace's journal is enabled. A storage backend with no
journal seam is an ordinary backend as long as nobody asked it to record
anything (eventsjournal.Apply takes the same deal at open time), and demanding
it unconditionally refused to start two registered-backend servers that had no
use for it.
`limit` runs 1..10000 defaulting to 1000, and `0` is REFUSED rather than
meaning unlimited as it does on the issue listings: a caller resuming from an
old checkpoint would otherwise ask one process to buffer the whole retained
window. `since` is required — defaulting a missing checkpoint to zero serves
the entire window to a consumer that meant to resume, which arrives as a flood
of duplicates rather than as an error.
Tests: handler-level over both refusals, the caught-up/empty/disabled trio, the
limit bounds and an int64 checkpoint; a storage-level head guard against the
real embedded store; and three end-to-end legs through a real `bd serve` —
mutate over HTTP then read the journal back gapless, prune and meet the 410 then
recover from floor-1, and a disabled workspace refusing. The truncation mapping,
the disabled gate, the window members and the limit ceiling were each mutated
and each failed a test.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
Enabling the journal now yields a BOUNDED feed. Until this commit the only
thing that deleted a record was an operator typing `bd events prune`, so the
person who turned the feature on was not the person who discovered, months
later, that a table nobody reads had become the largest thing in the database.
Retention floors already described the window a consumer is guaranteed; this
applies them without being asked.
The shape is SQLite's WAL auto-checkpoint rather than a background compactor,
with Dolt's auto-GC as the second reference: the WRITER pays, immediately after
its own commit, only when a cheap persisted threshold says work is due, and
never for more than a fixed slice of it. Neither needs a daemon, and neither can
turn a user's command into an unbounded wait. Only the trigger and amortization
pattern transfer — the journal needs no finalization data movement, so our
checkpoint analog is pure prefix deletion.
POLICY IS THE FLOORS, and it is not a second implementation.
ComputeEventsAutoPruneBoundInTx hands the EXISTING resolver an unbounded request
(before = head+1) and keeps whatever the floors leave, through the same two
scalar reads `bd events prune` uses — now factored into one place so a floor
cannot mean one thing when an operator asks for it and another when maintenance
applies it. Both floors disabled means the operator chose an unbounded ledger,
and auto-prune becomes a no-op that does not even read the throttle.
TRIGGER is the root PersistentPostRunE maintenance net, last after Dolt
auto-commit, auto-backup, auto-export and auto-push, before the store closes.
That is the narrowest existing seam with the four properties this needs: the
command succeeded (cobra never reaches PostRunE on an error return), its
transaction is closed, a plumbing is still open, and the read classification is
already made there. It fires at most once per process. Four gates keep it
writer-pays, each one load-bearing rather than decorative: the post-command
maintenance policy (strict --readonly, `bd serve`); the read-only
classification, without which `bd list` prunes the journal, since a read-only
classification still opens a writable store; preview commands (--dry-run,
--inspect), which promised not to mutate and are held to it by a
write-refusing open; and the whole `bd events` family, because reading a feed
must never be what prunes it and `bd events prune` has just resolved the bound
by hand. `bd events tail` joins the read-only classification while it is at it
— it is a pure read that had been opening a writable store. Both write
plumbings are covered: the store path and the proxied-server unit-of-work
provider, which commits maintenance in the ephemeral form (no Dolt commit) that
dolt_ignored tables require.
`bd serve` has no command boundary, so it drives the same routine from a ticker
with a clean, self-contained shutdown. It reads the same persisted watermark
every CLI process reads, so a server and the CLIs beside it share one schedule
rather than three.
EXECUTION is its own transaction per batch: `DELETE ... WHERE seq < ? ORDER BY
seq ASC LIMIT 10000`, at most 3 batches per pass, all of it under a 30-second
pass budget and on NO-RETRY transactions. Maintenance is humble by
construction: the retry helper a user's write deserves would spend up to
fifteen seconds of backoff per transaction losing races on work nobody asked
for, and a maintenance transaction that loses a race has nothing to recover —
the prefix delete is idempotent and the next trigger resumes. ORDER BY is not
decoration —
without it a limited delete may remove an arbitrary subset, and a hole above the
floor is silent loss the left-edge truncation check cannot report. Verified
against the real engine that Dolt accepts the ordered, limited single-table
delete. A backlog larger than one pass drains over the next few commands instead
of stalling this one. Every failure is logged and swallowed: maintenance must
never fail a user's command.
THROTTLE is a watermark (ts + head) in local_metadata, the clone-local ignored
plane, read together with the seq counter in ONE query — the not-due answer, the
overwhelmingly common one, costs a single indexed lookup. Due means an hour
elapsed or 5k records advanced; both are constants, because they tune how often
maintenance amortizes rather than promising anything. A stamp far in the FUTURE
(a clock stepped forward and later corrected) also reads as due, or the
interval trigger would never fire again on a workspace that looks healthy. The
watermark is stamped BEFORE the deletes, in a transaction of its OWN, so a
persistently failing prune degrades to no maintenance rather than to a retry on
every command — sharing that transaction with the bound read, as the first cut
did, rolls the stamp back with the failure and reinstates exactly the
per-command penalty the ordering exists to prevent. Racing processes are
idempotent: a prefix delete that already happened is indistinguishable from one
that just did. A workspace with the journal off pays nothing at all.
CONFIG: `events-journal-auto-prune`, default true, BD_EVENTS_JOURNAL_AUTO_PRUNE,
a config.yaml startup key like the other three (YamlOnlyKeys — without that entry
`bd config set` reports success and changes nothing; all four are also added to
the recognized-key set, so the documented opt-out no longer prints an
unrecognized-key warning beside a command that worked). The resolver now reads
the YAML 1.1 boolean spellings, which is a data-deletion fix rather than a
nicety: an unreadable value falls through to the key's DEFAULT, so
`events-journal-auto-prune: no` had read as "keep pruning" — an opt-out that
went on deleting the records it was written to preserve. Its two resolution
arms (no workspace yet, and a resolved workspace) now agree on an unreadable
value instead of splitting false/true. Manual `bd events prune` remains for an
earlier, on-demand cut below the floors; physical disk reclaim still rides
`dolt gc`.
SCOPE: a pass maintains the workspace whose command triggered it. A routed
write (`bd create --repo ../other`) journals into the target, but the trigger
runs against the launcher's own workspace and plumbing — one command must not
open maintenance transactions on every database it wrote to in passing — so a
workspace only ever written remotely relies on commands run in it, or on its
own `bd serve`. Stated in the docs rather than papered over.
Consumer safety is unchanged. ComputeEventsPruneWhere, the truncation contract
and the seq counter are untouched; deletion is still prefix-only and still
bounded by the floors, and a laggard still gets the typed truncation error.
Docs corrected, because four places said the opposite:
- docs/reference/events-journal.md: "manual to prune" in the opening, and
"Pruning is manual. Nothing deletes journal records on your behalf." at the
head of the retention section, which is rewritten around the new default;
the config table gains the key and stops attributing the floors to the CLI
command alone.
- cmd/bd/events.go: `bd events prune` said "Pruning is manual: nothing deletes
journal rows on your behalf"; it now says retention is enforced to the
floors automatically and this command is for an EARLIER, on-demand cut
BELOW the floors — it cannot cut deeper than they allow, so shrinking the
retained window means lowering them. `bd events` gains the same summary.
- CHANGELOG.md: "Pruning is manual — nothing deletes journal records on your
behalf" replaced by the bounded-by-default story, including the volume
trigger and the per-workspace scope.
- internal/config/config.go and internal/storage/issueops/journal_prune.go:
floors are no longer described as belonging to `bd events prune`.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
Adds docs/reference/events-journal.md: what the journal is (a durable,
replayable, clone-local record of committed mutations), how to enable it,
the record contract and its seven ops, the typed truncation error and how a
consumer recovers, manual pruning and the retention floors, the boundaries
(per replica, per branch, sync/raw SQL/store-open/compaction non-coverage),
and how the dolt_ignored tables sit in Dolt.
Every technical claim is derived from the code on this branch — cmd/bd
events help text, the issueops journal engine, the migrations, and the
config defaults — and states the same contract the CLI help does.
It lands in Reference rather than Core Concepts because the page specifies a
machine-facing contract rather than teaching the bead/dependency model; it
sits beside the JSON output contract and observability, the two other pages
an integrator reads. A short orientation section separates the three
event-ish systems (script hooks, audit history, the journal) so a reader
picks the right one, and reference/advanced.md no longer claims there is no
`bd events` command.
CHANGELOG records the new commands, the opt-in journal and its three config
keys, the events_journal_truncated failure mode, and is_blocked joining the
documented /v0 issue schemas.
Both the page and migration 0064's down script also record the one destructive
outcome that raises no error: dropping and recreating the journal tables, or
losing bd_events_seq, restarts the sequence space at 1, so a parked consumer's
checkpoint sits above the new head and reads as "caught up" forever. Nothing
about the new journal looks pruned, so the typed truncation error cannot report
it — the only remedy is to re-baseline, and the only defence is saying so where
someone will be standing when it happens.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
Both files had their Last reviewed markers refreshed today without the content
gaps being closed, so the freshness signal is currently green on two docs that
are missing real material.
azure-devops.md — `ado.reconcile_interval` is undocumented. It is real,
user-tunable config (internal/ado/reconcile.go, default 10) setting how many
syncs pass between automatic reconciliation scans, and the doc already documents
the `--reconcile` flag that forces one. Adds a Reconciliation section, and notes
that `ado.syncs_since_reconcile` is beads' own counter rather than a setting.
otel-data-model.md — claims a complete schema but lists 7 of 111 storage spans,
so the issueops role surface is invisible to anyone instrumenting from it.
Rather than 100+ prose sections that would drift again, state the rule the code
follows — span name is "storage." + operation name, which is also the
db.operation attribute (InstrumentedStorage.op) — and inventory both families:
72 direct storage.<Method> spans and 39 storage.<Role>.<Method> spans.
Also records why the families do not double-count: the role decorators wrap the
UNINSTRUMENTED store (IssueLifecycle calls Unwrap() before wrapping), so one
logical operation emits one span on either path and the counters stay
comparable.
No behaviour change; documentation catching up to the code.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>