github gastownhall/beads v1.4.0-rc.4

pre-releaseone hour ago

beads v1.4.0-rc.4

Pre-compiled binaries for Linux, macOS (Intel & Apple Silicon), Windows (AMD64 & ARM64), Android/Termux (ARM64), and FreeBSD.

Installation (release candidate)

This is a prerelease for validation. The stable install channels —
Homebrew, the install.sh / install.ps1 scripts, npm, and PyPI —
intentionally keep serving the latest stable release, so they will not
install this RC. Use one of the methods below.

Manual download (recommended):
Download the archive for your platform from the Assets below, extract it,
and place bd on your PATH.

Go install (pinned to this RC):

go install github.com/steveyegge/beads/cmd/bd@v1.4.0-rc.4
# For embedded Dolt support:
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@v1.4.0-rc.4

1.4.0 is a one-way upgrade. Back up first, with your current bd. Consenting to the schema migration (bd migrate schema, --force, or BD_ALLOW_MIGRATE=1) moves a 1.2.x or 1.3.x store to schema v74. After that, bd 1.3.x and older refuse the database; going back means restoring a backup. From 1.4.0-rc.1, rc.2 or rc.3, rc.4 is a binary swap: it adds no migration.

  • Validate on a copy, or on a store you have backed up with your current bd (bd dolt push, a JSONL export, or bd backup sync).
  • Every Dolt server bd talks to, and the dolt CLI on PATH, must be 2.6.0 or newer.
  • Read Upgrade notes and Known issues under [1.4.0-rc.4], [1.4.0-rc.3], [1.4.0-rc.2] and [1.4.0-rc.1] in CHANGELOG.md before installing.

New in rc.4:

  • Go programs that link beads can open a proxied-server workspace with beads.OpenBestAvailable (#8323). It used to return no error and open a new, empty embedded store at .beads/embeddeddolt there (cgo builds). It now goes through the workspace's bd proxy: it adopts a running proxy or starts one from the bd on PATH; with no bd there, or with a proxy that a bd older than 1.4 started (left running), it fails with beads.ErrProxyUnavailable. A managed-local workspace also needs dolt on PATH (or BEADS_DOLT_BIN), even to adopt a running proxy. Forcing server mode and naming a plain Dolt server's port in BEADS_DOLT_SERVER_PORT keeps the direct server connection (a 1.4 proxy's data port accepts only bd). The returned store does not serve every Storage method; see [1.4.0-rc.4] for its differences from DoltStore. beads.Open, OpenFromConfig and OpenGated are unchanged (see Still open).
  • On a proxied-server workspace whose database has a Dolt remote (bd init --proxied-server adds one from git origin by default), the remote-migrate refusal no longer offers bd migrate --force, BD_ALLOW_REMOTE_MIGRATE=1 bd migrate, bd dolt push, bd dolt pull or bd bootstrap, which are refused there or create a separate local database. It names bd migrate schema --force, run on one clone of that remote only with the proxy's library clients stopped (#8568). Server and embedded mode are unchanged.
  • On a shared or external Dolt server and in proxied-server workspaces, the refusals a 1.3.x upgrade meets, and the bd upgraded to …: N schema migration(s) pending notice, no longer say read commands keep working until you migrate: every issue read needs arrival_seq (migration 0073), so until bd migrate schema runs an upgraded client can neither read nor write issues. Upgrade every client and migrate in one sitting (#8571).

From rc.3:

  • Telemetry no longer exports issue content. Correction to the rc.1 notes: with the console trace exporter on (BD_OTEL_ENABLED=true with OTEL_TRACES_EXPORTER=console, or the legacy BD_OTEL_STDOUT=true on its own), rc.1 and rc.2 still wrote titles, descriptions, notes, labels, comments and search text to stderr in the bd.args span attribute (#8505); logs that kept bd's stderr can hold it. bd.args now names only the command and the flags that were set, so trace queries that read its values must change.
  • bd ranks a release candidate below its release (#6595). Moving from a candidate to 1.4.0 records the release in the version marker in proxied-server workspaces and on a Dolt server whose data is in .beads/dolt; in shared-server mode and on other external servers bd doctor keeps reporting the candidate until you run bare bd migrate once per database.

Behavior changes to know before installing (from rc.2):

  • bd github now stops when a repository lookup fails. Rerun after a temporary failure. Never clear or repoint another repository's bead links to get past it: the next sync creates unlinked beads as new issues in the configured repository.
  • Server-mode pulls need EXECUTE on dolt_fetch and dolt_merge.
  • bd backup restore refuses a Dolt server on another host. Run it on the server's machine, in a workspace that names the same dolt_database.

Still open:

  • #7283: after bd migrate schema the recorded bd version can stay at 1.3.x in every mode; in server mode bd doctor reports it — run bare bd migrate once per database (embedded too; proxied-server mode refuses it and nothing there acts on the marker). See the corrections under [1.4.0-rc.4] Known issues.
  • From 1.3.x, bd ready prints no upgrade notice and bd upgrade status says upgraded: false: read these notes, or run bd info --whats-new after bd migrate schema (bd refuses it before).
  • Go programs that open a proxied-server workspace with beads.Open, OpenFromConfig or OpenGated still go around its proxy: Open can create an empty database, and with no proxy running the other two start a Dolt server that blocks bd until it is killed. Use OpenBestAvailable (#8412, #8323).
  • On a proxied-server workspace, no bd command adopts a remote that another clone has already migrated, and the adopt and fork stops still name bd bootstrap (which creates a separate local database there). bd can't refresh its copy of the remote in that mode, so check with the other clones before you migrate one. See Known issues under [1.4.0-rc.4] for the manual adopt route.
  • Only bd can use a proxied-server workspace's proxy data port (since rc.1). A plain MySQL client, or a gc release that reads a proxied rig directly, is closed after 5 seconds with nothing sent (ERROR 2013 (HY000): Lost connection to server at 'handshake: reading initial communication packet'), and proxy.log records it only if the proxy was started with BD_DEBUG=1. Run SQL with bd sql.
  • bd create --repo <url>'s cached clone still writes the URL into merge commits (#8434).

When 1.4.0 ships, install it by hand. Server-mode bd doctor on rc.3 or rc.4, run in a terminal, also tells you; nothing tells you on rc.1 or rc.2, on an embedded or proxied-server workspace, or when bd doctor runs under an agent, a script or --json.

Changelog

Features

  • ef08cba feat(sdk): route proxied-server workspaces through the bd proxy (GH#8323) (#8558) (#8563)

Bug Fixes

  • 89b5bfe fix(migrate): give proxied-server workspaces a remote-migrate refusal they can act on (bd-5hl9dg) (#8568)
  • b97fce2 fix(migrate): stop promising that reads keep working before a schema migration (#8571)
  • 7c0e969 fix(uow): restore #8571's readOnly comment hunk dropped in the backport resolution

Others

  • 5cd368a chore(release): fold #8568 into v1.4.0-rc.4 notes; date rc.4 2026-11-20
  • cdd563c chore(release): fold #8571 into v1.4.0-rc.4 notes; correct earlier rc notes from the upgrade drill
  • cde822f chore(release): prepare v1.4.0-rc.4
  • f7e572f docs(release): correct rc.4 adopt known issue and --force guidance (#8569 review)

Don't miss a new beads release

NewReleases is sending notifications on new releases.