* docs: fix broken xref to docs/EXTENDING.md in extension example
The extension example README referenced docs/EXTENDING.md in three
places, but that file was deliberately deleted in the SQLite -> Dolt
migration (see CHANGELOG entry "Deleted deprecated docs - removed
EXTENDING.md and MULTI_REPO_HYDRATION.md (SQLite-era, no longer
applicable)"). Anyone following the example hits a broken link.
Removed all three references. The example README is itself the
canonical reference for the extension pattern, so no redirect target
is needed.
Note: other docs in the repo still reference the deleted EXTENDING.md
(docs/ADVANCED.md, docs/CONFIG.md, examples/library-usage/README.md,
website/docs/reference/advanced.md). Those are out of scope for this
fix and should be addressed in follow-up issues.
Tracking bead: mybd-q71
GH: #3683
PR: builds on follow-up audit from PR #3706
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: fix remaining broken xrefs to deleted EXTENDING.md across repo
Round 1 (commit ddeff314c) only fixed the extension example README
because the original prompt scoped that PR narrowly. The bead
(mybd-q71) acceptance is repo-wide ("no broken xrefs anywhere"), so
this follow-up sweeps the rest in the same PR per the project's
"one issue per PR" rule.
Per-file treatment (EXTENDING.md was deleted in commit 508387377
before v1.0.0 was tagged, so even the v1.0.0 versioned snapshot has
been broken since release):
- docs/ADVANCED.md (3 refs):
* Note in Extensible Database section: drop trailing "See
EXTENDING.md for details" — the surrounding sentence about
Dolt-era alternatives stands on its own.
* Bold "See EXTENDING.md for complete documentation" line:
redirect to the canonical working example
(examples/bd-example-extension-go).
* Next Steps bullet: same redirect.
- docs/CONFIG.md (2 refs):
* Namespace doc for compact_*: replace "(see EXTENDING.md)" with
"(used by `bd admin compact`)" — the doc itself describes the
keys, no external reference needed.
* See Also bullet: replace with link to docs/ADVANCED.md
(Extensible Database section).
- examples/library-usage/README.md (1 ref):
* See Also bullet: replace EXTENDING.md link with link to the
sibling bd-example-extension-go example.
- website/docs/reference/advanced.md (1 ref):
* Custom Tables section: replace EXTENDING.md link with link to
the bd-example-extension-go README on GitHub.
- website/versioned_docs/version-1.0.0/reference/advanced.md (1 ref):
* Same fix as the live docs. EXTENDING.md was deleted before
v1.0.0 release (commit 508387377 is an ancestor of tag v1.0.0),
so this versioned snapshot has been broken since cut and a fix
here doesn't violate frozen-in-time correctness — the link was
never valid in the v1.0.0 release.
- website/static/llms-full.txt (1 ref, auto-generated artifact):
* Updated to match the corrected source so the on-disk artifact
isn't broken until next regeneration.
- beads.go and internal/beads/beads.go (package doc comments):
* Replaced "see docs/EXTENDING.md" / "see EXTENDING.md" with a
pointer to examples/bd-example-extension-go. These were real
broken pointers in published Go source comments.
CHANGELOG.md historical entries left untouched (intentional history).
cmd/bd/info.go:747 left untouched (it's a programmatic CHANGELOG
entry rendered by `bd info`, equivalent to a CHANGELOG line).
Verification:
grep -rn 'EXTENDING\.md' --include='*.md' .
returns only CHANGELOG.md hits.
Tracking bead: mybd-q71
GH: #3683
PR: #3713 (round 2)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add Go-side dedup in searchTableInTx to ensure SearchIssues never
returns the same issue ID twice, regardless of how many dependency
subqueries match. This prevents bd list from showing issues multiple
times when they have more than one blocks dependency.
* feat(linear): adopt issueBatchCreate/issueBatchUpdate for 50x efficiency
Implements tracker.BatchPushTracker interface on linear.Tracker.
Adds BatchCreateIssues and BatchUpdateIssues methods that chunk
inputs into groups of 50 (Linear's per-call limit). Graceful
fallback to per-issue mutations on batch failure.
* fix(linear): address BatchPush correctness blockers from maphew review
Three correctness issues flagged in PR #3654 review:
1. Skip semantics: BatchPush now fetches each existing issue before
updating and compares with PushFieldsEqual (title, description,
priority, status). Unchanged issues are added to result.Skipped
instead of being re-pushed unconditionally. forceIDs bypasses the
check, matching the single-issue path in engine.go:doPush.
2. Batch-create result mapping: results are now matched by title rather
than array index. Linear's issueBatchCreate API does not guarantee
response order matches input order; index-based mapping silently
associated wrong ExternalRefs with issues. Unmatched inputs are
recorded in result.Errors with the title for debugging.
3. Multi-team state cache: build a StateCache per configured team at the
start of BatchPush. Updates to issues belonging to non-primary teams
resolve workflow state IDs against that team's cache, not the primary
team's. The primary cache is used only for creates (which always target
the primary team).
Add four regression tests covering: unchanged-issue skip, forceIDs bypass,
title-based result mapping with reversed API response, and per-team state ID
selection in a two-team setup.
* fix(linear): prevent duplicate issues from batch-create correctness gaps
Two correctness fixes addressing maphew's re-review blockers on PR #3654:
1. Title-based result correlation is unsafe for duplicate titles.
BatchPush now detects duplicate titles before batching. Issues with
duplicate titles are routed through single-create with idempotency
markers (CreateIssueIdempotent) instead of the batch mutation where
title-based correlation would silently lose one duplicate.
2. Full-chunk fallback after ambiguous batch failure risks duplicates.
BatchCreateIssues no longer falls back to creating the entire chunk
when the batch mutation returns success=false or an API error. Instead
it searches for each issue's idempotency marker to discover which were
partially created, returns only confirmed issues, and errors on the
rest. If the recovery search itself fails, the error propagates rather
than risking duplicates.
Supporting infrastructure ported from feat/linear-idempotency-markers:
- idempotency.go: GenerateIdempotencyMarker, AppendIdempotencyMarker
- FindIssueByDescriptionContains, CreateIssueIdempotent on Client
* fix(linear): gofmt client.go and tracker_test.go
Fix Check formatting CI failure — two files had formatting drift
from the merge conflict resolution.
The LightDark() arguments were reversed: light gray (#bfbdb6) was shown
on light backgrounds (invisible) and dark gray (#5c6166) on dark backgrounds
(poor contrast). Swap them so each variant is legible on its intended
background.
Closes#3611
Add staleness detection so agents and devs automatically get fresh
Linear data without retry infrastructure.
- New staleness library (internal/linear/staleness.go): WriteLastPull,
ReadLastPull, IsPullStale, IsWithinDebounce, GetStalenessInfo
- --pull-if-stale flag on bd linear sync with configurable --threshold
(default 20m) and 5-minute debounce to prevent agent loops
- bd prime auto-pulls when stale and LINEAR_API_KEY is set
- Per-session stderr warning on any bd command when data is stale
- 14 new tests covering all staleness functions
Design validated by three adversarial reviewers (architecture,
performance, agent-native). Morning storm (50 devs) = 1% of rate
limits. Scales to 500 devs safely.
Refs: PLAN.md d16, btl-seo
`Ephemeral=&false` in SearchIssuesInTx previously only queried the issues
table, skipping the wisps table entirely. But NoHistory beads (ephemeral=0,
no_history=1) live in the wisps table and must survive export.
Extend the wisps merge pass to also run when Ephemeral=&false. The WHERE
clause (`ephemeral=0 OR ephemeral IS NULL`) already exists in the wisps
query via BuildIssueFilterClauses — so NoHistory beads are included while
true ephemeral wisps (ephemeral=1) are correctly excluded.
Fixes the regression flagged in GH#3659 review: `TestExportNoHistoryBeadRoundTrip`
documents that NoHistory beads must survive export/import. (GH#3649)
OAuth-only sync path (no LINEAR_API_KEY required):
- Tracker.Init() now checks for OAuth credentials first
(LINEAR_OAUTH_CLIENT_ID + LINEAR_OAUTH_CLIENT_SECRET), constructs
NewOAuthClient per team when present, and only falls back to API key
when OAuth is absent. Missing both is a clear error naming both options.
Lint fixes:
- oauth.go: add //nolint:gosec on DefaultOAuthTokenURL (G101 false
positive — URL path component, not a credential)
- oauth.go: change defer resp.Body.Close() to
defer func() { _ = resp.Body.Close() }() to satisfy errcheck
- .golangci.yml: add unparam exclusion for getLinearConfig (ctx param
kept for context propagation)
Docs/code precedence alignment:
- getLinearConfig: env vars now take precedence over config.yaml for
yaml-only keys (was reversed). Matches documented precedence:
OAuth > LINEAR_API_KEY > config file.
Tests:
- TestTrackerInitOAuthOnly: validates OAuth client construction without
API key
- TestTrackerInitNoAuthFails: validates error message when no auth
configured
- Format types.go (struct field alignment was off by one space)
- parseRetryAfter: use http.ParseTime for HTTP-date form (RFC 1123 /
RFC 850 / ANSI C) instead of time.Parse(time.RFC1123) — the latter
requires an exact timezone abbreviation while http.ParseTime accepts
the canonical GMT form mandated by RFC 9110 §10.2.3
- Add MaxRetryAfterDelay (300s) cap on server-provided Retry-After
delays; log a warning to stderr and clamp when the hint exceeds the cap
- Wire linear.rate_limit_floor / LINEAR_RATE_LIMIT_FLOOR through both
Tracker.Init() and getLinearClient() so the config key is functional
via `bd config set linear.rate_limit_floor <n>` and the env var
- ErrRateLimitExhausted now implements RateLimitExhausted() bool;
engine.go uses an interface check (no import cycle) to abort the
push loop immediately on quota exhaustion instead of cascading the
error across every remaining issue
- Tests: extend TestParseRetryAfter with HTTP-date future/past cases;
add TestExecute_RetryAfterCapApplied to confirm the cap path is taken
Fix 1 (double description formatting): Tracker.CreateIssue was calling
BuildLinearDescription(issue) to format the description, but the sync
engine's FormatDescription hook already calls BuildLinearDescription
before invoking CreateIssue. For issues with AcceptanceCriteria/Design/
Notes, this caused those sections to be appended twice in the Linear
description. Fix: use issue.Description directly in CreateIssue, trusting
the caller to have pre-formatted it.
Fix 2 (retry race in CreateIssueIdempotent): The previous implementation
called CreateIssue (which goes through Execute's retry loop) after the
initial marker search. If issueCreate reached Linear but the HTTP response
was lost, Execute could retry the mutation and create a duplicate issue
with the same idempotency marker. Fix: add createIssueSingleAttempt that
runs the mutation exactly once. After any failure, re-search for the
marker before returning the error so callers can safely retry
CreateIssueIdempotent without creating duplicates.
Also documents the concurrent multi-source limitation (Linear provides no
server-side uniqueness enforcement; the dedup window is bounded by search
index propagation).
Adds regression tests:
- TestCreateIssueNoDoubleFormatDescription: verifies AC/Design sections
appear exactly once in the description sent to Linear
- TestCreateIssueIdempotentRecoverAfterAmbiguousFailure: verifies that an
ambiguous create failure (5xx response) followed by a recovery search
returns the already-created issue with deduped=true
Removing the lock file after unlocking creates a lifecycle race: a blocked
waiter acquires the old inode (between flock release and os.Remove), then a
third process creates a new file at the same path and locks it — both
processes believe they hold the lock.
Fix: never call os.Remove in Release(). Truncate diagnostic metadata while
still holding the flock, then release. The stable path is reused by
subsequent AcquireSyncLock calls via O_CREATE|O_RDWR.
Also:
- Handle writeLockInfo's Truncate error (was silently discarded with _ =)
- Add #nosec G304 to readLockInfo (path is program-constructed, not user input)
- Update test: assert lock file persists and is empty after Release, not removed
Fix-merged for release prep: preserved the contributor rate-limit handling and added the maintainer fix to avoid sleeping after the final retry attempt. Auto-merge after CI.
Fix-merged for release prep: preserved the contributor Linear type mappings and added exact-only matching to avoid story false positives such as history. Auto-merge after CI.
Carry forward the useful CLI dependency parsing fix from gastownhall/beads PR #3560 while excluding unrelated governance/template and Dolt subsystem changes.
blocked-by:<id> and depends-on:<id> now store a blocks dependency from the new issue to the target, while explicit blocks:<id> continues to invert direction so the target depends on the new issue.
Also reject unknown create --deps dependency types using the centralized well-known dependency type policy.
Co-authored-by: kev <kglynn@pryoninc.com>
* fix(config): refuse to write secret keys to git-tracked config.yaml
P0 security fix. bd config set for secret keys (api_key, secret, token,
password) now detects git tracking of the target config file and refuses
the write with an actionable error pointing to env var alternatives.
Adds --force-git-tracked escape hatch for tests. Updates stale template
documentation and setup guides to lead with env var approach.
* fix(config): scope secret git safety check to YAML-backed keys
Use real environment variable hints for known secret config keys and avoid blocking database-backed secret-looking keys such as notion.token.
Maintainer follow-up for PR #3652.
* fix(config): silence gosec on env var hint names
The map contains environment variable names, not secret values.
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
Keep GetLabelsForIssuesInTx compatible with existing callers that pass a scoped active-wisp set while retaining the new batched partitioner for default callers.
This fixes stale Dolt tests on PR #3666 after the GH#3414 batching refactor.
Co-authored-by: Harry Miller <harry_miller@trimble.com>
Every mutating bd command against a remote Dolt backend hung ~10–15s
with `auto-export failed: ... hydrate labels: ... context canceled`.
Root cause: five bulk fetchers in internal/storage/issueops partitioned
IDs into wisp vs permanent buckets by calling IsActiveWispInTx once per
ID, and each call is a round-trip to the SQL server. With ~600 issues
over WAN latency that's ~12s of sequential SELECTs *before* the real
label query runs — blowing past the context deadline.
Fix:
- Add PartitionWispIDsInTx that batches the check into one
`SELECT id FROM wisps WHERE id IN (...)` per queryBatchSize chunk,
reducing cost from O(N) to O(1 + N/200) round-trips. Falls back to
"no wisps" when the wisps table is absent (pre-migration dbs).
- Rewrite GetLabelsForIssuesInTx, GetCommentsForIssuesInTx,
GetDependencyRecordsForIssuesInTx, GetBlockingInfoForIssuesInTx, and
DeleteIssuesInTx to use it.
- Add fast-path helpers GetLabelsForIssuesFromTableInTx and
GetDependencyRecordsForIssuesFromTableInTx for callers (searchTableInTx)
that already know every ID is in a single table, skipping the partition
round-trip entirely on the hot auto-export path.
Tests:
- New wisp_partition_test.go covering the partitioner directly: empty,
all-perm, all-wisp, mixed-with-unknown, input-order preservation, and
a 450-ID large-batch case crossing the queryBatchSize boundary.
- End-to-end mixed-routing regression tests for GetCommentsForIssues,
GetDependencyRecordsForIssues, and a 250-ID GetLabelsForIssues case
that crosses the chunk boundary.
Made-with: Cursor
Add OAuthTokenManager for machine-to-machine authentication using
Linear's client_credentials grant. This enables CI workers to use a
service identity (actor=application) instead of personal API keys.
Key changes:
- New OAuthTokenManager with lazy acquisition, caching, thread-safe
refresh (5-min buffer before expiry), and Invalidate() for 401 retry
- AuthMode enum (APIKey vs OAuth) on Client with appropriate header
format: API keys use "Authorization: <key>", OAuth uses "Bearer"
- NewOAuthClient() constructor and WithOAuth() option
- 401 auto-retry: invalidate token and re-acquire on first 401
- Auth precedence: LINEAR_OAUTH_CLIENT_ID/SECRET env vars >
LINEAR_API_KEY env var > bd config
- Mark oauth_client_secret as secret key (uses IsSecretKey from PR-1)
- 12 new tests covering acquisition, caching, refresh, invalidation,
error handling, thread safety, and header format
Validated against Linear sandbox: client_credentials grant works with
scope=read,write, actor=application gives bot identity, 30-day TTL.
Refs: gastownhall/beads integration charter, PLAN.md §6 PR-3
Acquires .beads/.linear-sync.lock at start of bd linear sync to
serialize concurrent invocations. Stale lock detection via PID
check. Clean release on SIGTERM via defer. Prevents duplicate
creates and conflict thrash from overlapping sync runs.
Embeds <!-- bd-idempotency: hash --> in Linear descriptions on create.
Pre-create dedup query uses description contains filter (validated
against Linear API). Hash uses immutable fields only (beadID +
creatorEmail + createdAtNano). Prevents duplicates under sync
interruption or multi-source create races.
P1 privacy fix. Federation push now filters issues by
federation.exclude_types config (default: ["wisp"]) before sending
to peers, consistent with the existing type filter in the sync
engine. Opt-out via federation.exclude_types = [].
bd list --deferred only matched issues with defer_until set, missing
issues with status=deferred but no defer_until timestamp. The filter
now uses (defer_until IS NOT NULL OR status = 'deferred') in both
issueops and dolt transaction paths.