* 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>
628 KiB
Changelog
All notable changes to the beads project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[Unreleased]
Added
backends.Backendgains an optionalOpenWith(ctx, beadsDir, OpenOptions)and aRemote boolfield for a registered extension backend (for example an HTTP client registrant).OpenOptions{Credential, HTTPClient, UserAgent}carries per-open injections — the motivating case is a single embedder process serving many workspaces with distinct credentials against a backend whose dialer would otherwise be process-global.Openkeeps working unmodified: a backend with noOpenWithfalls back to it and ignoresHTTPClient/UserAgent, but refuses rather than silently drops a non-nilCredential. The public SDK gainsbeads.OpenBestAvailableWith(and thebackendpackage's matching aliases);beads.OpenBestAvailableis now that function called with a zeroOpenOptions, with identical behavior for every existing backend.doltserver.ResolvePhysicalRootsnow recognizes a registered remote backend (backends.IsRemote) before any Dolt-mode check, so a remote-backend workspace is never misclassified as having a local Dolt root to gate.bd serve'sGET /v0/beads/contextnow reportswire_revision(the non-additive wire-shape counter for this build) andmin_client_wire_revision(the oldest revision this build still answers correctly). A client may declare the revision it was built for on any request via the optionalBd-Wire-Revisionheader (a plain non-negative decimal — no leading+or leading zero); a declared revision belowmin_client_wire_revisionis refused with400 invalid_argument/reason: "wire_revision_unsupported"andmin_wire_revision,wire_revision, andbd_versionfields naming this server's floor, current revision, and release string. The header is absent by default and an absent header is served exactly as before — this is additive, not a new precondition on existing clients. A client with nowire_revisionsignal to read yet may infer one frombd_versiononly as an ADVISORY hint (string-or-number, never a refusal on an inferred0) — see thewire_revisionproperty's inference notes ininternal/httpapi/spec/openapi.v0.yamlfor the cutoff and known-exception builds. Seeinternal/httpapi/wire_revision.goand that same property for the full revision history.GET /v0/beads/issues'ssortparameter now advertises theissues.list.sortcapability token, the same way an operation itself does, and a CI rule (TestNewParameterOnExistingOperationHasABehaviorToken) requires every new parameter on an existing operation, or new request body member on an existing operation, to carry a token thatCapabilities()actually advertises (not just backtickeda.btext shaped like one). Three frozen baselines (internal/httpapi/testdata/pretoken_*.json) grandfather what predates the rule and are pinned never to grow (TestPretokenBaselinesNeverGrow); a brand-new operation is permanently exempt — its own review decides its capability story.- A CI golden digest (
internal/httpapi/wireshape) pins the JSON name, type, format, enum, required-ness, and nullability of every EXISTING response AND request-body member across the whole HTTP spec — including array item shape andadditionalPropertiesvalue shape — recursing through$refand through a schema's ownallOforoneOf, and fails if any changes withoutwire_revisionbumping to match;go run ./internal/httpapi/wireshape/cmd/gendigestrefuses to write a changed or removed entry unlesswire_revisionhas moved past what the existing golden recorded, and refuses any write at a lowerwire_revision(purely additive entries otherwise always write). The same digest also pins every operation PARAMETER (query, path and header), keyed by operationId + location + name, and records its type, item shape, enum, required-ness, effective style and explode (OpenAPI's defaults filled in where unset), and default — a parameter retyped, re-enumerated, narrowed, re-serialized, switched required, or removed is non-additive exactly like a response or request-body member. A new member or parameter always counts as additive, even a REQUIRED one an old client will not send, and value constraints (maxLength,patternand the like) are outside the digest: such changes need their own review againstwire_revision.
Changed
bd preflight --fix --jsonno longer returns aVersion syncfix result: version updates must keep all release surfaces aligned viascripts/update-versions.sh.- Release-tag pushes require Go and reject batches containing different release versions.
- On version drift the release-tag pre-push hook points at the checker's
remedies instead of prescribing
scripts/update-versions.sh <version>, andscripts/check-versions.shandbd preflightlist the three that work: withcmd/bd/version.goalready at the release version, that re-run rewrites only the.githooksmarkers anduv.lockand leaves any other drifted file as it was.
Fixed
-
PRs based on
hotfix/**branches now run full CI, not just cross-version historical smokes and triage labeling.pr.yml,pr-risk.yml,conformance.yml,cross-version-smoke.ymlandregression.ymlall triggerpull_requestonmainandrelease/**, but not onhotfix/**— a backport PR based on a hotfix line (the same positionrelease/**was added for) got no unit shards, no lint, no risk gate, and no required CI Gate at all: 15 passing cross-version smokes and triage jobs, nothing else. Addedhotfix/**alongsiderelease/**in all five (#7148). -
Ordinary bd commands now wait out a maintenance operation instead of failing at once. While
bd init,bd backup restore,bd migrateorbd bootstrapholds the workspace gate exclusively, every other bd command on that workspace — and, in shared-server mode, on every project sharing the server (another project's ~8sbd init) — failed immediately with "a maintenance operation is running". They now wait up to 30s (one "waiting for another bd process" notice after 2s; Ctrl-C aborts), then fail with the same error naming the bound (and, in shared-server mode, saying the holder may be another project). Override withBEADS_GATE_WAIT_TIMEOUT(1m,90); scripts that relied on the old fail-fast behavior should setBEADS_GATE_WAIT_TIMEOUT=0. Git hooks stay fail-fast so a commit or checkout is never stalled. Waiting is writer-fair: once a maintenance operation is waiting for the gate, newly started commands queue behind it, so a steady stream of short commands can no longer starvebd init. The queue only ever delays a command, never fails it, and a maintenance operation that cannot get in (for example behind abd list --watch) stops queueing others after 10s. Queued maintenance operations run one after another, and a waiting command waits for all of them. The queue marker is an OS lock beside the gate (*.gate.lock.intent, covered by the existing*.gate.lock*gitignore pattern), so a crashed waiter never leaves a stale queue behind.bd init's own wait (BEADS_INIT_GATE_TIMEOUT) rises from 30s to 60s, since back-to-back inits under load take 10-15s each. -
Concurrent
bd init --shared-serverruns in different projects no longer refuse each other. Every shared-server project gates the one shared dolt data dir, andbd initholds that gate exclusively for its ~8s run but waited only 5s for it, so a second init (or an init during another project's long command) failed with "bd init refuses to run over live bd activity".bd initnow waits (60s by default, see the gate-wait entry above), printing one "waiting for another bd process on the shared server" notice after 2s, then fails with the same refusal naming the bound. Override it withBEADS_INIT_GATE_TIMEOUT(2m,90). Other exclusive operations keep their 5s wait. -
A proxied-server command against an unreachable external Dolt upstream now fails within about a second with a clear error instead of stalling ~20-30s. The local db proxy stayed up, so the client only saw a bare close, which the bootstrap ping retried as a transient drop for its whole 30s budget before reporting
invalid connection. The proxy now answers such a connection with a MySQL error (2003, prefixedbeads db proxy:) saying what happened: the dial was refused / the socket is missing / the host is unreachable, or the upstream closed the connection before the MySQL greeting (down, restarting, or at its connection limit). The client retries that error only for about a second, so an endpoint that is flapping or rebinding is still ridden out within one command. A backend that drops a connection after the greeting, a dial timeout, and every refusal from a managed (local sidecar) backend keep the full transient retry. -
bd listno longer silently drops all but the last repeated filter flag.--status,--state, and--idwere plain string flags, sobd list --status open --status closed --status pinnedkept onlypinned— a census over 477 issues quietly answered over 3, with nothing in the output to distinguish the narrowed answer from a correct one. Repeats of those three flags now accumulate (duplicates collapse) instead of overwriting, so--status open --status closedselects the same set as--status open,closed. The one repeat that does not simply accumulate is one involving--status all:allcannot be combined with other statuses, so--status all --status openis now refused rather than narrowed toopen.--typeand--assigneeare single-valued all the way down — unioning would fail type validation or exact-match nobody — so a repeat of either now refuses loudly instead of silently keeping the last value:invalid argument "epic" for "-t, --type" flag: --type given more than once (already "bug"); pass a single value. Single-flag and comma-form spellings behave exactly as before. -
bd restore,bd admin compact,bd repo <add|remove|list|sync>,bd migrate [sync|hooks|schema]andbd preflightno longer register a local--jsonthat shadows the root persistent flag. pflag keeps a command's own flag and drops the inherited one, sorootCmd.PersistentFlags().Changed("json")stays false for that command; #6293 compensated for that per command by making the pre-run consult the subcommand's ownChangedbit before the root's. Deleting the eleven local registrations removes the shadowing itself rather than working around it:--jsonmoves to the Global Flags section of those commands'--help, and a guard test now fails the build if a command shadows the root flag again — closing the class before an unbound local copy can reappear and invert the output mode it was meant to select. -
bd init --forcecan no longer silently recreate a missing server-side database as empty (be-5up5).--forceis an alias for--reinit-local, which skips the existing-data guard entirely, and the reinit path's own typed confirmation keys on the issue count — which is 0 in exactly the case where the database is missing. Sobd init --forceagainst a lost database created a fresh empty one at the same name, with no prompt and no destroy token: the 2026-08-11 fleet-wide data-loss reflex, reached through the flag an operator in a panic is most likely to try. The missing-database refusal now applies on the reinit path too.--force/--reinit-localauthorize destroying a database that exists; only the explicit, per-invocation--recreate-missingauthorizes creating one where the configured database has gone missing. -
bd init --reinit-localand--forceno longer wave through a workspace that predatesproject_id. Their missing-database safety net returned early whenever.beads/metadata.jsoncarried noproject_id, before it ever probed for this project's local database directory — so a workspace initialized before GH#2372 minted that field, whose local Dolt storage had since been lost, was protected under plainbd initbut not under the two flags an operator reaches for in a panic. The probe now runs first and unconditionally, and an absentproject_idis allowed through only when there is no local Dolt data directory either, matching the plain-bd initguard.--recreate-missingstill opens it. The signal decision behind both guards is recorded inengdocs/adr/0004-missing-database-guard-signal.md. -
bd init --recreate-missingnow reaches its own opt-in. The existing-data check derived "is this project's database here?" from the Dolt data directory, which exists on every initialized workspace, so the missing-database branch was unreachable and both--recreate-missingopt-ins behind it were dead code. Four surfaces — the flag help,bd help init-safety,docs/recovery/init-safety.md, and the guard's own refusal text — told the operator to runbd init --recreate-missing --prefix <p>; that command exited 1 with a false "already initialized" message and pointed back atbd init --reinit-local, which is the destructive path, leaving the documented recovery circling between two refusals. The check now probes<dolt-data-dir>/<database>/.dolt, the same probe the reinit-path guard uses. -
The missing-database guard probes this project's own database directory (
<dolt-data-dir>/<database>/.dolt) rather than the Dolt data directory that merely contains it. The data directory always exists on an initialized workspace — shared-server mode creates the machine-global one on resolution, and per-project mode creates it at init — so probing it made the guard a no-op in shared-server mode, which is the topology of the 2026-08-11 loss. User-visible wherever the data directory exists but the database is gone. -
The missing-database refusal no longer prints a ready-to-paste
bd init --recreate-missingcommand line. It names the flag and points tobd help init-safety, which keeps the full invocation behind the diagnosis it requires (ADR 0002 Invariant 4). The refusal also fires when the server merely could not be reached, and a stopped server, a wrong port or a wrong data dir all look the same from there; recreating in any of them strands the real data behind an empty namesake. Run without--prefix, the old line also printed--prefixwith no value. The--forceand--reinit-localhelp,bd help init-safetyand the recovery playbook now say that neither flag authorizes recreating a missing server-mode database. -
BEADS_DOLT_POOL_READ_TIMEOUT/dolt.pool-read-timeout(and the write twins) now apply to everybdcommand in server mode. The knobs shipped in #5089, but their env/config ladder ran only for callers ofNewFromConfig*; the CLI's own store open hand-builds its config and goes straight toNew, so everybdcommand kept the built-in 10 s pool deadline whatever the knob said — on a large shared server that is what madebd closeof a bead with dependents die in its recompute withi/o timeoutand no relief valve. The ladder now runs from the constructor every DoltStore open shares — the CLI's store and library callers ofNew/NewFromConfig*;bd serve's HTTP data path builds its own DSN without pool deadlines and is unchanged (#6144). Note for operators of loaded servers: the documented precedence now reachesbd importas well — it used to inherit the 5 m long-read fallback unconditionally because the CLI's knob value was always 0, so aBEADS_DOLT_POOL_READ_TIMEOUTset below that now bounds import too; size the knob for your largest import, or leave it unset for the fallback. -
BEADS_DOLT_MAX_CONNS/dolt.max-connsnow size the pool for ordinarybdcommands in server mode. The pool-size knob (GH#3140) had the same hole as the deadline knobs above: it was read only on theNewFromConfig*path (routed stores,bd doctor, ...), so the CLI's own store open always ran on the built-in 10-connection pool whatever the knob said. It now shares the deadlines' ladder in the constructor every DoltStore open reaches (#7052). -
No-DB commands in a redirected workspace no longer lose the source repo's
dolt_database(be-xil, be-fyt).bd doctor,bootstrap,context,dolt,initandversionskip store init, and the beads dir they select is resolved throughbeads.FindBeadsDir(), which follows a.beads/redirectinternally. The source repo's configured database name was therefore gone before anything could capture it, sobd doctorfell through to the shared target directory's own default database and reportedDolt Schema: wrong database— offering a--fixthat would have repointed the rig at an unrelated rig's store. The redirect source is now captured before that resolution, matching the store-requiring path. -
An explicit
--db,BEADS_DBorBD_DBtarget is no longer shadowed by the ambient repo's redirect-source database (be-fyt).beads.GetRedirectInfo()deliberately resolves from the CWD repo's local.beadsregardless of--db/BEADS_DIR(bd-wayc3), so when the ambient repo itself had an active redirect, the preservation above re-opened the same "wrong database" failure through a narrower door. Preservation is now skipped whenever the caller named an explicit target, asking the same questionselectedNoDBBeadsDirasks so the two cannot drift apart. Note that a--dbvalue naming a database rather than a path is not an explicit directory target: it is consumed only on the store-requiring path, the ambient workspace is still what gets selected, and its source database is still preserved. -
An ambient
BEADS_DOLT_SERVER_PORTnow marks a workspace externally managed — suppressing auto-start — and no longer stops bd reaping its own orphaned server (#5934). SettingBEADS_DOLT_SERVER_PORT(or the legacyBEADS_DOLT_PORT) now makesResolveServerModeclassify a workspace as an externally-managed server, so bd stops trying to own a lifecycle it does not own. The stale-server cleanup path is deliberately carved out of that rule: it keeps resolving the mode without the port var, so bd still reaps a same-repo orphan it started (GH#2430) instead of declining because the environment named a port. Aproxied-serverworkspace is exempt from the new rule entirely — it reaches its server through the proxy, so an ambient port does not describe its lifecycle. -
bdcaps how large the auto-backup destination can grow, instead of growing it forever (#6071).CALL DOLT_BACKUP('sync', ...)only ever adds new chunks to the destination — it never prunes ones that became unreachable on the source (history rewrites, superseded data) — and Dolt exposes no supported way to GC a backup destination in place. Left uncapped, the destination could only grow until disk filled; this is the root cause of the 2026-06-19 outage, where a 1.7GB store produced a 43GB backup directory. Auto-backup now pauses (nothing is deleted) once the destination reachesbackup.size-cap-mb(default 2048MB); set it to0to disable the cap entirely. The pause is no longer stderr-only:bd backup statusand its--jsonoutput now report asize_capobject (enabled,cap_mb,current_bytes,exceeded), so an agent/CI caller relying on--jsonor--quietcan see that auto-backup has stopped instead of reading a reassuring "Last backup" line while nothing further syncs. The remediation advice no longer suggests deleting the backup directory — nothing guarantees a deleted destination is cleanly recreated by the next sync, and the server-side backup remote stays registered against that path; it now points at raisingbackup.size-cap-mbor pointingbackup.git-repoat a different git repository instead — notbd backup init, which configures manualbd backup sync's destination and leaves auto-backup paused. The size-cap check itself runs after both the interval throttle and change detection, so it costs nothing on any path that is not about to sync — an idle workspace never reaches it at all, and a paused destination re-arms the interval throttle on the skip, so it is measured at most once perbackup.intervalrather than on every command.backup.size-warn-interval(default 24h) controls how often the pause is re-announced. Manualbd backup/bd backup syncare not capped. -
bd contextresolves a workspace outside a git repository instead of hard-failing (#4772). The command's own help promises it "does not require the database to be open, making it useful for diagnostics in degraded states", but it exited withcannot determine repository rootwhenever the working directory was not inside a git repo — even with a perfectly valid.beads/present — so consumers usingbd context --jsonas a health probe got a false "unreachable" in healthy non-git scopes.GetRepoContext()finds and boundary-validates.beads/before it asks git for a root, so that one failure means only that git is missing. It now returns a typed*beads.NoRepoRootError, andGetRepoContextAllowingNoGit()selects it witherrors.Asand roots the context at the.beadsparent. Typed rather than by message text on purpose: the SEC-003 unsafe-location rejection embeds the offending path verbatim, so a substring test would let a workspace under a hostile path clear its own security refusal. Every other failure, that one included, propagates untouched.Scoped to the callers that only read config:
bd contexton both routes, and thedomain/fscontext provider — whichbd servealso resolves through, sobd servein a non-git directory with a valid.beads/now proceeds rather than failing at context resolution. Anything that runs git commands still usesGetRepoContext(). The synthesized context roots at the repository containing the.beads/(falling back to its parent when git cannot be asked there either) and decidesis_redirectedpositionally — whether discovery standing in the working directory would have found that.beads/— so--db,BEADS_DB/BD_DBand-Care reported the same wayBEADS_DIRis.bd contextalso printscwd repo: git: unavailablerather than silently omitting the one degraded state it exists to report. -
bd comment/bd comments addrefuse an abbreviated id and a reserved word instead of silently resolving one to the wrong issue (#5393).bd comment list <id>, a typo forbd comments list, used to parse as id="list" with no guard on the id slot — and since no issue is ever literally named "list", the default abbreviation-tolerant resolver would fuzzy-match it against whatever existing bead or wisp id happened to start with "list" and write the rest of the command line there as a comment. Confirmed in production: 15+ automated sessions made this exact typo over two days and all landed on the same unrelated wisp.bd comment's id positional now (a) refuses the four words abd comments <verb>typo is likely to produce —list,add,rm,delete— before any id resolution is attempted, on both the embedded and proxied-server paths, and (b) requires an EXACT id match (bd-a1b2c3d4, nota1b2) rather than the abbreviation-tolerant matching every other command keeps. The refusal message is truthful about which case applies: a reserved word gets a hint towardbd comments; an abbreviation of a REAL issue getsid abbreviations are not accepted on comment writes; use the full id from \bd show `` rather than the generic (and in that case false) "no issue found matching" text a genuine not-found gets. See Working with IDs for the full read/write distinction. The proxied-server comment path was investigated separately and found to already be exact-id-only by construction (its resolution never performed abbreviation matching in the first place) — a regression test now locks that in rather than leaving it undocumented. -
A git hook beads never wrote is no longer reported as installed (#6084).
getHookVersionreturns no error for a readable hook file that carries no beads markers, so a hand-writtenpre-commit— one beads does not own — was printed as✓ installed (version )bybd hooks list, counted as installed bybd info, and reported as no drift bybd config drift. Those surfaces now report such a file as not installed. This is a user-visible change to a scripted contract: in a repository whose hooks beads does not own,bd config driftnow exits 1 (drift detected) where it exited 0, so automation keyed on that exit code should re-check those repositories before upgrading. A hook that callsbd hooks run <hook>still counts as installed even with no beads marker — that is the integration beads prescribes for external hook managers such as lefthook and husky (GH#946) — and it is version-agnostic, so it is never reported outdated and never promptsbd hooks install, which would overwrite the manager's own hook.bd hooks list,bd infoandbd config driftnow use the same predicate asbd doctorfor deciding whether a hook file is a beads hook;bd doctor's own installed/missing check still only tests for file existence and is tracked separately. -
bd doctorno longer flags a.local_versionthat starts withv. The canonical spelling of a Go module version — and the string a build stamped from a Go pseudo-version reports and writes into.local_versionitself — was rejected by the Version Tracking check (Invalid version format), and read as major 0 in version comparisons, because the helpers parsed digits first. They now accept an optional leadingv; versions without it are unchanged (#6152). -
bd serve's blocked-close refusal names the blockers. A409 not_closablefor a live blocker — onissues/{id}:close,issues:batchCloseper-item outcomes,PATCH issues/{id}into a done status, andissues:batchApply— said only "issue is blocked", so an HTTP client could not tell the user what held the close, whilebd closeon the direct and proxied routes printscannot close blocked issue: X is blocked by [Y]. The refusal now carries ablockersextension member ([{id, kind, type}],kindlocalorexternal,typethe blocking edge type when known) and adetailthat opens with the direct route's sentence. The code, the status and theopen_childrendiscriminator are unchanged. The list travels typed end to end: close refusals are now anissueops.BlockedError(still matchingErrCloseBlocked, with a byte-identical message), so the server never parses prose to build the member and a client can rebuild the same typed error. -
The #6716 fan-in stall is fixed on the proxied-server route and the remaining store routes. Two blockers of one dependent taken away at the same time (parallel workers closing both, or a close racing a
bd dep removeor a delete of the other) could leave the dependentis_blocked=1and missing frombd readyuntilbd recompute-blocked(#6716). The post-commit recheck the Dolt store write transactions gained for that issue now also runs on every write the proxied-server (uow/domain-db) route serves, which under--proxied-server— the default topology — isbd close(single and batch),bd update --status,bd dep remove,bd delete,bd batchandbd serve; onRunInTransaction(bd batchdirect,bd cook,bd mol squash/burn, and SDK callers that close or update inside a transaction); and on the wisp close, update and delete writers and the legacy dependency removal behindbd duplicates --merge. Demote-to-wisp moves a row between planes without taking a blocker away and is unchanged. -
An explicit
BEADS_DIRis authoritative during workspace discovery. WhenBEADS_DIRnamed a directory without project files yet (missing, empty, or not initialized), discovery ignored it and walked up from the current directory instead, then reboundBEADS_DIRto whatever ancestor workspace it found.bd initrefused with "already initialized" because of the parent workspace, and data commands such asbd createandbd listread and wrote the parent's store. Discovery now reports no workspace for such aBEADS_DIR, sobd initinitializes the named directory and other commands fail with "no beads database found".bd import/bd setupandbd bootstraptarget the named directory when they create a workspace. Behaviour withBEADS_DIRunset is unchanged. Behaviour change: aBEADS_DIRthat points at a project root rather than its.beadsdirectory (for exampleBEADS_DIR=$repoinstead ofBEADS_DIR=$repo/.beads), or at a.beadsthat does not exist yet, used to work by accident because discovery walked up to the nearest workspace; it now fails with "no beads database found". PointBEADS_DIRat the.beadsdirectory itself. (#6938) -
A proxied workspace's proxy retires when its Dolt backend exits cleanly. The proxy noticed its
dolt sql-serverchild exiting only when the exit status was non-zero. A backend that shut down gracefully (for example on SIGTERM) left the proxy up and adoptable in front of a dead store: with--proxied-server-idle-timeout 0it never went away,bd dolt statuscalled it running, and every command failed untilbd dolt stop. The proxy now retires on any backend exit, as it already did on a crash, so the next bd command (includingbd ping) starts a fresh proxy and backend.bd dolt statusno longer reports a proxy whose managed backend is gone as running: the text says "not serving" and the JSON reportsrunning: false(withproxy_pidstill set), including for a stranded proxy started by an older bd. (#6937) -
bd sqlno longer drops the rows of CTE queries or CALL result sets (#6932). In proxied-server mode,WITH name(cols) AS (...) SELECT ...andWITH RECURSIVE ...queries were misread as writes and printedOK, 0 rows affectedwith no error; they now return their rows. Statements are now classified with the Dolt SQL parser (shared by the proxied and direct paths): reads return rows, plain writes (including CTE-prefixedUPDATE/DELETE) commit and reportrows_affected, and anything that may both write and return rows (CALL,EXPLAIN ANALYZEof a write,RETURNING) or that the parser cannot classify is committed and prints whatever rows it returns, soCALL DOLT_BRANCH(...)-style result sets are rendered instead of discarded. Visible changes for scripts: in direct server mode a multi-statement write, or a single write statement the parser cannot classify, now printsOK/{"status":"ok"}(as proxied mode already did) instead ofOK, N rows affected/{"rows_affected":N}; and--readonlynow refuses statements it cannot parse (for examplePRAGMA) instead of treating them as reads. -
bd typesnow lists exactly the typesbd create --typeaccepts (#6934). The two resolved the type set through different code and could disagree: a server-mode workspace'sbd typesdropped.beads/config.yamltypes.customentries once the database had any custom type, although create accepts them; in proxied modebd config set storage-class.<type>checkedconfig.yamlalone and refused custom types registered in the database; and the built-in system typesmessage,molecule,gateandeventwere never listed. Every mode now composes custom types by one rule (thecustom_typestable, else thetypes.customconfig row, always unioned withconfig.yaml).bd typesgains a "System types" section, andbd types --jsonan additivesystem_typesfield;core_typesandcustom_typesare unchanged. A failure to read the custom types now failsbd types,bd create --graphandbd config set storage-class.*instead of being silently treated as "no custom types". -
bdrefuses a bare tooling sentinel (null,undefined, an empty string) as an issue ID (#6214).jq -rprints the literalnullwhen a selector misses and JS tooling printsundefined, sobd update "$(bd list --json | jq -r '.[0].id')" --status closedarrived at ID resolution as a plain four-character token. Those tokens are a valid partial-ID shape, so they reached the leading-prefix abbreviation branch and resolved to whichever issue's hash began with them — closing an issue the caller never named and exiting 0 with a success line.bd update null,bd comment nulland every other command that resolves an ID now fail before any lookup, because the guard sits in the shared resolver. An ID that merely contains a token (bd-null,null3t0,undefined-behavior) still resolves, and abbreviation matching is otherwise unchanged. The empty string already failed; it now says why. -
Table-rebuild
__temp__intermediates can no longer materialize as tracked tables on@@dolt_transaction_commit=1servers. The ignored-series rebuilds stage every clone-local table through a__temp__<table>rename, but the intermediate names carried nodolt_ignorepattern: against a transaction-commit server eachCREATE TABLE __temp__Xauto-committed a real table at HEAD, and the rename onto the ignored final name left an unstageable__temp__X -> Xhalf indolt_statusthat wedged every later open behind the dirty-table guard (observed in the field as a three-city shared hub wedging twice in one day, each time ending in fleet-wide write refusal and a manual SQL repair).__temp__%now ships in the canonical seeded pattern set — asserted, like the events-journal patterns, before the series that creates the tables — so intermediates are born ignored. The scoped seed commit also gains--skip-empty: under@@dolt_transaction_commit=1the server has already committed the seeded rows at their own transaction boundaries, and the previously unconditionalDOLT_COMMITdied with "nothing to commit", killing the pass on exactly the under-seeded stores the heal targets. Fenced deployments: adding a canonical pattern un-convergesdolt_ignorefor every existing database, so the next write-mode open issues oneINSERT IGNORE INTO dolt_ignore; a hosted or box-fenced wire client that is denied that INSERT fails its open until one privilegedbdopens the store and heals the pattern — self-healing, one privileged open per upgrade (degrading a denied seed to a skip is tracked separately). -
bd ready --parentandbd blocked --parentno longer re-scan the whole parent-child edge relation for every descendant they find. The transitive descendant walk recursed against a materializedparent_edgesCTE that Dolt cannot index through, so its cost was (parent-child rows) × (descendants): 7.5 s for a 483-descendant parent on a 4.6k-edge database, and past the shared-pool read deadline on a busy server. The walk now recurses directly offdependencies/wisp_dependenciesthrough their typed target indexes and returns the same rows in a fraction of the time (#6128). -
bd list --parenton a proxied-server workspace no longer drops a child whose prefix differs from its parent's (#6130). The edge to such a parent is stored independs_on_external—issueops.IsExternalDepTargetroutes every cross-prefix target there — but the descendant walk behind the proxied tree view resolved a parent only through the issue and wisp target columns, so the child and its subtree were missing from the tree and from--watch, while the direct route listed them. The walk now reads all three target columns, as the direct route's--parentfilter does. Nothing listed before can drop out: the added column is read only when the other two are both empty. -
notion.tokenis kept out of the Dolt database (#6676). It was missing from the yaml-only key list that holds the other tracker secrets, sobd config set notion.token— the commandbd notion statusrecommends — wrote it to the database, whose contentsbd dolt pushsends to the remote. It is now written toconfig.yamllikegithub.token,gitlab.tokenand the other tracker secrets, and refused on a git-trackedconfig.yamlwith a pointer toNOTION_TOKEN. A token an older bd already stored in the database is still read, afterconfig.yamland beforeNOTION_TOKEN, so existing setups keep authenticating.bd config unset notion.tokenremoves both copies — theconfig.yamlentry and any row an older bd left in the database — and reports which of them it actually removed; that cleanup covers every yaml-only secret key, not just this one. The database half is best effort and says so: it is skipped only where reaching the row would mean creating a database (the command never creates one), so it still runs for a server-mode or proxied workspace whose database is simply not on local disk, and it is attempted even when theconfig.yamledit fails, so a workspace whose only copy is the stored row still has a remover.bd notion statusnow reports the auth source asdatabase_legacyrather thanconfig_tokenwhile the stored row is the one authenticating, so an affected workspace can identify itself. A token that was already pushed should still be rotated: deleting the row locally does not unpublish it from remotes that already have a copy. -
A server-mode workspace with an empty
.beads/doltis no longer refused as legacy (#5682, #6935). bd creates.beads/dolton use even when the data lives on an external Dolt server, and leaves it empty. When the gitignored.local_versionwitness was missing — after a fresh checkout, or when a provisioner created the empty root beforebd init --server --external— the legacy-upgrade guard refused every command,bd initincluded, as a "legacy Dolt server workspace", and no bd command could repair it. An empty root holds nothing a legacy release could have left, so the guard now admits it:bd initwrites the witness, and an existing workspace in that state re-seeds it on the next command. A pre-1.0 witness, or a.beads/doltthat holds anything, is still refused. -
bd -C dir primenow describes the target workspace instead of the launch directory (#5509).-CresolvesBEADS_DIRbut never changes directory, so prime's cwd-relative surfaces still described wherever the command was launched: the clone-local.beads/PRIME.mdtier, the AGENTS.md/CLAUDE.md divergence reminder, the git upstream/remote probes behind the template's git-authority wording, and the redirect notice. All four now resolve against the-Ctarget, matchingcd dir && bd prime; without-Cthe behavior is byte-for-byte unchanged.Note for
-Cusers: the git-remote probe prime shares with auto-backup (isBackupAutoEnabled) follows the same change, so underbd -C dir <any command>auto-backup enablement and thebd backup statusnote are now decided by the-Ctarget's git remote rather than the launch directory's. That makes the probe agree with the store actually being backed up, but it can flip auto-backup on or off for-Cinvocations whose launch directory and target differ in remote configuration. -
bd show --watchworks under--proxied-server. It was refused withproxy.watch.unsupportedalthough the provider can answer the poll the waybd list --watchalready does, so every proxied workspace — the default transport for managed-local setups — had no way to watch a bead. The proxied route now shares the direct route's loop: render once, re-read every 2s, redraw only when the issue's status orupdated_atchanges, stop cleanly on Ctrl+C/SIGTERM, and require exactly one id. Each poll opens its own short unit of work, so a long watch never pins a transaction, and a poll that fails (the issue was deleted, the backend blipped) keeps the last render without printing, as on the direct route. On both routes a watch whose id cannot be found now exits non-zero instead of 0. -
Generated git hooks accept uutils coreutils
timeoutas a deadline helper (#5541). The managed hook section probestimeoutandgtimeoutwith--versionand accepted only the GNU coreutils banner, so a host whosetimeoutis uutils coreutils (Ubuntu 25.10+, or a distribution configured withuutils-coreutilsin place of GNU) failed the probe and fell through. Where Perl was installed the shim still got a deadline from the Perlalarmarm — which Git for Windows Perl does not guarantee acrossexec— so the missing deadline bit uutils hosts without Perl, which ranbd hooks rununbounded (with the documented warning). The probe now also accepts thetimeout (uutils coreutils)banner; native Windowstimeout.exestays rejected (#5503). The widened probe ships in the generated hook section, which is rewritten only bybd hooks install— hosts that already installed hooks must run it once to pick up the fix. -
bd closenow exits non-zero when any issue in a batch fails to close (#6648). A batch with one refused id used to exit 0 as long as another id closed, so scripts could not tell that part of the batch was left open. The closable ids still close, the refusals are still printed, and a finalError: N of M issues failed to closeline is added; ids that were already closed still count as success. Both the direct and proxied-server routes behave this way for ids the close policy or the engine refuses. (An id that cannot be resolved at all is unchanged and still differs by route: the direct route aborts the whole command before any close runs, while the proxied route refuses that argument and closes the rest.) In--jsonmode the summary is instead a compact JSON line on stderr naming the failed ids, matchingbd update's partial-failure report, while stdout keeps the usual closed-issues array. Eachfailed[]entry carries the refusal as the engine worded it, identically on both routes; the--forcehint and the route's own framing stay on the human-readable stderr line, which is unchanged.--claim-nextstill claims when part of the batch closed — the claim commits inside the batch's own transaction and a sibling's refusal does not roll it back — so the summary names the claimed id rather than leaving it silently assigned. -
Unblocking two blockers of one dependent at the same time — closing both, or a close racing a
bd dep removeor a delete of the other — no longer leaves the dependent stuck as blocked and hidden frombd readyuntilbd recompute-blocked: a write that takes a blocker away (a close, an update to an inactive status, a dependency removal, a delete) and runs through a Dolt store write transaction now rechecks the dependents it recomputed once that transaction has committed (#6716). The proxied-server route and the remaining store routes are covered by the entry above. -
bd list --watch --formatis refused instead of silently dropping the format (#6277).--watchalways re-renders the pretty listing, so on the direct route a--formattemplate was ignored without a word, while--proxied-serveralready refused the combination. Both routes now fail with the same--format cannot be combined with --watchusage error. -
Explicit
bd update --claimand directbd closenow enforce unsatisfied external capability dependencies. Mixed close batches still commit eligible items together, and--claim-nextskips externally blocked work even when--forceoverrides the close guard. -
The smart migrate gate no longer auto-migrates a clone whose data is behind the remote, and
bd dolt pullnow works from that state (#6575). The gate's first-mover verdict was computed from schema facts alone, so a clone level with the remote on schema but behind it in unpulled data commits was classified a safe first-mover and migrated in place — minting local-only schema commits on a history missing those commits, which can leave every laterbd dolt pullrefusing to merge (#6368). The equal-version path now reads the branch position its callers already supply and stops with a pull-first remedy instead.The stop applies whenever the clone has commits left to pull, whether or not it also has local commits of its own. Since bd auto-commits every write, a clone that is both behind and ahead is the ordinary multi-machine state and reaches the same wedge; it is told its pull will merge rather than fast-forward, and how to resolve conflicts if it reports them. A clone that is level, or that only has unpushed local commits with nothing to pull, still auto-migrates exactly as before.
Crucially, the refusal no longer blocks its own remedy.
bd dolt pullopens the store too, so on a refused clone it used to hit the very refusal that prescribed it — and an embedded workspace has no externaldoltbinary to fall back to, which leftBD_ALLOW_REMOTE_MIGRATE=1(performing the migration the stop exists to prevent) as the only way forward.bd dolt pullnow opens leniently for this one refusal, the waybd dolt commitdoes for the dirty-working-set refusal (#4566); every other gate refusal still fails that open. This supersedes the 1.3.0 upgrade note's statement that the pending-migration gate refusesbd dolt pull: for the data-behind stop it does not, by design. Re-run the command you were blocked on once the pull completes and the migration proceeds.Commands that keep working through the stop say the same thing.
bd list,bd readyandbd showsucceed against the old schema, andbd dolt commitstill commits the working set; on embedded storage all of them used to print the blunt migrate-or-adopt coordination bullets while doing so — namingbd migrate --force && bd dolt push, which on a data-behind clone applies the migration this stop exists to prevent and then fails the push non-fast-forward, andbd bootstrap, which no-ops against an existing workspace. They now print the pull-first guidance, shape-branched the same way the fatal refusal is, alongside the note that the command in hand continued at the current schema. Refusals that are not the data-behind stop keep the coordination bullets, which are right for them.--jsoncallers get the same remedy the terminal does:observed,expectedandoptionsdescribe the pull (a singlepull-firstoption) rather than the migrate-or-adopt decision that does not apply here, plus adata_behind_shapeoffast-forwardordiverged. For the fast-forward shape on a non-shared store — one unconditional option, no local commits, nothing discarded —human_decision_requiredis nowfalse, so an agent can run the pull instead of stalling for approval of a step the same payload calls riskless. It staystruefor the diverged shape (the pull merges and can need conflict resolution) and on a shared store (the follow-up consent step needs an operator who can confirm every co-resident client is upgraded). On a shared Dolt sql-server the guidance still carries #5920's consequence — migrating promotes the schema for every co-resident client — and names the consent step the retry needs there:bd migrate schema --force. It is the forced form because this stop always has a remote configured (behind-ness is read from the remote-tracking ref), and the barebd migrate schemaconsent is only read for a shared database with no remote; the flag consents to migrating a remote-backed shared store, and by then the pull has landed the commits the clone was missing. The payload'sdocslink points at the data-behind section rather than the migrate-or-adopt recipe, and that section — plus the upgrade and init-safety ordering rules — now records thebd dolt pullexception instead of stating the pull is always refused.Both existing escape hatches are unchanged:
bd migrate --force/BD_ALLOW_REMOTE_MIGRATE=1are still consulted before the smart gate, andBD_SMART_GATE=0still yields the blunt gate unconditionally (including forbd dolt pull, which is what opting out means). Pulling before the first open after upgrading avoids the state entirely. -
A
--formattyped onbd listnow beats ajson: trueconfig default (#6278). Withjson: trueinconfig.yaml(or the environment),bd list --format digraph,dotor a template printed the JSON listing instead, becausebd list's own--formatflag shadows the root one the config-precedence check looks at. A typed--formatnow wins over the config default; an explicit--jsonstill wins over--format. -
Strict readonly no longer records last-touched state (#5785). Under strict readonly (
--readonly, orreadonlyin config),bd showwrote the issue id to.beads/last-touchedeven though readonly promises not to mutate workspace-local state — the database store was opened read-only while this marker file was still written.SetLastTouchedIDnow returns early in that mode, so a readonly workspace leaves the marker untouched. Ordinary (non-readonly)bd showkeeps recording last-touched exactly as before, so only consumers drivingbd --readonly … --jsonsee the change. -
Markdown bodies now honor the terminal's actual background instead of always rendering dark (#5776).
glamour.WithEnvironmentConfig()defaults tostyles.DarkStylewheneverGLAMOUR_STYLEis unset, with no regard for the terminal's real background — unlikeinternal/ui's own adaptive colors, which probe it vialipgloss.HasDarkBackground. That left every markdown body's colors wrong on a light-background terminal even though the section header wrapping it adapted correctly. The fix lands at the shared renderer, so it covers every markdown bodybdprints — DESCRIPTION, DESIGN, NOTES, ACCEPTANCE CRITERIA, and comment bodies, direct and proxied alike — not justbd show's DESCRIPTION field. An explicitGLAMOUR_STYLEoverride still takes priority over the detected background.
Added
-
POST /v0/beads/issues:batchApplyaccepts up to 1000 items, up from 100.issueops.MaxApplyBatchItemsmoves from 100 to 1000; the request body cap rises from 4 MiB to 16 MiB (maxApplyBatchBodyBytes); and the whole plan still applies in exactly ONE transaction — the cap raise never chunks a request. A request over 100 items now runs under a separate, EXTENDED whole-run budget instead of the ordinary 60s request deadline: a newbd serve --large-apply-ceilingflag sets it (5 minutes by default), applied flat regardless of item count, never scaled down. A request at or under 100 items is completely unaffected and keeps exactly the 60s deadline it has always had. A request over 100 items also serializes against every other such request through a dedicated one-wide semaphore, so at most one oversized write transaction is in flight at a time; the wait for that semaphore is itself bounded, so a burst of oversized requests is shed with503rather than queuing indefinitely and starving ordinary traffic. An ordinary (<=100-item) request is never made to wait on it. Graceful shutdown waits out an in-flight large apply up to its own deadline, but refuses any large apply still queued for the semaphore once shutdown begins, rather than extending the drain further.bd serve's orchestrator stop grace must be at least--large-apply-ceilingplus 5 seconds, or an externalSIGKILLcan still cut off an in-flight large apply the drain would otherwise have waited out; seeengdocs/SERVE_RUNBOOK.md. A newissues.batchApplyLargecapability token onGET /v0/beads/contextlets a client learn whether a given server accepts the raised envelope before sending a plan over the old 100-item bound. Measured wall-clock for the whole-transaction apply (embedded Dolt, build+commit only) backs the 5-minute default: a 356-item plan (the design doc's primary measured shape) commits in ~12.6s (23.8x headroom under the ceiling), and a 1000-item plan (the new cap) commits in ~57.5s (5.2x headroom). -
A long-running schema migration now says so instead of going quiet (#5997). Migrations are allowed to take a long time by design — migration 0047's full-table
is_blockedrecompute is a real example — but until now a slow one and a wedged one looked identical from outside:bdsimply stopped printing. A watchdog now emits a WARN naming the migration's version, name, and elapsed time once the migration's own SQL has been running past the interval, and repeats every interval while it keeps running, so an operator reading logs can tell "still working" from "stopped emitting anything". Coverage is the migration body specifically — the per-step Dolt commit that follows it on the production embedded path is outside the watchdog, so a stall there is still quiet. SetBEADS_MIGRATION_WATCHDOG_INTERVALto change the 5-minute default; it accepts durations like10mand bare seconds like90, and falls back to the default when unset or unparsable. This is observability only and never a circuit breaker: the migration receives the caller's exact context, its error is passed through unchanged, and nothing is aborted or rolled back. The warning is deliberately not terminal-gated, so it survivesbd serve, systemd, CI, and piped invocations. -
Auto-backup runs on a managed-local proxied-server workspace. The proxied arm of the post-command hook now calls auto-backup, so an explicit
backup.enabled=true(orBD_BACKUP_ENABLED=1) takes the same throttled, change-detected Dolt-native backup into.beads/backupit takes in direct mode, through the proxied provider's non-transactional seam. Before this the opt-in was inert on every proxied workspace andbd backup statussaid so. The default stays OFF, as on every server-mode workspace: many bd clients share one server. It is honored exactly wherebd backup syncis — a proxied server bd started itself — and stays inert on an external or team-server topology, strict--readonly,bd serve, a preview (--dry-run/--inspect) and a migration freeze. A command that opened no provider (e.g.bd dolt stop) backs nothing up rather than relaunching the server to do so.bd backup statusnow reports the proxied default asauto: off in proxied-server mode; set backup.enabled=true to opt in. -
Auto-backup and
bd backup syncno longer overlap. A per-workspace backup lock (.beads/backup.lock) serializes them in every mode: auto-backup skips when another backup holds it, andbd backup syncwaits up to 5 seconds (the bound restore uses for the workspace gate) and then fails with "another backup is running for this workspace". -
bd purgecovers an orchestrator's wisp retention sweep. Three changes that together letbd purge --wisps-plane --older-than 168h --forcereplace a rawDELETE FROM wispsretention step:- Live-dependent protection, always on.
bd purgeno longer deletes a closed bead that a live bead depends on through aparent-child,tracksorblocksedge — a closed molecule root whose step is still open, a closed wisp a live convoy tracks, a closed blocker of live work. "Live" is any status that is not done, including custom statuses. The held-back count is reported aslive_dependent_skippedin--json(and on its own line in text output). The protection is on the role (issueops.SweepRequest.ProtectLiveDependents);bd prunedoes not ask for it. --wisps-planeselects every closed row stored in the wisps table, including--no-historybeads, which the default ephemeral selection leaves tobd prune. It works on embedded, server and proxied workspaces, and because it reaches durable-tier rows it requires--older-thanor--pattern, likebd prune(issueops.SweepWispsPlane).--older-thanaccepts hour and finer durations (36h,168h,90m, down to1s) on bothbd purgeandbd prune. Day values (7,7d,2w) are unchanged. AnNhvalue used to be converted to whole days: floored above a day (36hswept rows only 24 hours old) and rounded UP to one day below it (12hkept everything younger than 24 hours). Both are now taken exactly, sobd prune --older-than 12hnow deletes rows closed 12–24 hours ago that it used to keep. A value too large to represent (e.g.213504d) is now refused instead of silently wrapping to a tiny age.--limit Ncaps onebd purgerun at N beads, oldest-closed first (issueops.SweepRequest.Limit), so a large backlog drains in bounded transactions;--jsonthen addsremainingandhas_more. Loop whilehas_moreis true.
- Live-dependent protection, always on.
-
bd backupworks on a proxied-server workspace bd runs the Dolt server for.bd backup init,sync,remove,statusandrestoreare routed over the proxied provider; before this, a proxied workspace — the default topology since 1.3.0 — had no backup path at all.bd backup restorestops the proxy and its Dolt child before replacing the database and leaves the workspace quiescent, so the next command relaunches against the restored data.The family stays refused by design on a proxied workspace pointed at a Dolt server bd does not own (an external host, socket, or a beads-team-server database):
CALL DOLT_BACKUP('add', …)registers the backup remote on the server, where it is global to every client connected to it, so one workspace's backup decision would silently become everyone's — the shapebd backup's own help text already warns about for auto-backup. Afile://destination has a second problem on top, since the server resolves that path on its own filesystem. The refusal keeps theproxy.backup.unsupportedcode and now carries"reason": "design"; a backup story for those deployments belongs to whoever runs the server. Whether a remote-scheme destination (DoltHub,aws://,gs://) should eventually be allowed there is recorded as an open question rather than settled — the server pushes those over the network from its own environment, which is the same credential question the next slice has to answer fordolt push.Backups on this topology are explicit only. Auto-backup has no post-command hook on the proxied path, so
backup.enabled=truedoes nothing there;bd backup statusandbd backuphelp now say so instead of attributing the OFF to a missing git remote, which was never the reason on a server topology. Wiring an auto-backup hook through the new routes is left to a later slice. -
bdsays when it resolved a partial ID instead of matching one exactly. (#6302) ID resolution tries an exact match first and only then falls back to leading-prefix abbreviation (a3f8->a3f8e9). Ambiguity was already a hard error naming every candidate, but a sole abbreviation match was returned silently, so a caller could act on an issue it had not named without any signal. bd now writes a one-line note to stderr identifying both the input and what it resolved to. The case that motivates it: a hierarchical child is a valid leading-prefix match for its own parent's ID, so after a parent is renamed or deleted the vacated ID quietly resolves to the child. Note this covers every leading-prefix abbreviation, not only that shape, so the ordinary documenteda3f8->bd-a3f8e9path now emits a line too, once per resolved argument. That breadth is deliberate: a.-boundary rule would fix parent/child but leavebd-x.1->bd-x.11just as silent. stdout and--jsonare unchanged; silence it with--quietorBD_NO_PARTIAL_ID_NOTICE=1. -
bd countaccepts--has-metadata-key(#6160), closing the last metadata-filter gap againstbd list,bd readyandbd search. A caller counting rows that merely carry a key no longer has to list them and measure the page. -
bd countsupports repeatable--metadata-field key=valuefilters (#6023), so callers can count the same metadata-scoped setbd listreturns without fetching every row. -
bd label rename <old> <new>fixes a label everywhere it appears, in one command instead of a per-issue add-then-remove loop (#6009). An issue that already carries the new label doesn't error — the rename drops its stale old label and counts the issue as a merge instead, reported honestly:Renamed label 'Backend' to 'backend': 6 issues (2 already had 'backend'). A label nothing carries is a clean no-op (No issues found with label 'Backend', exit 0). The sweep covers both planes, durable issues and wisps, and the direct and proxied-server routes end at the sameissueops.RenameLabelInTxprimitive — the proxied route journals throughdomain.LabelUseCase.RenameLabelrather than a per-issue add+remove fan-out, so merge semantics, the zero-carrier no-op, and the singlelabel_renamedevent per touched row are identical on both.--dry-runpreviews the blast radius (a count and the first 10 issues, all of them under--json) without writing anything, through a read-only path kept apart from the write path so a preview can never reach a transaction. Itsmergedcount is a plain snapshot intersection of two independent reads, though, not the write path's measured one: the real rename derivesmergedfrom what itsINSERT IGNOREactually affected, specifically so a concurrent label add between two reads can't skew the count, and the preview has no insert to measure against. Treat the dry-run number as an estimate — the flag's own help text says so now too. A rename that fails partway through reports an UPPER BOUND - up to how many issues may have been renamed, and up to how many of those were merges - rather than only the error. It cannot be a landed count: both routes assign those numbers inside the transaction, so a rollback or an exhausted retry returns them still describing an attempt that landed nothing. Only a Dolt publication failure after the SQL side already committed is a genuine partial, and the count alone cannot tell the two apart. -
bd label remove --prefixremoves every label matching a prefix in one call, instead of requiring an exact label name per removal.bd list/bd readyalready supported--label-pattern/--label-regexfor finding issues by label shape;label removehad no equivalent for stripping a whole label family (e.g. everypool:refused:*reason label) — callers had to fetch the labels themselves and issue onelabel removeper exact name.--prefixresolves the matching labels per issue and removes that issue's whole matching set in a single edit;bd label remove <id> --prefix pool:refused:replaces that fetch-then-loop. Routed through the sameissueops.Lifecycle/issueops.Readerroles as a plainlabel remove, so it works identically on the embedded and proxied-server (bd serve) storage modes. -
PATCH /v0/beads/issues/{id}acceptsclaim: true, the wire spelling ofbd update <id> --claim. It passes through to the same lifecycle role the direct route uses (issueops.UpdateRequest.Claim), so the claim and the patch land in one transaction with the direct route's semantics: a same-actor re-claim is idempotent (changed: false), a foreign holder is 409already_claimedand an unclaimable status 409not_claimable— both namingclaimand carrying{id}:claim'sassignee/issue_statusmembers — and a refused claim writes none of the patch. Withclaim: truethepatchmay be empty.claimbesideexpected_assignee,expected_statusorforce_assignee_transferis a 400. A server that predates the member refuses it asunknown_parameterbefore any database work, so an HTTP client can forwardbd update --claiminstead of refusing it, and can never mistake an older server for one that dropped the claim.
Fixed
-
bd showcounts a wisp's comments instead of reportingcomment_count: 0(#5565). On the direct/embedded path,CountIssueCommentsalways queried the permanentcommentstable, whileGetIssueCommentsroutes an active wisp towisp_comments, so--include-commentsreturned rows the count said did not exist andcomments_omittedwas never set. The count now routes by wisp status the same way, matching proxied-server mode. -
bd dolt startno longer puts a second sql-server over a proxied workspace's data directory. On a proxied-server workspace the default root IS.beads/dolt, andbd dolt startknew nothing about proxied mode: with the proxy quiesced it launched an unsuperviseddolt sql-serverdirectly over that root, after which ordinary bd commands failed (invalid connection) because the relaunched proxy found a foreign server on its port; with the proxy live it instead adopted the proxy's own dolt child into bd's classic PID/port records, leaving two managers for one process. It is now a typed refusal with codeproxy.dolt_start.conflict. The proxy owns its backend's lifecycle — it starts on demand andbd dolt stopshuts it down. Direct-server and embedded workspaces are unaffected. -
bd infohonorsdoctor.suppress.git-hooks(#6027).bd infoprinted the "Git hooks not installed" / "outdated" warning unconditionally, so suppressing the check forbd doctorleft it nagging on everybd info. It now reads the samedoctor.suppress.*config through the doctor helper and skips the warning whengit-hooksis suppressed.bd info --jsonnever carried the warning and is unchanged. -
bd dolt statustells the truth on a proxied workspace. It read the classic PID file, which proxied mode never writes, and so reportedDolt server: not runningwhile the proxy was serving CRUD — the wrong answer that sent operators tobd dolt startin the first place. It now reads the proxy's own records and reports the proxy and its dolt backend separately, without starting either. JSON output shape change: on a proxied workspacebd dolt status --jsonnow emits{"mode": "proxied-server", "root": ..., "running": <proxy up>, "proxy_pid": ..., "proxy_port": ..., "backend_managed": ..., "backend_running": ..., "backend_pid": ..., "backend_port": ..., "idle_timeout": ...}instead of the always-false{"running": false, "pid": 0, "port": 0}.runningdescribes the proxy, the endpoint every bd command connects through;backend_managedis false on external proxied topologies, where the dolt server is not bd's process to report on. -
bd create --metadataandbd update --metadatanow require a JSON object (#6035). Both checked only that the value was valid JSON, sobd create --metadata '"oops"'stored a bare string (or an array or number) as the issue's metadata, whilebd updaterefused the same value only late, in the storage merge, with an internal unmarshal error. A shared check now refuses a string, number, boolean, array ornullup front on every create and update path withinvalid --metadata: must be a JSON object;{}is still accepted.nullis the one value update handled differently before: the storage merge accepted it as a no-op and exited 0, sobd update --metadata nullnow exits 1 where it used to silently change nothing. Values inside the object stay opaque, so a string value that looks like JSON is kept as written. -
bd mol ready --gatedno longer refuses under--proxied-serverwhenBEADS_MAX_ROWSis set (#6293). The proxied capability front door keyed its rules on cobra's leaf name, andbd readyandbd mol ready --gatedshare the leaf "ready", so the row cap refusal written for the former also refused the latter — a proxy-supported command with no--max-rowsflag to refuse. Rules are keyed on the full command path now. -
bd initno longer tells you not to runbd initwhen it refuses a foreign database (#5558). Whenbd initopens a server database that already exists and belongs to a different project — for example when--server-host/--server-port/--databasepoint it somewhere other than this workspace's own server — it correctly refuses withPROJECT IDENTITY MISMATCH, but the refusal was the one written for ordinary opens, ending in "Do NOT run 'bd init'". The init-time refusal now names the database and points at remedies that work from there: pointbd initat this project's server (--server-host/--server-port) or an unused database name (--database), or runbd doctor --fix/bd bootstrapifmetadata.jsonis the stale side. Onlybd init's own open gets this wording; every other open, including the library API,bd doctor --fixandbd bootstrap, keeps the existing message.
Changed
-
The managed shared Dolt server now opens its configured remotesapi listener (#6020).
dolt.remotesapi-port(machine-global user config) andBEADS_DOLT_REMOTESAPI_PORTnow reach the launcheddolt sql-server(as--remotesapi-portin flag mode,remotesapi.portin generated-YAML mode), anddoltserver.Restartapplies a listener change under one lifecycle lock. Zero (the shared-mode default) still means no listener.This changes the meaning of a pre-existing knob:
BEADS_DOLT_REMOTESAPI_PORTpreviously only informed federation doctor checks; a managed server launched with it set now actually opens that listener. A server still running from before the setting appeared refusesbd dolt startwith abd dolt stop && bd dolt startremedy, while auto-start keeps serving SQL and prints a warning until the server is restarted.Security caveat: Dolt binds the remotesapi listener on all interfaces and serves it unauthenticated, unlike the managed 127.0.0.1 SQL listener. Only enable it where a firewall, private interface, or tunnel bounds who can reach the port.
-
bd mol pourandbd mol wispnow reject a--varname the proto cannot consume, instead of dropping it silently. An unusable name was accepted and ignored, which turned a typo in an optional var into a conditional step that quietly never appeared, or a defaulted var that quietly kept its default - with a successful exit and no output to suggest otherwise. A name is accepted if any proto being poured declares it, references it as a{{handlebar}}in any field the pour substitutes - the prose fields,assignee,labels, a gate'sawait_id, and every string value in its metadata - references it from a stepconditionor from a step thatconditionremoved, or uses it as a{name}placeholder that a standalonetype = "expansion"formula substitutes as it builds its steps from[[template]]. The last three matter because the condition filter and the[[template]]expansion both run before the cook, and nothing in the cooked subgraph records the names they consume or drop; collecting them ahead of the filter also keeps a name's validity a property of the formula rather than of another var's value. Anything left over cannot affect the pour, so it is reported:unknown variables: has_spke (available: has_spike, story). A var belonging to an--attachproto still passes, as do a proto's documentation handlebars. The refusal applies only where the declared-var set is fully known, which means a proto cooked from a formula: a proto loaded from the database (bd cook --persistoutput, and every--attachproto) no longer has its[vars]declarations, so a declared-but-unreferenced name is indistinguishable from a typo and nothing is refused for that pour rather than risk breaking one that works. Out of scope for now:bd mol bond --varandbd mol seed --vargo throughformula.ValidateProvidedVars, which only iterates declared vars, so they still drop an unknown name silently. Also fixed alongside: the missing-var hint printed--var =<value>when there was no missing var to name. -
A formula with a
waits_forgate and no spawner to wait for is now rejected, and an invalid formula is no longer reported as not found. A gate step infers its spawner fromneeds[0], so with nothing to infer from, cooking stamped thegate:<value>label and emitted no dependency edge at all - a gate bead that never blocks and never resolves.bd createalready refused--waits-for-gatewithout--waits-for; the formula path was the outlier.Formula.Validatenow enforces the same rule. Separately, a validation failure is distinguishable from "this name is not a formula": callers that fall back to a proto/issue lookup previously swallowed the real error and reportednot found as issue or formula, so an invalid formula looked like a typo.bd mol bond --dry-runalso resolves throughparser.Resolvenow, so it resolves and validates the same way the real bond does rather than previewing a bond that then errors on those checks. Later cook transforms (inline expansions, expansions, aspects and condition filtering) are still only exercised by the real bond. -
bd primedescribes the memory split instead of prohibitingMEMORY.md(#6111, refs #5169). The guidance line used to readDo NOT use MEMORY.md files — they fragment across accounts. That warning predates harnesses that ship a first-party, machine-local memory whose index file is also namedMEMORY.md, so in a workspace running both, prime told the agent every session not to use a file the harness was actively maintaining. The line now says what each store is for: durable project facts go inbd remember, because per-tool memory files fragment across accounts; per-operator preferences stay in the harness's own memory. Output text only, no behaviour change. The same sentence is updated in its sibling renderings — the MCP/minimal context, the generated AGENTS.md sections for the minimal and Codex harness templates, and the README snippet — sobd initand copy-paste do not re-introduce the prohibition. -
BREAKING: unforced
bd update --notesover existing notes is now refused, not warned (#5946). Replacing existing non-empty notes with different non-empty content — the blind clobber that destroys another agent's handoff notes — previously printed a warning after succeeding; it now writes nothing and exits 1. The same fence turnsPATCH /v0/beads/issues/{id}andbatch:applyfrom 200 into 409notes_overwrite_refusedwhenpatch.noteswould do the same, on both backends and both batch legs. Migration: pass--force(CLI) orforce_notes_overwrite(API) to overwrite deliberately — the CLI then prints the old warning as an audit trail — or preserve history with--append-notes/bd note.Two edges are deliberate. An explicit clear is never fenced behind
--force:--notes ""(or an API patch to the empty string) does not trip this refusal, because every sibling text field clears the same way, the pattern the fence exists to stop is an agent writing its own content over someone else's, and the refusal's advice — force, or append — is meaningless for a clear. (The CLI gives the clear its own verb,--clear-notes— see the next entry — but never gates it behind--force.) And--forceis no longer mutually exclusive with--if-assignee, since a guarded notes overwrite has to be able to say both. This widens what--forcereaches under the guard: its assignee half stays suppressed (a transfer under--if-assigneeauthorizes only through the matching CAS, never the force bypass), but its close-policy half — closing despite open children or a live blocker — now applies there too, a combination the CLI previously rejected outright.bd editis unaffected: it pre-fills the editor with the current notes, a sighted edit rather than a blind clobber. -
bd mol bond --refno longer deadlocks the molecule it bonds into, and no longer accepts--type conditional. A--refarm is nested inside its target and its hierarchical ID records that, so an ordering edge onto the target was unsatisfiable in both directions: the arm waited for the molecule to close, and the molecule could not close while it held an open arm.bd readywent empty with nothing to point at. For a sequential bond (the default) that edge is now dropped, so the arm carries no ordering and is ready as soon as it is spawned - containment is a nested arm's only satisfiable relationship to its container. A conditional edge has no such degradation: it means "run only if the target fails", so dropping it would run the arm unconditionally, turning a deadlock into a silent false dispatch.--refwith--type conditionalis therefore refused outright (including under--dry-runand on the proxied route); omit--refto bond a conditional arm as a sibling, which is satisfiable and keeps its edge. -
bd mol ready --gatedprints a dispatch command that exists. The hint namedbd sling, which has never been a command in this binary, so the one actionable line in the output could not be run. It now printsbd assign <ready-step-id> <agent>, and says which listed molecule the example belongs to when more than one is waiting. -
bd purgekeeps closed beads a live bead depends on. A closed bead that a not-done bead depends on throughparent-child,tracksorblocksis no longer purged (reported aslive_dependent_skipped), so a purge that used to delete a closed molecule root under a live step now leaves it. See the--wisps-planeentry under Added. -
bd statusnow discloses the counted rows a defaultbd listwill not show.Total Issuescounts the database;bd listshows a filtered view of it, and the two disagreed silently — an operator reconciling a total against a listing found rows they could not account for. A new line names the breakdown and the flags that reveal each part:Not shown by bd list: 2 gates (--include-gates --all), 1 template (--include-templates --all), omitted entirely when there is nothing to disclose. The counts describe the database, every status included, which is why the remedy names--allbeside the type flag: the default listing hides closed rows independently of what a row is, so a closed gate is counted here and the type flag alone would not show it.gate_issuesandtemplate_issuesjoin the--jsonpayload and the OpenAPIStatisticsschema, additively; they are broken out ofTotalIssuesrather than removed from it, so the buckets still do not sum to the total in either direction.bd status --assignedgets the same breakdown, which it needs for the same reason againstbd list --assignee. Not yet covered: durable rows carrying a configured infra type (GH#6439), which need the workspace'stypes.infraset that the portable count has no seam to read. -
Proxied-server refusals now say why they refuse. The JSON a refused command prints gains a
reasonfield next to the existingcode,errorandmutates:designfor a refusal that is expected to stay (shared history, multi-repo routing, destructive admin, strict--readonly) andunimplementedfor a capability gap with a named owner. Addingreasonleft every existing code, message and exit status as it was, andreasonis absent on refusals that report a runtime state rather than a policy, so existing consumers are unaffected. The policy behind it moved into one registry (cmd/bd/capability_registry.go) that every command must appear in. -
A command with no proxied-server route now fails with a typed error (
proxy.store.unrouted) instead of the bare stringproxy server store should be uow provider. -
bd backup restore --jsonprints a result object on every topology ({"restored": true, "source": "<dir>"}). It previously printed nothing at all, which left a caller unable to tell a completed restore from a silently skipped one. This applies to direct/embedded workspaces too, not only proxied ones. -
bd backup init,sync,removeandrestoreno longer print a usage block after a failure. They now silence cobra's own error and usage rendering like the rest of the CLI, so a failure is one error line on stderr instead of the message followed byError: exit code 1and the full usage text. Exit statuses are unchanged; this applies on every topology. -
bd label removeandbd label addno longer claim a no-op edit (#5988). Removing a label the issue never had printed✓ Removed label 'x' from <id>, and adding one it already had printed✓ Added label, so a real edit could not be told from a no-op. Such a label is now reported as• Label 'x' was not on <id>/• <id> already has label 'x', with JSON statusunchangedinstead ofremoved/added; a multi-label edit reports each label by what actually happened to it. The exit code is still 0, so idempotent callers are unaffected. -
Proxied
--repoand row-cap refusals are typed again (#6293).bd create --repounder--proxied-serveranswers--jsonwith the stable{"code": "proxy.repo.unsupported", …, "mutates": false}on stdout rather than prose on stderr, andbd ready --claim --max-rows Nrefuses with the sameproxy.max_rows.unsupportedshape asbd ready --max-rows N:--claimdoes not exempt a row cap the proxied route cannot enforce either way.bd createis the only command that registers--repo, so it is the only command this refusal applies to. -
bd ready --gatedruns under--proxied-serverwith a row cap set (#6697). It was refused whenever--max-rowsorBEADS_MAX_ROWSresolved to a positive cap, whilebd mol ready --gated— the documented alias for the same gate-resume scan — was not, so one command line behaved differently under its two spellings. The gated arm lists molecules whose gate closed rather than ready rows and threads no cap on either route, so it no longer consults one; a cap passed alongside--gatedis ignored, matching what the direct route has always done. Every otherbd readyarm still refuses an active cap,--claimincluded. -
The proxied
bd admin compactrefusal names the command it means (#6293). The message is now "only 'bd admin compact --dolt' is supported in proxied-server mode"; it read "only 'compact --dolt'", which names the rootbd compact— a different command, with no--doltflag and its own proxied route. Scripts matching the old text need updating. -
bd queryno longer silently stops at 50 rows when its output is piped (#6229).bd listhas treated piped stdout as unlimited since GH#4094, butbd queryread its--limitdefault of 50 straight through, sobd query '...' | consumerdropped every row past 50 with no hint. An unflaggedbd querynow resolves through the same policy asbd list: an explicit--limitwins, piped stdout is unlimited, agent mode on a terminal gets 20, and a terminal gets 50. -
bd preflighthonors thejsonconfig default (#6293).json: truein the config file selects JSON output forbd preflight, as it already did elsewhere; previously only the explicit flag was honored. -
BREAKING:
bd update --notes ""is now refused; clear with--clear-notes(#6021). An empty--notespreviously wiped the whole notes field at exit 0 behind the same✓ Updatedreceipt as a successful write — and the empty string is exactly what a dead command substitution (--notes "$(cat missing.txt)") collapses to, the accident behind every recorded loss in the report. At the flag layer the accident and the deliberate clear are the same bytes, so the empty value is refused unconditionally (exit 1, naming the alternative) and the deliberate clear gets its own verb:bd update <id> --clear-notes, mutually exclusive with--notesand--append-notes. A verb rather than an--allow-empty-notesopt-in because what needs authorizing is an intent, not an input path — the description guard's--allow-empty-descriptionunblocks stdin/file plumbing, which notes does not have — and because an opt-in passed habitually would silently disarm the guard, while a habitual--clear-notesfails loudly on the next real update.--forcedoes not bypass the refusal (the overwrite fence answers a different question),--append-notes ""remains a safe no-op, and the HTTP API is unchanged:patch.notes: ""still clears — a JSON payload is a deliberate construction, not a shell substitution. -
--noteshelp no longer reads as additive (#6272).bd update --helpdescribed--notesas "Additional notes" and thebd primetext said "Add supplementary notes" — both read as appending, so agents following the injected guidance faithfully clobbered prior context. The update help now names the operation ("Replace the notes field …") with the--append-notescontrast at the point of use, and the base/create help is field-named like--descriptionand--design, implying no merge behavior. -
bd gate checkresolves bead gates whose target lives in a prefix-routed rig (#5859). After a local miss, the evaluator follows the target bead ID throughroutes.jsonland reads the owning store without writing to it. This covers explicit gate checks in embedded, server, and proxied-server command paths; the legacy<rig>:<bead-id>await value remains accepted for compatibility.
Fixed
-
routes.jsonlprefixes containing a hyphen now route (#5048). Prefix routing cut the bead ID at its first-and required an exact match, so a route such asclaude-os-could never matchclaude-os-76land the lookup fell through to "not found". Routing now picks the longest route prefix the ID starts with. Single-hyphen routes behave as before; where bothhq-andhq-cv-are configured,hq-cv-*IDs now take thehq-cv-route instead ofhq-. -
A dotted config key now round-trips: what
bd config setwrites,bd config getand bd's own readers find (#6574, #6594, bd-zj95). Setting a key likesync.remoteordolt.hostinto aconfig.yamlwith no matching section appended a key whose name contained the dot — a top-levelsync.remote: "..."— instead of nesting it undersync:. Viper finds a key spelled that way; the direct readerGetStringFromDirsplits on the dot and walks nested mappings, so it does not. The value was set and invisible at the same time depending on which reader asked, andbd init --remotein a fresh workspace was the ordinary way in: the remote was recorded and then not found. New dotted keys are written nested now. An existing flat spelling is updated in place for compatibility with other writers of the shared config file — rewriting that one line and nothing else, the comment on it included — and bd's direct reader recognizes both forms with the same precedence as Viper.bd doctorwarns when both forms coexist.bd config unsetremoves the nested form — it only ever matched the flat spelling, so unsettingsync.remotesilently left the remote live. Keys the write does not own, including dotted ones somebody else put there, are left exactly as they are.Four things that used to succeed now report an error instead, because each one produced a value no reader could see, or claimed to remove a value it had left live. On
bd config set: a key under a parent that already holds a value (sync: enabled, thenbd config set sync.remote), and a key in a file whose top level is not a mapping. Onbd config unset: a key inside a flow-style mapping (sync: {remote: "..."}), which bd matches by line and so cannot edit, and a key whose value is a block scalar (remote: |, in either spelling), where commenting the key out would leave the body behind as a value of its own. Unsetting a key that is not set remains a successful no-op in every shape. -
A self-hosted GitLab no longer re-creates its own issues on every push (#6735). The tracker decided whether a stored
external_refwas one of its own by looking for the substring "gitlab" in the URL, so an instance whose hostname does not contain it —https://nova.teachx.ai, say — had its own issue and work-item URLs classified as foreign.bd gitlab pushthen took the create-not-update path for issues that were already synced, and pull reconciliation and conflict detection skipped them. Such a URL is now also recognized when its host, and base path for a GitLab served from a sub-path, match the configuredgitlab.url.Recognition only widens: every ref the substring check already claimed is classified exactly as before, so no existing link changes meaning. Two limits are worth knowing. Matching is host-scoped, not project-scoped — with GitLab at the host root, a ref pointing at another project on the same host now counts as this tracker's, as has always been the case for
gitlab.com. And the host is compared literally, sogitlab.urlmust name it the way GitLab spells it in theweb_urls it returns; writing an explicit default port (https://host:443) matches none of them and leaves the old behavior in place.
Changed
-
bd ready --jsonanswers a capped page and its total in one pass, andstorage.Storagegains a requiredGetReadyWorkWithCountsAndTotalmethod (#6731). A full capped page used to trigger a second counting pass in its own transaction, re-running the expired-defer sweep and every wisp/deferred probe; the total now comes fromCOUNT(*) OVER ()on the page's own query inside the same read transaction. Two behaviors improve with it: the--jsontotal honors external-dependency exclusions (the old second pass counted externally blocked issues, so text and--jsoncould report different numbers), and the page and its total now come from one snapshot instead of two, so "Showing N of M" can no longer be internally inconsistent under concurrent writes. One contract change: a total that fails now fails the command, where it previously could not — the total is taken from the page's own query, so the page would have failed anyway.Out-of-tree storage backends must implement the new method to compile. Every in-tree implementer is updated, but
internal/storage/backendsis an extension seam whose registrants are supplied by a downstream distribution and returnstorage.DoltStoragedirectly. A registrant must implementGetReadyWorkWithCountsAndTotal(ctx, types.WorkFilter) ([]*types.IssueWithCounts, int, error): the page identical toGetReadyWorkWithCounts, and the total identical to the numberCountReadyWorkanswers for the same filter (which ignoresLimit), resolved in the page's own read transaction. There is deliberately no optional-interface fallback — a store that cannot size the ready set should fail to compile rather than silently fall back to an unbounded query. -
storage.Storagegains a requiredSearchIssueSummariesmethod (#3458). It is a narrow-projection variant ofSearchIssuesfor list-shaped rendering: it returns[]*types.IssueSummary(exported asbackend.IssueSummary), which carries the list columns, labels, and the four wisp-plane markers but none of the TEXT/JSON columns. Nothing inbdcalls it yet, so no command's output changes. Consumers that only call the interface are unaffected; any external type that implements it (a custom store, mock, or proxy, or aninternal/storage/backendsregistrant) must add the method to compile:SearchIssueSummaries(ctx context.Context, query string, filter types.IssueFilter) ([]*types.IssueSummary, error). It honorsSortBy/SortDescandSkipLabelsexactly asSearchIssuesdoes,IncludeDependenciesis a silent no-op (a summary has nowhere to put dependency records), and wisps are merged in unlessSkipWispsis set, with their markers set so a wisp row stays distinguishable from a durable issue. -
Push
--dry-runnow honors--create-only(#6337). The sequential tracker push previewed "Would update" for every already-linked issue, even though a real--create-onlyrun skips them, so the preview over-reported updates and under-reported skips. This affectedbd jira syncandbd linear syncwith--push --create-only --dry-run. The dry-run now applies the same--create-onlygate as the real run. Linear's dry-run also no longer counts an issue its batch filter skipped (create-only, aShouldPushhook, parent, type, or conflict) as skipped twice. Notion's batch dry-run was already correct. -
bd config unsetno longer reports success while the key stays set, and now names where the unset actually landed. A key present inconfig.yamlbut not claimed byIsYamlOnlyKeywas deleted from the database only, so it stayed effective; it is now cleared from both, and the reported location -Unset <key> (in database, config.yaml)- is derived from what the writes actually changed rather than from a pre-check of viper's merged value, which counted defaults and environment variables as present in the file. A yaml-only key that was not in the file prints<key> was not set in config.yamlinstead of claiming a write. A workspace with no projectconfig.yamlat all is an answer rather than a failure, so a database-backed unset there no longer deletes the row and then exits non-zero. Unsetting a key whose value is the indented block beneath it (a mapping or a list), which used to comment out the key line and orphan the block into aconfig.yamlthat no longer parsed, is now refused alongside the flow-style and block-scalar shapes above. An unset also keeps the file's trailing newline, and an unset that changes nothing now leaves the file byte-identical - on a CRLFconfig.yamlit previously reported a write for a key that was never there and rewrote every line ending to LF. The stderr side-effect hint is gated on the write too, so a no-op no longer announces a removal it did not make, and the--jsonpayload for a yaml-only key carries achangedboolean so the machine branch can tell an absent key from an unpopulated field.
[1.3.0] - 2026-09-15
The first tested release off main since the 1.1 line. [1.2.2] was a recovery
release that re-shipped the v1.1.2 code under a higher version number, so a
v1.2.2 user is running 1.1-era code and meets everything below at once:
the changes listed here, plus the [1.2.1] changes that release deliberately
withheld. Read the upgrade notes before installing.
Upgrade notes
On an embedded or local store, the first invocation migrates your schema, in
place, from v53 to v66. A v1.2.2 (or any 1.1.x) database sits at main-series
schema v53; this binary knows v66, so the first command that opens the store
applies 13 main-series migrations, 0054_add_lease_columns through
0066_add_events_journal_actor. Two of those passes rewrite rows rather than
just reshaping tables — the aux-row id rekey and the events dolt_ignore flip
described under Changed — so on a large store the first invocation is
noticeably slower than the ones after it. It is crash-resumable and picks up
where it left off, but do not interrupt it if you can avoid it.
A shared Dolt sql-server is never auto-migrated (#5920, #6048): migrating it
promotes the schema for every client at once, so it waits for explicit consent
via bd migrate schema. Remote-backed stores keep their existing
designated-migrator gate. Upgrade all of that server's clients first — see
Shared servers.
The counter restarts partway through, and that is not a loop. The clone-local (dolt_ignored) series runs after the main one, through the same printer and its own numbering, and it moves 0011 → 0026 on this upgrade. So the run is about 28 migrations, not 13, and what you see on stderr is 13 lines counting up to 0066 followed by 15 lines starting again at 0012:
Applying migration 0065: widen_wisp_comments_text…
Applying migration 0066: add_events_journal_actor…
Applying migration 0012: create_leases… ← clone-local series, not a restart
A counter that jumps backwards is the signature operators kill runs over. Let it finish.
Progress prints only when stderr is a terminal. Piped and CI runs see nothing at all, which is deliberate — a silent-looking CI upgrade is not a stuck one.
Back up first, with the binary you have now. Take the backup before you
install 1.3.0. Under the new binary bd export triggers the auto-migration
before it exports, so a snapshot taken afterwards is a post-migration snapshot
and cannot protect you against the migration going wrong. On a remote-backed
store, finish syncing with the old binary too: once 1.3.0 is installed the
pending-migration gate refuses bd dolt push and bd dolt pull as well, not
just bd migrate.
# with your CURRENT bd, before installing 1.3.0:
bd dolt push # remote-backed stores only
bd export --all -o .beads/backup/pre-1.3.0-$(date +%Y%m%d).jsonl
A JSONL export is cheap, issue-complete, and importable by any bd version. If
you want a Dolt-native snapshot that keeps history and config, configure a
destination and sync it — bare bd backup takes no backup, it is a command
group that prints help and exits 0:
bd backup init <path-or-dolthub-url> # once, to configure a destination
bd backup sync # take the snapshot
Upgrade every client that shares a store, together. The forward schema-skew
guard means an older co-resident binary — a second bd earlier in PATH, a
long-running bd serve, another clone's cron job — refuses a database migrated
past what it knows, rather than proceeding blind. That is the guard working, not
a bug, but it makes a mixed-version fleet a broken fleet: one machine running
1.3.0 takes the whole store forward and every 1.2.2 client stops. Run
which -a bd after installing, and on a remote-backed store follow the existing
designated-migrator procedure (one clone migrates and pushes; the rest pull or
re-clone). See
Upgrading for the
per-install-method recipes and the multi-clone flow.
If you need to go back, the rollback is a schema-cursor rollback, not a
downgrade of the data: the procedure is written up in the
recovery runbook
(repo copy: docs/recovery/accidental-1-2-1-release.md). Its worked example is
the v53↔v65 case from the accidental 1.2.1 release; the steps are the same for
v66, with the version numbers adjusted.
Breaking changes for v1.2.2 users
This is a highlights list, not the complete set. A v1.2.2 user is crossing
two releases at once, and the breaks below are the ones most likely to stop a
script or a service. The full set is the [1.2.1] section further down plus the
Changed section here — read [1.2.1] in full before upgrading, since
[1.2.2] withheld it and v1.2.1 itself was pulled, so nobody on the supported
line has seen it.
After upgrading, bd upgrade review prints exactly the entries between the
version you were running and this one. (Prefer it to bd info --whats-new,
which dumps the entire release history.)
Carried from [1.2.1] — never shipped to v1.2.2 users:
bd update --status <done-status>now enforces close policy. Moving an issue toclosed(or any configured done-category status) viabd update,bd batch update, or the issueops facade refuses when the issue has open children or a live direct blocker, matchingbd close. Override withbd update --force(update <id> status=closed force=trueinbd batch;UpdateRequest.ForceClosePolicyfor facade consumers). An unforced refusal rolls back the entire batch.bd searchincludes closed issues by default (bd-t5yex). The dominant query is "was this already found/filed/fixed?", where excluding closed issues produced a false "no". Narrow with--status opento get the old behavior.bd listkeeps its open-only default.- The no-ID "last touched issue" fallback on
bd update/bd closeis interactive-only (bd-m00pb, #4839). A scriptedbd update $ID …with an empty$IDnow refuses in argument validation instead of mutating whatever was touched last. The fallback requires a terminal stdin;BD_NON_INTERACTIVE=1andCI=1/truealso disable it. SetBD_LAST_TOUCHED_FALLBACK=1if a script genuinely relied on it. bd human listhides done/frozen and pinned beads by default, and validates--status(#5332). It previously passed--statusthrough unvalidated and showed closed beads. A--statustypo is now an error rather than an empty list. Every bead type still shows.bd dolt pushandbd syncno longer adopt a git-origin-derived Dolt remote without consent (#5068). Both used to silently derive a remote fromgit remote get-url origin, persistsync.remote, commit that config change under your git identity, and upload the full issue history — which published a whole issue database to a public origin on a command the user believed targeted an already-configured remote. Adoption now prompts (defaulting to no) and fails closed non-interactively.--yes/-yconsents ahead of time.bd --readonly serveis refused instead of binding a server that cannot do what it advertises. On a Dolt SQL-server workspace the flag was previously a silent no-op and the server came up fully writable, so anything scripted as a "safe" read-only server does not start after this upgrade — drop the flag. Worth checking before you restart a long-runningbd serveas part of the fleet upgrade above.bd config listandGET /v0/beads/configno longer enumerate thekv.plane, which is wherebd remembermemories live. That closed an unauthenticatedGET /v0/beads/confighanding out every stored memory. A script that read memories out ofbd config listnow gets empty output rather than an error; usebd kv/bd rememberinstead.- The published
backendpackage drops orphan handling (bd-gwryr).backend.OrphanHandlingand its four constants, thestorageoriginals they aliased,BatchCreateOptions.OrphanHandlingandissueops.CheckOrphanare removed. They never did anything except cost a query, but a Go consumer that names them no longer compiles.
New in 1.3.0 (full entries under Changed):
- An explicitly configured Dolt server port now outranks the ambient
BEADS_DOLT_PORTenvironment variable. - Actor matching decodes an exact
--run to/instead of collapsing it to a generic separator, sogastown--mayormatchesgastown/mayorand stops matchinggastown__mayor.
Added
-
The events journal records WHO performed each mutation.
bd_events_journalgains anactorcolumn (migration 0066 plus its ignored-series twin 0025, so upgraded workspaces and fresh clones converge on the same shape), stamped inside the mutating transaction with the same identity the audit-events table resolves; on acommentrow it is the comment's author.bd events tail/bd events exportJSON gains an additive, omit-when-emptyactorfield — empty means the path had no actor (derived maintenance, deletes, rows older than the column), never a user. The input for same-field / different-actor conflict measurement over the journal. -
bdwarns when it stores a label containing a space (#5813). Such a label is a legitimate thing to ask for —-l 'good first issue'— and bd stores it as asked rather than re-splitting a boundary the shell already decided. But it is also exactly what a missed comma looks like, and that case cannot be told apart from the deliberate one at the point of writing. A line on stderr catches it at the keystroke instead of months later:⚠ Stored "auth backend" as ONE label — it contains a space.It is advice, not an error; stdout is untouched, so--silentstill prints just the ID, and--quietsilences it. Not emitted for--remove-label, since removing such a label is how the damage gets repaired. -
bd doctorgains aLabel Whitespacecheck for finding damage already in a database (#5813). It reports labels that contain whitespace or differ from their trimmed form, andbd doctor --fixrepairs them. The check is warn-only: a database with legacy damage still exits 0. As with the rest of barebd doctor, it does not yet run in embedded mode (GH#3794). -
bd staleandbd blockedgain--label,--label-anyand--exclude-label(#5822), with the same meanings and the same flag names they already have onbd listandbd ready:--labelis AND (repeatable, must have all),--label-anyis OR,--exclude-labeldrops anything carrying one. They were the two listing commands with no label-scoped output at all, so a theme-scoped stale sweep had to pull the whole list as JSON and post-filter it on the labels array. Filtering happens in SQL ahead ofLIMIT, not on the hydrated rows, so--label x --limit 10returns ten matching issues rather than whatever survives filtering the first ten. No--themeflag: beads has no theme concept, themes are labels here, and--label theme:xis the native way to say it. -
New
*.gate.lockfiles appear next to and inside.beads(#5046, #5093). A two-level cooperative gate now serializes the operations that cannot safely overlap — ordinary commands take it shared, maintenance likebd backup restoretakes it exclusive. It isflock-based, so the file is the lock's name, not its state: the gate is created once (mode0600) and deliberately never deleted, because deleting it is how two processes end up holding two different locks for the same resource. Each gate sits beside what it guards, never inside it: the workspace gate for<dir>/.beadsis<dir>/.beads.gate.lockin the project root, and the physical-root gate is.beads/embeddeddolt.gate.lockin the default embedded mode (.beads/dolt.gate.lockunder a server layout; under the shared server it lives beside~/.beads/shared-server/doltand never enters the workspace at all; a remote Dolt host has no physical gate). Both are covered by the*.gate.lock*patternbd doctormaintains in the project and.beadsgitignores, so an upgraded workspace picks up the ignore rule on the nextbd doctor --fix; a workspace with no.beadsdirectory is not gated at all, rather than scattering lock files into whatever directorybdwas run from. -
sortonGET /v0/beads/issues. The listing served one order —(created_at DESC, id ASC)— because the cursor is a keyset position in it, and the spec said so in its own words: "the sort order is welded to the cursor contract, and a new order needs new surface." The cost of that welding fell on every client that wantedbd list's ordering, because the only way to get it was to page the whole result set and re-sort locally. Measured over a 1400-row store at the 200-row page an HTTP client actually uses, that is 7 requests plus a client-side comparator;?sort=priorityis 1 (TestProxiedServerListSortRetiresTheWalk, which runs both strategies against a realbd serveand checks both againstbd list --jsonrow for row). It is the one cost on this surface that got worse as a project grew.Two values, and the set is closed.
createdis the existing order, now spellable.priorityis(priority ASC, created_at DESC, id ASC)—bd list's flagless ordering, which is also whatbd list --sort priorityproduces, so one served order retires the walk for both. The other seven ordersbd list --sorttakes are not offered: each value here is a cursor contract needing a key proven total, andidis a natural-numeric order no database expresses,updatedmoves on every write,closedis nullable, andstatus/title/type/assigneeare mutable and unindexed.Absent
sortstill meanscreated, permanently. It is the compatibility contract for every client written before the parameter existed; changing it would alter which rows a truncated page contains, with no error to notice it by. A server that predates the parameter answersparam: "sort"withreason: "unknown_parameter", which is the per-parameter capability probe a client dispatches on to fall back.The cursor now carries its order, and a mismatch is refused. This is the half that makes the parameter safe rather than merely useful. The token was base64 of
{t,i}with no binding, so acreated-order cursor replayed undersort=prioritywould have decoded perfectly and been read as a position in a different total order — a page that both skips and duplicates rows, served with a 200, undetectable by the client. Tokens are nowv2with an explicit order member and decode refuses any token whose order differs from the request's, asinvalid_cursor(documented recovery: restart paging). Outstandingv1tokens stay readable as thecreated-order positions they are, so no traversal in flight has to restart. This does not contradict "the token carries no filters": filters select the set, the order decides what the position means.priorityis a mutable key, whichcreated_atis not, and the spec says so: undercreatedonly new rows move relative to a walk, while a priority update moves an existing row too, so it can be seen twice or missed. That is the already-documented "a cursor pins a position, not a snapshot" caveat reached by a second route, not a new class of error — unchanged data never skips or repeats under either order.
Changed
-
Shared Dolt databases (sql-server mode) no longer auto-apply schema migrations on a version bump. Migrating a shared database promotes the schema for every connected bd client at once and locks out clients still on an older binary, so bd now refuses without explicit consent: run
bd migrate schemaonce after upgrading every client, or setBD_ALLOW_REMOTE_MIGRATE=1in scripted use. Reads keep working on the current schema meanwhile. Embedded (single-user) databases still auto-migrate silently, unchanged. (#5920) -
Commands that cannot work under
--proxied-servernow refuse before any provider opens (#6293).bd doctor,bd backup,bd restore,bd diff,bd migrate,bd branch,bd conflicts,bd vc,bd federation,bd repo,bd flatten,bd sync,bd dolt push|pull|commit,bd dolt remote add|list|reset-data, andbd admin compactwithout--doltreturn a typed refusal carrying a stable code (proxy.doctor.unsupportedand friends) instead of failing partway through, or silently doing nothing. Two changes worth planning for:bd doctorunder--proxied-serverused to print a note to stderr and exit 0; it now exits 1 withproxy.doctor.unsupported. A script that treated barebd doctoras a no-op in this mode needs to stop calling it, or tolerate the non-zero status.- Under
--json, a refusal is strict JSON on stdout ({"code": …, "error": …, "mutates": false}) rather than prose on stderr, so a wrapper parsing stdout gets a machine-readable answer and"mutates": falsestates that the refusal touched nothing.
-
The smart migration gate's "auto-migrate as safe first-mover" and auto-fast-forward arms are now embedded-only. On a shared server the gate always stops for consent, because neither argument can observe the other clients attached to that server. (#5920, #4516)
-
The newly exported Go packages (
backend,backend/conformance,beadserrors,issueops,journalops,memoryops,schema,test/conformance) are marked EXPERIMENTAL: they are not yet covered by the project's compatibility promise and may change in a minor release. Pin an exact beads version and re-run the conformance suite on every bump. -
The optimistic-concurrency token is now a JSON string — responses carry
revisionas an opaque decimal string andexpected_versionmust be sent as that string. JSON-number tokens exceeded JavaScript's 2^53 integer precision. This member never shipped in a tagged release. -
CI: migration-test and upgrade-smoke now seed and assert wisp-plane data (wisps, wisp deps/comments, leases, events, ignored-track cursor) across v1.0.1/v1.1.x/v1.2.2 → candidate upgrades.
-
--profileis now--cpu-profile, with no alias (#5126, bd-ugz). The persistent flag that writes a CPU profile is spelled--cpu-profile; the old--profilespelling is gone rather than deprecated, so it fails as an unknown flag instead of silently doing nothing.--profileis the conventional name for a named configuration, not for pprof output, and holding it hostage to a debugging aid nobody passes twice a year was the wrong trade. Scripts and aliases that profile bd need the new spelling. -
Migration 0061 rekeys every events, comments, snapshot and compaction-snapshot row to a content-derived id (#5150, bd-ri8bd). Those four aux tables minted random UUIDv7 ids, which is fine for a single writer and wrong for replication: unversioned newest-wins replication has no merge pass, so two clones recording the same fact produced two rows that never converged. Ids are now UUIDv5 over a SHA-256 digest of the row's own content (frozen column order, plus the table name and a duplicate-disambiguating ordinal), so the same fact derives the same id everywhere and convergence is a property of the key rather than of a reconciliation step. New rows derive their id at insert; existing rows are converted by a one-time bulk rekey on the first open after upgrade, which is the main reason that invocation is slower than the ones after it. The pass is crash-resumable through a
local_metadatasentinel and records completion clone-locally, so it runs once per clone and is not repeated on the next command.wisp_eventsandwisp_commentsare deliberately excluded — they are clone-local and never merge. Any external reference to an event, comment or snapshot id taken before the upgrade will not resolve afterwards. -
The
eventsaudit table is now clone-local (#5162, bd-red8u). Migration 0062 moveseventsonto the dolt_ignored plane in a self-committing drop/commit/recreate that preserves every row. Events are single-writer audit rows with low cross-machine value, and minting a versioned Dolt commit for each one was the dominant source of commit churn on a busy store. The consequence is the point:eventsrows no longer replicate. They keep full SQL durability locally andbd history <id> --eventsstill reads them, but a pull no longer brings another machine's events over, and a push no longer sends yours. Events already committed before the flip stay in the remote's history until the next squash window. Comments stay versioned. -
The
interactions.jsonlaudit sidecar is opt-in (#4688, fixes #4687).audit.enablednow defaults to false andbd initno longer creates the file, so status/assignee/priority field-change logging writes nothing unless you ask for it. Setaudit.enabled=true(orBD_AUDIT_ENABLED=1) to restore the old behavior. The database-backed replacement isbd history <id> --events, which needs no sidecar. Anything that read.beads/interactions.jsonlon the assumption it would exist needs the config key set. -
bd importrefuses a redirected stdin rather than quietly ignoring it (#5171, bd-axluy). Barebd importimports the default JSONL, andbd import -imports stdin; abd import < file.jsonllooked like the second and behaved like the first, importing a different file than the one on the command line with no way to notice. With stdin redirected, no-, and no named source,bd importnow errors and names both fixes./dev/nullis a character device, so a scripted barebd importunder a subprocess still imports the default file as before. -
Auto-backup defaults to off under a Dolt sql-server (wy-zrmqr). The automatic backup used to switch itself on whenever a git remote existed, regardless of storage mode — which on one shared sql-server meant ~31 clients independently deciding to back up the same database, pinning its CPU. The default is now off in server, proxied-server and shared-server modes (and in nocgo builds, which are always server-backed); embedded mode is unchanged and still enables it when a git remote is present. An explicitly configured
backup.enabled(orBD_BACKUP_ENABLED) always wins over the default, andbd config get backup.enablednow prints the effective value with its source —default (auto: off in sql-server mode)— rather than a barefalsethat could not be told apart from a configured one. -
bd hooks install --chainand--forceare accepted no-ops (#5284, bd-5vdt8). ManagedBEGIN/END BEADS INTEGRATIONmarker sections made both flags meaningless: an install now replaces only the content between its own markers, so content outside them is always preserved (what--forceused to negate) and an existing hook always keeps running alongside the bd section (what--chainused to request). The flags remain registered so existing invocations do not break, and--jsonstill echoes them, but neither changes what is written. A hook with no markers is handled by shape: a legacy bd hook is replaced, and a foreign one gets a one-time<hook>.backupsidecar before the section is injected. Symlinked and git-tracked hook paths are refused outright, before anything is written. -
Write commands refuse to run while a migration freeze marker is present (dc-6jaq). When a file named
MIGRATION-FREEZEexists in the workspace directory, the working directory, or any ancestor of either — or at the path named byBD_MIGRATION_FREEZE_FILE, which is authoritative when set —bd create/update/close/remember/importand every other write command (~120 call sites,bd qincluded), plus the destructivebd init --reinit-localandbd bootstrap, print⛔ workspace is frozen for migrationnaming the marker's path and exit 14, a distinct code scripts can branch on, instead of writing to a store mid-migration. Operators freeze a workspace by creating the file (optionallyoperator<TAB>RFC3339 timestamp<TAB>reasonon one line, echoed back in the refusal) and thaw it by removing the file. Read commands (list,show,ready, …) keep working during a freeze, and bd's own maintenance stands down with them — version tracking, auto-migration, JSONL auto-import, Dolt auto-commit, auto-backup, auto-export and auto-push are all skipped, so a frozen store is never rewritten just because someone ran a read. A runningbd serveis not gated: stop it before freezing. If bd cannot tell whether a marker is present, it refuses rather than assuming the workspace is open. -
bd dep addnames the implicittype=blocksdefault, but only to an interactive operator (#5854). Creating an edge with no-t/--typesilently produces ablocksedge, which drops the dependent out ofbd ready— the usual surprise when someone meant structural parent/child linkage.bd dep addnow says so on stderr. Becauseblocksis the documented default and the majority-correct case, the note is gated: it is emitted only when stderr is a TTY, so scripted and agent callers (and CI, andbd dep add 2>log) never see it and are not trained to ignore stderr.--quietsilences it, as it does the other non-error stderr notices, andBD_NO_DEP_TYPE_WARNING=1turns it off for operators who have internalised the default.--jsonoutput is unchanged. -
bd showlabelscreated_byasCreated by:, notOwner:(be-ss66). The text view renderedcreated_byunder a label naming a different concept.owneris a separate field holding a separate value — the git author email kept for CV attribution — exposed asownerin--jsonand never rendered in the text view at all. Two identities, one label, and the label named the one that was not on screen. This is a correctness fix and not polish: a reader asking "whose bead is this" reasonably reaches for what the label promises, and two defect analyses were filed off exactly that mistake in one evening, both measuring provenance from the wrong column and both retracted after another agent disproved them.bd shownow printsCreated by: <identity>. The--jsonpayload is unchanged, and a repo-wide audit found no in-tree parser of the oldOwner:text — the only other producer,bd github's repo-config display, names an actual repository owner and keeps its label. -
beads_dirandrepo_rootare now OPTIONAL members ofContextResponseonGET /v0/beads/context. They are the only two members of the identity handshake that describe the SERVER's filesystem rather than the workspace's logical identity, and an absolute host path is not something a remote client can act on — it cannot open it. The document already called publishing them a cost "an operator accepts when binding beyond loopback"; while they were required, accepting it was the only conforming option. A deployment that does not want to disclose its filesystem layout can now withhold them and still serve a conforming body.No body changes.
bd servepublishes both, always, exactly as before — the relaxation is a promise to clients, not a switch on the server. What changes is what a client may assume: it MUST tolerate their absence, and MUST identify a workspace byproject_id,databaseandbackend, which stay required. In Go,apigen.ContextResponse.BeadsDirand.RepoRootbecome*string. -
An explicitly configured Dolt server port now outranks the ambient
BEADS_DOLT_SERVER_PORT/BEADS_DOLT_PORTenvironment variables (be-wf9a.1, be-9tju, GH#4052).ServerPortresolution now carries a source — which step of the chain produced the port — and the env read only applies when that source is not an assertion by the user or by tooling acting for them. Two deliberate behavior changes follow. First, a port set by the caller before the store opens (a library caller filling inConfig.ServerPort, orbd init --server-port) is no longer silently replaced by whatever the surrounding shell exported; previously the env var won unconditionally. Second, the legacyBEADS_DOLT_PORTspelling no longer overrides a port resolved from.beads/config.yaml(dolt.port), Dolt's ownconfig.yaml(listener.port), ormetadata.json(dolt_server_port). The currentBEADS_DOLT_SERVER_PORTspelling is unaffected — it sits first in the resolution chain and still wins over all of them.Compatibility: a workspace that relied on exporting
BEADS_DOLT_PORTto redirect away from a port pinned in config now connects to the pinned port instead. Switch toBEADS_DOLT_SERVER_PORT, or change the pinned value. Ports that bd resolved for itself — the gitignored.beads/dolt-server.port, and the shared-server default 3308 — stay non-authoritative and remain overridable by either spelling, which is the case that kept working throughout.A related failure goes away with it: because bd's own bookkeeping is no longer mislabeled as user configuration, a stale
.beads/dolt-server.portleft by a crashed server no longer makes auto-start refuse to start with "bd will not silently use a different port than the one you configured" when nothing was configured. Auto-start warns and retargets, as it did before. Shared-server mode still fails closed there — a repo-local auto-start is a different database, not a port refresh — but now says so in its own words. -
bd reclaimsummarizes the leases its replica guard declined instead of naming every one, every run (wy-sp2l4). A lease granted by another replica is by construction never reclaimed here, so the audit was not a one-off: it repeated identically on every run, one stderr line per stranded remote lease. A supervisor on a 1-minute timer against a federated store with 47 of them printed 47 lines a minute, indefinitely. The default is now ONE line —reclaim: skipped 47 stale leases granted by other replicas — "mini" (30), "mini2" (17), not this node ("laptop")…— naming at most three replicas and collapsing the rest into a count, with the exact total preserved.bd -v(orBD_DEBUG=1) expands it to the per-lease lines, itself capped at 20 with a collapsed tail. Still stderr-only:bd reclaim --jsonowns stdout and its payload is unchanged. Under--quietthe audit now skips its queries entirely rather than running them to discard the output. -
Actor matching decodes an exact
--run to/instead of collapsing it to a generic separator (be-p7dzx, bundled be-vc51). Identity comparison — used byExpectedAssigneeon release and update, and by claim/close/unclaim authorization — canonicalizes a run of.,_or-to one separator so the same identity spelled under different layers' conventions compares equal. An exact two-byte--run is now excluded from that collapse: it is gascity's session-name encoding of a rig-qualified agent's/, so it decodes to/. Compatibility:gastown--mayornow matchesgastown/mayor, and stops matchinggastown__mayorandgastown-mayor. That is the intended fix rather than a side effect —gastown--mayoris the agentmayoron riggastownwhilegastown__mayoris the dotted aliasgastown.mayor, so matching them was a widening — but any stored--spelling that is NOT a gascity slash encoding changes equivalence class silently, with no error to notice. Longer or mixed runs,__and---included, are unaffected and still collapse. -
bd ready --claimnow refuses a row cap under--proxied-server. The proxied ready role cannot enforce--max-rows/BEADS_MAX_ROWS, so bd fails loudly rather than silently dropping the limit;--claimno longer exempts the command. Agent rigs that set the cap globally must unset it for proxiedbd ready --claim. Direct mode is unchanged, and a claim there still succeeds against a ready pool larger than the cap. (#6269)
Fixed
-
Server-mode issue mutations no longer revert concurrent writers' committed rows (#5740). The issue-mutation path ran
DOLT_ADD/DOLT_COMMITinside its still-open SQL transaction;DOLT_ADDstages the whole table as of the transaction's BEGIN-time root, and the Dolt commit was minted before the commit-time merge that reconciles concurrent writers — so a mutation could silently write every row another session had committed during its window back to that session's BEGIN-time value, seen in production as claims reverting minutes after they were made. The Dolt commit now runs after the SQL transaction commits, against the post-merge working set. Its failure is logged rather than returned: the data is durably committed by then and rides the next Dolt commit, and treating an applied mutation as failed is what made retries double-apply and claim verification disown claims the caller held. Reported and fixed by @nova-submodules. -
Removed-backend rejection now detects an existing Dolt database and gives the exact
metadata.jsonheal (change"backend"to"dolt", or delete the field) instead of a destructive export/reinitialize path. Workspaces that bd v1.2.x opened as Dolt despite a stale"backend"value are one edit from healthy, and the message now says so. Rejection remains fail-closed and read-only — no storage database is opened or modified — and still exits 1. (Detection helper ported from @steveyegge's #4740.) -
bd migrateno longer aborts with a duplicate-primary-key error when the same dependency edge exists in two typed target columns; duplicate edges are now merged deterministically (issue-ref wins over wisp/external), renaming an issue no longer leaves its dependency rows on a stale primary key, and databases left half-rekeyed by earlier binaries are detected and repaired on the next migration pass (#5268). -
Legacy tracked
ignored_schema_migrationsself-heals by untracking it at open time, unwedgingbd dolt pullon upgraded databases (#4356). -
A v1.1.x/v1.2.x ignored-migration cursor is believed when
leases.granted_nodeis merely not yet migrated, so upgrades apply only the pending ignored tail instead of replayingignored/0007and silently restampingwisps.updated_at(#5981 class, #5366 follow-up). -
Auto-export heals after
bd deleteinstead of permanently refusing — the orphan guard proves deletions against the store's own history (embedded and server modes), stores wedged by earlier binaries recover on first run, andexport-state.jsonis now versioned (#5896). -
bd flattenandbd compactnow finish with a full Dolt GC (all generations), so re-running them on a previously-GC'd store actually reclaims the orphaned history and retires orphaned--as-ofaddresses;bd gcgains--fulland hints when a default pass reclaims little (#5907). -
--storage-classis honored on the proxied-server and--fileroutes and rejected as a plan-wide--graphflag; it was silently ignored there. -
Delete and cascade
dep_removejournal rows are attributed to the requesting actor (#5985);bd events export/tailnow say when the journal is disabled. -
Truthful errors when a server-scoped credential cannot reach the requested database (missing / denied / wrong-session attribution);
--init-if-missingis honored in proxied-server mode. -
The aux row re-key survives dolt#11131-class encoding drift instead of failing mid-upgrade with a raw
invalid hash lengtherror. Drifted tables are skipped with a warning, recorded clone-locally inaux_row_rekey_drifted, and re-keyed on a later pass, rather than leaving the database unopenable. This already reached 1.1.x and v1.2.2 users — it is the [1.1.2] fix — and lands on the main line here, so a store upgrading from v1.2.2 is not newly exposed (#5064, #4380). Diagnosis and fix by @marcodelpin, carried and reworked by @maphew. -
Server mode honors
Config.LenientOpen, so the dirty-table guard's documented recovery is executable. The refusal tells you to runbd dolt commit/bd vc commit, but against an external Dolt server those commands could not open the store to do it — the flag reached server mode andnewServerModenever read it, while the field's own doc comment said "Ignored in server mode". That left the #4566 deadlock intact for exactly the case with no way out: embedded mode can move the database directory aside andbd bootstrap, and there is no equivalent against a shared server. Fixed by @Toady00 (#5783, #5781). -
bd bootstrapprobes git remotes for Dolt data instead of rejecting them outright (#6037, #5743, #5663).bd initdeliberately persists a git-origin-derivedsync.remoteinto the tracked.beads/config.yaml— a git origin is a valid Dolt remote beforerefs/dolt/dataexists, because the firstbd dolt pushcreates that ref on the same remote — but bootstrap classified those URLs as code-repo URLs and returned before the origin auto-detect that would have hydrated the clone,git+https://andgit+ssh://included. Committedsync.remotevalues from earlier releases hydrate again. The failure was silent because one outcome code covered both "a database already exists, nothing to do" and "I refused and left you with nothing": bootstrap printed✓ Database already exists, exited 0, and created nothing, after whichbd init --reinit-localpointed back atbd bootstrapin a closed loop. Bootstrap now exits non-zero whenever it declines to set up a database. -
--set-metadataagain stores numbers/booleans/null as typed JSON scalars (v1.2.2 behavior); string-forcing lives on--metadata-json. Values written by in-window dev builds are left as strings; re-apply the flag to retype a key. -
bd create --json(andPOST /v0/beads/issues) again echo sub-second RFC3339Nano timestamps; reads (show/list) remain second-precision as in v1.2.2. -
bd purgeandbd pruneselect candidates by TIER, so a typed wisp is ephemeral however it was minted (#5995). The two sweeps split the world between them —bd purgeclears the ephemeral tier,bd prunethe durable one — but membership was decided by the rawephemeralcolumn, and a wisp minted before that column was set carried awisp_typewithephemeral = 0. Such a bead belonged to neither sweep:bd purgereported "No closed ephemeral beads to purge" whilebd pruneskipped it as a wisp. One production database had 858 such rows / 7.3 MB that no sweep could ever reach. The tiers are now complementary predicates over both columns — ephemeral isephemeral = 1 OR wisp_typeis non-empty, durable is its exact complement — evaluated across both planes rather than taking the wisps-plane fast path, because legacy typed wisps live in theissuestable. A non-emptywisp_typenow also implies ephemeral at mint, on every create path, so no new bead can land in the gap. A previously unreachable typed wisp is now abd purgecandidate, so the first purge after upgrade may clear considerably more than usual. NoHistory beads (wisps plane, nowisp_type) stay durable-tier, unchanged. -
bd primesays when it could NOT read the memory plane (#5877). A broken or unreachable store made prime omit the memory section entirely, so a session that woke with zero recall looked exactly like a workspace that simply has no memories — same output, same exit 0, no way for a fleet operator to tell them apart. Prime still never fails a session-start hook, but a memory read it cannot serve now rendersSkipped: beads storage unavailable (<error>) — persistent memories were NOT injected this session, alongside the timeout banner that already existed for a deadline. Both the classic and the proxied-server route share the banner. A workspace-less directory, and a healthy store with no memories, stay silent as before. -
bdno longer serializes every invocation behind the schema-init advisory lock. The schema-init probe ran entirely inside the database-scopedGET_LOCK('bd_schema_init:<db>', 5), so on a shared Dolt server everybdprocess queued behind every other one to discover that it had nothing to migrate. Measured on an 18-seat rig: 1500is_free_locksamples over 14s found the lock held 96.7% of the time, held runs had a 673ms median and a 4.2s max, and free gaps had a 0ms median — the lock was handed straight from holder to holder. That queue was 0.4-2.4s of pure waiting on every claim, heartbeat, list, comment and mail check.MigrateUpWithLocknow answers the steady-state question first, without the lock — it puts the session on the target database (proving the database exists before issuing any statement that could fail, so a fresh bootstrap still falls through to the lockedCREATE DATABASE; callers whose pool already names the database inject nothing and the probe simply declines a session that is elsewhere), then asks whether both migration cursors are at this binary's latest with the content-hash column and custom-status/type backfills done, whether all the canonicaldolt_ignorepatterns are present, and finally whether the migration lock is free — and takesGET_LOCKonly on the path that can actually migrate. That last term is what keeps the probe honest while a peer is mid-pass: the cursors land before the backfills and rekeys finish, so a held lock, not the cursors alone, is the proof that nobody is rewriting the tables underneath this caller. The probe issues no writes — its one session mutation is theUSEthat pins the target database — and fails closed: any error, any unreadable state, and anything short of provably converged falls through to the locked path unchanged, as does any caller carrying fresh-bootstrap heal authority. -
Incremental auto-export now actually takes the incremental path (#5806). Change detection compared
GetStateHash()values — a hash of the entire database plus working set (DOLT_HASHOF_DB()), not a commit — butChangedIssueIDsfeeds both endpoints straight intodolt_diff(), which only accepts real commit hashes or the literalWORKING. Every incremental attempt therefore failed to resolve a diff and silently fell back to a full export: correct output, but the incremental short-circuit this feature exists for never actually ran. The "to" endpoint is nowWORKING(dolt_diff's own literal for the live working set) paired with the previous export's real commit hash as "from", so the incremental path resolves and fires as designed.Three format/scope regressions surfaced alongside the dead code path, since nothing had ever exercised it end-to-end: the incremental patch could leak memories into the auto-export output (full export filters them; the patch path did not), could include the configured owner's own issues where full export excludes them, and omitted the
_typediscriminator field full export always writes. All three are now pinned by tests that diff a patched run's output against a from-scratch full export of the same state. The patch write is also now atomic (write-temp + rename), matching the full-export path's existing guarantee.The owner and
_typefixes match full export exactly. Memory records deliberately do not, and the difference is worth stating: where the full path refuses to overwrite anissues.jsonlthat already contains memory lines (guardAutoExportOverwrite), the incremental path preserves them verbatim and proceeds. Preserving is the better behavior — a manually seeded export survives patching byte-for-byte instead of wedging — so the incremental path keeps it rather than adopting the refusal.Scope: this is a server-mode (
DiffStore) improvement only.EmbeddedDoltStoreimplements neitherDiffStorenorStateHasher, so in the default embedded mode the incremental path is inert (incremental skipped — store does not implement DiffStore) and every cycle is still a full export. The deletion-proof guard below started out server-mode only for the same reason; #5896 is now closed for embedded mode too — see the store-history heal entry below.Caveat: the diff anchor only advances on real commits. In server mode dolt auto-commit is off, so with no commits being made the anchor stays put and the diff range grows with every cycle. That is correct but not free: once the change set crosses the 5000-id threshold, every export falls back to a full rewrite until something commits and the anchor moves forward.
-
bd deleteno longer wedges auto-export in server mode (#5806, part of #5896). Auto-export's orphan guard refuses to overwrite anissues.jsonlholding issue records absent from the local store — the #4988 protection against a JSONL that has run ahead of the database. A normalbd deleteproduced exactly that shape, so a single delete leftissues.jsonlpermanently stale, with a "refusing to overwrite" warning on every later command. The guard now asksdolt_diffwhether each JSONL-only id was genuinely removed since the last export's anchor and, when proven, stops treating it as corruption.The proof is deliberately narrow. It requires
diff_type='removed'on the issues table itself, so a label-, dependency- or comment-only change, a delete-then-recreate, a wisp, or any diff error all still refuse. It also requires the anchor to still be reachable fromHEAD: after aDOLT_RESET --hard, a branch checkout, or any other data-dir rewind, a row reads as "removed" without anyone having deleted it, and honoring that would drop a live record. Both conditions must hold, or the guard refuses as before. -
Disabling telemetry no longer strands the queued eventsData backlog forever (GH#5712).
bd send-metricsearly-returned on disabled metrics before its prune step, and the spawn gate refused to schedule the child at all when disabled — so the one machine whose queue can never again drain by upload (the one that just opted out) kept every queued batch and orphaned emitter temp indefinitely (2M+ files / 15.8GB observed on one control VM). With metrics disabled, bd now still spawns the detached child under the same marker-first throttle, and the child prunes by the normal TTL/cap policy and exits without POSTing anything. Until that pre-existing backlog ages out, a host that just opted out while its queue still holds batches younger than the 7-day TTL (and under the file/size caps) keeps forking the throttled, detached, network-free prune child every flush interval — reclaiming nothing until those batches age past the TTL — so new prune-onlybd send-metricsprocesses on a freshly disabled host are expected during that bounded window and never POST. Once the backlog has decayed empty, spawns stop entirely; a machine that never enabled telemetry has no queue directory and never forks. -
bd showon a deleted or purged issue no longer prints text identical to an ID that never existed (ga-m6inyb).bd deleteand wisppurgeboth remove a row (and itsevents) from the live tables with no trace left behind, so "not found" was collapsing two states that call for opposite responses — archived (success) and never-existed (possibly lost data) — into one observable. This had a real cost: a gate-reviewer session showed a legitimate issue successfully, hit an unrelated mysql i/o timeout on a retry moments later, got the identical "not found" text for the same ID, and reasonably concluded data had been lost — when the issue had simply been archived in between.bd showon a missing ID now adds a second line —Hint: this ID may have never existed, or may reference a deleted/purged record with no trace left in the live database — try 'bd history <id>'— pointing at the existing, opt-inbd history <id>for anyone who wants to check further on a non-wisp issue (wisps are never committed to history, purged or not, so there is no signal left to recover for them). JSON output gains an additivehintfield; the existingerrortext is unchanged. Direct-mode text output changes for one path: the single-ID not-found branch's first line changes fromError fetching <id>: no issue found matching "<id>"toIssue <id> not found, matching the wording the multi-ID and proxied-mode paths already used (those two are unchanged aside from gaining the new secondHint:line). -
Explicit commits now sweep the entire working set and report no-ops honestly. In server mode,
bd vc commitandbd dolt commitpreviously routed through the config-excluding automatic-commit path, so out-of-band config changes could remain dirty even though the command exited successfully. Both commands now include config while continuing to exclude ignored wisp tables. A clean or otherwise non-committable working set reportsNothing to commit(committed: falsein JSON) instead of attributing an unchanged HEAD to a new commit. -
Every CLI label write now normalizes its input, as every label filter already did (#5813, fixes #5812).
utils.NormalizeLabels(trim, drop empty, dedupe) was applied tolist,search,ready,orphans,countand workapi — and to no write path at all. The filter trimmed its input and the store did not, so a label could not match its own filter:bd create --labels 'theme:a, theme:b'storedtheme:bwith pflag's leading space intact, andbd list --label theme:bthen returned nothing. The failure is silent in the worst way — a filtered list quietly short of rows is indistinguishable from a complete one. One real database had 150 such rows across 111 issues, found months later only because theme-by-theme counts refused to reconcile.create,quick,update(--add-label,--remove-label,--set-labels) andtagnow normalize on the way in.--remove-labelmatters as much as the additive flags: an untrimmed' theme:a'silently removed nothing.bd tagis included deliberately. Its help calls it "Shorthand forbd update <id> --add-label <label>", and it was the last CLI door still storing a positional verbatim. Normalization happens before the direct/proxied route split, so the two routes cannot disagree. A label that is only whitespace is now refused rather than dropped: the plural flags can discard an empty element and still honor the rest of the request, butbd taghas one label to add, so dropping it would report success having written nothing.Import and batch ingest are deliberately excluded and keep round-trip fidelity: what was exported is what is restored.
-
bd showno longer corrupts shell globs and other quoted wildcards in a description or notes (#5799). CommonMark lets a*or_run act as both an opener and a closer when the characters flanking it fall in the same class, and a quoted glob is exactly that shape — the*in'*.captured'sits between'and.. Two such runs therefore paired, including across lines, since goldmark joins a paragraph's lines before parsing. Everything between them rendered as emphasis: with color the asterisks were consumed and silently vanished from the command, leaving a still-plausible but different one on screen; without color, glamour's notty style wrote a literal**into the middle of the text. Storage was never affected —bd show --jsonalways returned the body byte-for-byte — but the rendered text is what a reader acts on, and what an agent reads when it takes its instructions from a bead. Runs that can act as both opener and closer are now hidden from the parser and restored afterwards, sobd showprints what was stored.The known trade, in two narrow shapes, both pinned by test: an authored closer that is itself both-flanking no longer pairs, so
see *"quoted"*, nextrenders literally rather than italicized (color path only — notty already printed it literally); and a backslash escape reaching for a both-flanking delimiter keeps its backslash, so\*.capturedrenders as\*.captured. An escape whose delimiter is not both-flanking, such asa \*literal\* b, is unchanged. Both are shapes CommonMark itself treats as ambiguous, and for a bead body — stored plain text, not authored markdown — showing the stored characters is the better of the two failures. Ordinary emphasis (**bold**,*italic*),SELECT * FROM t, code spans and fenced blocks all render exactly as before. -
bd blockedsilently ignored the label filters it already accepted (#5822).types.WorkFilterhas carriedLabels,LabelsAnyandExcludeLabelsall along, andbd blockedbuilt one, butGetBlockedIssuesInTxonly ever readParentID. Programmatic callers that set them got unfiltered results back and no error — a full list where a scoped one was asked for. -
Proxied-server mode (and
bd serve) ran schema migrations on every store open without consulting any migration gate, so an upgraded client silently migrated a shared database — including from read-only commands. The gate now runs on that path too: read commands warn and continue on the current schema, writes refuse, andbd servefails to start until the schema is reconciled. (#5043) -
bd migrate schemanow works in proxied-server mode instead of refusing. The migration runs during the provider open under the verb's consent. (#5043) -
Migration-gate and schema-skew failures on the proxied open path and at
bd servestartup now print their full actionable block instead of a single truncated line. (#5043) -
bd doctornow honors strict--readonlyand the migration freeze (#6028).bd doctor --fix/--cleanrefuse to mutate under either gate — the freeze refusal exits 14 and names the marker, and there is no doctor-side override — and plainbd doctordiagnosis no longer rewrites.local_versionor auto-applies schema migrations while a freeze is active or--readonlyis set; it reports the pending migration instead. Both gates key on the directory doctor was pointed at, not just the one it was launched in. Diagnosis itself keeps working under a freeze. -
An externally-managed Dolt sql-server is no longer mistaken for bd's own, which had silently disarmed the shared-store migrate gate (#6118). When the port arrived from
BEADS_DOLT_SERVER_PORT, frombd init --server-port, or from a stale port file left by a server that had since died, bd classified a genuinely shared server as workspace-owned and migrated its schema in place — no prompt, no warning, exit 0 — after which every older client on that server was hard-refused withschema version mismatch. Ownership is now proven from bd's own live port and PID record rather than inferred from how the endpoint was named: bd must have bound that port and the process answering it must still be alive. Everything else is shared, and stays gated. -
A
dolt.mode: serverworkspace declared in.beads/config.yamlis no longer refused as a legacy workspace (#6119). The upgrade guard resolved the connection mode frommetadata.jsonalone, so a workspace that names its mode only in config.yaml fell through to the embedded arm and was refused outright — including workspaces this release had just created and was already operating on. The guard now resolves the mode through the sameIsDoltServerModeprecedence chain the rest of bd uses, and a.local_versionwitness naming bd 1.0 or later vetoes the legacy verdict in every mode rather than only in server mode. -
A server-mode workspace with no
metadata.jsonno longer opens a phantom embedded database and answersbd listwith a false-empty result and exit 0 (#6120). Config substitution now gates onIsDoltServerMode, andBEADS_DOLT_SERVER_MODEis honored on that path instead of being ignored.
Security
-
Release binaries now build with Go 1.26.7 instead of 1.26.5, closing seven standard-library advisories reachable from
bd: quadraticnet/urlpath resolution,html/templateJavaScript-regexp context tracking, unbounded post-handshakecrypto/tlsmessages, a missingReadHeaderTimeoutonnet/http's unencrypted HTTP/2 check, unbounded recursion inencoding/xmlandencoding/asn1, and thex/net/idnaPunycode bug innet/http's vendored copy.bd serveand bd's outbound TLS calls exercise these paths. Thegodirective stays at 1.26.5, so nothing changes for code importing the beads module. -
Dependency bumps clearing all 25 open advisories.
golang.org/x/crypto0.55.0,golang.org/x/mod0.40.0,klauspost/compress1.18.7,moby/go-archive0.3.3,kin-openapi0.144.0 withoapi-codegen2.7.1, and a refreshedintegrations/beads-mcp/uv.lock. None of the fixed code was reachable from the shippedbdbinary: the go-archive and x/crypto/ssh paths are testcontainers-only, the compress bug is in thes2codec bd does not link, and the kin-openapi critical is inopenapi3filtermiddleware that enters the graph only through thetooldirective for spec codegen. No behavior change; no dolt bump was required.
Documentation
-
Known limitation: multi-rig prefix routing (
routes.jsonl) is not supported with proxied-server rigs — cross-rig bead gates stay pending,bd closeof a bead gate in proxied-server mode requiresbd gate checkor--force, and routed lookups cannot open proxied-server targets (#5861). -
The heartbeat/re-home invariant and the two states it can strand are now documented where the code lives (wy-sp2l4): a heartbeat proves the holder is alive, not that the lease moved, so
granted_nodeis backfilled but never overwritten. A renamed replica (mini→mini2) and an imported foreign lease whose holder name also exists locally therefore keep reading foreign while a local heartbeat keeps them alive, recoverable only withbd reclaim --any-replica. Reviewed and KEPT rather than re-homed: re-homing would let a heartbeat silently reassign enforcement of a lease another replica granted — the robbery the guard exists to prevent. Recorded inHeartbeatIssueInTx,docs/multi-agent/federation.md, andbd reclaim --help.
[1.2.2] - 2026-08-15
Recovery release, cut from the v1.1.2 tree on branch release/v1.2.2 (not
from main). v1.2.0 and v1.2.1 were published by accident on 2026-08-11
without release testing (v1.2.0's tag burned pre-publish; only v1.2.1
reached users). This release supersedes them by re-releasing the tested
1.1 line: it is the v1.1.2 code under a higher version number, so every
install channel (Homebrew, npm, the install script,
go install ...@latest) moves forward onto tested code. The 1.2.x-only
features listed under [1.2.1] below are not in this release; they
remain on main for a properly tested future release.
If v1.2.1 migrated your database (running any command once was enough),
v1.2.2 stops with schema version mismatch: database is at v65, binary knows up to v53. See the recovery guide
(site,
repo copy at the tag)
for the two-minute fix (roll the schema cursor back to v53) and a verified
stopgap (BD_IGNORE_SCHEMA_SKEW=1).
Changed
- The forward-skew error recognizes the accidental-release window (on the release branch): a v53 binary opening a database at schema v54–v65 points at the recovery guide instead of advising "install the latest release" (which would loop back to that binary).
go.modretracts v1.2.1, v1.2.0, and v1.1.1 sogo install github.com/steveyegge/beads/cmd/bd@latestresolves to this release instead of the accidental one. (The retract block is also carried on main so future tags keep the retractions.)
[1.2.1] - 2026-08-11
(Released as 1.2.1: the v1.2.0 tag burned pre-publish on a freebsd cross-compile failure in the release build — fixed below — and a burned tag is never reused, per the v1.1.1 precedent.)
Added
-
--briefonbd listandbd ready, andbriefon the two HTTP listings (#5546, #5554, #5586). The listing commands return the whole body of every row they page. On one real 16,051-issue storebd ready --jsonreturned 454,021 bytes with notes plus description accounting for 76% of it, on exactly the call an agent makes to decide what to work on next.--briefomits the free-form text (description,design,acceptance_criteria,notes,payload,waiters), measuring 93.4% smaller. Filtering is untouched:--desc-containsand its siblings select rows, and this selects fields. It is opt-in and the default payload is unchanged.The response carries no marker for the omission. An omitted field is indistinguishable from a genuinely empty one, so only the caller that passed the flag knows its rows are partial; there is no
is_lite_partialin the JSON. The one visible marker is in text output, wherebd list --long --briefprintsDescription: (omitted by --brief)rather than an empty section.The flag is refused wherever it could not be honored, rather than accepted and dropped. On
bd readyit requires--jsonand is refused with--claim,--gated,--moland--explain: the projection reaches the driver through the counts query alone, which those routes do not run. Onbd listit works in text mode too, and is refused with--watch, with the--parenttree walk, and with--format, where a caller's template could print a dropped field with nothing to mark it. -
--brief-depsonbd show, andbrief_depson the HTTP detail read (#5546, #5547, #5549).bd show --jsoninlines every dependency at full body, so reading one issue costs the free-form text of everything it depends on. On one real 16,051-issue store a singlebd show --jsonreturned 214,456 bytes, of which 193,039 was thedependenciesarray and one dependency carried a 180,975-bytenotesfield. The dependents side of the same detail view already had a shallow shape for this reason (be-4d36f2, where hub beads cost 5-13 GB); dependencies never got it. The new flag projects each dependency down toid,title,status,issue_type,priorityanddependency_type, which measured 89.3% smaller on that call. It is opt-in and the default payload is unchanged. -
bd servegets optional bearer authentication, and requires it beyond loopback (#5516). The help used to say "no authentication and no TLS", and the first half of that is what kept the server on a developer's loopback. Two flags answer it, and both default to today's behavior: abd servewith no arguments is byte for byte the server it has always been.--auth-token-filenames a file of accepted tokens, one per line, all accepted. Every operation exceptGET /healthzthen requiresAuthorization: Bearer <token>—GET /v0/beads/contextincluded, because it reports the repo root, beads directory and database name. There is deliberately no--auth-token: a credential passed as an argument is readable out ofpsby every local user.BEADS_SERVE_TOKEN_FILEis the environment fallback.Rotation is a file rewrite, with no restart. The accepted set is not a startup snapshot: the file is re-read while the server runs, at most once a second for the whole process, on the accepting path as well as on a mismatch — which is what makes REVOCATION work and not just rotation. Write
{new,old}, roll the clients, dropold; both take effect within about a second. A failed or empty re-read keeps the last-good set and logs, so a writer that truncates before writing cannot lock every client out.--allow-non-loopbacknow requires a token file. Beyond loopback, reaching the address would otherwise be the whole authorization.--insecure-no-authis the explicit, auditable way to say you meant that anyway. There is still NO TLS: a deployment beyond loopback supplies confidentiality itself.--allowed-host(repeatable, exact, no wildcards) adds Host header values to the DNS-rebinding allowlist, which is what a service deployment behind a DNS name trips over first.401/unauthenticatedjoins the frozen code vocabulary, withWWW-Authenticate: Bearerand a FIXEDdetailthat never echoes the presented credential. A missing header, a wrong scheme and an unrecognized token are one code deliberately — telling them apart would tell an unauthenticated caller which guess was closer. A token is a shared secret granting the whole surface, not an identity, soactoris still caller-asserted provenance and not the authenticated principal. -
Six more v0 operations, and the guarded-write token they compose from (#5506, #5507, #5508, #5510, #5535, #5536, #5540). Each is the wire half of a role that already existed and was already pinned on three legs.
POST /v0/beads/issues/{id}:release— give a claim back, whatbd unclaimspells. It is NOT idempotent, and that is the one thing to read before adopting it: a release over a row holding no claim is409/not_releasable, never a 200, because the post-state is anonymous. Do not read the code as "already released" — it also covers "the status will not accept a release", which is true of a row that is still ASSIGNED. Read the row.expected_assigneeis a compare-and-set on the holder andforceignores it; the two may not be sent together.POST /v0/beads/issues:claimNextandPOST /v0/beads/issues:batchClose— take the next ready bead in one round trip, and close many as one act.GET /v0/beads/issues:countandGET /v0/beads/dependencies:count— the two counting reads, each with its role's whole filter surface.dependencies:countboundsissue_idat 100 anchors.GET /v0/beads/issues/{id}/related— one anchor's neighbors, direction- parameterized and type-filterable. The length ofitemsis a NEIGHBOR count and not an EDGE count: a target that is anexternal:reference or another repository's id has no far end here and is silently not a neighbor, while the same edge IS a row onGET /v0/beads/dependencies.expected_versionon close, reopen and delete, andrevisiononGET /v0/beads/issues/{id}— the row's optimistic-concurrency token, so a read-modify-write loop can start from a READ instead of seeding its first guard from a write it did not want to make. A miss is409/precondition_failedand writes nothing.revisionis deliberately NOT on the listing rows:types.IssueWithCountsis also the JSONL interchange record, so a token there would write a per-write-random value into everybd exportline and every auto-flushedissues.jsonl.
not_releasablejoins the frozen 409 vocabulary. Every one of these carries the claim's posture unchanged:actoris caller-asserted provenance, hooks do not fire, the per-command auto-commit machinery does not run, and the only durable effect is the single storage commit the role makes in its own transaction. -
bd serveanswers aBd-Project-Idheader, and says so incapabilities. A client that knows which workspace it means to address stamps the request with that workspace's project id; a server that serves a different one refuses before any database work, so a misdirected read or write mutates nothing. An ABSENT header is served exactly as before, so this is additive wire surface and not a new precondition.GET /healthzandGET /v0/beads/contextare exempt — liveness must answer whatever workspace a caller believed it reached, and the handshake is where a client LEARNS the id to stamp with. Detect it with theproject.enforcecapability. -
A durable events journal, and
bd eventsto read it (bd-opisf). External tooling that wants to stay in step with a workspace had two options and neither was a feed: a fire-and-forget script hook that may not run, or polling whole snapshots and diffing them — which still misses anything that changed twice between two reads. The journal is the third. Every committed issue mutation writes one ordered record, in the same transaction as the mutation itself, and a consumer replays those records from a checkpoint it can resume. Each record carries the operation, the mutated id, and the issue's full post-mutation snapshot (includingis_blocked), so a mirror stays correct without re-querying the graph.It is off by default and opt-in per workspace:
bd config set events-journal true, orBD_EVENTS_JOURNAL=1. Nothing is recorded while it is off, so a workspace that never enables it pays nothing.On means bounded. Two retention floors define the window every consumer is guaranteed —
events-journal-retain-days(default 7) andevents-journal-retain-rows(default 100000), each disabled by setting it to 0 — and beads enforces them for you: after a mutating command commits, and on a timer insidebd serve, it deletes the prefix the floors do not protect. The pass is throttled by a persisted watermark (about one an hour per workspace — or sooner after a large burst of writes), runs in its own transactions outside the mutation's, is capped at a few batches so a long backlog drains over several commands rather than stalling one, and can never fail a command — a failure is logged and skipped. It maintains the workspace whose command triggered it, so a workspace only ever written remotely (a routedbd create --repo) relies on commands run in it, or on its ownbd serve. Setting both floors to 0 keeps every record forever;events-journal-auto-prune falsekeeps the floors but leaves deletion to you. All four areconfig.yamlkeys withBD_EVENTS_JOURNAL*environment equivalents.bd events tail --since <seq>prints records as JSON lines and--followkeeps printing them as writes commit;bd events exportprints the journal from the beginning;bd events prune --before <seq>takes an earlier, on-demand cut below the floors — it cannot cut deeper than they allow, so shrinking the retained window means lowering them. The floors are a recent-window guarantee, not a consumer watermark: size them for the longest outage a consumer must survive.A read that cannot resume fails instead of lying. When
--sincefalls below the oldest retained record, the read neither skips ahead to the surviving suffix nor returns an empty success: both are silent record loss that a cursor cannot detect. It exits 1 with a typedevents_journal_truncatederror carryingsince,floorandhead, so a consumer can choose between resuming atfloor - 1with a known gap and re-baselining. Under--jsonthat is the error payload; mid---followit is one compact JSON object on a line of the JSONL stream it interrupts, because the consumer on the other end is a line reader. An interior gap — which nothing in bd can produce, since a prune only ever removes a prefix — refuses the same way.The journal is clone-local working-set state (
dolt_ignored): never versioned, never pushed or federated, per branch, and per replica — each clone counts its own seq space, so a checkpoint from one replica is meaningless against another.bd dolt pulland merge-settled changes, rawbd sqlDML, store-open migrations, and compaction rewrites are not journaled. The record contract and every boundary are documented in docs/reference/events-journal.md. -
is_blockedis a documented optional member of the /v0 OpenAPI issue schemas (bd-opisf) —Issue,IssueWithCounts,IssueDetails,IssueWithDependencyMetadataandTreeNode, the five welded to the canonical Go struct. It is the persisted readiness projection: true when an open blocking dependency keeps an issue out of the ready set, derived from the dependency graph and maintained by the server, never set by a client. It is omitted when false, so absence means false. Journal snapshots are what set it; readiness itself is computed exactly as before. -
bd servegrows the write half of the agent loop (v0 wire surface, #5410, #5417, #5422, #5423, #5429). v0 shipped with one mutation, the claim, which meant an HTTP client could take work and had to fork abdsubprocess to finish it. Five operations close that loop:POST /v0/beads/issues/{id}:closeandPOST /v0/beads/issues/{id}:reopen— the two halves of the lifecycle move. Both are idempotent, and both say so in the body rather than in a status: a close of a closed issue answers200withalready_closed: true, a reopen of an open onealready_open: true, and each still carries the row.PATCH /v0/beads/issues/{id}— partial update of one issue. Thepatchobject publishes nineteen members; four of them (estimated_minutes,external_ref,due_at,defer_until) are nullable, and an explicitnullCLEARS them. That set is closed and machine-checked against the document, so anullon any other member is a400rather than an unannounced clear. A patch that changes nothing answers200withchanged: false.POST /v0/beads/dependencies:add— up to 100 edges per request, asserted all or none, echoed back in request order. A refusal names the offending edge asedges[i].member, so a client learns which edge and which member rather than that something in the batch was wrong.POST /v0/beads/dependencies:remove— removes exactly the edge the body names. Idempotent at the role: an edge that is not there isremoved: falsewith a200, never a 404, so a replayed teardown does not have to classify an error to discover it already ran.
Every one of them carries the claim's posture, unchanged. The
actoris caller-asserted provenance for the audit trail and not authenticated identity; hooks do not fire; the per-command auto-commit machinery does not run. The only durable effect is the single storage commit the role makes inside its own transaction, so durability is per request on every write, not just the claim.Three codes join the frozen error vocabulary, all 409 and all typed so a client never has to substring-match a message.
not_closableis close policy refusing an unforced close of an issue with open children or a live blocker.dependency_existsis the pair that already carries an edge of a DIFFERENT type, and carriesexisting_typeandrequested_type.dependency_cyclecovers both never-makes-progress refusals: the plain scheduling cycle, and a blocking edge against the issue's own ancestor or descendant — the second carriesissue_id,blocker_idandblocker_is_ancestor, and their ABSENCE is what tells a client which of the two it got. Every extension member is read off the refusing transaction's own typed error; the hierarchy members have no other source, since the conflicting edge may exist only inside the batch that was rolled back. An edge naming an endpoint this database can see the absence of is a400onedges[i].issue_idoredges[i].depends_on_id, not a 404: the request BODY is what is wrong, and there is no path id to have missed.GET /v0/beads/issues/{id}takes two new parameters.include_commentspopulatescommentswith the full comment bodies andinclude_dependentspopulatesdependentswith the issues that depend on this one, each carrying its edge type. Both default to false, because both are extra reads nobody should pay for by accident — and when a caller does not ask,comment_count,dependent_countandcomments_omittedstill report what was left out, so an absentcommentsis never ambiguous between "no comments" and "not included in this response". A malformed boolean is this operation's own400 invalid_argument/reason: "invalid_value", which is deliberately not theunknown_parametera client should read as version skew.GET /v0/beads/contextadvertisesissues.close,issues.reopen,issues.update,dependencies.addanddependencies.removealongside the rest — derived from the registered handlers as always, so probingcapabilitiesremains the way to ask one server what it can do. -
The two dependency-endpoint refusals now carry an identity (bd-yby99.9).
DependencyEditor.AddDependenciesrefuses an edge whose SOURCE names no row, and one whose TARGET names no row this database can see the absence of. Both were "an error" and nothing more — not the same error text on every backend, and impossible to tell apart from an infrastructure failure — which left the role's typed-refusal vocabulary with a hole every other refusal it can raise had already filled. They are nowerrors.Is-matchable asErrDependencySourceNotFoundandErrDependencyTargetNotFound, carried by a*DependencyEndpointNotFoundErrornaming the refused edge and which of its endpoints was absent, all three re-exported from the root package beside the conflict types. What is NOT refused is unchanged: anexternal:reference and another repository's id are still accepted as external targets.The user-facing message is byte-identical on the embedded and store paths (
issue <id> not found), and the proxied-server path now renders that message too instead of a raw foreign-key violation — the endpoint is classified from the refusing transaction rather than parsed out of the driver's prose, so the two plumbings agree on the text as well as the type. The sharedDependencyEditorcontract asserts the sentinel and the typed fields for each endpoint, alone in a request and mid-batch, with the mid-batch half reading the graph back at zero edges.RemoveDependencyis unaffected: a removal that finds no edge is a success, not a refusal.
Changed
-
Text-input commands now REFUSE two sources instead of silently picking one (#5332).
bd comment,bd noteandbd comments addused to apply a precedence order when a caller gave both positional text and--stdinor--file: the flag won and the positional text was dropped with no message. Naming two sources is now an error —cannot combine positional text "..." with --stdin— because the dropped half was, in every case we could find, the text the caller actually meant. Single-source invocations are unchanged. Scripts that relied on the old precedence (passing both and expecting the flag to win) must drop the redundant argument.bd human respondgains the same layer, so its response text can come from positional args,--response,--fileor--stdin;--responseis no longer a required flag.bd human dismisstakes its reason positionally as well as via--reason. Both now accept trailing positional text (<id> [text...]), matchingbd comment's contract — a second argument is free text, never a second issue id. -
bd list --status=allno longer hides boolean-pinned beads (#5332).allpromises every status, but the pinned exclusion was decided by comparing the raw selector string topinned/hooked, soallfell through and kept forcingPinned=false. The same string comparison also missed every multi-status set containing them, so--status=pinned,closedexcluded the pinned beads it explicitly asked for. Both now lift the exclusion. Scripts that used--status=allas a way to list everything EXCEPT pinned beads will see pinned beads appear; add--no-pinnedto keep the old result.--readyis unaffected: it forces statusopenand ignores the selector, so anallit never applies has no pinned side effect either. -
bd human listmatchesbd list's status handling, and hides no bead type (#5332). It used to pass--statusthrough unvalidated and show closed beads by default. Now done/frozen statuses and pinned beads are hidden by default,--statusis validated against the built-in and custom status names (comma-separated sets andallsupported, so a typo is an error rather than an empty list), and every bead TYPE still shows — gates, wisps, infra beads and templates — because ahumanlabel is an explicit request for a person's attention.bd human statscounts across every status, as before. -
bd human statsclassifies dismissals by close-reason PREFIX (#5332). It matched the substringdismisscase-insensitively anywhere in the close reason; it now requires theDismissedprefix thatbd human dismisswrites, shared as one constant so the writer and the classifier cannot drift. Beads closed before this with a lowercase or mid-string "dismiss" in their reason move from the Dismissed count to the Responded count. Forward behavior is unchanged. -
bd label add/removeover many issues is no longer one atomic transaction (ga-26w10, #5489). Both routes — the direct one and the proxied-server one — now end atissueops.Lifecycleandissueops.Reader, which deletes the four-way(add|remove) × (wisp|durable)switch the proxied route hand-rolled below the roles and the second implementation of the command that came with it. The plane is resolved inside the role's own transaction, so the wisp branch is gone rather than moved.The deliberate delta: a multi-issue edit is N guarded updates rather than one raw transaction, so
bd label add a b c mylabelrecords three history entries instead of one, and a failure on the third leaves the first two written where the old shape rolled them back. Neither is obviously right — the new one attributes each edit to its own issue and lands what it could — and the atomic shape is expressible today as oneissueops.BatchApplierupdate item per issue. The proxied route's resolution failure also lost itslabel added:prefix, which named a write the command never attempted; both routes now print the direct route's message.bd label list-allandbd label propagateare unchanged and stay off the role: no role answers "every distinct label in this workspace", and propagate is a search plus a fan-out needing the same batch question. -
The settings plane no longer serves the KV plane by any read (bd-rfwtv, bd-klko9).
bd kvkeys and thebd remembermemories nested under them are user data stored as config rows; they ride in the settings table without being settings. Listing them was already excluded, but a caller naming an exact key still got the value — and sincebd rememberderives its key from the content it stores, the keys are guessable, sobd config get kv.memory.<slug>andGET /v0/beads/config/kv.memory.<slug>(a surface whose only credential is an optional shared bearer, and whose redaction decides on the key NAME while a memory's secret is in the VALUE) walked around the exclusion.A point read of a
kv.key now answers exactly as a key nothing ever stored does — the echoed key, an empty value, a nil error — so a caller cannot tell a refusal from an absence.bd config showno longer prints those rows undersource=databaseeither; it reads the table raw and prints values in full, so it had inherited neither filter.Nothing is deleted and nothing becomes unreachable. The rows are untouched, and the surfaces that own them —
bd kv get,bd kv list,bd recall,bd memories— read the store directly and are unaffected.bd config setandbd config unsetstill take a verbatimkv.key, which keeps the escape hatch for a wedged memory. What is gone is reading memory contents throughbd config get,bd config listandbd config show.This is plane hygiene, not a confidentiality boundary.
bd servehas no authentication, and it serves every memory in full through/v0/beads/memoriesby design — anyone who can reach the server can still read them. What this closes is the settings plane's habit of handing user data to callers that asked for configuration: the routes that get republished into agent transcripts and pasted into issues. Do not read it as a fix that makes memories secret from someone who can already reach the port. -
bd searchnow includes closed issues by default (bd-t5yex). The dominant real-world search query is "was this already found/filed/fixed?" — exactly the query where silently excluding closed issues produced a false "no" (downstream repos grew shell wrappers purely to undo the old default).bd listkeeps its open-only default. Narrow explicitly with--status open(or any status list) where the old behavior is wanted;--status allstill works and is now redundant. Applies to both the embedded and proxied-server paths.Two consequences to know: matches beyond
--limit(default 50) are dropped under a status-blind sort (priority, then created), so a broad query on a large DB can now fill the page with closed matches and silently drop open ones — use--status openor raise--limitwhen hunting live work. Andbd query(plus the HTTPq=endpoint) deliberately keeps its closed- exclusion default with opt-in--all; onlybd searchchanged.
Removed
-
BREAKING (published
backendpackage): orphan handling is gone (bd-gwryr).BatchCreateOptions.OrphanHandlingand its four modes never did anything except cost a query. Removed symbols:backend.OrphanHandling,backend.OrphanAllow,backend.OrphanResurrect,backend.OrphanSkip,backend.OrphanStrict, and thestorageoriginals they aliased (storage.OrphanHandlingand the same four constants), theBatchCreateOptions.OrphanHandlingfield, andissueops.CheckOrphan.Migration for out-of-tree consumers: delete the option. Every call site in bd passed
OrphanAllow(or left the field at its zero value, which took the same branch), andOrphanAllowis exactly what the code still does — a hierarchical create whose parent is missing is accepted, and the child's auxiliary counter row is skipped because it would have no owner. OnlyOrphanStrict(reject the create) andOrphanSkip(silently drop it) behaved differently, and nothing but one conformance case ever passed them; a consumer that relied on either must now check for the parent itself before calling.OrphanResurrectwas never implemented — it shared a branch withOrphanAllow, and the resurrect-a-deleted-parent behavior its doc comment described left with the JSONL sync layer long ago.Every hierarchical-ID create paid a
SELECT COUNT(*)parent-existence probe to feed a switch whose only reachable arm ignored the answer. That query is now gone from the create path.
Fixed
-
--label-anyis no longer silently dropped bybd readyandbd ready --claim. The ready-work WHERE builder emitted clauses for--labeland--exclude-labelbut none for--label-any, so the OR-set filter was ignored on the ready/claim path (with or without--parent) on every backend — whilebd list/bd searchhonored it. On an atomic claim this was dangerous rather than merely wrong: a worker fencing itself to its own lane (bd ready --claim --label-any lane-a --parent epic-1) would happily claim another lane's issue and believe it was fenced.--label-anynow emits an OR-set membership clause that AND-combines with--label,--exclude-label, and--parent, exactly as the flag help promises; an exhausted lane now claims nothing instead of falling back to unfenced work. -
FreeBSD builds compile again (#5661). The dbproxy process-identity arc (procid, unverified-process) shipped linux/darwin/windows implementations with no fallback, breaking
GOOS=freebsdcompilation — caught only by the release build's cross-compile (GH#5662 tracks the CI gap). Unsupported platforms now get stubs that fail proxied-mode spawns with a clean, actionable error; classic (non-proxied) bd is unaffected, matching what v1.1.2 shipped on freebsd. -
Telemetry no longer taxes every bd invocation. Two startup costs paid on every command, measured during the post-wave startup audit, are gone. First, the machine-scoped distinct ID was recomputed on every invocation — a fork of the platform machine-id probe (
ioregon macOS, 20.2±1.2ms) — even withBD_DISABLE_METRICS=1and even forbd --version. The ID is now resolved only when metrics are enabled and cached at~/.beads/machine-id(0600), so the probe runs at most once per machine; a probe failure is retried next run rather than cached. Second, every invocation unconditionally spawned a detachedbd send-metricschild — a full re-exec of the binary plus an HTTPS upload attempt, with no check that anything was queued. The spawn now requires at least one queued event batch and is throttled to one attempt per 5 minutes (marker:eventsData/.last-flush); queued events still upload, just batched. Telemetry content, opt-out semantics, and the sanctioned endpoint pinning are all unchanged. -
A long or multi-paragraph close reason renders as body text in
bd show(#5595). Every other free-text field — description, design, notes, acceptance criteria, comments — reaches the terminal through the markdown renderer, which word wraps and indents. The close reason did not: it was formatted into the metadata block besideOwner:andCreated:, so it never wrapped and its second and later lines read as separate metadata entries, a blank line and a bare- bulletsitting directly underCreated:.bd close --reason-fileexists so agents can write structured close reports, and those were exactly the reasons that came out corrupted. A reason that still fits one metadata line — nearly all of them, including one-liners that arrive from a file with a trailing newline — is unchanged; anything larger now gets aCLOSE REASONsection rendered by the same call the other body fields make. The JSON payload is untouched. The compaction savings line moved into the metadata block at the same time, so it can no longer be stranded below that section, and all fivebd showrender paths now report it alike. -
Script hooks now fire on both write plumbings (bd-opisf). bd has two write plumbings and only one of them ran the workspace's hook scripts. The DoltStorage decorator chain fires
on_create/on_update/on_closeafter every mutation it lands; the unit-of-work plumbing — the one proxied-server mode writes through — fired nothing from the plumbing, so an integration wired to.beads/hooks/silently missed every mutation that went through it. Four commands (update,close,reopen,gate) had grown hand-wired hook calls of their own to paper over the gap; every other write —create, batch create and close, claim,comment, label edits, dependency edits — ran no hook at all. A notifying wrapper now fires them from the plumbing, buffered during the transaction and drained only after the commit succeeds, so a rolled-back or retried write reports nothing.Six changes are visible in proxied mode, and all six move it toward what the embedded path has always done (a seventh, below, applies to both):
- One firing site per plumbing. The four per-command hook calls are gone.
bd update -s closedfireson_updateonly. It used to fireon_closeas well.bd closeis what fireson_close, on both plumbings.bd closeno longer fires anon_updateahead of itson_close.- Hooks run fire-and-forget, after the write commits, rather than synchronously inside the command.
no-hooksis honored. The per-command calls ignored it, so hooks fired in proxied mode even when they were switched off.- An idempotent re-close fires
on_close, and a doublebd gate resolvefires it too. The per-command calls suppressed both; the embedded path has always fired for a close that succeeded, changed row or not, so a script reconciling on "it is closed" is told every time rather than only the first.
And one change every workspace sees, embedded and proxied alike: a command now waits for its own fire-and-forget hooks before exiting, bounded by the per-hook timeout (10s). Both plumbings run hook scripts on background goroutines, and a short command could return from
mainbefore one had even started — a hook that silently never fired. The wait happens after the store closes, so a hook script's ownbdcan open the workspace, and it runs on the error exit paths too, so a partial batch still delivers the hook for what it did commit. A command that fires no hooks waits on nothing.bd servestill runs no hooks, andbd importstill fires none on either plumbing (both import through the batch-upsert engine rather than the per-issue verbs). -
--dolt-auto-commit batch/offnow actually defer version commits in SQL-server mode (bd-4wamg). The mode was silently inert there: the CLI's auto-commit policy was embedded-only, and the storage layer minted one Dolt commit inside every write transaction regardless — measured at one commit per write through all five configuration paths (flag, config.yaml, env,bd config set, no-daemon). The write verbs now thread the batch/off deferral to the storage layer's commit sites, which leave writes in the working set for an explicit commit point (bd dolt commit), in server and embedded mode alike. The server-mode default changes spelling, not behavior: it used to resolve tooff(while behaving likeon); it now resolves toon, naming what a default server-mode write has always done. The--dolt-auto-commithelp also stops claimingDefault: off. On a shared server, staging is table-level, so anon-mode writer's commit may sweep up another client's deferred rows — deferral bounds who creates commits, not commit contents.Scope: embedded and direct SQL-server modes. Proxied-server routes never apply auto-commit policy (they short-circuit before it resolves), so batch/off remain inert there — tracked as a follow-up. A deployment that had explicitly configured
dolt.auto-commit: offfrom the old help text note: in server mode that was behaving likeon; it now genuinely stops minting version commits until an explicitbd dolt commit. -
The no-ID "last touched issue" fallback on
bd update/bd closeis now interactive-only (bd-m00pb, #4839). Previously a scriptedbd update $ID ...with an accidentally empty$IDsilently mutated whatever issue was touched last — a real agent session corrupted an unrelated closed bead this way. The missing-ID refusal happens in argument validation, before any store open, migration, or auto-import side effect. The fallback now requires stdin to be a terminal;BD_NON_INTERACTIVE=1andCI=1/truealso disable it. Scripts that intentionally relied on it can setBD_LAST_TOUCHED_FALLBACK=1(or=0to disable the fallback everywhere). Explicit IDs andbd show --currentare unaffected. -
A dated defer now means what it says: the issue returns to the ready front when the date passes (bd-i8qx8).
bd defer --untilandbd update --defersetstatus=deferredplus adefer_untiltimestamp, but nothing ever flipped the status back — so an expired defer stayed invisible tobd readyforever until a human ranbd undefer. One deployment measured 241 issues (including P1s) silently dark this way, regenerating daily from correct-looking automation.Ready-front reads and claims (
bd ready,bd ready --claim,bd list --ready, and the serve/proxied Reader roles) now run a lazy wake sweep first: every issue (and wisp) withstatus=deferredanddefer_until <= nowflips tostatus=open, defer_until=NULL— byte-identical to whatbd undeferwrites, so a later dateless re-defer cannot inherit a stale past date. Each wake records astatus_changedevent (actorbd-defer-wake).What does NOT change: a dateless defer (
bd deferwith no--until,defer_untilNULL) is the indefinite icebox and never auto-wakes —bd undeferremains its only exit. The sweep is a no-op when nothing has expired (no dolt commit is minted), advisory by contract (a ready listing never fails because the sweep could not run — strict--readonlyskips it), and identical in embedded, server, and proxied-server modes. -
bd delete --cascadeno longer marks LIVE issues as deleted in other issues' text (bd-x82so). When the deletion named a wisp, the set used to rewrite[deleted:<id>]citations was computed differently from the set that was actually deleted: dependents reachable only through a wisp root were left in place, and then their neighbours'description,notes,designandacceptance_criteriawere rewritten to say those still-present rows had been deleted.bd wisp gcran exactly this path, because it hardcodes cascade.Text already corrupted by earlier builds is NOT repaired. Those are stored bytes and nothing here scans for them; a
[deleted:<id>]marker naming a row that still exists is a leftover from a pre-fix build. Searching for markers whose id is still present will find them.Three consequences of the same fix, all on the direct and embedded routes and all converging onto what the team-server route already did:
bd delete <wisp> --cascadenow deletes the wisp's dependents in both planes, as--cascadehas always claimed. It previously stopped at the wisp, reported only what it deleted, and gave no sign it had done less than asked. Anyone relying on that under-deletion will see more rows go — andbd wisp gcnow removes durable rows hanging off abandoned wisps.bd delete <wisp>with a durable dependent, unforced, is now refused withissue <id> has dependents not in deletion set. It previously succeeded and silently orphaned the dependent.bd delete <wisp> --forcenow lists that dependent in the orphan report, where it previously reported nothing, and the removed cross-plane edge is counted.
The two set computations are gone: one
DeletionSet, resolved once, is handed to the neighbourhood read, the delete and the rewrite, so they cannot drift apart again. -
bd queryno longer drops matches from anORorNOTquery (bd-pohmh). Your results will change, and they change by getting bigger. To answer an expression the storage filter cannot express, both routes fetchedmax(3 × --limit, 100)rows and applied the expression to those in memory. A match past that window was absent from the page — and the truncation hint said nothing, so the answer looked complete.bd query "type=bug OR label=urgent"over a workspace with more than a hundred issues has been returning an arbitrary prefix of its answer.The window is gone: the expression is now evaluated against every candidate row, the page is the first
--limitMATCHES, and the truncation hint is exact. The cost is real and worth knowing: a broadOR/NOTexpression over a large workspace now reads every row its plain filters admit, where it used to read at most a few hundred. Narrow the expression — the parts of it that ARE plain filters still bound the read — if that matters to you.Two smaller changes ride along.
bd query --offset Nnow works withOR/NOTexpressions, where it used to be refused outright: the offset skips matches, which is only meaningful now that every match is seen.--offsetwith--sortis still refused, with new wording, and so is a malformed expression: both messages now come from one place instead of one per route. -
bd purge --patternandbd prune --patternno longer report success on a malformed glob (bd-pn231). Both routes matched patterns with the error return offilepath.Matchdiscarded, sobd prune --pattern '[' --forceprinted "No closed beads to prune" and exited 0 — indistinguishable from a correct pattern over an empty set. A pattern the glob syntax refuses is now an error naming the pattern, on both routes. -
bd purge --dry-runandbd prune --dry-runno longer fail on sweeps the real run completes (bd-pn231). The preview asked for the refuse-if-any- external-dependent path while the confirmed run asked for the force path, so a dry run could report "has dependents not in deletion set" for a sweep--forcefinishes by orphaning them — and the CLI then swallowed the error and printed zeros. The preview and the run now ask the same question.
Added
-
GET /v0/beads/dependencies/blocking— the blocking decorationbd listprints, over HTTP (bd-5k21g).bd servenow answers?ids=bd-abc&ids=bd-defwith, per requested id, its open blockers, the beads it blocks and its open parent — the derived summarybd listrenders asblocked by:andblocks:, from the sameissueops.BlockingAnnotatorboth CLI routes call.capabilitiesgainsdependencies.blocking.It is not a mode of
GET /v0/beads/dependencies: that one returns stored edge rows and applies nothing, this one applies the status rule and separates the parent edge from the blocking ones. It is also not a page — the number of ids the caller named is what bounds it, so there is nolimitand no cursor. An id that names nothing is annotated bare rather than reported missing, which is the same answer the CLI gives. -
GET /v0/beads/dependencies/tree— thebd dep treewalk over HTTP (bd-lx5iu).bd servenow answers a recursive walk from one root —?root_id=bd-abc&direction=both&max_depth=3&status=open— with the flatTreeNodelistbd dep tree --jsonemits, from the sameissueops.TreeWalkerboth CLI routes call.capabilitiesgainsdependencies.tree.It is a sibling of
GET /v0/beads/dependenciesrather than a mode of it: that one answers raw stored edge rows for many anchors at one hop, this one recurses from a single anchor. Aroot_idthat names nothing is a 404 here, where an unknownissue_idthere is reported inmissing— one anchor leaves no other answer to preserve. There is nomax_rows: the defensive cap is a CLI circuit breaker and refusing a whole answer is not something this surface offers a remote client. -
GET /v0/beads/issues:query— thebd queryexpression language over HTTP (bd-pohmh).bd servenow answers boolean expressions —?q=type%3Dbug+OR+label%3Durgent— with the same page shape the ready listing returns, under the same completeness guarantee as the CLI, because both call oneissueops.Querier. It is the only operation on the surface that takes a disjunction; every filter parameter ofGET /v0/beads/issuesnarrows. There is no cursor and nooffset: a predicate query's matching set is assembled outside the database, so there is no keyset position to encode.capabilitiesgainsissues.query. -
POST /v0/beads/issues:delete— deleting named beads over HTTP (bd-x82so).bd servegains the second destructive operation on its surface: a body ofidspluscascade,forceanddry_run, answering with the counts and the orphan list. It calls the sameissueops.Deleterbd deletecalls, so the dependents guard, the all-or-nothing id resolution and the reference rewrite are the library's rather than the handler's — the endpoint cannot orphan a graph by omission.cascadeandforceboth default false, which is the guarded mode.capabilitiesgainsissues.delete. -
POST /v0/beads/issues:batchCreate— creating many issues over HTTP (bd-lu170).bd servegains the second write on its surface and the first one that creates rows: a request carrying anactorand up to 100 items is created as ONE transaction, or none of it is. It runs on the newissueops.BatchCreatorrole that bothbd create --fileroutes now call, andcapabilitiesgainsissues.batchCreate.The server assigns every id. There is no
idmember on an item, so this operation can never adopt or overwrite a stored row; the generated ids come back initems, in request order, which is the only place a client can learn them.bd importremains the upsert surface and is not published here.A dependency target may name an issue the workspace holds, an item created EARLIER in the same request, an
external:reference, or an id belonging to another repository. Anything else is a400and nothing is created. Hooks do not fire and the per-command auto-commit machinery does not run, exactly as forPOST /v0/beads/issues/{id}:claim. -
POST /v0/beads/issues:sweep— bulk clearance of closed beads over HTTP (bd-pn231). The operation behindbd purge(tier: ephemeral) andbd prune(tier: durable), on the newissueops.Sweeperrole both CLI routes now call.capabilitiesgainsissues.sweep.This is the first DESTRUCTIVE operation on the surface, and nothing it deletes comes back.
bd servebinds loopback, and its bearer — optional, and where configured a single shared token admitting a client to the whole surface — grants no narrower right, so anyone who can reach the port with a credential it accepts can now clear closed beads:--helpgained a DESTRUCTIVE OPERATIONS section and the--allow-non-loopbackwarning says so. Adurablesweep with neither a cutoff nor a pattern is refused by the role itself rather than by the handler, anddry_run: truecosts the same request without writing anything.protect_referenceddefaults totruehere, where the CLI's equivalent (--ignore-references) is opt-out. The local flag and the remote member therefore disagree on purpose: being authenticated here says nothing about whether this particular deletion was meant — one shared token admits a client to everything published — so a remote caller who omits a member should not get a weaker guard than the operator typing the same sweep locally. Sendprotect_referenced: falseto match the CLI default. -
GET /v0/beads/configandGET /v0/beads/config/{key}— the workspace's stored settings over HTTP (bd-kzepq).bd servenow answers for the settings planebd config listandbd config getread. Both operations run on the newissueops.WorkspaceConfigrole the CLI reaches through the same accessor, andcapabilitiesgainsconfig.listandconfig.get.A setting whose KEY marks it as credential-bearing — the name contains
token,secret,passwordor an API-key spelling, whichnotion.tokendoes — is published withredacted: trueand novalue. Withheld values are OMITTED rather than masked, so a client cannot mistake a placeholder for configuration. The CLI is unchanged and still prints stored values in full: its caller already holds the database, while redaction is the whole control on this surface — a bearer here is optional and, where configured, shared and surface-wide, so it cannot withhold one value from one caller.There is no HTTP WRITE, deliberately.
bd config setroutes most keys toconfig.yamlor to git config before the database is ever reached, and both live on the client's filesystem, so a server-side write of (say)export.autowould return success and land a row nothing reads. The multi-source views —bd config show,drift,apply,validate— are off the role and off the wire for the same reason. -
bd serveruns on a registered storage backend. A downstream distribution that registers a backend (github.com/steveyegge/beads/backend.Register) could already use it from every ordinarybdcommand —bd list,bd createand friends dispatch the store open through the registry — butbd servealone reimplemented a creation path of its own, hard-wired to Dolt's SQL wire, and refused the workspace before it got there. It now uses the store the root command already opened, through the same registry dispatch: zero creation calls of its own, so there is one creation path rather than two. The two issue roles are taken from BENEATH the workspace's hook decorator, keeping the documented "hooks do not fire" contract (httpapi.Listenrefuses a hook-firing role rather than trusting the caller), and the store's lifecycle stays where it was — opened and closed by the root command, closed only after the server has drained. The startup line names the source (db=roles) and the backend (mode="<name> (registered backend)").The permanent refusal is unchanged and unweakened: an embedded-Dolt workspace is still refused, because its commit protocol runs outside the SQL transaction and this server's per-request atomicity would be a lie there. The classification consults the registry before any Dolt-mode signal, which is the order the store open already resolves them in — and which also fixes a latent
CGO_ENABLED=0bug where a registered workspace was handed to the Dolt provider and either failed with a misleading Dolt error or connected to a defaulted host and served the wrong database.
Changed
-
BREAKING:
bd config listandGET /v0/beads/configno longer enumerate thekv.plane, which is wherebd remembermemories live. Memories and genericbd kvvalues are stored as config rows underkv.— user data riding in the settings table because there is one table, not because they are settings — and both doors onto the settings plane were listing them with their values. On the HTTP door that meant an unauthenticatedGET /v0/beads/confighanded every stored memory to anything that could reach the port, and the surface's redaction is no defence there: it decides on the KEY name, while a memory's content is in the VALUE, so a memory containing a credential under an innocuous slug was served verbatim.The exclusion is in the shared role both doors call, not in the HTTP handler, so the CLI and the API cannot drift apart on what a setting is. The whole
kv.prefix goes, not justkv.memory..What still works:
bd memories,bd recallandbd kv listare unaffected — they read the store directly and are the purpose-built views over those rows. So arebd prime's memory injection and export's memory extraction. Point access is unchanged and deliberately so:bd config get kv.fooandGET /v0/beads/config/kv.foostill answer a key named exactly, andbd config set/bd config unsetstill write and remove one. The enumeration was what made a memory discoverable; naming one you already know is a different question, and refusing it would take away the escape hatch of removing a wedged memory throughbd config unset.What breaks: a script parsing
bd config listor its--jsonoutput forkv.rows. Generickv.rows have no other HTTP view today. -
BREAKING:
bd --readonly serveis now refused instead of binding a server that cannot do what it advertises. On a Dolt SQL-server workspace this previously bound a fully functional, fully writable server — the flag was a silent no-op there — so anyone scriptingbd --readonly serveas a "safe" read server loses it on upgrade and should drop the flag. The advertised capability set is a property of the build and includes the issue-claim operation, so under strict readonly the two database sources degraded differently and silently: a registered backend bound on its read-only store and answered every claim with an opaque 500 while still advertisingissues.claim, and a Dolt SQL-server workspace built its own writable provider and let every claim land, so the flag bought nothing.bd servenow refuses to start under--readonly(orreadonlyin config), before it resolves the workspace, so the answer is the same on both.
Fixed
-
GET /v0/beads/contextandbd contextno longer describe every workspace as Dolt. The shared identity projection hardcodedbackend: doltand copieddolt_modeanddatabaseunconditionally — and both of those default rather than fail, so a workspace on a registered backend was reported asbackend="dolt",dolt_mode="embedded",database="beads": a confident description of a topology it is not on, on the one endpoint automation is told to trust for a server's identity. The backend is now named as the store open resolves it, and the two Dolt-derived values are reported only for the Dolt backend; a registered backend reports the empty string for both, which is the only valuebdcan assert about a backend it does not implement. No wire field is renamed, retyped or dropped — both remain required strings, and thev0shape is unchanged. -
Public surface for out-of-tree storage backends (bd-h3dib.2). The storage backend contract and its conformance suite are now importable by external Go modules — the conformance-gated external-backend path promised on #4415. The new
github.com/steveyegge/beads/backendpackage exports, by type alias, the engine interface (backend.DoltStorage) and every type its 164 method signatures reach, the sentinel errors the contract requires by identity, and thin wrappers over the backend registry (backend.Register); the suite moved frominternal/storage/conformancetogithub.com/steveyegge/beads/backend/conformanceunchanged, so an external backend proves itself with the sameconformance.RunAllthe embedded-Dolt reference runs in CI. Aliases mean identical types: a store compiled against the public names satisfies the internal interface, anderrors.Ismatches across the module boundary. A reflection-based drift guard (backend.TestPublicSurfaceComplete) fails in-tree if a contract change ever reaches an internal type with no public alias. Stability: EXPERIMENTAL — the contract still evolves; pin an exact version and re-run the conformance suite on every bump. -
bd serve— the beads work surface over HTTP (bd-serve v0). Automation clients and orchestrators that fork abdsubprocess per call can now hold one connection instead.bd servebinds loopback and answers six OpenAPI-specified operations:GET /healthz,GET /v0/beads/context,GET /v0/beads/ready,GET /v0/beads/issues,GET /v0/beads/issues/{id}, and the one write,POST /v0/beads/issues/{id}:claim. The wire contract isinternal/httpapi/spec/openapi.v0.yaml; types are generated from it andmake api-checkfails a change that edits one without the other.GET /v0/beads/contextreports which operations the running build actually implements, derived from the registered handlers, so a release cut mid-slice cannot advertise one that does not work.The reads run on
issueops.Reader, the same rolebd show --jsonreaches, so filter construction, workspace config, default limits and the wisp fallback happen inside the role rather than being re-performed per front door. The exact scope of that property — what is shared, what is machine-enforced and by which lint rule, and what is not enforced — is stated in full inissueops.Reader's doc comment and in engdocs/design/bd-serve-v0.md; it is narrower than "the CLI and the API cannot disagree", and the difference is written down.Errors are typed. Every non-2xx is an RFC 9457
problem+jsondocument with a machine-readablecode(invalid_argument,invalid_cursor,not_found,already_claimed,not_claimable,busy,db_unavailable,internal), one frozen HTTP status per code, andRetry-Afteron the retryable ones. A client that classified claim conflicts by substring-matching error text should switch to the typed 409:assigneeandissue_statuscome from a read inside the losing transaction, never from parsing the sentinel's prose. A 5xxdetailis a fixed string per code — driver errors embed the DSN — and the body'srequest_idcorrelates to the one log line that carries the real error.Paging is an opaque keyset cursor on
GET /v0/beads/issues(GET /v0/beads/readyhas none: its sort policies admit no keyset predicate). The token holds a position and a private encoding version and nothing else, so it does not expire, survives a restart, and has exactly one failure recovery — restart paging without it. It also carries no filters, so a cursor reused under changed filters is not refused and silently resumes from the old position; repeat every filter verbatim for a traversal.Deliberate omissions, stated as contract rather than gaps. No authentication and no TLS — the trust model is the loopback boundary the database already relies on, and
--allow-non-loopbackis an operator decision that additionally refuses unlimited (limit=0) reads. A DNS-rebindingHostallowlist with no off switch. Hooks do not fire on an HTTP claim (a user-controlled subprocess per mutation is an unbounded latency multiplier and an orphaned child at shutdown). The per-command auto-commit machinery does not run: durability is per request, and an idempotent re-claim by the current holder writes no commit at all, so a polling client cannot mint empty storage commits. An HTTPactoris caller-asserted provenance for the audit trail, not authenticated identity — the same thing--actorhas always been.Embedded-Dolt workspaces are refused permanently: that backend commits outside the SQL transaction, so the per-request atomicity this contract states could not hold there.
Operators: pass an explicit port. The default
--addr 127.0.0.1:0takes an ephemeral one and carries no mutual exclusion — N servers run side by side on different ports. Probe readiness withGET /v0/beads/ready?limit=1;/healthzis liveness only and stays green while the database is unreachable. Deployment, the connection budget for a shareddolt sql-server, the request-log format and the ambiguous-shutdown re-claim recovery are in engdocs/SERVE_RUNBOOK.md. -
Replica-aware leases:
bd reclaimno longer reverts a lease another replica granted (wy-jpd3.7). A lease is only meaningful on the replica that granted it — the other machine's liveness view is stale by up to one sync interval — so each lease now records its granting node (leases.granted_node, ignored migration 0016;types.Issue.LeaseGrantedNode, which rides the JSONL interchange so an imported lease keeps its provenance).bd reclaimskips a lease that positively names a different replica, naming each skip on stderr, and the newbd reclaim --any-replica(types.ReclaimFilter.AnyReplica) is the escape hatch for a replica that is permanently gone.bd showannotates a lease granted elsewhere.The guard is opt-in and fail-open. It arms only where you set the new
node_idconfig key (BEADS_NODE_ID/BD_NODE_ID, orbd config set node_id <name>, which writes the per-machine~/.config/bd/config.yaml— anode_idin the git-tracked project.beads/config.yamlwould give every clone the same identity and leave the guard armed but inert). There is deliberately no hostname fallback: the hostname names the client process's machine, not the store, so on a shared or remote dolt sql-server — where many hosts are clients of ONE store and there is no sync interval to defend against — it would stop a supervisor reaping any worker's lease at all. Unset (the default), and a lease of unknown provenance, behave exactly as before, so an upgrade can never strand a lease the reaper could previously recover. Also documents the invariant the guard cannot enforce: grace window > sync interval, and lease TTL > sync interval. -
bd sync— one verb for the federation loop (wy-jpd3.4). Every multi-machine beads deployment hand-rolls the same sequence in shell; this ships it.bd sync [--remote <name>] [--attempts N]pulls, checks for merge conflicts, runs the fullis_blockedrecompute, and pushes — retrying a bounded number of times (default 3) when another replica wins the push race. Two properties are the point of the verb. Conflicts are detected positively, from the merge's own captured conflict rows and fromdolt_conflicts, never inferred from the pull's exit status: a pull fails for plenty of reasons that are not conflicts, and a settled merge that is conflicted aborts and leavesdolt_conflictsempty, so an exit-status guess invents phantom conflicts and misses real ones. And a conflict sync cannot settle is never resolved by picking a side: it halts before recomputing or pushing and exits 2, with no--strategy-style override to make it do otherwise. (The pull underneath still auto-settles the convergent classes it always has — machine-local metadata, audit-only dependency rows, LWW on issue cells; anything past those halts.) The halt message reports which state the halt left behind, read from which detection source fired rather than assumed: the SQL pull route aborts the merge and restores the working set, while the CLI/git-protocol route deliberately leaves the conflict rows live. The recompute between pull and push is not bookkeeping either:is_blockedis denormalized, so a merge that brings in a dependency edge from another replica leavesbd readystale until it runs. It runs unconditionally, on every attempt —RecomputeAllBlockedis precisely the repair that does not depend on a merge advancing HEAD, so gating it on "did anything merge" would mean a column left stale by a hand-resolved conflict (a statebd synccreates by exiting 2) is never repaired again while every tick reports success. Exit codes are the machine contract, so a sync timer can branch without parsing output:0synced,1error,2merge conflict (halted, nothing pushed),3push-race retries exhausted (transient — retry next tick).--jsonreports the outcome as{"status", "attempts", "conflicts", "conflicts_live", "rows_corrected", "pushed"}on every non-error exit; exit 1 emits bd's standard{"error": ...}envelope. A confirmed-no-remote rig exits 0 with the same guidancebd dolt pushprints;dolt.local-onlyandno-pushare honored. -
bd reclaimscope filters (wy-jpd3.3).bd reclaimgained--label/--label-any/--exclude-label/--assignee/--id, mirroring the claim-side label surface (bd ready --claim), so a supervisor can scope its reaper to exactly the partition it claims from. Filters AND-combine and never widen the stale set. This matters on a federated deployment: each replica's view of another machine's liveness is stale by up to one sync interval, so an unscoped reaper on one machine can revert a unit that is alive on the machine that granted its lease — point each supervisor's reclaim at its own claim partition and that cannot happen. A scope flag supplied with no usable value (e.g.--label "$LANE"withLANEunset) is a hard error rather than a silent degrade into a global sweep, and the builder fails closed (1=0) for programmatic callers.bd reclaim --jsonnow reports ascopedboolean so a reclaim log distinguishes a scoped sweep from a global one. -
Every command that had a role now reaches it through the accessor, on both routes (facade waves 1-4). This is the close of the programme: twenty-three capability accessors on the storage substrate, each answering a role interface in the leaf package
issueops, each with a backend-independent conformance suite run against the Dolt server store, the embedded Dolt store and the unit-of-work provider, and each reached by the CLI's direct route, the CLI's--proxied-serverroute and — where the capability is published — one HTTP operation, all calling the same role.bd servepublishes sixteen capability-bearing operations, twelve of them added by the programme, every one written intointernal/httpapi/spec/openapi.v0.yamlbefore its handler existed.What did NOT get a role is as deliberate as what did.
bd showandbd closewere already behindReaderandBatchCloser/Lifecycleon both routes, so there was nothing to converge.bd versionprints build information and a role is an interface onto a substrate — the one part of it that touches state, the recorded-version marker, gotVersionReconcilerinstead. Most ofbd initCREATES the substrate a role would be reached through; only the workspace identity is reachable as a store capability, and that is whatBootstrapperandInitVerifierare.bd create --graphis deferred on the record: it is an UPSERT with caller-supplied symbolic names andBatchCreatoris create-only with server-assigned ids, so folding them would have meant one role with two incompatible id policies. -
A shared semantic contract for every issue role (bd-yby99). Seven of the eight role interfaces in
issueopsnow have a backend-independent conformance suite inbackend/conformance, run against the Dolt server store, the embedded Dolt store, and the unit-of-work provider. One hundred and twenty-nine cases coverReader,Relations,Commenter,DependencyEditor,ReadyClaimer,BatchCloserandLifecycle— the last spanning Create, Update, Close and Reopen. The unit-of-work leg runs 127 of them: the two staging cases assert which concrete Dolt tables a commit staged, which that provider has no way to observe. Each case is written against the promise stated in the role's doc comment, cited by file and line, rather than against any implementation's current behaviour, so the doc comment is the artefact under test as much as the code is.Read the three legs for what they are. The Dolt and embedded-Dolt stores share one validate/execute body for six of the roles and the entire implementation for
Reader, so a green run on all three is two readings of the contract plus a wrapper-and-engine check, not three independent votes. The unit-of-work provider is the only separately written body, and every divergence found so far where one backend disagreed with another rather than all three with the doc has surfaced there.Where an implementation contradicts its own doc comment the case still asserts what the doc says, and the disagreeing backend is parked at its wiring site with a greppable
KNOWN DIVERGENCE <bead>skip, so the agreeing backends stay pinned. Thirty-one findings have come out of that, all children ofbd-yby99: seven divergences, where the implementations disagreed, and twenty-four spec gaps, where the doc was silent rather than wrong and the case carried an in-fileSPEC-GAP <bead>marker instead of an invented assertion.Every parked case now runs. The three findings that had a backend parked are adjudicated and fixed, so the five
KNOWN DIVERGENCEskips are gone and all three legs run their full set with zero skips: an invalidClaimNextsort policy now matchesErrValidation(bd-yby99.18), a reparent on the unit-of-work provider now replaces every parent edge (bd-yby99.26), and a dependency removal on that provider now reaches the ephemeral plane (bd-yby99.17). Each has its own entry below; none was resolved by weakening a case.Twenty-two of the spec gaps are adjudicated as well. In each the leaf doc gained the promise it had been missing and the contract case was tightened to assert it, in that order, because the doc is the spec and a case may never assert more than the doc promises. Ten of the adjudications moved production code rather than only the doc —
bd-ocrn7,.3,.4,.7,.8,.17,.18,.19,.20and.26— and each is a user-visible change with its own entry below, not a quiet edit made to turn a case green.Three findings remain open, and none is parked — no case skips anywhere.
bd-yby99.9is the doc's own admitted silence, named in the leaf text so a caller does not read the silence as a promise: the dependency-existence refusals still carry no error identity.bd-yby99.1is withbd-soezdfor measurement rather than adjudication.bd-yby99.30records a CLI retry-safety property thebd-yby99.19decision traded away (see below). The empty-string label question (bd-yby99.28,bd-yby99.29) is closed, not open: the entry is now dropped on every backend andLabelPatchsays so. Five duplicated per-backend test files were deleted outright and a sixth trimmed, their scenarios folded into the shared cases; the Dolt-only facts they also pinned — history-entry message spellings, working-set cleanliness, the GH#2455 no-op removal sweep — stay Dolt-only in persistence tests.
Changed
-
bd delete --forceon a TEAM SERVER now orphans dependents instead of deleting them (bd-x82so). Read this one before you upgrade a team-server script.Against a proxied server,
bd delete X --forceused to delete X and its whole dependent subtree, and--cascadewas refused outright with "not supported in proxied-server mode (delete always cascades)". There was no way to delete one bead on a team server without taking everything that depended on it, and asking for the safer behaviour was an error.Both routes now mean the same three things by the same two flags, which are the local database's meanings, unchanged:
you type you get bd delete XREFUSED if anything outside the request depends on X bd delete X --forceX is deleted; its dependents survive, ORPHANED bd delete X --cascade --forceX and its whole dependent subtree are deleted A team-server script that relied on the implicit cascade will start leaving orphans. Add
--cascadeto it. The proxied--jsonresult gainsorphaned_issuesso a script can see them; a cascade leaves it null. -
Proxied
bd initADOPTS an existing project identity instead of overwriting it (bd-zl3u8). This one silently corrupted shared databases. Against a team server whose database another rig had already identified,bd init --proxied-serverwrote its own locally-derived issue prefix and project id straight over the stored pair — renaming every id the co-tenant was about to mint. It now reads the identity first and prints "Adopted project identity from existing database", which is what the direct route has always done. There is no flag that restores the overwrite.Two consequences ride along.
bd initno longer fills in a missing project id on a substrate that already carries an issue prefix: half-identified is now adopted as it stands rather than completed, because the guard that stops the overwrite above cannot tell a half-provisioned workspace from a shared one mid-write. Re-identifying is an explicit act with no command yet; if you have such a workspace, it keeps working and it stays half-identified. Andbd initwithBEADS_DIRpointing outside the repository now records a project id, taken from that workspace's ownmetadata.json, where it previously recorded none and left exactly the state the new refusal will not complete. -
bd listandbd childrenprint blocker ids in ASCENDING ORDER (bd-5k21g). Theblocked by:andblocks:ids in compact and agent output came out in query order, which is map-iteration and query-plan dependent, so an unchanged workspace could print different bytes on two consecutive runs. They are now sorted ascending with repeats collapsed, on both routes. Only rows with two or more live blockers change; a diff-based script that pinned the old order was pinning an order the database never promised. -
bd delete <one-id>without--forcenow REFUSES when the bead has an outside dependent, instead of printing a preview and exiting 0 (bd-x82so). This is the direct route converging with itself: the multi-id path and--dry-runhave always refused here, and only the unconfirmed one-id preview did not. The refusal names the bead and says to use--cascadeor--force, which is the same sentence the other two paths already printed. -
bd deleterewrites text references INSIDE the delete transaction (bd-x82so). The direct route deleted the rows in one transaction and then rewrote[deleted:ID]into the neighbouring beads' descriptions afterwards, discarding every update error it got; a failure in the window left a workspace whose beads were gone and whose descriptions still cited them by id. The whole operation — the existence probe, the dependents guard, the cascade expansion, the deletion and the rewrite — is now one transaction on the newissueops.Deleterrole, shared by both routes and bybd serve.The trade, said out loud: the transaction is now as large as the deletion plus its graph neighbourhood, so a delete whose neighbourhood is big enough to exceed the backend's write timeout fails whole instead of deleting the beads and leaving the text stale. Split a very large
--from-filebatch. -
bd deleterefuses the whole request when any id names no bead (bd-x82so), on both routes and under--dry-run. The multi-id path already did; the guarantee is now the role's, so nothing partial is deleted before the typo is reported. -
bd dep tree --direction=bothnow sees ONE database state (bd-lx5iu). Both routes made two independent reads — the dependency walk and the dependent walk — with no transaction spanning them, so an edge added between them could leave the two halves of the picture describing different graphs. The whole walk, both directions, now runs inside one transaction on the newissueops.TreeWalkerrole. -
bd dep treeon a team server resolves partial ids and honors--max-rows(bd-lx5iu). Two things the--proxied-serverroute did not do and the direct route did.bd dep tree a1b2used to fail there: the argument went to storage verbatim, so the abbreviation that worked on a direct workspace did not work on a shared one. It resolves now, and an id that resolves to nothing reports the same lookup failure the direct route reports.bd dep tree X --max-rows Nused to be refused outright — "not supported in proxied-server mode" — because the unit-of-work path threaded no cap. The cap now rides the role's request, so all three backends enforce it and the flag means the same thing wherever the command runs. It is still POST-HOC: a tree walk has no query filter to thread a cap through, so the full tree is built and then counted. -
bd dep tree --show-all-pathsis documented as the no-op it always was (bd-lx5iu). Nothing has ever read the flag. It was accepted and passed down to a walk that ignored it, so a node reachable by two paths has always been shown once, under the first path that reached it. The flag is still accepted so no script breaks, its help text now says it is ignored, and the one-visit rule is a stated promise of the role rather than an accident of the walk.TreeNode'struncatedmember is dead in the same way: it is alwaysfalse, because a node beyond--max-depthis absent from the answer rather than present and flagged. -
bd purgeandbd pruneselect and delete in ONE transaction (bd-pn231). The direct route used to search in one transaction and delete in another, so a bead closed between the two could be counted and not deleted, or deleted and not counted. Both routes now run the whole sweep as one act on the newissueops.Sweeperrole, and the count a sweep reports is the set it deleted.The trade is worth knowing before you run a very large purge on a team server. One transaction means the Dolt server backend can no longer batch wisp deletions 200 at a time, so a purge big enough to exceed Dolt's write timeout now fails whole instead of deleting part of the workspace and reporting nothing. Sweep in slices (
--pattern,--closed-before) if you are clearing a very large backlog.The version-control entry for a sweep is now
bd: sweep <n> <tier> bead(s)on both routes, where the proxied route wrotebd: prune <n> bead(s)and the direct route wrotebd: delete <n> issue(s), naming neither the command nor the tier. Scripts that grep commit messages for the old spellings need updating. -
bd list --max-rowsreports its own malformed value first (bd-b34o7). The row cap now rides the list request rather than being stamped onto the filter after it was built, which moves the flag's validation ahead of the filter's.bd list --max-rows -1 --status bogusnow reports the--max-rowsusage error where it used to report the invalid status; the exit code is unchanged and it takes two bad arguments to reach. -
bd create --fileis all or nothing, and its plan-wide flags now mean something (bd-lu170). Both routes build oneissueops.CreateBatchRequestand ask for the newBatchCreatorrole, so a markdown plan is created as one act with one history entry on either.A file the workspace refuses now creates NOTHING. Each template goes through the same validation a single
bd creategoes through — the workspace's configured types and statuses, the field lengths, the create-only guard — and a template that fails takes the whole file down with it. Re-running a file that used to fail can therefore give a different outcome than it did before, because the run before it may have landed rows this one refuses to duplicate; checkbd listbefore re-running a plan that errored on an older version.A declared dependency on an id that does not exist is now an error rather than a silently dropped edge. The direct route used to create the issues and leave the edge out, with nothing on stdout or stderr saying so, so a plan file with a typo produced a graph that looked complete and was not. An
external:reference and an id belonging to another repository are still written, exactly asbd dep addaccepts them; only a target that shares the workspace's own prefix and names no row is refused.--ephemeral,--no-history,--mol-typeand--validateare honoured on the direct route. All four were accepted and silently ignored there while the proxied route acted on them, sobd create --file plan.md --ephemeralcreated durable issues on a local workspace and wisps on a team server.--validate(andvalidation.on-create) now lints every template on both routes, which is the policy a single-issue create has always applied. Issues created from a file also carrycreated_byandowner, as a single-issue create does.bd create --file --jsonemits the STORED rows on both routes. Each entry is the post-create snapshot the role reads back — withowner,created_byand dependency records carrying their owncreated_at,created_byandmetadata— where the direct route used to marshal the structs it had built in memory. Additive: no member was removed, and both routes now emit one shape.Proxied
--fileloses itsconfig.yamlfallback fortypes.custom, the same convergence onto the direct route's database-only vocabulary that landed for single-issue create (bd-7oyh5).bd create --graphis untouched: an upsert over a declared shape is a different contract, and it gets its own role when it gets one. -
Proxied
bd ready --json --limit Npublishespagination.total(bd-s10oa). UnderBD_JSON_ENVELOPE=1the direct route has always carried the size of the ready front beside a truncated page; the proxied route emitted nototalkey at all, so the same script read a number against a local workspace and nothing against a team server. Both routes now answer from the newissueops.ReadyCounterrole. The count is only asked for when the page came back full, so an untruncated listing costs nothing extra. -
Proxied
bd dep list a b creports ids that name nothing (bd-nhsno). The route handed its raw arguments to the batch read, whose answer simply has no entry for an id nothing matched, so a typo printed<id> has no dependencies— a clean graph — instead of a warning. It now printswarning: no issue found: <id> (skipped)on stderr, the line the direct route has always printed, and omits the anchor from stdout. Emitted in--jsonmode too, on stderr, so the document stays a flat array.Two smaller shape changes ride along, on both routes: a repeated anchor is answered ONCE, at its first mention, rather than twice; and
bd dep list --type X a bprints<id> has no dependenciesinstead of a section header with no rows under it for an anchor whose every edge the filter rejected. -
bd status --assignedreports why it failed (bd-4ze25). The direct route swallowed every underlying error and printed the causelessfailed to get assigned statistics. Both routes now report the same underlying error. Relatedly, the proxied--no-blockedwarning is derived from the ANSWER rather than printed unconditionally before the query, so it is correct for any backend and disappears by itself when a backend gains a fast path. -
bd dep cyclesoutput is deterministic, and no longer shortens a cycle it cannot fully describe (bd-wfkbv). Two changes, both visible in bytes.The report is now CANONICAL: each cycle's members are rotated so the lowest id comes first, and the cycles are sorted against each other. Two runs against an unchanged database previously disagreed — the walk iterated a Go map, so both the order of the cycles and each one's starting point moved between runs,
--jsonincluded, and on a graph with overlapping cycles even the SET of cycles could differ. Diffing two snapshots is now meaningful.A cycle whose member has no row behind it is now reported HONESTLY. Members that could not be looked up were silently dropped from the path, so a three-node cycle rendered as a two-node one and looked complete, and a cycle none of whose members could be looked up vanished from the report and from the
Found N dependency cyclescount. Every member is now carried with its id, its description is omitted rather than the member, and the cycle is marked partial. The count no longer shrinks because rows went missing.--jsontherefore emits a NEW SHAPE: an array of{"members": [{"id", "issue"?}], "partial": bool}where it used to emit an array of arrays of issues. Theissuemember is the same issue object as before and is absent — never null — for a member this workspace holds no record of. Scripts that readbd dep cycles --jsonneed updating.The post-add cycle warning that
bd dep add,bd dep --blocksandbd linkprint is the same sweep and gains the same two properties, on both the direct and the proxied route. -
The v0 HTTP surface reaches twelve operations (facade wave 2). This release adds six:
GET /v0/beads/stats(bd-4ze25),GET /v0/beads/dependencies/cycles(bd-wfkbv),GET /v0/beads/dependencies(bd-nhsno),GET /v0/beads/ready:count(bd-s10oa) and the two config reads (bd-kzepq). Every one answers from the SAMEissueopsrole itsbdcommand reaches, so the two surfaces cannot drift: the operation is written intointernal/httpapi/spec/openapi.v0.yamlfirst and the wire types are generated from it.capabilitiesnow carriesready.list,ready.count,issues.list,issues.get,issues.claim,stats.get,config.list,config.get,dependencies.cycles,dependencies.list. -
GET /v0/beads/stats— the workspace summary over HTTP (bd-4ze25). The same envelopebd status --jsonprints, minusrecent_activity, which no shipped code path populates.skip_blockedis a HINT: a backend with no cheaper path answers with the full numbers and says so throughblocked_count_skipped, which is derived from the answer rather than echoed from the request.assigneescopes the summary to one actor and is refused when empty rather than answering with the unassigned rows. -
GET /v0/beads/dependencies— stored edge rows for several issues at once (bd-nhsno). The shapebd dep list a b c --jsonemits. An id that names nothing is reported in the response'smissingmember rather than turning the whole call into a 404, so a batch keeps the answers for the ids that WERE found; an edge whose target this database holds no row for is still an edge and is returned as stored. -
GET /v0/beads/ready:count— the size of the ready front (bd-s10oa). Takes the same filter vocabulary asGET /v0/beads/ready, decoded once by the same code so the two cannot admit different parameters, and takes nolimitand nosort: a cardinality has no page and no order. -
bd servepublishesGET /v0/beads/dependencies/cycles(bd-wfkbv). The cycle sweep is now an HTTP operation as well as a command, answering from the same role, andcapabilitiesgainsdependencies.cycles. It takes no parameters and is not paginated: truncating would shrink the count, which is the number an operator acts on.bd linkon a team server also runs its cycle sweep and its title lookups AFTER the write commits rather than inside it, so the warning describes a graph other clients can see. -
bd countis one implementation again (bd-m8hn7). The command had two: the direct route opened its own store and the proxied route re-parsed the same flags against a unit of work, and each independently loaded the workspace list configuration before applying--include-infra. The cardinality contractbd countkeeps withbd listwas therefore asserted once and implemented twice. Both routes now go through the newissueops.Counterrole, which builds its filter with the same shared builderbd listuses. Text and--jsonoutput are unchanged on both routes — the committed protocol corpus fixture forbd countis byte-identical — so this is a change you should only notice if the two routes previously disagreed. Two behaviours are now written down as promises rather than left as accidents: an unrecognised--statusor--typestill matches nothing and answers0rather than refusing (wherebd listvalidates both), and a grouped count'sTotalis computed independently of its buckets, so overlapping dimensions such as labels do not sum to it. -
Proxied
bd create,bd reopenandbd updateemit the same--jsonshape as their direct counterparts (bd-7oyh5, bd-1f5a2, bd-xt6de). Each of the three now answers from the hydrated post-state snapshot theissueops.Lifecyclerole returns instead of a bare row read, so all three gained thelabelsfield they were silently dropping, and — as on the direct route — dependency records are not included. Scripts that read proxied output should expect the direct route's documented shape; nothing was removed.bd update --claim --jsonis the one exception and still strips labels. -
Proxied multi-id
bd reopenrecords one history entry per id (bd-1f5a2). It wrote a single combined entry covering every id in the batch; the direct route has always written one per id, and both routes now do. On a team server abd reopen a b cis consequently three round trips and three Dolt commits rather than one, which a script reopening a large batch will feel. -
Proxied
bd createvalidates the way the direct route validates (bd-7oyh5). Its custom issue-type check no longer falls back toconfig.yamlwhen the database has no custom types, its explicit-id prefix guard no longer consults the YAML prefix overlay, and its--type,--statusand prefix refusals are worded as the role words them. The direct route has never had either fallback, so this is convergence onto the stricter of the two. The version-control entry a proxied create records also changes text, frombd: create <id>tocreate issue: the role publishes no field for a caller-supplied label, and no test asserted either string. -
Proxied
bd updateerror messages no longer name the stage that failed (bd-xt6de). "opening unit of work" and "committing" collapse into the generic per-id update failure, and an update whose commit fails with a context cancellation now aborts the batch instead of recording a per-id verdict for it. This matches the choicebd update --claimalready made when it moved to the role. Exit codes are unchanged. -
An empty-string label is dropped rather than stored (bd-yby99.29). Adding or replacing labels with an empty value wrote a
labelsrow keyed on''on the Dolt-backed stores and dropped it on the unit-of-work one, so the same edit left different rows depending on which route served it. Dropping wins on both routes now: an edit carrying only an empty value changes nothing and reports no change, and an empty value alongside real ones drops only itself rather than failing the edit. A row that renders as nothing and matches nothing was never worth storing, and refusing the whole update would have let one stray value sink an otherwise-good multi-label edit. An empty row already stored is left alone by add and remove, and cleared by a replace that omits it — ordinary set behaviour, not a migration, so nothing sweeps existing data. -
An invalid sort policy is now a typed validation refusal (bd-yby99.18). Asking for a sort the ready query does not have —
--sort newest, or aClaimNextsort on a batch close — was refused with a bare error carrying no sentinel, on all three backends. A caller doingerrors.Is(err, issueops.ErrValidation)to separate "you asked for something impossible" from "the database is unwell" classified it as a backend failure, which is the wrong half of the role's own error trichotomy. It now wrapsErrValidation. The message text is byte-identical — the wrap uses%.0wdeliberately — so the HTTP surface that prefix-matches it to render a 400 rather than a 500, and every script reading the printed line, are unaffected. -
A batch close that changed nothing no longer claims work or records history (bd-yby99.19).
BatchClosercouplesClaimNextto "at least one item closed", and "closed" was being read as "the item returned no error" — which an already-closed item does. A batch whose items were all already closed therefore mutated nothing and still handed out a claim and wrote a history entry. Landing now means changed: an all-idempotent batch earns no claim and records no entry. A batch that closed even one item is unaffected.This has a cost worth stating plainly, tracked as
bd-yby99.30. An agent that closed an issue, crashed before receiving its next work item, and retriedbd close <id> --claim-nextused to get work from the retry; it now gets nothing, because the retry closes nothing. That retry-safety property was deliberate, and the way to get it back without re-coupling a claim to a no-op is forcmd/bdto callReadyClaimer.ClaimNextitself when the batch reports no change. That is a design call above the role seam and has not been made. -
A batch's Dolt commit message no longer names wisp ids (bd-yby99.20). A batch may close ephemeral and durable items together, and the durable commit message named every item that landed. Wisp tables are dolt-ignored, so that message shipped a reference to work no other machine can resolve — the same federation leak
Commenteralready guards against. The message is now composed from durable landings alone and reports ephemeral ones as a count. Closing a wisp still counts as work landing: a wisp-only batch still succeeds and still earns its claim. -
Breaking:
bd list --readynow refuses a filter it cannot honor instead of silently ignoring it (bd-yby99.8). The--readyarm reaches the blocker-aware query through a narrower filter than the rest ofbd listuses, and everything that filter could not carry was dropped without a word:bd list --ready --id tst-d68answered with every ready issue in the workspace, not the one named. It now fails with a validation error naming the fields it could not honor.The refused combinations are
--readytogether with any of--id,--title,--spec,--title-contains,--desc-contains,--notes-contains,--external-contains,--external-ref, any--created/--updated/--closed/--defer/--duebound,--deferred,--overdue,--empty-description,--no-labels,--no-parent,--pinned,--priority-min,--priority-max, or an HTTP list cursor. A script that passed one of these was already getting the wrong answer; it now gets an error instead of silently wrong rows. Everything--readydoes carry is unchanged —--type, all the label flags,--assignee,--no-assignee,--priority,--parent,--mol-type,--wisp-type,--metadata-field,--has-metadata-key,--exclude-type,--include-gates,--include-infra,--limit,--offset,--max-rows,--sortand--reverse— as is--no-pinned, which the ready query already satisfies by construction.What
--readycarries, what it refuses, and the two things the ready set decides for itself (it never returns pinned issues, and it applies no template predicate of its own) are now stated onissueops.ListRequest.ReadyFlagand pinned by the Reader conformance contract at all three backends. -
issueops.Readernow refuses anOffsetit cannot honor instead of silently ignoring it (bd-yby99.7). The store-backed reader — one body, handed back by both the Dolt server store and the embedded store — rendersLIMITwithoutOFFSET, so a caller that paged withOffsetgot the unpaged first page again and again with no error to notice: three matching rows came back 3/3/3 atOffset0/1/2.ReadyandListnow return a typed*issueops.ErrUnsupportednaming the operation and the backend. The unit-of-work reader, which does renderOFFSET, keeps honoring it, and both behaviours are now pinned by one conformance case: anOffsetis honored or refused, never ignored.No CLI behaviour changes.
bd ready --offset,bd list --offsetandbd query --offsetalready rejected a non-zero offset on the direct route and already reached the unit-of-work path under--proxied-server, where offset paging works and is unaffected. This closes the same hole one layer down, for callers built on the library rather than on the CLI.ErrUnsupportedmoved into the publicissueopspackage and is aliased back frominternal/storage, so a consumer holding only a role interface can classify the refusal witherrors.Aswithout importing an internal package. It is the same type throughout:beads.ErrUnsupportedandstorage.ErrUnsupportedare unchanged aliases and every existingerrors.Assite keeps matching. The portable way to page a listing across backends is the keyset position (ListRequest.AfterCreatedAt/AfterID), which every implementation honors and which is stable under concurrent writes; ready work carries no keyset and therefore has no portable paging. -
Breaking: a dependency type is now bounded at 32 characters, not 50 (bd-yby99.3). The
typecolumn on bothdependenciesandwisp_dependenciesisVARCHAR(32)and no migration widens either, so the validator's old 50-character bound accepted a range of types — 33 to 50 characters — that no row could ever carry. Depending on the caller, such a type either failed at the database with a raw truncation error or was silently cut short.types.DependencyType.IsValidnow bounds at the new exportedtypes.MaxDependencyTypeLen, so the refusal arrives from one place, ahead of every backend, with a typed validation error.This narrows what bd accepts on twelve paths, among them
bd create --deps,bd dep add --type,bd link --type,bd batch,bd graph applyand markdown import. In practice nothing in the wild should notice: every well-known type is far shorter (the longest,conditional-blocks, is 18 characters), andbd create --depsaccepts only well-known types anyway. The user-visible error text changed too — messages that readmax 50 charsorat most 50 charactersnow name 32 — so a script matching on that literal string needs updating. One rough edge is unchanged and worth knowing about:bd create's interactive form warns and drops an invalid dependency rather than failing, so a 33-to-50-character type there now silently loses the edge instead of creating an unstorable one. -
Breaking:
bd update --status <done-status>now enforces close policy. Moving an issue intoclosed(or any configured done-category status) viabd update,bd batch update, or the issueops facade now refuses when the issue has open children or a live direct blocker — matchingbd close. Override withbd update --force, which now means: allow-a/--assigneeto overwrite another actor's live in_progress claim, AND allow a status change into done despite open children or a live blocker (same asbd close --force).bd update --forcewithout-awas previously a validation error on the direct path; it is now valid. Inbd batch, spell the overrideupdate <id> status=closed force=true; an unforced refusal rolls back the entire batch. Facade consumers: setUpdateRequest.ForceClosePolicy. Tracker sync-pull always forces (remote state is authoritative).bd batch closeremains unchecked, as before. -
Public
beads.Storageinterface gained a requiredIssueClaimer()method (bd-serve claim role).IssueClaimer() (issueops.Claimer, error)returns the guarded atomic claim:Claim(ctx, issueops.ClaimRequest) (issueops.ClaimResult, error), one compare-and-set that sets assignee and status only while the issue is claimable, reports the idempotent re-claim asChanged: falsewith nothing written, and refuses a lost CAS with a wrappedErrAlreadyClaimedorErrNotClaimable. When the refusing state was readable in the same transaction the refusal is an*issueops.ClaimConflictErrorcarrying the assignee and status — so a client classifies a conflict from typed fields instead of matching substrings in the message, whileerrors.Isand the refusal's exact prose are unchanged.POST /v0/beads/issues/{id}:claimnow runs on the role; the CLI'sbd update --claimis not on it yet. It is a role of its own rather than a fifth verb onissueops.Lifecycle— a capability that role does not cover gets its own accessor. Consumers that only call the interface are unaffected; any external type that implements it (a custom store, mock, or proxy) must add the method to compile. A decorator must implement it by recursing into the store it wraps, the wayIssueLifecycle()does.ClaimResult.Issueis the post-state issue ROW — deliberately without labels, dependency records or comments, unlikeUpdateResult— because that is what the already-published v0 claim response andbd update --claim --jsonboth report today. -
issueops.ReopenRequestgained aProvenancefield, andbd reopennow names the issue in its Dolt commit message on the direct path.Provenanceis the same optional labelUpdateRequestalready carries: it names the surface a mutation came from, it never changes whether a history entry is recorded, and empty still selects the implementation's default. It exists on this request because the defaults do not agree — the store-backed backends writebd: reopen issueand the unit-of-work backend writesreopen issue, neither naming the issue. A caller that spells a label now gets one entry whichever backend served it. The visible change is inbd dolt logonly: a directbd reopen bd-1readsbd: reopen bd-1where it readbd: reopen issue, orreopen issueon the unit-of-work backend.UpdateRequestandReopenRequestare the only two requests that carry the label, and deliberately so.CreateRequestgains nothing — no surface has ever named the created issue, so the field would have no caller. Neither doCloseRequest,CloseBatchRequest,ClaimNextRequest,AddCommentRequest,AddDependenciesRequestorRemoveDependencyRequest: each of those roles composes its entry from what the call actually did, so a caller-supplied label could only restate it or contradict it. For the batch close and the claim one is not even expressible — those messages name what LANDED and which id the claim WON, neither of which is knowable before the call. For the dependency verbs the entry follows the edges: one edge names both endpoints, several name only their count, and — see the source-routing note below — a request made entirely of wisp-sourced edges records no entry at all, leaving a label nothing to name. -
Public
beads.Storageinterface gained requiredDependencyEditor(),Commenter()andIssueRelations()methods. Three more roles alongsideIssueLifecycle(),IssueReader(),ReadyClaimer()andBatchCloser(), reached the same way and layered by each decorator in its own accessor. Consumers that only call the interface are unaffected; any external type that implements it (a custom store, mock, or proxy) must add all three to compile, and a decorator must implement the two write roles by recursing into the store it wraps rather than delegating blindly.DependencyEditor() (issueops.DependencyEditor, error)edits the dependency graph.AddDependenciesasserts a set of edges as ONE durable act — one transaction, at most one history entry — and is ALL-OR-NOTHING: any refused edge (self-dependency, cycle, type conflict, hierarchy conflict, unknown endpoint) refuses the whole request and writes nothing. Edges asserted together describe a graph, and half a graph is a graph nobody asked for.RemoveDependencyis idempotent: a missing edge isRemoved: falsewith a nil error and no history entry, notErrNotFound.The dependency-type constants
issueops.DepBlocks,DepParentChild,DepRelated,DepDiscoveredFrom,DepRepliesToandDepWaitsForship with it. They are documented common values of an OPEN, workspace-configurable set — not a closed enum, not exhaustive, and not validated against: nothing refuses a type merely because it is absent from the list, and a workspace's own type is a first-class value everywhere aDependencyTypeis accepted. They exist becauseinternal/typesis unimportable outside the module, so without them an external embedder can hold aDependencyTypebut has no spell-checked way to name one — the same reason the error sentinels are re-exported.Commenter() (issueops.Commenter, error)appends one comment as one atomic mutation. A blankTextisErrValidation, as is an emptyIssueID; the issue-then-wisp fallback happens inside, as it does forReader.Get; a non-empty id naming neither plane isErrNotFound— an unaddressed request is invalid, not a thread that went missing, so the two are worth telling apart.issueops.Comment(an alias for the canonical comment model) is the result type. A comment on an ephemeral row records no durable history entry — the wisp tables are dolt-ignored so ephemeral work never ships, and an entry naming a wisp thread is exactly the artifact that ignoring them prevents; the comment still lands on the ephemeral thread and reads back from it.IssueRelations() (issueops.Relations, error)reads an issue's neighbors.Relatedrequires an explicitRelationOutorRelationIn— the zero direction isErrValidation, with no implicit "both", because a silent default hands a caller the inverse graph with nothing to notice. An unusableTypesentry isErrValidationrather than a filter that matches nothing, and an anchor missing from both planes isErrNotFoundrather than an empty list. The result order is pinned: ascending by the neighbor's id, with the edge type breaking a tie.bd dep add,bd dep remove,bd dep list,bd commentandbd comments addare on these roles on BOTH routes — the direct one reaches them through the store's own accessor exactly as the proxied one reaches them through the provider's. Four behaviors changed on the proxied route:bd dep listnow answers in the pinned order rather than in the order the two dependency tables happened to be read; abd dep listnaming an issue that does not exist now reports that instead of printing an empty neighbor list, matching what the direct route has always done; abd dep removethat finds no edge now records no Dolt commit at all, where it used to name one; and a single-linebd dep add --filewritesbd: dep add <a> <b>rather thandependency: add 1 edges.Four more changed on the direct route as it joined them.
bd dep listthere now answers in the same pinned order. Dolt commit messages for the explicit dep verbs are now the role's —bd: dep add <a> <b>andbd: dep remove <a> <b>— where the direct path used to writedependency: add <type> <a> -> <b>/dependency: remove <a> -> <b>in server mode and a genericbd: dep add (auto-commit) by <actor> [...]in embedded mode. Abd dep add --fileedge refused by storage no longer carries aline N:prefix, because the role's request is all-or-nothing and names no edge index — parse and id-resolution errors still name their line. And abd dep add --filein embeddedbatch/offauto-commit mode now defers its version commit to the next explicit commit point instead of always writing one, which is what every other write verb already did.bd comment's direct route changed one thing with it, on the embedded backend only: a comment's Dolt commit is now the role'sbd: comment <id>authored bybeads, where the CLI auto-commit wrotebd: comment (auto-commit) by <actor> [<id>]authored byroot. That is the spelling the Dolt server backend already wrote, and it is one commit per comment either way. Comment LISTING (bd comments <id>) is on neither role and unchanged on both routes: reading a thread is a paging question with a cursor of its own, whichissueops.Commenterdeliberately excludes.DependencyEditor.AddDependenciesroutes each edge by its SOURCE, the rule the stores' own dependency verb has always applied and the onebd dep removeandbd dep listalready read: a wisp-sourced edge goes towisp_dependencieswith its event inwisp_events, an issue-sourced one todependenciesandevents. Routing by source rather than pinning it to the issues plane is what keepsbd dep add <wisp-id> <target>working: a wisp has no row in the issues plane, so a pinned source has nothing to hang an edge off, and the two routes would not even have failed alike — the direct one on its source-existence check, the proxied one on anfk_dep_issueforeign key violation. ONE REQUEST MAY MIX THE TWO: it is still one transaction, the parent-child-first ordering and the whole-graph cycle gate both span the two tables (a cross-plane cycle is still refused), and a refusal rolls back both planes. Only the durable half is versioned, so a request made entirely of wisp-sourced edges records no history entry and leaves the working set clean — asserted end to end against a real embedded store byTestEmbeddedDepAddWispSource, which runsbd dep add <wisp-id> <target>at the front door.bd linkon the proxied server routes the same way, matching its direct twin. Behind the role there is no plane-pinned bulk variant left to reach for by mistake: the internal domain layer's three bulk add verbs are now the one source-routedAddDependencies, so every bulk caller — role,bd link, unit of work — gets this rule and cannot opt out of it. -
Public
beads.Storageinterface gained requiredReadyClaimer()andBatchCloser()methods. Two more roles alongsideIssueLifecycle()andIssueReader(), reached the same way and layered by each decorator in its own accessor. Consumers that only call the interface are unaffected; any external type that implements it (a custom store, mock, or proxy) must add both methods to compile, and a decorator must implement them by recursing into the store it wraps rather than delegating blindly.ReadyClaimer() (issueops.ReadyClaimer, error)takes ready work atomically:ClaimNextselects, wins the compare-and-set and hydrates the row it won, all in one transaction. Its filter isissueops.ReadyRequest— the same typeReader.Readytakes — so the claim's predicate cannot drift from the setbd readyshows;LimitandOffseton it areErrValidation, because the claim scan clears them and accepting a field only to drop it is worse than refusing it. An empty ready front is a nil result with a nil error, not an error class to classify.BatchCloser() (issueops.BatchCloser, error)closes many issues as one durable act:CloseBatchcommits every item that lands in ONE transaction with at most one history entry. The request is the transaction boundary — nothing on the contract exposes begin or commit. It is deliberately not all-or-nothing: a refused id is skipped and the survivors commit together, soCloseBatchResult.Outcomescarries one entry per requested item in request order, each with a typederrors.Is-able refusal that never aborts the rest. An optionalClaimNextruns after the closes, in the same transaction, only when at least one item closed.bd ready --claimandbd closeare on these roles on BOTH routes. Three behaviors changed on the proxied route: the proxied claim's Dolt commit message is nowbd: claim ready <id>, the spelling the other two backends already wrote (it wasbd: ready --claim <id>); molecule auto-close,--suggest-nextand--continuenow run after the close transaction rather than inside it, which is where the direct route has always run them — a plainbd close a b cis still exactly one Dolt commit, while a close that actually auto-closes a molecule or advances a step now produces two; andbd close --claim-nextwalks the ready order and takes the first row it can win, where it used to read the single top ready row and warn if that row had already been taken — a race with another agent now claims the next candidate instead of claiming nothing.bd close's direct route closed N ids as N transactions with N Dolt commits until it joined them, so five things changed as it did.bd close a b cnow writes ONE commit namedbd: close a, b, cinstead of three namedbd: close issue— one request per STORE, since a transaction cannot span the second repo a prefix-routed id reaches.--claim-nextruns inside the closes' transaction and only when something landed, walks the ready order the way the proxied route already did, and its--jsonclaimedvalue is now the post-claim row (in_progress, assigned) rather than the pre-claim row the old two-step read. Molecule auto-close runs after ALL the closes land rather than between them — the root still closes exactly once; only which id's slot prints theAuto-closed completed moleculeline can move. The open-children refusal moved from a cmd/bd pre-flight read into the close's own transaction, closing a read-then-write window that madebd close <child> <parent>depend on argument order; its message is unchanged. And an unsatisfied gate on an issue that ALSO has open children now reports the gate rather than the children, because the gate check stayed in the pre-flight — both were already refusals. -
Public
beads.Storageinterface gained a requiredIssueReader()method (bd-serve reader role).IssueReader() (issueops.Reader, error)is the read counterpart ofIssueLifecycle(): one accessor returning a role that answersReady,ListandGetwith filter construction, workspace-config loading, default limits and the wisp fallback all performed inside it, so a caller cannot half-perform that construction and answer the same question a different way. All three ofbd serve's issue reads andbd show --json's detail view are on the role;bd listandbd readyare not yet, and share theinternal/workapibuilders instead — seeissueops.Reader's doc comment for exactly what that does and does not cover. It is a role of its own rather than three more methods onissueops.Lifecycle— a capability that role does not cover gets its own accessor. Consumers that only call the interface are unaffected; any external type that implements it (a custom store, mock, or proxy) must add the method to compile. A decorator must implement it by recursing into the store it wraps and layering its own behavior onto the result, the wayIssueLifecycle()does, rather than delegating blindly — a blind delegation compiles and still satisfies the interface while silently dropping that decorator's layer for every read. -
beads.BulkIssueStore.ReclaimExpiredLeasesgained atypes.ReclaimFilterparameter (wy-jpd3.3), threaded through the domain use-case/repository interfaces and every backend. Callers that reclaim globally pass the zerotypes.ReclaimFilter{}(unchanged behavior); any external type that implements the interface must update its signature to compile. -
Public
beads.Storageinterface gained two required methods (#4911).UpdateIssueChecked(an optionalExpectedVersioncompare-and-swap on updates) andMergeMetadata(atomic single-key metadata merge) are now part of thebeads.Storage/storage.Storagecontract. Consumers that only call the interface are unaffected; any external type that implements it (a custom store, mock, or proxy) must add both methods to compile.UpdateIssueCheckedwith a nilExpectedVersionbehaves exactly likeUpdateIssue, andMergeMetadatacan be layered over a read-modify-write of issue metadata. See examples/library-usage. -
Storage backend scope simplified (bd-sadcd). The recently merged direct PostgreSQL and MySQL adapters have been rolled back before entering a tagged release. Supporting additional general-purpose server databases introduced dialect, credential, schema-lifecycle, migration, CI, and operational complexity at odds with our goal of keeping Beads as simple as possible and consuming as few resources as possible. The storage interface, shared issue core, SQLite implementation, and conformance harness remain; embedded Dolt, Dolt server, and SQLite are the supported storage paths. Dolt server mode and its use of the MySQL wire protocol are unchanged. Existing PostgreSQL or MySQL workspaces stop before their configured databases are opened or modified; see the migration guide.
-
Cross-type blocking dependencies are now allowed (bd-wg7ve, #4034).
bd dep add <task> <epic>— gating a work item on an epic (program) completing — previously failed with a backwards-reading error ("tasks can only block other tasks, not epics"). The blanket same-type rule (GH#1495) is replaced by a hierarchy deadlock guard that rejects only the cases that actually wedge the graph: gating an issue on its own ancestor (the ancestor can't close until its descendants finish) or on its own descendant (blocked status cascades down to the very issue that must close to clear the gate). Sibling ordering edges stay allowed. The guard now also coversconditional-blocks, which previously skipped cross-type validation entirely. A task gated on an epic becomes ready when the epic itself is closed, consistent withbd ready/bd blocked. -
Claim/unclaim refusals now steer toward the holder instead of teaching eviction (bd-at6rc, wyvern wy-zs5s2). The
--claimrefusal for an issue assigned to someone else suggestedbd unclaim <id>— in a multi-agent fleet that copy taught an unclaim-then-claim steamroller that evicted a live, heartbeated claim mid-review. The refusal now says to coordinate with the holder, and unclaim's ownership rejection frames--forceas an abandoned-claim escape hatch rather than a routine override. (The ownership check itself — foreign unclaim requires--force— landed in #4675.)
Fixed
-
Multi-id
bd dep listno longer changes its JSON shape on failure (bd-nhsno). The direct route used the batched edge read onlyif err == niland otherwise fell through to the neighbour path, which emits a different document — issues, not edge rows — with no error and no warning. Worse, the batched read was only ATTEMPTED when every resolved anchor shared one store, so a cross-workspace batch emitted the wrong document every time rather than only on failure. The read now goes through the newissueops.EdgeReaderrole, taken per store, with the answers merged back into argument order, and a failure is reported as a failure. -
bd ready --claimhonours the directory-label scope (bd-s10oa). The branch that applies a directory's configureddirectory.labelsdefault tested the filter it had already written that default into, so it could never fire. In a directory withdirectory.labelsconfigured,bd ready --claimtherefore claimed from the WHOLE ready front whilebd readybeside it listed only the configured scope — handing an agent work the listing never offered it. Both routes affected. -
Proxied
bd config set status.customandtypes.customtake effect immediately (bd-kzepq). Reads of the custom status and type vocabularies are TABLE-first: they consult the normalizedcustom_statusesandcustom_typestables and fall back to the config string only when the table is empty. The direct route has always rewritten the table in the same transaction as the row; the proxied route wrote only the string. So on a team serverbd config set types.custom "session"reported success,bd config get types.customread it back,bd doctorre-verified against the string and reported all-OK — andbd create -t sessionansweredinvalid issue type: sessionfor as long as the workspace lived. Both routes now project the value into its table inside the same unit of work as the row, so the setting and its effect land together or neither does. -
bd config set-many issue_prefix=<x>is refused, asbd config sethas always been (bd-kzepq).bd config setrejects the workspace id prefix in both spellings and points atbd init --prefix,bd bootstrapandbd rename-prefix, each of which does work a config write cannot — seeding a workspace that has none, or rewriting the ids that already exist.set-manypartitioned its pairs by source and wrote the database ones straight through, so it walked past that guard and re-prefixed the workspace: beads created before the write and beads created after it disagreed about their own namespace, with nothing to reconcile them. Both verbs now refuse it, and so does the substrate, so a future front door cannot miss it either. -
bd create --id <id>on a proxied server refuses an occupied id instead of overwriting it (bd-7oyh5). The direct route has always been create-only. The proxied route passed no such flag, sobd create --id bd-abc123 --title ...against an id that already existed silently upserted every column of the resident issue — title, type, description, labels — and exited zero. The original was gone, with no history entry naming a create and nothing in the output to suggest anything had been replaced. Both routes now returnErrAlreadyExistsnaming the id and leave the stored row untouched, across the shared id space: an occupied durable id refuses a wisp create and an occupied wisp id refuses a durable one. If you have automation that relied on--idas an upsert, it should callbd update. -
Proxied
bd update --ephemeraland--no-historymove the issue instead of flagging it in place (bd-xt6de). The direct route sends these through an atomic aggregate move: insert into the target plane, copy the auxiliary rows, retarget inbound dependency edges, drop the lease, delete from the source. The proxied route instead ran a plain column update on whichever table the row already sat in, so a proxiedbd update --ephemeralleft the issue inissuescarryingephemeral = 1— still durable, still versioned, still replicated, but invisible to every wisp-plane read and skipped by JSONL export. Both routes now perform the move. The inverse spellings--persistentand--historyappeared to work before only by accident: moving a row that never leftissuesis a no-op that still clears the flag. This does not repair existing rows. Any issue a proxiedbd update --ephemeralproduced before this release is still inissueswith the flag set, and nothing here finds it; that needs its own migration. -
Proxied
bd reopenreopens an issue in a configured done status (bd-1f5a2). The proxied handler short-circuited onstatus != closedand reported "nothing to do" for any workspace-configured done status, so on a team server an issue in a custom done state such asverifiedcould not be reopened at all while the same command worked locally. Both routes now go throughissueops.Lifecycle.Reopen, which spans the whole configured done category. Reopening something genuinely not closed is still a no-op and still says so. -
bd update --parenton a proxied server no longer leaves a stale parent (bd-yby99.26). A parent id is a set assignment: setting it replaces every parent edge the child has, and clearing it removes them all. The unit-of-work route stopped after the first edge it found. A child with two parents reparented to a third kept one of the originals, and clearing the parent left the rest in place — in both cases reported as a success. Two parents on one child is not the common shape, but the failure was silent and the resulting graph is wrong for every reader that walks parent edges. The Dolt backends already applied the set rule; this brings the third route into line. -
bd dep removeon a wisp-sourced edge now removes it (bd-yby99.17). On the proxied server the removal was pinned to the durable plane: an edge whose source is a wisp was looked for independencies, not found, and reported asRemoved: falsewith a nil error while the row stayed inwisp_dependencies. The command exited zero having changed nothing. A removal cannot put an edge anywhere, so it now reads the source's plane and deletes from there, and the delete's own result is the found/not-found verdict. Removing an edge that genuinely does not exist is still a nil-error no-op, as before. -
A dependency on an issue in another repository no longer fails with a raw foreign-key error (bd-ocrn7). beads addresses a foreign repo's work by prefix —
otherrig-9001from a rig whose own prefix isbd-— and the database holds such a target independs_on_external, a column with no foreign key, precisely because the row cannot exist locally. The domain route classified the target by looking only for the literalexternal:prefix, decidedotherrig-9001was local, wrote it todepends_on_issue_id, and the foreign key rejected the insert withError 1452. No edge was written and the error named a constraint rather than the problem.Both routes now classify through one named rule,
issueops.IsExternalDepTarget: a target is external if it is spelledexternal:...or its prefix differs from the source's. That is what the Dolt backends have always done, so this brings the third route into line rather than inventing a policy. The foreign key itself is untouched, and a genuinely local, genuinely missing target is still refused as before. One consequence beyond the failing case: a cross-prefix target that does happen to exist in the local issues table now also lands in the external column on this route, which means derived blocking no longer reads that edge — again matching what the Dolt backends already produced. -
A ready claim that wins an ephemeral row no longer reports a spurious "could not be verified" error (bd-yby99.4). In server mode,
bdre-reads a claim it just made to confirm the write landed, because an exit code is not truth against a degraded server. That re-read always looked in theissuestable. But a ready claim can win a wisp when the request's filter admits ephemeral rows (bd ready --claim --include-ephemeral), and the claim is written to thewispstable by design — so the verify hunted for the row in a table that never held it and turned a perfectly good claim intoreported success but could not be verified (server degraded?). The verification is now plane-aware rather than skipped: a wisp claim is checked against thewispsrow, so no check was traded away for the fix.The
ClaimNextcontract is now explicit that the ready set is whatever the filter admits — an ephemeral row the filter pulls in is genuinely claimable, and claiming it moves that row rather than promoting it to a durable issue. Two properties follow that callers should plan around: such a claim records no durable history entry, because ephemeral rows are not versioned, so reconstructing who took what from history alone will not show it; and it takes no lease, sobd heartbeatrefuses it andbd reclaimwill not recover it if the agent holding it dies. -
bd dolt pushandbd syncno longer adopt a Dolt remote derived from git origin without consent (#5068). On a rig with no Dolt remote configured, both commands silently derived one fromgit remote get-url origin, added it, persistedsync.remoteinto.beads/config.yaml, committed that config change under the user's git identity, and uploaded the full issue history — no prompt, no flag, no opt-out. A public git origin therefore published the whole issue database on a command the user believed targeted an already-configured remote.Adoption is now a consent decision and fails closed. Interactively, bd shows the derived URL and every side effect that follows a yes (including the config commit made under your git identity) and defaults to no. Non-interactively it refuses and exits non-zero, naming the URL it would have adopted and the explicit opt-in.
--yes/-yconsents ahead of time for scripted use;--no-adoptorBD_NO_REMOTE_ADOPT=1disables adoption entirely and wins over--yes. Rigs with a remote already configured are unaffected — that path was and remains a no-op.Workspace resolution also moved below the gate: it calls
prepareSelectedNoDBContext, which mutates workspace state, and nothing may mutate before consent is established. -
Proxied-server CI shard 1 flake:
TestProxiedServerCleanDatabasesran a server-global destructive command against the shared test container (p1-9lf, hazard tracked in p1-8dz). The test used the shared external Dolt container undert.Parallel(), andbd dolt clean-databasesdrops every database matchingstaleDatabasePrefixeson the server it is pointed at. The container is bootstrapped with a database namedbeads_test(internal/testutil/container_provider.go), which matches one of those prefixes — so every run of this test dropped the shared container's own bootstrap database out from under whatever sibling tests were mid-flight, which is timing-correlated with thebusy buffer/ "pending schema migrations alter pre-existing dirty tables" failures seen inTestProxiedServerDeleteandTestProxiedServerFindDuplicates. The test now runs against a dedicated proxied server (bdProxiedInit), like the new purge test, so its blast radius is its own server. -
bd dolt clean-databases --purge-droppednow works in proxied-server mode (p1-9lf). The command read the flag and then dropped it on the floor before dispatching to the proxied-server implementation, so under--proxied-serverstale databases were dropped but never purged: their directories stayed under.dolt_dropped_databases/, disk was never reclaimed, and nothing reported that the flag had done nothing. The proxied dual had drifted further than that one flag — it also lacked the batching/circuit-breaker drop loop, the dry-run "purge ignored" notice, and theDOLT_UNDROPrecoverability trailer, and its early return on "nothing stale found" was incompatible with purge semantics (a prior run's residue is invisible toSHOW DATABASES, so--purge-droppedmust still fire when this run drops nothing). Both topologies now share one implementation keyed onversioncontrolops.DBConn, which*sql.DB(direct server) and the pinned non-transactional*sql.Conn(proxied server, viauow.MaintenanceProvider.RunNonTx) both satisfy, so the behavior cannot diverge again. Per-operation timeouts now derive from the command's context on both paths, so Ctrl-C interrupts a long clean. -
bd dolt clean-databasesgains an opt-in--purge-droppedflag to reclaim disk from what it drops (be-pq5, #3663).DROP DATABASEonly moves a database's directory under.dolt_dropped_databases/; Dolt keeps the on-disk data there — recoverable viaCALL DOLT_UNDROP(name)— until an explicitCALL DOLT_PURGE_DROPPED_DATABASES(). The operator-facing cleanup command dropped staletestdb_*/benchdb_*/etc. databases fromSHOW DATABASESbut never issued that purge, so disk usage on the shared Dolt server stayed high across repeated runs.--purge-droppedruns the purge after cleanup (a failed purge is reported as a warning rather than aborting the command, since the databases are already dropped from the server's active set at that point) and fires even on a run that finds nothing stale to drop, since a prior run's dropped-but-unpurged residue isn't visible toSHOW DATABASESeither.CALL DOLT_PURGE_DROPPED_DATABASES()is server-global and irreversible — Dolt has no way to scope it to only the databases a given run dropped, so--purge-droppedalso permanently deletes every other dropped-but-not-yet- purged database on the server, removingDOLT_UNDROPrecovery for all of them. It defaults to off for that reason; without it, dropped databases are left in place, recoverable viaDOLT_UNDROP, same as before this change.
Added
-
Conditional (compare-and-set) updates:
bd update --if-assignee/--if-status(bd-wsqvw, from wyvern's wheelhouse hostile-review epic wy-mdi5h; design inPROPOSAL-cas-conditional-update.md). When either guard is present the update applies only if the issue's current assignee/status still equals the expected value — one atomic transaction, nothing written on a mismatch, and a loud non-zero exit naming actual vs expected (typed asstorage.ErrAssigneeMismatch/ newErrStatusMismatch).--if-assignee ''means "expected unassigned". A guard mismatch is machine-distinguishable from infra failure: exit code 13 when every failure in the run was a stale guard (a racer won — skip gracefully) vs 1 for anything else (retry/abort); in--jsonmode each entry in the failure report'sfailedarray additionally carries"guard_mismatch": true, and the stderr text always contains the sentinel tokenassignee mismatch/status mismatch. This closes the two coordination transitions no existing verb could express: reassign X→Y only while X still holds it (bd update <id> --if-assignee worker -a mayor), and claim-on-behalf with a status guard (bd update <id> --if-assignee '' --if-status open -a owner -s in_progress). Guards require a field update to ride on, are mutually exclusive with--claim(its own CAS), compose with each other and with the engine'sExpectedVersionrow CAS, and work in every dolt mode. In Dolt server mode a guarded update that writes assignee/status is claim-family and is resolved by the bd-zccb9 verify-by-re-read protocol, so its exit code stays truthful under a degraded server. Library consumers get the same guards via newUpdateIssueOptions.ExpectedAssignee/ExpectedStatusfields on the existingUpdateIssueChecked— no interface change; out-of-treeStorageimplementations that ignore the new fields simply do not enforce them and should add support before advertising guard semantics. -
Pool-aware claiming via the
claim.poolsconfig key (bd-bguz6). Dispatcher fleets pre-assign issues to a pool pseudo-assignee (e.g.fable-crew);--claimpreviously refused those ("already assigned"), forcing a two-step--assignee <me> -s in_progressper issue. Aliases listed inbd config set claim.pools "fable-crew,night-crew"are now claimable by any actor through the same atomic compare-and-swap — the claim stamps the normal lease, and issues assigned to a real actor (or to an alias not in the config) keep their anti-steal protection. Pool-aware claiming works in every dolt mode — the proxied-server claim path applies the same predicate — andclaim.*is a recognized config namespace (documented inbd config --help). Note: if a pool take's lease expires,bd reclaimreturns the issue to the unassigned pool, not to the pool alias it was dispatched to. Off by default: with noclaim.poolsconfigured, behavior is unchanged. -
Work leases: claim-TTL, heartbeat, and reclaim for dead-worker recovery (schema v54, migration
0054) (#4537). A claim was previously permanent — a worker that died mid-task stranded its issuein_progressforever. Claims now carry a lease:- Claiming stamps
lease_expires_at = now + TTL(default 5m) andheartbeat_at. bd heartbeat <id>— owner-only; pushes the lease forward. Fails once the lease is gone.bd reclaim --older-than <dur>— revertsin_progressissues whose lease expired more than<dur>ago back to ready (clears assignee/started_at, records alease_reclaimedevent). Default grace 2×TTL.
Because Dolt has no row locking and merges concurrent commits cell-by-cell, every status/ownership/lease-mutating path also rewrites a shared
row_lockcell, forcing a racing heartbeat vs. reclaim to a serialization conflict that the retry layer replays — instead of silently cell-merging into a zombie claim. The same landing wraps the work-queue hot paths (bd ready --claim, claim, update, close) in serialization- conflict retry, so N concurrent workers draining one queue no longer surface MySQL 1213/1205 errors. - Claiming stamps
-
bd migrate --force(andbd migrate schema --force): CLI flag twin ofBD_ALLOW_REMOTE_MIGRATE=1for bypassing the remote-migrate gate (#4259) as the single designated migrator; process-local so it cannot leak into child processes (git hooks, dolt subprocesses). -
Cursor agent hooks.
bd setup cursornow installs.cursor/hooks.jsonalongside the existing rules file, wiring three Cursor lifecycle events to a new hiddenbd cursor-hookcommand:sessionStartinjects fullbd primecontext into every new agent session.preCompactarms a one-shot refresh marker (and notifies the user).postToolUsere-injectsbd primeexactly once after a compaction, then no-ops.
This brings Cursor (IDE and recent
cursor-agentCLI builds — verified on the 2026.06 line; early-2026 CLI builds only fired shell hooks) to parity with the Claude Code / Codex hook integrations, so Beads context survives context compaction instead of being forgotten. Existing user hooks in.cursor/hooks.jsonare preserved, andbd setup cursor --removeonly removes the Beads-managed entries.The integration now matches Claude/Codex on several more fronts:
bd initauto-installs Cursor (rules + skill + hooks) the same way it auto-sets up Claude Code and Codex, and stages.cursor/for commit.bd setup cursor --globalwrites hooks to~/.cursor/hooks.json(and the agent skill to~/.agents/skills/beads) so they apply to every project. (Global scope is hooks + skill only; Cursor has no reliable file-based global rules location — those live in Cursor Settings.)- Canonical rules content.
.cursor/rules/beads.mdcnow wraps the sharedrecipes.Template(the same content every other file-based recipe uses) instead of a hand-maintained copy, so it no longer drifts or omits the Issue Types / Priorities / git-authority sections. - Agent skill.
bd setup cursorinstalls the shared.agents/skills/beads/SKILL.md(which Cursor loads natively), so Cursor-only users get the same progressive-disclosure skill Codex installs. The skill is shared with Codex and is only removed once no integration still relies on it. bd doctorreportsCursor Integration,Cursor Settings Health(malformed.cursor/hooks.json→ error), andCursor Hook Completeness(all three lifecycle events present) checks — with agent-mode enrichment — paralleling the Claude integration checks.
Changed
- Remote-ahead adopts fast-forward automatically when it is provably
loss-free AND lands exactly at this binary's latest migration. When the
smart remote-migrate gate
(#4516) finds the
remote ahead with no content skew, this clone's local Dolt history a
strict ancestor of the remote's with a clean working set, AND the
fast-forward would land exactly at the binary's own latest migration
(nothing pending after it, nothing beyond what this binary supports),
bdnow fast-forwards to the remote's migrated schema automatically instead of stopping with an adopt directive — nothing local is discarded. An unpushed local commit, a dirty working set, or a remote that is not exactly at this binary's latest migration all disqualify the automatic fast-forward and fall back to the existing manualbd bootstrapadopt directive (with the sharper loss-free guidance whenever ancestor+clean still hold), never a forced write. SetBD_SMART_GATE=0to opt out and keep the manual wall for every remote-ahead case, as before (#4259).
Fixed
-
Claim-family writes are now verified by re-read in Dolt server mode (bd-zccb9, from wyvern incident wy-ejph3). Under a degraded sql-server the exit status of
bd update --claim/bd claim/ unclaim was not truth in either direction: a claim could report success while the server-side transaction died with the abandoned connection and rolled back (a phantom claim that later cost a duplicate implementation), and conversely a connection error could print with the write actually applied. After the claim transaction, bd now re-reads the issue's assignee and status on a fresh connection and resolves the outcome against the database: a reported success that did not land fails loudly ("treat the claim as NOT applied"); an ambiguous commit-phase loss is settled by the re-read — verified applied becomes an accurate success, verified rolled back is replayed once (safe: nothing landed). Applies to claim, ready-claim, and unclaim in server mode; wisps and embedded mode are unchanged. New metricsbd.claim_verify_lost_totalandbd.claim_verify_recovered_totalcount loud failures and converted outcomes. -
Single-issue
bd create --id P.Nno longer leaveschild_countersstale (one root cause of #4750; the issue stays open — three other drift paths remain).CreateIssueInTxWithResultonly reconciledchild_counterswhen the batch path calledReconcileChildCounters; an explicit hierarchical--idnever advanced the parent'slast_childhigh-water mark. Once such children were later archived out ofissues,GetNextChildIDTxno longer saw them and could re-mint an already-used suffix — an ID collision with an archived issue. The single-issue path now callsReconcileChildCounterstoo, and its changed tables are merged into the result so the reconcile actually gets staged for commit.
[1.1.2] - 2026-07-26
Hotfix release cut from v1.1.0. (There is no 1.1.1 release: its tag was cut
but the release pipeline's package gate failed on a stale MCP lockfile before
publishing anything, and the version number was burned rather than moving the
tag.) If bd migrate on 1.1.0 aborted with
rekey aux row ids: <table>: ... invalid hash length and the database then
refused to open, this release lets the migration complete.
Fixed
- The v53 aux row re-key survives dolt#11131 encoding drift. On storage
affected by the upstream Dolt adaptive-encoding bug, reading the drifted
cells panics (
invalid hash length: 19), which aborted the migration and left the database unopenable under 1.1.0. The re-key now skips such a table with a warning, records it in a clone-local drift record (aux_row_rekey_driftedinlocal_metadata), and completes the migration; recorded tables are retried on later migration passes and are exempted from the changed-signature dirty-table guard so the retry cannot re-brick the database (#4380).
[1.1.0] - 2026-07-04
First stable release of the 1.1.0 line. It consolidates everything from [1.1.0-rc.1] and [1.1.0-rc.2] (see those sections below for the full feature set) plus the post-rc.2 migration-recovery fixes listed here. The theme of 1.1.0 is a safe schema-migration and upgrade path: it repairs the v52/v53 drift classes that broke real-world rc.1/rc.2 upgrades, makes an interrupted migration recoverable in-tool instead of a dead end, and turns the remote-migrate gate from a blunt block into a state-aware one.
Upgrade Notes
- Back up before migrating (
bd export --all -o backup.jsonl) before runningbd migrateon an older, especially remote-backed, database. The fixes below repair databases that reached a migration with drifted state; an export is cheap insurance while such drift is being repaired.
Changed
- The state-aware remote-migrate gate is now on by default. rc.2 shipped
the smart gate behind an opt-in env var, but nothing in the gate's block
message or docs surfaced that the var existed, so in practice everyone kept
hitting the blunt always-block behavior. The provably-safe first-mover case
(remote at the same schema version as this clone) now auto-migrates without
BD_ALLOW_REMOTE_MIGRATE; remote-ahead still stops with an adopt directive and content skew still stops for a human. SetBD_SMART_GATE=0to opt out and restore the unconditional block (#4516).
Fixed
- A failed v53 migration no longer traps the database, and the v53 repair
now covers
wisp_dependenciessplit-column drift. rc.2 repaired theissuesrig columns, but a database coming from schema v49 could still fail v53 when itswisp_dependenciestable was missing the split target columns (depends_on_issue_id,depends_on_wisp_id,depends_on_external) — and a half-applied v53 then bricked every subsequent command on open (#4555). The migration runner now adds and backfills the missing split columns before v53, and a narrow recovery gate lets an already-failed-v53 database self-heal on the next open — including theissue_snapshots/compaction_snapshotstables that migration 0051 leaves dirty during a single-pass v49→v53 upgrade (#4558). - A dirty working set no longer deadlocks migration recovery in embedded
mode. Every store open runs the migration, which correctly refuses to
alter tables that have uncommitted working-set changes — but the documented
recovery (commit the working set) is itself a command that opens the store
and hits the same refusal, a deadlock with no in-tool escape
(#4566).
bd dolt commitandbd vc commitnow open past that guard, commit at the current schema, after which a normalbd migrateapplies cleanly; the refusal message now names the recovery path (#4567).
[1.1.0-rc.2] - 2026-07-02
Second release candidate for 1.1.0. Fixes the two upgrade-breaking migration regressions reported against rc.1 (#4502, #4534), hardens the remote-migrate gate that rc.1 introduced, and ships the validated upgrade documentation.
Upgrade Notes
- Back up before migrating. The upgrade guide's remote-backed recipes now
start with a JSONL export (
bd export --all -o ...) beforeBD_ALLOW_REMOTE_MIGRATE=1 bd migrate. The two fixes below repair real databases that reached a migration with drifted state; an export is the cheap insurance while such drift is being repaired.
Fixed
- v53 migration no longer fails on pre-rig
issuestables. The rig/agent columns (hook_bead,role_bead,agent_state,last_activity,role_type,rig) were only ever added to the squashed bootstrap0001_create_issues, so a database bootstrapped before they existed sits at schema v52 without them — and migration 0053, which copies those columns fromwisps, failed withUnknown column 'agent_state' in 'issues'even with zero rig wisps to repair (#4502). The migration runner now repairs the drift in code immediately before applying v53, adding whichever of the six columns are missing (databases in the wild may have some but not all). Shipped migration files stay frozen — the repair lives in the runner because a failing migration can never be fixed forward by a later migration file. - One orphaned
child_countersrow no longer bricks everybd create. Migration 0039 droppedfk_counter_parentand clone-local migration 0002 re-added it underFOREIGN_KEY_CHECKS = 0, so a counter row orphaned during the FK-less window (an interrupted create, a parent deleted without cascade) survived the constraint's return — and Dolt then failed constraint validation on every subsequent insert, including brand-new top-level issues, on an otherwise healthy database (#4534). A new clone-local migration moves any live-wisp counters towisp_child_countersand deletes rows dangling fromissues— the same rows the FK'sON DELETE CASCADEwould have removed had it been in force. Runs automatically on the next command with the new binary; already-bitten databases are healed in place. - Old binaries fail fast on writable opens of a schema-newer database instead of proceeding against a schema they do not understand (#4531) — the guard rail for the mixed-version window during multi-clone upgrades.
- Prerelease GitHub releases now ship prerelease-correct install instructions. The release notes header previously showed the stable install methods (brew, install scripts), three of which do not deliver a prerelease (#4530).
bd rememberno longer clobbers a memory whose content is its own key, and a barebd remember <existing-key>now recalls instead of overwriting.
Added
- Smarter remote-migrate gate. The gate introduced in rc.1 is now state-aware and agent-safe: cases that are provably safe to migrate auto-resolve instead of stopping every agent at the wall, while genuinely risky states still require the designated migrator (#4515, #4516).
- Backend-agnostic storage conformance test suite (#4414).
Documentation
- Validated upgrade recipe for remote-backed / multi-clone databases in the upgrade guide, exercised end-to-end on a live database (#4514), plus a consolidated Homebrew tap-migration snippet across install docs, a README pointer to the upgrade guide, and a pre-migrate backup step in the recipes (this release).
[1.1.0-rc.1] - 2026-06-23
Upgrade Notes
-
Mixed bd versions sharing one Dolt remote. Pre-1.0.6 binaries record applied migrations as
(version, NULL)while 1.0.6+ records(version, sha256)inschema_migrations, so two clones applying the same migration with different bd vintages used to produce a row conflict onbd dolt pull. The pull auto-resolver now resolves this class by keeping whichever side recorded the hash. Two different recorded hashes for the same version are the real #4259 schema fork and are still surfaced to the operator (see thebd doctorMigration Content Skew check). To avoid the mixed-vintage window entirely, upgrade all clones of a shared remote together, letting one designated machine migrate andbd dolt pushfirst. -
Upgrading a remote-backed database: one machine migrates, the rest adopt. This release reshapes the
dependenciesprimary key (migration0050), andbdnow refuses to silently migrate a database that has a Dolt remote configured. If two clones cross the0050boundary with un-synced dependency edits on both sides, their histories become permanently un-mergeable — Dolt refuses the merge outright (cannot merge because table dependencies has different primary keys in its common ancestor) before the pull auto-resolver can run. Replacing the binary alone is not enough; follow the ordered recipe:- With your current binary, on every clone:
bd dolt push+bd dolt pulluntil all are in sync, then stop editing. Once the new binary is installed,push/pullare gated too, so this must happen first. - Designated migrator only: install the new binary, then
BD_ALLOW_REMOTE_MIGRATE=1 bd migrateandbd dolt push. - Every other clone: install the new binary, then
bd bootstrapto adopt the migrated database (bd dolt pullis refused while the clone still has pending migrations; do not migrate on these clones). - Confirm with
bd version; in server mode,bd doctoradds a migration-content-skew check (not available in embedded mode).
A single clone with a remote follows the same gate (push with the old binary, then migrate and push). Full recipe and the single-clone variant: Upgrading bd — remote-backed databases and multiple clones. If clones have already forked, see the recovery playbook: docs/RECOVERY.md#pk-fork-refused.
- With your current binary, on every clone:
Added
-
perf(schema): composite
(status, updated_at)and standalonedefer_untilindexes onissues(migration 0052). Speeds upbd staleandbd readyon large rigs. First run after upgrade applies the migration — expect a one-time 10–25 s pause on rigs with >10K issues. Do not interrupt. -
Per-migration content hash.
schema_migrationsnow records the SHA-256 of each migration's file content alongside its version (content_hash), so two clones at the sameMAX(version)but with divergent migration content become detectable (reporter fix No.2 for #4259). The column is added to fresh databases via the bootstrap schema and idempotently to existing databases at migrate time; already-applied rows keep a NULL hash. The column definition and the hashes are deterministic, soschema_migrationsstill merges cleanly across clones. -
bd doctormigration-content-skew check. Using the recorded hashes,bd doctornow compares the localschema_migrationsagainst the cached remote-tracking ref (no network fetch) and warns when this database and its remote applied different content for the same migration version — the silent schema fork from #4259, surfaced as a clear advisory instead of a cryptic merge failure. Read-only diagnostic (it does not gate push/pull); the comparison primitive (schema.ContentHashSkew) is reusable. -
Remote-migrate prevention gate.
bdnow refuses to silently auto-apply pending schema migrations to an existing database that has a remote configured (in both server and embedded mode), and tells the operator to choose: migrate (as the single designated migrator, thenbd dolt push) or adopt the already-migrated database from the remote (bd bootstrap). Migrating each clone independently forks the schema and breaksbd dolt pull(#4259). The gate is a no-op for fresh databases, databases already at the binary's version, databases with no remote, and read-only opens. The designated migrator proceeds withBD_ALLOW_REMOTE_MIGRATE=1. In server mode the gate also detects remotes persisted on disk in.dolt/config, so a freshly (auto-)started server — whose in-memorydolt_remotestable is not yet populated — cannot slip a remote-backed database past the gate. -
Recovery guidance for Dolt primary-key merge refusals. When
bd dolt pull(orpush) fails with Dolt's hard refusalcannot merge because table X has different primary keys [in its common ancestor]— the un-mergeable schema fork left behind by independently-migrated clones straddling a PK-reshaping migration (#4259) —bdnow recognizes the error class and prints the bootstrap-from-canonical-clone recovery recipe instead of just the raw error. Full playbook: docs/RECOVERY.md#pk-fork-refused.
Fixed
-
Cross-clone issue-delete vs child-row-insert merges now converge. The synced child tables (
dependencies,labels,comments,events, snapshots) carryFOREIGN KEY ... ON DELETE CASCADEtoissues(migrations0041/0042), but Dolt merges row-wise and never re-executes cascades: if clone A deleted an issue while clone B added a dependency, label, or comment referencing it,bd dolt pullfailed outright with a foreign-key constraint violation ("transaction rolled back"), recorded nothing indolt_conflicts, and could never converge on retry. The pull auto-resolver (SQL and CLI routes) now repairs this class by applying the foreign key's own cascade semantics — deleting the merged-in rows whose issue reference dangles — and refuses, exactly as before, any constraint violation it does not recognize (different constraint type, table bd does not own, FK to another parent). The repair converges across clones: it deletes precisely the rows the cascade already removed on the deleting clone. (bd-6dnrw.4) -
is_blockedrecompute no longer misses auto-resolved merges. A pull whose merge bd auto-resolved (conflicts) or cascade-repaired (constraint violations) lands in the working set without advancing HEAD — the merge commit is created later — so the bd-6dnrw.3 post-pull recompute mistook it for "nothing merged" and skipped, leavingis_blockedstale exactly when the merge had needed intervention. The recompute now diffs to the working set and skips only whenissues/dependenciesare clean too. (bd-6dnrw.39) -
is_blockedrecomputed afterbd dolt pull. The denormalizedis_blockedcolumn (migration0046) was maintained only by local write paths, so a pull that merged another clone's writes silently left it stale — e.g. clone A closes blocker X while clone B adds an edge W→X, and the merged result carriesW.is_blocked=1with a closed blocker, hiding W frombd ready. Every pull path (server SQL and CLI routes, peer pulls, embedded mode) now recomputes the column for exactly the rows the merge changed, scoped viadolt_diffbetween the pre- and post-pull HEADs and expanded through the same affected-set logic the local write paths use. Oversized or schema-reshaping merges fall back to a full recompute; conflicted pulls skip it until the operator resolves. (bd-6dnrw.3, PR 4107 follow-up) -
Stale
is_blockedis now repairable —bd recompute-blocked. The post-pull recompute above is scoped to the merge diff and is skipped when a re-pull merges nothing (HEADunchanged), so a recompute that failed after its merge committed — or a conflicted pull resolved by hand (which skips the recompute) — could leaveis_blockedstale with no way to repair it: rerunningbd dolt pullmerged nothing and recomputed nothing. The newbd recompute-blockedcommand runs a full, unconditional recompute over every issue and wisp and commits the result; it is idempotent and works in both embedded and server mode (unlikebd doctor, which is server-mode only). Server-modebd doctoralso gains a read-only Blocked State check that reports stale rows and abd doctor --fixthat runs the same repair. (bd-6dnrw.37) -
Deterministic history-table primary keys (cross-clone merge-safety). Migration
0037converted the legacy BIGINT primary keys ofevents,comments,issue_snapshotsandcompaction_snapshotsby backfillingUUID()— a different random value on every clone, the same hazard class as thedependenciesfork below. Two legacy clones that upgraded independently held identical history rows under different primary keys, so their merges duplicated every pre-upgrade event and comment (or refused outright). A one-time-per-clone upgrade backfill now rewrites those ids to deterministic values derived from each row's content (internal/storage/rowid), so independently-migrated clones converge to byte-identical history tables; exact-duplicate rows are kept distinct via per-duplicate ordinals. The pass is gated on a clone-local marker (ignored migration0009), so steady-state opens never re-key — rows inserted after the pass are minted once and reach other clones by merge, so their ids are already consistent. (bd-6dnrw.2, the history-table sibling of #4259) -
Deterministic dependency primary keys (cross-clone merge-safety).
dependencies.id(andwisp_dependencies.id) were filled byDEFAULT (UUID()), a per-clone-random value. Two clones that created the same edge — or that applied migration0043independently — diverged on the primary key, sobd dolt pullfailed unrecoverably (cannot merge because table dependencies has different primary keys in its common ancestor, or auk_dep_*unique-key violation).idis now derived deterministically from the natural edge key(issue_id, target)at every insert site (internal/storage/depid); migration0050drops the random default and idempotently re-asserts the natural-identity unique keys; and an upgrade backfill rewrites existing rows. Independently-migrated clones now converge to byte-identical, merge-safedependencies. And because the same edge now has the same primary key on every clone,bd dolt pullauto-resolves a same-edge dependency conflict that differs only in audit columns (created_at/created_by/metadata/thread_id) the same way it already does for the metadata table — so two machines that each runbd dep add X Ybetween syncs merge cleanly. A conflict where the dependency type differs is still surfaced for the operator. (#4259)
[1.0.5] - 2026-05-28
Upgrade Notes
-
JSONL auto-export and auto-staging are now opt-in. Repositories that relied on the previous implicit default should set it explicitly before or after upgrading:
bd config set export.auto true bd config set export.git-add trueDolt is the primary datastore.
.beads/issues.jsonlis now treated as an optional export for viewers such asbv, interchange, and issue-level migration. It is not the canonical git-tracked source of truth, not cross-machine sync, and not a full database backup. Usebd dolt push/bd dolt pullfor sync andbd backupfor restorable database backups. Existing repositories that already haveexport.auto: trueorexport.git-add: trueconfigured keep that behavior.
Added
-
Schema-version guard:
bdnow hard-fails at database-open time when the database schema is ahead of the binary's embedded migrations. This protects against cryptic SQL errors (e.g.,column X could not be found in any table in scope) that occur when an older binary opens a database migrated by a newer one. The error message names the exact version mismatch and provides a copy-paste rebuild command. Use--ignore-schema-skew(or env varBD_IGNORE_SCHEMA_SKEW=1) to bypass the guard when you know the forward migrations are safe for your workload. Fresh databases and normal forward-migration paths are unaffected. -
Foreign keys across issue and wisp tables. Migrations
0040–0042and the newignored/0001–ignored/0004add explicit FKs withON DELETE CASCADE ON UPDATE CASCADEondependencies,labels,comments,events,issue_snapshots,compaction_snapshots,child_counters, and the matchingwisp_*tables. Deleting or renaming a parent row now cascades automatically — the manual cleanup loops inissueops/delete.go,dolt/wisps.go,dolt/ephemeral_routing.go, andcmd/bd/rename_prefix.gohave been removed (net ~300 lines down). (#3952) -
issueops.DeleteWispFromDependenciesInTx/UpdateWispIDInDependenciesInTx. Because Dolt forbids foreign keys from tracked tables (dependencies) todolt_ignore'd tables (wisps), wisp deletion and rename now invoke these helpers explicitly to keepdependencies.depends_on_wisp_idconsistent. The standard store APIs (DeleteIssue,UpdateIssueID,deleteWispBatch, etc.) wire them up automatically; only call them directly if you bypass those entry points. (#3952) -
Forward schema-skew guard.
bdnow hard-fails when it opens a database that has been migrated to a newer schema version than the binary understands, instead of operating blindly on forward-migrated data. (#4152) -
dolt.modeconfig key. Newdolt.mode(server|embedded) configuration key with validation;bd initnow warns on ambiguous configs and hard-fails whendolt.host/dolt.portare set without server mode. -
bd list --skip-labels. New toggle to skip label hydration for faster listings; honored in both text and JSON output. -
bd showcount-only JSON details.bd show --jsoncan return count-only relationship details with opt-in streamed payloads, avoiding large hydrations when only counts are needed. -
Server-side custom type validation. Storage now honors
.beads/config.yamltypes.customduring server-side validation. (#4024, #4026) -
bd initcontributor routing. On fork detection,bd initauto-configures contributor routing. (#4028)
Changed
-
Large content columns widened to
LONGTEXT. Issue content and event/wisp-event value columns are migrated fromTEXTtoLONGTEXT, lifting the previous ~64 KB per-field ceiling. (#4027, #3682) -
dependencies.depends_on_idis now a STORED generated column. The polymorphic target has been split into three typed columns:depends_on_issue_id,depends_on_wisp_id,depends_on_external.depends_on_idremains asCOALESCE(...) STOREDfor read paths; writes todepends_on_idwill fail — code that inserts dependencies must populate exactly one typed column (enforced by a newck_dep_one_targetCHECK). Same split mirrored towisp_dependencieswith a correspondingck_wisp_dep_one_target. Migrations0041(tracked) andignored/0003(wisps) perform the column split, copy existing rows by classifying their targets againstissues/wisps, and add the new typed-target indexes. (#3952) -
Most existing dependency-table FKs now use
ON UPDATE CASCADE. Migration0042rebuildsfk_dep_issue,fk_labels_issue,fk_comments_issue,fk_events_issue,fk_snapshots_issue, andfk_comp_snap_issueto cascade on both delete and update. Same treatment for the wisp-side FKs inignored/0003. Prefix rename and ID-update paths rely on this cascade instead of touching aux tables manually. (#3952) -
Migrations
0041and0042are intentionally irreversible. The matching.down.sqlfiles are documented no-ops because rebuilding the polymorphic column from typed columns would require schema-aware backfill that the storage layer no longer performs. Restore from a priordoltcommit if rollback is required. (#3952) -
BEADS_MAX_ROWS/--max-rowsdefensive row cap — ops can now setBEADS_MAX_ROWS=N(or passbd list --max-rows N) to boundSearchIssuesresult sets. Default is disabled; on overage,bdexits with code 2 and writes a two-line error to stderr (stdout stays empty sojqpipelines don't get half-rendered JSON). The flag is wired onbd list,bd ready,bd dep tree,bd find-duplicates, andbd graph. The env var is also honored bybd doctor,bd lint,bd doctor-conventions, andbd doctor-pollution.bd cleanup,bd gc,bd export,bd export --auto,bd migrate-issues, andbd jiraexplicitly opt out so a misconfigured env can't abort a sweep partway. (be-x42v)
Fixed
- Symlinked
CLAUDE.mdrepair guidance - troubleshooting docs now include a testedgit update-index --cacheinforecipe for repositories that already contain a corruptedmode 120000CLAUDE.mdentry with Markdown content. The setup bug was fixed in #4192; this note is for repairing affected clones. - Codex hook metadata isolation - Codex hook metadata now lives under
.codex-plugin/hooks/, preventing Claude from loading Codex-only hooks from the shared plugin root while keeping Codex setup pointed atbd codex-hook. (#3924) - Hook and prime wait bounds - generated git hooks now fall back from
timeouttogtimeoutto Perlalarm, andbd primememory loading is bounded byBEADS_PRIME_TIMEOUT(default 10s). Non-positiveBEADS_PRIME_TIMEOUTvalues fall back to the default instead of silently disabling the safety bound. Internal beads-repo git operations also run with hooks suppressed viacore.hooksPath=so automated.beads/commits and pushes cannot recurse through user hook managers.GitCmdCWD()remains for user-working-repo status/ref operations and does not perform beads commits. (#4172) - JSONL auto-export shrink guard - when opt-in
export.autois enabled, auto-export now refuses to overwrite an existing.beads/issues.jsonlthat contains records outside the auto-export scope (memories, infrastructure beads, templates, ephemeral wisps, or unknown record types). This prevents a viewer/interchange refresh from silently replacing a richer JSONL file with the filtered auto-export subset. (#4069) bd quicknow treats label insertion as part of issue creation: label failures abort the create instead of being silently dropped.bd dolt statusreports externally-managed local servers truthfully - when a rig is configured asdolt_mode: serverpointing at a local host butdolt.auto-start: false(so an orchestrator or systemd owns the sql-server lifecycle),bd dolt statuspreviously saidnot runningbecause no PID file existed. It now SQL-probes the configured endpoint, matching the path already used for non-local hosts, and reportsrunning (external)with host/port/database/version when the server answers. JSON output shape change: on affected rigs,bd dolt status --jsonnow emits{"running": true, "mode": "external", ...}instead of{"running": false, "pid": 0, ...}. Automation that parsed the oldrunning:falseas a "needs restart" sentinel should switch to checkingrunningdirectly. (be-0eyj, #3550)- Migrations run on a connection with no read timeout, so large or slow schema migrations no longer fail under the default query timeout. (#4154)
- Duplicate migration version numbers now hard-fail instead of silently under-applying a release's migrations. (#4197)
bd closesupports per-id reasons when closing multiple issues at once (#4194), and re-closing an already-closed issue is now an idempotent success instead of an error. (#4025)bd create --defer <future-date>creates a deferred issue (statusdeferred) rather than an open one. (#4071)bd createcommits labels atomically during initial issue creation; label-insertion failures abort the create instead of being silently dropped. (#4149)- JSONL import preserves comment IDs and skips stale issue snapshots. (#4103, #4204)
bd initDolt wiring hardening - honor local-only remote wiring (#4227), apply config server mode before validation, platform-accurate config-path warnings, and tighter Dolt marker handling (#4083).- MCP
validateanddetect-pollutionroute tobd doctor. (#4037) bd doltdetects managed handoff port conflicts. (#4217)bd listkeepsrelates-toout of dependency tree mode and honors--skip-labelsin JSON output. (#3936)- Audit
newIDentropy widened to reduce ID-collision risk under high create volume. (#4046) - Performance:
bd countuses a SQLCOUNT(*)aggregate instead of fetching and counting rows;bd readynarrows deferred-parent child filtering;bd getqueries primary issues before falling back to wisps; andbd searchgains skip-wisps merge and wisp-count caching.
[1.0.4] - 2026-05-07
Added
bd init --reinit-local/--discard-remote— named-intent flags for local re-initialization and explicit remote-history override. Replaces the overloaded--force. Seebd help init-safetyanddocs/recovery/init-safety.md.bd init-safety— documents the init flag surface + destroy-token format. Referenced by every init refusal message.- Stable exit codes for init refusals —
10remote divergence,11local exists,12destroy-token missing. Grep-safe for CI. - ADR 0002 —
bd initsafety invariants — encodes the single-source identity rule, scope-bound--force/--reinit-local, theCheckRemoteSafetychokepoint, the error-text-no-echo rule, and the race-safety invariant. docs/RECOVERY.md— playbooks for each named init refusal.- CODEOWNERS —
cmd/bd/init*.goroutes review to maintainers with an ADR-linked acknowledgment requirement. bd -C <path>— run bd from another directory without changing the caller's shell cwd. Useful for hooks, agents, and scripts that coordinate multiple workspaces.bd close --reason-file— reads close reasons from a file or stdin, matching existing body-file workflows.- Linear sync throughput and correctness improvements — batch create/update, idempotency markers, retry-after handling, OAuth client-credentials support, and workspace-level sync locking.
- Shared Beads plugin package — Claude and Codex plugin metadata now ship together from the repository.
Changed
-
bd init --forcesemantics narrowed to local-only —--force(or--reinit-local) bypasses only the LOCAL data-safety guard. It does NOT authorize silent divergence of remote history. When origin hasrefs/dolt/data,bd init --forcenow refuses with exit code 10 unless--discard-remoteis also passed. Fixes the long-standing footgun wherebd init --forcein a repo with remote Dolt history silently set up an orphan branch that failed to push. -
Init refusal messages follow What/Why/Next structure — runtime error text no longer echoes copy-pasteable destructive invocations. Token values and exact override commands live in
bd help init-safetyanddocs/RECOVERY.mdonly. Closes the failure class where an AI agent destroyed 247 issues by pattern-matching on the tool's own error output (58f5989bf). -
beads.OpenBestAvailablesignature changed (breaking) — returns(Storage, error)instead of(Storage, Unlocker, error). The per-open flock andUnlockerreturn value were removed; the embedded Dolt engine handles its own concurrency internally. External SDK consumers that callOpenBestAvailablemust drop the second return value. (PR #3614) -
Embedded-mode flock removed — the process-lifetime exclusive flock on
.beads/embeddeddolt/has been removed. Concurrentbdprocesses now open the embedded engine independently. If the GH#2571 nil-deref stack (NewConnector→DoltDB.SetCrashOnFatalError→CollectDBs) resurfaces under concurrent access, it should be filed and fixed indolthub/driver, not reintroduced as a beads-side flock. (PR #3614) -
Auto-export is now opt-in by default — repositories without explicit
export.auto/export.git-addsettings leave JSONL refresh and staging disabled unless a viewer or JSONL integration explicitly enables them. This keeps.beads/issues.jsonlas an optional export surface, not the default mutation path. (GH#4062) Thanks Kevin Glynn for surfacing the JSONL source-of-truth mismatch through the export cleanup work that led to this change. -
Release workflow uses the checked-in beads-release formula — the old release shell path now delegates to the formula-backed release workflow with CI gates.
Deprecated
bd init --force— deprecated alias for--reinit-local. Continues to work for ≥2 releases, emits aDeprecationWarning, routes internally to--reinit-local. Use--reinit-localgoing forward. CI and scripts are unaffected for the duration of the deprecation window.
Fixed
bd close <id>in contributor auto-routing mode —bd closenow resolves IDs through the same routing fallback asbd showandbd update. Previouslybd closeerrored withno issue found matching <id>in workspaces withrouting.mode=auto,routing.contributor=<path>, andbeads.role=contributor— even for IDs thatbd createhad just returned, because the issue lived in the routed planning store whilebd closeonly checked the local primary. Bulk close (bd close <id1> <id2> ...) is also fixed by sharing one routed-store handle across the close batch. Fixes #3608.- Dolt-in-git hook recursion — internal pushes of
refs/dolt/dataskip git hooks, preventing sync loops. Fixes #3724. - Hook setup and migration safety — generated hooks no longer drop sibling commands, stale Claude hooks are warned about, and post-pull/checkout auto-import keeps committed
.beads/issues.jsonlstate fresh. - Dependency display and routing — dependency trees show blocked state only for genuine blockers, tolerate unresolved IDs in batch output, and include dependency type information.
- Export filtering — closed memories and ephemeral wisps are excluded from default exports, and NoHistory beads survive explicit filters.
- Graph/list regressions — graph HTML emits empty arrays instead of
null, merges disconnected components for--all --html, and list output avoids duplicate issues with multiple blockers. - Configuration documentation and validation drift — stale TOML/
BEADS_*references were corrected to YAML/BD_*, and secret keys are refused in git-tracked config. - Release preflight and packaging — release formula adoption, script selection, pure-Go test helpers, Windows install cleanup, and generated CLI reference paths were hardened for the v1.0.4 release attempt.
[1.0.3] - 2026-04-24
Fixed
go install ...@latestrestored — released a tag whosego.modno longer contains localreplacedirectives, fixing install failures from v1.0.1 and v1.0.2. Fixes #3338 and #3312.- npm macOS archive layout — macOS release archives are flat, matching the path expected by the npm postinstall script. Fixes #3388.
- Windows install cleanup —
make installon Windows removes stale extensionlessbdfiles before installingbd.exe, avoiding PATH shadowing by older installs. Fixes #3399. - Windows test portability — fixed tests that hardcoded POSIX path or permission behavior. Fixes #3404.
- Embedded pre-commit hook cwd — pre-commit export no longer prints "no beads database found" for embedded-mode repositories. Fixes #3454.
[1.0.2] - 2026-04-15
Fixed
- npm publish: provenance validation —
npm-package/package.jsonrepository.url,bugs.url, andhomepageupdated fromsteveyegge/beadstogastownhall/beadsso that npm's sigstore provenance validator accepts the published artifact. The repo move in v1.0.0 left these URLs stale, which caused npm publishes for v1.0.0 and v1.0.1 to be rejected after provenance check (E422).
[1.0.1] - 2026-04-15
Added
bd batch— Atomic multi-operation transactions across create/update/close/dep. All ops commit together or none do. (PR #3165)bd config drift/bd config apply— Detect and reconcile drift between yaml, git, and database config surfaces. (PR #3086)bd config show— Unified provenance view showing where each effective config value comes from. (PR #3084, bd-934)started_aton issues — Timestamp recording when an issue first enteredin_progress. (PR #3206, GH#2796)beads_globalshared-server database — Dedicated shared-server database for cross-project state. (fa87dd2b)- Pool metrics telemetry — Shared-server connection pool metrics for diagnosing pool exhaustion. (PR #3172, GH#3140)
OpenBestAvailablepublic API — Library consumers can open the best available backend without hard-coding selection. (PRs #3143, #3149)- Selective sync:
--issuesflag andpush/pullsubcommands — Tracker sync accepts explicit issue ID lists;--parentported across trackers. (PR #2975) --label/--label-anyforbd orphans— Filter orphan detection by label. (PR #3026)- Cross-version smoke tests — CI gate for upgrade compatibility across prior releases. (GH#2968)
- Migration test harness — Cross-era upgrade fidelity tests. (PR #3067)
- Docusaurus versioning — Site versioned per release;
llms-full.txtaligned with snapshots. (PR #3033) - Azure Blob Storage remotes —
az://recognized as a valid Dolt remote URL scheme. (PR #3101) - Side-effect hints for
bd config set/unset— Shows what else changes when a config value is modified. (PR #3089) - Dynamic config-list discovery —
bd config listauto-discovers yaml keys and env vars. (PR #3088) BEADS_DOLT_READY_TIMEOUT— Override the 10swaitForReadytimeout duringbd init --shared-serverfor slower hardware. (PR #3188, GH#3142)
Changed
- Auto-export enabled by default —
export.autodefaults totrueand the defaultexport.pathis nowissues.jsonl(previouslyexport.jsonl), withexport.git-addon by default.bd initprompts interactively (default: keep enabled);--non-interactivekeeps it enabled. Allexport.*keys are listed inbd config --help. (PR #3204, GH#2973) gms_pure_goby default — Test and install helpers default to the pure-Go build tag, dropping ICU linkage from CI. (PRs #3240, #3259)- ICU runtime dependency removed from release binaries — Release builds no longer link ICU, fixing portability issues. (PR #3066)
- Dolt connection pool lifetime configurable — Longer default, configurable via env. (PR #3163)
- Dolt connection TLS explicitly disabled — When TLS is not configured, connections now explicitly opt out rather than depending on driver defaults. (PR #3107)
- Dolt log noise reduced —
NewConnectionspam silenced;dolt-server.logrotates at startup to cap size. (PRs #3160, #3161)
Fixed
- Schema migration conflict — Removed a conflicting column on the schema migration table; migration issue patched with test coverage. (commits
f079786b,65dbdbf5,9aa9b82f) - Wisp tables missing after bootstrap clone —
bd bootstrapnow ensures wisp tables exist after cloning. (commit31d51232) - CI test binary timeout on macOS —
bdtest binary memoized to avoid 10-minute timeout. (PR #3273) - Local-only state moved to Dolt-ignored tables — Prevents local state from polluting shared history. (commit
50f715b1) - Worktree awareness across commands — Hooks path, fingerprint, doctor checks, config validate, preflight, reset, bootstrap path synthesis,
rename-prefix,countExistingIssues, and formula search paths all resolve correctly when run inside a git worktree. (PRs #3169, #3123, #3235, plus numerous smaller fixes) bd bootstraphardening — Commitsissue_prefixto the config table; writesmetadata.jsonandconfig.yamlafter sync clone; uses parent workspace db name when local.beadsmissing; rejects empty--database; auto-start allowed for migration tests. (PRs #3203, #3247, #3083, #3076)- Remote URL validation hardened at config parse time — Security hardening for tracker and backup remotes. (PR #3210)
bd listtruncation hint in all output modes — Truncation now indicated in JSON/compact/long formats. (PR #3243, GH#3212)bd list --watchhierarchy consistency — Parent/child ordering stable across watch refreshes. (PR #3236)bd update --defersets status=deferred — Deferring an issue now transitions status correctly. (PR #3241, GH#3233)bd mol bondtransitive cycle detection — Cycles through transitive dependencies now caught. (PR #3111, GH#2719)bd dep add/removeallows cross-prefix targets — No longer rejects dependencies that cross prefix boundaries. (commit7b02edda)bd dolt pullnil-pointer panic in embedded mode — Embedded backend no longer panics on pull. (PR #3148)- Diverged-history guidance on auto-push failure — Actionable recovery steps printed instead of raw error. (PR #3138)
bd configerror message hints — Suggestbd config set(notbd config) in error messages. (PR #3141)- JSONL export in pre-commit hook — Atomic code+issues commits via pre-commit hook. (PR #3121)
- Auto-export / auto-backup errors surfaced to stderr — Silent failures now visible. (PR #3122)
go installon Windows — Fixed ICU header dependency that brokego installon Windows. (PR #3112, GH#3013)- Stepping-stone migration paths removed — Unsupported intermediate migration versions cleaned up. (PR #3110)
- SQLite-era JSONL migration preserves dependencies and labels — Migration from pre-Dolt exports no longer drops graph edges or labels. (PR #3082, GH#3079)
- MCP workspace discovery detects Dolt-backed projects — MCP server no longer misses Dolt-native repos. (PR #3207, GH#2997)
- npm postinstall closes download streams — Resource leak fixed. (PR #3228)
- Husky hooks sanitized when copied — Husky-managed hooks no longer corrupt beads-managed hook directory. (PR #3208, GH#3132)
- GitLab issue link dependencies wired into sync pull — Dependencies via GitLab links now import. (PR #3202, GH#2645)
.beads/FS_NOCOW_FL on btrfs — Prevents btrfs kworker thrashing on Dolt files. (PR #3162)- Auto-commit config table writes —
bd remember,bd forget, andbd configcommands now commit their writes. (PR #3052, bd-g8p) - Shared-server CLI dir resolved from shared root — Corrects path resolution for shared-server layouts. (PR #3223)
.claude/gitignore narrowed — Blanket ignore replaced with specific patterns so project.claude/content is tracked. (PR #3190, GH#3182)- Release archives extracting into subdirectory — Install handles nested archive layouts. (PR #3167)
bd importhelp text — Removed references to nonexistent-iflag. (PR #3200)
Docs
- ADR-0001: multi-remote approach decision (PR #3209)
- ICU regex policy / build dependency guidance (GH-3126)
- Contributor protection policy for AI agents (PR #3151)
- Cross-era migration instructions (PR #3081)
- Unified quick-start (site + stub) (PR #3032)
- Hosted docs link (PR #3011)
[1.0.0] - 2026-04-02
1.0 — Stable Release
Beads 1.0 marks the transition from rapid iteration to production stability. The Dolt migration that began in v0.55.0 is complete: embedded Dolt is the default on all platforms, server lifecycle management is no longer required, and the critical reliability issues that affected the v0.55–v0.63 series have been resolved.
Added
- Embedded Dolt default on macOS — Native CGO builds on macOS enable embedded Dolt by default, eliminating the external Dolt server entirely. (PR #2971)
- Custom status/type normalized tables —
custom_statuses(name, category)andcustom_types(name)tables replace comma-separated config strings. Views use table-backed subqueries instead of dynamic IN clauses. Migration is automatic and idempotent. (PR #2961) bd rules auditandbd rules compact— Scan.claude/rules/*.mdfor contradictions and near-duplicates; merge rule groups with deduplication. (PR #2810)bd config set-many— Batch config operations across yaml, git, and database keys in a single command. (PR #2943)- Credentials file support —
~/.config/beads/credentialsfor Dolt server passwords with Unix permission checks, env var override, and proper DSN escaping. (PR #2854) - Spike, story, and milestone issue types — First-class support with constants, validation, and normalization aliases. (PR #2923)
- GitLab sync: epic→milestone, task hierarchy, type filtering — Epics sync as GitLab milestones, tasks create work items via GraphQL with parent hierarchy, internal types excluded from push by default. (PR #2889)
- ADO shorthand refs —
ado:NNNNNrecognized in IsExternalRef and ExtractIdentifier, preventing duplicates on sync. (PR #2966) - ADO push filters —
--types,--states, and--no-createflags now apply to push operations. (PR #2944) - Public format package —
format.PrettyIssue,CompactIssue,LongIssuefor external tooling. (PR #2871) - SlotSet/SlotGet/SlotClear — Per-issue metadata slots in the Storage interface for delegation tracking and hook state. (PR #2870)
- WispFilter export —
beads.WispFiltertype alias exported from root package. (PR #2868) --non-interactive/--yesfor bootstrap — Skip confirmation prompts in CI/automation. (PR #2942)- Batch dependency list —
GetDependenciesWithMetadatasupports multiple issue IDs. (PR #2875) bd ready --explain— Dependency-aware reasoning for why issues are or aren't ready. (PR #2814)- Graph integrity enforcement — Extended cycle detection and
bd graph checkcommand. (PR #2814) - Tracker hardening — Retry logic with jitter for all tracker HTTP clients, pagination guards for Linear/Jira, response size limits, terminal-safe content sanitization. (PRs #2814)
- Release stability gate — Upgrade safety checks and breaking-change communication. (GH#2951)
- Hook firing in storage layer —
HookFiringStoredecorator moves hook logic out of CLI layer. (PR #2891)
Changed
bd setup claudedefaults to project-local — Settings written to.claude/settings.json(shared/team) by default;--globalfor user-level. Auto-runs duringbd init. (PR #2972)strconv.ParseBoolfor env vars —IsAutoStartDisableduses standard boolean parsing with whitespace trimming. (PRs #2955, #2956)- Comma-separated
--statusfilter —bd list --status open,in_progressnow works. (GH#2846) - Custom types from YAML —
ResolveCustomTypesInTxhonors config.yaml custom types in create path. (GH#2793) - lipgloss v2, backoff v5, goldmark 1.8.2 — Dependency updates.
Fixed
- Concurrent embedded Dolt panic — Exclusive flock acquired on embedded store open, held for store lifetime. Second concurrent opener gets a clear error instead of a nil-pointer panic. (GH#2571)
- Spaces in repo path — Embedded Dolt no longer URL-encodes local filesystem paths, fixing
%20lookup failures on macOS. (GH#2920) - Schema version bump —
currentSchemaVersionbumped to 11 for custom_statuses/custom_types migration. Prevents "table not found" errors on upgrade. (GH#2974) - Dolt init failure — Embedded-by-default eliminates server port 0 / connection refused issues for new users. (GH#2656)
- Bootstrap for missing database —
bd bootstrapprobes server for actual database existence before declaring no-op. Recovery guidance updated across all error surfaces. (PR #2940) - Diverged history recovery — Dolt push/pull detect diverged history and print actionable recovery guidance. (PR #2941)
- No-db command routing —
bd context,bd dolt show, etc. honor--dbflag,BEADS_DBenv, and externaldolt_data_dirlayouts. (PR #2844) - Auto-backup address conflict — Detects when another backup remote owns the URL and syncs through it. (PR #2927)
- Shared server project_id —
bd init --databaseon a shared server adopts existing_project_idinstead of generating a new one. (PR #2925) - Init leaves beads.role unset — Fixed edge cases where role was not persisted during init. (GH#2950)
--shared-servermode detection — Correctly treated as server mode for DoltMode resolution. (PR #2947)- GitLab work_items URL dedup — Pull dedup checks both issues and wisps tables; URL pattern matches
/work_items/paths. (PR #2889) - GitLab work item type ID — Dynamic GraphQL query with per-session cache instead of hardcoded
gid://.... (Follow-up to PR #2889) - Stale noms LOCK files — Cleaned after bootstrap clone. (PR #2913)
- ADO WIQL date precision — RFC3339 timezone formatting in WIQL queries. (PR #2911)
- Blocked icon in
bd list— Dependency-blocked issues now show blocked indicator. (GH#2858) - Installer ICU/CGO fallback — Correct handling on systems without ICU libraries. (PR #2965)
Community
Contributors: harry-miller-trimble, coffeegoddd, quad341, Bella-Giraffety, maphew, rjc123, Fredkr, sammywachtel, anupamchugh, ktoulgaridis, outdoorsea, Geargrindadmin.
[0.63.3] - 2026-03-30
Added
- Embedded mode by default — New installations now use embedded Dolt as the default storage backend, eliminating the need to run a separate Dolt server process. Existing server-mode installations are unaffected. (PR #2842)
bd create --graph— Batch issue creation from a YAML/JSON dependency graph, replacing the standalonebd graph-applycommand. (PR #2894)- Multi-project/team sync — Linear, Jira, and ADO integrations now support syncing multiple projects and teams in a single repo. (PR #2868)
- Notion sync — Reimplemented Notion integration on REST data sources with full page property mapping. (PR #2843)
- GitLab sync — Optional group-level GitLab issue sync. (PR #2801)
- Linear
--parentflag —bd linear sync --parentlimits sync push to a specific ticket tree. (PR #2853) - Remote URL support — Multi-repo hydration now supports remote URLs. (PR #2827)
- Top-level command aliases —
bd comment,bd assign,bd tag,bd link,bd priorityas convenient shortcuts. (GH#2611) - Storage interface expansion —
ListWisps,MergeSlot,ReopenIssue,UpdateIssueType, replication, and VC interfaces now exposed in the public API. (PRs #2782-#2788) - SearchIssues dependency hydration — Bulk dependency population for search results. (PR #2773)
--agents-fileflag —bd init --agents-filecustomizes the agent instructions filename. (PR #2761)- Multi-process concurrency tests — Server lifecycle and concurrent access integration tests. (PR #2767)
Changed
- Backup system simplified — Removed git-based backup/restore (
backup export-git,backup fetch-git). Backup and restore now operate exclusively through Dolt's native replication. (PR #2842) - dolthub/driver v1.84.0 — Updated from v1.83.8, picking up serialization retry support.
- Dolt write retry —
writeRetryTxautomatically retries on Dolt serialization errors. (PR #2855) - CI overhaul — Test sharding, precompiled binaries, shared Go module cache for faster CI runs.
- Gas Town terminology removed — Remaining Gas Town naming removed from beads orchestrator detection. (PR #2762)
- TypeScript v6, backoff v5, goldmark 1.7.17 — Dependency updates.
Fixed
- Init git cache reset —
bd initnow resets git caches after auto-init, preventing stale.beads/dolt/references in embedded mode. (PR #2907) - Doctor embedded mode — Improved embedded mode detection and push error guidance. (PR #2910)
- Create description warning — Removed spurious description warning; test-issue warning now gated on DB size. (PR #2908)
- External contributor PRs —
block-gh-watchhook now allows external contributors to create PRs. (PR #2907) - CWD
.beads/priority —bdnow checks CWD for.beads/before git-worktree resolution, fixing worktree-based discovery in nested projects. - Epic closure eligibility — Wisp children now correctly included in epic closure checks. (PR #2843)
- Prefix routing —
bd edit,bd reopen, andbd deletenow correctly route with prefixes from town root. (PRs #2780, #2847) - ADO/Jira custom type_map — Custom type maps no longer silently ignored. ADO dependency links now imported correctly. (PR #2771)
- Init safety guard —
bd init --forceno longer bypasses close --quiet check. (PR #2799) - Circuit breaker TTL — Stale circuit breaker files cleaned during init; files moved to subdirectory. (PR #2799)
bd show --watch— Replaced fsnotify with polling to fix cross-platform compatibility. (PR #2755)- Config unset routing —
config unsetnow routes to correct store; backup keys shown in list. (GH#2727) - Doctor false errors — Server health checks skipped when no Dolt server expected; bare worktree fallback fixed. (GH#2722)
- UTC timestamps — ADO/Jira defer_until comparisons use UTC_TIMESTAMP(). (PR #2819)
- Cloud storage routing — Push/pull routed through CLI when cloud storage env vars are set. (GH#2820)
- Embedded schema — Removed HOP columns (crystallizes, quality_score) from embedded schema. (PR #2837)
- JSON path quoting — Dotted metadata keys now properly quoted in JSON path expressions. (PR #2865)
- Hook fire on update —
bd update --status closednow fires on_close hook;bd closefires on_update. (PR #2754)
Embedded Dolt
- 46 commits from the Dolt team (coffeegoddd) completing embedded Dolt support: bootstrap, compact, migrate, sync, backup, restore, maintenance, setup, config, and advanced commands. Includes serialization retry, driver bump to v1.84.0, CI test sharding, and
RunInTransactionrefactor for sharedissueopsoperations.
Community
Contributors: coffeegoddd (Dustin Brown), matt wilkie (maphew), harry-miller-trimble, quad341, ktoulgaridis, eitsupi, renezander030, REMvisual, aphexcx, anupamchugh, MovGP0, Bella-Giraffety, julianknutsen, osamu2001, toumorokoshi, fernanja, sammywachtel, outdoorsea.
[0.62.0] - 2026-03-21
Added
- Custom status categories —
bd config set status.custom "in_review:active,qa_testing:wip,archived:done,on_hold:frozen"assigns categories to custom statuses that control behavior inbd ready(active statuses included) andbd list(done/frozen statuses excluded by default). Backward compatible — old flat format"foo,bar"still works with no behavior change. (PR #2665) bd statusescommand — Lists all built-in and custom statuses with their icons, categories, and descriptions. Supports--jsonfor programmatic use.bd notecommand — Shorthand for appending notes to issues without thebd update --noteceremony.- Audit logging — Status, assignee, and priority changes are logged to
.beads/interactions.jsonlwith close reasons. Survives Dolt GC flatten, so you can recover context after aggressive cleanup. --exclude-typeflag —bd ready --exclude-type wispandbd list --exclude-type wispfilter issues by type.--agents-profileflag —bd init --agents-profile minimalcontrols the default AGENTS.md profile (full/minimal).- Memories in export/import —
bd export/bd importnow round-trip agent memories. - Azure DevOps integration — New
bd adocommands for syncing work items with Azure DevOps (bd ado sync,bd ado status,bd ado projects). - MCP
readytool filter —issue_typefilter exposed on the MCP ready tool for agent use. - Quality/lifecycle commands in prime —
bd prime, templates, andbd doctornow surface quality and lifecycle commands.
Changed
- BEADS_ACTOR replaces BD_ACTOR —
BEADS_ACTORis now the primary environment variable for agent identity;BD_ACTORremains as a deprecated fallback. - ServerMode enum — Dolt server ownership inference consolidated into a clean
ServerModeenum (Auto, External, Shared, Embedded), replacing ad-hoc string checks. - dolthub/driver v1.83.8 — Updated from v0.2.1, picking up Dolt engine improvements and bug fixes.
- anthropic-sdk-go v1.27.1 — Updated from v1.27.0.
- Internal cleanup — Removed Gas Town-specific concepts from beads types and code: GUPP references, polecat/crew/overseer terminology, HOP fields, agent-as-bead subsystem, patrol molecule references, role templates, hardcoded
~/gt/paths. Beads is now fully standalone.
Fixed
- Windows Dolt server lifecycle —
ErrServerNotRunningsentinel error prevents false "failed to stop" warnings; stale PID/port files cleaned up even when server is already dead. (GH#2670) - Hook preservation —
bd initnow preserves ALL pre-existing hooks (not just beads-managed ones) when overridingcore.hooksPath. (PR #2738) - Shim timeout — Hook shim timeout increased from 30s to 300s, preventing premature termination of chained pre-commit pipelines (linters, formatters, type-checkers). Configurable via
BEADS_HOOK_TIMEOUT. (GH#2732) - GetNextChildIDTx query — Replaced broken
CAST(SUBSTRING_INDEX(...) AS UNSIGNED)with Go-sideParseHierarchicalID, fixing child ID reconciliation for non-numeric IDs after JSONL imports. (GH#2721) - Credential key in .gitignore —
.beads-credential-keyadded to project-root.gitignoretemplate as defense-in-depth for the AES-256 encryption key. (GH#2695) - SQL stored procedures for flatten/compact —
bd flattenandbd compactnow use SQL stored procedures in server mode, fixing failures on shared Dolt servers. --format jsoncollision — Resolved flag collision betweenrootCmdpersistent--formatflag andlist/dep-treelocal--jsonflags.- Concurrent schema init —
initSchemaOnDBserialized withGET_LOCKto prevent Dolt journal corruption in multi-agent environments. (GH#2672) - External Dolt server safety —
KillStaleServersrespectsIsAutoStartDisabledand server ownership, preventing accidental kills of externally-managed servers. (GH#2641) - Doctor infinite restart loop — Doctor no longer triggers infinite Dolt server restart cycles. (GH#2636)
- Schema version 8 — Dolt schema bumped to version 8 with proper commit of version update. (PR #2635)
- Repo-local servers — Auto-started Dolt servers kept alive across sequential
bdcommands within the same repo. - Store config preservation — Reopening stores by path no longer drops repo-specific config. (PR #2628)
- Validation on close —
--validatenow checks--acceptancefield;validation.on-closeconfig controls enforcement. (PR #2654) .beads/.envload order — Environment file loaded beforenoDbCommandsearly return, fixing env-dependent non-DB commands. (GH#2677)- Update description safety — Empty stdin/file no longer silently erases descriptions; requires explicit opt-in.
- Bootstrap JSONL imports — Correctly imports from git-tracked
.beads/issues.jsonl. - Doctor fail-closed — Server-mode integrity recovery now fails closed instead of silently passing.
Embedded Dolt
- 73 commits from the Dolt team (coffeegoddd) advancing embedded Dolt support: create, list, update, close, show, delete, search, query, label, gate, promote, move, merge-slot, quick, diff, count, find-duplicates, graph, and views/reports commands now work in embedded mode. Includes shared
issueopspackage extraction for transaction-based operations used by both server and embedded backends.
Community
Contributors: coffeegoddd (Dustin Brown), matt wilkie (maphew), harry-miller-trimble, gzur, Algorune, sfncore, angelamayxie, paf0186, Patrick Farrell, Tim Visher.
[0.61.0] - 2026-03-15
Added
--no-historyflag —bd create --no-historystores beads in the wisps table (skipping Dolt commits) without making them GC-eligible, fixing agent identity beads being incorrectly garbage collected.bd update --no-history/--historytoggles the flag. (GH#2619)--claim-nextflag —bd close --claim-nextauto-claims the next highest priority available issue after closing--skillsand--contextflags —bd create --skills/--contextadd structured sections to issue descriptions--exclude-typefor wisp GC —bd mol wisp gc --exclude-type agent,rigprotects specific types from garbage collection--typefilter for wisp list —bd mol wisp list --type bugfilters by issue type- Auto-detect beads database on git origin —
bd bootstrapprobes origin forrefs/dolt/dataand auto-clones the database;bd initwarns when existing data is detected (GH#2580) - Install checksum verification — install scripts verify SHA256 checksums before extraction (GH#1857)
- Jira
pull_jqlconfig —jira.pull_jqlconfig key orJIRA_PULL_JQLenv var for custom JQL filters during issue fetch - UUID primary keys — events, comments, and snapshot tables migrated from AUTO_INCREMENT to UUID() primary keys for federation-safe multi-clone operation
Changed
- Prime SSOT —
bd primeis now the single source of truth for agent instructions. Agent files use versioned hash-based markers with profile support (full/minimal) for staleness detection and automatic upgrades. Symlink safety and profile precedence (full preserved over minimal) (GH#2139) - Formula extends merges by ID — child steps with matching IDs override parent steps in-place instead of appending duplicates
- Circuit breaker keyed on host:port — prevents cross-host blocking when servers share a port
- Backup scoped by prefix — backup export and restore filter by current project prefix, preventing cross-project data leakage on shared servers
Fixed
- Embedded Dolt CI — clean stale noms LOCK files before opening embedded store (fixes TestEmbeddedInitConcurrent panic), update stale from_jsonl test, gofmt import.go
- Circuit breaker port-0 poisoning — returns nil breaker for unresolved port 0 during standalone auto-start
- KillStaleServers scoped to repo — only kills orphan Dolt processes belonging to the current repo's data directory
- Port resolution chain —
applyConfigDefaultsconsults port file > config.yaml > metadata.json instead of falling through to default 3307 - Doctor fingerprint checks —
bd doctor /path/to/repocomputes fingerprints from the target path, not cwd - Doctor auto-start on cold standalone — doctor checks now use CLI auto-start policy instead of suppressing on explicit ports
- Doctor server-backed runtime detection — layered detection for server-backed runtime on older metadata.json without
dolt_mode - Credential key location — moved from
.beads/dolt/to.beads/to avoid creating ghost directories in shared-server mode - Colons in query values — unquoted identifiers like
label=gt:merge-requestnow work without quoting - Init localhost warning — warns when server host defaults to localhost for remote Dolt setups
- Repo-local Dolt server preservation — stale cleanup preserves servers from other repos
- Backup restore UUID IDs — accepts UUID-format comment and event IDs during restore
[0.60.0] - 2026-03-12
Added
bd bootstrapwith recovery actions —bd bootstrapnow executes recovery actions directly instead of just printing advice, making first-run and repair workflows hands-free (GH#2438, GH#2372)bd contextcommand — new command for safe-first error guidance, surfacing relevant context when things go wrong (fix-merge PR #2496)bd help --listandbd help --doc— CLI doc generation flags for producing machine-readable command listings and full documentation (GH#2527)bd donealias —bd doneis now an alias forbd close, aligning with Gas Town's session lifecycle vocabularybd done <id> <message>— last argument is treated as the close reason, removing the need for--comment--design-fileflag — read design documents from files instead of stdin forbd createworkflows (PR #2524)--destroy-tokenfor safe re-init — enables non-interactivebd initre-initialization with explicit confirmation token (GH#2497)- GitHub Issues integration — tracker plugin for syncing GitHub Issues with beads (GH#2373)
- Global PRIME.md fallback —
~/.config/beads/PRIME.mdis used when no project-level PRIME.md exists (GH#2330) - Shared Dolt server mode — multi-repo and multi-agent setups can share a single Dolt server instance (GH#2416)
- Ephemeral port allocation for Dolt — replaces hash-derived ports with OS-assigned ephemeral ports, eliminating port collisions entirely (GH#2415)
- Workspace identity preflight —
bd bootstrapvalidates workspace identity before any operations (GH#2438) - Epic close guards — prevents accidental closure of epics with open children; includes merge re-parenting and progress display
bd searchsearchesexternal_ref— external references (GitHub issue URLs, Linear IDs, etc.) are now searchable (GH#2494)- JSON-aware error output — errors include structured JSON when
--jsonis active, with JSONL schema validation and contract tests (GH#2499) ai.api_keyconfig — fallback forANTHROPIC_API_KEYenvironment variable, stored inconfig.yaml- Embedded Dolt storage interfaces — new storage abstraction layer contributed by DoltHub (coffeegoddd) for future embedded Dolt work (PR #2427, PR #2428)
- Community tools — added beads-web and claude-protocol to COMMUNITY_TOOLS.md; added community forks listing (PR #2457)
Changed
- Dolt port allocation — switched from deterministic hash-derived ports to OS-assigned ephemeral ports; stored in repo-local state file rather than derived at runtime (GH#2415)
- Auto-push state moved to local file — prevents metadata merge conflicts during
bd dolt pullby keeping auto-push state out of the shared metadata (GH#2466) - YAML config prefix precedence — YAML config prefix now takes precedence over DB-stored prefix in shared-server mode (GH#2469)
- Charm library upgrades — migrated glamour to v2 (
charm.land/glamour/v2) and huh to v2 (charm.land/huh/v2) (GH#2471) - Daemon infrastructure fully removed — final cleanup of all remaining daemon references and idle monitor infrastructure (GH#2431, GH#2452)
- Dead sync mode scaffolding removed — removed remaining sync mode code that was left behind after the Dolt migration (GH#2485)
- 3-way merge engine remnants removed — cleaned up leftover code from the removed 3-way merge system (GH#2391)
- Nix flake — uses
go mod editinstead ofsedfor version patching (more reliable)
Fixed
- Dolt journal corruption —
KillStaleServersnow runs insideflockto prevent concurrent server kills from corrupting the Dolt journal (GH#2430) - Dolt config corruption — uses explicit
DOLT_ADDto prevent config corruption from stale working set state (GH#2455) - Dolt pull merge errors — auto-commits pending changes before pull to prevent merge errors (GH#2474)
- Dolt pull transaction safety — wraps
DOLT_PULLin explicit transaction for autocommit compatibility (GH#2501) - Dolt remote directory —
bd dolt remote add/list/removenow operate on the correct directory (GH#2306, GH#2311) - Dolt endpoint drift — warns when auto-started server endpoint doesn't match config (GH#2399)
- CLI remotes synced into SQL server — CLI-managed remotes are now synced into the SQL server on store open (GH#2315)
- Server mode
.beads/creation — correctly creates.beads/directory when using externalBEADS_DOLT_*env vars (GH#2519) - Metadata merge conflicts — auto-resolves metadata merge conflicts during
bd dolt pull(GH#2466) - Metadata replacement bug —
--metadatanow merges with existing metadata instead of replacing it (GH#2423) - Backup file detection — detects backup files on database-not-found and after
bd init(GH#2327) bd exportcrash — fixed crash on zero-time timestamps and stalebd syncrefs (GH#2488, GH#2493)bd children— now includes closed children by default (GH#2481)bd doctor --fix— regenerates missingmetadata.json(GH#2482); backfillsproject_idfor pre-GH#2372 Dolt stores (GH#2490); blocked at Gas Town town root to prevent accidental damage (GH#2450)bd doctor— detects stale.legacyhook sidecars (GH#2398);--clean --jsonnow works correctly (GH#2438)bd lint— accepts non-emptyacceptance_criteriafield without heading (GH#2468)bd list --json— no longer ignored when--treedefaults to true (three separate fixes consolidated)bd mol wisp— reports correct count whenRootOnly=truebd init— prevented from creating DB on another project's Dolt server (GH#2336); init guard allows fresh clones with committedmetadata.json(GH#2433);data-dirblocked in server mode (GH#2438)- Init guard error message — removed dangerous
--forcesuggestion - JSONL backups — preserve dependency metadata (GH#2487); restore denormalized JSONL without data loss (GH#2479)
- Reparented children — excluded from molecule auto-close (GH#2480)
- Worktree hooks — use absolute path for
core.hooksPathso hooks work in worktrees (GH#2414) - Worktree
.gitignore— skip append when parent directory pattern already covers the entry - Git hook shims — added timeout and graceful DB-missing handling
- Stale lock files — follow redirect target when cleaning stale lock files
- BEADS_DIR — stabilized paths from detached commit worktrees; prefer stable branch worktrees
BEADS_DOLT_PORTfallback — added fallback inGetDoltServerPort()(GH#2486)- PersistentPreRun flag checks — use
Root().PersistentFlags()for all persistent flag checks (GH#2514) - Stale pinned flag — auto-cleared on status transition
- Install script — detects WSL and MINGW/MSYS/CYGWIN environments (PR #2409)
- Test stability — Dolt test suite eliminates container crashes and cascading failures; timezone-aware date assertions; same-type issues for blocks dependency tests
Performance
- Close-time template subgraph loading — significantly faster epic close operations (GH#2458)
Documentation
- Stale sync references purged — comprehensive cleanup of
bd sync,bd import,--branchrefs across CLI help, setup generators, and docs (GH#2522, GH#2435, GH#2442) - Stale migration ref fixed —
bd migrate --to-doltreferences replaced withbd init --from-jsonl(GH#2333) - QUICKSTART.md — removed stale
--branchflag and SQLite references (GH#2522) - CI doc validation — added CI check to catch stale documentation references
- Community tools — added beads-web and claude-protocol
Dependencies
github.com/dolthub/driverupdated (multiple digests)golang.org/x/syncv0.20.0golang.org/x/sysv0.42.0golang.org/x/termv0.41.0- OpenTelemetry Go monorepo v1.42.0
- Testcontainers Go monorepo v0.41.0
- Charm glamour v1.0.0 → v2.0.0
- Charm huh v0.8 → v2.0.0
[0.59.0] - 2026-03-05
Added
bd list --treedefault — tree view is now the default display mode forbd list(GH#2345)- OpenCode recipe —
bd setupnow includes an OpenCode integration recipe - Fresh clone detection —
bd doctordetects fresh clones on Dolt server and guides through init (GH#2372) - Config-aware init guard —
bd initdistinguishes server-reachable from DB-exists, with better error messages (GH#2372) - Sync remote hint in errors — database-not-found errors now surface
sync.git-remoteconfig for easier troubleshooting - Nix flake modernization — updated flake for nixpkgs-25.11, fix-merge of PR #2314
- Doctor warning suppression — suppress specific
bd doctorwarnings via config (GH#1095) - Community Tools — added fancypantalons/nvim-beads to COMMUNITY_TOOLS.md
Changed
- 3-way merge config removed —
ConflictStrategy,FieldStrategy, and all associated config/validation removed; Dolt handles merge natively (GH#2353) - Daemon infrastructure removed — the bd daemon has been fully removed; bd is now purely CLI-driven (w-bd-001)
- Legacy daemon lock infrastructure removed — cleaned up stale lock files and related code
- Backup git-push defaults to OFF —
bd backupgit push now requires explicit opt-in (GH#2363) - Test infrastructure modernized — migrated all tests from
StartTestDoltServerto container-native API; readiness expanded to 5-state enum; crash detection via standalone functions (GH#2304) ExtractPrefixconsolidated — moved totypespackage for reuse across codebase
Fixed
- Hook marker handling —
bd doctor --fixrepairs broken/orphaned hook markers; version added to END marker for future matching (GH#2344) - Legacy hook migration — warn on user-modified legacy hooks; handle backup sidecar files during migration
- Dolt push/pull directory — use correct database subdirectory for CLI push/pull/fetch operations
- Contributor auto-routing — add fallback routing for show/update/close commands (GH#2345)
- Config-aware prefix detection —
ResolvePartialIDnow respects config for prefix routing - Doctor command order — correct
enrichFreshClonecommand sequencing - Batch IN-clause queries — prevent full table scans in all IN-clause queries (GH#2294)
- Init port resolution — use
DefaultConfigfor port resolution during init (GH#2372) - Idle monitor — single-instance lock, port config isolation, project UUID verification (GH#2367, GH#2372)
- Init data safety — prevent data destruction from misleading error messages (GH#2363, GH#2372)
- Circuit breaker tuning — reduce cooldown to 5s and add active TCP health probe
- Deterministic ordering — add ID tiebreaker to all ORDER BY clauses
- Backup on feature branches — skip git commits during hook runs and on feature branches
- Backup config routing — route
backup.*keys toconfig.yamlso overrides are respected - Embedded Dolt — handle context canceled in cleanup, add SQL concurrency test
- Tombstone entries — skip tombstone entries in
bd init --from-jsonl - DerivePort — restore as standalone default in
DefaultConfig; log fallback on collision - Cross-type blocking — align validation with cross-type blocking rules
- Cross-prefix dep routing — extend to dep commands (GH#2296)
- Dolt serialization retry — retry on serialization error in concurrent tests
- CLI routing — gate on local remote availability; extend SQL push timeout (GH#2295)
- Docker Hub network calls — skip when Dolt image not cached (GH#2277)
- Wisp batch deletes — commit per batch in
deleteWispBatchto avoid write timeout - Idle monitor watchdog — kills itself via
Stop()to prevent zombie processes
Documentation
- Audit and clean up stale sync mode documentation (w-bd-004)
- Network/privacy section added to SECURITY.md
- DerivePort birthday-problem collision recovery documented
- Misleading examples corrected in QUICKSTART.md
- GIT_INTEGRATION.md updated re deprecated beads-merge and Jujutsu
- Circuit breaker and upgrade recovery troubleshooting docs
- Duplicate nvim-beads entry fixed in COMMUNITY_TOOLS.md
[0.58.0] - 2026-03-02
Added
- Persistent agent memory —
bd remember,bd memories,bd recall,bd forgetfor knowledge that survives sessions and account rotations. Backed by the k/v store, auto-injected atbd primetime. bd purge— delete closed ephemeral beads (wisps) to reclaim storage (GH#1692)bd mol last-activity— show the most recent activity timestamp for any molecule (GH#1456)bd show --current— show the active issue without specifying an ID (GH#2184)bd doctor validate— Dolt-native conflict detection for data integrity checks (GH#2249)bd init --backend— explicit backend selection with SQLite deprecation notice--stdinflag — alias for--body-file -onbd createandbd updatebd preflight --check— aligned with CI checks for pre-push validation (GH#2230)- gofmt + golangci-lint pre-commit hook — automatic code quality enforcement (GH#2179)
- JSONL-to-Dolt migration script — standalone bash script for pre-0.50 users (GH#2276)
bd doctor --fix— bridge pending hook migrations into automated repairbd create-form --parent— create sub-issues with label inheritance
Fixed
- Dolt CPU spikes — batch IN-clause queries in
dependencies.goandcomputeBlockedIDsto prevent runaway CPU usage on large databases (GH#2294) - Dolt joinIter hangs — avoid hanging queries in
GetReadyWorkblocker computation - Stealth mode backup push —
no-git-opsconfig now correctly prevents backup git push (GH#2290) - Stale DB connection crash — retry stale connection and preserve temp file in
bd edit(GH#2267) - OSC escape leaks — prevent escape sequence pollution when third-party hook runners (lefthook, husky) call
bd hooks rundirectly (GH#1303) validateIssueIDPrefix— now checksallowed_prefixesconfig, unblocking convoy creation with multi-prefix databases (GH#1179)- Molecule steps in
bd ready— remove stale SQLite-era filtering that hid mol steps (GH#1359) bd blockedchildren — include children of blocked parents in output (GH#1495)- Same-type blocking validation — enforce that dependencies match allowed type pairs
- Cross-prefix dependency routing —
bd dep add/rm/blocks/treenow routes by prefix (GH#2285) - Cross-prefix dep existence check — skip target existence check for cross-prefix dependencies
- Wisps table recreation — recreate
dolt_ignore'd wisps tables on schema fast-path (GH#2271) - Missing wisps table — gracefully handle in epic/blocked queries (GH#2271)
- Wisp dependency scanning — scan
wisp_dependenciesingetChildrenOfIssuesandgetChildrenWithParents - Cascade-delete wisp children — delete blocked step children during wisp GC
- Batch wisp deletes — reduce Dolt commit pressure in
DeleteIssues - Dolt push/pull hint — show helpful message when remote not found (GH#2118)
- Git-protocol remote fallback — use CLI fallback for all git-protocol remotes, not just SSH (GH#2268)
dolt_data_dirpersistence — strip absolute paths frommetadata.jsonon save (GH#2251)- Dolt config port — consult
config.yamlfordolt.portinDefaultConfig(GH#2073) - Missing
dolt_database— detect and repair inmetadata.json(GH#2160) - Dolt remote guards — guard remote subcommands against store init bypass (GH#2224)
bd searchperformance — avoidLIKE %%full-table scans- Worktree DB discovery — skip own
.beads/in separate-DB discovery (GH#2190) - Contributor routing — detect fork workflow, apply routing to list and ready
- Pre-commit Go version mismatch — detect before golangci-lint panics
- Viper defaults — skip in
getRoutingConfigValueto unblock DB fallback bd mol wisp create— default to root-only unless formula setspour=true- Bare repo init — skip
AGENTS.mdgeneration in bare repositories last_import_timerefresh — prevent false staleness after write commands (GH#2255)- Hook marker detection — validate marker count and order; recognize marker-managed hooks (GH#2244, GH#2242)
- Gitignore template — add missing dolt runtime files (GH#2256)
- Pre-0.56 Dolt database upgrade — graceful recovery path (GH#2137)
- Remotesapi port check — skip when no federation peers configured (GH#2273)
- Doctor subsystem — fix panics, masked errors, missing
rows.Err(), federation port, hardcoded paths; add 3 new tests - N+1 query patterns — replace with batch queries in
deep.goandmigration_validation.go IsBlockedreporting — align blocker reporting with blocked-cache semantics (GH#1524)
Removed
- Beads Classic SQLite backend — the SQLite storage layer and all migration infrastructure have been removed. Dolt is the only backend. (GH#87493ce)
go-sqlite3dependency — no more CGO requirement; tests use Dolt testcontainers- Deprecated commands — removed dead SQLite-era code and legacy scripts
Documentation
- Updated stale references to JSONL and SQLite architecture
- Hook migration preview/apply workflow documentation
[0.57.0] - 2026-03-01
Added
bd doctor --agentmode — AI agent diagnostics for automated health checks (bd-6ud)- SSH push/pull fallback — dual-surface remote management (SQL + CLI) with automatic SSH detection (#2178)
- Hook migration system — census and migration planning for git hooks with doctor signal (#2217)
- Section markers for git hooks — hooks now use section markers for safer updates (GH#1380)
- Auto-close molecule root — molecule root automatically closes when all steps complete (#2200)
- CLI aliases —
--commentalias forbd close,--yes/-yalias forbd mol burn bd backupcommands —init,sync, andrestorefor Dolt-native backups- JSONL backup & auto-backup —
bd exportcommand for JSONL backup, auto-enable when git remote exists bd gc,bd compact,bd flatten— standalone beads lifecycle management- Circuit breaker — Dolt server connection circuit breaker to prevent agent hangs
- Config-driven metadata schema — enforcement via
metadata_schemaconfig (GH#1416) - Metadata flags —
--metadataforbd create,--set-metadata/--unset-metadataforbd update, metadata filtering inbd ready(GH#1406) - PreToolUse hook — blocks interactive cp/mv/rm prompts in agent workflows
- Auto-update stale hooks —
bd initdetects and updates outdated hooks (GH#1466) --root-onlyflag — forbd mol wisp createhksupport — hk.jdx.dev as supported git hook manager (#2182)bd dolt remote— add, list, remove subcommands for Dolt remote management- Auto-push to Dolt remote — automatic push with 5-minute debounce after Dolt commits
dolt-data-dirconfig — custom dolt data directory (#2143)--databaseflag forbd init— configure existing server database (#2102)- Per-worktree redirect —
.beads/redirectoverrides main repo.beads(#1995) has_metadata_key— new predicate inbd queryDSL (#1996)- MCP claim tool — atomic start-work for MCP integrations (#2071)
- Auto-clean noms LOCK — stale Dolt noms LOCK file cleanup on startup (#2059)
- Stale database detection — in
bd doctorandbd dolt clean-databases - Self-managing Dolt server — port collision fallback, idle monitor, crash watchdog for standalone users (GH#2049, GH#2050)
bd dolt start/stop— server lifecycle management commands- Counter mode —
issue_id_mode=counterfor sequential issue IDs (#2013) - Auto-migration shim — SQLite to Dolt migration via sqlite3 CLI
- Auto-migrate on first command — SQLite to Dolt auto-migration on first
bdcommand - Linear Project sync — sync Linear projects to beads (#2022)
- Label inheritance — child issues inherit parent labels on creation
- Infra type routing — route agent/rig/role/message beads to wisps table
IsInfraTypeconfig-driven — viatypes.infraconfig keybd init --stealth— setsno-git-ops: truein config (GH#2159)- Staleness check — read-only commands validate against JSONL freshness
- CLI feedback titles — command feedback now shows issue titles (GH#1384)
- OTel design docs — OpenTelemetry architecture and data model documentation (#2195)
- Jira V2 API — support for Jira V2 API (#2088)
Fixed
- Shadow database prevention —
bdno longer runsCREATE DATABASE IF NOT EXISTSunconditionally; errors with clear diagnostic instead of creating shadow databases - Auto-start suppressed with explicit server port — prevents shadow database creation when configured server is temporarily down
- Phantom catalog entries — respect existing
dolt_databaseconfig in init and migrate paths (#2051) information_schemaresilience — replace withSHOW COLUMNS/SHOW TABLESto avoid stale catalog crashesbd doctor --server— fix crash on phantom entries- Reparented child display — reparented child no longer appears under old parent (#2001)
- Homebrew publishing — use
brewsinstead ofhomebrew_casksfor formula publishing; auto-publish tap on release - NULL
created_bycrash — handle NULL in issue scan to preventbd duplicatescrash (#2198) - Dolt UNION crash — avoid
SELECT * UNIONthat crashes Dolt on column count mismatch SHOW DATABASES LIKE— replace with exact-match iteration for Dolt compatibility- Dolt port resolution — doctor checks and all commands use hash-derived port instead of hardcoded 3307 (#2148)
dolt_data_dirrespect — doctor checks use configured data directory (#2181)- Wisps table defaults — add default values to NOT NULL TEXT columns (bd-5nn)
- AUTO_INCREMENT reset — reset counters after
DOLT_PULL(#2135) bd init --stealth— correctly setsno-git-ops: truein config (GH#2159)- Skip autopush on read-only — prevent writes on read-only commands (GH#2191)
- Sandbox guard — restore sandbox guard in
maybeAutoPush(#2192) - Mol notes field — propagate notes field from formula steps to issues (#2155)
- Graph children layer — lift children to parent's layer in graph layout (GH#1748)
- DefaultInfraTypes mutation — unexport to prevent inconsistency (#2193)
- Conditional-blocks readiness — evaluate conditional-blocks deps in
computeBlockedIDs()(#2128) - Dolt connection timeouts — prevent agent hangs with connection timeouts
- Migration safety — verify DB target, deduplicate, spot-check data during migration (#2156)
- Ephemeral read-path fallback — fall through to issues table when wisps table missing (#2161)
- Ephemeral explicit-ID lookup — complete routing across all storage layers (GH#2053)
waits-fordeps inbd blocked— include in output (GH#2043)- Reopen/undefer no-op status — report correct status (GH#2037)
- Post-create metadata — commit deps and labels to Dolt after create (GH#2009)
- Status validation — validate against built-in + custom statuses on update (#2021)
- Empty title/label rejection — reject on update/label add (GH#1994)
- Non-zero exit on failure — exit non-zero when all close/update attempts fail (GH#2014)
- JSON metadata validation — validate on creation path (#2032)
- Wisp field validation — parity with issues in
createWisp(#2032) - Empty comment rejection — reject whitespace-only comment text
bd stalevalidation — reject non-positive--daysflagbd deferpast date warning — warn when--untildate is in the past- Doctor non-git-repo — gracefully handle in fingerprint and role checks
- Doctor cruft cleaning — clean cruft in redirect-expected dirs without redirect file (#2194)
- Doctor gitignore — follow redirect when fixing outdated
.beads/.gitignore(#2078) - Doctor maintenance — migrate maintenance checks to Dolt (#2146)
- Dolt server management — Gas Town guardrails, one server per town, kill-before-start (#2089)
- Migration 007 resilience — handle schema evolution differences (#2168)
- Windows compatibility — Makefile ldflags fix, connectex syscall handling, doltserver filesystem heuristic (#2165, #2171, #2092)
- Batch SQL queries — prevent query explosion with IN-clause batching (#2108)
- Routing write divergence — check local store before prefix routing (#2106)
- Hook outdated detection — unify between
CheckGitHooksandhooksNeedUpdate(#2105) - Linear status sync — include
stateIdin push updates (#2144) - Dep type overwrites — prevent silent dependency type overwrites on dep add
- Prefix sanitization — sanitize hyphens to underscores for SQL database names (GH#2142)
- Issue prefix normalization — prevent double-hyphen bead IDs
- SQLite
#in URI paths — escape to prevent truncation (#2150) bd deptraversal — traverse blocks-type edges in dep tree and graph commands (#2151)bd dolt push/pull/commit— allow to initialize store (GH#2042)bd init --from-jsonl— restore for server mode- Doctor stale verification — improved verification after --fix (#2077)
- Upsert on insert — prevent duplicate primary key errors (GH#2061)
- Database version auto-migrate — auto-migrate on CLI upgrade for all commands
- Wisp double-prefixing — stop wisp ID double-prefixing and add wisp fallback to
ResolvePartialID - Dolt
DOLT_COMMITtransaction — commit SQL tx beforeDOLT_COMMITto persist wisp data - OSC escape leaks — prevent in git hooks (GH#1303)
bd ready --json— include labels, deps, and parent in output- Git upstream warning — suppress for repos with no remotes (#2116)
bdinit prefix sanitization — sanitize auto-detected prefix for MySQL database names- Rejected flag-like args — reject flag-like positional args in
bd create - Backup streaming — stream backup exports to disk, reduce allocations
- Version scripts — update for section markers, suppress unused param lint
Performance
- Test parallelization — Dolt storage tests 3.5x faster, protocol tests 3x faster
- Branch-per-test isolation — shared DB with branch-per-test for doctor (44s → ~12s), cmd/bd, and protocol tests
- Testcontainers migration — test Dolt server uses testcontainers instead of binary spawning
- Consolidated test suites — messaging and dep test suites merged for efficiency
- Add phantom catalog detection to
bd doctor - Fix
bd doctor --servercrash on phantom entries (replaceINFORMATION_SCHEMA.SCHEMATAwithSHOW DATABASES)
[0.56.1] - 2026-02-23
Fixed
- Release CI — remove
verify-cgo.shpost-hook from darwin and freebsd builds which intentionally useCGO_ENABLED=0(cross-compilation without CGO)
[0.56.0] - 2026-02-23
Removed
- Embedded Dolt mode — beads now requires a running Dolt SQL server. The embedded Dolt driver (
dolthub/driver) and all CGO build-tag bifurcation have been removed. Binary size drops from 168MB to ~41MB. Usebd dolt startordolt sql-serverto run the server. - SQLite ephemeral store — ephemeral issues (wisps) now live in Dolt-backed
wispstable withdolt_ignore, replacing the separate SQLite database. Runbd migrate wispsto migrate existing data. - JSONL sync pipeline — the entire JSONL-based sync system (
bd sync, git-portable mode, belt-and-suspenders mode) has been removed. Dolt-native push/pull via git remotes is the only sync mechanism.bd syncis now a deprecated no-op. - JSONL bootstrap — clone initialization uses Dolt clone only; JSONL bootstrap path removed.
- JSONL plumbing — cross-rig JSONL flush, JSONL recovery in doctor, and JSONL-based restore have been removed.
Added
- Metadata query support —
bd list,bd search, andbd querynow support--metadata-field key=valueandhas_metadata_keyfilters (#1908) - Metadata visibility —
bd showandbd list --longdisplay metadata in human-readable format (#1905) - Wisps table — ephemeral issues stored in dedicated Dolt-backed table with
dolt_ignorefor compaction-friendly lifecycle bd migrate wisps— migration command for SQLite-to-Dolt ephemeral data- Batch auto-commit mode — reduces Dolt commit bloat by batching writes with SIGTERM/SIGHUP flush
--agents-templateflag —bd initnow supports named AGENTS.md templates viaembed.FS- Mux setup recipe —
bd setup muxwith layered AGENTS.md and managed hooks - Standalone formula execution —
bd mol wispsupports expansion formulas (#1903) - Sentinel errors —
ErrNotFound,ErrNotInitialized,ErrPrefixMismatchfor cleaner error handling --skip-prefix-validation—bd importflag for legacy data migration- Protocol invariant test suite — data integrity and blocking semantics regression tests (#1910)
- OpenTelemetry instrumentation — opt-in OTLP tracing for hooks and storage operations (#1940)
- Transaction infrastructure —
RunInTransactionwith commit messages, isolation, retry, and batch wrapping for Dolt concurrency
Fixed
bd readyordering — respect SortPolicy and preserve result ordering (#1883)waits-forreadiness —bd readyand molecule analysis now correctly handlewaits-fordependencies (#1900)- Dependency tree parent ID — populate ParentID in tree output and show [BLOCKED] for root (#1992)
- Parent-child display —
bd listnow separates parent-child deps from blocking deps (#1948) - Hook shim templates — use
bd hooks runinstead of nonexistentbd hookcommand - Cross-expansion dependencies —
bd mol cookpropagates deps across formula expansions (#1901) - Wisp auto-close — wisp root automatically closes after squash (#1898)
- Dolt server writes — commit via
execContextwhen server runs with--no-auto-commit - Metadata normalization — normalize metadata and waiters in
UpdateIssue - Batch import — persist labels, comments, and deps during import
- Noms LOCK detection — use
flockprobe instead of file existence (#1960) - Doctor backend awareness — deep validation checks configured backend, not directory presence
- Doctor federation — use configured database name in federation and health checks (#1904, #1924, #1925)
- Doctor orphan deps — exclude
external:deps from orphan check (#1593) - Jira sync — use correct API v3
/search/jqlendpoint (#1953) - Plugin dep order — correct inverted
bd dep addargument order in plugin docs (#1928) - Wisp routing — fix multiple ephemeral store routing gaps for create, read, promote, and gc
- Prime output — remove stale
--from-mainflag reference bd listresolved blockers — treat missing/unreachable blockers as resolved (#1884)- Wisp search parity — add ~15 missing filter fields to
searchWisps - Wisp label hydration — hydrate labels in
getWispsByIDsfor search results - Query nil guard — prevent panic in
GetBlockedIssuesandGetEpicsEligibleForClosure - Issue prefix clobber — guard
SetConfigto prevent overwrite when rigs share a Dolt database - Atomic bond/squash —
bd mol bond,bd mol squash, andbd mol cooknow run in single transactions (bd-wvplu, bd-4kgbq) bd readyparent filter — pass--parentfilter toGetReadyWork/GetBlockedIssuesand propagate blocked status to children (#2009, #1495)bd listsort/limit —--limitnow applies after--sort; trim whitespace inbd edit(#1237, #1234)- Doctor lock false positive — use
flockprobe for noms LOCK, remove stalebd syncreferences (#1981, #2007) - Repo sync consistency — cross-prefix hydration and close guard consistency (#1945, #1524)
- DOLT_COMMIT in CRUD — all write operations now produce Dolt commits for history tracking
- Double JSON encoding — fix daemon-mode RPC response unmarshaling across show, dep, label, reopen (bd-4ec8)
- G304 gosec finding — annotate
os.ReadFilein tips.go with#nosecfor constructed paths (bd-8g8) - Stale daemon references — remove obsolete
bd daemonreferences from all documentation (#1982)
Performance
- Binary size — 168MB → ~41MB (dropped
dolthub/driverand wazero WASM runtime) - Linux/Windows startup — eliminated 2-second wazero JIT compilation penalty on every invocation
- Test suite — doctor tests 89s → 28s; shared DB pattern across cmd/bd suites
- Test isolation — dolt package and cmd/bd tests now isolated from production Dolt server (bd-2lf6)
- N+1 queries — batch dependency/label/comment queries with per-invocation caching (#1874)
[0.55.4] - 2026-02-20
Fixed
- Release CI: FreeBSD build — disable CGO for FreeBSD target; zig sysroot lacks stdlib.h
[0.55.3] - 2026-02-20
Fixed
- Release CI: macOS builds — disable CGO for darwin targets; zig sysroot lacks macOS frameworks (CoreFoundation, Security) and libresolv; pure-Go build via
gms_pure_go+netgotags
[0.55.2] - 2026-02-20
Fixed
- Release CI: libresolv — strip
-lresolventirely from zig wrappers instead of replacing with-lresolv.9(zig sysroot has neither); macOS builds usenetgotag so libresolv is not needed - Release formula — added rate limit warnings to prevent burning GitHub API quota during CI wait
[0.55.1] - 2026-02-20
Fixed
- Release workflow YAML — heredoc in zig wrapper step broke YAML literal block parsing; replaced with echo commands
- Version consistency — marketplace.json was not bumped in v0.55.0
- Go formatting — ran gofmt on 8 files
- Lint — fixed unused parameter and dead code in config.go
[0.55.0] - 2026-02-20
Fixed
- Release CI: zig upgrade — upgrade zig 0.13.0 → 0.14.0 to fix
AccessDeniedbug in cross-compilation (ziglang/zig#20689) - Release CI: macOS libresolv — work around zig 0.14.0
libresolvresolution by using versioned-lresolv.9(ziglang/zig#16674) - Release CI: Android ARM64 — disable CGO for Android target (server mode only)
- 5 pre-existing test failures — resolve test failures and Dolt panic (bd-iqsw6v)
- Doctor daemon references — remove daemon references for post-daemon architecture
Removed
- ~5K lines dead code — classic cleanup of obsolete sync pipeline remnants
[0.54.0] - 2026-02-18
Fixed
- Release CI — fix zig cross-compilation cache race by serializing goreleaser builds (
--parallelism 1) - Android ARM64 build — disable CGO for Android target (server mode only)
.zig-cache/in.gitignore— prevent goreleaser dirty-git false positive
[0.53.0] - 2026-02-18
Added
- Dolt-in-Git sync — native Dolt push/pull via git remotes replaces the entire JSONL sync pipeline;
BootstrapFromGitRemote(),HasRemote(),sync.git-remoteconfig key bd dolt start/bd dolt stop— explicit Dolt server management commands (#1813)bd dolt commit— desire-path ergonomics for committing Dolt data (#1812)- Server mode without CGO —
OpenFromConfig()exported for server-mode aware store opening (#1805) - Hosted Dolt support — TLS, authentication, and explicit branch configuration
bd mol wisp gc --closed— bulk purge of closed wisps--no-parentflag forbd list— filter out child issuesbd readypretty format — improved default output with priority sort, truncation footer, and parent epic context- Dolt compaction methods —
bd compactsupport for Dolt databases - Storage interface —
Storageinterface decouples from concreteDoltStore(bd-l3o) - Lock health diagnostics —
bd doctordetects and reports dolt-access.lock and noms LOCK issues - Codecov integration — component-based coverage tracking in CI
Fixed
- Pre-commit deadlock on embedded Dolt — resolve hook deadlock (#1841, #1843)
bd doctor --fixhang — run fixes in-process instead of spawning subprocess (#1850)- Dolt lock errors — surface lock errors with actionable guidance instead of silent empty results (#1816)
BEADS_DIRconfig loading — respectBEADS_DIRwhen loading config.yaml (#1854)- Dolt
Unknown databaseretry — retry onUnknown databaseafterCREATE DATABASE(#1851, #1852) - Windows
Expand-Archive— qualify to avoid Pscx module conflict (#1826) bd initgit repo check — ensures git repo exists and runs clean diagnosticsSaveConfigValue— preserves existing file contents (#1816)moleculecore type — treat molecule as core issue type (#1866)- Formula
VarDef— distinguish "no default" fromdefault=""(#1837) - Worktree test isolation — harden metadata.json isolation (bd-la2cl)
- Goroutine leak — replace
time.SleepwithwaitForin tests (#1822)
Removed
- JSONL sync-branch pipeline — deleted
internal/syncbranch/(5,720 lines),snapshot_manager,deletion_tracking, doctor sync-branch checks/fixes, and all associated tests (~11,000 lines total) - Daemon infrastructure — removed lockfile activity signal and orchestrator (bd-9u8zd)
- 3-way merge engine remnants — removed remaining merge code (bd-aswyy)
- Dead stubs —
CheckBackendMigration,NeedsJSONL, and other no-ops (bd-23nlq) - Dead SQLite-only
bd repaircommand
Documentation
- BeadHub — added to COMMUNITY_TOOLS.md
- beads-compound plugin — added to Claude Code Orchestration section (#1814)
- Stale reference cleanup — removed daemon/SQLite/JSONL/tombstone references from docs and comments
[0.52.0] - 2026-02-16
Added
bd ready --include-ephemeral— new flag to include ephemeral issues in ready work results
Fixed
- Doctor redirect target resolution — fix path resolution for redirect targets (#1803)
- Dolt directory creation guard — skip dolt directory creation when not in server mode (#1800)
- Tilde expansion in core.hooksPath on Windows — properly expand
~in git hook paths (#1798) - Worktree redirect path resolution — resolve redirect paths from worktree root, not
.beads/dir (#1791) - Block rename-prefix in worktrees — prevent rename-prefix from running in git worktrees to avoid JSONL staleness (#1792)
- CI lint warnings — resolve gosec G204 and unparam lint warnings (#1790)
Removed
- Dead git-portable sync functions — remove unused
gitCommitBeadsDirandgitPush(#1793)
[0.51.0] - 2026-02-16
Changed
- Dolt-native cleanup (dolt-1s40) — massive 8-phase refactoring to remove all legacy SQLite/JSONL/daemon infrastructure:
- Phase 2: Remove daemon compat stub and
--no-daemonflag - Phase 3: Remove 3-way merge engine
- Phase 4: Remove tombstone/soft-delete system
- Phase 5: Remove JSONL sync layer
- Phase 6: Remove SQLite backend entirely
- Phase 7: Remove storage factory, memory backend, and provider abstraction; replace with direct Dolt calls
- Phase 8: CLI & config cleanup — remove remaining SQLite/daemon remnants
- Phase 2: Remove daemon compat stub and
- Post-cleanup pruning — removed 12 dead/duplicate DoltStore methods (650 lines), 5 legacy doctor checks (1,457 lines), internal/beads type aliases, stale no-op stubs and dead functions
bd syncis now a no-op — sync layer removed as Dolt handles persistence directly- Dolt-native API renamed — legacy storage API consolidated to direct DoltStore calls
- Server watchdog — added Dolt server health monitoring
Fixed
- Dolt config test corruption — tests calling
setDoltConfig()usedFindBeadsDir()which in worktree environments returned the rig's.beads/instead of the test's temp dir; fixed witht.Setenv("BEADS_DIR", beadsDir)(#1780) - Dolt embedded mode database name — read from
metadata.jsoninstead of hardcoding (#bd-pqn2e) - Batch
DeleteIssueshang — queries batched to prevent hang on large ID sets, with correctness hardening and comprehensive tests (#1770) bd mol currentstep readiness — useanalyzeMoleculeParallelfor accurate step readiness (#1786, #1276)bd doctorAccessLock — migrate Dolt health checks to shared AccessLock connection with error-path tests andCloseWithTimeoutdocumentation (#1780)bd doctor --yes— honor--yesflag for repo fingerprint auto-fix (#1782)bd doctorsqliteConnString pragmas — restore pragmas dropped by Phase 8 cleanupGetReadyWorktype filtering — exclude workflow/identity types from ready work results (#1774)bd createdependency direction — swap dependency direction for explicitblocks:prefix (#1742)bd dolt seedcustom types — seedtypes.customin default config (#1733)messagebuilt-in type — addmessageas recognized built-in issue type (#1742)- Routing redirect resolution — lock relative redirect resolution for routed lookups (#1751)
- Schema init skip — skip schema initialization when already at current version (#1765)
- Test race conditions — serialize
dolt.New()and stdio redirection to eliminate test races deleteBatchsignature mismatch — fix signature and unused types import- gofmt — formatting fixes across 24+ files
- Bounded lock contention — enforce bounded lock retry behavior in syncbranch read/write tests (#1777)
- Malformed test names — fix test names and remove obsolete SQLite-backend doctor tests
Performance
- CASCADE deletes — leverage SQL CASCADE to cut deletion queries by 60%
- Schema init — skip when already at current version, reducing startup overhead
Documentation
- SQLite → Dolt migration — updated 10+ documentation files replacing stale SQLite references with Dolt (ARCHITECTURE.md, FAQ, TROUBLESHOOTING, WORKTREES, INTERNALS, and more)
- Deleted deprecated docs — removed
EXTENDING.mdandMULTI_REPO_HYDRATION.md(SQLite-era, no longer applicable) - INSTALLING.md — revised for mise installation methods (#1756)
- CLAUDE.md — fix stale file references and SQLite mentions
- Contributor docs — updated stale SQLite references to Dolt
- Dolt migrate command — fix typo (#1779)
[0.50.3] - 2026-02-15
Added
- SyncEngine hook system —
PullHooks(GenerateID, TransformIssue, ShouldImport) andPushHooks(FormatDescription, ContentEqual, ShouldPush, BuildStateCache/ResolveState) allow tracker-specific behaviors without modifying the engine - Jira native integration — extracted into
internal/jira/package with REST API v3 client, ADF document conversion, field mapping, and full test coverage - Tracker plugin registry —
tracker.Register()+init()pattern for auto-discovery of tracker implementations (Linear, GitLab, Jira)
Changed
- SyncEngine refactor — all three tracker CLIs (Linear, GitLab, Jira) now use the shared
tracker.Enginefor Pull→Detect→Resolve→Push orchestration, eliminating ~800 lines of duplicated sync code - Tracker adapters inlined — moved from
internal/tracker/adapters/{linear,gitlab}intointernal/{linear,gitlab}as self-contained packages withtracker.goandfieldmapper.go
Fixed
- Jira State mapping bug — removed stale
*StatusFieldpointer assignment injiraToTrackerIssuethat could cause incorrect status mapping when Priority was set but Status was nil - CI: Windows build — renamed
test_wait_helper.goto_test.gosuffix so non-test builds don't try to resolve test-only symbols - CI: gofmt — fixed formatting across 14 files
- Formula variable validation — use
Requiredfield for formula variable validation bd slotrouting — added routing and label-based agent check to slot commands
Performance
- Test suite — replaced ~60
git initsubprocess calls with cached template copy, reducing test setup overhead
[0.50.2] - 2026-02-14
Added
- SQLite-to-Dolt migration nudge — rate-limited hint (once per 24h) on any
bdcommand for SQLite users, plusbd doctorbackend migration check (#1706) - Dolt audit log for
bd dolt config setchanges
Fixed
bd doctorperformance — replaced O(n) full-table scans with SQL aggregation queries, reducing doctor runtime from 130s to 6s on large databases (#1706)- Dolt metadata writes — reliable
bd_version,repo_id,clone_idpersistence with init-time verification, doctor fix, and migrate extension (#1741) FindBeadsDirworktree boundary — stopped directory walk from escaping sibling worktree boundaries (#1731)bd doctorplugin install command — corrected command shown in doctor output (#1732)- Backend descriptions — updated
bd backend listand help text to show Dolt as the default (not SQLite) since v0.50
[0.50.1] - 2026-02-14
Fixed
- CI: goreleaser failure — removed dead
internal/rpcimport from test stubs that brokego mod tidy - CI: Windows smoke test — use
--backend sqliteand temp dir to avoid Dolt dependency and repo.beads/conflicts - CI: lint errors — updated golangci-lint v2 exclusions for fmt.Fprintf errcheck, gosec G104/G304
- CI: gofmt — fixed formatting in init_test.go, main.go, sync_git_remote_test.go
Added
- Plugin-based issue tracker framework with Linear and GitLab adapters (#1150)
[0.50.0] - 2026-02-14
Added
- Dolt is now the default backend for new
bd initprojects. Existing SQLite projects are unaffected.BEADS_DBenv var auto-detects SQLite. bd graphvisualization overhaul — terminal-native horizontal DAG as default view, plus DOT and interactive HTML export formats. Old box view available via--box(bd-9de)bd sqlcommand for raw SQL access to the underlying database. Supports table, JSON, and CSV outputbd help --allto dump complete command reference (#1699)decisionbuilt-in issue type with aliases and help strings- Cross-database dependency resolution via prefix routes in
bd show,bd graph, andbd blocked— external deps display actual title, status, and priority (bd-k0pfm) bd show --watchflag for auto-refreshing display on file changes with fsnotify debouncebd vc commit --stdinfor reading multi-line commit messages from stdinBD_BRANCHenv var for branch-per-polecat write isolation in DoltBD_NAMEenv var for multi-instance help text identitybd doctorartifact cleanup —--check=artifactsdetects stale JSONL, WAL/SHM, backup files. Works with--cleanand--fixbd doctorClaude Code integration checks — detect malformedsettings.json, verify hook completeness, detect legacy MCP tool referencesbd doctoroutput grouped by category with per-category pass counts- Dolt corruption recovery via
bd doctor --fix— backs up corrupted.dolt-data/, reinitializes fresh Dolt database, auto-imports from JSONL backup - Frictionless
bd init— better test-issue detection, non-interactive stdin detection, version tracking at init time, cancellable prompts, actionable error hints viaFatalErrorWithHint - Mise installation documented in INSTALLING.md
Changed
- Default backend is Dolt —
bd initwithout--backendnow creates Dolt databases. Existing projects with no explicit backend in metadata.json continue to use SQLite (backward compatible) - Removed daemon/RPC subsystem — internal daemon, RPC layer, and
internal/rpc/package deleted (~19,663 lines). All commands use direct embedded database access - Removed JSONL sync layer —
internal/importer/,markDirtyAndScheduleFlush(), anddaemonClient != nilbranches eliminated (~7,634 lines) - Stripped dirty tracking from Storage interface —
MarkIssueDirtysubsystem no longer part of the storage contract bd graphdefault view changed from vertical box layout to horizontal DAG- Schema version downgrade protection — CLI refuses to run against a database written by a newer version
- Upgrade notification only triggers for actual version upgrades (no longer fires on downgrades/branch switches)
resolve-conflictsdefaults to canonicalissues.jsonl- Batch
GetLabelsForIssuesreplaces N+1GetLabelscalls in list operations - Consolidated redirect resolution into single
FollowRedirectfunction - Backend-agnostic refactoring — compact, migrate, dep, sync, findReplies, and wisp/mol commands use Storage interface instead of SQLite type assertions
Fixed
bd closeenforces gate satisfaction before closing machine-checkable gates (gh:pr,gh:run,timer,bead).--forcebypassesbd showexits non-zero when issue not found (previously exited 0 with empty JSON output)bd listclosed-blocker filtering — closed issues no longer shown as blockers in annotationsbd list --parentincludes dotted-ID children — matches both explicit parent links andX.*naming conventionbd readydeferred-parent propagation — excludes children of deferred parents from ready work- Dolt
joinIterpanic prevented by replacingIN/EXISTSsubqueries with Go-level filtering - Embedded Dolt self-deadlock in git hooks and
bd migrate— added tonoDbCommands - Dolt rename FK violation — disable FK checks during rename operations
- Dolt
GetIssuesByLabeldeadlock — fixed connection pool exhaustion withMaxOpenConns=1 - XSS vulnerabilities in graph HTML export (bd-67uzz)
- Redirect path resolution — resolve from parent of
.beadsdir, not.beadsitself bd migrate --to-doltsetssync.mode=dolt-nativeand uses config-based backendbd doctorbackend-agnostic checks — uses storage factory instead of raw SQLite; routes.jsonl false positive fix;dolt_mode serverrespectedbd showextra newline before first issue header removed--typeflag help text shows only base typesbd primeprompt optimized to avoid spurious "creating issue without description" warning- Linuxbrew ICU paths supported in Makefile
- Windows build recipe fixed (BINARY conditional moved inside targets)
go installfixed by removing localreplacedirective- Nix flake build and
goseclint errors resolved - Duplicate Cobra command registration replaced with
Aliases - Homebrew upgrade command corrected in upgrading docs
Documentation
- Added Dolt GitHub link to README
- Added beadsmap and Beadbox to community tools
- Corrected Homebrew upgrade command
- Added Mise installation instructions to INSTALLING.md
[0.49.6] - 2026-02-08
Reverted
- Embedded Dolt mode restored - The v0.49.5 removal was premature; embedded mode is still needed in Beads (only Gas Town should be server-only). Restores dolthub/driver, advisory flock, embedded connector lifecycle, CGO build tags, and vendored go-icu-regex
[0.49.5] - 2026-02-08
Added
bd searchcontent and null-check filters - Filter issues by description content and metadata presence (--has,--no) (bd-au0.5)bd promotecommand - Promote wisps to persistent beads (gt-7mqd.9)bd todocommand - Lightweight task management for quick personal trackingbd find-duplicatescommand - AI-powered duplicate issue detection (bd-581b80b3)bd validatecommand - Data-integrity health checks, integrated intobd doctor --check=validate(bd-e108)- Dolt fail-fast TCP check - Quick connectivity check before MySQL protocol initialization
- Windows PE version info - Embedded version metadata reduces antivirus false positives (bd-t4u1)
- Centralized AI model config -
ai.modelconfig key withDefaultAIModel()helper - Newsletter generator - Automated narrative release summaries (#1197)
Changed
- Embedded Dolt mode removed - Server-only Dolt connections now; embedded driver fully removed (bd-esqfe). Windows Dolt backend connects via MySQL protocol. Note: reverted post-release — see [Unreleased]
bd initdefaults to chaining hooks - No longer prompts; chains by default (bd-bxha)- Homebrew formula name -
bd doctornow correctly suggestsbrew upgrade beadsinstead ofbrew upgrade bd - Doctor output - Summary-first layout with improved formatting (bd-4qfb)
- JSON output standardized - Consistent JSON format across all commands (bd-au0.7)
- Go toolchain - Downgraded from 1.25.7 to 1.25.5 for Nix compatibility. Note: back to 1.25.7 after embedded Dolt restore — see [Unreleased]
Fixed
- Security: SQL injection prevention - SQL identifier validation for dynamic table and database names (dolt-test-46a)
- Security: path traversal - Fixed path traversal in export handler and command injection in import
- Security: CVE-2025-68121 - Go toolchain upgrade for TLS runtime fix
- RPC: empty mutation events - Pass issueID via closure to prevent zero-value IDs in label/dep operations (dolt-test-rgh)
- RPC: server shutdown - Drain in-flight requests before closing storage; proper response-write-then-shutdown pattern
- RPC: nil storage guards - Added to handleCommentList, handleCommentAdd, and health handler
- RPC: daemon socket path - Use ShortSocketPath for status/health/metrics commands
- Daemon: YAML config parsing - Recognize both hyphenated and underscored daemon config keys (e.g.,
auto-syncandauto_sync) - Daemon: stderr redirect - Removed unsafe global os.Stderr replacement during import
- Daemon: daemon stop suggestion -
bd doctorfix suggestions now include workspace path argument - Doctor: role check - Falls back to database config for users who set role via
bd config set - Doctor: gastown detection - Auto-detect gastown mode when routes.jsonl exists
- Doctor: routing mode - Accept
explicitas valid routing mode alongside auto/maintainer/contributor - Doctor: Dolt conflicts query - Use correct
tablecolumn name (nottable_name) - Sync: conflict resolution - Apply --ours/--theirs strategy correctly
- Sync: tombstone export - Include tombstones in auto-flush full export
- Merge: panic prevention - Use strings.HasPrefix to prevent panic on short error messages
- Import: label sync - Remove DB labels absent from JSONL during import
- Import: issueEqual comparison - Include dependencies and comments in comparison
- Export: dirty flag preservation - Prevent stdout export from clearing dirty flags and auto-flush state
- Export: temp file collisions - Use unique temp filenames in writeMergedStateToJSONL
- Migration: bounds checks - Add bounds checks for slice/string access in migrate.go
- Migration: daemon check - Check for running daemon before dolt migration
- Migration: error logging - Log warnings for label and dependency import errors
- Migration: legacy spec_id - Fix doctor --fix migration for legacy spec_id
- SQLite: WAL retry deadlock - Make Close() idempotent to prevent deadlock (bd-4ri)
- SQLite: BUSY retry - Use SQLITE_BUSY retry logic for all BEGIN IMMEDIATE calls (bd-ola6)
- SQLite: JSONL locking - Add exclusive lock to flushToJSONLWithState to prevent race conditions
- Dolt: connection retry - Make "connection refused" retryable in retry logic
- Dolt: cross-rig contamination - Use prefix-based database names; detect contamination in post-migration check
- Dolt: port consistency - Use port 3307 consistently for server connections
- Config: beads.role - Write to git config instead of SQLite
- Config: viper guard - Log when viper uninitialized in getConfigList
- Config: BD_BACKEND blocked - Block env var to prevent data fragmentation (bd-hevyw)
bd listoutput - Separate parent-child from blocks display;--alldisables default limitbd dep listrouting - Fix cross-rig routing from town root (bd-ciouf)- Cross-prefix ID resolution - Support multi-repo scenarios (GH#1513)
- Staleness checks - Added to export, graph, history, gate list commands
- Gitignore template - Add
.jsonl.lockto template and requiredPatterns - MCP plugin - Remove output_schema workaround for FastMCP 2.14.4
- Nix/Windows CI - Unbroken: removed orphaned pure_go_windows.go, updated flake.lock, fixed vendorHash
Documentation
- Messaging system documentation (messaging.md)
- Issue metadata field and reserved key prefixes
- Docker trick for updating flake.lock without nix
- Community Tools: JetBrains beads-manager plugin, Beadspace desktop app
- Fix ready docs and external-ref documentation (#1523, #1339)
[0.49.4] - 2026-02-05
Added
- Label pattern and regex filtering - New
--label-pattern(glob) and--label-regexflags forbd listandbd ready. Filter issues by label patterns liketech-*or regex liketech-(debt|legacy)(#1491) - Simple query language - Complex filtering via a simple query syntax for
bd list beadscommand alias - Installer now creates abeadsalias alongsidebd- spec_id field - New field for linking issues to specification documents (#1372)
- Wisp type field -
wisp_typecolumn for TTL-based compaction of ephemeral molecules - Dolt schema migration runner - Automated schema migrations for Dolt backend
- Dolt migration validation in bd doctor - Checks for Dolt migration health
- Agent-managed Dolt upgrade path -
bd migratesupport for Dolt upgrades --metadataflag for bd update - Update issue metadata from CLI via JSON (#1417, bd-0vud2)- UpdateIssue metadata via json.RawMessage - Programmatic metadata updates (#1417)
- BD_SKIP_ACCESS_LOCK env var - For Dolt lock testing scenarios
- Orphan branch support for sync-branch migration - Cleaner sync branch setup
- config.local.yaml support - Local configuration overrides via
.beads/config.local.yaml - Makefile up-to-date check -
make installnow verifies repo is current before building
Changed
bd readynow shows only open issues - Excludes in_progress, matchingbd list --readybehavior. Shows work that is truly available to claim- release.sh is now a molecule gateway - Creates a release wisp instead of running a batch script
- Merge driver embeds types.Issue - Prevents field drift between merge driver and core types (#1481)
Fixed
- JSONL file locking - Prevents race conditions in concurrent writes and incremental exports
- WAL checkpoint robustness - Retry logic for SQLite WAL checkpointing
- Merge driver field drift - Driver now preserves all issue fields including spec_id, metadata, and dependencies (#1480, #1481, #1482)
- Atomic bd claim - Compare-and-swap semantics prevent race conditions (#1474)
- BEADS_DIR routing - Respects BEADS_DIR over prefix routing in show/close/update commands
- Dolt-native sync fixes - Disabled JSONL sync exports, auto-flush, and imports in dolt-native mode to prevent conflicts
- Daemon auto-import - Proper JSONL import on startup with hash update; check changes AFTER pulling
- Windows build - Dolt now builds on Windows via pure-Go regex; prebuilt releases in installer
- Cross-rig dependency resolution - Uses factory.NewFromConfig for proper backend detection
- Dolt lock contention - Advisory flock prevents zombie processes; scoped migration helpers
- Dolt connection stability - Retry logic for transient errors, timeout on embedded close, fix for nested query bad connections
- Dolt FK constraint - Removed FK constraint on depends_on_id for external references
- bd list --tree deduplication - Children no longer appear multiple times
- bd show relates-to display - Correctly displays and deduplicates RELATED section
- bd cleanup --hard - Always prunes tombstones immediately
- Formula TOML vars - Accept simple string vars in [vars] section
- config.yaml fallback - Custom types work in daemon mode
- Content-based merge for daemon pulls - Prevents spurious conflicts (GH#1358)
- TOML snake_case tags - Proper serialization of formula struct fields
- Worktree bare repo support - Use GetGitCommonDir for worktree creation
- routes.jsonl corruption - Excluded from FindJSONLInDir to prevent import errors
- Compaction safety logic - Restored accidentally removed safety checks
- Structured logging - Replaced custom daemonLogger with *slog.Logger
Documentation
- Non-interactive shell command guidance for agents
- Makefile CGO settings and DOLT.md env vars
- Atomic claim feature in quick reference
- ICU build deps and installer hints
- Community Tools: beads-sdk and Beads Task-Issue Tracker
[0.49.3] - 2026-01-31
Changed
- Embedded Dolt is now the default - Server mode is opt-in via
dolt_mode: "server"in metadata.json orBEADS_DOLT_SERVER_MODE=1env var
Fixed
- Dolt split-brain root cause eliminated (B1+B2) -
DatabasePath()now always resolves to.beads/dolt/for dolt backend regardless of staledatabasefield values;bootstrapEmbeddedDolt()blocks JSONL auto-import in dolt-native sync mode to prevent silent rogue database creation - CGO/ICU build fix - Makefile and test.sh detect Homebrew's keg-only
icu4cand export CGO flags so dolt's go-icu-regex dependency links correctly on macOS - Dolt mergeJoinIter panic - Eliminated three-table joins that triggered panics on type-filtered queries; added guard against nil pointer panic during auto-import in dolt-native mode
- Template variable extraction - Filter Handlebars keywords (
if,each,unless,with) fromextractVariables(#1411)
[0.49.2] - 2026-01-31
Added
-
GitLab backend for bidirectional issue sync - Full GitLab integration for syncing beads issues with GitLab
- REST API client wrapper with pagination, rate limiting, and context cancellation
- Bidirectional sync: pull from GitLab, push to GitLab with conflict detection
bd gitlab sync,bd gitlab status,bd gitlab projectssubcommands- GitLab-to-beads mapping with path-based IDs and collision handling
- Conflict resolution strategies for concurrent edits
- Integration and unit test suites
-
Key-value store - New
bd kvsubcommand for persistent key-value storagebd kv get,bd kv set,bd kv delete,bd kv listcommands- Key validation and proper exit codes on missing keys
-
Per-issue JSON metadata field - Optional metadata field on issues (SQLite + Dolt) (#1407)
-
Events JSONL export - Opt-in event audit trail export via
events-exportconfig -
Role configuration - Explicit role configuration via git for agent and user roles
bd initinteractive contributor role prompt- UserRole detection in RepoContext
- Agent roles configurable via config (bd-hx8w)
-
Dolt improvements
- Dolt-specific diagnostics and performance profiling in
bd doctor - Auto-detect Dolt server and enable server mode during
bd init - Env var overrides for Dolt server connection settings
bd backendandbd sync modesubcommands for inspecting storage config
- Dolt-specific diagnostics and performance profiling in
-
CLI improvements
comment_countin issue JSON views (list, ready, search)- Comment timestamps with time display and
--local-timeflag - Hint to view step instructions in
bd mol currentoutput (#1403) - Resolve external refs in
bd dep listfor cross-rig dependencies - Inline blocking dependency display in
bd listoutput
-
Jira sync -
pull_prefixandpush_prefixconfig options for flexible prefix mapping -
Sync - Push permission error detection during sync
Changed
-
Separation of concerns - Removed Gas Town-specific code from beads core
- Removed Gas Town role detection from hooks
- Removed
--role-typeflag frombd create - Removed Gas Town actor validation from validation layer
- Generalized RoleType to be project-agnostic
-
Refactoring
- Storage factory for backend-aware database access
- Compact accepts interface instead of concrete SQLiteStorage
- RPC layer no longer imports sqlite directly
- JSONL deletion markers now processed during import
Fixed
-
GitLab fixes - Multiple rounds of code review improvements for merge readiness
- Conflict detection before push with SyncContext
- Pagination limits and context cancellation
- Error handling and type safety improvements
-
Dolt backend fixes
- Graceful server-to-embedded fallback when Dolt server unreachable
- Detect and clean stale Dolt lock files
- Skip JSONL staleness check in dolt-native mode
- Backend detection in all
bd doctorfix functions - Use
GetDoltDatabase()instead of raw config for server mode - Factory-based storage creation for backend awareness
- Fix for stale JSONL in dolt-native mode
- SQLite not created when Dolt fails in dolt-native mode
- Revert Dolt lock cleanup workaround; fix embedded Dolt open via driver retries (#1389)
-
Sync fixes
- Set GIT_DIR and GIT_WORK_TREE in GitCmd for worktree support
- Normalize JSONL path in CommitToSyncBranch for sync-branch mode
- Use store.Path() for database mtime update
- Ensure sync-branch worktree exists on fresh clone (#1349)
- Skip sync when source and destination JSONL paths are identical (#1367)
- Respect dolt-native mode in daemon_sync_branch.go
- Respect dolt-native mode in JSONL export paths
- Auto-stage JSONL files after flush in pre-push hook
-
Other fixes
- Ignore undeclared handlebars in formula description text (#1394)
- Exclude ephemeral issues from Linear sync push (#1397)
- Allow event type in CreateIssue validation (#1398)
- Update MCP Stats model to match
bd stats --jsonoutput (#1392) - Handle EINVAL from chmod on Unix sockets in containers (#1399)
- Correct error message for
--gatedflag (#1391) - Check rows.Err() in SQLite GetAllEventsSince
- Exclude tombstones from external_ref uniqueness validation
- Handle nil pointer dereference in
bd restorewith invalid issue ID - Make daemon start idempotent (#1334)
- YAML config support for daemon auto-sync settings (#1294)
- Use IsValidWithCustom for
--typevalidation (#1356) - Skip SQLite-specific checks in doctor when using Dolt backend
- Tombstone wins over closed in merge conflict resolution
Documentation
- GitHub Copilot integration guide with cross-platform MCP paths (#1348)
- KV store CLI documentation
- Updated COMMUNITY_TOOLS.md
- Added export-state/ to gitignore template
[0.49.1] - 2026-01-25
Added
-
Dolt backend now fully supported - The Dolt storage backend has been extensively tested and is ready for community evaluation
- Note: Dolt is not enabled by default. We encourage users to try it out and report feedback!
- Auto-commit on write commands with explicit commit authors (#1267)
- Server mode for multi-client access - enables multiple processes to share a Dolt database
bd doctor --serverflag for Dolt server mode health checks- Server mode configuration in metadata.json schema
- Comprehensive test suite for Dolt storage backend (#1299)
- Lock retry and stale lock cleanup for operational reliability (#1260)
- Adaptive ID length instead of hardcoded 6 chars
- See docs/DOLT.md for setup guide
-
New command flags
bd activity --details/-dfor full issue information in activity feed (#1317)bd export --idand--parentfilters for targeted exports (#1292)bd update --append-notesflag to append to existing notes (#1304)bd update --ephemeraland--persistentflags (#1263)bd show --idflag for IDs that look like flags
-
Doctor improvements
--serverflag for Dolt server mode health checks- Stale closed issues check is now configurable (#1291)
-
Community tools - Added beads-kanban-ui, beads-orchestration (#1255), and abacus (#1262)
-
Newsletter generator - Automated narrative summaries of releases
Changed
- Homebrew installation - Now uses core tap for beads installation (#1261)
- GitHub Actions - Upgraded for Node 24 compatibility (#1307, #1308)
Fixed
-
Dolt backend fixes
- Skip JSONL checks in pre-push hook for dolt-native mode
- Add ID generation to transaction CreateIssue
- Use capabilities check instead of blanket Dolt block in daemon
- Recognize shim hooks as Dolt-compatible
- Add hook compatibility check and migration warning
- Skip JSONL sync for Dolt backend
- Refuse daemon startup with deprecated --start flag for Dolt backend
- Add YAML fallback for custom types/statuses
- Prevent daemon startup and fix routing same-dir check
- Proper server mode support for routing and storage
- Skip daemon auto-start for all Dolt backends
-
Daemon fixes
- Prevent stack overflow on empty database path (#1288, #1313)
- Add sync-branch guard to daemon code paths (#1271)
-
List command fixes
- Optimize
bd list --jsonto fetch only needed dependencies (#1316) - Prevent nil pointer panic in watch mode with daemon (#1324)
- Populate dependencies field in JSON output (#1296, #1300)
- Optimize
-
Import/export fixes
- Support custom issue types during import (#1322)
- Populate export_hashes after successful export (#1278, #1286)
- Use transaction for handleRename in upsertIssuesTx (#1287)
-
SQLite fixes
- Use BEGIN IMMEDIATE without retry loop (#1272)
- Add retry logic to transaction entry points (#1272)
- Use withTx helper for remaining transaction entry points (#1276)
-
Other fixes
bd gate add-waiternow functions correctly (#1265)- Respect BEADS_DIR environment variable in init (#1273)
- Find molecules attached to hooked issues (#1302)
- Separate parent-child deps from blocking deps in
bd show(#1293) - PrefixOverride now respected in transaction storage layer (#1257)
- Prime command defaults to beads, avoids TodoWrite/TaskCreate (#1289)
- Build:
make installnow properly builds, signs, and installs to ~/.local/bin
Documentation
- Dolt backend guide - Comprehensive docs/DOLT.md guide (#1310)
- Federation section with quick start and topologies
- Articles collection - Created ARTICLES.md for articles and tutorials about Beads (#1306)
[0.49.0] - 2026-01-21
Added
-
Dolt federation for multi-repo sync - Peer-to-peer issue synchronization across repositories
bd federation synccommand for syncing with configured peersbd federation statusshows connection and sync state- SQL-server mode for daemon (
--federationflag) enables peer connections - SQL user authentication for secure peer-to-peer sync
- Doctor federation health checks validate connectivity and sync state
- See docs/FEDERATION.md for setup guide
-
SQLite to Dolt migration - Migrate existing repos to version-controlled storage
bd migrate doltconverts SQLite database to Dolt backend- Preserves full issue history during migration
- Automatic JSONL bootstrap for routes and interactions
-
New commands
bd children <id>- Display child issues for a parentbd rename <old-id> <new-id>- Rename issue IDsbd view- Alias forbd showcommand (#1249)bd config validate- Validate sync configurationbd mol seed --patrol- Seed patrol molecules (#1149)
-
Sync improvements
- Per-field merge strategies for fine-grained conflict resolution
- Interactive conflict resolution with
--manualstrategy - Incremental export for large repositories (performance improvement)
sync.modeconfiguration to control sync behavior
-
CLI conveniences
-mflag as alias for--descriptioninbd create--typeand--exclude-typeflags for Linear sync filtering (#1205)--tree --parentcombination for hierarchical display (#1211)
-
Jujutsu (jj) version control support - Beads now works with jj repositories
- Hook support for jj operations
- Proper detection of jj-managed repositories
-
Codex CLI setup recipe - Automated setup for OpenAI Codex CLI integration (#1243)
-
Real-time activity feed - Uses fsnotify for instant updates
-
Per-worktree export state tracking - Each worktree maintains independent sync state
-
Automatic multi-repo hydration in
bd init --contributor- Routing and hydration now configured togetherbd init --contributorautomatically adds planning repo torepos.additional- Routed issues appear in
bd listimmediately after setup - No manual
bd repo addrequired for contributor workflow
-
Doctor improvements
- Routing+hydration mismatch detection - warns when routing configured without hydration
- Hydrated repo daemon check - ensures JSONL stays fresh in additional repos
- Patrol pollution detection and fix
--gastownflag for Gas Town-specific checks (#1162)- Federation health checks
-
Nix shell completions - Baked into default package (#1229)
Changed
-
Auto-routing disabled by default - Explicit opt-in required (#1177)
- Prevents unexpected cross-repo routing
- Enable with
routing.mode: autoin config.yaml
-
Gas Town types removed from core - Beads core no longer includes Gas Town-specific types
- Types like
patrol,convoymoved to Gas Town configuration - Cleaner separation between beads and Gas Town
- Ongoing cleanup tracked in bd-741si, bd-7nd6t, bd-31ajf
- Types like
Fixed
-
Daemon zombie state after database file replacement - Improved reconnection resilience (#1213)
- Health checks now properly detect and handle database file replacements
- Prevents "sql: database is closed" errors
-
Routed issues invisible in
bd list(split-brain bug) - Auto-flush JSONL after routing (#1251)bd createnow flushes JSONL immediately in target repo- Hydration now sees new issues immediately
-
WSL2 Docker Desktop compatibility - Detect bind mounts and disable WAL mode (#1224)
- Prevents database corruption on Docker Desktop file systems
-
Daemon stack overflow - Prevent recursion in handleStaleLock (#1238)
-
Molecule steps excluded from
bd ready- Filter out non-actionable items (#1246) -
Tree ordering stabilization - Consistent
--treeoutput (#1228) -
Cross-repo orphan detection - Honor
--dbflag (#1200) -
Custom types with daemon - Show custom types when daemon is running (#1216)
-
Dolt backend fixes
- Parse timestamps from TEXT columns correctly
- Single-process mode enforcement (daemon/autostart disabled) (#1221)
- Read-only daemon commands now work
- Init/daemon/doctor integration fixes (#1218)
-
Redirect handling - Follow redirect when creating database
-
Auto-import tombstone handling - Auto-correct deleted status to tombstone (#1231)
-
Routing store cleanup - Close original store before replacing (#1215)
-
Worktree redirect paths - Correct path computation in
bd worktree create(#1217) -
Sync-branch worktree - Use worktree for
--full --no-pull(#1183) -
Custom types from config - Load types.custom during init auto-import (#1226)
Documentation
-
Federation setup guide - Added docs/FEDERATION.md
- Peer configuration and authentication
- Sync workflow documentation
-
Daemon troubleshooting guide - Added docs/TROUBLESHOOTING.md and docs/DAEMON.md
- Common daemon issues and solutions
- Database replacement handling
-
Multi-repo hydration guide - Added comprehensive section to docs/ROUTING.md
- Explains hydration requirement when using routing
- Troubleshooting guide for common issues
-
Contributor vs maintainer setup - Added to README.md
- Clarifies when to use
bd init --contributor - Documents role configuration options
- Clarifies when to use
[0.48.0] - 2026-01-17
Added
-
VersionedStorage interface - Abstract storage layer with history/diff/branch operations
- Enables pluggable backends (SQLite, Dolt) with unified API
- Supports time-travel queries and branching semantics
-
bd synccommand specification - Formalized sync workflow implementation- Clearer separation between export, import, and merge phases
-
bd typescommand - List valid issue types (#1102)- Shows all available types with descriptions
-
"enhancement" type alias - Alternative name for "feature" type
- Matches GitHub issue label conventions
-
bd close -mflag - Alias for--reason(git commit convention)- More intuitive for git users:
bd close <id> -m "reason"
- More intuitive for git users:
-
RepoContext API - Centralized git operations context (#1102)
- Consistent git directory handling across codebase
-
Dolt backend improvements (WIP)
- Automatic bootstrap from JSONL on first access
- Git hook infrastructure for Dolt operations
bd compact --doltflag for Dolt garbage collection
Fixed
-
Doctor sync branch health check - Removed destructive --fix behavior (GH#1062)
- No longer warns about expected source file differences
- Prevents accidental sync branch history destruction
-
Duplicate merge target selection - Use combined weight (GH#1022)
- Considers both dependents and dependencies when choosing merge target
- Prevents closing issues with children/dependencies
-
Worktree exclude paths - Use --git-common-dir for correct paths (GH#1053)
- Fixes
bd init --stealthin git worktrees
- Fixes
-
Daemon git.author config - Apply configured author to sync commits
- Respects
git.authorconfig andBD_GIT_AUTHORenv var
- Respects
-
Hook chaining preservation - Prevent --chain from destroying original hooks (#1120)
- Backs up existing hooks before chaining
-
Sync routed prefixes - Allow routed prefixes in import validation
- Fixes multi-prefix workflow issues
-
Windows CGO-free builds - Enable building without CGO (#1117)
- Improved Windows compatibility
-
Shell completions without database - Work without .beads/ (#1118)
- Completions function in non-beads directories
-
Timestamp normalization - Normalize to UTC for validation (#1123)
- Prevents timezone-related validation failures
-
Symlinked .beads directories - Correct routing for symlinks (#1112)
- Proper resolution of symlinked beads directories
-
Nil pointer in ResolvePartialID - Prevent panic (#1132)
- Guards against nil pointer dereference
-
Orphaned dependencies on delete - Mark dependents dirty (#1130)
- Prevents orphan deps in JSONL after issue deletion
-
Git hooks in worktrees - Fix hook execution (#1126)
- Hooks now work correctly in linked worktrees
Documentation
-
CLI skill reference - Synced with v0.47.1 commands
- Updated command documentation in claude-plugin
-
AGENTS.md fixes - Removed references to nonexistent CLAUDE.md
- Corrected cross-references in documentation
[0.47.2] - 2026-01-14
Added
-
Dolt backend (experimental) - Version-controlled issue storage with time-travel
bd init --backend=doltenables Dolt-based storage- Full version history for issues with branch/merge semantics
- See docs/DOLT.md for migration guide
-
bd show --childrenflag - Display child issues inline with parent- Shows hierarchical structure in issue details
-
Comprehensive NixOS support - Improved Nix flake and home-manager integration
- Better daemon handling in Nix environments
- Updated flake.nix with proper dependencies
Changed
- Release workflow modernized - bump-version.sh replaced with molecule pointer
- Use
bd mol wisp beads-release --var version=X.Y.Zfor releases - New
scripts/update-versions.shfor quick local version bumps
- Use
Fixed
-
Redirect + sync-branch incompatibility - bd sync works correctly in redirected repos (bd-wayc3)
- Worktree git status failures resolved
- Proper handling of .beads/redirect during sync operations
-
Doctor project-level settings - Detects plugins/hooks/MCP in .claude/settings.json
- No longer misses project-scoped configurations
-
Contributor routing -
bd init --contributorcorrectly sets up routing (#1088)- Fork workflows now properly configure sync.remote=upstream
Documentation
- EXTENDING.md deprecated - Custom SQLite tables approach deprecated for Dolt migration
- External tools pattern recommended for integrations
[0.47.1] - 2026-01-12
Added
-
bd list --readyflag - Show only issues with no blockers (bd-ihu31)- Filters to issues that are immediately actionable
- Equivalent to
bd readybut integrated into list command
-
Markdown rendering in comments - Comment text now renders Markdown (#1019)
- Enhanced readability for formatted notes and descriptions
Changed
- Release formula improvements - Updated beads-release formula with v0.47.0 learnings
- Better gate handling and step organization
Fixed
-
Nil pointer in wisp create - Prevent panic when creating wisps (mol)
- Fixed nil pointer dereference in molecule creation
-
Route prefix for rig issues - Use correct prefix when creating issues in rigs (#1028)
- Issues created in rigs now use the proper routing prefix
-
Duplicate merge target selection - Prefer issues with children/deps (GH#1022)
- Better heuristics for choosing merge target in duplicate detection
-
SQLite cache rebuild - Rebuild blocked_issues_cache after rename-prefix (GH#1016)
- Ensures cache consistency after prefix changes
-
Doctor JSONL check - Exclude sync_base.jsonl from multiple files check (#1021)
- Reduces false positives in doctor diagnostics
-
Merge struct completeness - Add QualityScore field to merge Issue struct
- Ensures all fields preserved during merge operations
-
MCP custom types - Support custom issue types and statuses in MCP (#1023)
- MCP server now handles non-built-in types correctly
-
Hyphenated prefix validation - Support hyphens in ValidateIDFormat (#1013)
- Prefixes like
my-project-now validate correctly
- Prefixes like
-
Git worktree initialization - Prevent bd init inside git worktrees (#1026)
- Avoids configuration issues when initializing in worktree directories
Documentation
- bd reset clarification - Document command behavior and workarounds (GH#922)
- Clearer guidance on reset command usage
[0.47.0] - 2026-01-11
Added
-
Pull-first sync with 3-way merge - Major sync improvement (#918)
- Reconciles local changes with remote updates before pushing
- Field-level conflict merging reduces manual intervention
- Base state tracking for better change detection
-
bd resolve-conflictscommand - Resolve JSONL merge conflict markers (bd-7e7ddffa)- Mechanical mode uses updated_at timestamps for deterministic resolution
- Closed status wins over open, higher priority wins
- Notes concatenated, dependencies unioned
- Dry-run mode and JSON output for agent integration
-
bd create --dry-run- Preview issue creation without side effects (bd-0hi7)- Shows what would be created in human-readable or JSON format
- Works with --rig/--prefix flags
-
Gate auto-discovery - Auto-discover workflow run ID in
bd gate check(bd-fbkd)- Queries GitHub directly when await_id is a workflow name hint
- ZFC-compliant: takes most recent run deterministically
-
Linear project filter -
linear.project_idconfig for sync (#938)- Fetch only issues from a specific project instead of all team issues
-
bd ready --gated- Gate-resume discovery for molecules (bd-lhalq)- Find molecules waiting on gates for automatic resumption
-
Multi-repo custom types - Trust and discover types across repositories (bd-62g22, bd-9ji4z)
bd doctordiscovers custom types from multiple repos- Non-built-in types trusted during hydration
-
Visual UX improvements - Enhanced display for list tree, graph, and show commands
- Better formatting and readability
-
Stale database handling - AllowStale option in List API (bd-dpkdm)
- Read-only commands auto-import on stale DB (#977, #982)
- Cold-start bootstrap for read commands
-
Batch molecule operations -
bd mol burnsupports multiple molecules (feat(mol)) -
Redirect health checks -
bd doctorvalidates redirect configurations -
Schema extensions - New fields for HOP integration
crystallizescolumn in sqlite storageattestsedge type for skill attestationsownerfield for human attributionactorfallback includes git user.name (#994)
Fixed
-
Daemon mode completeness - Several daemon mode gaps closed (GH#952)
--dueand--deferflags now work in daemon mode (#953)bd dep add/remove --jsonreturns proper JSON output (#961)DeferUntilfield parsed correctly in daemon handleCreate (#950)- Silence deprecation warnings in
--jsonmode (#1039a691)
-
Sync robustness
- Canonicalize dbPath to fix filepath.Rel errors (GH#959, #960)
- Validate custom types in batch issue creation (#943)
- Force-add .beads in worktree for contributor mode (#947)
- Initialize store after daemon disconnect (GH#984)
sync --import-onlyworks when daemon was connected
-
Windows fixes
- Infinite loop in findLocalBeadsDir/findOriginalBeadsDir (GH#996)
bd initno longer hangs when not in a git repo (#991)- Daemon stop/kill uses proper Windows API (GH#992)
- SQLite uses DELETE mode on WSL2 Windows filesystem (GH#920)
-
Daemon socket handling - Long workspace paths now work (GH#1001, #1008)
- Socket path shortening for deep directory structures
- Relocate daemon socket for deep paths
-
Prevent data corruption
- FK constraint failures on batch/concurrent issue creation (GH#956)
- Prevent closing issues with open blockers (GH#962)
- Nil pointer panic in dep --json mode (GH#998)
-
Doctor improvements
- Recognize bd shims when external manager config exists (GH#946)
- Detect lefthook jobs syntax (GH#981)
- Add .sync.lock and sync_base.jsonl to gitignore (#980)
-
Prime command - Use flush-only workflow when no git remote configured (#940)
-
Install safety - Stop existing daemons before binary replacement (#945)
-
Git hooks - Add
--no-daemonto sync commands to prevent inline import failures (#948) -
Linear sync - Use project_id when creating issues via
sync --push(GH#973, #1012) -
Team wizard - Validate sync.branch in wizard and migrate commands (GH#923)
-
Worktree fixes
- Skip beads restore when directory is redirected (bd-lmqhe)
- Migrate sync works in git worktree environments (#970)
-
Misc fixes
bd editparses EDITOR with args (GH#987)- Use SearchIssues for ID resolution (GH#942)
- Respect hierarchy.max-depth config setting (GH#995, #997)
- Add timeout to daemon request context to prevent hangs
- Avoid null values in Claude settings hooks (GH#955)
- Restore Gas Town types (agent, role, rig, convoy, slot) (GH#941)
- Add TypeRig constant and IsBuiltIn method (GH#1002)
Changed
-
Daemon CLI refactor - Consolidated to subcommands with semantic styling (#1006)
-
Release formula refactor - Bump script broken into individual version-update steps (bd-a854)
- More durable: can resume from specific step if interrupted
- Better visibility in activity feed
Documentation
- Add lazybeads (Bubble Tea TUI by @codegangsta) to community tools (#951)
- Fix
bd quickstartlink to database extension documentation (#939)
[0.46.0] - 2026-01-06
Added
-
Custom type support - Configure custom issue types in beads config.yaml (bd-649s)
- Define project-specific types beyond the built-in set
- Types persist across sync and export
-
Gas Town types extraction - Core Gas Town types moved into beads package (bd-i54l)
- Enables beads to understand rig identities and agent workflows
- Foundation for deeper Gas Town integration
Fixed
- Gate workflow discovery - Handle workflow name hints in
gh:rungate discovery (bd-m8ew)- Better matching of GitHub Actions workflow runs
- Consolidated numeric ID handling
[0.45.0] - 2026-01-06
Added
-
Dynamic shell completions - Tab completion for issue IDs in bash/zsh/fish (#935)
- Optimized prefix filtering for faster completion
- Added completions to more commands
-
Android/Termux support - Native ARM64 binaries for Android (#887)
-
Deep pre-commit framework integration -
bd doctorchecks pre-commit hook configs (bd-28r5) -
Rig identity bead type - New
rigbead type for Gas Town rig tracking (gt-zmznh) -
--filter-parentalias - Alternative to--parentinbd list(bd-3p4u) -
Unified auto-sync config - Simpler daemon configuration for agent workflows (#904)
-
BD_SOCKET env var - Test isolation for daemon socket paths (#914)
Fixed
-
External hook manager detection -
bd doctornow detects lefthook, husky, pre-commit, and other hook managers- Checks if external managers have
bd hooks runintegration configured - Reports which hooks have bd integration vs which are missing
bd doctor --fixuses--chainflag when external managers detected to preserve existing hooks- Supports YAML, TOML, and JSON config formats for lefthook
- Detects active manager from git hooks when multiple managers present
- Checks if external managers have
-
Init branch persistence -
--branchflag now correctly persists to config.yaml (#934) -
Worktree resolution - Resolve worktrees by name from git registry (#921)
-
Sync with redirect - Use inline import for
--import-onlywith .beads/redirect (bd-ysal)- Handle .beads/redirect in git status checks (bd-arjb)
- Persist sync branch to yaml and database (GH#909)
- Atomic export and force-push detection (bd-3bhl, bd-4hh5)
-
Doctor improvements
- Recognize lowercase 's' skip-worktree flag (#931)
- Improve messaging for detection-only hook managers (bd-par1)
- Align duplicate detection with
bd duplicates(bd-sali) - Query metadata table instead of config for last_import_time (#916)
-
Update prefix routing -
bd updatenow routes likebd show(bd-618f) -
Formula phase - beads-release formula marked as vapor phase (gt-mjsjv)
-
Lint fixes - Address gosec, misspell, and unparam warnings
-
CI improvements - Windows smoke tests, timeouts, golangci-lint exclusions
Changed
- Test refactoring - Replace testify with stdlib in daemon tests (#936)
Documentation
- Add bun installation method to INSTALLING.md (#930)
- Add Parade app to community tools list
[0.44.0] - 2026-01-04
Added
-
Recipe-based setup architecture - Major refactor of
bd init(bd-i3ed)- Modular, composable setup via recipes
- Cleaner separation of init concerns
-
Gate evaluation system - Phases 2-4
bd gate checkfor timer and GitHub gate evaluation (GH#884)bd gate discoverfor auto-discovery of gh:run await_id (bd-z6kw)bd gate add-waiterandbd gate showfor phase handoff- Cross-rig bead gate support
- Gate-aware beads-release.formula v2 (bd-r24e)
- Merge-slot gate for serialized conflict resolution
-
Dependency command improvements
--blocksshorthand flag for natural dependency syntax (GH#884)--blocked-byand--depends-onflag aliases (bd-09kt)
-
Multi-prefix support -
allowed_prefixesconfig option (#881)- Configure multiple valid prefixes per rig
- Enables flexible issue routing
-
Sync improvements
- Detect uncommitted JSONL changes before sync (GH#885)
bd doctorsync divergence check for JSONL/SQLite/gitBD_DEBUG_SYNCenv for protection debugging
-
PRIME.mdoverride - Workflow customization (GH#876)- Custom prime output per project
-
Daemon config -
daemon.auto_*settings in config.yaml (GH#871) -
Compound visualization -
bd mol showdisplays compound structure (bd-iw4z) -
/handoffskill - Session cycling slash command (bd-xwvo)
Fixed
-
bd readynow shows in_progress issues (#894)- Previously filtered out your active work
-
bd showdisplays external_ref field in text output (#899) -
macOS case-insensitive path handling (GH#880)
- Worktree validation, daemon paths, git operations
- Canonicalize path case for consistency
-
Sync metadata timing - Finalize after commit, not push (GH#885)
- Defer SQLite metadata updates until after git commit
- Prevents sync state corruption
-
Sparse checkout isolation - Prevent config leaking to main repo (GH#886)
- Disable sparse checkout on main repo after worktree creation
-
close_reasonpreserved during merge/sync (GH#891) -
Parent hub contamination during
bd init(GH#896) -
NoDb mode - Set cmdCtx.StoreActive correctly (GH#897)
-
Event storm prevention when gitRefsPath is empty (#883)
-
Doctor improvements
- Detect status mismatches between DB and JSONL (GH#885)
- Detect missing git repo, improve daemon startup message (#890)
- Skip JSONL tracking checks in sync-branch mode (GH#858)
-
bd rename-prefix- Sync JSONL before and after (#893) -
sync.remoteconfig now respected inbd sync(GH#872) -
Snapshot protection made timestamp-aware (GH#865)
-
Hyphenated rig names supported in agent IDs (GH#854, GH#868)
-
Cross-repo agent routing (#864)
-
Config key normalization - GetYamlConfig matches SetYamlConfig (#874)
-
Daemon startup failure - Propagate reason to user (GH#863)
-
Molecule variable substitution in root bead title/desc
-
Submodule detection - Correct main repo root detection (#849)
-
bd mergeoutput sorted by issue id (#859) -
Auto-create agent bead when
bd agent statecalled on non-existent agent -
Windows zip extraction - Add retry logic for npm install
-
Cycle detection runs in daemon mode for --blocks flag
-
bd slot setcross-beads prefix routing (bd-hmeb) -
git statusnoise - Hide issues.jsonl when sync.branch configured (GH#870)
Changed
- Skill names updated from
/bd-*to/beads:*(#862)
Performance
- Batch external dep checks by project (bd-687v)
Internal
- Extract warnIfCyclesExist helper
- Gate field parsing and creation tests
- Sync unit tests for gitHasUncommittedBeadsChanges
- SQLite cache rebuild benchmarks
- Repository guards in deployment workflows
[0.43.0] - 2026-01-02
Added
-
Step.Gate evaluation - Phase 1: Human Gates
- Gate steps that require human approval before proceeding
- Foundation for workflow control points
-
bd lintcommand - Template validation- Validate issue templates against schema
--validateflag also added tobd create
-
bd ready --pretty- Formatted output- Human-friendly display of ready work
Fixed
- Cross-rig routing -
bd closeandbd updatenow support cross-rig operations via prefix routing - Agent ID validation - Now accepts any rig prefix (GH#827)
bd syncin bare repo worktrees - Fixed exit 128 error (GH#827)bd --no-db dep tree- Now shows complete tree (GH#836).beads/last-touched- Restored to gitignore template (GH#838)
[0.42.0] - 2025-12-30
Added
-
llms.txtstandard support - AI agent discoverability (#784)- Standard endpoint for AI agents to discover project info
- Helps LLM-powered tools understand your project
-
bd preflightcommand - PR readiness checks- Static checklist for pre-commit/pre-push verification
- Phase 1 implementation with test, lint, and version checks planned
-
--claimflag forbd update- Work queue semantics- Atomic claim-and-assign for multi-agent coordination
- Prevents race conditions in work assignment
-
bd stateandbd set-state- Label-based state management- Helper commands for operational state patterns
- Documents labels-as-state pattern
-
bd activity --town- Cross-rig activity feed- Aggregated view across all rigs in town
- Better visibility into multi-rig workflows
-
Convoy issue type - Reactive completion tracking
- Issues that complete when all tracked items complete
tracksrelation type for convoy membership
-
Agent identity trailers - prepare-commit-msg hook
- Automatically adds agent identity to commits
- Structured labels for agent beads
-
Daemon RPC endpoints - Config and mol stale
- Remote config queries via daemon
- Stale molecule detection endpoint
-
Non-TTY auto-detection - Cleaner output in pipes
- Automatically adjusts output for non-interactive use
Fixed
- Git hook chaining now works correctly (GH#816)
.beads/redirectnot committed - Prevents worktree conflicts (GH#814)bd syncwith sync-branch - Fixes worktree copy direction (GH#810, #812)sync.branchvalidation - Rejects main/master as sync branch (GH#807)- Read operations read-only - No more database writes on list/ready/show (GH#804)
bd listdefaults - Non-closed issues, 50 limit to protect context (GH#788)- External direct-commit bypass - When sync.branch configured (bd-n663)
- Migration 022 syntax - SQL error on v0.30.3 upgrade path
- MCP redirect support - Plugin follows .beads/redirect files
- Jira sync error - Better message when Python script not found (GH#803)
- Doctor false positives - For molecule/wisp prefix variants
- BD_ACTOR in direct mode - Consistent actor handling
- Label accumulation - When updating agent role_type/rig
[0.41.0] - 2025-12-29
Added
-
bd swarmcommands - Multi-agent batch work coordinationbd swarm create- Create swarm from epic with childrenbd swarm status- Show swarm progress and blocked workbd swarm validate- Validate swarm structure and dependencies- N+1 query fix for blocked checks (performance optimization)
-
bd repaircommand - Orphaned reference repair- Detect and repair orphaned foreign key references
- Support for comments/events orphan detection
--jsonflag for machine-readable output- Transaction safety with backup and dirty_issues marking
-
bd compact --purge-tombstones- Dependency-aware cleanup- Remove tombstones while respecting dependency order
- Safe cleanup that won't break DAG structure
-
bd init --from-jsonl- Manual cleanup preservation- Initialize database from curated JSONL file
- Preserves manual edits made to JSONL
-
bd humancommand - Focused help menu- Human-friendly command reference
- Quick overview without CLI verbosity
-
bd show --short- Compact output mode- Brief issue summary for scripting
- Less verbose than default format
-
bd delete --reason- Audit trail for deletions- Optional reason stored in activity log
- Better traceability for issue cleanup
-
hookedstatus - Hook-based work assignment- New status for issues assigned to agent hooks
- Enables autonomous agent work pickup
-
mol_typeschema field - Molecule classification- Track molecule type (patrol, work, etc.)
- New migration (adds schema field)
-
Agent ID canonical naming - Validation update
- Updated validation for orchestrator naming conventions
- Supports rig/role/name format
Fixed
-
--varflag allows commas in values (GH#786)- Variables like
--var files=a.go,b.gonow work correctly - Parser respects quoted values
- Variables like
-
bd syncin bare repo worktrees (GH#785)- Fixed sync failure when working in worktrees of bare repos
- Correctly detects git configuration
-
bd delete --cascaderecursive deletion (GH#787)- Now properly deletes all transitive dependents
- Previously only deleted direct children
-
bd doctorpre-push hook detection (GH#799)- No longer falsely reports hook issues
- Correctly identifies bd-managed hooks
-
Gitignore fork protection (GH#796)
- Removed negations that could override protection
- Safer fork handling
-
Illumos/Solaris disk space check (GH#798)
- Added platform support for disk space detection
- Expands OS compatibility
-
Pre-migration orphan cleanup - Chicken-and-egg fix
- Clean orphans before migration to avoid failures
- Smoother upgrade path
-
hq-prefix routing - Town root discovery- Correctly finds routes.jsonl from anywhere in town
- Fixes cross-rig routing for HQ beads
-
Config.yaml database override warning
- Shows warning when config overrides db location
- Helps debug unexpected behavior
-
normalizeBeadsRelPathedge case - Similar prefix handling- Fixes path normalization for similar prefix names
- e.g.,
beadsvsbeads-sync
-
bd doctor --fixredirect handling- Properly follows .beads/redirect files
- Limited verbose output for cleaner runs
Changed
-
CLI command consolidation - Reduced surface area
- Grouped related commands under parent commands
- Cleaner
bd --helpoutput
-
Code organization - File size limits
- Split large cmd/bd files to meet 800-line limit
- init.go: 1928 → 705 lines
- Improved maintainability
-
Documentation updates
- Replace Epic Planning with Ready Front model
- Add components overview (CLI vs Plugin vs MCP)
- Add installation method comparison table
Internal
- Extract IssueDetails to shared type
- Export FollowRedirect and consolidate implementations
- Extract shared getEpicChildren helper for swarm commands
- Extract hashFieldWriter to reduce ComputeContentHash repetition
- Break up runCook (275 lines) into focused helpers
- Break up flushToJSONLWithState (280 lines) into focused helpers
- Extract shared importFromJSONLData function
- Consolidate duplicated step collection functions
- Add git helper and guard annotations for tests
- Fix golangci-lint errors (errcheck, gosec, unparam)
[0.40.0] - 2025-12-28
Added
-
bd worktreecommand - Parallel development support- Manage git worktrees with beads integration
- Enables working on multiple issues simultaneously
-
bd slotcommands - Agent bead slot management- Track agent assignments with dedicated slot operations
- Supports multi-agent orchestration workflows
-
bd agent statecommand - ZFC-compliant state reporting- Report agent state in standardized format
- Enables machine-readable status checks
-
bd doctor --deep- Full graph integrity validation- Deep validation of bead dependency graphs
- Includes agent bead integrity checks
-
Agent bead support - New bead types
type=agentandtype=rolefor agent tracking- Agent-specific fields in schema (migration 030)
- Agent ID pattern validation on create
-
Computed
.parentfield - JSON output enhancement- Parent field included in JSON for convenience
- Simplifies integration with external tools
-
Auto-bypass daemon for wisp operations - Performance
- Ephemeral wisp operations skip daemon overhead
- Faster patrol cycle processing
-
Pour warning for vapor-phase formulas - Safety
- Warning when pouring formulas designed for wisps
- Prevents accidental persistent molecule creation
Fixed
-
O(2^n) → O(V+E) cycle detection (GH#775) - Performance
- Replaced exponential algorithm with linear DFS
- Dramatic speedup for large dependency graphs
-
Import hash mismatch warnings - Data integrity
- Update jsonl_file_hash on import operations
- Prevents spurious hash mismatch warnings
Deprecated
The following commands are deprecated and will be removed in v1.0.0:
bd relate→ usebd dep relateinsteadbd unrelate→ usebd dep unrelateinsteadbd daemons→ usebd daemon <subcommand>insteadbd cleanup→ usebd admin cleanupinsteadbd compact→ usebd admin compactinsteadbd reset→ usebd admin resetinsteadbd comment→ usebd comments addinsteadbd template→ usebd molinsteadbd templates→ usebd formula listinsteadbd template show→ usebd mol showinsteadbd template bond→ usebd mol bondinsteadbd detect-pollution→ usebd doctor --check=pollutioninsteadbd migrate-hash-ids→ usebd migrate hash-idsinsteadbd migrate-tombstones→ usebd migrate tombstonesinsteadbd migrate-sync→ usebd migrate syncinsteadbd migrate-issues→ usebd migrate issuesinstead
All deprecated commands continue to work but print a warning. Update your scripts and muscle memory before v1.0.0 to avoid breakage.
Changed
-
Community tools documentation (GH#772, GH#776)
- Consolidated into dedicated docs page
- Added opencode-beads to community tools list
-
Activity feed improvements - Better context
- Shows title and assignee in activity entries
- More informative
bd activityoutput
[0.39.1] - 2025-12-27
Added
-
bd wherecommand - Show active beads location- Displays the resolved database path after following redirects
- Helpful for debugging multi-rig setups
-
--parentflag forbd update- Reparent issues- Move issues between epics with
bd update <id> --parent=<new-parent> - Supports clearing parent with
--parent=none
- Move issues between epics with
-
Redirect info in
bd prime- Multi-clone support- Shows when database is redirected to another location
- Improves visibility into routing behavior
Fixed
-
Doctor follows redirects - Multi-clone compatibility
bd doctornow correctly follows database redirects- Prevents false negatives when running from rig roots
-
Remove 8-char prefix limit (GH#770) -
bd rename-prefix- Removed arbitrary length restriction on issue prefixes
- Allows longer, more descriptive prefixes
Changed
- Git context consolidation - Internal refactor
- Unified git context into single cached struct
- Reduces redundant git operations
Documentation
-
Database Redirects section - ADVANCED.md
- Comprehensive documentation for redirect feature
- Explains multi-clone integration patterns
-
Community Tools update (GH#771) - README.md
- Added opencode-beads to community tools list
[0.39.0] - 2025-12-27
Added
-
bd orphanscommand (GH#767) - Detect orphaned issues- Finds issues mentioned in git commits that were never closed
- DRY refactoring of orphan detection from
bd doctor - Helps maintain issue hygiene in larger projects
-
bd adminparent command - Consolidated admin toolsbd admin cleanup- Clean up unused databd admin compact- Compact the databasebd admin reset- Reset to initial state- Reduces top-level command clutter
-
--prefixflag forbd create- Cross-rig issue creation- Create issues in other rigs from any directory
- Accepts prefix (
bd-), short form (bd), or rig name (beads) - Works with existing routes.jsonl routing
Changed
-
bd mol catalog→bd formula list- Command rename- Aligns with formula-based terminology
bd formula listshows available molecule templates
-
bd info --thanks- Relocated thanks command- Contributors list moved under
bd info - Reduces command namespace pollution
- Contributors list moved under
-
Removed unused commands
bd pin,bd unpin,bd hookremoved- Functionality covered by orchestrator molecule commands
- Cleaner separation between beads (data) and orchestration
-
bd doctor --check=pollution- Integrated test pollution check- Detects test artifacts left in production database
- Previously standalone
bd detect-pollutioncommand
Fixed
-
macOS codesigning - Fixed
bump-version.sh --install- Ad-hoc signing for local installations
- Prevents macOS from quarantining the binary
-
Lint errors and Nix vendorHash (GH#769)
- Resolved golangci-lint issues
- Updated Nix package hash for reproducible builds
Documentation
-
Issue Statuses section - CLI_REFERENCE.md
- Comprehensive status lifecycle documentation
- Clear explanations of open, pinned, in_progress, blocked, deferred, closed, tombstone
-
Consolidated UI_PHILOSOPHY files (GH#745)
- Merged duplicate philosophy docs
- Single source of truth for UI design principles
-
README and PLUGIN.md fixes (GH#763)
- Corrected installation instructions
- Updated plugin documentation
[0.38.0] - 2025-12-27
Added
-
Prefix-based routing - Cross-rig command routing
bdcommands auto-route to correct rig based on issue ID prefix- Routes stored in
~/gt/.beads/routes.jsonl - Enables seamless multi-rig workflows from any directory
-
Cross-rig ID auto-resolve - Smarter dependency handling
bd dep addauto-resolves issue IDs across different rigs- No need to specify full paths for cross-rig dependencies
-
bd mol pour/wispsubcommands - Reorganized command hierarchybd mol pourfor persistent moleculesbd mol wispfor ephemeral workflows- Cleaner organization under
bd molnamespace
-
Comments display in
bd show(GH#177) - Enhanced issue details- Comments now visible in issue output
- Shows full discussion thread for issues
-
created_byfield on issues (GH#748) - Creator tracking- Track who created each issue for audit trail
- Useful for multi-agent workflows
-
Database corruption recovery (GH#753) - Robust doctor repairs
bd doctor --fixcan now auto-repair corrupted SQLite databases- JSONL integrity checks detect and fix malformed entries
- Git hygiene checks for stale branches
-
Chaos testing for releases - Thorough validation
--run-chaos-testsflag in release script- Exercises edge cases and failure modes
-
Pre-commit config - Local lint enforcement
- Consistent code quality before commits
Changed
-
CLI consolidation - Reduced top-level command clutter
bd cleanup,bd compact,bd reset→bd admin cleanup|compact|resetbd migrate-*→bd migrate hash-ids|issues|sync|tombstonesbd cook→bd formula cookbd detect-pollution→bd doctor --check=pollutionbd quickstarthidden, use docs/QUICKSTART.md instead- Hidden aliases maintain backwards compatibility with deprecation notices
-
Sync backoff and tips consolidation (GH#753) - Smarter daemon
- Daemon uses exponential backoff for sync retries
- Tips consolidated from multiple sources
-
Wisp/Ephemeral naming finalized -
wispis canonicalbd mol wispis the correct command- Internal API uses "ephemeral" but CLI uses "wisp"
Fixed
-
Comments display position (GH#756) - Formatting fix
- Comments now display outside dependents block
- Proper visual hierarchy in
bd showoutput
-
no-db mode storeActive (GH#761) - JSONL-only fix
storeActivecorrectly set in no-database mode- Fixes issues with JSONL-only installations
-
--resolutionalias (GH#746) - Backwards compatibility- Restored
--resolutionas alias for--reasononbd close
- Restored
-
bd graphwith daemon (GH#751) - Daemon compatibility- Graph generation works when daemon is running
- No more conflicts between graph and daemon operations
-
created_byin RPC path (GH#754) - Daemon propagation- Creator field correctly passed through daemon RPC
-
Migration 028 idempotency (GH#757) - Safe re-runs
- Migration handles partial or repeated runs gracefully
- Checks for existing columns before adding
-
Routed ID daemon bypass - Cross-rig show
bd showwith routed IDs bypasses daemon correctly- Storage connections closed per iteration to prevent leaks
-
Modern git init (GH#753) - Test compatibility
- Tests use
--initial-branch=mainfor modern git versions
- Tests use
-
golangci-lint clean (GH#753) - All platforms
- Resolved all lint errors across platforms
Improved
- Test coverage - Comprehensive testing
- Doctor, daemon, storage, and RPC client paths covered
- Chaos testing integration for edge cases
[0.37.0] - 2025-12-26
Added
-
Gate commands - Async coordination for agent workflows
bd gate create- Create gates with await conditions (gh:run, gh:pr, timer, human, mail)bd gate eval- Evaluate timer and GitHub gates (checks run completion, PR merge)bd gate approve- Approve human gatesbd gate show/list/close/wait- Full gate lifecycle management
-
bd close --suggest-next(GH#679) - Smart workflow continuation- Shows newly unblocked issues after closing
- Helps agents find next actionable work
-
bd ready/blocked --parent(GH#743) - Epic-scoped filtering- Filter issues by parent bead or epic
- Enables focused work within a subtree
-
TOML support for formulas - Alternative format
.formula.tomlfiles alongside JSON support- Human-friendly authoring option
-
Fork repo auto-detection (GH#742) - Contributor workflow
- Detects fork repositories during init
- Offers to configure .git/info/exclude for stealth mode
-
Control flow operators - Advanced formula composition
loopoperator for iterating over collectionsgateoperator for conditional execution- Condition evaluator for gates and loops
- Control flow integrates with aspect composition
-
Aspect composition - Cross-cutting workflow concerns
aspectsfield in formulas for reusable patterns- Aspects match steps by type, title pattern, or custom criteria
- Enables logging, retries, notifications as composable concerns
-
Runtime expansion types - Dynamic step generation
on_complete- Generate steps when a step completesfor-each- Expand steps for each item in a collection- Enables dynamic workflows based on runtime state
-
bd formula list/show- Formula discovery commandsbd formula list- List available formulas in search pathsbd formula show <name>- Display formula definition and metadata
-
bd mol stale- Detect complete-but-unclosed molecules- Finds molecules where all children are closed but molecule is open
- Helps identify forgotten cleanup tasks
-
Stale molecules check in doctor - Proactive detection
bd doctornow warns about stale molecules- Integrated with
bd mol staledetection
-
Distinct ID prefixes - Clear entity type identification
- Protos:
bd-proto-xxxprefix - Molecules:
bd-mol-xxxprefix - Wisps:
bd-wisp-xxxprefix - Makes entity type immediately visible in IDs
- Protos:
-
no-git-opsconfig (GH#593) - Manual git controlbd config set no-git-ops trueto disable auto git operationsbd primeoutputs stealth-mode protocol when enabled- Useful for custom git workflows or manual commit review
Changed
-
Formula format: YAML → JSON - Standardized format
- Formulas now use
.formula.jsonextension - JSON provides better tooling support and validation
- Existing YAML formulas need migration
- Formulas now use
-
Removed
bd mol run- Orchestration delegated to orchestrator- Molecule execution now handled by orchestrator commands
bdfocuses on issue tracking primitives- Use orchestrator's molecule runner for execution
-
Simplified wisp architecture - Single database model
- Wisps stored in main database with
Wisp=trueflag - Removed separate
.beads-wisp/directory - Wisps filtered from JSONL export automatically
- Wisps stored in main database with
Fixed
-
Gate await fields preserved during upsert - Multirepo sync
- Gate fields no longer cleared during multi-repo sync operations
- Enables reliable gate coordination across clones
-
Tombstones retain closed_at timestamp - Soft delete metadata
- Tombstones preserve the original close time
- Maintains accurate timeline for deleted issues
-
Git detection caching - Performance improvement
- Cache git worktree/repo detection results
- Eliminates repeated slowness on worktree checks
-
Windows MCP graceful fallback (GH#387) - Platform compatibility
- Daemon mode falls back gracefully on Windows
- Prevents crashes when daemon unavailable
-
Windows npm postinstall file locking (GH#670) - Install reliability
- Handles file lock errors during npm install
- Improves installation success on Windows
-
installed_plugins.json v2 format (GH#741) - Claude Code compatibility
bd doctornow handles both v1 and v2 plugin file formats- Fixes "cannot unmarshal array" error on newer Claude Code versions
-
git.IsWorktree() hang on Windows (GH#727) - Init safety
- Added isGitRepo() guard before calling git.IsWorktree()
- Fixes
bd inithanging outside git repositories on Windows
-
Skill files deleted by bd sync (GH#738) - Sync safety
bd syncno longer deletes skill files in .claude/- Prevents accidental removal of Claude Code configuration
-
doctor check false positives (GH#709) - Cleaner diagnostics
- Skips interactions.jsonl and molecules.jsonl in sync checks
- These files are runtime state, not sync targets
-
FatalErrorRespectJSON - Consistent error output
- All commands respect
--jsonflag for error output - Errors return proper JSON structure when flag is set
- All commands respect
-
bd sync commits non-.beads files - Sync isolation
- Sync operations now only commit .beads/ directory changes
- Prevents unintended commits of working directory files
-
Content-level merge for divergence - Better conflict resolution
- Divergence recovery uses content-level merging
- Reduces false conflicts during multi-clone sync
-
Child→parent dep fix opt-in - Migration control
--fix-child-parentflag required for automatic fix- Prevents unexpected dependency modifications
-
Aspect self-matching recursion - Formula safety
- Aspects cannot match themselves during expansion
- Prevents infinite recursion in aspect composition
-
Map expansion nested matching - Correct child handling
- Map expansion now correctly matches nested child steps
- Fixes missing expansions in hierarchical formulas
-
Mol/wisp ID prefix combination - Correct ID generation
- Database prefix combined with type prefix correctly
- IDs like
bd-mol-xxxinstead ofbdmol-xxx
-
mol run hierarchical children (bd-c8d5, bd-drcx) - Complete loading
bd mol runloads all hierarchical children- Supports title lookup for molecule identification
-
Wisps excluded from sync (bd-687g, bd-9avq) - Export correctness
- Wisps filtered from JSONL export and nodb operations
- Ephemeral molecules don't pollute shared state
Documentation
-
MOLECULES.md rewrite - Workflow-first structure
- Reorganized around practical workflows
- Clearer distinction between protos, molecules, wisps
-
Molecular chemistry docs - Conceptual foundation
- Phase metaphor: solid (proto) → liquid (mol) → vapor (wisp)
- Pour, bond, distill, squash operations explained
[0.36.0] - 2025-12-24
Added
-
Formula system (bd-weu8, bd-wa2l) - Declarative workflow templates
bd cook <formula>- Execute a formula template with variable interpolation- Formula files (
.formula.json) support inheritance viaextends needsandwaits_forfields for dependency declarations--prefixflag for custom issue prefix when cooking- Search paths:
.beads/formulas/,~/.beads/formulas/,~/gt/.beads/formulas/
-
Gate issue type - Async coordination primitives
bd gate create <name>- Create a gate for coordinating parallel workbd gate open <id>- Open a gate (unblock waiters)bd gate close <id>- Close a gate (block new work)- Gates integrate with
waits-fordependencies for fanout patterns
-
bd listviewer enhancements (#729) - Built-in terminal UI--pretty- Colorized, formatted output for human viewing--watch- Live-updating view (refreshes on changes)
-
bd searchfilters - Enhanced search capabilities--after,--before- Date range filtering--priority- Exact priority match--content- Full-text content search
-
bd compact --prune- Standalone tombstone pruning- Prune old tombstones without full compaction
- Configurable retention period
-
bd export --priority- Exact priority filter for exports -
--resolutionalias (GH#721) - Alternative to--reasononbd closebd close bd-42 --resolution "Fixed in commit abc123"
-
Database size check in doctor (#724) - Issue count threshold warnings
- Warns when issue count exceeds configurable threshold
- Helps identify when cleanup or compaction is needed
-
Config override notifications (#731) - Transparency for config sources
- Shows when environment variables override config file values
- Helps debug unexpected behavior from env overrides
-
Windows code signing infrastructure - Signed Windows binaries
- Code signing certificate integration for Windows releases
- Improved trust and installation experience on Windows
-
RPC endpoints for monitoring (bd-0oqz, bd-l13p)
GetMoleculeProgress- Query molecule execution stateGetWorkerStatus- Query worker health and current task
-
Cross-database molecule spawning
bd mol runcan spawn in external beads databases- Enables cross-project workflow orchestration
-
Config-based close hooks - Custom scripts on issue close
- Configure hooks in
.beads/config.yaml - Run validation or notification scripts when issues close
- Configure hooks in
Changed
-
Removed
bd mol spawn- Use pour/wisp onlybd pour <proto>for persistent moleculesbd wisp create <proto>for ephemeral molecules- Simplifies mental model: pour = liquid (persistent), wisp = vapor (ephemeral)
-
bd readyexcludes workflow types - Cleaner ready queue- Gates and other workflow coordination types excluded by default
- Use
--include-workflowto see all types
-
Natural language activation (#718) - Improved Claude integration
- Enhanced activation patterns for natural language commands
- Anthropic 2025 API compliance updates
Fixed
-
Dots in prefix handling (GH#664) - SQLite extractParentChain fix
- Prefixes containing dots (e.g.,
my.project) now work correctly - Parent chain extraction uses proper escaping
- Prefixes containing dots (e.g.,
-
allowed_prefixes config respected - Import validation
- Import now respects
allowed_prefixesconfiguration - Prevents importing issues with unauthorized prefixes
- Import now respects
-
Child counter updates (GH#728) - Explicit child ID creation
child_counterstable updated when explicit child IDs created- Prevents ID collision when mixing auto and explicit child IDs
-
Comment timestamps preserved (#735) - Import fidelity
created_attimestamps on comments preserved during import- Maintains audit trail for imported issues
-
sync.remote config respected (#736) - Daemon sync operations
- Daemon respects configured remote for sync operations
- Fixes sync to wrong remote when multiple remotes configured
-
Export requires -o flag (#733) - Explicit output control
bd exportnow requires-oflag to write to file- Prevents accidental stdout pollution in scripts
-
YAML config key normalization (#732) - Consistent config parsing
- Config keys normalized to canonical format (snake_case)
sync.remoteandsync_remoteboth work
-
JSON output standardization - Consistent API
- Empty arrays return
[]notnull - Error responses have consistent structure
- All commands with
--jsonfollow same patterns
- Empty arrays return
-
MCP Claude Code compatibility - Tool schema fix
- Added
output_schema=Noneto MCP tools - Fixes "Invalid schema" errors in Claude Code
- Added
-
Windows file locking - Better Windows support
- Proper file handle cleanup prevents locking issues
- Fixes "file in use" errors on Windows
-
Template commands with daemon - Daemon mode compatibility
bd pour,bd wisp creatework correctly with daemon running
-
Startup config to config.yaml (GH#536) - Config persistence
- Startup wizard writes to config.yaml, not SQLite
- Configuration survives database recreation
-
Multi-hyphen prefixes (GH#422) - Prefix parsing
- Prefixes like
my-project-nameparsed correctly - Fixes issue ID extraction with complex prefixes
- Prefixes like
-
--pourflag in bond operations - Phase controlbd mol bond --pourcorrectly forces liquid phase
-
Stealth mode gitignore (GH#704) - Local-only exclusion
- Uses
.git/info/excludeinstead of global gitignore - Stealth mode truly local to the repository
- Uses
-
Pinned field import - Field preservation
pinnedfield preserved during JSONL import
-
External deps in orphan check - Migration fix
- External dependencies excluded from orphan validation
- Fixes spurious migration warnings
-
Child→parent dependency detection - Prevents LLM temporal reasoning trap
- Epic children can no longer depend on their parent epic
- Blocks a common AI mistake: LLMs use temporal reasoning for "phases" and invert dependencies
- Example: "Phase 1 before Phase 2" triggers "Phase 1 blocks Phase 2" → WRONG
- Correct model: "Phase 2 needs Phase 1" →
bd dep add phase2 phase1 - Clear error message explains the anti-pattern when detected
Improved
-
Test coverage - Significant improvements across codebase
- daemon: 27% → 72%
- compact: 17% → 82%
- setup: 28% → 54%
- storage: interface conformance tests
- RPC: comprehensive delete handler tests
-
Structured logging - Better observability
- Daemon uses
slogfor structured logging - Consistent log format across components
- Daemon uses
-
Code organization - Modular refactoring
- Split
sync.gointo focused modules - Split
queries.gointo focused modules - Typed JSON response structs (no more
map[string]interface{})
- Split
-
JSONL size reduction - Smaller exports
omitemptyon all JSONL fields- Removes null/empty values from exports
[0.35.0] - 2025-12-23
Added
-
Dynamic molecule bonding - Attach templates to running molecules at runtime
bd mol bond <proto> <target> --ref <issue-id>- Inject template steps dynamically- Enables responsive workflows: attach error recovery, expand scope mid-execution
- Templates can reference existing issue data via
--reffor variable interpolation
-
bd activitycommand - Real-time state feed for workflow monitoring- Stream mutation events as they happen (JSON format)
- Monitor molecule progress without polling
- Useful for dashboards, debugging, and automation
-
waits-fordependency type - Fanout coordination gatesbd dep add <gate> <step> --type waits-for- Gate waits for all steps- Unlike
blocks, waits-for is used for parallel coordination (fan-in pattern) - Gate unblocks only when ALL waits-for dependencies complete
-
Parallel step detection - Auto-identify parallelizable work
- Molecules automatically detect steps that can run concurrently
bd mol showdisplays parallel-capable step groups- Helps agents optimize execution order
-
Molecule navigation commands (bd-sal9, bd-ieyy) - Track progress through workflows
bd mol current- Show current step and molecule progressbd close --continue- Auto-advance to next step in moleculebd close --no-auto- Close without auto-claiming next step
-
bd list --parentflag - Filter issues by parentbd list --parent=bd-xyz --status=openshows open children of bd-xyz- Useful for epic progress tracking and molecule step listing
-
Conditional bond type - Run steps only when predecessors fail
bd mol bond --type conditional-blocksfor error-handling workflows- Step B runs only if step A fails (useful for fallback paths)
-
External dependency display - Show cross-project deps in tree view
bd dep treenow displays external dependencies with repo prefix- Satisfied external deps filtered from blocked issues
-
Performance optimization indexes (bd-bha9, bd-a9y3) - Faster queries for large databases
- Added indexes for common query patterns
- Improved GetReadyWork and SearchIssues performance
Changed
-
Consolidated doctor --fix (GH#715, bd-bqcc) - Single command for all fixes
bd doctor --fixnow handles: hooks, permissions, sync branch, schema- Removed individual
bd migrate,bd hooks installsuggestions - Daemon health check integrated into doctor flow
-
Auto_pull config (GH#707) - Periodic remote sync in event-driven mode
bd config set daemon.auto_pull trueenables pull every 5 minutes- Prevents staleness when git changes happen outside daemon's watch
Fixed
-
Rich mutation events for status changes - Events now include full context
- Status transitions emit complete before/after state
- Enables better monitoring and auditing
-
External deps filtered from GetBlockedIssues - Correct blocking calculation
- External dependencies no longer incorrectly block local work
- Only local blocking deps affect ready queue
-
Parallel execution migration race (GH#720) - Multiple daemons no longer corrupt DB
- Added file-based migration lock to prevent concurrent schema changes
- Retry logic when migration lock is held by another process
-
bd create -f with daemon (GH#719) - File flag now works in daemon mode
-f/--fileflag properly forwarded through RPC
-
FindJSONLInDir interactions.jsonl (GH#709) - No longer picks wrong file
- Skip
interactions.jsonlwhen discovering JSONL files
- Skip
-
Daemon duplicate log messages (PR#713) - Reduced log spam
-
Worktree health check redundancy (PR#711) - Integrated into CreateBeadsWorktree
-
Diverged sync branch handling (GH#697) - Auto-recovery on push failure
-
Tombstones in JSONL export (GH#696) - Deletions now propagate correctly
Refactored
- Remove legacy autoflush code paths
- Consolidate duplicate path-finding utilities
- Replace map[string]interface{} with typed JSON structs
- Migrate sort.Slice to slices.SortFunc
- Add testEnv helpers, reduce SQLite test file sizes
[0.34.0] - 2025-12-22
Added
-
Wisp commands - Full ephemeral molecule management
bd wisp create <proto>- Instantiate proto as ephemeral wisp (solid→vapor)bd wisp list- List all wisps with stale detectionbd wisp gc- Garbage collect orphaned wisps- Wisps have Wisp=true flag and are not exported to JSONL (never sync)
-
Chemistry UX commands - Phase-aware molecule operations
bd pour <proto>- Instantiate proto as persistent mol (solid→liquid)bd mol bond --wisp- Force spawn as vapor when attaching to molbd mol bond --pour- Force spawn as liquid when attaching to wisp- Squash clears Wisp flag, promoting to persistent (exported to JSONL)
-
Cross-project dependencies (bd-66w1, bd-om4a) - Reference issues across repos
external:<repo>:<id>dependency syntaxbd ship <id> --to <repo>- Ship issues to other beads reposbd readyfilters by external dependency satisfaction- Configure additional repos in
.beads/config.yaml
-
Orphan detection in bd doctor - Find issues with missing parents
- Detects parent-child relationships pointing to deleted issues
- Suggests fix commands for orphaned issues
Changed
- Multi-repo config uses YAML (GH#683) -
bd repo add/removenow writes to.beads/config.yaml- Fixes disconnect where CLI wrote to DB but hydration read from YAML
bd repo removenow cleans up hydrated issues from removed repo- Breaking:
bd repo addno longer accepts optional alias argument
Fixed
- Wisp flag handling - Wisps now use Wisp=true flag in main database (not exported to JSONL)
- Prefix validation in multi-repo mode (GH#686) - Skip validation for external repos
- Empty config values (GH#680, GH#684) - Handle gracefully in getRepoConfig()
- Doctor UX improvements (GH#687) - Better diagnostics and daemon integration
- Orphaned test file - Removed repo_test.go with undefined functions
[0.33.2] - 2025-12-21
[0.33.1] - 2025-12-21
Changed
- Ephemeral → Wisp rename - Aligns with Steam Engine metaphor (wisps = ephemeral vapor)
- JSON field changed from
ephemeraltowisp(breaking change for API consumers) - CLI flag changed from
--ephemeralto--wisponbd cleanup - SQLite column remains
ephemeral(no migration needed)
- JSON field changed from
Fixed
- Lint error in mail.go - Added nosec directive for mail delegate exec.Command
[0.33.0] - 2025-12-21
Added
- Wisp molecules - Support for ephemeral wisps
bd wisp createcreates wisp issues that live only in SQLite- Wisp issues never export to JSONL (prevents zombie resurrection)
- Use
bd pourfor persistent mols,bd wisp createfor ephemeral wisps bd mol squashcompresses wisp children into a digest issue--summaryflag allows agents to provide AI-generated summaries
Fixed
- Comments not deleted with issue -
DeleteIssuenow cascades to comments table
[0.32.1] - 2025-12-21
Added
-
MCP output control parameters (PR#667) - Reduce context window usage by up to 97%
brief- Return minimal responses:BriefIssuefor reads,OperationResultfor writesbrief_deps- Full issue with compact dependenciesfields- Custom field projection with validationmax_description_length- Truncate long descriptions- New models:
BriefIssue,BriefDep,OperationResult - Default
brief=Truefor writes (minimal confirmations)
-
MCP filtering parameters - Align MCP tools with CLI capabilities
labels/labels_any- AND/OR label filteringquery- Title search (case-insensitive)unassigned- Filter to unassigned issuessort_policy- Sort ready work by hybrid/priority/oldest
Fixed
- Pin field not in allowed update fields
bd update --pinnedwas failing with "invalid field" error- Added
pinnedto allowedUpdateFields and importer
[0.32.0] - 2025-12-20
Changed
- Removed
bd mailcommands - Mail is orchestration, not data plane- Removed:
bd mail send,bd mail inbox,bd mail read,bd mail ack,bd mail reply - The underlying data model is unchanged:
type=message,Sender,Ephemeral,replies_tofields remain - Orchestration tools should implement mail interfaces on top of the beads data model
- This follows the principle that beads is a data store, not a workflow engine
- Removed:
Fixed
-
Symlink preservation in atomicWriteFile (PR#665) - Thanks @qmx
bd setup claudeno longer clobbers nix/home-manager managed~/.claude/settings.json- New
ResolveForWrite()helper writes to symlink target instead of replacing symlink
-
Broken link in examples (GH#666) - Fixed LABELS.md link in multiple-personas example
[0.31.0] - 2025-12-20
Added
-
bd defer/bd undefercommands - New "deferred" status for icebox issues- Issues that are deliberately postponed, not blocked by dependencies
- Deferred issues excluded from
bd readyand shown with ❄️ snowflake styling - Full support in MCP server, graph views, and statistics
-
Agent audit trail (GH#649) - Append-only logging for AI agent interactions
- New
.beads/interactions.jsonlaudit file bd audit record- Log LLM calls, tool calls, or pipe JSON via stdinbd audit label <id>- Append quality labels (good/bad) for dataset curationbd compact --audit- Optionally log compaction prompts/responses- Audit entries are immutable; labels create new referencing entries
- New
-
Directory-aware label scoping (GH#541) - Auto-filter issues by directory in monorepos
- Configure
directory.labelsto map paths to label filters bd readyandbd listauto-apply when in matching directories- Example:
packages/maverick: maverickshows only maverick-labeled issues
- Configure
-
Molecules catalog - Separate storage for template molecules
- Templates now live in
molecules.jsonl, distinct from work items - Hierarchical loading: built-in → town → user → project
- Molecules use
mol-*ID namespace withis_template: true
- Templates now live in
-
Windows winget manifest (GH#524) - Prepare beads for Windows Package Manager
- Added manifest files for winget submission
- Once merged to microsoft/winget-pkgs:
winget install SteveYegge.beads
-
Git commit configuration (GH#600) - Control beads auto-commit behavior
git.author- Override commit author (useful for bots)git.no-gpg-sign- Disable GPG signing (fixes Touch ID prompts)
-
Require description config (GH#596) - Enforce descriptions on issue creation
- Set
create.require-description: trueto error on missing descriptions - Also supports
BD_CREATE_REQUIRE_DESCRIPTIONenv var
- Set
Changed
-
bd statsmerged intobd status(GH#644) - Consolidated status commandsstatsnow an alias forstatus- Colorized output with emoji header
- Shows all statistics (tombstones, pinned, epics, lead time)
- Added
--no-activityflag to skip git activity parsing
-
Thin hook shims (GH#615) - Hooks now delegate to
bd hooks run- Eliminates hook version drift after upgrades
- No more manual
bd hooks install --forceneeded - Shims use
# bd-shim v1marker (format version, not bd version)
-
MCP context tool consolidation - Merged 3 tools into 1
- Combined
set_context,where_am_i,initinto singlecontexttool - Actions:
set(default with workspace_root),show(default),init
- Combined
-
Doctor improvements (GH#656) - Enhanced diagnostics and testing
- Visual improvements with grouped output
- Comprehensive test coverage added
- Fixed gosec warnings
- Contributed by @rsnodgrass
Fixed
-
relates-tocycle detection (GH#661) - Exclude relates-to from cycle detection- Relates-to links are bidirectional by design, not cycles
-
Doctor
.local_versioncheck (GH#662) - Check correct version file- Now checks
.local_versioninstead of deprecatedLastBdVersion
- Now checks
-
Doctor Claude plugin link (GH#623) - Updated broken documentation link
-
Read-only gitignore in stealth mode (GH#663) - Print manual instructions instead of failing
- When global gitignore is read-only (e.g., symlink to immutable location), shows what to add manually
- Contributed by @qmx
[0.30.7] - 2025-12-19
Fixed
-
bd graphnil pointer crash (#657) - Fixed crash when runningbd graphon epicsrenderGraph()was passednilinstead of the subgraph, causing panic incomputeDependencyCounts()
-
Windows npm installer file lock (#652) - Fixed installation failure on Windows
- The download file handle wasn't fully closed before extraction attempted
- Now properly waits for
file.close()callback before proceeding
[0.30.6] - 2025-12-18
Added
bd graphdependency counts - Graph command shows dependency counts using subgraph formattingtypes.StatusPinned- New status for persistent beads that survive cleanup
Fixed
- CRITICAL: Dependency resurrection bug - Fixed 3-way merge to respect dependency removals
mergeDependencieswas using union (additive-only) instead of proper 3-way merge- Now removals are authoritative: if either left or right removes a dep, it stays removed
- This prevented orphaned parent-child relationships from being permanently removed
[0.30.5] - 2025-12-18
Removed
- YAML simple template system - Removed
--from-templateflag frombd create- Deleted embedded templates:
bug.yaml,epic.yaml,feature.yaml - Templates are now purely Beads-based (epics with
templatelabel) - Use
bd template instantiate <id>for template workflows
- Deleted embedded templates:
[0.30.4] - 2025-12-18
Added
bd template instantiate- Create beads issues from YAML workflow templatesbd template instantiate <file.yaml>- Create issues from workflow definitions--assignee <identity>flag for auto-assignment during instantiation- Supports multi-issue workflows with dependency chains
- Templates define issue properties (title, type, priority, dependencies)
Changed
bd mail inbox --identity- Fixed to properly filter by identity parameter
Fixed
- Orphan detection warnings - No longer warns about closed issues or tombstones
- Previously
bd doctorreported false positives for completed dependencies
- Previously
Removed
- Legacy MCP Agent Mail integration - Removed obsolete
mcp_agentspackage - YAML workflow execution system - Replaced by simpler template instantiation
Notes
- Experimental edges: The new graph link fields (
relates_to,replies_to,duplicate_of,superseded_by) and mail commands are experimental and subject to change in upcoming releases. Early adopters should expect breaking changes to these APIs.
[0.30.3] - 2025-12-17
Fixed
- Data loss race condition - Removed unsafe
ClearDirtyIssues()method- Old method cleared ALL dirty issues, risking data loss if export failed partway
- All code now uses
ClearDirtyIssuesByID()which only clears exported issues - Affects:
internal/storage/sqlite/dirty.go,internal/storage/memory/memory.go
Closed (Already Implemented)
- Stale database warning - Commands now warn when database is out of sync with JSONL
- Staleness check error handling (bd-n4td, bd-o4qy) - Proper warnings and error returns
[0.30.2] - 2025-12-16
Added
-
bd setup droid(GH#598) - Factory.ai (Droid) IDE support- Configure beads for use with Factory.ai's Droid
- Contributed by @jordanhubbard
-
Messaging schema fields - Foundation for inter-agent messaging
- New
messageissue type for agent-to-agent communication - New fields:
sender,wisp,replies_to,relates_to,duplicate_of,superseded_by - New dependency types:
replies-to,relates-to,duplicates,supersedes - Schema migration 019 (automatic on first use)
- New
-
bd mailcommands - Inter-agent messagingbd mail send <recipient> -s <subject> -m <body>- Send messagesbd mail inbox- List open messages for your identitybd mail read <id>- Display message contentbd mail ack <id>- Acknowledge (close) messagesbd mail reply <id> -m <body>- Reply to messages (creates threads)- Identity via
BEADS_IDENTITYenv var or.beads/config.json
-
Graph link commands - Knowledge graph relationships
bd relate <id1> <id2>- Create bidirectional "see also" linksbd unrelate <id1> <id2>- Remove relates_to linksbd duplicate <id> --of <canonical>- Mark issue as duplicate (closes it)bd supersede <old> --with <new>- Mark issue as superseded (closes it)bd show --thread- View message threads via replies_to chain
-
Hooks system - Extensible event notifications
.beads/hooks/on_create- Runs after issue creation.beads/hooks/on_update- Runs after issue update.beads/hooks/on_close- Runs after issue close.beads/hooks/on_message- Runs after message send- Hooks receive issue ID, event type as args, full JSON on stdin
-
bd cleanup --wispflag - Clean up transient messages- Deletes only closed issues with
wisp=true - Useful for cleaning up messages after swarms complete
- Deletes only closed issues with
Fixed
-
Windows build errors (GH#585) - Fixed gosec lint warnings
- Contributed by @deblasis
-
Issue ID prefix extraction - Word-like suffixes (e.g.,
my-project-audit) now parse correctly- Previously could incorrectly split on word boundaries
Removed
- Legacy deletions.jsonl code - Fully migrated to inline tombstones
- Removed
deletions.jsonlfrom git tracking - All deletion tracking now via inline tombstones in
issues.jsonl
- Removed
Documentation
-
Messaging documentation - New docs for messaging system
docs/messaging.md- Full messaging reference with examplesdocs/graph-links.md- Graph link types and use cases- Updated
AGENTS.mdwith inter-agent messaging section
-
Windows installation command in upgrade instructions (GH#589)
- Contributed by @alexx-ftw
-
Aligned
bd primeguidance with skill's hybrid TodoWrite approach
[0.30.1] - 2025-12-16
Added
-
bd resetcommand (GH#505) - Complete beads removal from a repository- Removes
.beads/directory and all associated data - Cleans up git hooks installed by beads
- Use
--forceto skip confirmation prompt
- Removes
-
bd cleanup --hardflag - Bypass tombstone TTL safety- Immediately removes tombstones regardless of age
- Use when you need to force-clean deleted issues
-
bd update --typeflag (GH#522) - Change issue type after creation- Convert between task, bug, feature, epic types
- Example:
bd update bd-xyz --type epic
-
bd qsilent quick-capture mode (GH#540)- Capture issues silently without output
- Ideal for scripting and automation
-
bd sync --checkflag - Pre-sync integrity checks- Validates database state before syncing
- Catches potential issues early
-
bd showdisplays dependent issue status (#583)- Shows status for all blocked-by and blocking issues
- Better visibility into dependency chains
-
bd daemon --statusshows config (#569)- Displays daemon configuration in status output
- Contributed by @crcatala
-
bd daemon --stop-all- Kill all daemon processes- Useful for cleanup when multiple daemons are running
-
Auto-disable daemon in git worktrees (#567)
- Daemon automatically disabled in worktrees for safety
- Prevents database conflicts between worktrees
-
claude.local.mdsupport - Local-only documentation- Add project notes that won't be committed
- Gitignored by default
-
Auto-add session completion instructions to AGENTS.md
- New projects get session-close protocol guidance
-
Inline tombstones for soft-delete
- Deleted issues become tombstones with
status: "tombstone"inissues.jsonl - Full audit trail:
deleted_at,deleted_by,delete_reason,original_type - TTL-based expiration (default 30 days) with automatic pruning via
bd compact - Proper 3-way merge support: fresh tombstones win, expired tombstones allow resurrection
- Deleted issues become tombstones with
-
bd migrate-tombstonescommand- Converts legacy
deletions.jsonlentries to inline tombstones - Archives old file as
deletions.jsonl.migrated
- Converts legacy
-
Enhanced Git Worktree Support
- Shared
.beadsdatabase across all worktrees - Worktree-aware database discovery
- Git hooks automatically adapt to worktree context
- Documentation in
docs/WORKTREES.md
- Shared
Fixed
- Multi-hyphen prefix parsing (GH#405) - Prefixes like
my-cool-projectnow work correctly bd syncon sync branch (GH#519) - Fixed sync when already on the sync branch- Pre-commit hook with removed
.beads(GH#483) - No longer blocks commits after beads removal - Priority format error messages (GH#517) - Clearer guidance on P0-P4 format
- Status naming consistency (GH#444) - Uses
in_progresseverywhere - Orphan detection with dots in directory names (GH#508) - No more false positives
- Circular error in pre-push hook (GH#532) - Fixed infinite loop scenario
- Doctor --fix auto-migrates tombstones - Automatic migration during repair
- Daemon detects external DB replacement (#564) - Contributed by @deblasis
- Import handles hierarchical hash IDs (#584) - Contributed by @rsnodgrass
- Nested worktree detection (GH#509) - Correctly finds
.beads/in parent repo - Import skips cross-prefix content matches - Prevents incorrect renames
- 3-way merge tolerates missing issues - More robust conflict resolution
- Pre-commit warns instead of failing on flush error - Graceful degradation
Security
- Go toolchain updated to 1.24.11 - Addresses CVEs in standard library
CI
- PR check for
.beads/issues.jsonlchanges - Rejects accidental database commits
Dependencies
- Bump
github.com/ncruces/go-sqlite3to 0.30.3 - Bump
github.com/spf13/cobrato 1.10.2 - Bump
golang.org/x/modto 0.31.0 - Bump
golang.org/x/termto 0.38.0 - Bump
pydanticto 2.12.5 (beads-mcp) - Bump
fastmcpto 2.14.1 (beads-mcp)
[0.29.0] - 2025-12-03
Added
-
--estimate/-eflag forbd createandbd update(GH #443)- Add time estimates to issues in minutes
- Example:
bd create "My task" --estimate 120(2 hours) - Example:
bd update bd-xyz --estimate 60(1 hour) - Enables planning and prioritization features in vscode-beads
-
bd doctorimprovements- SQLite integrity check - Detects database corruption
- Configuration value validation - Validates config settings
- Stale sync branch detection - Warns about abandoned beads-sync branches
--outputflag - Export diagnostics to file for sharing--dry-runflag - Preview fixes without applying- Per-fix confirmation mode - Approve each fix individually
-
--readonlyflag - Read-only mode for worker sandboxes- Blocks all write operations
- Useful for parallel worker processes that should only read
Fixed
-
bd syncsafety improvements- Auto-push after merge with safety check
- Handle diverged histories with content-based merge
- Multiple safety check enhancements
-
Auto-resolve merge conflicts deterministically
- All field conflicts resolved without prompts
- Uses consistent rules for field-level merging
-
3-char all-letter base36 hash support (GH #446)
- Fixes prefix extraction for edge case hashes like "bd-abc"
-
bd readymessage fix- Shows correct message when all issues are closed
-
Version notification spam fix
- Store version in gitignored .local_version file
-
Nix flake vendorHash update
- Fixed build after dependency bumps
Documentation
- Added perles and vscode-beads to Third-Party Tools
- Encourage batch close and parallel creation in
bd primeoutput
[0.28.0] - 2025-12-01
Added
-
bd daemon --localflag (#433) - Run daemon without git operations- Ideal for multi-repo setups where git sync happens externally
- Prevents daemon from triggering git commits/pushes
- Use with worktrees or when beads sync is handled by another process
-
bd daemon --foregroundflag - Run daemon in foreground mode- For systemd/supervisord/launchd integration
- Logs to stdout instead of background file
- Process stays attached to terminal
-
bd migrate-synccommand - Migrate to sync.branch workflow- Moves beads data to a dedicated sync branch
- Keeps main branch clean of .beads/ commits
- Automated setup of sync.branch configuration
Fixed
-
Database Migration: close_reason column
- Added missing database column for close_reason field
- Fixes sync loops where close_reason was lost on import/export
- Automatic migration on first run
-
Multi-repo Prefix Filtering (GH #437)
- Issues now filtered by prefix when flushing from non-primary repos
- Prevents issues from other projects appearing in exports
-
Parent-Child Dependency UX (GH #440)
- Fixed backwards documentation in DEPENDENCIES.md
bd shownow displays epic children under "Children" not "Blocks"- Clearer UI labels for dependency relationships
-
sync.branch Workflow Fixes
- Fixed .beads/ restoration from branch after sync
- Prevents final flush after sync.branch restore
bd doctornow detects when on sync branch
-
Jira API Migration
- Updated from deprecated Jira API v2 to v3
- Fixes authentication issues with newer Jira instances
-
Redundant Database Queries
- Removed extra GetCloseReason() calls after column migration
- Improves query performance for issue retrieval
Documentation
- Added go install fallback instructions for Claude Code web (GH #439)
- Added uninstall documentation (GH #445)
Internal
- Refactored daemon sync functions to reduce ~200 lines of duplication
- Consolidated local-only sync functions into shared implementation
[0.27.2] - 2025-11-30
Fixed
-
CRITICAL: Prevent Mass Database Deletion on JSONL Reset
- git-history-backfill now includes safety guard to prevent purging entire database
- If >50% of issues would be deleted via git history, operation is aborted with warning
- Threshold prevents accidental deletion when JSONL is reset (git reset, branch switch, etc.)
- If 10-50% would be deleted, operation proceeds but shows warning message
- Fixes bug where
git reset --hard origin/mainwould lose all issues
-
Fix Fresh Clone Initialization
bd initnow works on fresh clones that have JSONL but no database- Auto-detects issue prefix from existing JSONL (no
--prefixflag needed) - Prevents "database not found" errors on first run in a cloned repository
-
Import Warning for Deleted Issues
- New warning message when issues are skipped due to deletions manifest
- Helps users understand why expected issues aren't being imported
- Warns user to check
bd deletedfor history of removed issues
-
Extract Issue Prefix for 3-char Hashes (#425)
ExtractIssuePrefix()now handles base36 hashes as short as 3 characters- Previously required 4+ chars, breaking hyphenated prefixes (e.g.,
document-intelligence-0sa) - Updated hash validation to accept base36 (0-9, a-z) instead of just hex
- Requires at least one digit to distinguish hashes from English words
[0.27.0] - 2025-11-29
Added
-
Custom Status States: Define custom issue statuses via config
- Configure project-specific statuses like
testing,blocked,review - Status validation ensures only configured statuses are used
- Backwards compatible: open/in_progress/closed always work
- Configure project-specific statuses like
-
Contributor Fork Workflows:
bd init --contributornow auto-configuressync.remote=upstream- Syncs issues from upstream rather than origin
- Ideal for contributors working on forks
-
Git Worktree Support: Full support for git worktrees (#416)
bd hooks installnow works correctly in worktrees- Helpful message when entering worktree repo without beads initialized
- Hooks properly detect worktree vs main repository
-
Daemon Health Checks: Health monitoring in daemon event loop
- Periodic health checks detect stale database state
- Auto-recovery from detected inconsistencies
-
Fresh Clone Detection:
bd doctornow detects fresh clones- Suggests
bd initwhen JSONL exists but no database - Improved onboarding experience for new contributors
- Suggests
-
bd sync --squash: Batch multiple sync commits into one
- Reduces commit noise when syncing frequently
- Optional flag for cleaner git history
-
Error Handling Helpers: Extracted FatalError/WarnError utilities
- Consistent error formatting across codebase
- Better error messages for users
Fixed
-
CRITICAL: Sync Corruption Prevention: Multiple fixes prevent stale database from corrupting JSONL
- Hash-based staleness detection: SHA256 hash comparison catches content mismatches
- Reverse ZFC check: Detects when JSONL has more issues than DB
- Stale daemon connection (
eb4b81d): Prevents corruption from stale SQLite connections - Combined, these fixes eliminate the sync corruption bugs that affected v0.26.x
-
Multi-Hyphen Prefix Support (#419): Hash IDs with multi-part prefixes now handled correctly
- Example:
my-app-abc123correctly parsed as prefixmy-app
- Example:
-
Out-of-Order Dependencies (#414): JSONL import handles dependencies before their targets exist
- Fixes import failures when issues reference not-yet-imported dependencies
-
--from-main Sync Mode (#418): Now defaults to
noGitHistory=true- Prevents spurious deletions when syncing from main branch
-
JSONL-Only Mode Detection: Auto-detects when config has
no-db: true- Properly handles repositories using JSONL without SQLite
-
Init Safety Guard: Prevents overwriting existing JSONL data on init
- Warns user when data already exists, requires confirmation
-
Snapshot Cleanup: Properly cleans up snapshot files after sync
- Removes
.beads/*.snapshotfiles that could cause conflicts
- Removes
-
Daemon Registry Locking: Cross-process locking prevents registry corruption
- Fixes race conditions when multiple processes access daemon registry
-
Doctor Merge Artifacts: Excludes merge artifacts from "multiple JSONL" warning
- Reduces false positives during merge resolution
Changed
- Documentation: Fixed birthday paradox threshold explanation in README
- Documentation: Corrected
bd dep addsyntax and semantics
Community
- PR #419: Multi-hyphen prefix support
- PR #418: --from-main noGitHistory default
- PR #416: Git worktree hooks support
- PR #415: CI fixes
- PR #414: Out-of-order dependency handling
- PR #404: Error on invalid JSON during init (@joelklabo)
[0.26.2] - 2025-11-29
Fixed
- Hash-Based Staleness Detection: Prevents stale DB from corrupting JSONL when counts match
- Previous count-based check (0.26.1) missed cases where DB and JSONL had similar issue counts
- New detection computes SHA256 hash of JSONL content and stores it after import
- On export, compares current JSONL hash against stored hash to detect modifications
- If JSONL was modified externally (e.g., by git pull), triggers re-import before export
- Ensures database is always synchronized with JSONL before exporting changes
[0.26.1] - 2025-11-29
Fixed
- CRITICAL: Reverse ZFC Check: Prevents stale database from corrupting JSONL
- Root cause:
bd syncexports DB to JSONL before pulling from remote - If local DB is stale (fewer issues than JSONL), stale data would corrupt the JSONL
- Added reverse ZFC check: detects when JSONL has >20% more issues than DB
- When detected, imports JSONL first to sync database before any export
- Prevents fresh/stale clones from exporting incomplete database state
- Root cause:
[0.26.0] - 2025-11-27
Added
-
bd doctor --check-health: Lightweight health checks for startup hooks (
3fe94f2)- Quick, silent health checks (exit 0 on success, non-zero on issues)
- Checks: version mismatch, sync.branch config, outdated hooks
- New
hints.doctorconfig option to suppress doctor hints globally - Git hooks now call
bd doctor --check-healthin post-merge/post-checkout
-
--no-git-history Flag: Prevent spurious deletions during import/sync (
5506486)- Use when git history is unreliable (shallow clones, squash merges)
- Prevents deletion manifest from removing issues based on stale history
-
gh2jsonl Hash ID Mode: Content-based ID generation for GitHub imports (#383 by @deangiberson)
--id-mode {sequential|hash}flag (default: sequential for backward compatibility)--hash-length {3,4,5,6,7,8}for configurable hash length (default: 6)- Hash IDs are deterministic using title, description, creator, timestamp
-
CI Provenance Attestation: npm publish now includes provenance attestation (
03d62d0) -
bdui: Added to Third-Party Tools ecosystem (#384)
Fixed
-
Critical: MCP Protocol Stdin Fix (PR #400 by @cleak)
- Subprocess stdin inheritance was breaking MCP JSON-RPC protocol
- All subprocess calls now use
stdin=subprocess.DEVNULL - Fixes hanging/blocking issues in Claude Desktop MCP integration
-
Git Worktree Staleness (#399)
- Staleness check was failing after writes in git worktrees
- Now uses RFC3339Nano precision for
last_import_timemetadata
-
Multi-Part Prefix Support (#398)
- Issue ID extraction now correctly handles multi-part prefixes
- Example:
my-app-123correctly extracts prefixmy-app
-
bd sync Commit Scope
bd syncnow only commits.beads/files, not other staged files- Prevents accidental commits of unrelated staged changes
-
Auto-Import to Wrong File
- Fixed auto-import exporting to wrong JSONL file
- FindJSONLPath now correctly skips deletions.jsonl
-
Deletions.jsonl Handling
- Git hooks now properly stage deletions.jsonl for cross-clone propagation
- bd doctor no longer warns about deletions.jsonl
- Prevent rebase failures from deletions.jsonl writes
-
Defense-in-Depth
- Added additional check for --no-auto-import flag
-
Tilde Expansion: Global gitignore path now expands
~correctly -
beads-mcp Type Checking: Resolved all mypy type checking errors
-
CI Test Stability: Fixed Windows test failures
Changed
-
Stealth Mode: Removed global gitattributes setup from
bd init --stealth(#391)- Stealth mode now purely local with no global git configuration
-
Pre-Push Hook Error Message: Improved clarity when sync fails (#390)
Refactoring
- Extract path canonicalization and database search helpers (
7d765c2) - Consolidate check-health DB access and expand hook checks (
3458956)
Documentation
- Sync skill CLI reference with current docs (
62d1dc9)
Community
- PR #400: MCP stdin fix (@cleak)
- PR #398: Multi-part prefix support
- PR #391: Stealth mode gitattributes removal
- PR #390: Pre-push hook error message (@jonathanpberger)
- PR #384: bdui ecosystem addition
- PR #383: gh2jsonl hash ID support (@deangiberson)
[0.25.1] - 2025-11-25
Added
- Zombie Resurrection Prevention: Stale clones can no longer resurrect deleted issues
- New JSONL sanitization step (3.6) after git pull removes deleted issues before import
- Prevents git's 3-way merge from re-adding issues that were deleted elsewhere
- New
bd doctorcheck 18: "Deletions Manifest" detects missing/empty manifest - New
bd doctor --fixhydrates deletions.jsonl from git history for pre-v0.25.0 deletions - ID validation prevents false positives from non-issue JSON fields
Fixed
- bd sync commit scope: Now commits entire
.beads/directory before pull- Previously only committed beads.jsonl, leaving metadata.json unstaged
- Fixes "You have unstaged changes" error during
git pull --rebase
[0.25.0] - 2025-11-25
Added
-
Deletion Propagation: Deletions now sync across clones via deletions manifest
- New
.beads/deletions.jsonltracks deleted issues with timestamp, actor, reason - Import automatically purges issues that were deleted in other clones
- Git history fallback for pruned deletion records (self-healing)
- New
bd deletedcommand to view deletion audit trail - Auto-compact during sync (opt-in via
deletions.auto_compact: true) - Configurable retention period (
deletions.retention_days, default 7) - Local unpushed work protected from accidental deletion
- Full documentation in docs/DELETIONS.md
- New
-
Stealth Mode: New
bd init --stealthflag for invisible beads usage (#381)- Adds
.beads/to project's.gitignoreautomatically - Useful for personal issue tracking in shared repos without affecting collaborators
- All bd functionality works normally, just not committed to git
- Adds
-
Ephemeral Branch Sync: New
bd sync --from-mainflag- Syncs from main branch without pushing to remote
- Ideal for feature branches that sync issues from main
- Prevents pushing local branch changes to origin
[0.24.4] - 2025-11-25
Added
-
Transaction API: Full transactional support for atomic multi-operation workflows
- New
storage.Transactioninterface with CreateIssue, UpdateIssue, CloseIssue, DeleteIssue - Dependency operations: AddDependency, RemoveDependency within transactions
- Label operations: AddLabel, RemoveLabel with transactional semantics
- Config/Metadata operations for atomic config+issue workflows
- Uses
BEGIN IMMEDIATEmode to prevent deadlocks - Automatic rollback on error or panic, commit on success
- 1,147 lines of new implementation with comprehensive tests
- New
-
Tip System Infrastructure: Smart contextual hints for users
- Tips shown after successful commands (list, ready, create, show)
- Condition-based filtering, priority ordering, probability rolls
- Frequency limits prevent tip spam
- Respects
--jsonand--quietflags - Deterministic testing via
BEADS_TIP_SEEDenv var
-
Sorting for bd list and bd search: New
--sortand--reverseflags- Sort by: priority, created, updated, closed, status, id, title, type, assignee
- Smart defaults: priority ascending (P0 first), dates descending (newest first)
- Works with all existing filters
-
Claude Integration Verification: New bd doctor checks
CheckBdInPath: verifies 'bd' is in PATH (needed for hooks)CheckDocumentationBdPrimeReference: detects version mismatches in docs
-
ARM Linux Support: GoReleaser now builds for linux/arm64 (PR #371 by @tjg184)
- Enables bd on ARM-based Linux systems like Raspberry Pi, AWS Graviton
-
Orphan Detection Migration: Identifies orphaned child issues
- Detects issues with hierarchical IDs where parent no longer exists
- Logs suggestions: delete, convert to standalone, or restore parent
- Idempotent and safe to run multiple times
Fixed
-
Transaction Cache Invalidation: blocked_issues_cache now invalidates correctly
- UpdateIssue status changes trigger cache invalidation
- CloseIssue always invalidates (closed issues don't block)
- AddDependency/RemoveDependency invalidate for blocking types
-
SQLITE_BUSY Retry Logic: Exponential backoff for concurrent writes
beginImmediateWithRetry()with 5 retries (10ms, 20ms, 40ms, 80ms, 160ms)- Eliminates spurious failures under normal concurrent usage
- Context cancellation respected between retry attempts
-
bd import Argument Validation: Helpful error for common mistake
- Running
bd import file.jsonl(without-i) now shows clear error - Previously silently read from stdin, confusing users with "0 created"
- Running
-
ZFC Import Export Skip: Preserve JSONL source of truth
- After stale DB import from JSONL, skip export to avoid overwriting
- Fixes scenario where DB with fewer issues would overwrite JSONL
-
Daemon Reopen with Reason:
--reasonflag now works in daemon mode- Previously ignored in daemon RPC calls
-
Windows Test Failures: Skip file permission tests on Windows
- Windows doesn't support Unix-style permissions (0600, 0755)
- Core functionality still tested, only permission checks skipped
Changed
- bd daemon UX: New
--startflag, help text when no argsbd daemonnow shows help instead of immediately starting- Use
bd daemon --startto explicitly start - Auto-start still works (uses
--startinternally) - More discoverable for new users
Documentation
- blocked_issues_cache Architecture: Document cache behavior and invalidation
- Antivirus False Positives: Guide for handling security software alerts
- import.orphan_handling: Complete documentation
- Error Handling Patterns: Comprehensive audit and guidelines
Dependencies
- Bump github.com/tetratelabs/wazero from 1.10.0 to 1.10.1 (#374)
- Bump github.com/anthropics/anthropic-sdk-go from 1.18.0 to 1.18.1 (#373)
- Bump actions/checkout from 4 to 6 (#372)
Community
- PR #371: ARM Linux support (@tjg184)
[0.24.3] - 2025-11-24
Added
-
BD_GUIDE.md Generation: Version-stamped documentation for AI agents (bd-woro,
9e16469)- New
--outputflag forbd onboardcommand generates BD_GUIDE.md - Separates bd-specific instructions from project-specific instructions
- Auto-generated header with version stamp warns against manual editing
- Detects outdated BD_GUIDE.md and suggests regeneration after upgrades
- Git-trackable diffs show exactly what changed between versions
- New
-
Configurable Export Error Policies: Flexible error handling for export operations (bd-exug,
e3e0a04)- Four policies: strict (fail-fast), best-effort (skip with warnings), partial (retry then skip), required-core (fail on core data only)
- Per-project configuration via
bd config set export.error_policy - Separate policy for auto-exports via
auto_export.error_policy - Retry with exponential backoff for transient failures
- Optional export manifests documenting completeness
-
Command Set Standardization: Complete flag and feature consistency overhaul (bd-au0,
273a4d1)- Global verbosity flags:
--verbose/-vand--quiet/-qacross all commands - Standardized
--dry-runflag behavior across all commands - Label operations added to
bd update:--add-labelsand--remove-labels - Enhanced
bd exportwith comprehensive filters (assignee, type, labels, priority, dates) - Enhanced
bd searchwith date and priority filters - Improved documentation for
bd cleanvsbd cleanupdisambiguation
- Global verbosity flags:
-
Auto-Migration on Version Bump: Automatic database schema updates (bd-jgxi,
7796f5c)- Database version automatically synced when bd CLI is upgraded
- Eliminates recurring "version mismatch" warnings in bd doctor
- Best-effort and silent to avoid disrupting commands
-
Version Tracking Validation: Comprehensive bd doctor checks (bd-u4sb,
d8f3eb0)- Validates metadata.json exists with valid LastBdVersion field
- Warns if LastBdVersion is very old (>10 minor versions behind)
- Ensures version tracking system is working correctly
-
Git Hooks Executable Validation: Hook reliability improvements (bd-fwul,
1c715bc)- bd doctor now validates git hooks have executable bit set
- Prevents silent hook failures from incorrect permissions
-
Socket Cleanup Race Condition Fix: Daemon reliability improvement (bd-4owj,
18f8105)- Re-checks socket existence after lock check to avoid stale state
- Handles daemon startup race conditions gracefully
-
Monitor Web UI Enhancements: UX/UI improvements (
aa2df73)- Interactive stats cards as filters
- Multi-select priority filtering with P0 support
- Find-as-you-type search functionality
- Modern card-based UI design with better mobile responsiveness
- Dev mode flag for easier development
-
bump-version.sh Automation: PyPI integration (
0547004)- New
--upgrade-mcpflag for automatic beads-mcp package upgrades - Tries pip first, falls back to uv tool
- Warns about version mismatch before PyPI publish
- New
Fixed
-
JSONL Import Foreign Key Violations: Graceful handling of deletions during merge (bd-koab,
d45cff5)- Import now continues when dependencies reference deleted issues
- Reports skipped dependencies with clear warnings
- Prevents complete import failure from FK constraint violations
- Common scenario: merges that delete issues referenced by other issues
-
Metadata JSONL Path Auto-Detection: Fix configuration mismatches (bd-afd,
d1641c7)- Auto-detects actual JSONL file when metadata.json is recreated
- bd doctor --fix now includes DatabaseConfig() auto-repair
- Prefers beads.jsonl over issues.jsonl (canonical name)
- Prevents mismatches after git clean, merge conflicts, or rebases
-
JSONL Resurrection Bug: Critical fix for deleted issue resurrection (bd-v0y,
c9a2e7a)- Removed mtime fast-path in hasJSONLChanged() causing false negatives
- Git doesn't preserve mtime on checkout, causing incorrect change detection
- Now always uses content hash for reliable comparison
- Prevents bd sync from overwriting pulled JSONL and resurrecting deleted issues
-
ZFC (JSONL First Consistency): Fix stale DB overwriting JSONL on sync (bd-l0r,
1ba068f,2e4171a,949ab42)- bd sync now detects stale DB (>50% divergence from JSONL) and imports first
- After ZFC import, skips export to prevent overwriting JSONL source of truth
- Fixes bug where DB with 688 issues would overwrite JSONL with 62 issues after pull
- JSONL is source of truth after git pull - DB syncs to match, not vice versa
- Preserves local uncommitted changes while catching stale DB scenarios
-
Merge Conflict Semantics: Improved resolution policies (bd-pq5k,
d4f9a05)- Merge logic now enforces: closed ALWAYS wins over open
- Deletion ALWAYS wins over modification
- Fixed closed_at handling: only set when status='closed'
- Prevents issues from getting stuck in invalid states
- Eliminates "zombie issues" that never die
-
JSONL Merge Conflict Auto-Resolution: Streamlined rebase workflow (bd-cwmt,
3cf5e26)- bd sync now auto-resolves JSONL conflicts during rebase
- Detects rebase state and JSONL-only conflicts
- Auto-exports from DB and continues rebase automatically
- Eliminates manual conflict resolution in common scenarios
-
Staleness Check Error Handling: Better metadata validation (bd-2q6d, bd-o4qy, bd-n4td,
b75914b)- CheckStaleness now returns errors for corrupted last_import_time metadata
- Enhanced warning messages when staleness check fails
- Handles empty string metadata (memory store behavior)
- Prevents silent failures with corrupted metadata
-
N+1 Query Pattern in Export: Dramatic performance improvement (bd-rcmg,
9c6b375)- Added batch methods: GetCommentsForIssues() and GetLabels() in bulk
- Reduced query count from ~201 to ~3-5 for 100 issues
- Eliminated per-issue loops in handleExport() and triggerExport()
-
Sync Branch Auto-Configuration: Prevent bd sync failures after init (bd-flil, bd-rsua,
a4c38d5,83609d5)- bd init now auto-sets sync.branch to current git branch
- bd doctor detects missing sync.branch config and provides --fix
- All branch detection uses 'git symbolic-ref' to work in fresh repos
- Fixes 'bd sync --status' error after fresh bd init
-
Merge Driver Auto-Repair: Fix stale git configurations (bd-3sz0, bd-tbz3,
1c8dd49)- Detects old bd versions (<0.24.0) with invalid %L/%R placeholders
- Auto-repairs during bd init and bd doctor --fix
- Git only supports %O (base), %A (current), %B (other) placeholders
- Supports both canonical (issues.jsonl) and legacy (beads.jsonl) filenames
-
Unvalidated Dependency Parsing: Prevent empty ID lookups (bd-ia8r,
e8a752e)- Validates dependsOnID is non-empty before setting discoveredFromParentID
- Ensures parent issue exists before generating child IDs in direct mode
-
Windows CI Test Failures: Cross-platform reliability (
153f724)- Fixed file locking issue in TestNewSQLiteStorage (added defer store.Close())
- Fixed nil slice return in TestFindAllDatabases (explicit empty slice initialization)
- Both issues related to stricter Windows file locking behavior
-
Invalid closed_at States: Data integrity fix (bd-1rh,
b428254)- Removed invalid closed_at timestamps for open issues
- Prevents inconsistent state from merge conflicts
-
Security: File permission hardening (
b6870de,ae5a4ac)- Changed file permissions from 0644 to 0600 for security (gosec G302)
- Config files now owner read/write only (not world readable)
- Added comprehensive security tests for WriteFile permissions
- Handles read-only files by fixing permissions before writing
Changed
-
bd init Defaults: Better out-of-box experience (bd-bxha,
ec4117d)- Git hooks and merge driver now installed by default
- Removed interactive prompts (simpler workflow)
- New opt-out flags:
--skip-hooksand--skip-merge-driver - Shows warning messages on failure with suggestion to run bd doctor --fix
-
bd init Validation: Automatic setup verification (bd-zwtq,
3a36d0b)- Runs bd doctor diagnostics at end of bd init
- Immediately identifies configuration problems before user encounters them
- Catches: missing hooks, unconfigured merge driver, missing docs, metadata issues
-
Internal Code Organization: Improved maintainability (bd-0a43,
58f37d0)- Split monolithic sqlite.go (1050 lines) into focused files
- store.go: Database initialization and utilities
- queries.go: Issue CRUD operations
- config.go: Configuration and metadata
- comments.go: Comment operations
- Zero functional changes, all tests pass
-
Documentation: Organization improvements (
a930fa3,62b5f53)- Moved event-driven daemon details to docs/DAEMON.md
- Added comprehensive error handling guidelines
- Reduced duplication in AGENTS.md
Testing
-
Blocked Issues Cache Validation: Comprehensive cache tests (bd-13gm,
0e6ed91)- 8 tests verify cache invalidation behavior
- Tests for dependency add/remove, status changes, transitive blocking
- Direct cache table queries validate implementation correctness
-
Sync Test Optimization: Reduced boilerplate (bd-ktng,
dfcbb7d)- Added shared git repo setup helpers
- Refactored 19 test functions
- Reduced duplicate code by ~300 lines
Performance
- Daemon Log Rotation: Production-ready configuration (bd-t7ds,
f454b3d)- Max size increased: 10MB → 50MB per file
- Max backups increased: 3 → 7 files
- Max age increased: 7 → 30 days
- Better handles long-running daemons with high log output
[0.24.2] - 2025-11-22
Fixed
-
Test Stability: Complete rootCtx initialization fix for all hanging tests (issue #355,
b8db5ab)- Fixed TestGetAssignedStatus missing rootCtx initialization (
a517ec9) - Prevents test hangs from uninitialized context
- Improved test reliability and isolation
- Fixed TestGetAssignedStatus missing rootCtx initialization (
-
JSONL Configuration: Improved bd doctor JSONL checks to focus on real problems (
87ee3a6)- Reduces false positives in JSONL validation
- Better detection of actual configuration issues
Changed
- JSONL Filename Default: Changed default JSONL filename from
beads.jsonltoissues.jsonl(c4c5c80)
[0.24.1] - 2025-11-22
Added
-
bd search: Date and priority filters (
787fb4e)--created-after,--created-beforefor date filtering--priority-min,--priority-maxfor priority range filtering- Enables more precise search queries
-
bd count: New command for counting and grouping issues (
d7f4189)- Count issues by status, priority, type, or labels
- Helpful for generating statistics and reports
-
Test Infrastructure: Automatic skip list for tests (
0040e80)- Improves test reliability and maintenance
- Automatically manages flaky or environment-specific tests
Fixed
-
Test Stability: Fixed hanging tests by initializing rootCtx (
822baa0, bd-n25)- Prevents test hangs from context cancellation issues
- Better test isolation and cleanup
-
Git Merge Driver: Corrected placeholders from %L/%R to %A/%B (
ddd209e)- Fixes merge driver configuration for proper conflict resolution
- Uses correct git merge driver variable names
-
Database Paths: Deduplicate database paths when symlinks present (#354,
f724b61)- Prevents duplicate database detection when symlinks are involved
- Improves reliability in complex filesystem setups
Changed
-
bd list: Accept both integer and P-format for priority flags (
2e2b8d7)--priority 1and--priority P1now both work- More flexible CLI input for priority filtering
-
bd update: Added
--bodyflag as alias for--description(bb5a480)- More intuitive flag name for updating issue descriptions
- Both flags work identically for backward compatibility
-
bd update: Added label operations (
3065db2)--add-labelsand--remove-labelsflags- Simplifies label management in update operations
-
GitHub Copilot Support: Added
.github/copilot-instructions.md(605fff1)- Provides project-specific guidance for GitHub Copilot
- Improves AI-assisted development experience
-
Documentation: Moved design/audit docs from cmd/bd to docs/ (
ce433bb)- Better organization of project documentation
- Clearer separation of code and documentation
Performance
-
Test Suite: Deleted 7 redundant tests from main_test.go (
fa727c7)- 3x speedup in test execution
- Improved CI/CD performance
-
Test Coverage: Tagged 16 slow integration tests with build tags (
8290243)- Faster local test runs with
-shortflag - CI can still run full test suite
- Faster local test runs with
Testing
-
Security Tests: Added security and error handling tests for lint warnings (
74f3844)- Improved code quality and safety
- Better coverage of edge cases
-
Shared Database Pattern: Refactored multiple test files to use shared DB pattern
- compact_test.go, integrity_test.go, validate_test.go, epic_test.go, duplicates_test.go
- Improved test consistency and maintainability
- Faster test execution through better resource sharing
[0.24.0] - 2025-11-20
Added
-
bd doctor --fix: Automatic repair functionality (bd-ykd9,
7806937)- Automatically fixes issues detected by
bd doctor - Repairs common database inconsistencies without manual intervention
- Automatically fixes issues detected by
-
bd clean: Remove temporary merge artifacts (
e8355c2)- Cleans up
.base,.ours,.theirssnapshot files - Helps maintain clean
.beads/directory after merges
- Cleans up
-
bd cleanup: Enhanced bulk deletion command
- Delete multiple closed issues efficiently
- Improved from previous versions with better performance
-
.beads/README.md Generation: Auto-generated during
bd init(bd-m7ge,e1c8853)- Provides project-specific beads documentation
- Helps new contributors understand the setup
-
blocked_issues_cache Table: Performance optimization for GetReadyWork (
62c1f42,ed23f8f)- Caches blocked issue relationships
- Dramatically improves
bd readyperformance on large databases
-
Commit Hash in Version Output: Enhanced version reporting (bd-hpt5,
7c96142)bd versionnow shows git commit hash- Helps identify exact build for debugging
-
Auto-detection of Issue Prefix: Scans git history to detect prefix (#277,
8f37904)- Automatically discovers project's issue prefix
- Reduces manual configuration needed
-
external_ref Support in Daemon RPC: Full daemon mode support (#304,
57b6ea6)- MCP server can now set external references in daemon mode
- Parity with CLI functionality
-
Context Optimization Features: AI agent improvements (#297,
f7e80dd)- Context propagation with graceful cancellation (bd-rtp, bd-yb8, bd-2o2,
57253f9) - Better memory management for long-running agent sessions
- Context propagation with graceful cancellation (bd-rtp, bd-yb8, bd-2o2,
Fixed
-
Critical: Auto-import Resurrection Bug (bd-khnb,
0020eb4,e28e3ea,7b6370f)- Fixed critical bug where deleted issues were resurrected during auto-import
- Cleaned up 497+ resurrected issues from production database
- Prevents data corruption from improper JSONL replay
-
Critical: bd sync Auto-resolves Conflicts (bd-ca0b,
a1e5075)bd syncnow automatically resolves conflicts instead of failing- Dramatically improves multi-agent workflow reliability
- Eliminates manual conflict resolution in most cases
-
Critical: Content-based Timestamp Skew Prevention (bd-lm2q,
d0e7047)- Fixed false-positive "JSONL is newer than database" warnings
- Uses content-based comparison instead of timestamp-only
- Prevents unnecessary imports that would corrupt state
-
Critical: bd sync DB Changes After Import (
81c741b)- Ensures database changes are properly applied after import
- Fixes desync issues between JSONL and database
-
Critical: Context Propagation Lifecycle Bugs (bd-rtp, bd-yb8, bd-2o2,
57253f9,a17e4af)- Fixed multiple context propagation issues causing crashes
- Graceful cancellation support for long-running operations
- Improved stability for AI agent workflows
-
Critical: Race Condition in Auto-flush (bd-52,
a9b2f9f)- Fixed race condition in auto-flush mechanism
- Prevents data loss during concurrent operations
-
Critical: Resource Leaks and Error Handling (#327,
fb65163)- Fixed critical resource leaks in daemon mode
- Improved error handling throughout codebase
-
Critical: In-memory Database Deadlock (bd-yvlc,
944ed10)- Fixed deadlock in migrations when using in-memory database
- Improves test reliability
-
MCP Schema Generation Recursion Bug (GH#346,
f3a678f)- Fixed infinite recursion in MCP schema generation
- Prevents stack overflow crashes
-
FK Constraint Failures (bd-5arw,
345766b)- Fixed foreign key constraint failures in AddComment and ApplyCompaction
- Improved data integrity
-
--parent Flag Behavior (
b9919fe)- Now correctly creates parent-child dependency relationships
- Previously was creating wrong dependency type
-
Exact ID Matching Priority (gh-316,
934ae04)- Prefers exact ID matches over prefix matches
- Prevents ambiguous ID resolution
-
Daemon Lifetime on macOS (GH#278,
68f9bef)- Fixed daemon exiting after 5s on macOS due to PID 1 parent monitoring
- Daemon now runs reliably on macOS
-
Daemon Export/JSONL Sync (GH#301, #321,
04a1996)- Fixed daemon export leaving JSONL newer than database
- Ensures proper sync between export and database state
-
bd doctor Hash ID Detection (GH#322,
8c1f865)- Fixed doctor incorrectly diagnosing hash IDs as sequential
- Improved detection logic for ID format validation
-
ResolvePartialID Handling (GH#336,
4432af0)- Improved ResolvePartialID / ResolveID handling for
bd show - Better partial ID matching and error messages
- Improved ResolvePartialID / ResolveID handling for
-
bd sync Windows Upstream Detection (#281,
1deaad1)- Fixed upstream branch detection on Windows
- Improved cross-platform compatibility
-
Compact Command Daemon Mode (#294,
d9904a8)- Fixed compact command failing with 'SQLite DB needed' error when daemon running
- Removed premature store check, uses ensureDirectMode
-
DB mtime Update After Import (#296,
9dff345)- Fixed DB mtime not being updated after import with 0 changes
- Prevents false staleness warnings
-
FOREIGN KEY Constraint on Non-existent Issues (
09666b4)- Fixed constraint failures when operating on non-existent issues
- Better error handling and validation
-
Monitor WebUI Daemon Detection (
e36baee)- Fixed monitor-webui failure to detect running daemon
- Improved daemon health checking
-
Onboard Test Deadlock on Windows (
4e22214)- Fixed deadlock in onboard tests on Windows
- Improved test stability
-
Windows Concurrent Issue Creation (
4cd26c8)- Fixed concurrent issue creation failures on Windows
- Better file locking on Windows
-
Missing Git Hook Message (#306,
92f3af5)- Improved messaging when git hooks are missing
- Clearer instructions for users
-
Prefix Detection for Hyphenated Apps (
83472ac, bd-fasa)- Fixed prefix detection to only use first hyphen
- Handles hyphenated application names correctly
-
External Ref Migration Failures (
8be792a)- Fixed external_ref migration failure on old databases
- Backward compatibility improvements
-
Duplicate Function Declaration (#328,
167ab67)- Fixed compilation failure from duplicate computeJSONLHash declaration
- Removed old version, kept simpler implementation
- Updated test to match new API
Changed
-
Performance Improvements (#319,
690c73f): -
FlushManager Improvements (
445857f)- Added constants for magic numbers
- Enhanced error logging
- Comprehensive functional tests
-
Auto-upgrade .beads/.gitignore (#300,
f4a2f87)- Automatically upgrades .gitignore on bd operations
- Ensures latest patterns are always applied
-
Code Refactoring:
-
Documentation Improvements:
- Document files created by bd init and clarify .gitattributes (
721274b,e7fd1dd) - How to resolve merge conflicts in .beads/beads.jsonl (
4985a68) - Document MCP tools loading issue in Claude Code (GH#346,
79b8dbe) - Add uv prerequisite to Claude Code plugin docs (#293,
a020c6c) - Don't auto-install Go in Windows installer (#302,
0cba73b)
- Document files created by bd init and clarify .gitattributes (
-
Improved Error Messages (#349,
27c0c33)- Compact error messages
- Remove bogus merge suggestion
- Add daemon/maintenance docs
-
AGENTS.md Refactoring (
21a0656)- Extracted detailed instructions to prevent context pollution
- Better organization for AI agent consumption
-
Type Safety Improvements (
9e57cb6)- Improved type safety in beads-mcp
- Fixed minor type issues
-
Test Improvements:
-
Local-only Git Repo Support (bd-biwp,
4de9f01)- Support repositories without remote origin
- Better handling of local development workflows
-
Version Marker in Post-checkout Hook (
ad2154b)- Add version marker to post-checkout hook
- Include in CheckGitHooks for better version tracking
Performance
-
GetReadyWork Optimization (bd-5qim,
690c73f,62c1f42,ed23f8f)- Introduced blocked_issues_cache table
- Eliminated expensive recursive queries
- Dramatically faster for large dependency graphs
-
bd list N+1 Query Elimination (
968d9e2)- Replaced per-issue label queries with bulk fetch
- Significant speedup when listing many labeled issues
Community
-
Pull Requests:
- #338: Prevent daemon from exiting when launcher process exits (@cpdata)
- #337: Improve ResolvePartialID handling (@cpdata)
- #333: Fix doctor incorrectly diagnosing hash IDs (@cpdata)
- #327: Address critical resource leaks and error handling
- #306: Improve missing git hook message
- #304: Add external_ref support to daemon mode RPC
- #302: Windows installer improvements
- #300: Automatic .beads/.gitignore upgrade
- #297: Context optimization features for AI agents
- #296: Fix DB mtime update after import
- #294: Fix compact command in daemon mode
- #293: Add uv prerequisite documentation
- #281: Fix bd sync Windows upstream detection
- #277: Auto-detection of issue prefix from git history
-
Dependency Updates:
- Bump github.com/anthropics/anthropic-sdk-go from 1.17.0 to 1.18.0 (#330)
- Bump golang.org/x/mod from 0.29.0 to 0.30.0 (#331)
- Bump fastmcp from 2.13.0.2 to 2.13.1 (#332)
- Bump pydantic from 2.12.0 to 2.12.4 (#285)
- Bump pydantic-settings from 2.11.0 to 2.12.0 (#286)
- Bump golangci/golangci-lint-action from 8 to 9 (#287)
- Bump golang.org/x/sys from 0.36.0 to 0.38.0 (#288)
- Bump github.com/ncruces/go-sqlite3 from 0.29.1 to 0.30.1 (#290)
- Bump github.com/google/go-cmp from 0.6.0 to 0.7.0 (#291)
Notes
This release represents a major stability and performance improvement with 179 commits since 0.23.1. Key themes:
- Reliability: Fixed critical auto-import resurrection bug and multiple daemon issues
- Performance: Significant optimizations for
bd readyandbd list - AI Agent Support: Improved context propagation and error handling
- Cross-platform: Better Windows and macOS support
- Developer Experience: Auto-detection, better error messages, improved docs
[0.23.1] - 2025-11-08
Fixed
-
#263: Database mtime not updated after import causing false
bd doctorwarnings- When
bd sync --import-onlycompleted, SQLite WAL mode wouldn't update the main database file's mtime - This caused
bd doctorto incorrectly warn "JSONL is newer than database" even when perfectly synced - Now updates database mtime after imports to prevent false warnings
- When
-
#261: SQLite URI missing 'file:' prefix causing version detection failures
- Without 'file:' scheme, SQLite treated
?mode=roas part of filename instead of connection option - Created bogus files like
beads.db?mode=ro - Caused
bd doctorto incorrectly report "version pre-0.17.5 (very old)" on modern databases
- Without 'file:' scheme, SQLite treated
-
bd-17d5: Conflict marker false positives on JSON-encoded content
- Issues containing JSON strings with
<<<<<<<would trigger false conflict marker detection - Now checks raw bytes before JSON decoding to avoid false positives
- Issues containing JSON strings with
-
bd-ckvw: Schema compatibility probe prevents silent migration failures
- Migrations could fail silently, causing cryptic "no such column" and UNIQUE constraint errors later
- Now probes schema after migrations, retries once if incomplete, and fails fast with clear error
- Daemon refuses RPC if client has newer minor version to prevent schema mismatches
-
#264/#262: Remove stale
--resolve-collisionsreferences- Docs/error messages still referenced
--resolve-collisionsflag (removed in v0.20) - Fixed post-merge hook error messages and git-hooks README
- Docs/error messages still referenced
Changed
-
bd-auf1: Auto-cleanup snapshot files after successful merge
.beads/no longer accumulates orphaned.base,.ours,.theirssnapshot files after merges
-
bd-ky74: Optimize CLI tests with in-process testing
- Converted exec.Command() tests to in-process rootCmd.Execute() calls
- Dramatically faster: 10+ minutes → just a few seconds
- Improved test coverage from 20.2% to 23.3%
-
bd-6uix: Message system improvements
- 30s HTTP timeout prevents hangs, full message reading, --importance validation, server-side filtering
-
Remove noisy version field from metadata.json
- Eliminated redundant version mismatch warnings on every bd upgrade
- Daemon version checking via RPC is sufficient
Added
- Go agent example with Agent Mail support
- Agent Mail multi-workspace deployment guide and scripts
[0.23.0] - 2025-11-08
Added
-
Agent Mail Integration: Complete Python adapter library with comprehensive documentation and multi-agent coordination tests
- Python adapter library in
integrations/agent-mail-python/ - Agent Mail quickstart guide and comprehensive integration docs
- Multi-agent race condition tests and failure scenario tests
- Automated git traffic benchmark showing 98.5% reduction in git traffic compared to git-only sync
- Bash-agent integration example
- Python adapter library in
-
bd info --whats-new: Agent version awareness for quick upgrade summaries
- Shows last 3 versions with workflow-impacting changes
- Supports
--jsonflag for machine-readable output - Helps agents understand what changed without re-reading full docs
-
bd hooks install: Embedded git hooks command
- Replaces external install script with native command
- Git hooks now embedded in bd binary
- Works for all bd users, not just source repo users
-
bd cleanup: Bulk deletion command for closed issues
- Agent-driven compaction for large databases
- Removes closed issues older than specified threshold
Fixed
-
3-way JSONL Merge: Auto-invoked on conflicts
- Automatically triggers intelligent merge on JSONL conflicts
- No manual intervention required
- Warning message added to zombie issues.jsonl file
-
Auto-import on Missing Database (
ab4ec90):bd importnow auto-initializes database when missing -
Daemon Crash Recovery: Panic handler with socket cleanup prevents orphaned processes
-
Stale Database Exports: ID-based staleness detection prevents exporting stale data
-
Windows MCP Subprocess Timeout: Fix for git detection on Windows
-
Daemon Orphaning (
a6c9579): Track parent PID and exit when parent dies -
Test Pollution Prevention (bd-z528, bd-2c5a): Safeguards to prevent test issues in production database
-
Client Self-Heal (
a236558): Auto-recovery for stale daemon.pid files -
Post-Merge Hook Error Messages (
abb1d1c): Show actual error messages instead of silent failures -
Auto-import During Delete: Disable auto-import during delete operations to prevent conflicts
-
MCP Workspace Context: Auto-detect workspace from CWD
-
Import Sync Warning: Warn when import syncs with working tree but not git HEAD
-
GH#254:
bd initnow detects and chains with existing git hooks -
GH#249: Add nil storage checks to prevent RPC daemon crashes
-
GH#252: Fix SQLite driver name mismatch causing "unknown driver" errors
-
Nested .beads Directories: Prevent creating nested .beads directories
-
Windows SQLite Support: Fix SQLite in releases for Windows
Changed
-
Agent Affordances (observations from agents using beads):
- bd new: Added as alias for
bd createcommand (agents often tried this) - bd list: Changed default to one-line-per-issue format to prevent agent miscounting; added
--longflag for previous detailed format
- bd new: Added as alias for
-
Developer Experience:
- Extracted supplemental docs from AGENTS.md for better organization
- Added warning for working tree vs git HEAD sync mismatches
- Completion commands now work without database
- Config included in
bd infoJSON output - Python cache files added to .gitignore
- RPC diagnostics available via
BD_RPC_DEBUGenv var - Reduced RPC dial timeout from 2s to 200ms for fast-fail
- Standardized daemon detection with tryDaemonLock probe
- Improved internal/daemon test coverage to 60%
-
Code Organization:
- Refactored snapshot management into dedicated module
- Documented external_ref in content hash behavior
- Added MCP server functions for repair commands
- Added version number to beads-mcp startup log
- Added system requirements section for glibc compatibility in docs
-
Release Automation:
- Automatic Homebrew formula update in release workflow
- Gitignore Formula/bd.rb (auto-generated, real source is homebrew-beads tap)
-
Other:
- Added
docs/directory to links (#242) - RPC monitoring solution with web UI as implementation example (#244)
- Remove old install.sh script, replaced by
bd hooks install - Remove vc.db exclusion from FindDatabasePath filter
- Added
[0.22.1] - 2025-11-06
Added
-
Vendored beads-merge by @neongreen: Native
bd mergecommand for intelligent JSONL merging- Vendored beads-merge algorithm into
internal/merge/with full attribution and MIT license - New
bd mergecommand as native wrapper (no external binary needed) - Same field-level 3-way merge algorithm, now built into bd
- Auto-configured during
bd init(both interactive and--quietmodes) - Thanks to @neongreen for permission to vendor: https://github.com/neongreen/mono/issues/240
- Original tool: https://github.com/neongreen/mono/tree/main/beads-merge
- Vendored beads-merge algorithm into
-
Git Hook Version Detection (bd-iou5,
991c624):bd infonow detects outdated git hooks- Adds version markers to all git hook templates (pre-commit, post-merge, pre-push)
- Warns when installed hooks are outdated or missing
- Suggests running
examples/git-hooks/install.shto update - Prevents issues like the
--resolve-collisionsflag error after updates
-
Public API for External Extensions (
8f676a4): Extensibility improvements for third-party tools -
Multi-Repo Patterns Documentation (
e73f89e): Comprehensive guide for AI agents working across multiple repositories -
Snapshot Versioning (
a891ebe): Add versioning and timestamp validation for snapshots -
--clear-duplicate-external-refsflag forbd importcommand (9de98cf)
Fixed
- Multi-Workspace Deletion Tracking (
708a81c,e5a6c05,4718583): Proper deletion tracking across multiple workspaces- Fixes issue where deletions in one workspace weren't propagated to others
- Added
DeleteIssueto Storage interface for backend extensibility (e291ee0)
- Import/Export Deadlock (
a0d24f3): Prevent import/export from hanging when daemon is running - Pre-Push Hook (
3ba245e): Fix pre-push hook blocking instead of exporting - Hash ID Recognition (
c924731,055f1d9): FixisHashIDto recognize Base36 hash IDs and IDs without a-f letters - Git Merge Artifacts (
41b1a21): Ignore merge artifacts in.beads/.gitignore - bd status Command (
1edf3c6): Now uses git history for recent activity detection - Performance: Add raw string equality short-circuit before jsonEquals (
5c1f441)
Changed
-
Code Organization:
- Extract SQLite migrations into separate files (
b655b29) - Centralize BD_DEBUG logging into
internal/debugpackage (95cbcf4) - Extract
normalizeLabelstointernal/util/strings.go(9520e7a) - Reorganize project structure: move Go files to
internal/beads, docs todocs/(584c266) - Remove unused
internal/daemonrunner/package (~1,500 LOC) (a7ec8a2)
- Extract SQLite migrations into separate files (
-
Testing:
-
CI/CD:
Performance
- Cache
getMultiRepoJSONLPaths()to avoid redundant calls (7afb143)
[0.22.0] - 2025-11-05
Added
-
Intelligent Merge Driver (bd-omx1,
52c5059): Auto-configured git merge driver for JSONL conflict resolution- Vendors beads-merge algorithm for field-level 3-way merging
- Automatically configured during
bd init(both interactive and--quietmodes) - Matches issues by identity (id + created_at + created_by)
- Smart field merging: timestamps→max, dependencies→union, status/priority→3-way
- Eliminates most git merge conflicts in
.beads/beads.jsonl
-
Onboarding Wizards (
b230a22): Newbd initworkflows for different collaboration modelsbd init --contributor: OSS contributor wizard (separate planning repo)bd init --team: Team collaboration wizard (branch-based workflow)- Interactive setup with fork detection and remote configuration
- Auto-configures sync settings for each workflow
-
Migration Tools (
349817a): Newbd migrate-issuescommand for cross-repo issue migration- Migrate issues between repositories while preserving dependencies
- Source filtering (by label, priority, status, type)
- Automatic remote repo detection and push
- Complete multi-repo workflow documentation
-
Multi-Phase Development Guide (
3ecc16e): Comprehensive workflow examples- Multi-phase development (feature → integration → deployment)
- Multiple personas (designer, frontend dev, backend dev)
- Best practices for complex projects
-
Dependency Status (
3acaf1d): Show blocker status inbd showoutput- Displays "Blocked by N open issues" when dependencies exist
- Shows "Ready to work (no blockers)" when unblocked
-
DevContainer Support (
247e659): Automatic bd setup in GitHub Codespaces- Pre-configured Go environment with bd pre-installed
- Auto-detects existing
.beads/and imports on startup
-
Session Completion Protocol (
095e40d): Session-ending checklist for AI agents- Quality gates, sync procedures, git cleanup
- Ensures clean handoff between sessions
Fixed
-
SearchIssues N+1 Query (bd-5ots,
e90e485): Eliminated N+1 query bug in label loading- Batch-loads labels for all issues in one query
- Significant performance improvement for
bd listwith many labeled issues
-
Sync Validation (bd-9bsx,
5438485): Prevent infinite dirty loop in auto-sync- Added export verification to detect write failures
- Ensures JSONL line count matches database after export
-
bd edit Direct Mode (GH #227,
d4c73c3): Forcebd editto always use direct mode- Prevents daemon interference with interactive editor sessions
- Resolves hang issues when editing in terminals
-
SQLite Driver on arm64 macOS (
f9771cd): Fixed missing SQLite driver in arm64 builds- Explicitly imports CGO-enabled sqlite driver
- Resolves "database driver not found" errors on Apple Silicon
-
external_ref Type Handling (
e1e58ef): Handle both string and *string in UpdateIssue RPC- Fixes type mismatch errors in MCP server
- Ensures consistent API behavior
-
Windows Test Stability (
2ac28b0,8c5e51e): Skip flaky concurrent tests on Windows- Prevents false failures in CI/CD
- Improves overall test suite reliability
Changed
-
Test Suite Performance (
0fc4da7): Optimized test suite for 15-18x speedup- Reduced redundant database operations
- Parallelized independent test cases
- Faster CI/CD builds
-
Priority Format (
b8785d3): Added support for P-prefix priority format (P0-P4)- Accepts both
--priority 1and--priority P1 - More intuitive for GitHub/Jira users
- Accepts both
-
--label Alias (
85ca8c3): Added--labelas alias for--labelsinbd create- Both singular and plural forms now work
- Improved CLI ergonomics
-
--parent Flag in Daemon Mode (
fc89f15): Added--parentsupport in daemon RPC- MCP server can now set parent relationships
- Parity with CLI functionality
Documentation
-
Multi-Repo Migration Guide (
9e60ed1): Complete documentation for multi-repo workflows- OSS contributors, teams, multi-phase development
- Addresses common questions about fork vs branch workflows
-
beads-merge Setup Instructions (
527e491): Enhanced merge driver documentation- Installation guide for standalone binary
- Jujutsu configuration examples
[0.21.9] - 2025-11-05
Added
-
Epic/Child Filtering (bd-zkl,
fbe790a): Newbd listfilters for hierarchical issue queries--ancestor <id>: Filter by ancestor issue (shows all descendants)--parent <id>: Filter by direct parent issue--epic <id>: Alias for--ancestor(more intuitive for epic-based workflows)ancestor_idfield added to issue type for efficient epic hierarchy queries
-
Advanced List Filters: Pattern matching, date ranges, and empty checks
- Pattern matching:
--title-contains,--desc-contains,--notes-contains(case-insensitive substring) - Date ranges:
--created-after/before,--updated-after/before,--closed-after/before - Empty checks:
--empty-description,--no-assignee,--no-labels - Priority ranges:
--priority-min,--priority-max
- Pattern matching:
-
Database Migration (bd-bb08,
3bde4b0): AddedON DELETE CASCADEtochild_counterstable- Prevents orphaned child counter records when issues are deleted
- Comprehensive migration tests ensure data integrity
Fixed
-
Import Timestamp Preservation (
8b9a486): Fixed critical bug whereclosed_attimestamps were lost during sync- Ensures closed issues retain their original completion timestamps
- Prevents issue resurrection timestamps from overwriting real closure times
-
Import Config Respect (
7292c85): Import now respectsimport.missing_parentsconfig setting- Previously ignored config for parent resurrection behavior
- Now correctly honors user's preference for handling missing parents
-
GoReleaser Homebrew Tap (
37ed10c): Fixed homebrew tap to point tosteveyegge/homebrew-beads- Automated homebrew formula updates now work correctly
- Resolves brew installation issues
-
npm Package Versioning (
626d51d): Added npm-package to version bump script- Ensures
@beads/bdnpm package stays in sync with CLI releases - Prevents version mismatches across distribution channels
- Ensures
-
Linting (
52cf2af): Fixed golangci-lint errors- Added proper error handling
- Added gosec suppressions for known-safe operations
Changed
- RPC Filter Parity (
510ca17): Comprehensive test coverage for CLI vs RPC filter behavior- Ensures MCP server and CLI have identical filtering semantics
- Validates all new filters work correctly in both modes
[0.21.8] - 2025-11-05
Added
- Parent Resurrection: Automatic resurrection of deleted parent issues from JSONL history
- Prevents import failures when parent issues have been deleted
- Creates tombstone placeholders for missing hierarchical parents
- Best-effort dependency resurrection from JSONL
Changed
- Error Messages: Improved error messages for missing parent issues
- Old:
"parent issue X does not exist" - New:
"parent issue X does not exist and could not be resurrected from JSONL history" - Breaking: Scripts parsing exact error messages may need updates
- Old:
Fixed
- JSONL Resurrection Logic: Fixed to use LAST occurrence instead of FIRST (append-only semantics)
- Version Bump Script: Added
--tagand--pushflags to automate release tagging- Addresses confusion where version bump doesn't trigger GitHub release
- New usage:
./scripts/bump-version.sh X.Y.Z --commit --tag --push
[0.21.7] - 2025-11-04
Fixed
-
Memory Database Connection Pool: Fixed
:memory:database handling to use single shared connection- Prevents "no such table" errors when using in-memory databases
- Ensures connection pool reuses the same in-memory instance
- Critical fix for event-driven daemon mode tests
-
Test Suite Stability: Fixed event-driven test flakiness
- Added
waitForhelper for event-driven testing - Improved timing-dependent test reliability
- Added
[0.21.6] - 2025-11-04
Added
-
npm Package: Created
@beads/bdnpm package for Node.js/Claude Code for Web integration- Native binary downloads from GitHub releases
- Integration tests and release documentation
- Postinstall script for platform-specific binary installation
-
Template Support: Issue creation from markdown templates
- Create multiple issues from a single file
- Structured format for bulk issue creation
-
bd commentAlias: Convenient shorthand forbd comments add
Changed
- Base36 Issue IDs (GH #213): Switched from hex to Base36 encoding for shorter, more readable IDs
- Reduces ID length while maintaining uniqueness
- More human-friendly format
Fixed
-
SQLite URI Handling: Fixed
file://URI scheme to prevent query params in filename- Prevents database corruption from malformed URIs
- Fixed
:memory:database connection strings
-
bd init --no-dbBehavior (GH #210): Now correctly createsmetadata.jsonandconfig.yaml- Previously failed to set
no-db: trueflag - Improved metadata-only initialization workflow
- Previously failed to set
-
Symlink Path Resolution: Fixed
findDatabaseInTreeto properly resolve symlinks -
Epic Hierarchy Display: Fixed
bd showcommand to correctly display epic child relationships -
CI Stability: Fixed performance thresholds, test eligibility, and lint errors
Dependencies
- Bumped
github.com/anthropics/anthropic-sdk-gofrom 1.14.0 to 1.16.0 - Bumped
fastmcpfrom 2.13.0.1 to 2.13.0.2
[0.21.5] - 2025-11-02
Fixed
-
Critical Double JSON Encoding Bug (bd-1048, bd-4ec8): Fixed widespread bug in daemon RPC calls where
ResolveIDresponses were incorrectly converted usingstring(resp.Data)instead ofjson.Unmarshal. This caused IDs to become double-quoted ("\"bd-1048\"") and database lookups to fail. Affected commands:bd show- nil pointer dereference and 3 instances of double encodingbd dep add/remove/tree- 5 instancesbd label add/remove/list- 3 instancesbd reopen- 1 instance
All 12 instances fixed with proper JSON unmarshaling.
[0.21.4] - 2025-11-02
Added
-
New Commands:
bd status- Database overview command showing issue counts and statsbd comment- Convenient alias forbd comments addbd daemons restart- Restart specific daemon without manual kill/start--jsonflag forbd stalecommand
-
Protected Branch Workflow:
BEADS_DIRenvironment variable for custom database locationsync.branchconfiguration for protected branch workflows- Git worktree management with sparse checkout for sync branches
- Only checks out
.beads/in worktrees, minimal disk usage - Only used when
sync.branchis configured, not for default users
- Only checks out
- Comprehensive protected branch documentation
-
Migration & Validation:
- Migration inspection tools for AI agents
- Conflict marker detection in
bd importandbd validate - Git hooks health check in
bd doctor - External reference (
external_ref) UNIQUE constraint and validation external_refnow primary matching key for import updates
Fixed
-
Critical Fixes:
- Daemon corruption from git conflicts
- MCP
set_contexthangs with stdio transport (GH #153) - Double-release race condition in
importInProgressflag - Critical daemon race condition causing stale exports
-
Configuration & Migration:
bd migratenow detects and sets missingissue_prefixconfig- Config system refactored (renamed
config.json→metadata.json) - Config version update in migrate command
-
Daemon & RPC:
bd doctor --jsonflag not workingbd importnow flushes JSONL immediately for daemon visibility- Panic recovery in RPC
handleConnection - Daemon auto-upgrades database version instead of exiting
-
Windows Compatibility:
- Windows test failures (path handling, bd binary references)
- Windows CI: forward slashes in git hook shell scripts
- TestMetricsSnapshot/uptime flakiness on Windows
-
Code Quality:
- All golangci-lint errors fixed - linter now passes cleanly
- All gosec, misspell, and unparam linter warnings resolved
- Tightened file permissions and added security exclusions
Changed
- Daemon automatically upgrades database schema version instead of exiting
- Git worktree management for sync branches uses sparse checkout (
.beads/only) - Improved test isolation and performance optimization
[0.21.2] - 2025-11-01
Changed
- Homebrew formula now auto-published in main repo via GoReleaser
- Deprecated separate homebrew-beads tap repository
[0.21.1] - 2025-10-31
Changed
- Version bump for consistency across CLI, MCP server, and plugin
[0.20.1] - 2025-10-31
Breaking Changes
- Hash-Based IDs Now Default: Sequential IDs (bd-1, bd-2) replaced with hash-based IDs (bd-a1b2, bd-f14c)
- 4-character hashes for 0-500 issues
- 5-character hashes for 500-1,500 issues
- 6-character hashes for 1,500-10,000 issues
- Progressive length extension prevents collisions with birthday paradox math
- Migration required: Run
bd migrateto upgrade schema (removesissue_counterstable) - Existing databases continue working - migration is opt-in
- Dramatically reduces merge conflicts in multi-worker/multi-branch workflows
- Eliminates ID collision issues when multiple agents create issues concurrently
Removed
- Sequential ID Generation: Removed
SyncAllCounters(),AllocateNextID(), and collision remapping logic (bd-c7af, bd-8e05, bd-4c74)- Hash IDs handle collisions by extending hash length, not remapping
issue_counterstable removed from schema--resolve-collisionsflag removed from import (no longer needed)- 400+ lines of obsolete collision handling code removed
Changed
- Collision Handling: Automatic hash extension on collision instead of ID remapping
- Much simpler and more reliable than sequential remapping
- No cross-branch coordination needed
- Birthday paradox ensures extremely low collision rates
Migration Notes
For users upgrading from 0.20.0 or earlier:
- Run
bd migrateto detect and upgrade old database schemas - Database continues to work without migration, but you'll see warnings
- Hash IDs provide better multi-worker reliability at the cost of non-numeric IDs
- Old sequential IDs like
bd-152become hash IDs likebd-f14c
See README.md for hash ID format details and birthday paradox collision analysis.
[0.20.0] - 2025-10-30
Added
- Hash-Based IDs: New collision-resistant ID system (bd-168, bd-166, bd-167)
- 6-character hash IDs with progressive 7/8-char fallback on collision
- Opt-in via
.beads/config.tomlwithid_mode = "hash" - Migration tool:
bd migrate --to-hash-idsfor existing databases - Prefix-optional ID parsing (e.g.,
bd-abc123or justabc123) - Hierarchical child ID generation for discovered-from relationships
- Substring ID Matching: All bd commands now support partial ID matching
bd show abcmatches any ID containing "abc" (e.g.,bd-abc123)- Ambiguous matches show helpful error with all candidates
- Daemon Registry: Multi-daemon management for multiple workspaces
bd daemons listshows all running daemons across workspacesbd daemons healthdetects version mismatches and stale socketsbd daemons logs <workspace>for per-daemon log viewingbd daemons killallto restart all daemons after upgrades
Fixed
- Test Stability: Deprecated sequence-ID collision tests
- Kept
TestFiveCloneCollisionfor hash-ID multi-clone testing - Fixed
TestTwoCloneCollisionto use merge instead of rebase
- Kept
- Linting: golangci-lint v2.5.0 compatibility
- Added
version: 2field to.golangci.yml - Renamed
excludetoexclude-patternsfor v3 format
- Added
Changed
- Multiple bd Detection: Warning when multiple bd binaries in PATH (PR #182)
- Prevents confusion from version conflicts
- Shows locations of all bd binaries found
[0.17.7] - 2025-10-26
Fixed
- Test Isolation: Export test failures due to hash caching between subtests
- Added
ClearAllExportHashes()method to SQLiteStorage for test isolation - Export tests now properly reset state between subtests
- Fixes intermittent test failures when running full test suite
- Added
[0.17.2] - 2025-10-25
Added
- Configurable Sort Policy:
bd ready --sortflag for work queue orderinghybrid(default): Priority-weighted by stalenesspriority: Strict priority ordering for autonomous systemsoldest: Pure FIFO for long-tail work
- Release Automation: New scripts for streamlined releases
scripts/release.sh: Full automated release (version bump, tests, tag, Homebrew, install)scripts/update-homebrew.sh: Automated Homebrew formula updates
Fixed
- Critical: Database reinitialization test re-landed with CI fixes
- Windows: Fixed git path handling (forward slash normalization)
- Nix: Skip test when git unavailable
- JSON: Increased scanner buffer to 64MB for large issues
- Bug: Stale daemon socket detection
- MCP server now health-checks cached connections before use
- Auto-reconnect with exponential backoff on stale sockets
- Handles daemon restarts/upgrades gracefully
- Linting: Fixed all errcheck warnings in production code
- Proper error handling for database resources and transactions
- Graceful EOF handling in interactive input
- Linting: Fixed revive style issues
- Removed unused parameters, renamed builtin shadowing
- Linting: Fixed goconst warnings
[0.17.0] - 2025-10-24
Added
- Git Hooks: Automatic installation prompt during
bd init- Eliminates race condition between auto-flush and git commits
- Pre-commit hook: Flushes pending changes immediately before commit
- Post-merge hook: Imports updated JSONL after pull/merge
- Optional installation with Y/n prompt (defaults to yes)
- See examples/git-hooks/README.md for details
- Duplicate Detection: New
bd duplicatescommand for finding and merging duplicate issues (bd-119, bd-203)- Automated duplicate detection with content-based matching
--auto-mergeflag for batch merging duplicates--dry-runmode to preview merges before execution- Helps maintain database cleanliness after imports
- External Reference Import: Smart import matching using
external_reffield (bd-66-74, GH #142)- Issues with
external_refmatch by reference first, not content - Enables hybrid workflows with Jira, GitHub, Linear
- Updates existing issues instead of creating duplicates
- Database index on
external_reffor fast lookups
- Issues with
- Multi-Database Warning: Detect and warn about nested beads databases
- Prevents accidental creation of multiple databases in hierarchy
- Helps users avoid confusion about which database is active
Fixed
- Critical: Database reinitialization data loss bug (bd-130, DATABASE_REINIT_BUG.md)
- Fixed bug where removing
.beads/and runningbd initwould lose git-tracked issues - Now correctly imports from JSONL during initialization
- Added comprehensive tests (later reverted due to CI issues on Windows/Nix)
- Fixed bug where removing
- Critical: Foreign key constraint regression (bd-62, GH #144)
- Pinned modernc.org/sqlite to v1.38.2 to avoid FK violations
- Prevents database corruption from upstream regression
- Critical: Install script safety (GH #143 by @marcodelpin)
- Prevents shell corruption from directory deletion during install
- Restored proper error codes for safer installation
- Bug: Daemon auto-start reliability
- Daemon now responsive immediately, runs initial sync in background
- Fixes timeout issues when git pull is slow
- Skip daemon-running check for forked child process
- Bug: Dependency timestamp churn during auto-import (bd-45, bd-137)
- Auto-import no longer updates timestamps on unchanged dependencies
- Eliminates perpetually dirty JSONL from metadata changes
- Bug: Import reporting accuracy (bd-49, bd-88)
bd importnow correctly reports "X updated, Y unchanged" instead of "0 updated"- Better visibility into import operation results
- Bug: Memory database handling
- Fixed :memory: database connection with shared cache mode
- Proper URL construction for in-memory testing
Changed
- Removed: Deprecated
bd reposcommand- Global daemon architecture removed in favor of per-project daemons
- Eliminated cross-project database confusion
- Documentation: Major reorganization and improvements
- Condensed README, created specialized docs (QUICKSTART.md, ADVANCED.md, etc.)
- Enhanced "Why not GitHub Issues?" FAQ section
- Added Beadster to Community & Ecosystem section
Performance
- Test coverage improvements: 46.0% → 57.7% (+11.7%)
- Added tests for RPC, storage, cmd/bd helpers
- New test files: coverage_test.go, helpers_test.go, epics_test.go
Community
- Community contribution by @marcodelpin (install script safety fixes)
- Dependabot integration for automated dependency updates
[0.16.0] - 2025-10-23
Added
- Automated Releases: GoReleaser workflow for cross-platform binaries
- Automatic GitHub releases on version tags
- Linux, macOS, Windows binaries for amd64 and arm64
- Checksums and changelog generation included
- PyPI Automation: Automated MCP server publishing to PyPI
- GitHub Actions workflow publishes beads-mcp on version tags
- Eliminates manual PyPI upload step
- Sandbox Mode:
--sandboxflag for Claude Code integration- Isolated environment for AI agent experimentation
- Prevents production database modifications during testing
Fixed
- Critical: Idempotent import timestamp churn
- Prevents timestamp updates when issue content unchanged
- Reduces JSONL churn and git noise from repeated imports
- Bug: Windows CI test failures (bd-60, bd-99)
- Fixed path separator issues and file handling on Windows
- Skipped flaky tests to stabilize CI
Changed
- Configuration Migration: Unified config management with Viper (bd-40-44, bd-78)
- Migrated from manual env var handling to Viper
- Bound all global flags to Viper for consistency
- Kept
bd configindependent from Viper for modularity - Added comprehensive configuration tests
- Documentation Refactor: Improved documentation structure
- Condensed main README
- Created specialized guides (QUICKSTART.md, CONFIG.md, etc.)
- Enhanced FAQ and community sections
Testing
- Hardened
issueDataChangedwith type-safe comparisons - Improved test isolation and reliability
[0.15.0] - 2025-10-23
Added
- Configuration System: New
bd configcommand for managing configuration (GH #115)- Environment variable definitions with validation
- Configuration file support (TOML/YAML/JSON)
- Get/set/list/unset commands for user-friendly management
- Validation and type checking for config values
- Documentation in CONFIG.md
Fixed
- MCP Server: Smart routing for lifecycle status changes in
updatetool (GH #123)update(status="closed")now routes toclose()tool to respect approval workflowsupdate(status="open")now routes toreopen()tool to respect approval workflows- Prevents bypass of Claude Code approval settings for lifecycle events
- bd CLI remains unopinionated; routing happens only in MCP layer
- Users can now safely auto-approve benign updates (priority, notes) without exposing closure bypass
[0.14.0] - 2025-10-22
Added
- Lifecycle Safety Documentation: Complete documentation for UnderlyingDB() usage
- Added tracking guidelines for database lifecycle safety
- Documented transaction management best practices
- Prevents UAF (use-after-free) bugs in extensions
Fixed
- Critical: Git worktree detection and warnings
- Added automatic detection when running in git worktrees
- Displays prominent warning if daemon mode is active in worktree
- Prevents daemon from committing/pushing to wrong branch
- Documents
--no-daemonflag as solution for worktree users
- Critical: Multiple daemon race condition
- Implemented file locking (
daemon.lock) to prevent multiple daemons per repository - Uses
flockon Unix,LockFileExon Windows for process-level exclusivity - Lock held for daemon lifetime, automatically released on exit
- Eliminates race conditions in concurrent daemon start attempts
- Backward compatible: Falls back to PID check for pre-lock daemons during upgrades
- Implemented file locking (
- Bug: daemon.lock tracked in git
- Removed daemon.lock from git tracking
- Added to .gitignore to prevent future commits
- Bug: Regression in Nix Flake (#110)
- Fixed flake build issues
- Restored working Nix development environment
Changed
- UnderlyingDB() deprecated for most use cases
- New UnderlyingConn(ctx) provides safer scoped access
- Reduced risk of UAF bugs in database extensions
- Updated EXTENDING.md with migration guide
Documentation
- Complete release process documentation in RELEASING.md
- Enhanced EXTENDING.md with lifecycle safety patterns
- Added UnderlyingDB() tracking guidelines
[0.11.0] - 2025-10-22
Added
- Issue Merging: New
bd mergecommand for consolidating duplicate issues (bd-7, bd-11-17)- Merge multiple source issues into a single target issue
- Automatically migrates all dependencies and dependents to target
- Updates text references (bd-X mentions) across all issue fields
- Closes source issues with "Merged into bd-Y" reason
- Supports
--dry-runfor validation without changes - Example:
bd merge bd-42 bd-43 --into bd-41
- Multi-ID Operations: Batch operations for increased efficiency (bd-195, #101)
bd update: Update multiple issues at oncebd show: View multiple issues in single callbd label add/remove: Apply labels to multiple issuesbd close: Close multiple issues with one commandbd reopen: Reopen multiple issues together- Example:
bd close bd-1 bd-2 bd-3 --reason "Done"
- Daemon RPC Improvements: Enhanced sync operations
bd syncnow works correctly in daemon mode- Export operations properly supported via RPC
- Prevents database access conflicts during sync
- Acceptance Criteria Alias: Added
--acceptance-criteriaflag (bd-228, #102)- Backward-compatible alias for
--acceptanceinbd update - Improves clarity and matches field name
- Backward-compatible alias for
Fixed
- Critical: Test isolation and database pollution (bd-1, bd-15, bd-19, bd-52)
- Comprehensive test isolation ensuring tests never pollute production database
- Fixed stress test issues writing 1000+ test issues to production
- Quarantined RPC benchmarks to prevent pollution
- Added database isolation canary tests
- Critical: Daemon cache staleness
- Daemon now detects external database modifications via mtime check
- Prevents serving stale data after external
bd import,rm bd.db, etc. - Cache automatically invalidates when DB file changes
- Critical: Counter desync after deletions
- Issue counters now sync correctly after bulk deletions
- Prevents ID gaps and counter drift
- Critical: Labels and dependencies not persisted in daemon mode (#101)
- Fixed label operations failing silently in daemon mode
- Fixed dependency operations not saving in daemon mode
- Both now correctly propagate through RPC layer
- Daemon sync support:
bd synccommand now works in daemon mode- Previously crashed with nil pointer when daemon running
- Export operations now properly routed through RPC
- Acceptance flag normalization: Unified
--acceptanceflag behavior (bd-228, #102)- Added
--acceptance-criteriaas clearer alias - Both flags work identically for backward compatibility
- Added
- Auto-import Git conflicts: Better detection of merge conflicts
- Auto-import detects and warns about unresolved Git merge conflicts
- Prevents importing corrupted JSONL with conflict markers
- Clear instructions for resolving conflicts
Changed
- BREAKING: Removed global daemon socket fallback
- Each project now must use its own local daemon (.beads/bd.sock)
- Prevents cross-project daemon connections and database pollution
- Migration: Stop any global daemon and restart with
bd daemonin each project - Warning displayed if old global socket (~/.beads/bd.sock) is found
- Database cleanup: Project database cleaned from 1000+ to 55 issues
- Removed accumulated test pollution from stress testing
- Renumbered issues for clean ID space (bd-1 through bd-55)
- Better test isolation prevents future pollution
Deprecated
- Global daemon socket support (see BREAKING change above)
[0.10.0] - 2025-10-20
Added
- Agent Onboarding: New
bd onboardcommand for agent-first documentation- Outputs structured instructions for agents to integrate bd into documentation
- Bootstrap workflow: Add 'BEFORE ANYTHING ELSE: run bd onboard' to AGENTS.md
- Agent adapts instructions to existing project structure
- More agentic approach vs. direct string replacement
- Updates README with new bootstrap workflow
[0.9.11] - 2025-10-20
Added
- Labels Documentation: Comprehensive LABELS.md guide (bd-159, bd-163)
- Complete label system documentation with workflows and best practices
- Common label patterns (components, domains, size, quality gates, releases)
- Advanced filtering techniques and integration examples
- Added Labels section to README with quick reference
Fixed
- Critical: MCP server crashes on None/null responses (bd-172, fixes #79)
- Added null safety checks in
list_issues(),ready(), andstats()methods - Returns empty arrays/dicts instead of crashing on None responses
- Prevents TypeError when daemon returns empty results
- Added null safety checks in
[0.9.10] - 2025-10-18
Added
- Label Filtering: Enhanced
bd listcommand with label-based filtering--label(or-l): Filter by multiple labels with AND semantics (must have ALL)--label-any: Filter by multiple labels with OR semantics (must have AT LEAST ONE)- Examples:
bd list --label backend,urgent: Issues with both 'backend' AND 'urgent'bd list --label-any frontend,backend: Issues with either 'frontend' OR 'backend'
- Works in both daemon and direct modes
- Includes comprehensive test coverage
- Log Rotation: Automatic daemon log rotation with configurable limits
- Prevents unbounded log file growth for long-running daemons
- Configurable via environment variables:
BEADS_DAEMON_LOG_MAX_SIZE,BEADS_DAEMON_LOG_MAX_BACKUPS,BEADS_DAEMON_LOG_MAX_AGE,BEADS_DAEMON_LOG_COMPRESS - Optional compression of rotated logs
- Defaults: 50MB max size, 7 backups, 30 day retention, compression enabled
- Batch Deletion: Enhanced
bd deletecommand with batch operations- Delete multiple issues at once:
bd delete bd-1 bd-2 bd-3 --force - Read from file:
bd delete --from-file deletions.txt --force - Dry-run mode:
--dry-runto preview deletions before execution - Cascade mode:
--cascadeto recursively delete all dependents - Force mode:
--forceto orphan dependents instead of failing - Atomic transactions: all deletions succeed or none do
- Comprehensive statistics: tracks deleted issues, dependencies, labels, and events
- Delete multiple issues at once:
Fixed
- Critical:
bd list --status allshowing 0 issues- Status filter now treats "all" as special value meaning "show all statuses"
- Previously treated "all" as literal status value, matching no issues
[0.9.9] - 2025-10-17
Added
- Daemon RPC Architecture: Production-ready RPC protocol for client-daemon communication (bd-110, bd-111, bd-112, bd-114, bd-117)
- Unix socket-based RPC enables faster command execution via long-lived daemon process
- Automatic client detection with graceful fallback to direct mode
- Serializes SQLite writes and batches git operations to prevent concurrent access issues
- Resolves database corruption, git lock contention, and ID counter conflicts with multiple agents
- Comprehensive integration tests and stress testing with 4+ concurrent agents
- Issue Deletion:
bd deletecommand for removing issues with comprehensive cleanup- Safely removes issues from database and JSONL export
- Cleans up dependencies and references to deleted issues
- Works correctly with git-based workflows
- Issue Restoration:
bd restorecommand for recovering compacted/deleted issues- Restores issues from git history when needed
- Preserves references and dependency relationships
- Prefix Renaming:
bd rename-prefixcommand for batch ID prefix changes- Updates all issue IDs and text references throughout the database
- Useful for project rebranding or namespace changes
- Comprehensive Testing: Added scripttest-based integration tests (#59)
- End-to-end coverage for CLI workflows
- Tests for init command edge cases
Fixed
- Critical: Metadata errors causing crashes on first import
- Auto-import now treats missing metadata as first import instead of failing
- Eliminates initialization errors in fresh repositories
- Critical: N+1 query pattern in auto-import
- Replaced per-issue queries with batch fetching
- Dramatically improves performance for large imports
- Critical: Duplicate issue imports
- Added deduplication logic to prevent importing same issue multiple times
- Maintains data integrity during repeated imports
- Bug: Auto-flush missing after renumber/rename-prefix
- Commands now properly export to JSONL after completion
- Ensures git sees latest changes immediately
- Bug: Renumber ID collision with UUID temp IDs
- Uses proper UUID-based temporary IDs to prevent conflicts during renumbering
- ID counter now correctly syncs after renumbering operations
- Bug: Collision resolution dependency handling
- Uses unchecked dependency addition during collision remapping
- Prevents spurious cycle detection errors
- Bug: macOS crashes documented (closes #3, bd-87)
- Added CGO_ENABLED=1 workaround documentation for macOS builds
Changed
- CLI commands now prefer RPC when daemon is running
- Improved error reporting and diagnostics for RPC failures
- More consistent exit codes and status messages
- Internal command architecture refactored for RPC client/server sharing
- Reduced code duplication between direct and daemon modes
- Improved reliability of background operations
- Ready work sort order flipped to show oldest issues first
- Helps prioritize long-standing work items
Performance
- Faster command execution through RPC-backed daemon (up to 10x improvement)
- N+1 query elimination in list/show operations
- Reduced write amplification from improved auto-flush behavior
- Cycle detection performance benchmarks added
Testing
- Integration tests for daemon RPC request/response flows
- End-to-end coverage for delete/restore lifecycles
- Regression tests for metadata handling, auto-flush, ID counter sync
- Comprehensive tests for collision detection in auto-import
Documentation
- Release process documentation added (RELEASING.md)
- Multiple workstreams warning banner for development coordination
[0.9.8] - 2025-10-16
Added
- Background Daemon Mode:
bd daemoncommand for continuous auto-sync (#bd-386)- Watches for changes and automatically exports to JSONL
- Monitors git repository for incoming changes and auto-imports
- Production-ready with graceful shutdown, PID file management, and signal handling
- Eliminates manual export/import in active development workflows
- Git Synchronization:
bd synccommand for automated git workflows (#bd-378)- One-command sync: stage, commit, pull, push JSONL changes
- Automatic merge conflict resolution with collision remapping
- Status reporting shows sync progress and any issues
- Ideal for distributed teams and CI/CD integration
- Issue Compaction:
bd compactcommand to summarize old closed issues (bd-254-264)- AI-powered summarization using Claude Haiku
- Reduces database size while preserving essential information
- Configurable thresholds for age, dependencies, and references
- Compaction status visible in
bd showoutput
- Label and Title Filtering: Enhanced
bd listcommand (#45, bd-269)- Filter by labels:
bd list --label bug,critical - Filter by title:
bd list --title "auth" - Combine with status/priority filters
- Filter by labels:
- List Output Formats:
bd list --formatflag for custom output (PR #46)- Format options:
default,compact,detailed,json - Better integration with scripts and automation tools
- Format options:
- MCP Reopen Support: Reopen closed issues via MCP server
- Claude Desktop plugin can now reopen issues
- Useful for revisiting completed work
- Cross-Type Cycle Prevention: Dependency cycles detected across all types
- Prevents A→B→A cycles even when mixing
blocks,related, etc. - Semantic validation for parent-child direction
- Diagnostic warnings when cycles detected
- Prevents A→B→A cycles even when mixing
Fixed
- Critical: Auto-import collision skipping bug (bd-393, bd-228)
- Import would silently skip collisions instead of remapping
- Could cause data loss when merging branches
- Now correctly applies collision resolution with remapping
- Critical: Transaction state corruption
- Nested transactions could corrupt database state
- Fixed with proper transaction boundary handling
- Critical: Concurrent temp file collisions (bd-306, bd-373)
- Multiple
bdprocesses would collide on shared.tmpfilename - Now uses PID suffix for temp files:
.beads/issues.jsonl.tmp.12345
- Multiple
- Critical: Circular dependency detection gaps
- Some cycle patterns were missed by detection algorithm
- Enhanced with comprehensive cycle prevention
- Bug: False positive merge conflict detection (bd-313, bd-270)
- Auto-import would detect conflicts when none existed
- Fixed with improved Git conflict marker detection
- Bug: Import timeout with large issue sets
- 200+ issue imports would timeout
- Optimized import performance
- Bug: Collision resolver missing ID counter sync
- After remapping, ID counters weren't updated
- Could cause duplicate IDs in subsequent creates
- Bug: NULL handling in statistics for empty databases (PR #37)
bd statswould crash on newly initialized databases- Fixed NULL value handling in GetStatistics
Changed
- Compaction removes snapshot/restore (simplified to permanent decay)
- Export file writing refactored to avoid Windows Defender false positives (PR #31)
- Error handling improved in auto-import and fallback paths (PR #47)
- Reduced cyclomatic complexity in main.go (PR #48)
- MCP integration tests fixed and linting cleaned up (PR #40)
Performance
- Cycle detection benchmarks added
- Import optimization for large issue sets
- Export uses PID-based temp files to avoid lock contention
Community
- Merged PR #31: Windows Defender mitigation for export
- Merged PR #37: Fix NULL handling in statistics
- Merged PR #38: Nix flake for declarative builds
- Merged PR #40: MCP integration test fixes
- Merged PR #45: Label and title filtering for bd list
- Merged PR #46: Add --format flag to bd list
- Merged PR #47: Error handling consistency
- Merged PR #48: Cyclomatic complexity reduction
[0.9.2] - 2025-10-14
Added
- One-Command Dependency Creation:
--depsflag forbd create(#18)- Create issues with dependencies in a single command
- Format:
--deps type:idor just--deps id(defaults to blocks) - Multiple dependencies:
--deps discovered-from:bd-20,blocks:bd-15 - Whitespace-tolerant parsing
- Particularly useful for AI agents creating discovered-from issues
- External Reference Tracking:
external_reffield for linking to external trackers- Link bd issues to GitHub, Jira, Linear, etc.
- Example:
bd create "Issue" --external-ref gh-42 bd updatesupports updating external references- Tracked in JSONL for git portability
- Metadata Storage: Internal metadata table for system state
- Stores import hash for idempotent auto-import
- Enables future extensibility for system preferences
- Auto-migrates existing databases
- Windows Support: Complete Windows 11 build instructions (#10)
- Tested with mingw-w64
- Full CGo support documented
- PATH setup instructions
- Go Extension Example: Complete working example of database extensions (#15)
- Demonstrates custom table creation
- Shows cross-layer queries joining with issues
- Includes test suite and documentation
- Issue Type Display:
bd listnow shows issue type in output (#17)- Better visibility:
bd-1 [P1] [bug] open - Helps distinguish bugs from features at a glance
- Better visibility:
Fixed
- Critical: Dependency tree deduplication for diamond dependencies (bd-85, #1)
- Fixed infinite recursion in complex dependency graphs
- Prevents duplicate nodes at same level
- Handles multiple blockers correctly
- Critical: Hash-based auto-import replaces mtime comparison
- Git pull updates mtime but may not change content
- Now uses SHA256 hash to detect actual changes
- Prevents unnecessary imports after git operations
- Critical: Parallel issue creation race condition (PR #8, bd-66)
- Multiple processes could generate same ID
- Replaced in-memory counter with atomic database counter
- Syncs counters after import to prevent collisions
- Comprehensive test coverage
Changed
- Auto-import now uses content hash instead of modification time
- Dependency tree visualization improved for complex graphs
- Better error messages for dependency operations
Community
- Merged PR #8: Parallel issue creation fix
- Merged PR #10: Windows build instructions
- Merged PR #12: Fix quickstart EXTENDING.md link
- Merged PR #14: Better enable Go extensions
- Merged PR #15: Complete Go extension example
- Merged PR #17: Show issue type in list output
[0.9.1] - 2025-10-14
Added
- Incremental JSONL Export: Major performance optimization
- Dirty issue tracking system to only export changed issues
- Auto-flush with 5-second debounce after CRUD operations
- Automatic import when JSONL is newer than database
--no-auto-flushand--no-auto-importflags for manual control- Comprehensive test coverage for auto-flush/import
- ID Space Partitioning: Explicit ID assignment for parallel workers
bd create --id worker1-100for controlling ID allocation- Enables multiple agents to work without conflicts
- Documented in CLAUDE.md for agent workflows
- Auto-Migration System: Seamless database schema upgrades
- Automatically adds dirty_issues table to existing databases
- Silent migration on first access after upgrade
- No manual intervention required
Fixed
- Critical: Race condition in dirty tracking (TOCTOU bug)
- Could cause data loss during concurrent operations
- Fixed by tracking specific exported IDs instead of clearing all
- Critical: Export with filters cleared all dirty issues
- Status/priority filters would incorrectly mark non-matching issues as clean
- Now only clears issues that were actually exported
- Bug: Malformed ID detection never worked
- SQLite CAST returns 0 for invalid strings, not NULL
- Now correctly detects non-numeric ID suffixes like "bd-abc"
- No false positives on legitimate zero-prefixed IDs
- Bug: Inconsistent dependency dirty marking
- Duplicated 20+ lines of code in AddDependency/RemoveDependency
- Refactored to use shared markIssuesDirtyTx() helper
- Fixed unchecked error in import.go when unmarshaling JSON
- Fixed unchecked error returns in test cleanup code
- Removed duplicate test code in dependencies_test.go
- Fixed Go version in go.mod (was incorrectly set to 1.25.2)
Changed
- Export now tracks which specific issues were exported
- ClearDirtyIssuesByID() added (ClearDirtyIssues() deprecated with race warning)
- Dependency operations use shared dirty-marking helper (DRY)
Performance
- Incremental export: Only writes changed issues (vs full export)
- Regex caching in ID replacement: 1.9x performance improvement
- Automatic debounced flush prevents excessive I/O
[0.9.0] - 2025-10-12
Added
- Collision Resolution System: Automatic ID remapping for import collisions
- Reference scoring algorithm to minimize updates during remapping
- Word-boundary regex matching to prevent false replacements
- Automatic updating of text references and dependencies
--resolve-collisionsflag for safe branch merging--dry-runflag to preview collision detection
- Export/Import with JSONL: Git-friendly text format
- Dependencies embedded in JSONL for complete portability
- Idempotent import (exact matches detected)
- Collision detection (same ID, different content)
- Ready Work Algorithm: Find issues with no open blockers
bd readycommand shows unblocked workbd blockedcommand shows what's waiting
- Dependency Management: Four dependency types
blocks: Hard blocker (affects ready work)related: Soft relationshipparent-child: Epic/subtask hierarchydiscovered-from: Track issues discovered during work
- Database Discovery: Auto-find database in project hierarchy
- Walks up directory tree like git
- Supports
$BEADS_DBenvironment variable - Falls back to
~/.beads/default.db
- Comprehensive Documentation:
- README.md with 900+ lines of examples and FAQs
- CLAUDE.md for AI agent integration patterns
- SECURITY.md with security policy and best practices
- TEXT_FORMATS.md analyzing JSONL approach
- EXTENDING.md for database extension patterns
- GIT_WORKFLOW.md for git integration
- Examples: Real-world integration patterns
- Python agent implementation
- Bash agent script
- Git hooks for automatic export/import
- Branch merge workflow with collision resolution
- Claude Desktop MCP integration (coming soon)
Changed
- Switched to JSONL as source of truth (from binary SQLite)
- SQLite database now acts as ephemeral cache
- Issue IDs generated with numerical max (not alphabetical)
- Export sorts issues by ID for consistent git diffs
Security
- SQL injection protection via allowlisted field names
- Input validation for all issue fields
- File path validation for database operations
- Warnings about not storing secrets in issues
[0.1.0] - Initial Development
Added
- Core issue tracking (create, update, list, show, close)
- SQLite storage backend
- Dependency tracking with cycle detection
- Label support
- Event audit trail
- Full-text search
- Statistics and reporting
bd initfor project initializationbd quickstartinteractive tutorial
Version History
- 0.9.8 (2025-10-16): Daemon mode, git sync, compaction, critical bug fixes
- 0.9.2 (2025-10-14): Community PRs, critical bug fixes, and --deps flag
- 0.9.1 (2025-10-14): Performance optimization and critical bug fixes
- 0.9.0 (2025-10-12): Pre-release polish and collision resolution
- 0.1.0: Initial development version
Upgrade Guide
Upgrading to 0.9.8
No breaking changes. All changes are backward compatible:
- bd daemon: New optional background service for auto-sync workflows
- bd sync: New optional git integration command
- bd compact: New optional command for issue summarization (requires Anthropic API key)
- --format flag: Optional new feature for
bd list - Label/title filters: Optional new filters for
bd list - Bug fixes: All critical fixes are transparent to users
Simply pull the latest version and rebuild:
go install github.com/steveyegge/beads/cmd/bd@latest
# or
git pull && go build -o bd ./cmd/bd
Note: The bd compact command requires an Anthropic API key in $ANTHROPIC_API_KEY environment variable. All other features work without any additional setup.
Upgrading to 0.9.2
No breaking changes. All changes are backward compatible:
- --deps flag: Optional new feature for
bd create - external_ref: Optional field, existing issues unaffected
- Metadata table: Auto-migrates on first use
- Bug fixes: All critical fixes are transparent to users
Simply pull the latest version and rebuild:
go install github.com/steveyegge/beads/cmd/bd@latest
# or
git pull && go build -o bd ./cmd/bd
Upgrading to 0.9.1
No breaking changes. All changes are backward compatible:
- Auto-migration: The dirty_issues table is automatically added to existing databases
- Auto-flush/import: Enabled by default, improves workflow (can disable with flags if needed)
- ID partitioning: Optional feature, use
--idflag only if needed for parallel workers
If you're upgrading from 0.9.0, simply pull the latest version. Your existing database will be automatically migrated on first use.
Upgrading to 0.9.0
No breaking changes. The JSONL export format is backward compatible.
If you have issues in your database:
- Run
bd export -o .beads/issues.jsonlto create the text file - Commit
.beads/issues.jsonlto git - Add
.beads/*.dbto.gitignore
New collaborators can clone the repo and run:
bd import -i .beads/issues.jsonl
The SQLite database will be automatically populated from the JSONL file.
Future Releases
See open issues tagged with milestone markers for planned features in upcoming releases.
For version 1.0, see: bd dep tree bd-8 (the 1.0 milestone epic)