Select timeout or gtimeout only after a successful GNU coreutils identity probe, validate BEADS_HOOK_TIMEOUT as positive whole seconds, and preserve the Perl and warned direct fallbacks under inherited shell options.
Keep GNU and Perl deadlines soft and backend-scoped, preserve natural status 137, regenerate every tracked hook artifact, and exercise the real process boundary through the required three-host preflight.
Fixes#5503
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
Three beads (ga-uwix0.1, ga-2yaqp.5, ga-2yaqp.6) plus a fable review round.
Docs and spec prose only: all 19 touched .go files are gofmt-normalized,
comment-stripped byte-identical to main. The one exception is deliberate and
reviewed — scripts/check_doc_freshness_test.go gains a data row, because the
delegated gate ruling required it.
ga-uwix0.1 — #5516 gave bd serve optional bearer auth and made it MANDATORY
beyond loopback; fifteen prose sites still said the opposite. The three the
council named are reworded to the stronger true form (the actor is not the
authenticated principal even where a bearer is required; a shared token admits
a client to the WHOLE surface and grants no narrower right). The sweep for a
fourth found eight more in five spellings the audit's grep could not reach,
including claim.go's "any client can claim as any name", release.go's
no-AUTHORIZATION variant, and six memory/settings-plane sites where the true
statement is sharper: a bearer decides WHO may call, never what a caller who
is let in may read. The review round found four more in the CHANGELOG's
UNRELEASED section, which round one had misclassified as released history —
they would have shipped false in the same release as the auth entry.
The serve runbook's "Binding beyond loopback" section was actionably wrong: it
said the flag "prints a warning and changes nothing else", and its refusals
table quoted a string not in the binary. Rewritten against a build, with every
flag, error string, event name and reason value produced by running the
command. It gains the operational trap nobody had written down: /healthz is
auth-exempt and GET /v0/beads/ready is not, so an unauthenticated readiness
probe earns a 401 forever while liveness stays green. The runbook is now IN
scripts/check-doc-freshness.sh, pinned to the four files it is read against.
ga-2yaqp.5 — nine prose defects, every count re-derived rather than trusted;
three of the audit's own numbers had moved again. 38 route rows and 36
capability-bearing ones; thirteen pinned schemas, not twelve or seven; six
missing entries in the no-query-parameter list, not five; twenty-eight role
accessors, not twenty-seven; nineteen patch members, not thirteen. Two prose
"code counts" were counting paragraphs. CodeAlreadyClaimed claimed the holder
is always attached when only one of four producers always attaches it and
releaseIssue never does. MetadataCAS's leaf contradicted its own shipped wire.
The path/operationId inversion is now recorded where a spec author looks.
ga-2yaqp.6 — the role checklist refreshed against what this wave's additions
actually cost, traced to real commits. Step 10 sent people to a name list
#5460 deleted. The "four more edits" claim was stated twice and undercounted
both times: the two freshest wire slices share a nine-file core plus
roles_test.go. The step-with-no-number gained the fact that explains its
instances — write-role decorators wrap, read-role decorators recurse, so the
call lands on the stub, and both real instances are reads. The wave got its
first CHANGELOG entry: six new public operations, not three, and zero new role
accessors in the window.
Review verdict: FIX-REQUIRED then all items addressed. The reviewer
live-falsified the strong auth form and failed to break it, and confirmed
every recount re-derives exact.
Priority used the filled circle also mapped to status-blocked, so agents
misread ready work as blocked (GH#4996). Render P-labels only; document
the convention for agents; keep ● for blocked status alone.
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
`bd show` printed "DEPENDS ON" on an issue that another supersedes, and
"BLOCKS" on its replacement instead of the obvious "SUPERSEDED BY" and
"SUPERSEDES." "BLOCKS" was doubly wrong since supersedes takes no part
in ready-work calculation.
Only blocks, parent-child, related and discovered-from had verbiage of
their own; duplicates, replies-to, tracks, attests and every other type
fell through to a `default: blocks` fallback, while conditional-blocks
and waits-for do block but lost the distinction.
One table now names each type from both ends of its edge and all three
renderers share it.
Type names have no consistent left-to-right reading, so each entry takes
its direction from the command that writes the edge: `bd supersede old
--with new` stores (old, new), making the source the replaced issue.
Same bug elsewhere, also fixed: `bd show --refs` headed groups with the
bare type name, so a canonical issue announced itself as the copy; `bd
dep add` and `rm` said "depends on" whatever the type; `bd dep list`'s
batch header said "X depends on:"; `bd list --deps` had supersedes and
conditional-blocks backwards; and the dependencies doc described
supersedes in reverse.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
BatchCreateOptions.OrphanHandling had four modes and one behavior. Every
production call site passed OrphanAllow (or left the field at its zero
value, which took the same branch), so CheckOrphan returned (false, nil)
on every path it could reach — after paying a SELECT COUNT(*)
parent-existence probe on every hierarchical-ID create to feed a switch
whose only reachable arm ignored the answer.
OrphanStrict and OrphanSkip were reachable from exactly one conformance
case, testAuditCreateOrphanHandling, which existed to execute them.
OrphanResurrect was never a branch at all: it shared the default arm with
OrphanAllow, and the "auto-resurrects missing parents from database
history" behavior its doc comment described left with the JSONL sync
layer. internal/beads' TestImportWithDeletedParent still asserted that
removed behavior; it goes too.
This removes the type, the four constants, the field, CheckOrphan and its
call site, the backend package's alias and re-exports (a breaking change
to a published package, signed off by the owner), the dead
ImportOptions.OrphanHandling, and the import.orphan_handling row in the
yaml-only-key test — replaced with import.unlisted-key, which keeps the
"import.* is exact-match, not a prefix namespace" assertion the row was
actually providing.
The behavior that remains is what OrphanAllow always did: a hierarchical
create whose parent is missing is accepted, and the child's auxiliary
counter row is skipped because it would have no owner
(TestReconcileChildCountersSkipsMissingParent pins that). The wasted
query is gone from the create path.
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
GET /v0/beads/events:watch holds a text/event-stream response open and emits
each committed mutation as it lands, so a consumer learns about a write when it
happens instead of on its next interval. It is a SIBLING of the paged read, not
a mode of it: `follow=true` would have given one operationId two media types,
two lifetimes, two limit rules and two capacity stories, and a client generated
from the document could not have described either.
THE CURSOR IS STILL THE CONTRACT, which is what makes this cheap to publish.
The server keeps no per-consumer state and remembers no subscription; a stream
is the `since` reads a poller would have performed, performed on its behalf
against the same ReadEventsJournalPage through the same read-only cursor. Every
event carries `id: <seq>`, so the checkpoint a client holds while streaming is
the number it would have held while polling, and `Last-Event-ID` — the header a
browser's EventSource resends by itself — takes exactly the value `since` takes.
That header WINS over the parameter, because the client that sends it did not
choose to: an EventSource reconnects to the URL it was built with, so honoring
`since` there would replay every record since the consumer started, on every
reconnect, forever. A nonempty unparseable one is a 400 naming the header rather
than a silent fallback, which would start a stream somewhere the client did not
ask for and never tell it; an EMPTY one means "no id yet" and defers to `since`,
because a client that always sets the header sends it empty on its first
connect and refusing that would break the request the header exists to serve.
Delivery is at-least-once against the client's own checkpoint: exactly once and
in order within a stream, duplicates only across a reconnect. No engine or
storage change — this consumes the poll read path.
EVERY REFUSAL IS DECIDED BEFORE THE FIRST BYTE — validation, the disabled 409,
the flush check, the stream cap, and then the first read, which is what turns a
pruned-past cursor into the paged read's own 410 rather than a 200 that
immediately reports its own failure. Exactly one failure can arrive after the
status is spent: a prune racing an open stream, emitted as a NAMED `truncated`
event carrying the 410's own body in the same encoding on one line (asserted
against Write's output, not merely agreeing with it), behind a raised `retry`
and followed by a close. Naming only the exception is what lets a bare
`onmessage` consumer treat an unrecognized event as "stop, this is not a
record"; one that ignores it does not lose records silently, it stalls loudly on
connect-time 410s, slowly. The other unreportable failure — a stored payload
that will not encode — ends the stream too, and names its seq in the log,
because it will end every stream that reaches that row and nothing else would
say which one it is.
THREE LIMITS HAD TO MOVE, and the middle one is the trap.
- requestDeadline (60s) does not apply to a streaming row. For every other
operation it is the backstop against a request holding resources forever;
here it would do nothing but sever the stream. Each READ carries a 15s
deadline instead — a liveness budget rather than a database one, since it
also bounds how long a stream can go without a heartbeat and how long it can
ignore a shutdown.
- http.Server.ReadTimeout (30s) had to be cleared per request, BEFORE the
connect read. There is no WriteTimeout on this server — statusWriter rolls a
deadline forward before every write, which bounds one stalled write rather
than a stream, and needs nothing here — but ReadTimeout is a deadline on the
WHOLE request, and net/http keeps a background read running while a handler
writes: the read that notices a disconnect. Its expiry cancels the request
context, so an idle stream would end itself at thirty seconds with no client
involved, and a database wedged during the connect read would be booked as
`client_closed`. Clearing it costs no disconnect detection — a client that
leaves still produces a read error — and a peer that vanishes without a FIN
is reaped by TCP keepalive, which Go's listener enables by default
(measured: 15s idle, 15s interval, 9 probes; ~150s).
- The database slot moves from the request to the read. Sixteen slots and
forty-eight stream places means one slot per open stream would let a handful
of idle consumers starve every other operation for hours with /healthz
green; a stream now takes a slot for the moment of each poll and gives it
back, and slot pressure delays a pass instead of ending a stream.
Streams are capped at 48, SIXTEEN BELOW the 64-connection limit, and the gap is
load-bearing arithmetic rather than caution: LimitListener returns a connection
slot only when the connection closes, which is after the handler returned and
after this counter came down, so a cap at maxConns could never be observed — the
connect that should earn the 503 would never be accepted, and neither would the
poll it is told to fall back to, nor a mutation, nor a fresh-connection
/healthz. The headroom makes the refusal deliverable; `events_watch_admitted`
carries the live gauge on every connect so accumulation is visible before the
cliff. Each stream jitters its own poll phase by ±10%, because consumers
reconnect together after a restart on one shared `retry` and a fixed interval
would march them into a single read burst per second forever. And a graceful
shutdown signals its streams (RegisterOnShutdown) rather than waiting them out;
the loop consults that signal and the client on EVERY pass, including the
draining ones, so a week-old backlog stays cancellable within one batch.
Tests: handler-level over live delivery (mutations land AFTER the connect),
id=seq, heartbeats, Last-Event-ID precedence including a stale header against a
live `since` and the empty-header polarity, the 400/409/410 connect legs, a
prune under an open stream, the cap and its 503, the cap's headroom against
maxConns, backlog drains cancelled by both a hangup and a shutdown, slot release
on every exit, a stream sharing a single-slot semaphore with a paged read, the
flusher refusal, the read-deadline clear and its ordering against the connect
read, jitter spread, and a clean drain with a stream open — all under -race.
Framing is pinned against a record whose payload carries literal newlines, a CR
and a `data:` line of its own. Two e2e legs through a real `bd serve`: mutate on
one connection while streaming on another under a 10s arrival bound, then
reconnect with Last-Event-ID and require the resume, plus the disabled refusal.
Mutated and each caught: the mid-stream truncated event, Last-Event-ID
precedence, the empty-header polarity, the cap decrement, the cap's headroom,
the drain-cancel fast path, the read-deadline clear and its ordering, the poll
jitter, the shutdown exit, and the deadline exemption.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
GET /v0/beads/events pages the durable mutation journal from a caller-held
checkpoint, so a hosted consumer stops shelling out to `bd events tail`. The
journal and its retention contract already landed; this is the consumption
surface for them.
THE RECORDS ARE THE CLI'S RECORDS, and that is a machine fact rather than a
promise. The envelope and its projection moved out of cmd/bd into
internal/eventsjournal, beside the activation and auto-prune logic that already
had to be reachable from two binaries; the spec pins EventRecord to that struct
with x-go-type, pinning.go proves the generator emitted an alias, and the
committed golden fixture now renders through the same function the handler
serves from. A second wire struct in internal/httpapi would have passed its own
tests while quietly shipping a different `ts` shape or a `dep` that appeared
when empty, and the consumer who notices is the one reconciling an HTTP mirror
against a CLI export.
THREE ANSWERS THE DATA CANNOT TELL APART, which is most of the design:
- CAUGHT UP is a 200 with an empty list. "Nothing new yet" is an ordinary
answer about a log, and a poller whose steady state was a 404 would have to
treat this surface's miss vocabulary as its happy path.
- DISABLED is a 409 `events_journal_disabled`. A journal that is off reads as
zero rows and a head of zero — byte-identical to an enabled journal nothing
has written yet — so without this gate a consumer would poll a workspace
that will never emit a record and call itself caught up forever. Activation
is workspace state, so it is resolved by cmd/bd (eventsjournal.EnabledFor)
and handed in; this package resolves no workspace state of its own. A 409
for CodeNotClosable's reason: a statement about state the client cannot see,
which the same request stops earning once an operator changes it.
- PRUNED PAST is a 410 `events_journal_truncated` carrying `since`, `floor`
and `head`. It is the surface's only 410 and it is the right one: those
records existed, were addressable by exactly this request, and were
deliberately deleted — retrying the same `since` can never succeed, which is
what a 404 would wrongly invite. The mapping lives in ClassifyError, keyed
on the typed error with errors.As, so neither database source can forget it;
the code is storage's own constant, so the CLI's `--json` failure and this
body cannot drift to two spellings of one condition.
`head` is why the read seam grew. ReadEventsJournal answers what came next and
cannot answer "keep asking, or wait?", so ReadEventsPageInTx returns the rows
and the counter head from ONE transaction, read in that order — a head taken
first could land below the last row served, which a consumer reads as "past the
end" and stalls on. `bd events tail --follow` keeps the cheaper path: it runs
the truncation decision every second and pays for a head read only in the
ambiguous cases.
The handler holds storage.EventsJournalCursor, a read-only interface, not the
wider accessor the CLI takes. There is no prune, no acknowledge and no
truncate over HTTP: retention stays a workspace decision, and a surface
documented to publish the journal should not be one line from a delete.
EventsJournal is the first CONDITIONAL role on httpapi.Config — required
exactly when the workspace's journal is enabled. A storage backend with no
journal seam is an ordinary backend as long as nobody asked it to record
anything (eventsjournal.Apply takes the same deal at open time), and demanding
it unconditionally refused to start two registered-backend servers that had no
use for it.
`limit` runs 1..10000 defaulting to 1000, and `0` is REFUSED rather than
meaning unlimited as it does on the issue listings: a caller resuming from an
old checkpoint would otherwise ask one process to buffer the whole retained
window. `since` is required — defaulting a missing checkpoint to zero serves
the entire window to a consumer that meant to resume, which arrives as a flood
of duplicates rather than as an error.
Tests: handler-level over both refusals, the caught-up/empty/disabled trio, the
limit bounds and an int64 checkpoint; a storage-level head guard against the
real embedded store; and three end-to-end legs through a real `bd serve` —
mutate over HTTP then read the journal back gapless, prune and meet the 410 then
recover from floor-1, and a disabled workspace refusing. The truncation mapping,
the disabled gate, the window members and the limit ceiling were each mutated
and each failed a test.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
Enabling the journal now yields a BOUNDED feed. Until this commit the only
thing that deleted a record was an operator typing `bd events prune`, so the
person who turned the feature on was not the person who discovered, months
later, that a table nobody reads had become the largest thing in the database.
Retention floors already described the window a consumer is guaranteed; this
applies them without being asked.
The shape is SQLite's WAL auto-checkpoint rather than a background compactor,
with Dolt's auto-GC as the second reference: the WRITER pays, immediately after
its own commit, only when a cheap persisted threshold says work is due, and
never for more than a fixed slice of it. Neither needs a daemon, and neither can
turn a user's command into an unbounded wait. Only the trigger and amortization
pattern transfer — the journal needs no finalization data movement, so our
checkpoint analog is pure prefix deletion.
POLICY IS THE FLOORS, and it is not a second implementation.
ComputeEventsAutoPruneBoundInTx hands the EXISTING resolver an unbounded request
(before = head+1) and keeps whatever the floors leave, through the same two
scalar reads `bd events prune` uses — now factored into one place so a floor
cannot mean one thing when an operator asks for it and another when maintenance
applies it. Both floors disabled means the operator chose an unbounded ledger,
and auto-prune becomes a no-op that does not even read the throttle.
TRIGGER is the root PersistentPostRunE maintenance net, last after Dolt
auto-commit, auto-backup, auto-export and auto-push, before the store closes.
That is the narrowest existing seam with the four properties this needs: the
command succeeded (cobra never reaches PostRunE on an error return), its
transaction is closed, a plumbing is still open, and the read classification is
already made there. It fires at most once per process. Four gates keep it
writer-pays, each one load-bearing rather than decorative: the post-command
maintenance policy (strict --readonly, `bd serve`); the read-only
classification, without which `bd list` prunes the journal, since a read-only
classification still opens a writable store; preview commands (--dry-run,
--inspect), which promised not to mutate and are held to it by a
write-refusing open; and the whole `bd events` family, because reading a feed
must never be what prunes it and `bd events prune` has just resolved the bound
by hand. `bd events tail` joins the read-only classification while it is at it
— it is a pure read that had been opening a writable store. Both write
plumbings are covered: the store path and the proxied-server unit-of-work
provider, which commits maintenance in the ephemeral form (no Dolt commit) that
dolt_ignored tables require.
`bd serve` has no command boundary, so it drives the same routine from a ticker
with a clean, self-contained shutdown. It reads the same persisted watermark
every CLI process reads, so a server and the CLIs beside it share one schedule
rather than three.
EXECUTION is its own transaction per batch: `DELETE ... WHERE seq < ? ORDER BY
seq ASC LIMIT 10000`, at most 3 batches per pass, all of it under a 30-second
pass budget and on NO-RETRY transactions. Maintenance is humble by
construction: the retry helper a user's write deserves would spend up to
fifteen seconds of backoff per transaction losing races on work nobody asked
for, and a maintenance transaction that loses a race has nothing to recover —
the prefix delete is idempotent and the next trigger resumes. ORDER BY is not
decoration —
without it a limited delete may remove an arbitrary subset, and a hole above the
floor is silent loss the left-edge truncation check cannot report. Verified
against the real engine that Dolt accepts the ordered, limited single-table
delete. A backlog larger than one pass drains over the next few commands instead
of stalling this one. Every failure is logged and swallowed: maintenance must
never fail a user's command.
THROTTLE is a watermark (ts + head) in local_metadata, the clone-local ignored
plane, read together with the seq counter in ONE query — the not-due answer, the
overwhelmingly common one, costs a single indexed lookup. Due means an hour
elapsed or 5k records advanced; both are constants, because they tune how often
maintenance amortizes rather than promising anything. A stamp far in the FUTURE
(a clock stepped forward and later corrected) also reads as due, or the
interval trigger would never fire again on a workspace that looks healthy. The
watermark is stamped BEFORE the deletes, in a transaction of its OWN, so a
persistently failing prune degrades to no maintenance rather than to a retry on
every command — sharing that transaction with the bound read, as the first cut
did, rolls the stamp back with the failure and reinstates exactly the
per-command penalty the ordering exists to prevent. Racing processes are
idempotent: a prefix delete that already happened is indistinguishable from one
that just did. A workspace with the journal off pays nothing at all.
CONFIG: `events-journal-auto-prune`, default true, BD_EVENTS_JOURNAL_AUTO_PRUNE,
a config.yaml startup key like the other three (YamlOnlyKeys — without that entry
`bd config set` reports success and changes nothing; all four are also added to
the recognized-key set, so the documented opt-out no longer prints an
unrecognized-key warning beside a command that worked). The resolver now reads
the YAML 1.1 boolean spellings, which is a data-deletion fix rather than a
nicety: an unreadable value falls through to the key's DEFAULT, so
`events-journal-auto-prune: no` had read as "keep pruning" — an opt-out that
went on deleting the records it was written to preserve. Its two resolution
arms (no workspace yet, and a resolved workspace) now agree on an unreadable
value instead of splitting false/true. Manual `bd events prune` remains for an
earlier, on-demand cut below the floors; physical disk reclaim still rides
`dolt gc`.
SCOPE: a pass maintains the workspace whose command triggered it. A routed
write (`bd create --repo ../other`) journals into the target, but the trigger
runs against the launcher's own workspace and plumbing — one command must not
open maintenance transactions on every database it wrote to in passing — so a
workspace only ever written remotely relies on commands run in it, or on its
own `bd serve`. Stated in the docs rather than papered over.
Consumer safety is unchanged. ComputeEventsPruneWhere, the truncation contract
and the seq counter are untouched; deletion is still prefix-only and still
bounded by the floors, and a laggard still gets the typed truncation error.
Docs corrected, because four places said the opposite:
- docs/reference/events-journal.md: "manual to prune" in the opening, and
"Pruning is manual. Nothing deletes journal records on your behalf." at the
head of the retention section, which is rewritten around the new default;
the config table gains the key and stops attributing the floors to the CLI
command alone.
- cmd/bd/events.go: `bd events prune` said "Pruning is manual: nothing deletes
journal rows on your behalf"; it now says retention is enforced to the
floors automatically and this command is for an EARLIER, on-demand cut
BELOW the floors — it cannot cut deeper than they allow, so shrinking the
retained window means lowering them. `bd events` gains the same summary.
- CHANGELOG.md: "Pruning is manual — nothing deletes journal records on your
behalf" replaced by the bounded-by-default story, including the volume
trigger and the per-workspace scope.
- internal/config/config.go and internal/storage/issueops/journal_prune.go:
floors are no longer described as belonging to `bd events prune`.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
Adds docs/reference/events-journal.md: what the journal is (a durable,
replayable, clone-local record of committed mutations), how to enable it,
the record contract and its seven ops, the typed truncation error and how a
consumer recovers, manual pruning and the retention floors, the boundaries
(per replica, per branch, sync/raw SQL/store-open/compaction non-coverage),
and how the dolt_ignored tables sit in Dolt.
Every technical claim is derived from the code on this branch — cmd/bd
events help text, the issueops journal engine, the migrations, and the
config defaults — and states the same contract the CLI help does.
It lands in Reference rather than Core Concepts because the page specifies a
machine-facing contract rather than teaching the bead/dependency model; it
sits beside the JSON output contract and observability, the two other pages
an integrator reads. A short orientation section separates the three
event-ish systems (script hooks, audit history, the journal) so a reader
picks the right one, and reference/advanced.md no longer claims there is no
`bd events` command.
CHANGELOG records the new commands, the opt-in journal and its three config
keys, the events_journal_truncated failure mode, and is_blocked joining the
documented /v0 issue schemas.
Both the page and migration 0064's down script also record the one destructive
outcome that raises no error: dropping and recreating the journal tables, or
losing bd_events_seq, restarts the sequence space at 1, so a parked consumer's
checkpoint sits above the new head and reads as "caught up" forever. Nothing
about the new journal looks pruned, so the typed truncation error cannot report
it — the only remedy is to re-baseline, and the only defence is saying so where
someone will be standing when it happens.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
Both files had their Last reviewed markers refreshed today without the content
gaps being closed, so the freshness signal is currently green on two docs that
are missing real material.
azure-devops.md — `ado.reconcile_interval` is undocumented. It is real,
user-tunable config (internal/ado/reconcile.go, default 10) setting how many
syncs pass between automatic reconciliation scans, and the doc already documents
the `--reconcile` flag that forces one. Adds a Reconciliation section, and notes
that `ado.syncs_since_reconcile` is beads' own counter rather than a setting.
otel-data-model.md — claims a complete schema but lists 7 of 111 storage spans,
so the issueops role surface is invisible to anyone instrumenting from it.
Rather than 100+ prose sections that would drift again, state the rule the code
follows — span name is "storage." + operation name, which is also the
db.operation attribute (InstrumentedStorage.op) — and inventory both families:
72 direct storage.<Method> spans and 39 storage.<Role>.<Method> spans.
Also records why the families do not double-count: the role decorators wrap the
UNINSTRUMENTED store (IssueLifecycle calls Unwrap() before wrapping), so one
logical operation emits one span on either path and the counters stay
comparable.
No behaviour change; documentation catching up to the code.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs: re-review and bump the three 90-day-stale freshness markers
azure-devops.md, json-schema.md, and otel-data-model.md all carried
Last reviewed: 2026-05-08 — exactly 91 days old today, so the doc-flags
freshness gate went red on every branch at once. Each doc was genuinely
re-reviewed against its Freshness source paths on main; drift found and
fixed:
- azure-devops.md: proxied-server mode note (ado sync/status/projects
hard-error there); --parent and --project flags documented; duplicate
--issues row dropped; real ado.org error text quoted; ado.pat's
yaml-only secret storage noted. Source bug found during review filed
separately: the cmd-level config reader cannot see a yaml-only PAT,
so the documented Quick Start fails on main (bd-wvf77).
- json-schema.md: bd show/close/update --json return top-level ARRAYS
(contract-test-pinned); jq recipes fixed accordingly; envelope
pagination key documented; show's always-present revision field and
import's unchanged counter added; error envelope (optional code/hint,
envelope-mode shape, stdout paths, exit 1) corrected; deprecation
notice's tty-only condition noted.
- otel-data-model.md: hard opt-in via BD_OTEL_ENABLED + standard OTel
SDK env vars (BD_OTEL_* legacy); console-only trace export; dolt span
attrs (shared doltSpanAttrs, dolt.remote, dolt.force_push,
dolt.conflicts, dolt.merge_with_strategy); facade-wave storage role
spans; seven new Dolt metrics; AI attrs (bd.ai.duration_ms, 4-attempt
retry); appendix re-pinned to current main.
scripts/check-doc-freshness.sh passes locally.
* docs(otel): complete claim_verify_lost op label enumeration; qualify retry policy as compact-only
Review findings on #5394: op also takes guarded-update
(claim_verify.go:113) and ready-claim (issues.go:439); the retry-policy
sentence describes compact's loop, find_duplicates makes one unretried
call.
* Add sealed-copy SQLite migration bridge (bd-mvh)
Create a fresh current workspace from a fingerprinted copy of an authenticated historical SQLite workspace. Keep every historical executable inside an isolated destination and reject malformed or semantically lossy cutovers without touching the source.
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Test User <test@test.com>
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of CI Bot
* Refuse implicit historical workspace upgrades (bd-mvh)
Detect historical SQLite and legacy Dolt layouts before config migration, version tracking, init, bootstrap, doctor, or store construction. Require the sealed-copy bridge while preserving current shared-server admission against the explicitly selected workspace.
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Test User <test@test.com>
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of CI Bot
* Qualify authenticated historical upgrades (bd-mvh)
Replace generic recipe discovery with a fixed, checksum-pinned corpus spanning the reviewed SQLite, server-Dolt, and embedded-Dolt eras. Assert source isolation, representative data fidelity, schema idempotence, and rollback retention while keeping historical executables inside bounded temporary environments.
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Test User <test@test.com>
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of CI Bot
* Add authenticated legacy SQLite reader (bd-tku)
Let the current binary read the exact v0.49.6/v0.50.3 SQLite contract from a sealed private DB/WAL copy and emit canonical JSONL for the normal fresh-Dolt import path. Reject schema drift and values that current import would lose, default, truncate, or deduplicate.
Qualify both authentic releases end to end, including current DATETIME(0) canonicalization and reader-to-fresh-import timestamp equality.
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of CI Bot
* Fix empty embedded-root upgrade bypass (bd-e6m)
Require an actual embedded Dolt repository marker before current layout precedence can suppress historical SQLite or legacy Dolt refusal.
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of CI Bot
* fix(migrate): maintainer review fixups for legacy SQLite upgrade PR
- decompose the legacy-workspace guard and extract the dependency-row loader
(behavior-preserving), and align the legacy SQLite reader projection with
issueops.ScanIssueFrom arity after the 0060/0061 rebase, guarded by a
projection arity test.
- assert the historical-upgrade harness schema no-op by shape
("Schema already at v<N>") instead of a hardcoded v59, so the migration-test
matrix stops reddening on every schema bump (candidate now prints v61).
* Fix historical upgrade review blockers (bd-mvh)
Route direct SQLite lanes through the current authenticated reader, guard no-store commands before legacy workspace mutation, and move coarse embedded repository detection behind the storage adapter. Restore the legacy reader projection contract and verify source-preserving behavior across the repaired paths.
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of CI Bot
* Fix historical upgrade edge cases (bd-mvh)
Refuse ambiguous local server-Dolt roots before storage opens and normalize nullable legacy SQLite sentinel fields during authenticated export.
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of CI Bot
* Fix final historical upgrade review blockers (bd-mvh)
Make explicit server selection outrank stale embedded repository markers, so ambiguous local server roots still fail closed.
Permit zero-record cutovers only through the authenticated direct SQLite reader, verify the empty round trip against a fresh current export, and align the upgrade guidance with the enforced admission matrix.
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of CI Bot
---------
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Test User <test@test.com>
* fix(export): promoted no-history wisps survive import round-trip (bd-r9uce)
A promoted no-history wisp is a durable issues-table row that still
carried no_history=true (PromoteFromEphemeralInTx cleared only
Ephemeral), and both import routes inferred the storage plane from row
flags (issueops.IsWisp: Ephemeral || NoHistory). Importing an export
stream containing such a row silently re-planed it into the wisps table,
dropping its cross-plane relations as cross-bucket dependencies on the
way — classic-mode data loss across export->import->export.
Belt and braces, per triage + the #5351 review endorsement:
1. Promote clears NoHistory too (and normalizes an explicit ephemeral
StorageClass to empty, the NormalizePersistenceMode promotion rule):
a promoted wisp is fully durable and the flag has no post-promotion
meaning.
2. Import routes the plane by an explicit marker, never by no_history.
Export stamps "wisp": true on rows that live in the WISPS table and
whose flags alone cannot prove it (the no_history shape; ephemeral
rows self-describe), classified by table membership via a new
PartitionWispIDs store capability (classic: batched wisps-membership
query behind an Unwrap walk through the telemetry/hook decorators;
proxied: the plane-pinned GetWispsByIDs read). Both parse loops
(bd import in both storage modes, bootstrap/init/auto-import) resolve
the plane through one shared helper, applyImportWispPlane, which pins
marker-less no_history records to the durable plane via a new
non-serialized Issue.WispPlaneOverride consulted by IsWisp. The
no_history flag itself is preserved on the row, keeping the
export->import->export byte-identity for wild data; the legacy
v0.35-v0.37 "wisp"-as-ephemeral alias behavior is unchanged.
Tests: the promoted shape now lives IN the proxied round-trip fixture
(cross_mode_byte_identical covers it, with relations); a classic-mode
round-trip test (fails on base: cross-bucket dependency drop + missing
plane marker); a proxied import plane-routing subtest; embeddeddolt pins
for promote clearing NoHistory and PartitionWispIDs membership
classification.
* docs(schema): document the export stream's explicit wisp plane marker (bd-r9uce)
* fix(export): fresh wisp_plane marker key — legacy-alias reuse was lossy under rollout skew (bd-r9uce)
Adopts lion's #5368 review recommendation: pre-fix v0.38+ binaries' alias
branch (hasWisp && !Ephemeral => Ephemeral=true) would import a marked
genuine no-history wisp as ephemeral — purge-eligible and excluded from
that rig's next export — making the common skew case lossy. A fresh key
degrades to flag routing on older readers, data-safe in both directions.
Legacy 'wisp' read alias preserved verbatim.
* fix(storage): clone WispPlaneOverride in cloneIssueForHook (bd-r9uce)
The hook snapshot guard (TestCloneIssueForHookCoversReferenceFields)
correctly flagged the new *bool field as uncloned: a hook mutating the
snapshot could alias the live issue's plane pin. Deep-copy it and add
it to the guard's covered-fields manifest.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FZXjihTayFcngYzo6xPd3p
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* refactor(telemetry): adopt standard OpenTelemetry SDK env vars with explicit BD_OTEL_ENABLED gate
Telemetry configuration moves from BD_OTEL_* data variables to the
standard OTEL_* environment variables. Activation now requires
BD_OTEL_ENABLED=true so a machine-global OTEL_* setting (for some other
instrumented tool) cannot silently turn bd telemetry on.
The resource picks up resource.WithFromEnv() so OTEL_SERVICE_NAME and
OTEL_RESOURCE_ATTRIBUTES take effect — users can override service.name
or stamp deployment.environment without forking.
Backwards compatibility: BD_OTEL_METRICS_URL, BD_OTEL_LOGS_URL, and
BD_OTEL_STDOUT continue to work and activate telemetry on their own.
Each translates to its OTEL_* equivalent unconditionally — a legacy
value wins over a pre-existing OTEL_* value so cross-tool environments
don't redirect bd traffic. Every invocation that sees a BD_OTEL_*
variable logs a one-line deprecation warning to stderr.
OTLP endpoint discovery is delegated to the SDK; the explicit URL
helper in internal/telemetry/otlp.go is removed.
OTEL_SDK_DISABLED=true forces telemetry off even when an opt-in is in
effect, matching SDK conventions.
Tests cover: legacy var translation + override semantics, master-switch
activation, OTEL_*-alone-doesn't-activate, OTEL_SDK_DISABLED override,
WithFromEnv resource attribute merge, deprecation warning emission, and
otlpMetricsEndpointSet detection (specific endpoint, generic endpoint,
negative).
Part of the gastownhall/beads PR #3475 split: isolates the OTEL_* env
var standardisation from the WrapStorage wiring (#3858) and the
bd.prefix attribute work (separate follow-up).
* refactor(cmd/bd): extract command-telemetry wiring into testable helpers
cmd/bd/main.go's PreRunE block contained two pieces of OTel wiring —
telemetry.Init and the bd.command.<name> root span construction — that
silently decay if a future refactor drops them. Same regression class
as the WrapStorage bug (telemetry implemented but never called) —
wiring buried in cobra PreRunE escapes review.
Extract two helpers in cmd/bd/command_telemetry.go:
- commandSpanAttrs(cmdName, version, args): pure function returning
the initial attribute set for the bd.command.<name> span. The
bd.actor attribute is stamped later via SetAttributes once
getActorWithGit() resolves.
- startCommandTelemetry(...): composes Init + Tracer.Start. Single
callable line in main.go.
Three tests cover the commandSpanAttrs output (full attrs and the
empty-args edge case) and the startCommandTelemetry wiring contract:
it must always return a non-nil context and span, since the
bd.command.<name> span is the parent for every storage and AI span
downstream — silently returning nil would break trace nesting across
the whole invocation. Whether the span actually records is governed
by telemetry.Init which is covered in internal/telemetry/telemetry_test.go.
main.go shrinks by 10 lines.
* fixup(cmd/bd): stage command_telemetry.go split omitted from merge commit
The previous merge commit (def9f97a4) resolved main.go's PersistentPreRunE
conflict to call initTelemetry()/startCommandSpan() but the working-tree edit
to cmd/bd/command_telemetry.go that defines those two helpers was never
staged, so the merge commit as recorded does not compile:
cmd/bd/main.go:680:3: undefined: initTelemetry
cmd/bd/main.go:706:26: undefined: startCommandSpan
This stages that omitted edit: command_telemetry.go now defines
initTelemetry (the Init half) and startCommandSpan (the span-start half,
using commandSpanAttrs) as separate functions, with startCommandTelemetry
kept as their combined form for callers/tests that don't need to interleave
other setup between the two steps. See the merge commit message for why the
split is necessary (main's usage-metrics bootstrap block sits between the
two steps for one internal subcommand).
Verified: CGO_ENABLED=0 go build -tags gms_pure_go ./... now succeeds.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(telemetry): gate the OTLP metric exporter on OTEL_METRICS_EXPORTER
A console-only or none selection — including the legacy BD_OTEL_STDOUT=true
translation — previously still installed an OTLP reader whenever a
machine-global OTEL_EXPORTER_OTLP_ENDPOINT existed, silently exporting bd
metrics to an endpoint configured for some other tool. The selector is now
parsed per the SDK spec (comma-separated; unset defaults to otlp; none
disables) and the OTLP reader requires the selection to include otlp.
The BD_OTEL_STDOUT translation keeps both destinations when
BD_OTEL_METRICS_URL is also set (console,otlp), preserving the existing
both-exporters behavior for that combination.
Also bound the test-cleanup Shutdown with a 2s context so suites configured
with unreachable endpoints (example.invalid) don't spend ~30s in OTLP
retries.
Both issues found by a cross-vendor (Codex) review of the rebased branch.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
repo = "{{var}}" in a formula gate step is substituted at pour time (bd mol
pour --var ...), not at cook --persist time; and bd gate discover requires a
workflow name hint for a cross-repo gate and ignores the local branch filter
unless --branch is passed explicitly.
Agent-Signature: claude-sonnet-5-medium on behalf of matt wilkie
- Delete queryGitHubRuns (unreferenced since queries are scoped per-repo).
- docs/workflows/gates.md: metadata.repo inheritance on an ad-hoc gate created
with `bd gate create` only applies to gh:run/gh:pr gates (SF4); reword to
say so instead of implying it for all gate types.
- createGateIssue wrote {"repo":...} metadata for any gate type; gate it with
the same isGitHubGateType helper repoMetadataForGate (SF4) already uses, so
a repo field on a human/timer/bead gate step - unrelated, ordinary metadata
for those types - is not mistaken for a GitHub repo selector.
Agent-Signature: claude-sonnet-5-medium on behalf of matt wilkie
createGateIssue built the gate issue directly without copying any
metadata, and formula.Gate had no field for it, so the declarative
cross-repo gate configuration documented for ad-hoc `bd gate create`
gates ("set the gate's string metadata.repo value") had no formula
equivalent. Add Gate.Repo (json/toml `repo`), thread it through
variable extraction and pour-time substitution alongside the other
gate fields, and propagate it onto the created gate issue's metadata
in createGateIssue. Validation of the value stays at check time
(githubRepoFromIssue), matching how any other gate's repo metadata is
validated. Document the new field in docs/workflows/gates.md.
Agent-Signature: claude-sonnet-5-medium on behalf of matt wilkie
* fix(reset): a comment is content when the question is deletion
GH#5221 stopped `bd admin reset` from deleting hooks it never installed, but
left one path open. classifyResetHook decides a sectioned hook by stripping
bd's block and asking isOnlyShebangOrEmpty whether anything remains — and that
predicate, by its own documented design, treats every comment as nothing.
So a hook of the user's whose own content is a shebang plus comments — a header
they wrote, a note to whoever edits it next, a lint step they commented out for
now — strips to "empty", classifies hookBdOwned, and is deleted whole. There is
nothing to restore it from: performReset renames <hook>.backup back into place,
and a backup exists only for hooks bd itself displaced, which is never the case
for a hook bd only injected a section into. A comment was once again enough to
make a hook bd's to delete, which is the failure GH#5221 exists to close.
The looser predicate is right where it lives. shouldPreserveHookContent is
deciding whether to COPY a hook forward into .beads/hooks, and declining to
carry a comment-only file loses a comment out of a file that still exists on
disk (GH#3536). Reset is deciding whether to DESTROY the file. The two
questions differ in what being wrong costs, so they no longer share an answer:
isOnlyShebangOrBlank counts only the leading shebang and blank lines as
nothing. It anchors the shebang on the first non-blank line rather than on
index 0, so it does not depend on whether stripping bd's section left a blank
line above it, and a second `#!` further down is read as the comment it is.
The divergence is deliberate and one-way, so both tests that could hide it now
say so. TestClassifyResetHook_AgreesWithHookPreservation keeps the arm that
matters — what preservation calls the user's, reset must not delete — and
replaces its converse with the weaker claim that still needs pinning: reset may
never call a marker-carrying file none of bd's business, or a hook bd wrote
survives a reset unremoved and unreported. TestResetEmptinessPredicateIsStricter
ThanPreservation pins the gap between the two predicates directly, so a later
cleanup that notices they answer "the same" question and collapses them into
one fails here instead of quietly restoring the deletion.
Verified the fix is load-bearing: pointed classifyResetHook back at the old
predicate and the three new cases fail (both classify cases, and the
collectResetItems case in both directions — removed when it should be kept,
absent from the preserved report when it should be named).
Agent-Signature: claude-opus-5-high on behalf of maphew
* docs(uninstall): stop handing out an rm -f batch under a "check first" warning
GH#5221 added a warning above the manual-cleanup hook deletions telling the
reader that these are the standard git hook names, that any of them may be a
hook they wrote, and to check each file before deleting it. It then left the
five unconditional `rm -f .git/hooks/<name>` lines directly beneath it, inside
the same copy-pasteable fence.
A warning that is followed, in the same block, by the commands that do the
thing it warns about is not a safeguard. Anyone treating the fence the way
fences in this document are meant to be treated deletes all five hooks and
reads the reason afterwards. Someone in this section has already lost the
command that could tell the difference for them.
So the hook step is no longer a batch. A read-only grep lists which of the five
exist and which carry a beads marker, and the disposition is then per file:
delete the ones beads generated whole, edit the block out of the ones that are
yours, leave the rest. `rm -f .git/hooks/<name>` appears once, with a
placeholder, in a sentence about a file the reader has just opened.
The per-file rules are the ones the code applies, including the case the
accompanying commit fixes: a hook that is your header comment plus beads'
block is yours to edit, not beads' to delete.
`bd dolt stop` and the `.beads` / worktree removals stay executable; those are
beads' own state, not files that might be the user's.
Agent-Signature: claude-opus-5-high on behalf of maphew
* fix(reset): decide hook deletion from provenance, not the word "beads"
`bd admin reset --force` deletes git hooks it believes bd installed. isBdHook
decided that by scanning the first ten lines for the substring "beads" —
anywhere, in any context. A comment, a path, a call to another tool: any of them
made a hook bd's to delete.
The repository's own tracked .githooks/pre-commit is such a file. It is composed
by hand, carries guards bd knows nothing about, and says "the beads section at
the bottom must run for non-Go commits too" on line 9. The old scan matched that
comment and would have removed the whole file. Nothing brings it back:
performReset's restore path renames <hook>.backup into place, and a backup
exists only for hooks bd itself displaced, so a hook bd never installed is
deleted with no restore.
The same scan was wrong in the other direction too — a marker past the tenth
line was invisible — but that failure is merely untidy, and this one loses work.
Provenance is not something reset has to guess at. bd writes markers when it
installs (hookVersionPrefix, shimVersionPrefix, inlineHookMarker) and wraps
injected blocks in section markers, and preservePreexistingHooks already has a
worked-out model of what those mean (GH#3536). classifyResetHook uses the same
markers and the same rules, and returns three states rather than a boolean,
because "bd installed this" and "bd may delete this" are different questions:
hookBdOwned bd wrote the whole file; removing it restores the
state before bd touched the repo.
hookUserOwnedWithBdSection the user's hook with bd's block injected. The file
is theirs. Reset reports it and leaves it.
hookNotOurs no marker. Not ours to remove or to mention.
The middle state is the one the old boolean could not express, and it is not
rare: it is what every marker-managed install since v0.49 produces. Under the
old code such a hook was deleted whole whenever "beads" fell inside the first
ten lines — which the generated section itself guarantees when it lands near the
top, since its second line reads "# This section is managed by beads."
Preserved hooks are reported in both the preview and the --force path, and in
--json as a "preserved" key. Saying nothing would leave the user believing a
reset removed a beads integration that is in fact still live in their hook.
Tests cover each state, both directions of the old first-ten-lines window, and
the missing-file case. TestClassifyResetHook_AgreesWithHookPreservation pins the
invariant across the two functions that decide this independently: if
shouldPreserveHookContent would carry content forward, reset must not delete the
file, and vice versa. It runs over the repo's own .githooks so the inputs are
hooks a person actually wrote, and asserts the agreement rather than a verdict
per file, so editing those hooks cannot make it lie.
Agent-Signature: claude-opus-5-high on behalf of matt wilkie
* docs(uninstall): stop telling users reset removes hook sections
Two claims in docs/recovery/uninstalling.md do not match what the code does,
and both point the same way — at deleting a hook file that is the user's.
The reset section said `bd admin reset` removes "beads-managed git hook
sections". It has never worked on sections; it removes whole files. With the
ownership check in this branch it removes only files beads generated in full,
and reports the ones it left alone, so say that instead.
The manual-cleanup section is worse: it hands the user five unconditional
`rm -f .git/hooks/<name>` lines. Those are the standard git hook names, not
names beads reserves, so any of them may be a hook they wrote — and the section
directly above it explains that `bd hooks uninstall` is preferable precisely
because beads preserves content outside its markers. Someone who reaches
manual cleanup is already in the case where the safe command did not work.
Name the markers so the check is something a reader can actually perform, and
say what to do with a hook that only has a beads block in it.
Agent-Signature: claude-opus-5-high on behalf of matt wilkie
The reporter uninstalled beads by hand (`rm -rf .beads/`) and was left with
git config still pointing core.hooksPath at the directory they had just
deleted, plus a stale beads.role. Nothing told them so: none of the three
registered hooks checks tests whether the configured hooks path still exists,
and `.beads/` reappearing on checkout made it look like beads was
reinstalling itself. It is not — post-checkout runs the JSONL import, which
initialises an embedded-dolt workspace under the old prefix as a side effect
(GH#4440).
Of the reporter's three suggested fixes, one was already implemented and did
not help them, because it only runs when you use the command they did not
use. The other two are here.
- New "Hooks Path" doctor check: warns when core.hooksPath resolves to a
directory that does not exist, naming both the configured value and the
resolved path. `bd doctor --fix` unsets it — but only when it is one of the
values bd itself writes. A third-party hooks path (husky and friends) is
reported and left alone; FixHooksPath re-reads and re-checks both
conditions immediately before acting, so a stale check result cannot cause
it to touch someone else's config.
- `bd hooks uninstall` now also unsets beads.role, and a config reset that
fails is returned as an error instead of a scrolling stderr warning. It no
longer reports success while beads-managed config is still set. beads.role
is read before it is unset rather than treating git's exit 5 as "already
absent": exit 5 also means "refusing an ambiguous unset" on a duplicated
key, and conflating the two would report a clean uninstall with the key
still there.
- docs/recovery/uninstalling.md's Manual Cleanup gains core.hooksPath, with
the reason, and the caveat that it is not a beads-only key.
KNOWN GAP, stated plainly: bare `bd doctor` is gated off in embedded mode by
deliberate policy (GH#3794, doctor.go), and embedded is the default and the
reporter's mode — so the new check does not yet reach the users most likely
to hit this. Lifting that gate is a human-vetted decision per the policy
comment and is deliberately not made here. The uninstall and documentation
changes are mode-independent and do help them.
Agent-Signature: claude-opus-5-high on behalf of matt wilkie
* docs: caveat --parent label inheritance with size/effort labels (#4562)
Children inherit parent labels by default. Examples that use --parent with
size/effort labels on epics silently double-label every child, which breaks
effort queries. Document --no-inherit-labels in labels.md and parent-create
examples (skill, quickstart, molecules, multi-agent coordination).
* docs(labels): consolidate example commands and fix issue-ref style
Maintainer commit per vishnujayvel's request on PR #5123: fold the
two-step "create then label" example under Size/Effort Estimates into
one bd create -l invocation, and normalize the bare #2100 reference
to the GH#NNNN style used elsewhere in the docs.
Agent-Signature: claude-code-sonnet-medium on behalf of matt wilkie
* docs: revert no-op --no-inherit-labels edits, cross-link instead (GH#4562)
--no-inherit-labels was a no-op in the quickstart/molecules/coordination
examples (none created labels), inverting the deliberate #2100 default
for readers who don't have the problem yet. Revert those three plus the
same no-op edit in the plugin's INTEGRATION_PATTERNS.md to match main,
and add a one-line cross-link to the labels.md caveat/worked example
instead, per maphew's review on #5123.
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
Three operational lessons from the July squash windows, in generic terms:
- Git-backed remotes never shrink on force-push: the remote manifest keeps
every historical table file listed as current, so the store must be
replaced in place — delete refs/dolt/data and the __dolt_remote_info__
branch on the git remote, then force-push a fresh store (verified on two
production remotes: 587M->57.8M and 274M->2.6M reachable).
- Sync jobs and writers are separate switches: a peer's sync job stays off
until that machine has verifiably re-cloned; unfencing writers must not
implicitly re-arm peer sync (the re-pollution hole hit twice).
- First push from a re-cloned machine is far larger than a routine tick;
timeout-capped sync jobs orphan partial uploads — one manual uncapped
push before handing back to the schedule.
Gates: go test ./test/docsync PASS, check-doc-freshness.sh PASS.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Add Kiro setup recipe
* docs: register integrations/kiro in docs.json navigation
The docsync guard (TestEveryDocsPageIsPublished) requires every docs/ page
in the Mintlify nav; it landed after this PR was written.
Agent-Signature: claude-fable-5-high on behalf of maphew
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P3JtQ3ukoVmfg6LCKcKBBh
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Commit ab3feda00 removed the len(prefix) > 8 check from validatePrefix,
but "Max length: 8 characters" survived in the command's Long help text,
the plugin skill page, and docs/reference/advanced.md. Remove from all
three sources; generated CLI docs are release-pinned and untouched.
* fix(build) fixing build when using MSVC (#4324)
* fix(build) fixing build when using Windows (#4324)
---------
Co-authored-by: Johann Dirry <johann.dirry@microsea.at>
Co-authored-by: matt wilkie <maphew@gmail.com>
* fix(show): flag comment_count as omitted when comments are not streamed
bd show --json's count-only default (be-ijck6q, pinned by
TestJSONContract_ShowOmitsOptInPayloadsByDefault) returns comment_count
with no comments key unless --include-comments is passed. A caller that
checks only `.comments` reads absence as "no comments" — wrong whenever
comment_count > 0. A caller that reads comment_count has no signal that
the array was left out on purpose rather than omitted by a client bug.
Add comments_omitted (bool, omitempty) to IssueDetails, set true only
when CommentCount > 0 and Comments was not populated. Leaves the
count-only default and its perf rationale untouched — this does not
revert cfcc95799/e538f2881, it makes the partial representation
self-announcing. Symmetric dependent_count/dependents case is a known,
separate gap left for a follow-up (not reported by ga-clgh, out of
scope here).
Did not bump JSONSchemaVersion / regen the golden corpus: this adds an
optional field via omitempty (no existing consumer's parse breaks,
no existing corpus fixture has comment_count > 0 for `show`), and
corpus-regen needs a live Dolt+Docker this sandbox doesn't have to
verify. Deferring that call to whoever can run `make corpus-regen` and
review the diff.
Fixes ga-clgh.
* fix(show): set comments_omitted on the proxied path too
The direct path flags comment_count as omitted when comments are not
streamed (ga-clgh); the proxied path silently left the flag unset. Mirror
the else-branch in proxiedBuildDetails, add proxied-path coverage for
present/included/zero cases, and document comments_omitted in the JSON
schema reference. No schema version bump: additive optional field already
emitted by the direct path.
Addresses the 2026-07-23 review on gastownhall/beads#4865.
Agent-Signature: claude-sonnet-5-medium on behalf of maphew
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
Second adversarial review of the replica-aware lease work, against the opt-in
rewrite. One blocker, in the operating instruction rather than the code.
node_id was documented as "BEADS_NODE_ID, or node_id in config.yaml", and
`bd config set node_id` wrote the PROJECT .beads/config.yaml — a git-TRACKED
file (nothing in .beads/.gitignore excludes it). Commit "node_id: mini" and
every clone that pulls reads "mini", so every granted_node comparison matches
and the guard is at once fully ARMED and fully INERT: laptop reaps mini's
leases exactly as if they were local. That is the precise hazard the feature
exists to close, now happening while the operator believes they are protected
— strictly worse than the pre-feature state, where nobody thought they were.
node_id is per-machine state, the class .beads/.gitignore already excludes as
sync-state.json / push-state.json / redirect. It now routes to the user-global
~/.config/bd/config.yaml through a new exact-key arm of IsUserGlobalKey (the
prefix list only ever held "metrics."); viper already merges that file, so
config.NodeID() reads it straight back.
The docs also said to set it "on every replica sharing the queue", which on a
shared or remote dolt sql-server means every HOST — rebuilding the same
fail-closed regression this commit's parent removed the hostname fallback to
avoid. The load-bearing rule was never stated: node_id names the STORE, not
the host. Clients of one sql-server are ONE replica and must share a value or
leave it unset. Now said outright in federation.md and `bd reclaim --help`.
Also from the review:
- bd show claimed "reclaim will decline it" for any foreign node, but with an
unnamed local node the guard is disarmed and reclaim reverts the lease
happily. The annotation is now gated on config.NodeID() != "".
- TestNodeIDContextOverride's empty-override assertion had gone tautological
when the hostname fallback went away: config.NodeID() is "" under test, so
it passed whether or not WithNodeID worked at all. It now sets a non-empty
fallback, asserts the fallback is what a no-override read returns, and only
then asserts the empty override still beats it.
- The heartbeat backfill's bare `granted_node = ''` is COALESCE'd, matching
the reclaim predicates; under NULL the IF took the else branch and the row
was never backfilled. Unreachable today (0016 is NOT NULL DEFAULT ''), but
the two sites disagreed about whether NULL was possible.
- The --any-replica audit line is skipped when localNode is "" rather than
printing `not this node ("")`: nothing was overridden, the guard was never
armed.
- reclaimReplicaSQL documents WHY granted_node stays unqualified — the DELETE
splices it into a bare `DELETE FROM leases` with no alias to qualify with —
and what to do if issues ever grows a column of that name.
- CHANGELOG entry, which this feature owed: a new flag, a new config key, two
env vars, and two public struct fields shipped without one.
Adversarial review of the landed replica-aware lease work (966ddac5a) found
that deriving the granting replica from os.Hostname() answers the wrong
question: the hostname names the CLIENT PROCESS's machine, not the store.
That is a fail-CLOSED regression in three topologies with no federation to
defend against. With a shared or remote dolt sql-server (BEADS_DOLT_SERVER_HOST,
ServerModeExternal, Hosted Dolt, a VPS) many hosts are clients of ONE store, so
a supervisor would match no worker's lease and reclaim 0 forever. In a container
the hostname is a per-run container ID, so a replaced worker's successor sees
its own single-machine leases as foreign. On macOS/DHCP the transient hostname
follows the network. Stranding a lease on a single-store deployment is a worse
failure than the cross-replica reclaim the guard exists to prevent.
So the guard is now OPT-IN: config.NodeID() reads BEADS_NODE_ID / BD_NODE_ID /
node_id in config.yaml and nowhere else, and "" (the default) disarms the guard
back to exactly the pre-feature behavior. This also settles the heartbeat
backfill hazard — on an unnamed deployment the backfill writes '' over '' and
cannot silently convert a fail-open row into a fail-closed one.
Also from the review:
- node_id joins recognizedConfigKeys and YamlOnlyKeys, so the documented
`node_id: mini` mitigation no longer warns and no longer writes to the Dolt
config table that NodeID() never reads (the GH#536 class YamlOnlyKeys exists
to prevent).
- reclaimReplicaSQL/warnReplica/reportForeignSkips move above the
ReclaimExpiredLeasesInTx doc block, which they had orphaned onto a private
helper.
- The --any-replica audit line moves past both re-checks, so it can no longer
log a revert that a post-snapshot heartbeat prevented.
- lease_granted_node joins ephemeralExportKeys in the conformance round trip.
- New cmd/bd/protocol coverage for the JSONL path (RestoreLeaseOnImportInTx),
the sole reason the field is on the wire: a lease claimed under
BEADS_NODE_ID=mini keeps mini after import on laptop, laptop's reaper
declines it, and --any-replica reverts that same row.
- The embeddeddolt test stops claiming its surviving-lease assertion exercises
the DELETE-side guard; inside one transaction that copy is defense in depth.
- A stray U+201D and an inconsistent COALESCE in reportForeignSkips.
A claim lease is only meaningful on the replica that granted it. Every other
replica's view of the holder's liveness is stale by up to one sync interval,
so a reaper over there can revert a unit that is very much alive here. Until
now the only defense was operator discipline: partition every supervisor's
reclaim by label and hope nobody runs an unscoped sweep.
Leases now record WHICH replica granted them (leases.granted_node, ignored
migration 0016, stamped from config.NodeID(): BEADS_NODE_ID / node_id config,
falling back to the hostname). bd reclaim skips a lease that positively names
another replica — on both the snapshot SELECT and the per-row DELETE
re-check — and names each skip on stderr, since silence there is
indistinguishable from "nothing to recover" while a genuinely dead remote
worker's unit sits in_progress forever. bd reclaim --any-replica is the
operator escape hatch for a replica that is gone for good.
The guard is deliberately fail-open on unknown provenance: granted_node ''
(a row predating the column, or a deployment whose NodeID is empty) is
treated as local, so the upgrade itself can never strand a stale lease the
reaper could previously recover. A heartbeat backfills an unknown row with
the local node and never overwrites a known one.
The one path that can materialize a FOREIGN lease row locally is
RestoreLeaseOnImportInTx — lease fields round-trip the JSONL interchange — so
the granting replica rides types.Issue.LeaseGrantedNode and a restored lease
keeps the replica the snapshot names, never this node. A snapshot from an
older binary carries none, restores as unknown, and behaves exactly as before.
What the guard cannot enforce is documented instead, in both bd reclaim --help
and docs/multi-agent/federation.md: grace window > sync interval, and lease
TTL > sync interval. A TTL shorter than the cadence at which replicas exchange
state is meaningless across the bridge — the remote view is a full interval
old by construction.
doc/beads-upstream-asks.md section 5.
Field incident from the first production run of this runbook (wy-7lmdp,
2026-07-18): all local writers were fenced, but a peer machine's scheduled
bridge-sync job was never stopped. One tick after the clean force-push it
pulled the new baseline, cross-merged it into its old chain, and pushed the
entire old history back to the freshly replaced remote.
Step 1 now tells the operator that writers include scheduled sync jobs on
every machine that syncs the database, to enumerate and verify them by
name, and why one live peer undoes the procedure. Step 5 orders re-enabling
per machine after its re-clone; the top warning says 'on every machine'.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The runbook (#4864) and the release-pinned CLI reference (#4876) crossed
mid-flight: the prevention section links /cli-reference/heartbeat, a page
the pin removed because bd heartbeat is not in v1.1.0. The dangling link
fails the docsync guard on main and on every branch cut from it. Keep the
prose, drop the link.
The v1.1.0 release notes tell the designated migrator to run
BD_ALLOW_REMOTE_MIGRATE=1 bd migrate, but the docs never named the
variable after the escape-hatch scrub. One mention belongs in the upgrade
guide, where a blocked or CI-scripting reader actually looks; the wording
is derived from the v1.1.0 source (remote_migrate_gate.go): boolean values
accepted, consulted only when the gate would fire, and it bypasses the
gate entirely — including the already-forked lanes — so the sentence says
to wire it into exactly one clone's upgrade job.
Old clones share the root by construction (Step 2 keeps it as sole
ancestor), so a pull is not refused — it cross-merges and, if pushed,
resurrects the bloat on the squashed remote. Wording per lion's re-review.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A Dolt remote accumulates chunks monotonically, so Step 4's force-push
re-points refs without freeing the old chain's storage. Warn and give the
replace-the-remote recipe; clones must re-clone after a squash anyway.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The per-section forwarding map mirrored the live playbook's structure — a
copy that would drift as docs/recovery/ evolves. A stub carries nothing to
maintain: one pointer to the live playbooks plus the reason the file
exists. Deep anchors from the wild land at the top of the page, where the
pointer is the first thing a reader sees.
Released v1.1.0 binaries print
github.com/gastownhall/beads/blob/main/docs/RECOVERY.md#pk-fork-refused in
the Dolt merge-refusal guidance (printAncestorPKMismatchGuidance,
cmd/bd/dolt.go at the tag), and github.com blob paths cannot be redirected —
the URL has 404ed since the docs restructure, at exactly the moment a user
is mid-incident. main's binary already prints the new path; this stub
un-rots the link for binaries already in the wild.
The stub reproduces the old file's section headings verbatim so GitHub
mints the same anchor slugs, and each section forwards to its successor in
docs/recovery/init-safety.md (all four sections map there 1:1). It is
registered in test/docsync's docsPublishExemptions as a deliberate,
documented exception to the no-pointer-stubs rule (decision 6), scoped to
last only while supported releases print the path.
* docs(pipeline): pin the generated CLI docs to the released bd; repair main's CLI reference
The #4874 squash-merge raced the docs-autofix bot: the bot had pushed a
regeneration from main's source onto the PR branch, so the squash landed a
contradictory mix — the release-aligned hand-written docs plus a CLI
reference re-documenting unreleased commands and flags, with docs.json
referencing four pages (heartbeat, migrate-personal, reclaim, unclaim)
whose files do not exist. That broken nav fails the docsync guard on main
and on every branch cut from it. This restores the intended end state of
#4874 and lands the pin that prevents the race from recurring.
- Regenerate the CLI reference from a bd built from the v1.1.0 tag (CI's
canonical pure-Go build), removing the unreleased commands/flags and
fixing the dangling nav entries.
- docs/cli-docs.pin names the release tag; scripts/resolve-docs-bd.sh
builds and caches a canonical pure-Go bd from that tag, fetching the tag
first in shallow CI checkouts.
- generate-cli-docs.sh, check-doc-flags.sh, and check-cli-docs-drift.sh
resolve bd through the pin and ignore a supplied binary while pinned
(BD_DOCS_IGNORE_PIN=1 bypasses), so the drift gates and the autofix bot
now enforce docs-match-release instead of docs-match-main.
- tools/docsmint detects the pre-overhaul Docusaurus staging layout that
bd <= v1.1.0 emits and converts it to the generic form before its normal
Mintlify transform (tested); removable once the pin reaches a release
whose emitter writes build/cli-docs.
- check-doc-flags.sh: run without timeout(1) on macOS instead of failing
Check 4.
- Decision record: engdocs/decisions/2026-07-17-docs-release-pin.md; the
beads-docs skill §8 updated to match.
* lint: annotate gosec G705 false positive in the docsmint legacy bridge
Same class as the existing nav-splice annotation: a developer tool writing
repo Markdown, not a web-output sink.
* docs: align user docs and CLI reference with the v1.1.0 release
The Mintlify site publishes from main, so the docs had drifted ahead of the
latest release — documenting features that no released binary ships.
- Remove architecture/storage-backends: v1.1.0 supports only Dolt (the
SQLite/Postgres/MySQL backends are post-tag work on main). Redirect the
old routes to /architecture/dolt and drop the alternate-backend claims
from README, core-concepts, architecture index, and FAQ.
- Stamp the docs homepage with the release: "These docs are for the 1.1.0
release" plus a link to the v1.1.0 release notes.
- Regenerate the CLI reference (docs/cli-reference/, docs/CLI_REFERENCE.md,
docs.json nav) from the released v1.1.0 binary via tools/docsmint: removes
pages for post-1.1.0 commands (heartbeat, migrate-personal, reclaim,
unclaim) and post-1.1.0 flags.
- Fix hand-written pages that referenced post-1.1.0 CLI surface, verified
against the v1.1.0 binary: bd dep relate/unrelate (not top-level
relate/unrelate), bd admin reset (not bd reset), bd hooks list (not
status), bd history / bd vc status (not vc log/diff), release the claim
via bd assign + bd update (no bd unclaim), drop bd migrate-personal and
bd daemon mentions, and reduce the Cursor integration page to the rules
file that v1.1.0's bd setup cursor actually installs.
- Stop documenting the BD_ALLOW_REMOTE_MIGRATE escape hatch (and the
nonexistent-in-1.1.0 bd migrate --force): the remote-migrate gate prints
its own operator guidance by design; docs now defer to it.
* docs: auto-regenerate CLI reference
Applied from the cli-docs-freshness-patch artifact of https://github.com/gastownhall/beads/actions/runs/29613329749
(generated with CI's canonical pinned build). See
scripts/check-cli-docs-drift.sh for how drift is attributed.
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Addresses lion's review on #4864: remote-tracking refs from past pushes/
fetches keep the pre-squash chain reachable, so Step 3's gc silently
reclaimed nothing on exactly the long-lived synced workspaces this runbook
targets. Step 3 now deletes them (force-push recreates them on the new
chain) and verifies with du -sh. Also: why the root commit stays as the
baseline parent, and Prevention links to the heartbeat/wisps pages.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Fenced-window procedure: backup, soft-reset squash to a baseline commit,
drop stale refs, gc --full, force re-publish, re-clone everywhere else.
Motivated by the wyvern deployment's 3.6G of reachable lease-churn
history (wy-7lmdp).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>