@beads/bd 0.22.0 → 0.24.0

package/bin/CHANGELOG.md

@@ -7,6 +7,603 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.24.0] - 2025-11-20
+
+### Added
+
+- **bd doctor --fix**: Automatic repair functionality (bd-ykd9, 7806937)
+  - Automatically fixes issues detected by `bd doctor`
+  - Repairs common database inconsistencies without manual intervention
+
+- **bd clean**: Remove temporary merge artifacts (e8355c2)
+  - Cleans up `.base`, `.ours`, `.theirs` snapshot files
+  - Helps maintain clean `.beads/` directory after merges
+
+- **bd cleanup**: Enhanced bulk deletion command
+  - Delete multiple closed issues efficiently
+  - Improved from previous versions with better performance
+
+- **.beads/README.md Generation**: Auto-generated during `bd init` (bd-m7ge, e1c8853)
+  - Provides project-specific beads documentation
+  - Helps new contributors understand the setup
+
+- **blocked_issues_cache Table**: Performance optimization for GetReadyWork (62c1f42, ed23f8f)
+  - Caches blocked issue relationships
+  - Dramatically improves `bd ready` performance on large databases
+
+- **Commit Hash in Version Output**: Enhanced version reporting (bd-hpt5, 7c96142)
+  - `bd version` now shows git commit hash
+  - Helps identify exact build for debugging
+
+- **Auto-detection of Issue Prefix**: Scans git history to detect prefix (#277, 8f37904)
+  - Automatically discovers project's issue prefix
+  - Reduces manual configuration needed
+
+- **external_ref Support in Daemon RPC**: Full daemon mode support (#304, 57b6ea6)
+  - MCP server can now set external references in daemon mode
+  - Parity with CLI functionality
+
+- **Context Optimization Features**: AI agent improvements (#297, f7e80dd)
+  - Context propagation with graceful cancellation (bd-rtp, bd-yb8, bd-2o2, 57253f9)
+  - Better memory management for long-running agent sessions
+
+### Fixed
+
+- **Critical: Auto-import Resurrection Bug** (bd-khnb, 0020eb4, e28e3ea, 7b6370f)
+  - Fixed critical bug where deleted issues were resurrected during auto-import
+  - Cleaned up 497+ resurrected issues from production database
+  - Prevents data corruption from improper JSONL replay
+
+- **Critical: bd sync Auto-resolves Conflicts** (bd-ca0b, a1e5075)
+  - `bd sync` now automatically resolves conflicts instead of failing
+  - Dramatically improves multi-agent workflow reliability
+  - Eliminates manual conflict resolution in most cases
+
+- **Critical: Content-based Timestamp Skew Prevention** (bd-lm2q, d0e7047)
+  - Fixed false-positive "JSONL is newer than database" warnings
+  - Uses content-based comparison instead of timestamp-only
+  - Prevents unnecessary imports that would corrupt state
+
+- **Critical: bd sync DB Changes After Import** (81c741b)
+  - Ensures database changes are properly applied after import
+  - Fixes desync issues between JSONL and database
+
+- **Critical: Context Propagation Lifecycle Bugs** (bd-rtp, bd-yb8, bd-2o2, 57253f9, a17e4af)
+  - Fixed multiple context propagation issues causing crashes
+  - Graceful cancellation support for long-running operations
+  - Improved stability for AI agent workflows
+
+- **Critical: Race Condition in Auto-flush** (bd-52, a9b2f9f)
+  - Fixed race condition in auto-flush mechanism
+  - Prevents data loss during concurrent operations
+
+- **Critical: Resource Leaks and Error Handling** (#327, fb65163)
+  - Fixed critical resource leaks in daemon mode
+  - Improved error handling throughout codebase
+
+- **Critical: In-memory Database Deadlock** (bd-yvlc, 944ed10)
+  - Fixed deadlock in migrations when using in-memory database
+  - Improves test reliability
+
+- **MCP Schema Generation Recursion Bug** (GH#346, f3a678f)
+  - Fixed infinite recursion in MCP schema generation
+  - Prevents stack overflow crashes
+
+- **FK Constraint Failures** (bd-5arw, 345766b)
+  - Fixed foreign key constraint failures in AddComment and ApplyCompaction
+  - Improved data integrity
+
+- **--parent Flag Behavior** (b9919fe)
+  - Now correctly creates parent-child dependency relationships
+  - Previously was creating wrong dependency type
+
+- **Exact ID Matching Priority** (gh-316, 934ae04)
+  - Prefers exact ID matches over prefix matches
+  - Prevents ambiguous ID resolution
+
+- **Daemon Lifetime on macOS** (GH#278, 68f9bef)
+  - Fixed daemon exiting after 5s on macOS due to PID 1 parent monitoring
+  - Daemon now runs reliably on macOS
+
+- **Daemon Export/JSONL Sync** (GH#301, #321, 04a1996)
+  - Fixed daemon export leaving JSONL newer than database
+  - Ensures proper sync between export and database state
+
+- **bd doctor Hash ID Detection** (GH#322, 8c1f865)
+  - Fixed doctor incorrectly diagnosing hash IDs as sequential
+  - Improved detection logic for ID format validation
+
+- **ResolvePartialID Handling** (GH#336, 4432af0)
+  - Improved ResolvePartialID / ResolveID handling for `bd show`
+  - Better partial ID matching and error messages
+
+- **bd sync Windows Upstream Detection** (#281, 1deaad1)
+  - Fixed upstream branch detection on Windows
+  - Improved cross-platform compatibility
+
+- **Compact Command Daemon Mode** (#294, d9904a8)
+  - Fixed compact command failing with 'SQLite DB needed' error when daemon running
+  - Removed premature store check, uses ensureDirectMode
+
+- **DB mtime Update After Import** (#296, 9dff345)
+  - Fixed DB mtime not being updated after import with 0 changes
+  - Prevents false staleness warnings
+
+- **FOREIGN KEY Constraint on Non-existent Issues** (09666b4)
+  - Fixed constraint failures when operating on non-existent issues
+  - Better error handling and validation
+
+- **Monitor WebUI Daemon Detection** (e36baee)
+  - Fixed monitor-webui failure to detect running daemon
+  - Improved daemon health checking
+
+- **Onboard Test Deadlock on Windows** (4e22214)
+  - Fixed deadlock in onboard tests on Windows
+  - Improved test stability
+
+- **Windows Concurrent Issue Creation** (4cd26c8)
+  - Fixed concurrent issue creation failures on Windows
+  - Better file locking on Windows
+
+- **Missing Git Hook Message** (#306, 92f3af5)
+  - Improved messaging when git hooks are missing
+  - Clearer instructions for users
+
+- **Prefix Detection for Hyphenated Apps** (83472ac, bd-fasa)
+  - Fixed prefix detection to only use first hyphen
+  - Handles hyphenated application names correctly
+
+- **External Ref Migration Failures** (8be792a)
+  - Fixed external_ref migration failure on old databases
+  - Backward compatibility improvements
+
+- **Duplicate Function Declaration** (#328, 167ab67)
+  - Fixed compilation failure from duplicate computeJSONLHash declaration
+  - Removed old version, kept simpler implementation
+  - Updated test to match new API
+
+### Changed
+
+- **Performance Improvements** (#319, 690c73f):
+  - Optimized GetReadyWork to use blocked_issues_cache (ed23f8f)
+  - Replaced N+1 label queries with bulk fetch in `bd list` (968d9e2)
+  - Cache invalidation for blocked_issues_cache (614ba8a)
+  - Significant speedup for large databases
+
+- **FlushManager Improvements** (445857f)
+  - Added constants for magic numbers
+  - Enhanced error logging
+  - Comprehensive functional tests
+
+- **Auto-upgrade .beads/.gitignore** (#300, f4a2f87)
+  - Automatically upgrades .gitignore on bd operations
+  - Ensures latest patterns are always applied
+
+- **Code Refactoring**:
+  - Extract duplicated validation logic to internal/validation (d5239ee)
+  - Centralize error handling patterns in storage layer (bd-bwk2, 3b2cac4)
+  - Extract duplicated validation and flag logic (bd-g5p7, bbfedb0)
+  - Improved code organization and maintainability
+
+- **Documentation Improvements**:
+  - Document files created by bd init and clarify .gitattributes (721274b, e7fd1dd)
+  - How to resolve merge conflicts in .beads/beads.jsonl (4985a68)
+  - Document MCP tools loading issue in Claude Code (GH#346, 79b8dbe)
+  - Add uv prerequisite to Claude Code plugin docs (#293, a020c6c)
+  - Don't auto-install Go in Windows installer (#302, 0cba73b)
+
+- **Improved Error Messages** (#349, 27c0c33)
+  - Compact error messages
+  - Remove bogus merge suggestion
+  - Add daemon/maintenance docs
+
+- **AGENTS.md Refactoring** (21a0656)
+  - Extracted detailed instructions to prevent context pollution
+  - Better organization for AI agent consumption
+
+- **Type Safety Improvements** (9e57cb6)
+  - Improved type safety in beads-mcp
+  - Fixed minor type issues
+
+- **Test Improvements**:
+  - Fix CI regressions and stabilize tests (7b63b5a)
+  - Fix parallel test deadlock (1fc9bf6)
+  - Annotate gosec-safe file accesses (bf9b2c8)
+
+- **Local-only Git Repo Support** (bd-biwp, 4de9f01)
+  - Support repositories without remote origin
+  - Better handling of local development workflows
+
+- **Version Marker in Post-checkout Hook** (ad2154b)
+  - Add version marker to post-checkout hook
+  - Include in CheckGitHooks for better version tracking
+
+### Performance
+
+- **GetReadyWork Optimization** (bd-5qim, 690c73f, 62c1f42, ed23f8f)
+  - Introduced blocked_issues_cache table
+  - Eliminated expensive recursive queries
+  - Dramatically faster for large dependency graphs
+
+- **bd list N+1 Query Elimination** (968d9e2)
+  - Replaced per-issue label queries with bulk fetch
+  - Significant speedup when listing many labeled issues
+
+### Community
+
+- **Pull Requests**:
+  - #338: Prevent daemon from exiting when launcher process exits (@cpdata)
+  - #337: Improve ResolvePartialID handling (@cpdata)
+  - #333: Fix doctor incorrectly diagnosing hash IDs (@cpdata)
+  - #327: Address critical resource leaks and error handling
+  - #306: Improve missing git hook message
+  - #304: Add external_ref support to daemon mode RPC
+  - #302: Windows installer improvements
+  - #300: Automatic .beads/.gitignore upgrade
+  - #297: Context optimization features for AI agents
+  - #296: Fix DB mtime update after import
+  - #294: Fix compact command in daemon mode
+  - #293: Add uv prerequisite documentation
+  - #281: Fix bd sync Windows upstream detection
+  - #277: Auto-detection of issue prefix from git history
+
+- **Dependency Updates**:
+  - Bump github.com/anthropics/anthropic-sdk-go from 1.17.0 to 1.18.0 (#330)
+  - Bump golang.org/x/mod from 0.29.0 to 0.30.0 (#331)
+  - Bump fastmcp from 2.13.0.2 to 2.13.1 (#332)
+  - Bump pydantic from 2.12.0 to 2.12.4 (#285)
+  - Bump pydantic-settings from 2.11.0 to 2.12.0 (#286)
+  - Bump golangci/golangci-lint-action from 8 to 9 (#287)
+  - Bump golang.org/x/sys from 0.36.0 to 0.38.0 (#288)
+  - Bump github.com/ncruces/go-sqlite3 from 0.29.1 to 0.30.1 (#290)
+  - Bump github.com/google/go-cmp from 0.6.0 to 0.7.0 (#291)
+
+### Notes
+
+This release represents a major stability and performance improvement with **179 commits** since 0.23.1. Key themes:
+- **Reliability**: Fixed critical auto-import resurrection bug and multiple daemon issues
+- **Performance**: Significant optimizations for `bd ready` and `bd list`
+- **AI Agent Support**: Improved context propagation and error handling
+- **Cross-platform**: Better Windows and macOS support
+- **Developer Experience**: Auto-detection, better error messages, improved docs
+
+## [0.23.1] - 2025-11-08
+
+### Fixed
+
+- **#263: Database mtime not updated after import causing false `bd doctor` warnings**
+  - When `bd sync --import-only` completed, SQLite WAL mode wouldn't update the main database file's mtime
+  - This caused `bd doctor` to incorrectly warn "JSONL is newer than database" even when perfectly synced
+  - Now updates database mtime after imports to prevent false warnings
+
+- **#261: SQLite URI missing 'file:' prefix causing version detection failures**
+  - Without 'file:' scheme, SQLite treated `?mode=ro` as part of filename instead of connection option
+  - Created bogus files like `beads.db?mode=ro`
+  - Caused `bd doctor` to incorrectly report "version pre-0.17.5 (very old)" on modern databases
+
+- **bd-17d5: Conflict marker false positives on JSON-encoded content**
+  - Issues containing JSON strings with `<<<<<<<` would trigger false conflict marker detection
+  - Now checks raw bytes before JSON decoding to avoid false positives
+
+- **bd-ckvw: Schema compatibility probe prevents silent migration failures**
+  - Migrations could fail silently, causing cryptic "no such column" and UNIQUE constraint errors later
+  - Now probes schema after migrations, retries once if incomplete, and fails fast with clear error
+  - Daemon refuses RPC if client has newer minor version to prevent schema mismatches
+
+- **#264/#262: Remove stale `--resolve-collisions` references**
+  - Docs/error messages still referenced `--resolve-collisions` flag (removed in v0.20)
+  - Fixed post-merge hook error messages and git-hooks README
+
+### Changed
+
+- **bd-auf1: Auto-cleanup snapshot files after successful merge**
+  - `.beads/` no longer accumulates orphaned `.base`, `.ours`, `.theirs` snapshot files after merges
+
+- **bd-ky74: Optimize CLI tests with in-process testing**
+  - Converted exec.Command() tests to in-process rootCmd.Execute() calls
+  - **Dramatically faster: 10+ minutes → just a few seconds**
+  - Improved test coverage from 20.2% to 23.3%
+
+- **bd-6uix: Message system improvements**
+  - 30s HTTP timeout prevents hangs, full message reading, --importance validation, server-side filtering
+
+- **Remove noisy version field from metadata.json**
+  - Eliminated redundant version mismatch warnings on every bd upgrade
+  - Daemon version checking via RPC is sufficient
+
+### Added
+
+- Go agent example with Agent Mail support
+- Agent Mail multi-workspace deployment guide and scripts
+
+## [0.23.0] - 2025-11-08
+
+### Added
+
+- **Agent Mail Integration**: Complete Python adapter library with comprehensive documentation and multi-agent coordination tests
+  - Python adapter library in `integrations/agent-mail-python/`
+  - Agent Mail quickstart guide and comprehensive integration docs
+  - Multi-agent race condition tests and failure scenario tests
+  - Automated git traffic benchmark showing **98.5% reduction in git traffic** compared to git-only sync
+  - Bash-agent integration example
+
+- **bd info --whats-new** (bd-eiz9): Agent version awareness for quick upgrade summaries
+  - Shows last 3 versions with workflow-impacting changes
+  - Supports `--json` flag for machine-readable output
+  - Helps agents understand what changed without re-reading full docs
+
+- **bd hooks install** (bd-908z): Embedded git hooks command
+  - Replaces external install script with native command
+  - Git hooks now embedded in bd binary
+  - Works for all bd users, not just source repo users
+
+- **bd cleanup**: Bulk deletion command for closed issues (bd-buol)
+  - Agent-driven compaction for large databases
+  - Removes closed issues older than specified threshold
+
+### Fixed
+
+- **3-way JSONL Merge** (bd-jjua): Auto-invoked on conflicts
+  - Automatically triggers intelligent merge on JSONL conflicts
+  - No manual intervention required
+  - Warning message added to zombie issues.jsonl file
+
+- **Auto-import on Missing Database** (ab4ec90): `bd import` now auto-initializes database when missing
+- **Daemon Crash Recovery** (bd-vcg5): Panic handler with socket cleanup prevents orphaned processes
+- **Stale Database Exports** (bd-srwk): ID-based staleness detection prevents exporting stale data
+- **Windows MCP Subprocess Timeout** (bd-r79z): Fix for git detection on Windows
+- **Daemon Orphaning** (a6c9579): Track parent PID and exit when parent dies
+- **Test Pollution Prevention** (bd-z528, bd-2c5a): Safeguards to prevent test issues in production database
+- **Client Self-Heal** (a236558): Auto-recovery for stale daemon.pid files
+- **Post-Merge Hook Error Messages** (abb1d1c): Show actual error messages instead of silent failures
+- **Auto-import During Delete** (bd-8kde): Disable auto-import during delete operations to prevent conflicts
+- **MCP Workspace Context** (bd-8zf2): Auto-detect workspace from CWD
+- **Import Sync Warning** (bd-u4f5): Warn when import syncs with working tree but not git HEAD
+- **GH#254** (bd-tuqd): `bd init` now detects and chains with existing git hooks
+- **GH#249**: Add nil storage checks to prevent RPC daemon crashes
+- **GH#252**: Fix SQLite driver name mismatch causing "unknown driver" errors
+- **Nested .beads Directories** (bd-eqjc): Prevent creating nested .beads directories
+- **Windows SQLite Support**: Fix SQLite in releases for Windows
+
+### Changed
+
+- **Agent Affordances** (observations from agents using beads):
+  - **bd new**: Added as alias for `bd create` command (agents often tried this)
+  - **bd list**: Changed default to one-line-per-issue format to prevent agent miscounting; added `--long` flag for previous detailed format
+
+- **Developer Experience**:
+  - Extracted supplemental docs from AGENTS.md for better organization
+  - Added warning for working tree vs git HEAD sync mismatches
+  - Completion commands now work without database
+  - Config included in `bd info` JSON output
+  - Python cache files added to .gitignore
+  - RPC diagnostics available via `BD_RPC_DEBUG` env var
+  - Reduced RPC dial timeout from 2s to 200ms for fast-fail (bd-expt)
+  - Standardized daemon detection with tryDaemonLock probe (bd-wgu4)
+  - Improved internal/daemon test coverage to 60%
+
+- **Code Organization**:
+  - Refactored snapshot management into dedicated module (bd-urob)
+  - Documented external_ref in content hash behavior (bd-9f4a)
+  - Added MCP server functions for repair commands (bd-7bbc4e6a)
+  - Added version number to beads-mcp startup log
+  - Added system requirements section for glibc compatibility in docs
+
+- **Release Automation**:
+  - Automatic Homebrew formula update in release workflow
+  - Gitignore Formula/bd.rb (auto-generated, real source is homebrew-beads tap)
+
+- **Other**:
+  - Added `docs/` directory to links (#242)
+  - RPC monitoring solution with web UI as implementation example (#244)
+  - Remove old install.sh script, replaced by `bd hooks install`
+  - Remove vc.db exclusion from FindDatabasePath filter
+
+## [0.22.1] - 2025-11-06
+
+### Added
+
+- **Vendored beads-merge by @neongreen** (bd-bzfy): Native `bd merge` command for intelligent JSONL merging
+  - Vendored beads-merge algorithm into `internal/merge/` with full attribution and MIT license
+  - New `bd merge` command as native wrapper (no external binary needed)
+  - Same field-level 3-way merge algorithm, now built into bd
+  - Auto-configured during `bd init` (both interactive and `--quiet` modes)
+  - Thanks to @neongreen for permission to vendor: https://github.com/neongreen/mono/issues/240
+  - Original tool: https://github.com/neongreen/mono/tree/main/beads-merge
+
+- **Git Hook Version Detection** (bd-iou5, 991c624): `bd info` now detects outdated git hooks
+  - Adds version markers to all git hook templates (pre-commit, post-merge, pre-push)
+  - Warns when installed hooks are outdated or missing
+  - Suggests running `examples/git-hooks/install.sh` to update
+  - Prevents issues like the `--resolve-collisions` flag error after updates
+
+- **Public API for External Extensions** (8f676a4): Extensibility improvements for third-party tools
+- **Multi-Repo Patterns Documentation** (e73f89e): Comprehensive guide for AI agents working across multiple repositories
+- **Snapshot Versioning** (a891ebe): Add versioning and timestamp validation for snapshots
+- `--clear-duplicate-external-refs` flag for `bd import` command (9de98cf)
+
+### Fixed
+
+- **Multi-Workspace Deletion Tracking** (708a81c, e5a6c05, 4718583): Proper deletion tracking across multiple workspaces
+  - Fixes issue where deletions in one workspace weren't propagated to others
+  - Added `DeleteIssue` to Storage interface for backend extensibility (e291ee0)
+- **Import/Export Deadlock** (a0d24f3): Prevent import/export from hanging when daemon is running
+- **Pre-Push Hook** (3ba245e): Fix pre-push hook blocking instead of exporting
+- **Hash ID Recognition** (c924731, 055f1d9): Fix `isHashID` to recognize Base36 hash IDs and IDs without a-f letters
+- **Git Merge Artifacts** (41b1a21): Ignore merge artifacts in `.beads/.gitignore`
+- **bd status Command** (1edf3c6): Now uses git history for recent activity detection
+- **Performance**: Add raw string equality short-circuit before jsonEquals (5c1f441)
+
+### Changed
+
+- **Code Organization**:
+  - Extract SQLite migrations into separate files (b655b29)
+  - Centralize BD_DEBUG logging into `internal/debug` package (95cbcf4)
+  - Extract `normalizeLabels` to `internal/util/strings.go` (9520e7a)
+  - Reorganize project structure: move Go files to `internal/beads`, docs to `docs/` (584c266)
+  - Remove unused `internal/daemonrunner/` package (~1,500 LOC) (a7ec8a2)
+
+- **Testing**:
+  - Optimize test suite with `testing.Short()` guards for faster local testing (11fa142, 0f4b03e)
+  - Add comprehensive tests for merge driver auto-config (6424ebd)
+  - Add comprehensive tests for 3-way merge functionality (14b2d34)
+  - Add edge case tests for `getMultiRepoJSONLPaths()` (78c9d74)
+
+- **CI/CD**:
+  - Separate Homebrew update workflow with PAT support (739786e)
+  - Add manual trigger to Homebrew workflow for testing (563c12b)
+  - Fix Linux checksums extraction in Homebrew workflow (c47f40b)
+  - Add script to automate Nix vendorHash updates (#235)
+
+### Performance
+
+- Cache `getMultiRepoJSONLPaths()` to avoid redundant calls (7afb143)
+
+## [0.22.0] - 2025-11-05
+
+### Added
+
+- **Intelligent Merge Driver** (bd-omx1, 52c5059): Auto-configured git merge driver for JSONL conflict resolution
+  - Vendors beads-merge algorithm for field-level 3-way merging
+  - Automatically configured during `bd init` (both interactive and `--quiet` modes)
+  - Matches issues by identity (id + created_at + created_by)
+  - Smart field merging: timestamps→max, dependencies→union, status/priority→3-way
+  - Eliminates most git merge conflicts in `.beads/beads.jsonl`
+
+- **Onboarding Wizards** (b230a22): New `bd init` workflows for different collaboration models
+  - `bd init --contributor`: OSS contributor wizard (separate planning repo)
+  - `bd init --team`: Team collaboration wizard (branch-based workflow)
+  - Interactive setup with fork detection and remote configuration
+  - Auto-configures sync settings for each workflow
+
+- **Migration Tools** (349817a): New `bd migrate-issues` command for cross-repo issue migration
+  - Migrate issues between repositories while preserving dependencies
+  - Source filtering (by label, priority, status, type)
+  - Automatic remote repo detection and push
+  - Complete multi-repo workflow documentation
+
+- **Multi-Phase Development Guide** (3ecc16e): Comprehensive workflow examples
+  - Multi-phase development (feature → integration → deployment)
+  - Multiple personas (designer, frontend dev, backend dev)
+  - Best practices for complex projects
+
+- **Dependency Status** (3acaf1d): Show blocker status in `bd show` output
+  - Displays "Blocked by N open issues" when dependencies exist
+  - Shows "Ready to work (no blockers)" when unblocked
+
+- **DevContainer Support** (247e659): Automatic bd setup in GitHub Codespaces
+  - Pre-configured Go environment with bd pre-installed
+  - Auto-detects existing `.beads/` and imports on startup
+
+- **Landing the Plane Protocol** (095e40d): Session-ending checklist for AI agents
+  - Quality gates, sync procedures, git cleanup
+  - Ensures clean handoff between sessions
+
+### Fixed
+
+- **SearchIssues N+1 Query** (bd-5ots, e90e485): Eliminated N+1 query bug in label loading
+  - Batch-loads labels for all issues in one query
+  - Significant performance improvement for `bd list` with many labeled issues
+
+- **Sync Validation** (bd-9bsx, 5438485): Prevent infinite dirty loop in auto-sync
+  - Added export verification to detect write failures
+  - Ensures JSONL line count matches database after export
+
+- **bd edit Direct Mode** (GH #227, d4c73c3): Force `bd edit` to always use direct mode
+  - Prevents daemon interference with interactive editor sessions
+  - Resolves hang issues when editing in terminals
+
+- **SQLite Driver on arm64 macOS** (f9771cd): Fixed missing SQLite driver in arm64 builds
+  - Explicitly imports CGO-enabled sqlite driver
+  - Resolves "database driver not found" errors on Apple Silicon
+
+- **external_ref Type Handling** (e1e58ef): Handle both string and *string in UpdateIssue RPC
+  - Fixes type mismatch errors in MCP server
+  - Ensures consistent API behavior
+
+- **Windows Test Stability** (2ac28b0, 8c5e51e): Skip flaky concurrent tests on Windows
+  - Prevents false failures in CI/CD
+  - Improves overall test suite reliability
+
+### Changed
+
+- **Test Suite Performance** (0fc4da7): Optimized test suite for 15-18x speedup
+  - Reduced redundant database operations
+  - Parallelized independent test cases
+  - Faster CI/CD builds
+
+- **Priority Format** (b8785d3): Added support for P-prefix priority format (P0-P4)
+  - Accepts both `--priority 1` and `--priority P1`
+  - More intuitive for GitHub/Jira users
+
+- **--label Alias** (85ca8c3): Added `--label` as alias for `--labels` in `bd create`
+  - Both singular and plural forms now work
+  - Improved CLI ergonomics
+
+- **--parent Flag in Daemon Mode** (fc89f15): Added `--parent` support in daemon RPC
+  - MCP server can now set parent relationships
+  - Parity with CLI functionality
+
+### Documentation
+
+- **Multi-Repo Migration Guide** (9e60ed1): Complete documentation for multi-repo workflows
+  - OSS contributors, teams, multi-phase development
+  - Addresses common questions about fork vs branch workflows
+
+- **beads-merge Setup Instructions** (527e491): Enhanced merge driver documentation
+  - Installation guide for standalone binary
+  - Jujutsu configuration examples
+
+## [0.21.9] - 2025-11-05
+
+### Added
+
+- **Epic/Child Filtering** (bd-zkl, fbe790a): New `bd list` filters for hierarchical issue queries
+  - `--ancestor <id>`: Filter by ancestor issue (shows all descendants)
+  - `--parent <id>`: Filter by direct parent issue
+  - `--epic <id>`: Alias for `--ancestor` (more intuitive for epic-based workflows)
+  - `ancestor_id` field added to issue type for efficient epic hierarchy queries
+
+- **Advanced List Filters**: Pattern matching, date ranges, and empty checks
+  - **Pattern matching**: `--title-contains`, `--desc-contains`, `--notes-contains` (case-insensitive substring)
+  - **Date ranges**: `--created-after/before`, `--updated-after/before`, `--closed-after/before`
+  - **Empty checks**: `--empty-description`, `--no-assignee`, `--no-labels`
+  - **Priority ranges**: `--priority-min`, `--priority-max`
+
+- **Database Migration** (bd-bb08, 3bde4b0): Added `ON DELETE CASCADE` to `child_counters` table
+  - Prevents orphaned child counter records when issues are deleted
+  - Comprehensive migration tests ensure data integrity
+
+### Fixed
+
+- **Import Timestamp Preservation** (8b9a486): Fixed critical bug where `closed_at` timestamps were lost during sync
+  - Ensures closed issues retain their original completion timestamps
+  - Prevents issue resurrection timestamps from overwriting real closure times
+
+- **Import Config Respect** (7292c85): Import now respects `import.missing_parents` config setting
+  - Previously ignored config for parent resurrection behavior
+  - Now correctly honors user's preference for handling missing parents
+
+- **GoReleaser Homebrew Tap** (37ed10c): Fixed homebrew tap to point to `steveyegge/homebrew-beads`
+  - Automated homebrew formula updates now work correctly
+  - Resolves brew installation issues
+
+- **npm Package Versioning** (626d51d): Added npm-package to version bump script
+  - Ensures `@beads/bd` npm package stays in sync with CLI releases
+  - Prevents version mismatches across distribution channels
+
+- **Linting** (52cf2af): Fixed golangci-lint errors
+  - Added proper error handling
+  - Added gosec suppressions for known-safe operations
+
+### Changed
+
+- **RPC Filter Parity** (510ca17): Comprehensive test coverage for CLI vs RPC filter behavior
+  - Ensures MCP server and CLI have identical filtering semantics
+  - Validates all new filters work correctly in both modes
+
+## [0.21.8] - 2025-11-05
+
 ### Added
 
 - **Parent Resurrection** (bd-58c0): Automatic resurrection of deleted parent issues from JSONL history
@@ -24,6 +621,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - **JSONL Resurrection Logic**: Fixed to use LAST occurrence instead of FIRST (append-only semantics)
+- **Version Bump Script**: Added `--tag` and `--push` flags to automate release tagging
+  - Addresses confusion where version bump doesn't trigger GitHub release
+  - New usage: `./scripts/bump-version.sh X.Y.Z --commit --tag --push`
 
 ## [0.21.7] - 2025-11-04
 

package/bin/README.md

@@ -58,6 +58,7 @@ Agents report that they enjoy working with Beads, and they will use it spontaneo
 - 🤖 **Agent-friendly** - `--json` flags for programmatic integration
 - 📦 **Git-versioned** - JSONL records stored in git, synced across machines
 - 🌍 **Distributed by design** - Agents on multiple machines share one logical database via git
+- 🚀 **Optional Agent Mail** - Real-time multi-agent coordination (<100ms vs 2-5s git sync, 98.5% reduction in git traffic)
 - 🔐 **Protected branch support** - Works with GitHub/GitLab protected branches via separate sync branch
 - 🏗️ **Extensible** - Add your own tables to the SQLite database
 - 🔍 **Multi-project isolation** - Each project gets its own database, auto-discovered by directory
@@ -67,6 +68,22 @@ Agents report that they enjoy working with Beads, and they will use it spontaneo
 - ⚡ **High performance** - Batch operations for bulk imports (1000 issues in ~950ms)
 - 🗜️ **Memory decay** - Semantic compaction gracefully reduces old closed issues
 
+## Requirements
+
+**Linux users:** Beads requires **glibc 2.32+** (Ubuntu 22.04+, Debian 11+, RHEL 9+, or equivalent).
+
+- ✅ **Supported:** Ubuntu 22.04+ (Jammy), Debian 11+ (Bullseye), Fedora 34+, RHEL 9+
+- ❌ **Not supported:** Ubuntu 20.04 (glibc 2.31), Debian 10 (glibc 2.28), CentOS 7, RHEL 8
+
+**Ubuntu 20.04 users:** Standard support ended April 2025. Please upgrade to Ubuntu 22.04+ or build from source:
+```bash
+git clone https://github.com/steveyegge/beads.git
+cd beads
+go build -o bd ./cmd/bd
+```
+
+**macOS/Windows:** No special requirements.
+
 ## Installation
 
 **npm (Node.js environments, Claude Code for Web):**
@@ -74,20 +91,23 @@ Agents report that they enjoy working with Beads, and they will use it spontaneo
 npm install -g @beads/bd
 ```
 
-**Quick install (all platforms):**
+**Quick install (macOS / Linux):**
 ```bash
 curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
 ```
 
+**Quick install (Windows - PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
+```
+
 **Homebrew (macOS/Linux):**
 ```bash
 brew tap steveyegge/beads
 brew install bd
 ```
 
-**Other platforms and methods:** See [INSTALLING.md](INSTALLING.md) for Windows, Arch Linux, and manual installation.
-
-**IDE Integration:** See [INSTALLING.md](INSTALLING.md) for Claude Code plugin and MCP server setup.
+For full, platform-specific instructions (Windows, Arch Linux, manual builds, IDE integrations, etc.) see the canonical guide in [docs/INSTALLING.md](docs/INSTALLING.md).
 
 **Claude Code for Web:** See [npm-package/CLAUDE_CODE_WEB.md](npm-package/CLAUDE_CODE_WEB.md) for SessionStart hook setup.
 
@@ -102,6 +122,12 @@ Beads is designed for **AI coding agents** to use on your behalf. Setup takes 30
 # In your project root:
 bd init
 
+# For OSS contributors (fork workflow):
+bd init --contributor
+
+# For team members (branch workflow):
+bd init --team
+
 # For protected branches (GitHub/GitLab):
 bd init --branch beads-metadata
 
@@ -109,6 +135,7 @@ bd init --branch beads-metadata
 # - Create .beads/ directory with database
 # - Import existing issues from git (if any)
 # - Prompt to install git hooks (recommended: say yes)
+# - Prompt to configure git merge driver (recommended: say yes)
 # - Auto-start daemon for sync
 
 # Then tell your agent about bd:
@@ -123,10 +150,39 @@ echo "BEFORE ANYTHING ELSE: run 'bd onboard' and follow the instructions" >> AGE
 3. Update CLAUDE.md with a note (if present)
 4. Remove the bootstrap instruction
 
-**For agents setting up repos:** Use `bd init --quiet` for non-interactive setup (auto-installs git hooks, no prompts).
+**For agents setting up repos:** Use `bd init --quiet` for non-interactive setup (auto-installs git hooks and merge driver, no prompts).
 
 **For new repo clones:** Run `bd init` (or `bd init --quiet` for agents) to import existing issues from `.beads/issues.jsonl` automatically.
 
+**Git merge driver:** During `bd init`, beads configures git to use `bd merge` for intelligent JSONL merging. This prevents conflicts when multiple branches modify issues. Skip with `--skip-merge-driver` if needed. To configure manually later:
+```bash
+git config merge.beads.driver "bd merge %A %O %L %R"
+git config merge.beads.name "bd JSONL merge driver"
+echo ".beads/beads.jsonl merge=beads" >> .gitattributes
+```
+
+### Files Created by `bd init`
+
+**`bd init` creates these files in your repository:**
+
+**Should be committed to git:**
+- `.gitattributes` - Configures git merge driver for intelligent JSONL merging (critical for team collaboration)
+- `.beads/beads.jsonl` - Issue data in JSONL format (source of truth, synced via git)
+- `.beads/config.yaml` - Repository configuration template
+- `.beads/README.md` - Documentation about beads for repository visitors
+- `.beads/metadata.json` - Database metadata
+
+**Should be in `.gitignore` (local-only):**
+- `.beads/beads.db` - SQLite cache (auto-synced with JSONL)
+- `.beads/beads.db-*` - SQLite journal files
+- `.beads/bd.sock` / `.beads/bd.pipe` - Daemon communication socket
+- `.beads/.exclusive-lock` - Daemon lock file
+- `.git/beads-worktrees/` - Git worktrees (only created when using protected branch workflows)
+
+The `.gitignore` entries are automatically created inside `.beads/.gitignore` by `bd init`, but your project's root `.gitignore` should also exclude the database and daemon files if you want to keep your git status clean.
+
+**Using devcontainers?** Open the repository in a devcontainer (GitHub Codespaces or VS Code Remote Containers) and bd will be automatically installed with git hooks configured. See [.devcontainer/README.md](.devcontainer/README.md) for details.
+
 Most tasks will be created and managed by agents during conversations. You can check on things with:
 
 ```bash
@@ -163,6 +219,34 @@ bd update <issue-id> --status in_progress --json
 bd close <issue-id> --reason "Implemented" --json
 ```
 
+## Configuring Your Own AGENTS.md
+
+**Recommendation for project maintainers:** Add a session-ending protocol to your project's `AGENTS.md` file to ensure agents properly manage issue tracking and sync the database before finishing work.
+
+This pattern has proven invaluable for maintaining database hygiene and preventing lost work. Here's what to include (adapt for your workflow):
+
+**1. File/update issues for remaining work**
+- Agents should proactively create issues for discovered bugs, TODOs, and follow-up tasks
+- Close completed issues and update status for in-progress work
+
+**2. Run quality gates (if applicable)**
+- Tests, linters, builds - only if code changes were made
+- File P0 issues if builds are broken
+
+**3. Sync the issue tracker carefully**
+- Work methodically to ensure local and remote issues merge safely
+- Handle git conflicts thoughtfully (sometimes accepting remote and re-importing)
+- Goal: clean reconciliation where no issues are lost
+
+**4. Verify clean state**
+- All changes committed and pushed
+- No untracked files remain
+
+**5. Choose next work**
+- Provide a formatted prompt for the next session with context
+
+See the ["Landing the Plane"](AGENT_INSTRUCTIONS.md#landing-the-plane) section in this project's documentation for a complete example you can adapt. The key insight: explicitly reminding agents to maintain issue tracker hygiene prevents the common problem of agents creating issues during work but forgetting to sync them at session end.
+
 ## The Magic: Distributed Database via Git
 
 Here's the crazy part: **bd acts like a centralized database, but it's actually distributed via git.**
@@ -387,6 +471,32 @@ bd list --assignee alice                   # Filter by assignee
 bd list --label=backend,urgent             # Filter by labels (AND)
 bd list --label-any=frontend,backend       # Filter by labels (OR)
 
+# Advanced filters
+bd list --title-contains "auth"            # Search title
+bd list --desc-contains "implement"        # Search description
+bd list --notes-contains "TODO"            # Search notes
+bd list --id bd-123,bd-456                 # Specific IDs (comma-separated)
+
+# Date range filters (YYYY-MM-DD or RFC3339)
+bd list --created-after 2024-01-01         # Created after date
+bd list --created-before 2024-12-31        # Created before date
+bd list --updated-after 2024-06-01         # Updated after date
+bd list --updated-before 2024-12-31        # Updated before date
+bd list --closed-after 2024-01-01          # Closed after date
+bd list --closed-before 2024-12-31         # Closed before date
+
+# Empty/null checks
+bd list --empty-description                # Issues with no description
+bd list --no-assignee                      # Unassigned issues
+bd list --no-labels                        # Issues with no labels
+
+# Priority ranges
+bd list --priority-min 0 --priority-max 1  # P0 and P1 only
+bd list --priority-min 2                   # P2 and below
+
+# Combine multiple filters
+bd list --status open --priority 1 --label-any urgent,critical --no-assignee
+
 # JSON output for agents
 bd info --json
 bd list --json
@@ -479,7 +589,7 @@ bd list --label backend,auth     # AND: must have ALL labels
 bd list --label-any frontend,ui  # OR: must have AT LEAST ONE
 ```
 
-**See [LABELS.md](LABELS.md) for complete label documentation and best practices.**
+**See [docs/LABELS.md](docs/LABELS.md) for complete label documentation and best practices.**
 
 ### Deleting Issues
 
@@ -521,18 +631,28 @@ bd config list --json
 bd config unset jira.url
 ```
 
-**See [CONFIG.md](CONFIG.md) for complete configuration documentation.**
+**See [docs/CONFIG.md](docs/CONFIG.md) for complete configuration documentation.**
 
 ### Compaction (Memory Decay)
 
-Beads uses AI to compress old closed issues, keeping databases lightweight as they age:
+Beads provides **agent-driven compaction** - your AI agent decides what to compress, no API keys required:
 
 ```bash
-bd compact --dry-run --all  # Preview candidates
-bd compact --days 90        # Compact closed issues older than 90 days
+# Agent-driven workflow (recommended)
+bd compact --analyze --json              # Get candidates with full content
+bd compact --apply --id bd-42 --summary summary.txt
+
+# Legacy AI-powered workflow (requires ANTHROPIC_API_KEY)
+bd compact --auto --dry-run --all        # Preview candidates
+bd compact --auto --all                  # Auto-compact all eligible issues
 ```
 
-This is agentic memory decay - your database naturally forgets fine-grained details while preserving essential context.
+**How it works:**
+1. Use `--analyze` to export candidates (closed 30+ days) with full content
+2. Summarize the content using any LLM (Claude, GPT, local model, etc.)
+3. Use `--apply` to persist the summary and mark as compacted
+
+This is agentic memory decay - your database naturally forgets fine-grained details while preserving essential context. The agent has full control over compression quality.
 
 ### Export/Import
 
@@ -564,6 +684,10 @@ bd daemons health
 bd daemons stop /path/to/workspace
 bd daemons stop 12345  # By PID
 
+# Restart a specific daemon
+bd daemons restart /path/to/workspace
+bd daemons restart 12345  # By PID
+
 # View daemon logs
 bd daemons logs /path/to/workspace -n 100
 bd daemons logs 12345 -f  # Follow mode
@@ -580,6 +704,39 @@ bd daemons killall --force  # Force kill if graceful fails
 
 See [commands/daemons.md](commands/daemons.md) for complete documentation.
 
+### Web Interface
+
+A standalone web interface for real-time issue monitoring is available as an example:
+
+```bash
+# Build the monitor-webui
+cd examples/monitor-webui
+go build
+
+# Start web UI on localhost:8080
+./monitor-webui
+
+# Custom port and host
+./monitor-webui -port 3000
+./monitor-webui -host 0.0.0.0 -port 8080  # Listen on all interfaces
+```
+
+The monitor provides:
+- **Real-time table view** of all issues with filtering by status and priority
+- **Click-through details** - Click any issue to view full details in a modal
+- **Live updates** - WebSocket connection for real-time changes via daemon RPC
+- **Responsive design** - Mobile-friendly card view on small screens
+- **Statistics dashboard** - Quick overview of issue counts and ready work
+- **Clean UI** - Simple, fast interface styled with milligram.css
+
+The monitor is particularly useful for:
+- **Team visibility** - Share a dashboard view of project status
+- **AI agent supervision** - Watch your coding agent create and update issues in real-time
+- **Quick browsing** - Faster than CLI for exploring issue details
+- **Mobile access** - Check project status from your phone
+
+See [examples/monitor-webui/](examples/monitor-webui/) for complete documentation.
+
 ## Examples
 
 Check out the **[examples/](examples/)** directory for:
@@ -594,24 +751,28 @@ Check out the **[examples/](examples/)** directory for:
 
 For advanced usage, see:
 
-- **[ADVANCED.md](ADVANCED.md)** - Prefix renaming, merging duplicates, daemon configuration
-- **[CONFIG.md](CONFIG.md)** - Configuration system for integrations
-- **[EXTENDING.md](EXTENDING.md)** - Database extension patterns
-- **[ADVANCED.md](ADVANCED.md)** - JSONL format and merge strategies
+- **[docs/ADVANCED.md](docs/ADVANCED.md)** - Prefix renaming, merging duplicates, daemon configuration
+- **[docs/CONFIG.md](docs/CONFIG.md)** - Configuration system for integrations
+- **[docs/EXTENDING.md](docs/EXTENDING.md)** - Database extension patterns
+- **[docs/ADVANCED.md](docs/ADVANCED.md)** - JSONL format and merge strategies
 
 ## Documentation
 
 - **[README.md](README.md)** - You are here! Core features and quick start
-- **[INSTALLING.md](INSTALLING.md)** - Complete installation guide for all platforms
-- **[QUICKSTART.md](QUICKSTART.md)** - Interactive tutorial (`bd quickstart`)
-- **[FAQ.md](FAQ.md)** - Frequently asked questions
-- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common issues and solutions
-- **[ADVANCED.md](ADVANCED.md)** - Advanced features and use cases
-- **[LABELS.md](LABELS.md)** - Complete label system guide
-- **[CONFIG.md](CONFIG.md)** - Configuration system
-- **[EXTENDING.md](EXTENDING.md)** - Database extension patterns
-- **[ADVANCED.md](ADVANCED.md)** - JSONL format analysis
-- **[PLUGIN.md](PLUGIN.md)** - Claude Code plugin documentation
+- **[docs/INSTALLING.md](docs/INSTALLING.md)** - Complete installation guide for all platforms
+- **[docs/QUICKSTART.md](docs/QUICKSTART.md)** - Interactive tutorial (`bd quickstart`)
+- **[docs/AGENT_MAIL_QUICKSTART.md](docs/AGENT_MAIL_QUICKSTART.md)** - 5-minute Agent Mail setup guide
+- **[docs/AGENT_MAIL.md](docs/AGENT_MAIL.md)** - Complete Agent Mail integration guide
+- **[docs/MULTI_REPO_MIGRATION.md](docs/MULTI_REPO_MIGRATION.md)** - Multi-repo workflow guide (OSS, teams, multi-phase)
+- **[docs/MULTI_REPO_AGENTS.md](docs/MULTI_REPO_AGENTS.md)** - Multi-repo patterns for AI agents
+- **[docs/FAQ.md](docs/FAQ.md)** - Frequently asked questions
+- **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Common issues and solutions
+- **[docs/ADVANCED.md](docs/ADVANCED.md)** - Advanced features and use cases
+- **[docs/LABELS.md](docs/LABELS.md)** - Complete label system guide
+- **[docs/CONFIG.md](docs/CONFIG.md)** - Configuration system
+- **[docs/EXTENDING.md](docs/EXTENDING.md)** - Database extension patterns
+- **[docs/ADVANCED.md](docs/ADVANCED.md)** - JSONL format analysis
+- **[docs/PLUGIN.md](docs/PLUGIN.md)** - Claude Code plugin documentation
 - **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guidelines
 - **[SECURITY.md](SECURITY.md)** - Security policy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beads/bd",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Beads issue tracker - lightweight memory system for coding agents with native binary support",
   "main": "bin/bd.js",
   "bin": {