#7301 scoped the pre-migration read failure on a shared server to schemas
that "predate 1.2.0". That misses 1.2.2, the recovery re-release of the
1.1 line: its migrations stop at 0053 with no lease migrations, so a 1.2.2
server sits at v53 like 1.1.x. Upgrading such a server's clients to 1.3.1
without `bd migrate schema` makes `bd list`, `bd show` and `bd ready` fail
with `table not found: leases`.
Key the caveat to schema v53 or older, naming 1.1.x and 1.2.2, which
matches the section's own "A 1.2.2 or 1.1.x database sits at schema v53".
Refs #6929, #7284, #7301
* docs(upgrading): scope the shared-server read failure to pre-1.2.0 schemas
#7284 said most reads fail between upgrading a shared server's clients
and running `bd migrate schema`. That only holds for a schema older than
1.2.0: the leases table ships with main migration 0055 and ignored 0012
and 0016, all in v1.2.0. From 1.2.x, reads keep working and only writes
are refused (probed against a 1.2.1 server with 1.3.1 and main builds).
Restore the original wording and add the pre-1.2.0 caveat, naming only
the observed `bd list` failure from #6929.
Refs #6929
* docs: add beads-viewer (Paseo plugin) to community tools
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit ad28cf00ba)
* Add LazyBeads (lb) to community tools
- List lesliesrussell/lazybeads under Terminal UIs
- Note that it is unrelated to the earlier lazybeads under Historical
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit 1aa2b645e2)
* docs(community-tools): update the beads-web entry
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit aa177110b3)
* docs(community-tools): mention the beads-web tree view
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QebAVaD36wUemAsdBx8wwJ
(cherry picked from commit e0eb482a11)
* Updated community tools documentation with Beads Tracker
Applied changes from BB to 1 file
Files modified:
- docs/community-tools.md
Updated community tools documentation
Applied changes from BB to 1 file
Files modified:
- docs/community-tools.md
Updated community tools documentation
Applied changes from BB to 1 file
Files modified:
- docs/community-tools.md
(cherry picked from commit 75d0f8de0c)
* docs: add b9s to community tools (TUI and web UI)
(cherry picked from commit 8bb6ab6913)
* docs: add btui to community tools (btui-bb2)
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Andreas Dellrud
(cherry picked from commit 81da372c63)
* docs: mention released btui Beads 1.3 support (btui-0fm)
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Andreas Dellrud
(cherry picked from commit 8f27445bee)
* docs: add beadside to community tools
(cherry picked from commit 2c2cb1fd5c)
* docs: add Beads for Obsidian to community tools
(cherry picked from commit cb82d067d8)
---------
Co-authored-by: cuongntr <cuongntr@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Leslie Russell <leslierussell@gmail.com>
Co-authored-by: weselow <598746@gmail.com>
Co-authored-by: Beyond Better <git@beyondbetter.app>
Co-authored-by: vanderheijden86 <vanderheijden86@gmail.com>
Co-authored-by: Andreas Dellrud <andreas.dellrud@gmail.com>
Co-authored-by: michal.psencik <misa.psencik@gmail.com>
Co-authored-by: Rome-1 <romethorstenson@gmail.com>
The shared-server upgrade steps said an upgraded client keeps reading the
old schema and only has writes refused. In practice most reads fail as
well: bd list, bd show and bd ready stop with "table not found: leases"
because 1.3 reads expect tables the old schema lacks. Say so, and tell
operators to run the migration as soon as the clients are upgraded
rather than treating the window as merely degraded.
Refs #6929, #7038
The upgrade docs told every non-migrating clone to adopt the migrated
database with `bd bootstrap`, claiming it replaces the local database.
On a clone that already has one, bootstrap prints "Nothing to do." and
exits 0, leaving the clone on the old schema (#6687).
Document the flow that works: every clone backs up with the old binary,
other clones `bd dolt pull` on the old binary after the migrator pushes
and then upgrade; a clone that already upgraded moves its local database
aside, re-clones with `bd bootstrap`, and re-imports the backup. Align
the gate description, shared-server note, and init-safety summary.
Also add a post-migration step to run `bd recompute-blocked` once per
database, since migration 0059 can over-set is_blocked and silently hide
ready work (#7037).
Refs #6687, #7037
Makes the repo's agent and contributor surface describe developing beads, not using bd, and requires every PR to link a documented issue.
- Contributor-only root AGENTS.md with a routing table; cmd/bd/AGENTS.md and engdocs/AGENTS.md seam files; CLAUDE.md symlinks so Claude Code loads nested files.
- Bug and feature issue forms, a PR template that requires Closes #, CONTRIBUTING sections for the triage and pipeline labels, and the opt-in fork-cache during dev setup.
- ROADMAP.md for 1.4: versioned beads (#6132), Graph Preview 2 (#7170), contributor onboarding (#7228).
- docsync guards: root AGENTS.md at or under 20 KB; every AGENTS.md symlinked, routed, and with resolving links, paths, and guard-test names.
Agent-Signature: claude-code-claude-opus-5-5-high on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(gate): ordinary commands wait out maintenance, with writer fairness
Ordinary bd commands take the workspace (and physical-root) gate SHARED and
never waited for it, so while another process held it EXCLUSIVELY — bd init
(~8s), backup restore, migrate, bootstrap — they failed at once with "a
maintenance operation is running". In shared-server mode every project
shares one physical-root gate, so another project's bd init broke every bd
command on the machine for its duration.
Ordinary commands now wait:
- up to 15s by default; BEADS_GATE_WAIT_TIMEOUT (Go duration or bare
seconds, same convention as BEADS_INIT_GATE_TIMEOUT) overrides it, and 0
restores fail-fast;
- one "waiting for another bd process ..." notice after 2s (shared with bd
init's notice);
- Ctrl-C aborts the wait. A canceled wait used to fall through to the
shared fail-open path ("continuing ungated"); it is now a hard error;
- past the bound, the same error naming the holder, the wait, and the knob.
Git hooks stay fail-fast: `bd hooks run` and the bd export/import children
the hooks spawn run with BD_GIT_HOOK=1, treat failure as a warning, and must
not stall a commit or checkout for 15s.
Writer fairness (internal/workspacegate). flock/LockFileEx give no queueing,
and acquisition is non-blocking polling, so a steady stream of overlapping
shared holders could keep a waiting exclusive acquirer (bd init) out past
its bound. A per-gate intent lock (<gate>.intent) fixes that: a waiting
exclusive acquirer whose first try is busy takes the intent lock
exclusively while it polls, and waiting shared acquirers probe it before
every attempt and wait while it is held. The exclusive waiter then waits
only for in-flight holders to drain. The intent is an OS lock, so a crashed
waiter's intent dies with it; its advisory sidecar is ignored when the lock
is free, and intent-lock errors other than "busy" degrade to the old
behavior. Fail-fast acquisitions (Wait <= 0) ignore the queue entirely, so
hooks and BEADS_GATE_WAIT_TIMEOUT=0 behave exactly as before. The intent
lock is taken only while acquiring its gate, directly before it in
AcquireAll's sorted order, so it adds no lock-order cycles.
Nested bd (bd orphans running bd close, hooks fired by git that bd runs)
would deadlock against the queue: the child queues behind an exclusive
waiter that is waiting for the child's parent. A bd process holding its
gates shared exports BEADS_GATE_SHARED_HOLDER_PID; a child whose recorded
ancestor is alive skips the queue (it cannot help the waiter anyway).
Tests: workspacegate fairness (a continuous shared stream no longer starves
an exclusive waiter; verified to fail without the queue), intent lifecycle,
stale intent from a SIGKILLed process, cancellation while queued,
InheritedSharedHold. cmd/bd: holder released after ~3s lets a command
through with one notice; past-bound error text; fail-fast modes (0, hooks);
Ctrl-C is not fail-open; a new command queues behind a waiting bd init
while a child of a shared holder does not; env parsing.
TestSharedServerConcurrent runs a late bd init of a new project during the
client workloads, so both directions are exercised against a real server.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(gate): a queued exclusive waiter may delay shared commands, never fail them
Review follow-up (B1). A doomed exclusive waiter — bd init or restore
blocked behind a long-lived shared holder such as `bd list --watch`,
`bd events tail --follow`, an open `bd edit` editor, or a beads.OpenGated
embedder — held the writer-fairness intent lock for its whole budget, so
every NEW ordinary command deferred to it and failed with "queued for
exclusive access" even though nothing held the gate exclusively. Before
the fairness change those commands ran normally.
Two bounds fix it while keeping the fairness win:
- An exclusive waiter drops the intent lock after maxIntentHold (10s)
without getting the gate and keeps polling unqueued. In-flight ordinary
commands drain far faster than that.
- The final attempt of a waiting shared acquisition tries the gate even
while intent is held, so a shared acquisition fails only when the gate
itself is held exclusively.
With the final attempt ignoring intent, AcquireAll's 1ns floor for an
exhausted budget is dead code (a Wait-0 attempt behaves the same), so it is
back to 0. queuedDetail drops an intent sidecar left by a dead process (on
Windows its removal can fail while another process is reading it).
Tests: the doomed-waiter scenario (both bounds; each fails with its bound
removed), intent lock order across a two-gate set in both directions, an
exhausted AcquireAll budget, two exclusive waiters handing off the intent,
and BEADS_GATE_SHARED_HOLDER_PID inherited through a real subprocess.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(gate): 30s shared wait, 60s init wait, accurate errors, hook pinning
Review follow-ups for the shared gate wait (S1-S5 and nits), on top of the
workspacegate fix that keeps a queued exclusive waiter from failing
ordinary commands.
- Ordinary commands wait up to 30s by default (was 15s). Queued
maintenance operations run one after another (two inits fanned out
across shared-server projects hold the gate back to back, 10-15s each
under load) and a waiting command waits for all of them. Documented in
configuration.md and CHANGELOG, including BEADS_GATE_WAIT_TIMEOUT=0 for
scripts that relied on fail-fast.
- bd init waits up to 60s by default (was 30s). Safe only now that a
waiting init stops queueing others after 10s.
- Error text: a shared acquisition now fails only when the gate is held
exclusively, so "running" is accurate; in shared-server mode it says
"the shared server (possibly from another project)", and the detail
still names the holder when known.
- hooks.go: the hookSubprocessEnv / bd import comments listed BD_GIT_HOOK's
consumers without the gate wait, which now reads it to stay fail-fast.
TestHookSubprocessEnvKeepsGateFailFast pins that hook subprocesses carry
it and therefore never wait on the gate.
- bd edit's $EDITOR (which can outlive bd by hours) no longer inherits
BEADS_GATE_SHARED_HOLDER_PID.
- Test hygiene: the cmd/bd test binary never advertises the marker
(in-process command tests run beside tests that spawn bd) and clears any
inherited one in TestMain; the notice-delay test runs in 1s, not 3s.
- TestSharedServerConcurrent's late init keeps a 30s bound so the 60s
default cannot mask a fairness regression.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
In shared-server mode every project's physical root is the one shared dolt
data dir, and bd init holds that dir's gate EXCLUSIVELY for its whole run
(~8s). It waited only exclusiveGateWait (5s) for it, so two concurrent
`bd init --shared-server` runs in different projects, or an init during
another project's long command, failed with "bd init refuses to run over
live bd activity".
acquireInitMutationGate now uses its own acquisition options:
- Wait: 30s by default, overridable with BEADS_INIT_GATE_TIMEOUT (Go
duration or bare seconds, same convention as BEADS_PRIME_TIMEOUT and
BEADS_FSCK_TIMEOUT); ctx cancellation still aborts the wait.
- One stderr notice ("waiting for another bd process on the shared
server (...)...") once the wait passes 2s, instead of immediately.
- Past the bound, the same refusal, now naming the budget and the knob.
Exclusivity is unchanged. The 5s exclusiveGateWait is also used by
backup restore, bootstrap, migrate and the backup lock; those keep it, so
the change is scoped to init via acquireExclusiveWorkspaceGatesWithOptions.
TestSharedServerConcurrent goes back to fully concurrent inits (manual runs
with many dirs raise BEADS_INIT_GATE_TIMEOUT to match). New unit tests: a
holder released after 6s lets init through with one notice; a holder past
the bound gives the clear ErrBusy error; cancellation; env parsing.
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The PAUSED warning, the `bd backup status` PAUSED line, CHANGELOG and
configuration.md told operators to switch to a fresh destination with
`bd backup init <new-path>`. That never ends the pause: backupDir()
reads only backup.git-repo, while `bd backup init` registers the
separate destination that manual `bd backup sync` pushes to, so
auto-backup keeps targeting the over-cap directory and stays paused.
Name the two levers that do end it: raise backup.size-cap-mb, or point
backup.git-repo at a different git repository. Also correct the
backup.git-repo row in configuration.md, which called it a repo URL
although backupDir() requires a local path containing .git (anything
else falls back to .beads/backup/), so the new advice is actionable.
TestPauseAutoBackupForSizeCap_RemediationAdvice and the status PAUSED
line now require backup.git-repo and reject `bd backup init`.
TestMaybeAutoBackup_RemediationLevers runs all three for real: raising
the cap and switching backup.git-repo each resume a sync, while
`bd backup init` leaves auto-backup paused.
Post-merge review follow-up to #6071.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(init): name --recreate-missing in the refusal without a paste-ready command
The missing-server-database refusal added in #5791 ended with a complete
`bd init --recreate-missing --prefix <prefix>` line. ADR 0002 Invariant 4
keeps complete destructive invocations out of bd error output, and this
refusal also fires when the server merely could not be reached: a stopped
server, a wrong port and a wrong data dir all look the same from here, and
recreating in any of them strands the real data behind an empty database of
the same name. The line also echoed the raw --prefix flag value, so a run
without --prefix printed `--prefix ` with nothing after it.
The refusal now names the flag and points to `bd help init-safety`, which
keeps the full invocation behind the diagnosis it requires. The unused
prefix parameter stays as `_` so the guard call sites are unchanged.
Also:
- --force / --reinit-local flag help, `bd help init-safety` and the init
guard comment now say neither flag authorizes recreating a missing
server-mode database; the --recreate-missing stanza says to rule out a
stopped server or wrong port/data dir and restore first.
- bootstrap.go comments no longer describe #5791 as open and unmerged.
- TestInitGuardMissingServerDBMessage_RefusalTextNoEcho pins the wording
for both evidence arms, with and without a prefix.
- TestInitGuard_RecreateMissingE2ECreatesMissingServerDB runs the real
binary against a live server lacking the database: refused without the
flag, created with it. The unit tests flip initAllowRecreateMissing
directly, so nothing exercised the documented command end to end.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(recovery): init-missing-server-db covers both evidence arms and the flag limits
The init-missing-server-db section described only the project_id arm of the
guard. Under --reinit-local or --force a workspace that predates project_id
is also refused when its local Dolt data directory survives, and the refusal
then cites that directory instead of metadata.json. "What happened" now
covers both arms.
"Limits worth knowing" replaces the stale "fails open" bullet with a table
of which local state meets the refusal under bd init and under
--reinit-local / --force, and what --recreate-missing changes. The
init-force-refused section now says --force / --reinit-local bypass only the
local data-safety guard, not this refusal or the remote one, and step 3 says
why the refusal names --recreate-missing without printing the command
(ADR 0002 Invariant 4).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(adr): mark ADR 0004 Accepted now that #5791 has landed
ADR 0004 (the missing-database guard signal) still read "Proposed" after the
guards implementing it merged in #5791, and its Consequences said
checkExistingBeadsDataAt "does not change" although the same PR gave it the
Tier 1 probe ahead of project_id. Record the acceptance and say what the PR
already changed; DOC_INVENTORY.md follows the status.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* Refuse reserved words and fuzzy id matches on bd comment writes
bd comment <id> [text...] treated its first argument as an id via the
same abbreviation-tolerant resolver used everywhere else, with no
protection against the id slot holding something that was never meant
to be an id. Two related failure modes came from that:
- "bd comment list <id>", a typo for "bd comments list" (or "bd
comments <id>"), silently ran with id="list" and text="<id>" instead
of erroring.
- If "list" (or any other stray first word) happened to be a
leading-prefix abbreviation of some unrelated issue's hash, the
resolver picked that issue and the comment landed there instead of
failing with "not found". This is exactly what happened in
production: 15+ automated sessions made the "bd comment list <id>"
typo over two days, and because "list" was a leading-prefix
abbreviation of an unrelated wisp's hash ("list3t0"), every one of
them wrote a garbage comment onto that wisp.
Fixes both, independently:
- checkCommentIDNotReservedWord rejects list/add/rm/delete as the id
argument before any resolution is attempted, mirroring the existing
"bd comments list" misplaced-subcommand guard.
- ResolvePartialIDExact (internal/utils) is an exact-match sibling of
ResolvePartialID: identical exact-ID and exact-hash matching
(including a wisp's hash with its "wisp-" infix stripped), but never
falls through to leading-prefix abbreviation matching. bd comment
now resolves through this via a new resolveAndGetIssueForMutationExact,
which keeps the existing cross-rig prefix-routing and contributor
auto-routing fallbacks intact (tightened to exact matching too) so
cross-repo comment writes by full id are unaffected.
Every other caller of the touched shared functions (ResolvePartialID,
resolveAndGetIssueForMutation, resolveViaPrefixRoutingWithAccess,
resolveViaAutoRouting) keeps its exact current behavior — the new exact
variants are additive, and existing call sites were updated to pass an
explicit "false" for the new parameter rather than changing behavior.
Testing: go build/go vet pass across the whole module. The new pure-Go
guard test and a hand-rolled in-memory PartialIDResolverStore test both
run and pass without Docker or a live Dolt server, and the latter
reproduces the original collision (ResolvePartialID) before asserting
the fix (ResolvePartialIDExact) in the same test, so the fixture is
proven to exercise the real failure mode rather than trivially passing.
The Dolt-container-backed table tests (mirroring the existing
TestResolvePartialID_Wisp / TestResolvePartialID suites) could not be
run locally (no Docker in this environment) — they compile and skip
cleanly the same way the pre-existing suite does, and will run for real
in CI.
* fix(ga-wpdum): address steveyegge's PR #5393 review items b/c/d
Review (2026-08-07, posted as a PR comment, not a formal GitHub review —
hence reviewDecision stayed empty) asked for four things before merge; (a)
rebase onto #5369 was already done (2026-09-07, see PR history). This
addresses the rest:
(c) MAJOR — comment writes require an exact id, but a REAL abbreviated id
was refused with "no issue found matching %q", which is false: the issue
exists, only the abbreviation was rejected. ResolvePartialIDExact now
distinguishes the two failure modes via a new sentinel,
ErrAbbreviatedIDNotAllowed, wrapped only when the input would have resolved
via leading-prefix abbreviation. bd comment's RunE checks errors.Is against
it and returns a truthful, actionable message pointing at `bd show <id>`
instead of claiming the issue is missing. Docs (hash-ids.md) and CHANGELOG
updated with the read/write carve-out this creates.
(b) MAJOR — investigated whether the proxied-server comment path needed the
same exact-match treatment. It doesn't: resolveCommentTargetProxied resolves
via workapi.GetIssueOrWisp with the raw id, which bottoms out in
issueSQLRepositoryImpl.Get's plain "WHERE id = ?" — SQL exact equality, with
no abbreviation-matching layer anywhere in that call chain (unlike the
embedded path's utils.ResolvePartialID). Comment writes over the proxied
server were already exact-id-only before this PR. Per the review's own
fallback ("extend exact matching to that path, or document/test the gap
explicitly"), added a regression test locking this in rather than leaving it
implicit.
(d) Added CLI-level (cobra-dispatch, in-process rootCmd.Execute) tests for:
- "rm"/"delete" reserved-word rejection, the two words the #5369-inherited
tests don't cover (only "list"/"add" have hand-written cases).
- The new (c) abbreviation-refusal message end-to-end, including a
same-abbreviation sanity check against `bd show` to prove it's a real,
resolvable abbreviation and not a fixture accident.
Plus a Docker-free fake-store test in internal/utils pinning
ErrAbbreviatedIDNotAllowed's distinguishability from a genuine not-found.
Fixed in the same pass, same class of defect as (c): checkCommentIDNotReservedWord's
message claimed every reserved word is a "misplaced bd comments subcommand" —
true for "list"/"add", false for "rm"/"delete" (no such subcommand exists;
bd has "delete" as a top-level command and "rm" as an alias elsewhere, e.g.
"dep rm"). Message now says "reserved word" generically, true for all four.
Testing: go vet (plain and -tags=integration) clean on cmd/bd and
internal/utils. go test ./internal/utils/... passes including the new
ErrAbbreviatedIDNotAllowed test. go test ./cmd/bd/. (non-integration tag)
passes including both reserved-word cases. The new CLI-level and
proxied-server integration tests need a Dolt test container (Docker) this
environment doesn't have — same limitation the original commit's own
Dolt-backed tests already disclosed; they compile clean under
-tags=integration and skip cleanly the same way the pre-existing suite does.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(ga-wpdum): address bee-ghosttrack's R1 review (M1 + the flagged MINOR)
R1 (aec6de4ad, REQUEST-CHANGES) found that CHANGELOG.md and hash-ids.md
claim `bd comments add` is guarded against abbreviated ids and reserved
words exactly like `bd comment`, but the code never extended the guard
to the plural form — `commentsAddCmd` had no Args validator and resolved
through the abbreviation-tolerant `resolveAndGetIssueForMutation`. Per
the reviewer's preferred fix (option ii), extend the guard instead of
softening the docs:
- Add `validateCommentsAddArgs` (mirrors `comment`'s `validateCommentArgs`
minus the singular/plural-confusion special cases) and wire it as
`commentsAddCmd.Args`, so a reserved-word id is refused before either
dispatch branch.
- Switch the embedded-path resolution from `resolveAndGetIssueForMutation`
to `resolveAndGetIssueForMutationExact`, with the same
`errors.Is(ErrAbbreviatedIDNotAllowed)` truthful-message mapping
`comment` already has. (The proxied path already resolved exactly —
it shares `addCommentProxied`/`resolveCommentTargetProxied` with
`comment` — so this closes the embedded-path gap only.)
- Update the one pre-existing test that asserted the old, now-removed
behavior (`PartialIDWithCommentsAdd` expected a genuine abbreviation to
succeed) to assert the refusal instead, and add a CLI-level regression
test mirroring `TestCLI_CommentAbbreviatedIDRejectedWithTruthfulMessage`.
- Add `TestValidateCommentsAddArgs`, a pure Args-validator unit test
(no store/Docker needed) mirroring `TestValidateCommentArgs`.
Also treats the one MINOR the review flagged as an actual gap (not just
a suggestion): the wisp-branch abbrevOnly tracking in id_parser.go had no
test pinning it — P3 (making the wisp-branch abbrevOnly append a no-op)
went uncaught. Strengthened
TestResolvePartialIDExact_FakeStore_ReproducesReportedIncident's "list"
assertion from a bare `err != nil` to `errors.Is(err,
ErrAbbreviatedIDNotAllowed)`, which is exactly the incident's own shape
in the wisp branch.
CI (PR Core / wrapper timing) is failing on this branch, but independently
confirmed pre-existing and unrelated: `ci-pr-core.sh` runs `go test -race
./...` with no `-timeout` override, so cmd/bd (a large package under
-race) hits Go's default 10-minute per-package ceiling; same-hour green
runs on other PRs measured 11-13.5 min total job time, already at the
edge, and the actively-running test at the deadline
(TestWhereCommand_ReadsPrefixFromEmbeddedStore) is unrelated to this
diff. R1 independently measured the same thing (541.6s/387.0s on other
green runs vs. 600.9s here). Needs a green re-run, not a code fix.
Verified locally (no Docker in this environment, so the two integration-
tagged CLI tests above compile-check clean via `go vet -tags=integration,
gms_pure_go` but run as SKIP rather than PASS; will run for real in CI):
- go build ./...; go vet ./cmd/bd/ ./internal/utils/: clean
- go vet -tags=integration,gms_pure_go ./cmd/bd/: clean
- gofmt -l on all 4 changed/added files: clean
- go test ./internal/utils/... -run ResolvePartialID: PASS
- go test ./cmd/bd/. -run 'TestValidateCommentsAddArgs|TestValidateCommentArgs|TestCheckCommentIDNotReservedWord': PASS
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(ga-wpdum): address bee-ghosttrack's R2 review (dead-red fixture + cobra-dispatch wiring test)
R2 (a639234a0, CHANGES_REQUESTED): TestCLI_CommentsAddShortID/PartialIDWithCommentsAdd
was dead-red in its own setup — it only truncated the fixture hash to a
4-char abbreviation when len(hash) > 4, but fresh test DBs mint 3-char
hashes (min_hash_length unset), so shortID always equaled the full hash
and the t.Fatalf guard fired before any of the subtest's real assertions
ran. That meant mutation P-B (reverting comments.go's exact resolver back
to the abbreviation-tolerant one) went uncaught.
Fix: derive the abbreviation as a strict, one-character-shorter leading
prefix of the real hash (hash[:len(hash)-1]), the same derivation
comment_proxied_integration_test.go already uses — correct regardless of
fixture hash length, with a length>=2 guard instead of the old
always-true-in-practice one.
Also closes R2's recommended "NEW MINOR — the guard's wiring is
untested": comments_add_test.go drives validateCommentsAddArgs directly
(catches a gutted body, mutation P-C) but nothing exercised
commentsAddCmd's Args field through real cobra dispatch, so unwiring it
back to cobra.MinimumNArgs(1) left every test green (mutation P-D). Added
TestCLI_CommentsAddReservedWordRejectedThroughCobraDispatch, which runs
`bd comments add <reserved-word> ...` through actual rootCmd.Execute()
dispatch for all four reserved words and asserts the bystander issue
receives no comment.
Not touched, per R2: the carried-over m1 (cross-rig abbreviation error
message) — reviewer marked "Not a blocker" — and the CI race-default
timeout on cmd/bd, already diagnosed (R2 + prior PR comment) as
pre-existing infra flakiness needing a fresh run, not a code change.
Verified in this environment (no Docker/testcontainers available, same
disclosed limitation as prior rounds): gofmt clean; go vet -tags=integration
./cmd/bd/... clean (requires CGO_CPPFLAGS/CGO_LDFLAGS/PKG_CONFIG_PATH
pointed at the keg-only icu4c@78 install); go test -tags=integration
-run 'TestCLI_CommentsAddShortID|TestCLI_CommentsAddReservedWordRejectedThroughCobraDispatch'
./cmd/bd/ -v passes with all Dolt-backed subtests skipping cleanly
(Docker not available) rather than panicking — confirms both tests compile
and execute up to the container-availability skip. The actual fixture-hash
logic under test only runs where a Dolt container exists (CI); it has not
been exercised against a real container here.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* chore(bazel): enumerate the PR's 4 new test files in BUILD.bazel (adopt-pr rebase gate)
Base added cmd/bd/BUILD.bazel and internal/utils/BUILD.bazel enumerates
go_test srcs explicitly, so PR #5393's four new test files were unlisted.
Output of 'make bazel-sync' (gazelle + go_srcs.py + mod tidy), verbatim and
idempotent. Measured: the unrepaired //internal/utils:utils_test binary lists
0 of the PR's 5 TestResolvePartialIDExact* tests while still building green
(a fake green); repaired it lists 5/5.
* fix(review): surface a routed-tier abbreviation refusal on comment writes
Review-loop fixup for PR #5393 (iteration 1). The review approved with no
required changes; these are the non-gating minor plus one of the two nits,
taken because the minor is a user-visible false message on this PR's own
headline contract.
[minor] Contract & Interface Fidelity. resolveAndGetIssueForMutationExact
passes exact=true to all three tiers, so the cross-rig and auto-routed tiers
can mint utils.ErrAbbreviatedIDNotAllowed too -- and both wrappers propagate it
unwrapped (routed.go:303-305) -- but each routed error was bound inside an `if`
statement and discarded, and `return nil, err` returned the LOCAL error. The
consumers' errors.Is (comment.go:158, comments.go:238) was therefore
structurally unable to observe a routed-tier refusal, so `bd comment hr-8wn
"text"` printed `no issue found matching "hr-8wn"` for an issue a routed rig
demonstrably holds -- the exact falsehood the sentinel's own doc condemns, at
the caller that doc names (internal/utils/id_parser.go:33). Both tiers' errors
are now captured and the first abbreviation refusal is returned in preference to
the local not-found. The wrong write was already refused on every tier; only
the message contract was unmet.
The new pin cmd/bd/comment_routed_exact_test.go drives the real seam (local
town store + routed rig + routes.jsonl, mirroring
TestCheckBeadGateCrossRigPrefixRoute) in both directions, because either
assertion alone passes for the wrong reason: an abbreviation of a routed issue
must select the ROUTED refusal, and an id absent everywhere must stay a plain
not-found. Proven non-vacuous by mutation -- dropping only the selection reds
direction 1 with `no issue found matching "gt-abcdefg"`, the original symptom
verbatim, while direction 2 still passes.
[nit] Test Evidence Quality. The proxied regression test asserted only
strings.Contains(stdout+stderr, id), which passes identically on the false and
the truthful message and so locked the local/proxied message asymmetry in where
the suite could not see it. It now asserts the whole message (verified
empirically: `Error: issue pa-2u not found`) and empty stdout, matching the
exact-message norm of the sibling missing-ID subtest. The asymmetry itself is
deliberate and stays: the proxied route resolves through one exact
`WHERE id = ?` and cannot distinguish an abbreviation of a real issue from an
absent id without adding back the abbreviation probing this PR exists to remove
from write paths.
[nit] Release Safety -- DECLINED, measured. The prescribed `### Changed` bullet
belongs at the top of the first `### Changed` block in `## [Unreleased]` (base
CHANGELOG.md:383), and main has since inserted its own bullet at exactly that
anchor (`@@ -384,0 +492,16`, the #6111 entry). Adding it would mint a second
CHANGELOG add/add conflict for the finalize base-refresh on top of the
`### Fixed` re-conflict already predicted by the rebase gate -- not worth it for
an optional nit whose own text says "No code change".
cmd/bd/BUILD.bazel gains one srcs row for the new test file (via make
bazel-sync, a no-op on a second run) so bazel.yml's "BUILD files in sync" gate
stays clean.
Validation: go build ./... rc 0; go vet ./cmd/bd/ ./internal/utils/ rc 0; gofmt
clean; git diff --check clean; cmd/bd selectors 11/11 PASS including base's own
TestMatchPrefixRoute (the GH#5048 longest-prefix union guard) and
TestResolveCloseTargets (the abbreviation-tolerant sibling path);
TestProxiedServerComment 3/3 under BEADS_TEST_PROXIED_SERVER=1.
* test(utils): pin #6215's sentinel guard to the shared resolver (#5393 base refresh)
Rebasing this PR onto current main (e7138e93af -> a1ac9f4dcb, 27 commits) hit
two conflicts. Both are recorded in .gc/reviews/<root>/base-refresh-repair.md;
this commit carries the one piece of the repair that is not simply a replayed
contributor hunk.
The substantive conflict was internal/utils/id_parser.go against ab88b20517
(#6215, "refuse a bare jq/JS sentinel ... as an issue ID", which itself says
Refs #5393). Both sides ADD at the same point -- the diff3 ancestor section is
empty -- so nothing base-owned is rewritten, and the only question is WHERE
#6215's guard lands now that this PR splits the resolver into ResolvePartialID
(abbreviation-tolerant) and ResolvePartialIDExact (exact-only) over a shared
resolvePartialID.
It belongs in the shared body. #6215 put it in ResolvePartialID only because
that was then the repository's single ID-resolution entry point ("One guard
covers the direct, embedded and proxied-server paths uniformly"); this PR adds
a second. Its changelog entry on main states the guarantee directly -- "bd
update null, bd comment null and every other command that resolves an ID now
fail before any lookup, because the guard sits in the shared resolver" -- and
bd comment is precisely what this PR routes through the exact-only path. The
relocation costs no patch delta: the guard re-anchors as unchanged context
after the PR's insertion, so the content-line diff of (old base..old head) vs
(new base..new head) is empty, and the PR's stat is 16 files +1212/-31 before
and after.
Nothing covered that choice, which is why this test exists. #6215's own
id_parser_sentinel_test.go exercises only ResolvePartialID, so the naive
textual resolution -- guard left in the exported wrapper -- keeps every one of
its assertions green while a sentinel reaching the exact path degrades into
`id is a valid abbreviation, but exact-match resolution is required here:
"null" (matches [hq-null3t0])`: it names an unrelated decoy issue and tells
the caller to use the full id, when in truth their selector matched nothing.
Mutation-proved in both directions: with the guard moved into the wrapper
alone, #6215's two tests still PASS and this test FAILs; with the guard deleted
outright, #6215's refusal test and this one both FAIL (so neither is vacuous).
The over-refusal arm mirrors #6215's accepted-inputs test through the exact
path, so hq-null3t0 and the bare hash null3t0 must still resolve.
No new file, so no BUILD.bazel srcs row is owed. 61 PASS / 0 FAIL / 0 SKIP for
-run 'Sentinel|ResolvePartialID' against a real Dolt container.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
* docs: add beadcyte to community tools (Web UIs)
Local web app that draws bead history and a projected future: a
historical-median estimator, a greedy WIP-cap scheduler, and an
eight-signal triage score, each with its own uncertainty. Reads and
writes only through the bd CLI.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs: correct beadcyte storage-access claim and normalize emphasis
The beadcyte entry said the tool "reads and writes exclusively through
the `bd` CLI ... never the Dolt files or `.beads/issues.jsonl`". The
first half is false for the shipped package. Measured against
beadcyte@0.9.0, the latest published version (tarball sha1
93964d9632cc1b1cc846f5d84f0dfa8a79a4ef57, matching the registry
shasum):
- The package starts exactly one process that is not `bd`:
`spawn("dolt", ["sql", "-r", "json", "-q", sql], ...)` with cwd
<project>/.beads/embeddeddolt (src/history-sql.mjs:250,
`doltSqlRunner`).
- `beadcyte freeze` reaches it through `readDoltDates`
(src/freeze-cli.mjs:110). `freeze` is a dispatched subcommand
(bin/beadcyte.mjs:37, 63-65). The path is on by default:
freeze-cli.mjs:33 sets `dolt: true`, and `--no-dolt` (:38) turns
it off.
- The author's own comment agrees: "`beadcyte freeze` is the ONE
place beadcyte reads Dolt directly ... read-only"
(src/history-sql.mjs:42-44).
Correcting an over-broad claim can easily introduce a new one, so each
clause of the replacement was checked:
- "reads and writes through the `bd` CLI": every other process the
package starts is `bd`. Writes go through `bd update`, including
freeze's own write-back (freeze-cli.mjs:127), and through
`bd dolt pull`/`push` (src/serve.mjs:498, 509).
- "read-only": `QUERIES` (history-sql.mjs:115-124) holds 4
statements, all SELECT. Every SQL call site passes one of them
(history-sql.mjs:302-303, 467-470).
- "never `.beads/issues.jsonl`": the package contains zero `jsonl`
references, so the entry still meets the page's compatibility bar
(docs/community-tools.md:8-11).
Emphasis: 51 of the page's 52 entries carry exactly one bold span, the
linked name. beadcyte carried three. Removing the bold from "happened"
and "expects to happen" brings it to 52/52.
Length: the correction adds 74 characters, bringing the entry to 1073.
That is still the longest of the 7 Web UIs entries, and 3rd on the
page after Beadazzle (1579) and Beads Dashboard (1300). Review
suggested trimming it to a feature summary. That suggestion is
optional and does not gate the review, and how the product is
described is the contributor's call, so this commit does not make it.
Gates: git diff --cached --check is clean. check-doc-flags.sh returns
rc=0 against the pinned v1.2.2 bd. check-doc-freshness.sh reports 68
PASS / 0 FAIL. go test ./test/docsync passes 8/8.
go test -tags integration -run TestDocFreshness ./scripts gives
37 pass / 0 fail / 1 skip.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local>
* fix(bd): cap auto-backup destination size to stop unbounded growth (ga-y6gjv)
ga-y6gjv asked for 4 fixes to bd's auto-backup subsystem. Three are already
merged and deployed (verified via git merge-base --is-ancestor against the
commit that built the currently-deployed ~/.local/bin/bd):
- interval throttle persists on failure too, per-workspace: 5f685959c
- default-off in sql-server/shared mode: 5f685959c, refined by 8b9429153
- `bd config get backup.enabled` reports the effective value: 5f685959c
This commit is only the fourth, still-open item: "prune/cap backup
archives." BackupSync/CALL DOLT_BACKUP('sync', ...) only ever transfers new
chunks into the destination — it never prunes ones that became unreachable
on the source DB (history rewrites, superseded data) — so even with the
interval fix slowing the frequency of syncs, the destination can still only
grow, never shrink. This was the actual disk-filling mechanism in the
2026-06-19 outage (43GB backup dir from a 1.7GB store).
I first tried wiring `dolt gc` into the post-sync path (mirroring
runCompactDolt's exec.Command("dolt", "gc", ...) pattern in compact.go).
That does not work: a backup destination is a bare Dolt chunk-store
directory with no .dolt repo-root marker, so the standalone dolt CLI can't
open it ("not a valid dolt repository") no matter what its working
directory is set to, and dolt_backup.go's SQL procedures only expose
add/sync/restore — never gc — for a backup destination. Confirmed this
empirically (a real dolt gc attempt against a real backup dir, outside any
test) before shipping anything, not just reasoned about it.
Given no supported way to prune a backup destination in place, this adds a
hard size cap instead: once the destination exceeds backup.size-cap-mb
(default 2048MB), maybeAutoBackup skips the sync attempt entirely rather
than letting it grow further, and prints a throttled warning
(backup.size-warn-interval, default 24h) telling the operator to free space
or raise the cap. This directly bounds the failure mode that caused the
outage — unbounded growth — without risking any operation against the
backup store's on-disk format.
Tests (cmd/bd/backup_cap_test.go): threshold check against a real
directory, warning-throttle persistence (mirrors the existing throttle
persisted on backup failure, backup_export.go), and end-to-end proof that
maybeAutoBackup never attempts BackupDatabase once capped. Confirmed each
new test fails against the pre-fix code (wiring temporarily reverted,
re-verified, restored) before treating it as green.
Verified: go build ./... clean, gofmt clean, go vet clean, full
cmd/bd + internal/config test run green (backup/config-focused subset run
with -v; no regressions in the wider package test runs either).
* fix(bd): address PR #6071 review feedback on backup size-cap (ga-y6gjv)
bee-ghosttrack's 2026-09-03 review of the size-cap fix (3d27d7a98) requested
changes before merge -- 4 major, 2 minor, all about the pause being
invisible rather than the cap mechanism itself. This addresses all six.
Major:
1. backup.size-cap-mb: 0 now means "no cap", not "use the 2048MB default."
effectiveSizeCapMB() centralizes the <=0-is-disabled interpretation;
backupSizeCapExceeded and the new status helpers all go through it.
Viper already registers a 2048 default for this key
(internal/config/config.go), so GetInt only returns <=0 when the
operator explicitly set 0 (or an unparseable value) -- the old code's
own `if capMB <= 0 { capMB = 2048 }` was silently overriding that
explicit choice, leaving no off switch for a legitimately larger
destination.
2. `bd backup status` (and --json) now report a `size_cap` object
(enabled, cap_mb, current_bytes, exceeded), and the human-text Config:
line grows a "Size cap: PAUSED (cap exceeded) -- X / Y..." line when
paused. Previously the pause was stderr-only and throttled to 24h, so
an agent/CI caller on --json or --quiet had no way to see that
auto-backup had silently and permanently stopped syncing.
3. The remediation message no longer says "delete the backup directory."
Nothing in this codebase demonstrates a deleted destination is cleanly
recreated by the next sync (the server-side Dolt backup remote stays
registered against that path), and following the old advice would
leave a zero-backup window while the next sync is itself
interval-throttled. It now points at backup.size-cap-mb / `bd backup
init <new-path>`.
4. docs/reference/configuration.md gains rows for both new keys plus an
expanded Auto-backup section (the cap mechanism, the pause, manual
backup staying uncapped, bd backup status reporting the pause);
CHANGELOG.md gets an [Unreleased]/Fixed entry referencing #6071.
Minor:
5. maybeWarnBackupSizeCap's throttle timestamp is now also cached in an
in-process map (capWarnFallback, keyed by dir) alongside the persisted
backup_state.json. The persist write targets the directory the cap
just declared full, so in the disk-full case this cap exists for, that
write fails and the timestamp never sticks -- a long-lived bd process
that keeps calling maybeAutoBackup for the same destination (e.g.
internal/storage/dbproxy's server mode) would otherwise re-warn on
every single call. The map is keyed by dir specifically so unrelated
destinations -- and unrelated tests -- never share a throttle.
6. The size-cap directory walk (getDirSize's filepath.Walk) now runs
after the interval throttle in maybeAutoBackup, not before. The
reviewer measured 65-100ms per bd invocation at 20k files in the
backup dir when the walk ran unconditionally on every command; moving
it below the throttle makes it free on the common (throttled) path and
only pays the walk cost once per interval, exactly when a sync attempt
would occur anyway.
Also noted by the reviewer: manual `bd backup` / `bd backup sync` stay
uncapped -- now documented in configuration.md.
Tests (cmd/bd/backup_cap_test.go, cmd/bd/backup_status_test.go): one new
test per review point. Each was confirmed to fail against the pre-fix code
for the expected reason before implementing -- including catching a
vacuous pass in my own first draft of the "disabled cap" JSON assertion
(zero-value Enabled:false matched whether the size_cap key existed at all
or not; fixed to assert key presence first). The disabled-cap test uses a
sparse file (Truncate, not a real write) to cross the legacy 2048MB
threshold without allocating 2GB of real disk or memory. The reordering
test is detected indirectly: if the cap check ran despite the throttle, it
would persist LastCapWarnAt; the interval-fresh case proves it does not.
Verified: go build ./cmd/bd/... clean, gofmt clean, go vet ./cmd/bd/...
clean, golangci-lint run ./cmd/bd/... -> 0 issues, targeted backup/status
test subset green (20/20, including every pre-existing backup test -- no
regressions).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(bazel): add backup_cap sources to //cmd/bd srcs lists
The contributor branched before `cmd/bd/BUILD.bazel` existed, so the two
files this PR adds were never enumerated there. After rebasing onto a base
that hand-maintains explicit srcs lists, `//cmd/bd:bd_lib` omits
`backup_cap.go` while still compiling `backup.go` and `backup_auto.go`,
which reference four symbols it defines:
backup.go:93 undefined: showSizeCapStatusJSON
backup.go:141 undefined: showSizeCapStatus
backup_auto.go:200 undefined: backupSizeCapExceeded
backup_auto.go:203 undefined: maybeWarnBackupSizeCap
`backup_cap_test.go` was likewise absent from `//cmd/bd:bd_test`, leaving
seven of the PR's nine new tests unreachable under Bazel.
`make bazel-sync-check` does not catch this: `tools/bazel/go_srcs.py --check`
only validates the `go_srcs` filegroup globs, not the `go_library`/`go_test`
srcs enumerations.
Four unrelated test files (config_leaked_secret_test.go, init_role_*_test.go,
init_git_bootstrap_routing_test.go) are also unlisted, but they are unlisted
on the base too, so they are left alone as pre-existing.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(backup): stop the size-cap walk from running on every bd command (#6071 review)
Maintainer review fixup for PR #6071 (ga-y6gjv), iterations 1 and 2.
The gating finding, filed independently by both review lanes and confirmed
empirically: the fixup that moved the getDirSize walk behind the interval
throttle does not deliver its claimed property, because state.Timestamp —
the only thing that re-arms that throttle — is written in exactly two
places, both inside runBackupExport. The two steady states that skip
before reaching it therefore pass the throttle on every single bd
invocation and pay the full filepath.Walk forever:
IDLE no new Dolt commit; the walk runs, then change detection skips
and writes nothing.
PAUSED cap exceeded; the walk has already happened by the time
maybeWarnBackupSizeCap persists LastCapWarnAt, which is the only
field it wrote.
PAUSED is the pathological case: an over-cap destination is by definition
the largest one, so the feature's terminal state was its most expensive,
persisting until an operator intervened. This landed on read-only
commands too, i.e. the 65-100ms/command agent-polling regression the walk
was moved to avoid.
Both halves of the documented remedy:
- Move the cap check after change detection, the order
docs/reference/configuration.md already describes ("If data changed and
the throttle interval has passed, bd checks the destination
directory's on-disk size"). This makes that sentence true and closes
the docs finding with no docs edit.
- Re-arm the interval throttle (state.Timestamp) on the cap-exceeded
skip, leaving LastDoltCommit untouched exactly as runBackupExport's own
failure path does, so change detection still sees pending work once the
cap is raised.
Neither half suffices alone: the reorder still walks every command in a
PAUSED workspace where data IS changing, and the persist alone still walks
forever when IDLE. Persisting on the idle skip instead would add up to one
backup.interval of backup latency, which this pairing avoids.
Also from the same review, all non-gating:
- The cap-check error path failed open behind a debug-only line, so one
unreadable entry could silently restore unbounded growth while
`bd backup status --json` reported the very same error. It now warns on
stderr, throttled by the backup interval and deliberately not by the
LastCapWarnAt slot: spending that slot here would suppress the more
important PAUSED notice for a full warn interval.
- The warn timestamp is now recorded only when the message was actually
printed, so --json/--quiet agent calls stop consuming the 24h slot
silently.
- Dropped capWarnFallback (map, mutex, two accessors). No reachable
production path can read it: both call sites are in PersistentPostRunE,
which runs once per CLI process, and the proxy child installs an empty
PersistentPostRun. Its pinning test is repurposed to the contract that
is real — a persist failure must not block the already-decided skip.
- Registered backup.size-cap-mb / backup.size-warn-interval in
YamlOnlyKeys, so the backup block is a complete inventory again.
Functionally inert: the map has no enumerator and its one predicate
consumer already matches on the "backup." prefix.
- `bd backup status` prints "Size cap: unavailable (<err>)" instead of
dropping the line, and the JSON error object carries an explicit null
`exceeded` so a consumer cannot read a missing key as "not exceeded".
The CHANGELOG's cost claim is corrected to match the shipped order; it
described the throttle as sufficient, which is the defect above.
Iteration 2, all non-gating (that review approved):
- The walk-error path re-arms the interval throttle itself before
proceeding uncapped. Iteration 1 relied on the fall-through into
runBackupExport to bound that warning to once per backup.interval,
but not every runBackupExport exit persists state.Timestamp: a failed
post-sync GetCurrentCommit returns without saving state, so the walk,
the warning and the sync itself repeated on every command. The doc
comment now states the bound the code has: once per interval whenever
backup_state.json can be written.
- `bd backup status` echoes the configured backup.size-cap-mb when the
cap is disabled instead of a literal 0. viper's GetInt also resolves
an unparseable value ("2048MB") to 0, so the line asserted a value the
operator never wrote.
- The status readers count only a destination that does not exist yet
as empty. getDirSize aborts on the first per-entry error, so a chunk
file removed mid-walk read as 0 bytes, i.e. `"exceeded": false` for a
destination that may be over its cap. It is now reported as
unavailable, like any other walk error.
- docs/reference/configuration.md no longer says `--json` reports the
string `PAUSED (cap exceeded)`; it reports `size_cap.exceeded: true`.
- TestMaybeAutoBackup_CapCheckSkippedWhenThrottled seeded the same commit
as its watermark, so after iteration 1's reorder change detection
alone stopped the walk: it passed with the interval throttle deleted,
and so did every other Backup/Throttle/Auto test in cmd/bd. It now
seeds a changed commit, and its comment names the renamed
pauseAutoBackupForSizeCap.
Tests: iteration 1's four new/updated pins are each mutation-proved.
Dropping the throttle re-arm reds the three throttle pins and leaves the
idle pin green; restoring the original ordering reds only the idle pin;
reverting both reds all four. Iteration 2's three new pins each go red
under their own mutation only: dropping the walk-error re-arm, restoring
the literal `=0`, and swallowing a walk ENOENT (dropping the root stat
reds the missing-destination case instead). Disabling the interval
throttle now reds the throttle test.
Base refresh before approval (rebased onto main 3f9561db2b, which had
made the PR CONFLICTING):
- main 8269a88cbf (#6327) moved compact onto storeSizeBytes and
deleted getDirSize from compact.go, leaving backup_cap.go its only
caller, so the merged tree failed to build (undefined: getDirSize)
although only CHANGELOG.md and backup_auto.go conflicted textually.
getDirSize is restored verbatim in backup_cap.go (plus the
path/filepath import), and the two comments that described it as
shared with, or exercised by, compact.go are corrected.
- main 4e4ebdb443 (#6879) added acquireBackupLock where this commit
places the size-cap check. Both are kept, the cap check first, as
its comment asks: a skip should not first take the lock.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
* test(feat): red — Add soft watchdog warning for long-running schema migrations (refs be-yyzzs)
* feat: green — Add soft watchdog warning for long-running schema migrations (refs be-yyzzs)
* fix(schema): address review follow-ups on migration watchdog doc citation (refs be-yyzzs, review be-sogif)
Round 1 review (be-sogif) flagged criterion 7: the soft-watchdog comment
at schema.go cited engdocs/plans/be-m65rs-migration-watchdog-scoping.md,
which was never landed to any reachable ref (only exists on PM's own
unmerged worktree branch). Replace the dangling file citation with an
inline summary of the rationale plus reachable citations: the existing
initSchema comment in store.go (migration 0047 as a concrete long-runner
example) and `bd show be-m65rs` for the full scoping decision. Comment-only
change; no functional/behavioral diff. gofmt/build/vet clean; full package
suite reconfirmed 132 PASS, 0 FAIL, 0 SKIP.
* test(schema): red — watchdog is silent off a tty, and ignores bare seconds
Both from review #5997.
TestRunMigrationsWatchdogSurvivesNonTTY drives runMigrations end to end
with a deliberately slow first migration body and a 10ms interval, with
the progress writer put in the state a non-tty caller really sees. It
fails with an empty buffer: runMigrations hands the watchdog the package
stderr var, which is io.Discard whenever os.Stderr is not a terminal, so
the warning is discarded under bd serve, systemd, CI and any piped
invocation — the exact cases where a migration running for twenty minutes
needs to be visible. On a tty it works, which is why this went unnoticed.
Asserting on the wiring rather than on a package variable, so the fix has
to actually reach the call site.
The interval table gains bare-seconds cases. store.go's parseTimeout — the
convention migrationWatchdogIntervalDuration's own doc comment claims to
follow — documents "bare numbers treated as seconds (e.g. \"90\")", and
this one does not, so an operator setting the value to 90 silently gets
5m.
Note the review's own example value, 300, cannot serve as the test input:
300s IS the 5m default, so it passes whether the value was parsed or
discarded. Using 90 and 600 instead, which distinguish.
watchdogStderr exists here but is not yet wired, so the red is behavioural
rather than a compile error.
Refs be-lotba.
* fix(schema): point the watchdog's last dangling citation at bd show be-m65rs
Review #5997 point 1. Round 2 replaced the citation on the call-site
comment but missed the one in runMigrationWithWatchdog's own doc comment,
which still named engdocs/plans/be-m65rs-migration-watchdog-scoping.md.
That path does not exist, and neither does engdocs/plans/ — so the comment
sent a reader after a file that was never committed.
Points it at bd show be-m65rs, matching what the call site already says.
This was the last engdocs/plans reference in the repo; a repo-wide grep for
that prefix is now empty, so the two comments can no longer disagree.
Refs be-lotba.
* fix(schema): send the migration watchdog WARN somewhere a non-tty caller sees
Review #5997 point 2. The package's stderr var is io.Discard whenever
os.Stderr is not a terminal (schema.go:26-37) — it was introduced for
routine per-migration progress lines, where discarding off a tty is
correct. Wiring the watchdog to it inherited that gating, so the WARN was
emitted only on an interactive terminal and silently dropped under bd
serve, systemd, CI and any piped invocation: precisely the situations
where a migration still running after twenty minutes is worth knowing
about. On a tty it worked, which is why it was not caught earlier.
Routes the watchdog through its own writer instead. This is not a new
convention for the package — remote_migrate_gate.go, smart_remote_migrate
_gate.go and both schema-skew notices in this file already write operator
warnings straight to os.Stderr, ungated, for the same reason. stderr keeps
its terminal gating and its progress lines.
Chose the writer over the alternative the review offered (scoping the doc
comment to "interactive runs"), since the feature's stated purpose in
be-m65rs is telling an operator reading logs that a migration is still
working — and logs are the non-tty case.
Turns TestRunMigrationsWatchdogSurvivesNonTTY green; it asserts through
runMigrations rather than on the package var, so the wiring at the call
site is what is under test.
Refs be-lotba.
* fix(schema): accept a bare-seconds watchdog interval, matching parseTimeout
Review #5997 nit. BEADS_MIGRATION_WATCHDOG_INTERVAL=300 fell back to the
5m default instead of meaning 300s, so an operator changing the value got
the number they were trying to change and no diagnostic.
The doc comment claimed to follow internal/storage/dolt/store.go's
timeoutFromEnv, but only its unset/invalid-falls-back shape. timeoutFromEnv
is a one-line wrapper; the contract lives in parseTimeout below it, which
retries an unparsable value as raw+"s" so bare numbers mean seconds. This
function skipped that half, so the comment promised a convention the code
did not implement. Now mirrors parseTimeout's full shape — including its
non-positive handling on both branches — and cites parseTimeout by name,
since that is where the behavior being mirrored actually is.
On the review's related note that d > 0 is the only floor: that is
deliberate and is also parseTimeout's only floor. Diverging here would
make the two disagree again, which is what produced this nit. Happy to add
a minimum on both together if you want one.
Not reused directly because parseTimeout is unexported in another package.
The interval table gains bare-seconds cases; 90 and 600 rather than the
review's 300, since 300s is the 5m default and so cannot distinguish
"parsed as seconds" from "fell back".
Refs be-lotba.
* docs(changelog): add the migration watchdog to Unreleased
Review #5997 nit: a new user-facing env var and a new WARN line earn an
Deliberately CHANGELOG only, not docs/reference/configuration.md — even
though BEADS_FSCK_TIMEOUT, the sibling this env var's parsing mirrors, has
a row in that page's table. docs/ describes the pinned release
(docs/cli-docs.pin is v1.2.2, which does not contain this feature) rather
than main, per engdocs/decisions/2026-07-17-docs-release-pin.md. The table
row belongs with the pin bump at release time; adding it now would
document a flag no released bd accepts.
Refs be-lotba.
* fix(bazel): list migration_watchdog_test.go in the schema go_test srcs
Base added internal/storage/schema/BUILD.bazel after this PR's merge base,
enumerating go_test srcs file by file. The PR's new migration_watchdog_test.go
was therefore absent from it, so under Bazel the target reported
"Executed 1 out of 1 test: 1 test passes" while running NONE of the new tests
("testing: warning: no tests to run") -- a silent green.
Measured both ways on the adopted head: without this entry 0 watchdog tests
run; with it, all 7 tests and 8 subtests execute and pass
(bazel test //internal/storage/schema:schema_test). The enumeration is
maintained at 100% repo-wide -- all 56 unlisted test files are
//go:build-tagged -- so this file would have been the only untagged omission.
Maintainer fixup applied during PR adoption's rebase gate. No contributor
code changed; the contributor could not have seen this file, which did not
exist at the merge base.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(schema): scope the watchdog promise to the migration body, stop the warner on panic
Maintainer fixup applied during PR adoption's review loop (iteration 1),
addressing the one major plus the three non-gating findings in the review
synthesis. No contributor commit was rewritten.
Major -- Change Impact / Blast Radius (scope). The watchdog wraps only
execMigrationBody, while a migration step also runs the dirty-table snapshot,
preMigrationRepair, the cursor INSERT and commitMigrationStep -- and this file
already says the per-step DOLT_ADD/DOLT_COMMIT is "the expensive, fallible part
of this step on the production embedded path". The CHANGELOG therefore
over-promised: it told users a wedged migration no longer "looked identical from
outside", which is false for a wedge in that commit. The synthesis offered two
arms and said explicitly not to do both. Taking the minimal-sufficient arm:
CHANGELOG.md now scopes the guarantee to the migration body and states that a
stall in the per-step commit is still quiet, and a comment at the call site
records that the narrow boundary is deliberate, and why. The extension arm was
declined on cost: widening the wrap means moving the snapshot/commit ordering
that carries this loop's atomic-commit contract (#4566, #4690), under a
strict-ordered sqlmock expectation set and the cross-package
migrateStepFaultHook tests -- more risk than an observability-only change should
carry. Measured: this fix leaves runMigrations at gocyclo 16 / gocognit 29,
byte-identical to before, whereas nesting the whole step in a closure would have
driven the cognitive score well past its current band.
Minor -- Resource Lifecycle & Cleanup. close(done)/wg.Wait() moved into a defer.
A panic out of fn skipped the straight-line close and orphaned the ticker
goroutine, which then went on warning about a migration that was no longer
running, for the life of the process, on the deliberately un-gated
watchdogStderr. Reachability is open rather than proven
(internal/httpapi/server.go:1406 recovers everything but http.ErrAbortHandler
and keeps serving), which is the argument for taking the one-keyword fix. Pinned
by a new test: against the pre-fix schema.go it reds with "3 WARN lines when the
panic unwound, 8 after a further 50ms"; with the defer it passes under -race.
Minor -- Test Evidence Quality. TestMigrationWatchdogIntervalDuration's
"unset_defaults_to_5m" arm never unset anything, so the ambient environment flowed
straight into the call. Two-arm control: with BEADS_MIGRATION_WATCHDOG_INTERVAL=600
exported the old arm reds ("= 10m0s; want 5m0s") and the fixed arm passes, with the
subtest confirmed to have actually run rather than being filtered out.
Nit -- Contract & Interface Fidelity. BEADS_MIGRATION_WATCHDOG_INTERVAL added to
docs/reference/configuration.md's env table, beside the BEADS_FSCK_TIMEOUT row
whose duration contract it mirrors.
Validation: go test ./internal/storage/schema/ -count=1 green (41s); 8 watchdog
tests + 8 subtests PASS, 0 SKIP, 0 FAIL; gofmt clean; go vet clean; git diff
--check clean; ./scripts/check-doc-freshness.sh PASSED.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(bazel): list golang.org/x/term in the schema go_test deps
migration_watchdog_test.go imports golang.org/x/term directly. Under Bazel
it compiled only through embed = [":schema"], but gazelle lists a test
file's own imports in the go_test's deps, so `bazel run //:gazelle`
rewrites this BUILD file. Since the base now gates PRs on the Bazel lanes,
BAZEL_TEST's "BUILD files in sync (gazelle, go_srcs, MODULE.bazel)" step
would fail on exactly this one line. This is the line gazelle produces.
Measured on the adopted head refreshed onto current main: the whole CI sync
step run locally (go_srcs.py --check, bazel run //:gazelle, go_srcs.py,
bazel mod tidy) leaves this line as the only drift in the repository.
With it, bazel test //internal/storage/schema:schema_test --config=ci
passes: 433 test cases, 0 failures, all 16 watchdog cases run (0 skipped),
and tools/bazel/check_testcases.py plus equivalence.py report no schema
divergence.
Maintainer fixup applied during PR adoption's pre-approval CI repair. No
contributor code changed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
* test(init): red — existing project with missing server DB must refuse init
be-5up5: server mode never has a local dolt/ directory, whether this is a
genuine fresh clone or an existing project whose database was lost from the
server — doltDirExists==false alone (GH#2433's signal) can't distinguish
them. Adds TestInitGuard_ExistingProjectMissingServerDB_Refuses, which spins
up a real dolt sql-server with no database and a metadata.json carrying a
non-empty project_id (proof of a prior real init). Currently fails: the
guard returns nil and lets init silently recreate the database as empty,
which is the 2026-08-11 fleet-wide data loss.
RED only — checkExistingBeadsDataAt is not yet fixed.
* fix(init): refuse to recreate a missing server-mode database (be-5up5)
bd init's server-mode "already initialized" check treated a missing or
unreachable database the same as a genuine fresh clone, silently
returning nil and letting init proceed to create an empty database —
even when metadata.json's project_id proved this was an existing
project whose database had gone missing (the 2026-08-11 fleet-wide
data loss).
Guard on cfg.ProjectID != "" to distinguish the two cases. An existing
project now gets a refusal (initGuardMissingServerDBMessage) that
names bd doctor / bd dolt status / bd backup restore as the recovery
path and explicitly does not recommend bd bootstrap, since bootstrap
has its own related mode-blind create bug (tracked separately). A new
--recreate-missing flag is required to opt into creating fresh in this
case — never implied by --force, config, or env. Genuine fresh clones
(empty project_id) are unaffected.
Also:
- doctor/gitignore.go: drop the "bd init (safe to re-run)" fix hint,
since re-running bd init is exactly the unsafe action this fix
prevents in the case that matters.
- storage/dolt/errors.go: the general "database not found" hint no
longer claims bd bootstrap is a safe first step for "an existing
project" — only for genuine fresh-clone / shared-server-recovery,
which is what the existing tests actually cover.
* test(init): pin exit_contract's bootstrap-not-recommended requirement (be-5up5)
TestInitGuard_ExistingProjectMissingServerDB_Refuses checked the refusal
and the absence of --force, but not the exit_contract's explicit "does
not recommend bd bootstrap for a server-mode workspace" requirement —
that was only verified by hand during self-review. Pin it directly, and
assert the message names an actual recovery path.
* test(init): cover --recreate-missing positive path (be-ab3b)
be-5up5's guard already correctly permits init to proceed when
--recreate-missing is set; only the negative path (flag absent -> refuse)
had test coverage. Adds TestInitGuard_ExistingProjectMissingServerDB_
RecreateMissingAllows, covering both guard sites the flag gates:
init.go:2566 (server reachable, database confirmed missing) and
init.go:2578 (server unreachable / errored during the check).
refs be-3mvz (review round 1 request-changes), closes be-ab3b
* chore: release gate PASS for bd init missing-server-DB guard fix (be-udx2)
* chore: record full pre-PR contributor check results for be-udx2 gate
* test(init): red — bd init --force recreates a missing server DB as empty
--force is a deprecated alias for --reinit-local (init.go ~395), and the
existing-data guard is gated on !reinitLocal (~763), so --force skips
checkExistingBeadsData — and with it the be-5up5 missing-database refusal
this PR added. The reinit path's own typed confirmation does not cover the
gap either: it keys on countExistingIssues, which returns 0 or an error in
exactly the case where the server-side database is missing, so no prompt
and no destroy token are ever required.
Net effect at this commit, measured against a real dolt sql-server
(2.2.3) holding no "myproject" database, with metadata.json carrying a
project_id:
$ bd init --force --prefix myproject --skip-hooks
...
Database: myproject
Issue prefix: myproject
Run bd quickstart to get started.
$ echo $?
0
$ ls <server data-dir>
config.yaml .dolt .doltcfg myproject <-- created, empty
An empty database at the name the real one used to occupy, exit 0, no
prompt. That is the 2026-08-11 fleet-wide data-loss reflex, reached
through the flag an operator in a panic is most likely to reach for.
This test drives the real binary because that is the only way to exercise
the --force -> reinitLocal -> "skip the guard" path end to end; a unit
test on the guard function cannot see that the caller never runs it.
Both subtests fail at this commit.
Reported in review of PR #5791 by bee-ghosttrack, item 1.
* fix(init): green — --reinit-local/--force cannot bypass the missing-DB guard
Add guardMissingServerDatabaseAt, a narrowed form of the be-5up5 refusal
that answers only one question — is this an already-initialized
server-mode project whose configured database is missing or
unconfirmable? — and run it on the reinitLocal path, which
checkExistingBeadsData never reaches.
The distinction the guard encodes: --reinit-local/--force authorize
destroying a database that EXISTS. They do not authorize inventing an
empty one where the configured database has gone missing. Only the
explicit, per-invocation --recreate-missing does that, which is what makes
that flag's "never implied by --force" help text an honest guarantee
rather than an aspiration. The review suggested softening that help text
instead; making the claim true seemed better than documenting that it
isn't.
Deliberately narrow. It returns nil for every state except the missing
database — no metadata, non-Dolt backend, non-server mode, empty
project_id, or a local dolt/ directory all fall through — so it never
resurrects the "already initialized" refusal that --reinit-local is
legitimately meant to bypass. The "stays silent on a fresh clone with no
project_id" subtest pins that boundary.
Same scenario as the previous commit, now:
$ bd init --force --prefix myproject --skip-hooks
Error:
(warn) Database "myproject" not found on server at 127.0.0.1:34813 ...
bd init will NOT create an empty database here — that would strand any
existing issue data behind a new, empty database of the same name.
$ echo $?
1
$ ls <server data-dir>
config.yaml .dolt .doltcfg <-- nothing created
Addresses review of PR #5791 by bee-ghosttrack, item 1.
* test(init): cover the unreachable-server refuse branch
Review of PR #5791, item 2. The PR claimed
TestInitGuard_ExistingProjectMissingServerDB_Refuses covered both guard
sites — server reachable with the database missing, and server unreachable
or errored while checking. It does not: that test starts a live dolt
sql-server, so it only ever exercises the first. The unreachable site had
coverage on the PERMIT side only (the BEADS_DOLT_SERVER_PORT=1 subtest of
_RecreateMissingAllows), which would not notice if its refusal were
dropped.
TestInitGuard_UnreachableServerRefuses closes that: port 1 is unreachable
by construction, so it needs no dolt binary and runs in the fast lane.
Also drops a comment reference to scripts/repro-bd-init-recreates-empty-db.sh,
which is not in the repo or in this diff (item 3, third bullet), and
describes the state the test sets up instead.
Addresses review of PR #5791 by bee-ghosttrack, item 2.
* docs(init-safety): document --recreate-missing and its known limits
Review of PR #5791, item 3 (doc drift), plus the non-blocking note.
The flag's own help pointed users at `bd help init-safety`, whose FLAG
SURFACE section did not list it — so the one place the help sends you was
the one place it was missing. Added there, stating plainly that it is
per-invocation only and never implied by --force/--reinit-local, config,
or env.
docs/recovery/init-safety.md gains an init-missing-server-db section (and
a TOC entry) covering the refusal users will actually hit: why the
fresh-clone and lost-database cases are indistinguishable from the local
filesystem in server mode, why the old "assume fresh clone" answer caused
the 2026-08-11 loss, and the three ways out in the order they should be
tried — diagnose the server first (a stopped server or wrong --data-dir
presents identically and needs no re-init), then restore from an export,
then --recreate-missing as the deliberate last resort.
Both limits the review flagged as non-blocking are recorded there and in
the guard comment rather than left as folklore:
- The guard keys on project_id, minted by GH#2372. A pre-GH#2372 workspace
carries none and is indistinguishable from a fresh clone, so it FAILS
OPEN. Accepted deliberately — failing closed would block legitimate
first inits on every such clone, and this guard's job is to stop a
silent recreate where prior initialization can be PROVEN, not to guess
where it cannot.
- Server mode only. Proxied-server mode returns early on a missing root
and never reaches the guard, and bd bootstrap has its own separate
mode-blind create path.
Addresses review of PR #5791 by bee-ghosttrack, item 3 and the
non-blocking notes.
* docs(changelog): record the --force missing-database bypass fix
Under Unreleased/Fixed. This is a behavior change to bd init --force on
every server-mode workspace whose database has gone missing, and it was
not recorded anywhere users read.
* fix(init): make the missing-server-database guard fire in shared-server mode
Review round 2, item 1 (blocking): the guard was a no-op in shared-server mode
— the topology of the 2026-08-11 data loss, and so the primary case.
guardMissingServerDatabaseAt statted doltserver.ResolveDoltDir(beadsDir) and
returned early when it was a directory, reading that as "there is local data to
protect". In shared mode ResolveDoltDir returns the machine-global
~/.beads/shared-server/dolt, and SharedDoltDir() MkdirAlls it
(internal/doltserver/doltserver.go:281). The stat therefore always succeeded and
checkDatabaseOnServer was never reached, while every per-project test kept
passing.
Fix per the reviewer's first option: test for THIS project's database directory
rather than the data directory that holds it. A Dolt data dir contains one
subdirectory per database, each with its own .dolt — verified on disk — so
<doltDir>/<dbName>/.dolt is the correct probe in BOTH modes, and it is strictly
more precise in per-project mode too: a data dir that exists but holds no
database for this project no longer counts as local data to protect.
Two new tests, both against a real dolt sql-server rather than an unreachable
port, covering the two cases the reviewer noted were uncovered:
TestInitGuard_SharedServerMode_MissingServerDB_Refuses
reachable server, database absent -> must refuse. This is the actual
loss shape. Reverting the one-line guard change turns it red with
"got nil error"; the pre-existing per-project tests stay green, so it
pins the shared-mode gap specifically.
TestInitGuard_SharedServerMode_PresentServerDB_Allows
reachable server, database present -> must NOT refuse, so --reinit-local
and ordinary reinit keep working. The reviewer verified this by hand and
flagged it as untested.
Also from the same review:
- docs/recovery/init-safety.md overstated the proxied limit. The proxied path
does not reach THIS guard (dispatch at init.go:619 precedes the
initAllowRecreateMissing assignment at :767), but it does reach the older
checkExistingBeadsData (init_proxied_server.go:89) — and because the flag is
never assigned there, --recreate-missing is inert under --proxied-server.
Documented as pre-existing rather than silently fixed.
- Shared-server mode now named explicitly in the same Limits section.
- checkExistingBeedsData typo corrected.
- The "### 3." heading wrapped onto a second line and rendered broken.
Verified: full TestInitGuard suite 15/15 PASS, 0 SKIP (12.1s), including all
pre-existing guard tests. go build ./... clean, gofmt clean, go vet clean.
Refs be-ok1tt, be-udx2.
* test(init): redirect the shared-mode fixtures with BEADS_SHARED_SERVER_DIR
Round-3 MINOR-2, unaddressed through round 4. The two shared-server tests
redirected HOME so SharedDoltDir() would resolve inside the test tree, but
SharedServerPath() reads BEADS_SHARED_SERVER_DIR first and only then falls
back to os.UserHomeDir(). An ambient BEADS_SHARED_SERVER_DIR — the override
that function's own comment advertises for testing — silently won, and the
pair then wrote into and asserted against the developer's real
~/.beads/shared-server/dolt, failing spuriously if a real "myproject" lived
there. HOME is also a no-op on Windows, where os.UserHomeDir() reads
%USERPROFILE%.
Set the variable the resolver actually consults first. No behavior change.
* test(init): make the present-database control pin the early return
Round-3 NIT-4, unaddressed through round 4, and demonstrated there: with the
local-database probe reverted, _SharedServerMode_PresentServerDB_Allows stayed
green, so it pinned nothing of the early return that commit rewrote. It
returned nil via the server check alone, because the fixture never gave this
project a database directory under the shared data dir.
Create that directory, the way a real shared-mode install has one, and then
assert the early return specifically: with the server made unreachable, the
local database directory alone must still satisfy the guard. Removing the
early return now turns this test red.
* test(init): red — the documented --recreate-missing recovery cannot reach its opt-in
Round-3 MAJOR-1 / round-4 finding 1. checkExistingBeadsDataAt derives "is this
project's database here?" from os.Stat(ResolveDoltDir(beadsDir)) — the DATA
directory, which exists on every initialized workspace (shared-server mode
MkdirAlls the machine-global one in SharedDoltDir; per-project mode MkdirAlls
it in ensureDoltInit). So the FR-010 missing-vs-present branch never runs and
both --recreate-missing opt-ins inside it are unreachable.
Four surfaces tell the operator to run `bd init --recreate-missing --prefix
<p>`: the flag help, `bd help init-safety`, docs/recovery/init-safety.md, and
the guard's own refusal text. That command exits 1 with a false "already
initialized" message pointing back at --reinit-local, which is the destructive
path. The documented recovery is a dead end and the only thing that works,
--reinit-local --recreate-missing, is named nowhere.
The existing _Refuses/_RecreateMissingAllows fixtures cannot see this: they
omit the data directory entirely, so their branch condition is true for the
wrong reason. These two add it, which is the state of every real workspace
whose server-side database was dropped.
Both fail at this commit.
* fix(init): green — probe this project's database directory, not the data dir holding it
Round-3 MAJOR-1 / round-4 finding 1. Test for <dolt-data-dir>/<database>/.dolt
instead of the data directory itself, so the FR-010 missing-vs-present branch
is reachable on an initialized workspace and `bd init --recreate-missing`
reaches its own opt-in. This is the same probe, for the same reason, that
guardMissingServerDatabaseAt already uses on the reinit path.
Making that branch reachable also exposes states the data-dir stat used to
shadow, and permitting them would be a new fail-open policy rather than a fix.
The clearest is a workspace that predates GH#2372: it carries no project_id,
so `existingProject` is false, and the branch would permit a silent empty
recreate on exactly the installed base this guard exists to protect. The
data-dir stat therefore stays — it stops being the gate and becomes the permit
condition, admitting only what the old probe already admitted, plus the
explicit per-invocation opt-in. Net behavior change is the opt-in becoming
reachable, and the false "already initialized" message being replaced by the
accurate missing-database refusal where the database is genuinely gone.
Choosing a better proof of prior local init is deliberately NOT done here.
project_id comes from git-tracked .beads/metadata.json, so a fresh clone
inherits one (round-4 finding 2); the replacement signal needs a different
answer in per-project and shared-server mode, and is tracked as its own
architecture decision on be-5pjhd. The known limit is now recorded in the
guard comment and in docs/recovery/init-safety.md rather than left implicit.
Tests: the two red tests from the previous commit now pass, and two more pin
the narrowing — a pre-project_id workspace with a local data dir stays blocked,
and --recreate-missing still opens it.
* docs: record the --recreate-missing fix and the fresh-clone project_id limit
Round-3 NIT-3 / round-4 finding 4: the round-3 probe change (data dir to
<dolt-data-dir>/<database>/.dolt) was never written down, and it is
user-visible wherever the data dir exists but the database is gone. Both that
and this round's --recreate-missing fix are now under [Unreleased] / ### Fixed.
The stray double blank line is gone with the section's move.
Also records, in docs/recovery/init-safety.md's "Limits worth knowing", that
project_id is inherited by a fresh clone because .beads/metadata.json is
git-tracked by default — the round-4 finding-2 gap this series deliberately
does not close. It fails in the safe direction and --recreate-missing is the
supported way through it; the replacement signal is tracked separately.
* docs(adr): ADR-0004 — proof-of-prior-init signal for the missing-database guards
Round-4 finding 2 asked what should replace project_id as the proof that a
workspace was initialized locally, and what the fail-open/fail-closed policy
should be per server mode. It needed a design decision rather than a
mechanical fix, so it was escalated; this records the answer.
The decision is to formalize what the code already does for local hosts and
keep project_id where nothing local can ever help. Presence of this project's
own <dolt-data-dir>/<database>/.dolt is unconditional proof, because the path
is gitignored and only a real local process creates it. Its ABSENCE, however,
cannot be promoted to proof in either direction: it looks identical whether
the workspace was never initialized here or was initialized here and lost its
storage — and the second is the shape of the 2026-08-11 incident. For a
genuinely remote host the probe is not merely silent today, it is structurally
silent forever, since the only code that creates that directory runs on local
server-management paths.
So project_id stays as the tier-2 fallback with its git-inheritance weakness
accepted, and --recreate-missing is the permanent resolution UX rather than a
stopgap. A local-only init marker and repurposing .local_version are recorded
as rejected, with reasons, so neither is re-proposed each review round.
Extends ADR 0002, which set the init safety invariants but left the evidence
question open.
* test(init): red — the reinit guard waves through a pre-project_id workspace
ADR-0004 follow-up 1. guardMissingServerDatabaseAt is the safety net for
--reinit-local and --force, which bypass checkExistingBeadsDataAt entirely. It
returns nil the moment cfg.ProjectID is empty, BEFORE it ever reaches the
per-database .dolt probe eighteen lines below.
checkExistingBeadsDataAt does the opposite: it probes first, and only falls
back to project_id — narrowed by the coarse-directory permit condition — when
that probe comes up empty. So a workspace initialized before GH#2372 minted
project_id, whose local Dolt storage has since been lost, is protected under
plain `bd init` and waved straight through under the two flags an operator
reaches for in a panic. The weaker path is the one behind --force.
Three tests through guardMissingServerDatabaseAt, mirroring the plain-init
trio: no project_id with a local data dir present must refuse; no project_id
with nothing local at all is a genuine fresh clone and must be allowed; and
--recreate-missing must still open the refused case.
The first fails at this commit. The other two pass, and pin the directions the
fix must not break.
* fix(init): green — probe the local database before consulting project_id
ADR-0004 follow-up 1. Move the per-database <dolt-data-dir>/<database>/.dolt
probe above the project_id check in guardMissingServerDatabaseAt, and run it
unconditionally, so this guard reasons in the same order as the plain-init
guard it backstops.
When the probe comes up empty and project_id is also absent, apply the same
coarse-directory permit condition checkExistingBeadsDataAt uses: allow only
when there is no local Dolt data directory either. A data directory with no
database in it still says this workspace has touched local Dolt storage, and
that is exactly the pre-GH#2372 lost-storage case the old early return waved
through under --reinit-local and --force.
One cell of the behavior matrix changes: no project_id, no local database, but
a local data directory present now refuses instead of returning nil.
Everything else is untouched, --recreate-missing still returns nil at the top
of the function, and a workspace with nothing local at all is still treated as
a fresh clone.
The comment records the shared-server asymmetry ADR-0004 accepts — there the
coarse directory is machine-global, so that cell is more conservative — as
settled rather than as an open defect, since it fails toward refuse and its
population only shrinks.
* docs: cite ADR-0004 from the plain-init guard, the recovery doc and CHANGELOG
The comment at checkExistingBeadsDataAt's project_id check said the limit was
"OPEN and tracked by be-5pjhd" and that the replacement signal was
"deliberately not made here". It is made now, so the comment says settled
instead of open, and points at the ADR rather than at a bead — with a note to
read it before reopening, since the two obvious alternatives are recorded
there as rejected rather than unconsidered.
docs/recovery/init-safety.md said the same thing in operator language and is
updated the same way, plus a new bullet stating that the guard now applies
equally to bd init, --reinit-local and --force. That equality is the
user-visible half of the fix and was not previously stated anywhere.
Its "Last reviewed" marker moves to today. The doc is freshness-tracked
against cmd/bd/init.go, which this series changes, and leaving the marker at
2026-09-08 would claim text written today had been reviewed eight days before
it existed.
* chore: remove leaked internal release-gate doc from PR branch
release-gates/be-udx2-init-missing-db-guard-gate.md
Tracked our internal gc-management/beads-rig release-gate checklist and
should never have been committed to this upstream branch -- it's process
residue from our deploy tooling, not part of the change itself.
Per maintainer bee-ghosttrack's request during review of PR #6571. The
root cause (our deploy tooling auto-committing this file) is already fixed
as of gm-qatxl1; this branch predates that fix, so this commit is cleanup
only -- no other content on this branch is touched.
Ref: be-lk7o3
* chore(bazel): enumerate init_guard_force_e2e_test.go in cmd/bd srcs
The PR adds cmd/bd/init_guard_force_e2e_test.go under a plain '//go:build cgo'
tag, which is the tag class cmd/bd/BUILD.bazel enumerates (the 23 unenumerated
test files in this package are all 'cgo && integration', 'scripttests' or
'chaos'). cmd/bd/BUILD.bazel is base-added, so the contributor's branch could
not have carried this row. Generated by 'make bazel-sync'; no hand edits.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(init): honor --recreate-missing on the proxied route; scope the refusal's evidence claim
Maintainer review fixes for PR #5791 (iteration 1). Five review minors; the
three substantive ones:
1. --recreate-missing was inert under --proxied-server. runInit dispatches to
runInitProxiedServer and returns before the assignment site, while
runInitProxiedServer calls checkExistingBeadsData, which reads the global —
so converting a server-mode workspace with a missing database to proxied
mode was refused despite the explicit opt-in, and the refusal named the
exact flag the operator had just passed. It failed closed, so there was no
data hazard, only a recovery dead-end. The assignment now sits beside its
flag read, upstream of every dispatch in runInit.
The PR's recovery runbook documented this inertness as "pre-existing
behaviour, not introduced here". The early dispatch is pre-existing, but
--recreate-missing is introduced by this PR, so the flag could not have had
pre-existing inertness. That paragraph is rewritten to the new behaviour.
2. initGuardMissingServerDBMessage asserted "metadata.json has a project_id"
unconditionally, but the --reinit-local/--force guard also emits it for a
workspace predating GH#2372 where only local Dolt storage proves prior use —
the population the CHANGELOG bullet names. The evidence sentence is now
selected by the caller, so the message never cites an artifact its caller
does not have. Pinned from both sides: the project_id cell must cite that
evidence, the no-project_id cell must not.
3. The new doc comment claimed initGuardServerMessage is "used when there is no
evidence either way". It has no production caller, so the contrast was
asserted as two live code paths. Reworded to intent. The dead message's
surviving "existing project -> bd bootstrap" sentence is pre-existing, is
pinned by four tests, and is left for a follow-up.
Also re-cited two stale path:line references by symbol and branch (the recovery
runbook's three, and a test comment's two), and expanded the else-branch comment
in checkExistingBeadsDataAt to cover the reachable-but-missing fall-through that
lands there — the branch's guards are correct for both cases only because their
conditions do not mention reachability.
Declined, with reasons, as out of scope for opportunistic cleanup: restructuring
the fall-through itself (a control-flow change in the diff's most complex
function, which both review lanes agree is behaviourally correct today);
rewording the caller-less message's bootstrap sentence (four pinned tests,
pre-existing); and adding --recreate-missing to the generated CLI reference
(the required check-doc-flags job passes at this head and seven other registered
initCmd flags are equally absent, so that page is not a flag enumeration).
Validation: go build ./... and go vet ./cmd/bd/ clean; gofmt clean;
go test ./cmd/bd/ -run 'TestInitGuard|TestCheckExistingBeadsData' ok (26 tests,
real Dolt servers); scripts/check-doc-freshness.sh PASSED; git diff --check
clean. The evidence pin was proved non-vacuous by mutation: forcing the reinit
call site back to an unconditional project_id claim reddens exactly the
no-project_id test and nothing else.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(doctor): drop the bd init hint from #5634's permissions warning
1d7629213b on this branch removed "bd init (safe to re-run)" from the
.beads/.gitignore fix hints, because re-running bd init is the unsafe
action be-5up5 guards against. #5634 (c33738d209) reached main while
this PR was open. It added a CheckGitignore warning for unexpected file
permissions that still carries the old hint, so after the merge it was
the only gitignore check that suggested bd init.
Give it the same "Run: bd doctor --fix" hint as the four other
gitignore warnings. That is a complete repair here: FixGitignore
restores mode 0600, and #5634's test already checks that the warning
clears after it runs.
TestCheckGitignore_WarnsOnLoosePermsWhenPatternComplete only checked
that Fix was non-empty. It now pins the exact hint. With the old
gitignore.go line put back, the test fails.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(init): name the real gitignore template in ADR-0004 and init.go
ADR-0004 and the matching comment in init.go both cite
`defaultGitignoreContent` in cmd/bd/doctor/gitignore.go as the place
that says .beads/metadata.json is git-tracked by default. No symbol by
that name exists, in this branch or in main's history. The constant
that says it is GitignoreTemplate. Its closing lines read "Config files
(metadata.json, config.yaml) are tracked by git by default since no
pattern above ignores them".
Rename the reference in both places. The claim itself is unchanged.
Neither file changes outside that one identifier.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* fix(formula): substitute vars in step assignee, labels, and metadata
Cook and pour substituted title/description/notes/gate but copied
assignee, labels, and metadata through raw, so a poured bead carried
literal `{{var}}` text in all three.
- labels: every label-based query, filter, and automation silently stops
matching, and nothing errors (GH#5110).
- metadata: general keys came through literal; only a top-level "repo"
key on a gh:* gate was substituted (GH#5110).
- assignee: worse than cosmetic - close refuses when the actor doesn't
match the assignee, so every step of a poured molecule is unclosable
and the molecule can never advance (GH#5754).
internal/formula/expand.go already substituted assignee and labels on
the inline-expansion path, so the two paths disagreed on the same
fields; Step.Assignee is documented as "supports substitution" and
ExtractVariables already scanned it, meaning pour hard-failed demanding
a variable it then refused to resolve.
Both call sites are fixed together: runtime-mode cook feeds the proto
that pour clones, so a field left literal in either path ships a
placeholder onto the bead. Fixing cloneSubgraphInto covers pour, wisp,
bond, and the proxied-server paths, which all funnel through it.
substituteMetadataRepo is generalized to substituteMetadataVars, which
resolves every string leaf of the metadata JSON at any depth. This drops
the earlier gh:*-gate-only restriction (SF2/SF4): reading a `repo` key
AS a GitHub selector is only correct on a gh:* gate, but resolving a
{{var}} in it interprets the key not at all. The walk still decodes into
json.RawMessage, so untouched values stay byte-identical, and object
keys are never rewritten (a rewritten key could collide with a sibling).
The variable scan is widened to match: extractAllVariables (pour) and
ExtractVariables (cook) now cover assignee, labels, metadata strings,
notes, and await ID, so pour demands exactly the variables it resolves.
Undeclared handlebars are still filtered out by VarDefs.
Regression coverage asserts on a poured bead, and checks the assignee
via validation.AssigneeMatches rather than a string compare - a
substitution-only assertion would pass while the unclosable symptom
persisted.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* chore(formula): regenerate schema_gen.go after the types.go doc edits
TestSchemaGenIsCurrent holds schema_gen.go to a byte-for-byte rerun of
the generator over types.go, and the field docs are part of the
generated output — so the Labels/Metadata comment updates made it stale.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(mol bond): resolve vars like pour instead of demanding every handlebar
buildAttachCloneOpts demanded every variable extractAllVariables found in
the proto subgraph and applied no declared defaults, unlike pour
(cmd/bd/pour.go) and wisp (cmd/bd/wisp.go). Widening the scanned field set
to assignee, labels and metadata therefore widened bond's hard refusal
along with it: a proto whose label or metadata carried an undeclared
documentation handlebar, or a declared var carrying only a default, made
`bd mol bond` fail with "missing required variables" where it previously
succeeded.
Run applyVariableDefaults + extractRequiredVariables there, matching the
sibling call sites. extractRequiredVariables returns the unfiltered list
when VarDefs is nil, so a legacy template still requires every var it
mentions; the change is strictly a reduction in false failures. Applying
the defaults also puts them in opts.Vars, which is the map
cloneSubgraphInto actually substitutes from.
Also from review:
- docs/workflows/gates.md no longer enumerates a stale three-field list for
where `{{var}}` substitution applies.
- maxMetadataSubstitutionDepth's doc names walkJSONStrings (not the
long-gone substituteJSONVars) and says plainly that hitting the bound
deliberately ships a literal placeholder rather than erroring.
Reported-by: bee-ghosttrack
Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* build(bazel): add the validation dep to the bd_test go_test (make bazel-sync)
mol_embedded_test.go and template_test.go now import internal/validation
directly (validation.AssigneeMatches, to check the substituted step
assignee), so gazelle emits //internal/validation on bd_test. bd_lib
already carries the dep, so bd_test compiles through embed, but gazelle
lists every direct test import on the go_test itself. cmd/bd/BUILD.bazel
landed on main after this PR branched, so the PR could not carry the
line; without it, bazel.yml's "BUILD files in sync" step fails in the
required Bazel / test lane. Generated by `make bazel-sync`.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local>
* test(doltserver): red — ResolveServerMode ignores BEADS_DOLT_SERVER_PORT/BEADS_DOLT_PORT (refs be-9i0yq.1)
* feat(doltserver): green — ResolveServerMode honors BEADS_DOLT_SERVER_PORT/BEADS_DOLT_PORT (refs be-9i0yq.1)
* test(doltserver): isolate BEADS_DOLT_SERVER_PORT/BEADS_DOLT_PORT in ambient-blind tests (refs be-lbnk8)
TestResolveServerMode_Default, _EmbeddedMode, and _EmbeddedHonoredWithoutServerEnv
cleared BEADS_DOLT_SHARED_SERVER/BEADS_DOLT_SERVER_MODE via t.Setenv but never
cleared BEADS_DOLT_SERVER_PORT/BEADS_DOLT_PORT, so they silently depended on
ambient absence of those two vars. That held in clean CI but not in this rig
(BEADS_DOLT_SERVER_PORT=28231 ambient), where round-1's new env-port-aware
step 2c in ResolveServerMode correctly fired and these three regressed.
servermode.go is unchanged: its precedence logic was already correct, and the
round-1 tests (EnvPortImpliesExternal, EnvPortOverridesStaleEmbedded) already
prove it. This is a test-hermeticity fix matching the isolation pattern those
two tests already follow.
* fix(doltserver): green — killStaleServersForDir ignores ambient BEADS_DOLT_SERVER_PORT (refs be-lbnk8)
killStaleServersForDir's orphan-cleanup guard (GH#2430) called the public
ResolveServerMode, which treats an ambient BEADS_DOLT_SERVER_PORT/
BEADS_DOLT_PORT (set fleet-wide on multi-agent rigs purely to route bd's
own client connections) the same as a genuine "not my server" declaration
(explicit shared-server/host/port config). That collapsed connection-
routing into lifecycle-ownership, so the guard silently skipped orphan
cleanup for directories beads still owns whenever the ambient var was set.
Split ResolveServerMode into a shared resolveServerMode(dir, honorPortEnv)
implementation:
- ResolveServerMode(dir) = resolveServerMode(dir, true) — unchanged
behavior for all existing callers.
- resolveServerModeIgnoringPortEnv(dir) = resolveServerMode(dir, false) —
skips only the ambient-port-var check, used solely by
killStaleServersForDir's guard.
Audited the other three production ResolveServerMode call sites
(internal/storage/dolt/open.go:47+182, cmd/bd/bootstrap.go:914); all three
correctly want the ambient port var included (auto-start suppression and
clone-strategy selection both need to route to an already-running server),
so they are left calling the public ResolveServerMode unchanged. A fourth
call site (internal/storage/dolt/store.go:1602) already independently
short-circuits on the same env vars before it would ever reach
ResolveServerMode, so it was unaffected by construction. Audit findings
recorded in be-lbnk8's notes.
TestKillStaleServersPreservesOtherRepoServers (added in the prior round)
now passes; TestResolveServerMode_HostInferredExternal and
TestResolveServerMode_EnvHostBeatsEmbeddedMetadata remain the same two
pre-existing/unrelated failures confirmed at the parent commit (tracked
as be-wbyau).
* docs(release-gates): record be-lbnk8 gate PASS (ambient serverport scoping fix)
Deploy gate for be-mob5e (source review be-lbnk8, deploy commit
f5328d863153ecef94df9713ca2e3ed5e0ab0a95). 7/7 criteria PASS, with
two named non-blocking exceptions in the policy/lint lane (stale
.githooks/commit-msg marker check, and a stale golangci-lint
result-cache artifact referencing a deleted worktree) — both
environmental, independently verified, unrelated to the diff.
* fix(doltserver): exempt proxied-server from the port-env check, gate the carve-out
Check 2c classified any workspace with BEADS_DOLT_SERVER_PORT set as external
without either guard HostImpliesServerMode applies. The proxied-server
exemption is the one that bites: a proxied workspace reaches its server through
the proxy, so an ambient port does not describe its lifecycle, and our own
constellation runs dolt_mode: proxied-server with that variable set. 2c now
mirrors 2b's exemption.
The second HostImpliesServerMode guard -- any explicit non-empty DoltMode
suppresses inference -- is deliberately NOT mirrored, because
TestResolveServerMode_EnvPortOverridesStaleEmbedded pins the opposite for
dolt_mode=embedded on GH#2949 grounds. configfile.IsDoltServerMode has no port
check at all, so for that one combination the storage-mode and lifecycle
resolvers still disagree. That is a precedence question above this change, not
something to settle by picking whichever makes the tests green; the code says
so and it is tracked separately.
Adds TestKillStaleServersReapsOrphanUnderAmbientServerPort, the missing gate on
the resolveServerModeIgnoringPortEnv carve-out: it sets the port variable
itself rather than relying on the host exporting one, so it catches a
re-disabled GH#2430 anywhere. Red/green confirmed -- pointing the guard back at
the naive ResolveServerMode gives killed=[], want [222].
Two mode tests also stopped inheriting an ambient Dolt port.
TestResolveServerMode_EnvHostBeatsEmbeddedMetadata and
TestResolveServerMode_HostInferredExternal neutralize SHARED_SERVER,
SERVER_MODE and SERVER_HOST but never the port vars, so on a host that exports
one they asserted against it. The latter fails that way on origin/main too. The
whole internal/doltserver package now passes under this rig's real ambient
BEADS_DOLT_SERVER_PORT, which the previous body claimed and did not do.
Adds the CHANGELOG entry this user-visible auto-start change was missing.
(refs be-lbnk8)
* refactor(configfile): centralize the port-implies-server-mode rule
doltserver kept a private doltServerPortFromEnv plus an inline proxied-server
exemption -- a second copy of a rule that belongs beside HostImpliesServerMode.
Extract Config.PortImpliesServerMode with the same shape (proxied exemption,
then BEADS_DOLT_SERVER_PORT and the legacy BEADS_DOLT_PORT) and have
resolveServerMode's check 2c call it. No resolver changes behaviour.
Also corrects check 2c's doc comment, which was the actual defect the review
found rather than the code. It claimed the "explicit non-empty DoltMode
suppresses inference" guard was deliberately unmirrored and called that an
unresolved precedence question. HostImpliesServerMode does not work that way:
it reads BEADS_DOLT_SERVER_HOST at configfile.go:421-423 and can return there,
before the DoltMode suppression at :424-426 is ever reached. Real precedence is
env > explicit dolt_mode > persisted host, and 2c already mirrors every tier
with a port-side counterpart -- there is no persisted-port tier to guard,
because an explicit dolt_mode=embedded returns at check 3 before check 4 reads
metadata.json's dolt_server_port. Settled as be-yb2ai;
TestResolveServerMode_EnvPortOverridesStaleEmbedded keeps pinning it.
IsDoltServerMode deliberately does NOT consult the new predicate: it selects the
storage backend for every data command, a far wider blast radius than this
lifecycle-only change, and extending it needs its own call-site audit. The two
resolvers therefore still disagree for an unset/embedded dolt_mode plus a bare
port env var and no other server signal. That gap is documented at both sites
and owned by be-2nolj.
TestPortImpliesServerMode covers the new predicate directly: 14 cases over env
precedence, invalid/zero/negative ports, env-beats-explicit-dolt_mode, and the
proxied-server exemption including case-insensitivity. (refs be-lbnk8)
* docs(changelog): say the ambient port marks external, not "no longer suppresses auto-start"
The headline claimed an ambient BEADS_DOLT_SERVER_PORT "no longer suppresses
auto-start". This PR does the opposite: check 2c yields ServerModeExternal for
that var, resolveAutoStart (internal/storage/dolt/open.go:223) returns false on
External, and ensureServerRunning (internal/doltserver/doltserver.go:969-985)
refuses to start with "auto-start is suppressed because the server is
externally managed".
Only the reap clause was true. The headline now states both halves as they
behave, matching the entry's own body text.
Review round 3 blocking point 1 (bee-ghosttrack).
* docs(dolt): note that an ambient server port marks the workspace external
docs/architecture/dolt.md presented BEADS_DOLT_SERVER_PORT purely as the port
knob, in both the server-mode connection table and the environment-variable
table. Since check 2c it is also a lifecycle assertion: on a plain
non-shared, non-proxied workspace it resolves ServerModeExternal, so
auto-start is suppressed and PortSourceEnv -- documented at
internal/doltserver/doltserver.go:630 as an authoritative user assertion --
is unreachable for a bd-owned auto-start. A user setting it to pick a port
gets the "externally managed" refusal instead of a server.
Both sites now say so. proxied-server is called out as exempt; shared-server
already resolves external at check 2, before 2c is reached.
Review round 3 non-blocking point 2 (bee-ghosttrack).
* docs(servermode): cite GH#6181 for the IsDoltServerMode gap, not an invisible bead
Both cross-references for the deferred resolver-precedence gap pointed at
be-2nolj, an internal bead id maintainers cannot see -- the reason review
round 3 asked for a GitHub issue. bee-ghosttrack opened GH#6181
("doltserver: ResolveServerMode and configfile.IsDoltServerMode must share
one inference gate") from this review, which is exactly that tracker, so the
comments now name it.
Comment-only; no behavior change.
Review round 3 point 2 follow-up (bee-ghosttrack).
* feat: green — Fix: PR #5934's env-port check reclassifies bd's own server as shared, so it refuses to migrate (refs be-4yy5e)
* chore: remove leaked internal release-gate doc from PR branch
release-gates/be-lbnk8-serverport-ambient-scope-gate.md
Tracked our internal gc-management/beads-rig release-gate checklist and
should never have been committed to this upstream branch -- it's process
residue from our deploy tooling, not part of the change itself.
Per maintainer bee-ghosttrack's request during review of PR #6571. The
root cause (our deploy tooling auto-committing this file) is already fixed
as of gm-qatxl1; this branch predates that fix, so this commit is cleanup
only -- no other content on this branch is touched.
Ref: be-lk7o3
---------
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(formula): reject a waits_for gate that has no spawner to wait for
waits_for = "all-children" (or "any-children") names no spawner, so
collectDependencies infers one from needs[0] and emits no dependency at
all when the step has no needs. Validation accepted that step, cooking
gave it a gate:all-children label, and the result was a step with zero
dependencies that is ready immediately — a fan-in that silently never
fans in. Only the label survived to suggest otherwise.
Reject it where the intent is still visible, naming both repairs: add
needs, or name the spawner with children-of(step-id), which carries its
own spawner and stays valid without needs. depends_on is deliberately not
accepted as a substitute, because the inference does not read it.
The fan-in example in docs/workflows/gates.md taught exactly the broken
shape — a summarize step with waits_for and no needs — so it is corrected
here alongside, with the spawner step it was missing.
* fix(formula): make a validation failure distinguishable from "not a formula"
Callers that resolve a name as a formula and fall back to a proto/issue
lookup have no way to tell the two apart, so a formula that exists and
does not validate is reported as not found and its real error is thrown
away. The spawnerless waits_for gate rejected above lands in exactly that
path.
ErrVarValidation already exists for the same reason, covering bad --var
values. Give Validate the matching sentinel; the message it produces is
unchanged. Wiring the fallbacks to it is a separate change.
* fix(mol): report an invalid formula instead of calling it not found
pour, wisp, bond and seed resolve a name as a formula first and fall back
to a proto/issue lookup. Any error from the formula path was treated as
"this is not a formula", so a formula that exists and fails validation
came back as "'<name>' not found as formula or proto ID" — with bd
formula list happily showing it. The real error was never printed, and
the advice to run bd formula list confirmed the wrong diagnosis.
Each fallback now reports a validation failure directly, the way it
already does for the bad --var values ErrVarValidation covers. A name
that really is not a formula is unaffected.
* fix(mol bond): make --dry-run validate the formula the real bond validates
resolveOrDescribe resolved a formula name with parser.LoadByName, which
never calls Formula.Validate - LoadByName -> loadFormula -> ParseFile does
not, and only parser.Resolve does. The real bond path
(resolveAndCookFormulaWithVars) calls Resolve, so the dry-run previewed
"will cook as proto" for every formula the real bond rejects, including
for the waits_for-without-a-spawner rule this branch adds. The function's
own comment already promised the opposite.
resolveOrDescribe now resolves before it validates provided vars, which
also means the --var check runs against the merged formula rather than the
unmerged one, so a var declared only in a parent is checked too. The two
error wrappings match the real path's, so the routes produce the same
message rather than merely the same exit code.
TestBdMolBondDryRun_RejectsInvalidFormulaLikeTheRealBond runs both routes
against the same invalid formula and asserts they agree - both fail, both
name waits_for, neither reports it as "not found as issue or formula". It
reproduces the gap against the old code:
dry-run previewed a bond the real bond rejects:
A: dryrun-invalid-gate (formula -> will cook as proto)
Also from review:
- validation_sentinel_test.go uses strings.HasPrefix instead of a slice
that would panic with index-out-of-range rather than failing cleanly if
the message ever shortened.
- Step.WaitsFor's field doc now states the needs requirement, and
schema_gen.go is regenerated from it, so the generated schema documents
the rule the validator enforces. docs/workflows/gates.md already said it.
The condition-filtering follow-up is filed as GH#6437: Validate runs
inside parser.Resolve, before FilterStepsByCondition, so a spawner dropped
by a false condition still reaches collectDependencies as a dangling
reference and is skipped silently - the same zero-dependency gate, past
the new check.
Reported-by: bee-ghosttrack
Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* test(mol bond): assert the dry-run gap in process, not through a subprocess
The regression test spawned an embedded bd and ran two CLI invocations,
which is the most expensive shape of test in cmd/bd - and cmd/bd already
runs 477s of its 600s budget on the macos runner, so the addition timed
the package out.
The process boundary was never what the test was about. resolveOrDescribe
and resolveOrCookToSubgraph are both reachable directly with a molReader
that answers "no such issue", and GT_ROOT puts a temp formula dir on
formula.DefaultSearchPaths without touching HOME or the working directory.
Same assertion - the two routes agree, both name waits_for, neither
reports an invalid formula as not found - in 0.03s instead of 18s.
Asserting the routes against each other rather than against a literal
message is deliberate: it is what stops a validation rule added later from
re-opening the same gap. The LoadByName control is now explicit too, since
that call still accepting the formula is the reason the bug existed; if it
ever starts validating, the comparison stops distinguishing anything and
the test says so instead of passing quietly.
Second case added while here: the dry-run validated --var values against
the UNMERGED formula, so a constraint declared only in a parent went
unchecked. Resolving first fixes that as well, and an extends chain with
the enum in the parent pins it:
dry-run accepted a var value the real bond rejects; the enum is
declared only in the parent (real bond said: formula "dryrun-child":
variable validation failed:
- variable "env": value "staging" not in allowed values [dev prod])
Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs(changelog): move this PR's entry under [Unreleased]
The 1.3.0 cut renamed the old [Unreleased] block, so the entry this branch
added there now merges cleanly into the released [1.3.0] section (#6643).
Agent-Signature: claude-code-opus-5-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* chore(bazel): enumerate the PR's two new test files in go_test srcs
Base added cmd/bd/BUILD.bazel and internal/formula/BUILD.bazel after this
branch's merge base, so the two untagged _test.go files this PR adds were
absent from their go_test srcs lists. Generated by 'make bazel-sync'
(bazel run //:gazelle); no hand edits. A second sync is a no-op.
* docs(formula): correct the waits_for spawner doc and the dry-run parity claim
Maintainer review fixup for the adoption of #5761 (review iteration 1
pre-merge checklist). Wording only -- no control flow changes.
internal/formula/types.go: the new Step.WaitsFor doc said "Requires needs
(or depends_on)", but Formula.Validate receives only step.Needs and cook
infers the spawner solely from Needs[0] (cmd/bd/cook.go:961-962) -- the
DependsOn loop never feeds waitsForSpawnerStepID, and the struct doc's
"merged during cooking" happens after Validate. A depends_on-only bare gate
is therefore correctly rejected: the code and the error message are right,
only the comment was wrong, and it shipped into the generated schema surface
agents read. docs/workflows/gates.md already states it correctly.
Regenerated schema_gen.go with `go generate ./internal/formula/`.
CHANGELOG.md: "so it fails on exactly what the real bond fails on" was an
overclaim. The dry-run now resolves and validates the way the real bond
does, but five later real-path failure surfaces (inline expansions,
expansions, aspect load/type, condition filtering) stay outside the preview.
Named that boundary rather than claiming total parity.
Contributor commits untouched.
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
* storage: add RenameLabel primitive with merge semantics
Add a storage primitive that renames a label across every issue and
wisp that carries it, in one transaction per store. An issue that
already carries the new label is a merge - the stale old-label row is
dropped rather than raising a duplicate-key error - and the call
reports renamed/merged counts plus every touched id.
- internal/storage/issueops/labels.go: RenameLabelInTx sweeps the
labels and wisp_labels tables (INSERT IGNORE then DELETE, so the
merge never errors), emitting one EventLabelRenamed plus the usual
full-snapshot journal row per touched issue/wisp, matching
AddLabelInTx/RemoveLabelInTx's journal shape. A single batch event
was considered and rejected: the journal-completeness guard requires
every touched row to carry its own journal entry.
- internal/storage/storage.go: RenameLabel added to the Storage
interface, next to AddLabel/RemoveLabel/GetIssuesByLabel.
- internal/storage/dolt, internal/storage/embeddeddolt: direct
implementations. The dolt commit targets the fixed events/labels
table pair; doltAddAndCommit's own HasStagedChanges guard skips it
when the rename touched wisps only (wisp tables are dolt-ignored,
same as AddLabel/RemoveLabel).
- internal/storage/hook_decorator.go: HookFiringStore.RenameLabel
fires on_update per touched issue, matching AddLabel/RemoveLabel.
- internal/types/types.go: new EventLabelRenamed event type. Unlike
EventLabelAdded/EventLabelRemoved, one rename produces exactly one
of these per touched row, never a paired add+remove.
- internal/jira/tracker_test.go: mock stub for the new interface
method.
Tests: internal/storage/dolt/label_rename_test.go, against a real
dolt-sql-server container - basic rename, merge, wisp sweep,
zero-carrier no-op, over-length refusal, event assertion. All green.
Also verified TestEveryBeadMutatorJournalsOrIsExempt still passes.
Gates: gofmt clean, go vet ./... clean, CGO_ENABLED=0 go test -tags
gms_pure_go -c -o /dev/null ./cmd/bd clean, go build ./... clean.
* storage: refuse RenameLabel(x, x) instead of wiping the label
RenameLabelInTx's merge branch treats every carrier of oldLabel as
already carrying newLabel when the two names collide (they are the
same string): the batched INSERT IGNORE no-ops on every row, and the
unconditional DELETE FROM <table> WHERE label = ? that follows then
removes every row for that label plane. A self-rename silently wiped
the label instead of leaving it untouched.
Reject oldLabel == newLabel (compared after trimming, case-sensitive)
before any write, returning the new ErrRenameLabelSameName. Verified
red->green: TestRenameLabel_SameNameRefused and
TestRenameLabel_SameNameAfterTrimRefused both fail (GetLabels returns
[] on both the labels and wisp_labels planes) against the pre-fix
code, and pass against the fix. Full TestRenameLabel* suite in
internal/storage/dolt still green.
* telemetry: instrument InstrumentedStorage.RenameLabel
AddLabel and RemoveLabel already get OTel spans/metrics through
InstrumentedStorage; RenameLabel had no override and so fell through
to the embedded storage.DoltStorage passthrough, invisible to
storage.* tracing. Add the override, mirroring the AddLabel/RemoveLabel
shape: span attributes for the old/new label pair (bd.label.old,
bd.label.new, matching the existing bd.dep.from/bd.dep.to pairing
convention), and on success a bd.result.count / bd.merged.count pair
following the SearchIssues-style "set result attributes after a
successful call" pattern already used elsewhere in this file.
* storage: document the O(N) round-trip cost of RenameLabelInTx's event loop
renameLabelInPlane's per-issue loop (InsertDerivedEvent + RecordEventInTx)
is O(len(oldIDs)) SQL round trips inside one transaction, up to four per
touched issue. On a huge label population that lengthens the transaction
and raises the odds an optimistic-concurrency retry has to redo the whole
rename from scratch.
No batching added: InsertDerivedEvent's dedup SELECT is a real
cross-replica convergence check (Protocol v0.1 C2.3), not a redundant one
this transaction could skip, and no batch primitive for this shape exists
anywhere in this package - building one here would be new shared
infrastructure grown for a single caller. AddLabelInTx/RemoveLabelInTx
already pay the identical per-call cost for their one issue; this loop is
that cost repeated once per touched issue. Documented inline as a
disclosed limitation rather than silently left unremarked.
* bda-lbjv: derive rename merge count from rows-affected, not a prior read
renameLabelInPlane computed merged from a snapshot SELECT of newLabel's
carriers taken before the INSERT IGNORE - a check-then-insert whose
result is used. A concurrent AddLabel(issue, newLabel) committing between
snapshot and insert made the reported count schedule-dependent while the
stored data stayed correct (cross-model finding: the Opus panel cleared
A1, codex flipped it to NOT-SAFE on exactly this line).
Now the count is a measurement: INSERT IGNORE reports one affected row
per id actually inserted, so merged = len(oldIDs) - inserted, and the
newLabel pre-read is gone entirely.
Tests: sqlmock scripts the racing schedule (insert sees a row the
snapshot read could not); mutation control confirms the old
implementation fails the new test. Full issueops package + live-store
TestRenameLabel_* green.
* bda-c77s: first-party coverage for EmbeddedDoltStore.RenameLabel
The embedded impl had zero tests while DoltStore.RenameLabel carries a
dedicated suite; AddLabel/RemoveLabel both have parallel embedded
coverage by convention. Four wiring cases (basic, merge, zero-carrier
no-op, same-name refusal) - the deep semantics stay pinned by the shared
issueops suite and the dolt-side tests against the same implementation.
BEADS_TEST_EMBEDDED_DOLT=1: 5 RUN, all green, 2.8s.
* storage: scope the rename delete to the ids the sweep captured
An unrestricted DELETE ... WHERE label = ? makes the sweep's blast radius
engine-dependent: under current-read DELETE semantics a row a concurrent
AddLabel(oldLabel) committed after this transaction's snapshot would be
removed without ever being renamed, counted or journaled. Restricting the
delete to the captured ids touches exactly the rows the INSERT IGNORE above
accounted for on every engine; a concurrent add outside the snapshot now
deterministically SURVIVES the rename - the same observable state as that
add landing after the rename committed, which is the only order-independent
reading of the race.
sqlmock WithArgs pins the id-scoped statement shape; the embedded-Dolt
lifecycle set stays green (5/5).
* cmd/bd: add `bd label rename <old> <new>` with dry-run preview
Wire the storage.RenameLabel primitive (previous commit) into a CLI
command that renames a label everywhere it appears in one call instead
of a per-issue add-then-remove loop.
- cmd/bd/label.go: `bd label rename <old> <new> [--dry-run]`.
validateLabelRename refuses empty/identical labels and the
'provides:' reserved prefix before any store call - it is a pure
function so those rules are testable without a store. --dry-run
previews the blast radius (count plus the first issues) read-only,
via a path kept separate from the write path so it can never reach a
transaction.
- cmd/bd/label_proxied_server.go: the proxied-server route composes
the existing per-issue LabelUseCase.AddLabel/RemoveLabel (and wisp
twins) in one uow.RunTx, the same fan-out shape label propagate
already uses on this route. It journals as an add/remove pair per
issue rather than the direct route's single EventLabelRenamed,
because LabelUseCase has no rename-shaped event; the rename
semantics (merge-on-collision, honest zero-carrier no-op, dry-run
preview) are identical on both routes.
- docs/core-concepts/labels.md: documents rename, dry-run, and merge
semantics under Label Management.
Tests: cmd/bd/label_rename_test.go (pure argument-validation table
test, no store needed) plus new subtests in
cmd/bd/label_embedded_test.go covering the full CLI path - basic
rename, merge, dry-run writes nothing, zero-carrier no-op,
identical/empty/reserved-prefix refusals. All green.
Gates: gofmt clean, go vet ./... clean, CGO_ENABLED=0 go test -tags
gms_pure_go -c -o /dev/null ./cmd/bd clean, go build ./... clean.
* cmd/bd,domain: emit label_renamed on the proxied route, not add+remove
runLabelRenameProxiedServer used to fan a rename out into a per-issue
AddLabel-then-RemoveLabel pair, journaling label_added/label_removed
instead of one EventLabelRenamed - a divergence from the direct
DoltStore/EmbeddedDoltStore route the upstream reviewer has already
rejected for another PR touching the same class of proxied/direct
split.
Add domain.LabelUseCase.RenameLabel and domain.LabelSQLRepository.
RenameLabel. The repository method delegates straight to
issueops.RenameLabelInTx (r.runner satisfies issueops.DBTX
structurally), so the proxied route is not merely the same SQL SHAPE
as the direct one, it is the same function: identical merge semantics,
the same ErrRenameLabelSameName refusal, and one EventLabelRenamed per
touched issue. runLabelRenameProxiedServer now just calls
uw.LabelUseCase().RenameLabel(...) inside its existing uow.RunTx.
Declare recordingLabelUC.RenameLabel so the notifying unit of work
records one update per touched issue/wisp (mirroring
HookFiringStore.RenameLabel on the direct route) instead of silently
recording nothing through the embedded interface - caught by the
existing structural parity guard, TestRecordingLabelUseCaseCoversItsSurface,
which fails on any domain.LabelUseCase method neither declared on
recordingLabelUC nor exempted with a reason.
Tests, verified red->green:
- internal/storage/domain/db: TestLabelUseCase/RenameLabel adds 5
subtests. EmitsOneRenamedEventPerIssue is the direct regression
test - reverting RenameLabel to a simulated add-then-remove
fan-out reproduces exactly the pre-fix event counts (renamed=0,
added=2, removed=1) it now asserts against (renamed=1, added=1,
removed=0).
- cmd/bd/label_proxied_integration_test.go: new "rename" subtest
exercises `bd label rename` end to end through the real proxied
server and asserts the same label_renamed/added/removed counts
directly against the events table.
- internal/storage/uow: TestRecordingLabelUseCaseCoversItsSurface
goes red (RenameLabel inherited, records nothing) without the
recordingLabelUC override and green with it.
Full internal/storage/uow suite (287s) and the new domain/db and
cmd/bd tests all pass.
* cmd/bd: record commandDidWrite before the rename error return
runLabelRename read renamed>0 into commandDidWrite only after the
`if err != nil` early return, so a rename whose SQL side committed but
whose store call also returned an error - the Dolt publication step
failing after the working-set write landed - never marked the command
as having written. The caller's deferred auto-commit would then skip
creating a Dolt commit for a write that, on disk, actually happened.
Move the commandDidWrite.Store(true) check ahead of the error check,
matching applyLabelEdit's existing per-issue marking a few lines above
in the same file.
New test: TestRunLabelRename_CommandDidWriteSetBeforeErrorReturn wraps
a real *dolt.DoltStore in a spy whose RenameLabel reports a publish
failure (renamed>0, err!=nil) after delegating to the real rename, and
asserts commandDidWrite is set despite the returned error. Verified
red->green: reverting the ordering reproduces the exact failure this
guards against.
* bda-bnid: nolint:forbidigo on proxied bulk rename call
The route delegates to domain.LabelUseCase.RenameLabel deliberately: one
EventLabelRenamed per issue with identical merge semantics to the direct
route. Patch.Labels (the lint's suggested remedy) would reintroduce the
per-issue add/remove event divergence this delegation replaced. Matches
the file's own convention (4 sibling nolints, same shape).
Negative control: without the nolint golangci-lint forbidigo reports
exactly this line; with it, 0 issues.
* cmd/bd: address review on label rename (CHANGELOG entry, dry-run caveat, partial-failure count)
Two blocking items from review (bee-ghosttrack, PR #6009):
- Add the CHANGELOG entry for `bd label rename`, in the house voice used
by the neighboring bd-label entries (bold lead sentence, PR link, dense
explanatory prose on the merge/dry-run/partial-failure contract).
- The `--dry-run` merged count is a plain snapshot intersection of two
independent reads - exactly the check-then-count shape
renameLabelInPlane's own comment documents rejecting for the write
path, because it is schedule-dependent under a concurrent
AddLabel/RemoveLabel. That is an acceptable estimate for a preview, but
nothing said so: the command's Long text, the --dry-run flag help, and
an inline comment at the computation site now all say the number is
not authoritative.
One non-blocking nit fixed (the other - hydrating full issue rows in the
direct dry-run just to print 10 titles - is left alone; see below):
- On a partial rename failure (renamed>0, err!=nil - e.g. a Dolt
publication failure after the SQL side already committed) the command
now reports how many issues were renamed and merged before the
failure, instead of only the error. Mirrors the existing shape in
conflicts.go's ResolveConflictRows handling ("resolved %d of %d
conflict(s) before failing").
Left alone, and why: the GetIssuesByIDs-hydration nit. GetIssuesByLabel
hydrates every matching issue via GetIssuesByIDs on both the old-label
and new-label reads, which is wasteful on a label carrying 10k issues
when the text-mode preview only prints 10. But the JSON-mode contract
already returns every matching issue's id+title (not capped at the
preview limit), so avoiding hydration only helps the text-mode path and
would branch the two output modes apart for a marginal win on an
uncommon case (a rename dry-run over a 10k-issue label). Not clean
enough to do inline without its own test coverage and a decision about
whether the JSON contract should change too - flagged in the review as
skippable, so skipping it here.
Verification:
- go build ./... - clean
- go vet ./cmd/bd/... - clean
- gofmt -l cmd/bd/label.go - clean
- go test ./cmd/bd/... -run 'Label|LabelRename' - all pass
- BEADS_TEST_EMBEDDED_DOLT=1 go test ./cmd/bd/... -run 'TestEmbeddedLabel$' -v
- all pass, including label_rename_basic/merge/dry_run_writes_nothing
- BEADS_TEST_PROXIED_SERVER=1 BEADS_TEST_EMBEDDED_DOLT=1 go test ./cmd/bd/...
-run TestProxiedServerLabel -v - all pass, including the "rename" subtest
- BEADS_TEST_EMBEDDED_DOLT=1 go test ./internal/storage/issueops/... -run Rename -v
- BEADS_TEST_EMBEDDED_DOLT=1 go test ./internal/storage/dolt/... -run Rename -v (live dolt-sql-server)
- BEADS_TEST_EMBEDDED_DOLT=1 go test ./internal/storage/embeddeddolt/... -run Rename -v
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* cmd/bd: report an upper bound on a failed rename, not a landed count
The partial-failure message asserted that renamed>0 means the SQL side committed. On both routes the counts are assigned inside the transaction closure (label_proxied_server.go RunTx, dolt/labels.go withRetryTx), so a Commit failure or retry exhaustion returns them holding the rolled-back attempt numbers - nothing landed, and the user read 'renamed 6 issue(s) before failing'. Retry exhaustion under a busy server is the likely failure for a bulk rename, so it misreported exactly when it fired. Now reports an upper bound. commandDidWrite keeps the same premise deliberately: it is fail-safe in the other direction.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* cmd/bd: pin the partial-failure wording, and hedge the merged count too
Round-3 review: the r2 correction rode unpinned. Nothing in the suite drives
a failing rename with renamed > 0, so the whole TestEmbeddedLabel suite passed
with the hunk reverted - the fix was unfalsifiable, which is the same defect
class the correction itself was about.
Extracts the sentence into labelRenamePartialFailureMessage, a pure function a
test can assert on without inducing a mid-transaction failure, and pins it:
the hedged phrasings must be present AND the two pre-correction phrasings must
be absent. Mutation-checked - restoring the old wording turns it red on three
assertions.
Also the round-3 nit: (%d merged) was the one unhedged clause in a hedged
sentence. It now reads (of which up to %d merged), so no number in the message
asserts a write that may never have landed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* docs: retire the landed-count premise from the CHANGELOG too
Round-4 review, MAJOR: the code retracted a premise and the CHANGELOG kept
publishing it. The entry still said a partway failure 'reports how many issues
were renamed and merged before the failure' - a landed count - while
labelRenamePartialFailureMessage had already become an upper bound.
The sentence carried the premise TWICE and the review named one: besides the
count, its parenthetical offered 'a Dolt publication failure after the SQL side
already committed' as the case, when the whole point of the correction is that
renamed > 0 cannot distinguish that from a rollback. Rewrote both halves: the
bound is explicit, and the two failure shapes are named as indistinguishable
from the count alone.
Also round-4 MINOR: the helper had been inserted between reportLabelRename's
doc comment and its func, so the comment headed the wrong function and
reportLabelRename was left undocumented. Moved back down.
Not done, deliberately: the round-4 NIT that the pin covers the helper and not
the call site. It is marked 'noting, not asking', and an unrequested fix is the
one that ships a defect - this PR already demonstrated that.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* CHANGELOG: move this PR's entry under [Unreleased]
The 1.3.0 cut renamed the old [Unreleased] block, so these lines
merged cleanly into a released section (gastownhall/beads#6643).
Moved 31 line(s); the code is unchanged.
* cmd/bd: register label rename in the proxied capability registry
TestProxyCapabilityRegistryCoversCommandTree requires every command path to
carry a proxied-server row. label rename has a proxied route (RunE hands the
rename to runLabelRenameProxiedServer and the --dry-run preview to a proxied
read UOW), so it joins its label siblings in proxyPermittedPaths.
* storage: mint a version for every bead a label rename touches
TestEveryBeadMutatorMintsOrIsExempt (added with #6650) fails on this PR:
RenameLabelInTx writes the labels table but never reached
RecordVersionInTx. A rename changes the label set - part of the durable
snapshot - of every issue that carried oldLabel, whether it gained
newLabel or already had it (merge), so each touched issue now mints one
version row, the same gate AddLabelInTx/RemoveLabelInTx draw on a row
that landed. RecordVersionInTx is already a no-op for wisps and when
versioned history is disabled, and a rename nobody carries touches no
id, so the no-op shape mints nothing.
TestRenameLabelMintsOneVersionPerTouchedBead is the runtime twin of the
static guard: plain rename +1, merge +1, untouched bead +0, a second
rename with no carriers +0, current_revision equal to the row count.
* build(bazel): list this PR's six new test files in their go_test srcs
Generated-artifact drift repair, produced by the repository's own command
(`make bazel-sync`) and inspected before committing, not hand-written.
The PR adds six `_test.go` files and none were listed in their package's
`go_test` srcs, so Bazel compiled each of those packages' test targets without
them - green by omission. That was invisible on the pre-merge head because its
CI predates the Bazel lanes entirely (zero `Bazel /` rows). This merge brings in
e1b2e79484 (#6941), which makes those lanes feed the required gate, so the
omission would now surface as a real red.
Purely additive: 6 insertions, 0 deletions, `go_test` srcs only. No `go_library`
srcs change is needed because every added file is a test, which is also why this
cannot break the build the way a missing production source would.
Verified: `make bazel-sync` is now a no-op against this tree (empty porcelain),
and `bazel build //cmd/bd/... //internal/storage/... //internal/types/...
//internal/telemetry/...` completes successfully - 3429 actions, 0 errors.
---------
Co-authored-by: Marco Del Pin <marco@omniaevo.it>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Add beads-pm-kit to the orchestration section: ten PM skills for running
a Beads board (split, estimate, take, loop, fleet, pm-loop, report,
forecast, audit, handoff), installable with
`npx skills add cuongbphv/beads-pm-kit`. The entry is sized to match its
neighbours in the section.
An implementation of the mail.delegate seam that gives any beads repo a
working bd mail. aweb is an open-source communication layer for agents:
durable mail and chat, wake-up events, local (team) or global
(cross-organization, federated) identities, signed and verified senders;
self-hostable or hosted. Guide and recording:
https://aweb.ai/docs/beads-mail/
Co-authored-by: Juan Reyero <juan@thestarmaps.com>
* 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>