feat: complete bd-kwro messaging & knowledge graph epic

- Add bd cleanup --ephemeral flag for transient message cleanup (bd-kwro.9) - Add Ephemeral filter to IssueFilter type - Add ephemeral filtering to SQLite storage queries Tests (bd-kwro.10): - Add internal/hooks/hooks_test.go for hook system - Add cmd/bd/mail_test.go for mail commands - Add internal/storage/sqlite/graph_links_test.go for graph links Documentation (bd-kwro.11): - Add docs/messaging.md for full messaging reference - Add docs/graph-links.md for graph link types - Update AGENTS.md with inter-agent messaging section - Update CHANGELOG.md with all bd-kwro features 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-16 20:36:47 -08:00
parent 46bfb43b8d
commit 8d73a86f7a
11 changed files with 1874 additions and 5 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -332,6 +332,47 @@ bd close bd-42 "Done"                       # Updates via git sync

 See [docs/AGENT_MAIL_QUICKSTART.md](docs/AGENT_MAIL_QUICKSTART.md) for 5-minute setup, or [docs/AGENT_MAIL.md](docs/AGENT_MAIL.md) for complete documentation. Example code in [examples/python-agent/AGENT_MAIL_EXAMPLE.md](examples/python-agent/AGENT_MAIL_EXAMPLE.md).

+### Inter-Agent Messaging (bd mail)
+
+Beads includes a built-in messaging system for direct agent-to-agent communication. Messages are stored as beads issues, synced via git.
+
+**Setup:**
+
+```bash
+# Set your identity (add to environment or .beads/config.json)
+export BEADS_IDENTITY="worker-1"
+```
+
+**Commands:**
+
+```bash
+# Send a message
+bd mail send <recipient> -s "Subject" -m "Body"
+bd mail send worker-2 -s "Handoff" -m "Your turn on bd-xyz" --urgent
+
+# Check your inbox
+bd mail inbox
+
+# Read a specific message
+bd mail read bd-a1b2
+
+# Acknowledge (mark as read/close)
+bd mail ack bd-a1b2
+
+# Reply to a message (creates thread)
+bd mail reply bd-a1b2 -m "Thanks, on it!"
+```
+
+**Use cases:**
+- Task handoffs between agents
+- Status updates to coordinator
+- Blocking questions requiring response
+- Priority signaling with `--urgent` flag
+
+**Cleanup:** Messages are ephemeral. Run `bd cleanup --ephemeral --force` to delete closed messages.
+
+See [docs/messaging.md](docs/messaging.md) for full documentation.
+
 ### Deletion Tracking

 When issues are deleted (via `bd delete` or `bd cleanup`), they are recorded in `.beads/deletions.jsonl`. This manifest:
@@ -378,10 +419,19 @@ bd deleted --json              # Machine-readable output

 ### Dependency Types

+**Blocking dependencies:**
 - `blocks` - Hard dependency (issue X blocks issue Y)
- `related` - Soft relationship (issues are connected)
+
+**Structural relationships:**
 - `parent-child` - Epic/subtask relationship
 - `discovered-from` - Track issues discovered during work (automatically inherits parent's `source_repo`)
+- `related` - Soft relationship (issues are connected)
+
+**Graph links:** (see [docs/graph-links.md](docs/graph-links.md))
+- `relates_to` - Bidirectional "see also" links (`bd relate <id1> <id2>`)
+- `duplicates` - Mark issue as duplicate (`bd duplicate <id> --of <canonical>`)
+- `supersedes` - Version chains (`bd supersede <old> --with <new>`)
+- `replies_to` - Message threads (`bd mail reply`)

 Only `blocks` dependencies affect the ready work queue.

--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  - New dependency types: `replies-to`, `relates-to`, `duplicates`, `supersedes`
  - Schema migration 019 (automatic on first use)

+- **`bd mail` commands** (bd-kwro.6) - Inter-agent messaging
+  - `bd mail send <recipient> -s <subject> -m <body>` - Send messages
+  - `bd mail inbox` - List open messages for your identity
+  - `bd mail read <id>` - Display message content
+  - `bd mail ack <id>` - Acknowledge (close) messages
+  - `bd mail reply <id> -m <body>` - Reply to messages (creates threads)
+  - Identity via `BEADS_IDENTITY` env var or `.beads/config.json`
+
+- **Graph link commands** (bd-kwro.2-5) - Knowledge graph relationships
+  - `bd relate <id1> <id2>` - Create bidirectional "see also" links
+  - `bd unrelate <id1> <id2>` - Remove relates_to links
+  - `bd duplicate <id> --of <canonical>` - Mark issue as duplicate (closes it)
+  - `bd supersede <old> --with <new>` - Mark issue as superseded (closes it)
+  - `bd show --thread` - View message threads via replies_to chain
+
+- **Hooks system** (bd-kwro.8) - Extensible event notifications
+  - `.beads/hooks/on_create` - Runs after issue creation
+  - `.beads/hooks/on_update` - Runs after issue update
+  - `.beads/hooks/on_close` - Runs after issue close
+  - `.beads/hooks/on_message` - Runs after message send
+  - Hooks receive issue ID, event type as args, full JSON on stdin
+
+- **`bd cleanup --ephemeral` flag** (bd-kwro.9) - Clean up transient messages
+  - Deletes only closed issues with `ephemeral=true`
+  - Useful for cleaning up messages after swarms complete
+
 ### Fixed

 - **Windows build errors** (GH#585) - Fixed gosec lint warnings
@@ -37,6 +63,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ### Documentation

+- **Messaging documentation** (bd-kwro.11) - New docs for messaging system
+  - `docs/messaging.md` - Full messaging reference with examples
+  - `docs/graph-links.md` - Graph link types and use cases
+  - Updated `AGENTS.md` with inter-agent messaging section
+
 - Windows installation command in upgrade instructions (GH#589)
  - Contributed by @alexx-ftw

--- a/cmd/bd/cleanup.go
+++ b/cmd/bd/cleanup.go
@@ -42,6 +42,9 @@ Delete all closed issues and prune tombstones:
 Delete issues closed more than 30 days ago:
  bd cleanup --older-than 30 --force

+Delete only closed ephemeral issues (transient messages):
+  bd cleanup --ephemeral --force
+
 Preview what would be deleted/pruned:
  bd cleanup --dry-run
  bd cleanup --older-than 90 --dry-run
@@ -64,6 +67,7 @@ SEE ALSO:
 		cascade, _ := cmd.Flags().GetBool("cascade")
 		olderThanDays, _ := cmd.Flags().GetInt("older-than")
 		hardDelete, _ := cmd.Flags().GetBool("hard")
+		ephemeralOnly, _ := cmd.Flags().GetBool("ephemeral")

 		// Calculate custom TTL for --hard mode
 		// When --hard is set, use --older-than days as the tombstone TTL cutoff
@@ -108,6 +112,12 @@ SEE ALSO:
 			filter.ClosedBefore = &cutoffTime
 		}

+		// Add ephemeral filter if specified (bd-kwro.9)
+		if ephemeralOnly {
+			ephemeralTrue := true
+			filter.Ephemeral = &ephemeralTrue
+		}
+
 		// Get all closed issues matching filter
 		closedIssues, err := store.SearchIssues(ctx, "", filter)
 		if err != nil {
@@ -124,11 +134,18 @@ SEE ALSO:
 				if olderThanDays > 0 {
 					result["filter"] = fmt.Sprintf("older than %d days", olderThanDays)
 				}
+				if ephemeralOnly {
+					result["ephemeral"] = true
+				}
 				output, _ := json.MarshalIndent(result, "", "  ")
 				fmt.Println(string(output))
 			} else {
 				msg := "No closed issues to delete"
-				if olderThanDays > 0 {
+				if ephemeralOnly && olderThanDays > 0 {
+					msg = fmt.Sprintf("No closed ephemeral issues older than %d days to delete", olderThanDays)
+				} else if ephemeralOnly {
+					msg = "No closed ephemeral issues to delete"
+				} else if olderThanDays > 0 {
 					msg = fmt.Sprintf("No closed issues older than %d days to delete", olderThanDays)
 				}
 				fmt.Println(msg)
@@ -144,15 +161,23 @@ SEE ALSO:

 		// Show preview
 		if !force && !dryRun {
-			fmt.Fprintf(os.Stderr, "Would delete %d closed issue(s). Use --force to confirm or --dry-run to preview.\n", len(issueIDs))
+			issueType := "closed"
+			if ephemeralOnly {
+				issueType = "closed ephemeral"
+			}
+			fmt.Fprintf(os.Stderr, "Would delete %d %s issue(s). Use --force to confirm or --dry-run to preview.\n", len(issueIDs), issueType)
 			os.Exit(1)
 		}

 		if !jsonOutput {
+			issueType := "closed"
+			if ephemeralOnly {
+				issueType = "closed ephemeral"
+			}
 			if olderThanDays > 0 {
-				fmt.Printf("Found %d closed issue(s) older than %d days\n", len(closedIssues), olderThanDays)
+				fmt.Printf("Found %d %s issue(s) older than %d days\n", len(closedIssues), issueType, olderThanDays)
 			} else {
-				fmt.Printf("Found %d closed issue(s)\n", len(closedIssues))
+				fmt.Printf("Found %d %s issue(s)\n", len(closedIssues), issueType)
 			}
 			if dryRun {
 				fmt.Println(color.YellowString("DRY RUN - no changes will be made"))
@@ -211,5 +236,6 @@ func init() {
 	cleanupCmd.Flags().Bool("cascade", false, "Recursively delete all dependent issues")
 	cleanupCmd.Flags().Int("older-than", 0, "Only delete issues closed more than N days ago (0 = all closed issues)")
 	cleanupCmd.Flags().Bool("hard", false, "Bypass tombstone TTL safety; use --older-than days as cutoff")
+	cleanupCmd.Flags().Bool("ephemeral", false, "Only delete closed ephemeral issues (transient messages)")
 	rootCmd.AddCommand(cleanupCmd)
 }
--- a/cmd/bd/mail_test.go
+++ b/cmd/bd/mail_test.go
@@ -0,0 +1,376 @@
+package main
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/steveyegge/beads/internal/types"
+)
+
+func TestMailSendAndInbox(t *testing.T) {
+	tmpDir := t.TempDir()
+	testStore := newTestStore(t, tmpDir+"/.beads/beads.db")
+	ctx := context.Background()
+
+	// Set up global state
+	oldStore := store
+	oldRootCtx := rootCtx
+	oldActor := actor
+	store = testStore
+	rootCtx = ctx
+	actor = "test-user"
+	defer func() {
+		store = oldStore
+		rootCtx = oldRootCtx
+		actor = oldActor
+	}()
+
+	// Create a message (simulating mail send)
+	now := time.Now()
+	msg := &types.Issue{
+		Title:       "Test Subject",
+		Description: "Test message body",
+		Status:      types.StatusOpen,
+		Priority:    2,
+		IssueType:   types.TypeMessage,
+		Assignee:    "worker-1",
+		Sender:      "manager",
+		Ephemeral:   true,
+		CreatedAt:   now,
+		UpdatedAt:   now,
+	}
+
+	if err := testStore.CreateIssue(ctx, msg, actor); err != nil {
+		t.Fatalf("Failed to create message: %v", err)
+	}
+
+	// Query inbox for worker-1
+	messageType := types.TypeMessage
+	openStatus := types.StatusOpen
+	assignee := "worker-1"
+	filter := types.IssueFilter{
+		IssueType: &messageType,
+		Status:    &openStatus,
+		Assignee:  &assignee,
+	}
+
+	messages, err := testStore.SearchIssues(ctx, "", filter)
+	if err != nil {
+		t.Fatalf("SearchIssues failed: %v", err)
+	}
+
+	if len(messages) != 1 {
+		t.Fatalf("Expected 1 message, got %d", len(messages))
+	}
+
+	if messages[0].Title != "Test Subject" {
+		t.Errorf("Title = %q, want %q", messages[0].Title, "Test Subject")
+	}
+	if messages[0].Sender != "manager" {
+		t.Errorf("Sender = %q, want %q", messages[0].Sender, "manager")
+	}
+	if !messages[0].Ephemeral {
+		t.Error("Ephemeral should be true")
+	}
+}
+
+func TestMailInboxEmpty(t *testing.T) {
+	tmpDir := t.TempDir()
+	testStore := newTestStore(t, tmpDir+"/.beads/beads.db")
+	ctx := context.Background()
+
+	// Query inbox for non-existent user
+	messageType := types.TypeMessage
+	openStatus := types.StatusOpen
+	assignee := "nobody"
+	filter := types.IssueFilter{
+		IssueType: &messageType,
+		Status:    &openStatus,
+		Assignee:  &assignee,
+	}
+
+	messages, err := testStore.SearchIssues(ctx, "", filter)
+	if err != nil {
+		t.Fatalf("SearchIssues failed: %v", err)
+	}
+
+	if len(messages) != 0 {
+		t.Errorf("Expected 0 messages, got %d", len(messages))
+	}
+}
+
+func TestMailAck(t *testing.T) {
+	tmpDir := t.TempDir()
+	testStore := newTestStore(t, tmpDir+"/.beads/beads.db")
+	ctx := context.Background()
+
+	// Create a message
+	now := time.Now()
+	msg := &types.Issue{
+		Title:       "Ack Test",
+		Description: "Test body",
+		Status:      types.StatusOpen,
+		Priority:    2,
+		IssueType:   types.TypeMessage,
+		Assignee:    "recipient",
+		Sender:      "sender",
+		Ephemeral:   true,
+		CreatedAt:   now,
+		UpdatedAt:   now,
+	}
+
+	if err := testStore.CreateIssue(ctx, msg, "test"); err != nil {
+		t.Fatalf("Failed to create message: %v", err)
+	}
+
+	// Acknowledge (close) the message
+	if err := testStore.CloseIssue(ctx, msg.ID, "acknowledged", "test"); err != nil {
+		t.Fatalf("Failed to close message: %v", err)
+	}
+
+	// Verify it's closed
+	updated, err := testStore.GetIssue(ctx, msg.ID)
+	if err != nil {
+		t.Fatalf("GetIssue failed: %v", err)
+	}
+
+	if updated.Status != types.StatusClosed {
+		t.Errorf("Status = %q, want %q", updated.Status, types.StatusClosed)
+	}
+
+	// Verify it no longer appears in inbox
+	messageType := types.TypeMessage
+	openStatus := types.StatusOpen
+	assignee := "recipient"
+	filter := types.IssueFilter{
+		IssueType: &messageType,
+		Status:    &openStatus,
+		Assignee:  &assignee,
+	}
+
+	messages, err := testStore.SearchIssues(ctx, "", filter)
+	if err != nil {
+		t.Fatalf("SearchIssues failed: %v", err)
+	}
+
+	if len(messages) != 0 {
+		t.Errorf("Expected 0 messages in inbox after ack, got %d", len(messages))
+	}
+}
+
+func TestMailReply(t *testing.T) {
+	tmpDir := t.TempDir()
+	testStore := newTestStore(t, tmpDir+"/.beads/beads.db")
+	ctx := context.Background()
+
+	// Create original message
+	now := time.Now()
+	original := &types.Issue{
+		Title:       "Original Subject",
+		Description: "Original body",
+		Status:      types.StatusOpen,
+		Priority:    2,
+		IssueType:   types.TypeMessage,
+		Assignee:    "worker",
+		Sender:      "manager",
+		Ephemeral:   true,
+		CreatedAt:   now,
+		UpdatedAt:   now,
+	}
+
+	if err := testStore.CreateIssue(ctx, original, "test"); err != nil {
+		t.Fatalf("Failed to create original message: %v", err)
+	}
+
+	// Create reply
+	reply := &types.Issue{
+		Title:       "Re: Original Subject",
+		Description: "Reply body",
+		Status:      types.StatusOpen,
+		Priority:    2,
+		IssueType:   types.TypeMessage,
+		Assignee:    "manager", // Reply goes to original sender
+		Sender:      "worker",
+		Ephemeral:   true,
+		RepliesTo:   original.ID, // Thread link
+		CreatedAt:   now.Add(time.Minute),
+		UpdatedAt:   now.Add(time.Minute),
+	}
+
+	if err := testStore.CreateIssue(ctx, reply, "test"); err != nil {
+		t.Fatalf("Failed to create reply: %v", err)
+	}
+
+	// Verify reply has correct thread link
+	savedReply, err := testStore.GetIssue(ctx, reply.ID)
+	if err != nil {
+		t.Fatalf("GetIssue failed: %v", err)
+	}
+
+	if savedReply.RepliesTo != original.ID {
+		t.Errorf("RepliesTo = %q, want %q", savedReply.RepliesTo, original.ID)
+	}
+}
+
+func TestMailPriority(t *testing.T) {
+	tmpDir := t.TempDir()
+	testStore := newTestStore(t, tmpDir+"/.beads/beads.db")
+	ctx := context.Background()
+
+	// Create messages with different priorities
+	now := time.Now()
+	messages := []struct {
+		title    string
+		priority int
+	}{
+		{"Normal message", 2},
+		{"Urgent message", 0},
+		{"High priority", 1},
+	}
+
+	for i, m := range messages {
+		msg := &types.Issue{
+			Title:       m.title,
+			Description: "Body",
+			Status:      types.StatusOpen,
+			Priority:    m.priority,
+			IssueType:   types.TypeMessage,
+			Assignee:    "inbox",
+			Sender:      "sender",
+			Ephemeral:   true,
+			CreatedAt:   now.Add(time.Duration(i) * time.Minute),
+			UpdatedAt:   now.Add(time.Duration(i) * time.Minute),
+		}
+		if err := testStore.CreateIssue(ctx, msg, "test"); err != nil {
+			t.Fatalf("Failed to create message %d: %v", i, err)
+		}
+	}
+
+	// Query all messages
+	messageType := types.TypeMessage
+	openStatus := types.StatusOpen
+	assignee := "inbox"
+	filter := types.IssueFilter{
+		IssueType: &messageType,
+		Status:    &openStatus,
+		Assignee:  &assignee,
+	}
+
+	results, err := testStore.SearchIssues(ctx, "", filter)
+	if err != nil {
+		t.Fatalf("SearchIssues failed: %v", err)
+	}
+
+	if len(results) != 3 {
+		t.Fatalf("Expected 3 messages, got %d", len(results))
+	}
+
+	// Verify we can filter by priority
+	urgentPriority := 0
+	urgentFilter := types.IssueFilter{
+		IssueType: &messageType,
+		Status:    &openStatus,
+		Assignee:  &assignee,
+		Priority:  &urgentPriority,
+	}
+
+	urgent, err := testStore.SearchIssues(ctx, "", urgentFilter)
+	if err != nil {
+		t.Fatalf("SearchIssues failed: %v", err)
+	}
+
+	if len(urgent) != 1 {
+		t.Errorf("Expected 1 urgent message, got %d", len(urgent))
+	}
+}
+
+func TestMailTypeValidation(t *testing.T) {
+	tmpDir := t.TempDir()
+	testStore := newTestStore(t, tmpDir+"/.beads/beads.db")
+	ctx := context.Background()
+
+	// Create a regular issue (not a message)
+	now := time.Now()
+	task := &types.Issue{
+		Title:     "Regular Task",
+		Status:    types.StatusOpen,
+		Priority:  2,
+		IssueType: types.TypeTask,
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+
+	if err := testStore.CreateIssue(ctx, task, "test"); err != nil {
+		t.Fatalf("Failed to create task: %v", err)
+	}
+
+	// Query for messages should not return the task
+	messageType := types.TypeMessage
+	filter := types.IssueFilter{
+		IssueType: &messageType,
+	}
+
+	messages, err := testStore.SearchIssues(ctx, "", filter)
+	if err != nil {
+		t.Fatalf("SearchIssues failed: %v", err)
+	}
+
+	for _, m := range messages {
+		if m.ID == task.ID {
+			t.Errorf("Task %s should not appear in message query", task.ID)
+		}
+	}
+}
+
+func TestMailSenderField(t *testing.T) {
+	tmpDir := t.TempDir()
+	testStore := newTestStore(t, tmpDir+"/.beads/beads.db")
+	ctx := context.Background()
+
+	// Create messages from different senders
+	now := time.Now()
+	senders := []string{"alice", "bob", "charlie"}
+
+	for i, sender := range senders {
+		msg := &types.Issue{
+			Title:       "Message from " + sender,
+			Description: "Body",
+			Status:      types.StatusOpen,
+			Priority:    2,
+			IssueType:   types.TypeMessage,
+			Assignee:    "inbox",
+			Sender:      sender,
+			Ephemeral:   true,
+			CreatedAt:   now.Add(time.Duration(i) * time.Minute),
+			UpdatedAt:   now.Add(time.Duration(i) * time.Minute),
+		}
+		if err := testStore.CreateIssue(ctx, msg, "test"); err != nil {
+			t.Fatalf("Failed to create message from %s: %v", sender, err)
+		}
+	}
+
+	// Query all messages and verify sender
+	messageType := types.TypeMessage
+	filter := types.IssueFilter{
+		IssueType: &messageType,
+	}
+
+	messages, err := testStore.SearchIssues(ctx, "", filter)
+	if err != nil {
+		t.Fatalf("SearchIssues failed: %v", err)
+	}
+
+	senderSet := make(map[string]bool)
+	for _, m := range messages {
+		if m.Sender != "" {
+			senderSet[m.Sender] = true
+		}
+	}
+
+	for _, s := range senders {
+		if !senderSet[s] {
+			t.Errorf("Sender %q not found in messages", s)
+		}
+	}
+}
--- a/docs/graph-links.md
+++ b/docs/graph-links.md
@@ -0,0 +1,278 @@
+# Graph Links in Beads
+
+Beads supports several types of links between issues to create a knowledge graph. These links enable rich querying and traversal beyond simple blocking dependencies.
+
+## Link Types
+
+### replies_to - Conversation Threading
+
+Creates message threads, similar to email or chat conversations.
+
+**Created by:**
+- `bd mail reply <id>` command
+
+**Use cases:**
+- Agent-to-agent message threads
+- Discussion chains on issues
+- Follow-up communications
+
+**Example:**
+
+```bash
+# Original message
+bd mail send worker-1 -s "Review needed" -m "Please review bd-xyz"
+# Creates: bd-a1b2
+
+# Reply (automatically sets replies_to: bd-a1b2)
+bd mail reply bd-a1b2 -m "Done! Approved with minor comments."
+# Creates: bd-c3d4 with replies_to: bd-a1b2
+```
+
+**Viewing threads:**
+
+```bash
+bd show bd-a1b2 --thread
+```
+
+### relates_to - Loose Associations
+
+Bidirectional "see also" links between related issues. Not blocking, not hierarchical - just related.
+
+**Created by:**
+- `bd relate <id1> <id2>` - Links both issues to each other
+
+**Removed by:**
+- `bd unrelate <id1> <id2>` - Removes link in both directions
+
+**Use cases:**
+- Cross-referencing related features
+- Linking bugs to associated tasks
+- Building knowledge graphs
+- "See also" connections
+
+**Example:**
+
+```bash
+# Link two related issues
+bd relate bd-auth bd-security
+# Result: bd-auth.relates_to includes bd-security
+#         bd-security.relates_to includes bd-auth
+
+# View related issues
+bd show bd-auth
+# Shows: Related: bd-security
+
+# Remove the link
+bd unrelate bd-auth bd-security
+```
+
+**Multiple links:**
+An issue can have multiple relates_to links:
+
+```bash
+bd relate bd-api bd-auth
+bd relate bd-api bd-docs
+bd relate bd-api bd-tests
+# bd-api now relates to 3 issues
+```
+
+### duplicates - Deduplication
+
+Marks an issue as a duplicate of a canonical issue. The duplicate is automatically closed.
+
+**Created by:**
+- `bd duplicate <id> --of <canonical>`
+
+**Use cases:**
+- Consolidating duplicate bug reports
+- Merging similar feature requests
+- Database deduplication at scale
+
+**Example:**
+
+```bash
+# Two similar bug reports exist
+bd show bd-bug1  # "Login fails on Safari"
+bd show bd-bug2  # "Safari login broken"
+
+# Mark bug2 as duplicate of bug1
+bd duplicate bd-bug2 --of bd-bug1
+# Result: bd-bug2 is closed with duplicate_of: bd-bug1
+
+# View shows the relationship
+bd show bd-bug2
+# Status: closed
+# Duplicate of: bd-bug1
+```
+
+**Behavior:**
+- Duplicate issue is automatically closed
+- Original (canonical) issue remains open
+- `duplicate_of` field stores the canonical ID
+
+### supersedes - Version Chains
+
+Marks an issue as superseded by a newer version. The old issue is automatically closed.
+
+**Created by:**
+- `bd supersede <old-id> --with <new-id>`
+
+**Use cases:**
+- Design document versions
+- Spec evolution
+- Artifact versioning
+- RFC chains
+
+**Example:**
+
+```bash
+# Original design doc
+bd create --title "Design Doc v1" --type task
+# Creates: bd-doc1
+
+# Later, create updated version
+bd create --title "Design Doc v2" --type task
+# Creates: bd-doc2
+
+# Mark v1 as superseded
+bd supersede bd-doc1 --with bd-doc2
+# Result: bd-doc1 closed with superseded_by: bd-doc2
+
+# View shows the chain
+bd show bd-doc1
+# Status: closed
+# Superseded by: bd-doc2
+```
+
+**Behavior:**
+- Old issue is automatically closed
+- New issue remains in its current state
+- `superseded_by` field stores the replacement ID
+
+## Schema Fields
+
+These fields are added to issues:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `replies_to` | string | ID of parent message (threading) |
+| `relates_to` | []string | IDs of related issues (bidirectional) |
+| `duplicate_of` | string | ID of canonical issue |
+| `superseded_by` | string | ID of replacement issue |
+
+## Querying Links
+
+### View Issue Details
+
+```bash
+bd show <id>
+```
+
+Shows all link types for an issue:
+
+```
+bd-auth: Implement authentication
+Status: open
+Priority: P1
+
+Related to (3):
+  bd-security: Security audit
+  bd-users: User management
+  bd-sessions: Session handling
+```
+
+### View Threads
+
+```bash
+bd show <id> --thread
+```
+
+Follows `replies_to` chain to show conversation history.
+
+### JSON Output
+
+```bash
+bd show <id> --json
+```
+
+Returns all fields including graph links:
+
+```json
+{
+  "id": "bd-auth",
+  "title": "Implement authentication",
+  "relates_to": ["bd-security", "bd-users", "bd-sessions"],
+  "duplicate_of": "",
+  "superseded_by": ""
+}
+```
+
+## Comparison with Dependencies
+
+| Link Type | Blocking? | Hierarchical? | Direction |
+|-----------|-----------|---------------|-----------|
+| `blocks` | Yes | No | One-way |
+| `parent_id` | No | Yes | One-way |
+| `relates_to` | No | No | Bidirectional |
+| `replies_to` | No | No | One-way |
+| `duplicate_of` | No | No | One-way |
+| `superseded_by` | No | No | One-way |
+
+## Use Cases
+
+### Knowledge Base
+
+Link related documentation:
+
+```bash
+bd relate bd-api-ref bd-quickstart
+bd relate bd-api-ref bd-examples
+bd relate bd-quickstart bd-install
+```
+
+### Bug Triage
+
+Consolidate duplicate reports:
+
+```bash
+# Find potential duplicates
+bd duplicates
+
+# Merge duplicates
+bd duplicate bd-bug42 --of bd-bug17
+bd duplicate bd-bug58 --of bd-bug17
+```
+
+### Version History
+
+Track document evolution:
+
+```bash
+bd supersede bd-rfc1 --with bd-rfc2
+bd supersede bd-rfc2 --with bd-rfc3
+# bd-rfc3 is now the current version
+```
+
+### Message Threading
+
+Build conversation chains:
+
+```bash
+bd mail send dev -s "Question" -m "How does X work?"
+bd mail reply bd-q1 -m "X works by..."
+bd mail reply bd-q1.reply -m "Thanks!"
+```
+
+## Best Practices
+
+1. **Use relates_to sparingly** - Too many links become noise
+2. **Prefer specific link types** - `duplicates` is clearer than generic relates_to
+3. **Keep threads shallow** - Deep reply chains are hard to follow
+4. **Document supersedes chains** - Note why version changed
+5. **Query before creating duplicates** - `bd search` first
+
+## See Also
+
+- [Messaging](messaging.md) - Mail commands and threading
+- [Dependencies](QUICKSTART.md#dependencies) - Blocking dependencies
+- [CLI Reference](CLI_REFERENCE.md) - All commands
--- a/docs/messaging.md
+++ b/docs/messaging.md
@@ -0,0 +1,254 @@
+# Beads Messaging System
+
+Beads provides a built-in messaging system for inter-agent communication. Messages are stored as beads issues with type `message`, enabling git-native communication without external services.
+
+## Overview
+
+The messaging system enables:
+- **Agent-to-agent communication** - Send messages between workers
+- **Thread tracking** - Replies link back to original messages
+- **Priority signaling** - Mark messages as urgent (P0) or routine
+- **Ephemeral cleanup** - Messages can be bulk-deleted after completion
+
+## Identity Configuration
+
+Before using mail commands, configure your identity:
+
+### Environment Variable
+
+```bash
+export BEADS_IDENTITY="worker-1"
+```
+
+### Config File
+
+Add to `.beads/config.json`:
+
+```json
+{
+  "identity": "worker-1"
+}
+```
+
+### Priority
+
+1. `--identity` flag (if provided)
+2. `BEADS_IDENTITY` environment variable
+3. `.beads/config.json` identity field
+4. System username (fallback)
+
+## Commands
+
+### Send a Message
+
+```bash
+bd mail send <recipient> -s <subject> -m <body>
+```
+
+**Options:**
+- `-s, --subject` - Message subject (required)
+- `-m, --body` - Message body (required)
+- `--urgent` - Set priority=0 (urgent)
+- `--identity` - Override sender identity
+
+**Examples:**
+
+```bash
+# Basic message
+bd mail send worker-1 -s "Task complete" -m "Finished bd-xyz"
+
+# Urgent message
+bd mail send manager -s "Blocked!" -m "Need credentials for deploy" --urgent
+
+# With custom identity
+bd mail send worker-2 -s "Handoff" -m "Your turn on bd-abc" --identity refinery
+```
+
+### Check Your Inbox
+
+```bash
+bd mail inbox
+```
+
+Lists all open messages addressed to your identity.
+
+**Options:**
+- `--from <sender>` - Filter by sender
+- `--priority <n>` - Filter by priority (0-4)
+
+**Output:**
+
+```
+Inbox for worker-1 (2 messages):
+
+  bd-a1b2: Task assigned [URGENT]
+      From: manager (5m ago)
+
+  bd-c3d4: FYI: Design doc updated
+      From: worker-2 (1h ago)
+      Re: bd-x7y8
+```
+
+### Read a Message
+
+```bash
+bd mail read <id>
+```
+
+Displays full message content. Does NOT mark as read.
+
+**Example output:**
+
+```
+──────────────────────────────────────────────────────────────────
+ID:      bd-a1b2
+From:    manager
+To:      worker-1
+Subject: Task assigned
+Time:    2025-12-16 10:30:45
+Priority: P0
+Status:  open
+──────────────────────────────────────────────────────────────────
+
+Please prioritize bd-xyz. It's blocking the release.
+
+Let me know if you need anything.
+```
+
+### Acknowledge (Mark as Read)
+
+```bash
+bd mail ack <id> [id2...]
+```
+
+Closes messages to mark them as acknowledged.
+
+**Examples:**
+
+```bash
+# Single message
+bd mail ack bd-a1b2
+
+# Multiple messages
+bd mail ack bd-a1b2 bd-c3d4 bd-e5f6
+```
+
+### Reply to a Message
+
+```bash
+bd mail reply <id> -m <body>
+```
+
+Creates a threaded reply to an existing message.
+
+**Options:**
+- `-m, --body` - Reply body (required)
+- `--urgent` - Set priority=0
+- `--identity` - Override sender identity
+
+**Behavior:**
+- Sets `replies_to` to original message ID
+- Sends to original message's sender
+- Prefixes subject with "Re:" if not already present
+
+**Example:**
+
+```bash
+bd mail reply bd-a1b2 -m "On it! Should be done by EOD."
+```
+
+## Message Storage
+
+Messages are stored as issues with these fields:
+
+| Field | Description |
+|-------|-------------|
+| `type` | `message` |
+| `title` | Subject line |
+| `description` | Message body |
+| `assignee` | Recipient identity |
+| `sender` | Sender identity |
+| `priority` | 0 (urgent) to 4 (routine), default 2 |
+| `ephemeral` | `true` - can be bulk-deleted |
+| `replies_to` | ID of parent message (for threads) |
+| `status` | `open` (unread) / `closed` (read) |
+
+## Cleanup
+
+Messages are ephemeral by default and can be cleaned up:
+
+```bash
+# Preview ephemeral message cleanup
+bd cleanup --ephemeral --dry-run
+
+# Delete all closed ephemeral messages
+bd cleanup --ephemeral --force
+```
+
+## Hooks
+
+The messaging system fires hooks when messages are sent:
+
+**Hook file:** `.beads/hooks/on_message`
+
+The hook receives:
+- **Arg 1:** Issue ID
+- **Arg 2:** Event type (`message`)
+- **Stdin:** Full issue JSON
+
+**Example hook:**
+
+```bash
+#!/bin/sh
+# .beads/hooks/on_message
+
+ISSUE_ID="$1"
+EVENT="$2"
+
+# Parse assignee from JSON stdin
+ASSIGNEE=$(cat | jq -r '.assignee')
+
+# Notify recipient (example: send to external system)
+curl -X POST "https://example.com/notify" \
+  -d "to=$ASSIGNEE&message=$ISSUE_ID"
+```
+
+Make the hook executable:
+
+```bash
+chmod +x .beads/hooks/on_message
+```
+
+## JSON Output
+
+All commands support `--json` for programmatic use:
+
+```bash
+bd mail inbox --json
+bd mail read bd-a1b2 --json
+bd mail send worker-1 -s "Hi" -m "Test" --json
+```
+
+## Thread Visualization
+
+Use `bd show --thread` to view message threads:
+
+```bash
+bd show bd-c3d4 --thread
+```
+
+This shows the full conversation chain via `replies_to` links.
+
+## Best Practices
+
+1. **Use descriptive subjects** - Recipients scan subjects first
+2. **Mark urgent sparingly** - P0 should be reserved for blockers
+3. **Acknowledge promptly** - Keep inbox clean
+4. **Clean up after sprints** - Run `bd cleanup --ephemeral` periodically
+5. **Configure identity** - Use `BEADS_IDENTITY` for consistent sender names
+
+## See Also
+
+- [Graph Links](graph-links.md) - Other link types (relates_to, duplicates, supersedes)
+- [Hooks](EXTENDING.md) - Custom hook scripts
+- [Config](CONFIG.md) - Configuration options
--- a/internal/hooks/hooks_test.go
+++ b/internal/hooks/hooks_test.go
@@ -0,0 +1,334 @@
+package hooks
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/steveyegge/beads/internal/types"
+)
+
+func TestNewRunner(t *testing.T) {
+	runner := NewRunner("/tmp/hooks")
+	if runner == nil {
+		t.Fatal("NewRunner returned nil")
+	}
+	if runner.hooksDir != "/tmp/hooks" {
+		t.Errorf("hooksDir = %q, want %q", runner.hooksDir, "/tmp/hooks")
+	}
+	if runner.timeout != 10*time.Second {
+		t.Errorf("timeout = %v, want %v", runner.timeout, 10*time.Second)
+	}
+}
+
+func TestNewRunnerFromWorkspace(t *testing.T) {
+	runner := NewRunnerFromWorkspace("/workspace")
+	if runner == nil {
+		t.Fatal("NewRunnerFromWorkspace returned nil")
+	}
+	expected := filepath.Join("/workspace", ".beads", "hooks")
+	if runner.hooksDir != expected {
+		t.Errorf("hooksDir = %q, want %q", runner.hooksDir, expected)
+	}
+}
+
+func TestEventToHook(t *testing.T) {
+	tests := []struct {
+		event    string
+		expected string
+	}{
+		{EventCreate, HookOnCreate},
+		{EventUpdate, HookOnUpdate},
+		{EventClose, HookOnClose},
+		{EventMessage, HookOnMessage},
+		{"unknown", ""},
+		{"", ""},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.event, func(t *testing.T) {
+			result := eventToHook(tt.event)
+			if result != tt.expected {
+				t.Errorf("eventToHook(%q) = %q, want %q", tt.event, result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestHookExists_NoHook(t *testing.T) {
+	tmpDir := t.TempDir()
+	runner := NewRunner(tmpDir)
+
+	if runner.HookExists(EventCreate) {
+		t.Error("HookExists returned true for non-existent hook")
+	}
+}
+
+func TestHookExists_NotExecutable(t *testing.T) {
+	tmpDir := t.TempDir()
+	hookPath := filepath.Join(tmpDir, HookOnCreate)
+
+	// Create a non-executable file
+	if err := os.WriteFile(hookPath, []byte("#!/bin/sh\necho test"), 0644); err != nil {
+		t.Fatalf("Failed to create hook file: %v", err)
+	}
+
+	runner := NewRunner(tmpDir)
+
+	if runner.HookExists(EventCreate) {
+		t.Error("HookExists returned true for non-executable hook")
+	}
+}
+
+func TestHookExists_Executable(t *testing.T) {
+	tmpDir := t.TempDir()
+	hookPath := filepath.Join(tmpDir, HookOnCreate)
+
+	// Create an executable file
+	if err := os.WriteFile(hookPath, []byte("#!/bin/sh\necho test"), 0755); err != nil {
+		t.Fatalf("Failed to create hook file: %v", err)
+	}
+
+	runner := NewRunner(tmpDir)
+
+	if !runner.HookExists(EventCreate) {
+		t.Error("HookExists returned false for executable hook")
+	}
+}
+
+func TestHookExists_Directory(t *testing.T) {
+	tmpDir := t.TempDir()
+	hookPath := filepath.Join(tmpDir, HookOnCreate)
+
+	// Create a directory instead of a file
+	if err := os.MkdirAll(hookPath, 0755); err != nil {
+		t.Fatalf("Failed to create directory: %v", err)
+	}
+
+	runner := NewRunner(tmpDir)
+
+	if runner.HookExists(EventCreate) {
+		t.Error("HookExists returned true for directory")
+	}
+}
+
+func TestRunSync_NoHook(t *testing.T) {
+	tmpDir := t.TempDir()
+	runner := NewRunner(tmpDir)
+
+	issue := &types.Issue{ID: "bd-test", Title: "Test"}
+
+	// Should not error when hook doesn't exist
+	err := runner.RunSync(EventCreate, issue)
+	if err != nil {
+		t.Errorf("RunSync returned error for non-existent hook: %v", err)
+	}
+}
+
+func TestRunSync_NotExecutable(t *testing.T) {
+	tmpDir := t.TempDir()
+	hookPath := filepath.Join(tmpDir, HookOnCreate)
+
+	// Create a non-executable file
+	if err := os.WriteFile(hookPath, []byte("#!/bin/sh\necho test"), 0644); err != nil {
+		t.Fatalf("Failed to create hook file: %v", err)
+	}
+
+	runner := NewRunner(tmpDir)
+	issue := &types.Issue{ID: "bd-test", Title: "Test"}
+
+	// Should not error when hook is not executable
+	err := runner.RunSync(EventCreate, issue)
+	if err != nil {
+		t.Errorf("RunSync returned error for non-executable hook: %v", err)
+	}
+}
+
+func TestRunSync_Success(t *testing.T) {
+	tmpDir := t.TempDir()
+	hookPath := filepath.Join(tmpDir, HookOnCreate)
+	outputFile := filepath.Join(tmpDir, "output.txt")
+
+	// Create a hook that writes to a file
+	hookScript := `#!/bin/sh
+echo "$1 $2" > ` + outputFile
+	if err := os.WriteFile(hookPath, []byte(hookScript), 0755); err != nil {
+		t.Fatalf("Failed to create hook file: %v", err)
+	}
+
+	runner := NewRunner(tmpDir)
+	issue := &types.Issue{ID: "bd-test", Title: "Test Issue"}
+
+	err := runner.RunSync(EventCreate, issue)
+	if err != nil {
+		t.Errorf("RunSync returned error: %v", err)
+	}
+
+	// Verify the hook ran and received correct arguments
+	output, err := os.ReadFile(outputFile)
+	if err != nil {
+		t.Fatalf("Failed to read output file: %v", err)
+	}
+
+	expected := "bd-test create\n"
+	if string(output) != expected {
+		t.Errorf("Hook output = %q, want %q", string(output), expected)
+	}
+}
+
+func TestRunSync_ReceivesJSON(t *testing.T) {
+	tmpDir := t.TempDir()
+	hookPath := filepath.Join(tmpDir, HookOnMessage)
+	outputFile := filepath.Join(tmpDir, "stdin.txt")
+
+	// Create a hook that captures stdin
+	hookScript := `#!/bin/sh
+cat > ` + outputFile
+	if err := os.WriteFile(hookPath, []byte(hookScript), 0755); err != nil {
+		t.Fatalf("Failed to create hook file: %v", err)
+	}
+
+	runner := NewRunner(tmpDir)
+	issue := &types.Issue{
+		ID:       "bd-msg",
+		Title:    "Test Message",
+		Sender:   "alice",
+		Assignee: "bob",
+	}
+
+	err := runner.RunSync(EventMessage, issue)
+	if err != nil {
+		t.Errorf("RunSync returned error: %v", err)
+	}
+
+	// Verify JSON was passed to stdin
+	output, err := os.ReadFile(outputFile)
+	if err != nil {
+		t.Fatalf("Failed to read output file: %v", err)
+	}
+
+	// Just check that it contains expected fields
+	if len(output) == 0 {
+		t.Error("Hook did not receive JSON input")
+	}
+	if string(output) == "" || output[0] != '{' {
+		t.Errorf("Hook input doesn't look like JSON: %s", string(output))
+	}
+}
+
+func TestRunSync_Timeout(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping timeout test in short mode")
+	}
+
+	tmpDir := t.TempDir()
+	hookPath := filepath.Join(tmpDir, HookOnCreate)
+
+	// Create a hook that sleeps for longer than timeout
+	hookScript := `#!/bin/sh
+sleep 60`
+	if err := os.WriteFile(hookPath, []byte(hookScript), 0755); err != nil {
+		t.Fatalf("Failed to create hook file: %v", err)
+	}
+
+	runner := &Runner{
+		hooksDir: tmpDir,
+		timeout:  500 * time.Millisecond, // Short timeout
+	}
+	issue := &types.Issue{ID: "bd-test", Title: "Test"}
+
+	start := time.Now()
+	err := runner.RunSync(EventCreate, issue)
+	elapsed := time.Since(start)
+
+	if err == nil {
+		t.Error("RunSync should have returned error for timeout")
+	}
+
+	// Should have returned within timeout + some buffer
+	if elapsed > 5*time.Second {
+		t.Errorf("RunSync took too long: %v", elapsed)
+	}
+}
+
+func TestRunSync_HookFailure(t *testing.T) {
+	tmpDir := t.TempDir()
+	hookPath := filepath.Join(tmpDir, HookOnUpdate)
+
+	// Create a hook that exits with error
+	hookScript := `#!/bin/sh
+exit 1`
+	if err := os.WriteFile(hookPath, []byte(hookScript), 0755); err != nil {
+		t.Fatalf("Failed to create hook file: %v", err)
+	}
+
+	runner := NewRunner(tmpDir)
+	issue := &types.Issue{ID: "bd-test", Title: "Test"}
+
+	err := runner.RunSync(EventUpdate, issue)
+	if err == nil {
+		t.Error("RunSync should have returned error for failed hook")
+	}
+}
+
+func TestRun_Async(t *testing.T) {
+	tmpDir := t.TempDir()
+	hookPath := filepath.Join(tmpDir, HookOnClose)
+	outputFile := filepath.Join(tmpDir, "async_output.txt")
+
+	// Create a hook that writes to a file
+	hookScript := `#!/bin/sh
+echo "async" > ` + outputFile
+	if err := os.WriteFile(hookPath, []byte(hookScript), 0755); err != nil {
+		t.Fatalf("Failed to create hook file: %v", err)
+	}
+
+	runner := NewRunner(tmpDir)
+	issue := &types.Issue{ID: "bd-test", Title: "Test"}
+
+	// Run should return immediately
+	runner.Run(EventClose, issue)
+
+	// Wait for the async hook to complete with retries
+	var output []byte
+	var err error
+	for i := 0; i < 10; i++ {
+		time.Sleep(100 * time.Millisecond)
+		output, err = os.ReadFile(outputFile)
+		if err == nil {
+			break
+		}
+	}
+
+	if err != nil {
+		t.Fatalf("Failed to read output file after retries: %v", err)
+	}
+
+	expected := "async\n"
+	if string(output) != expected {
+		t.Errorf("Hook output = %q, want %q", string(output), expected)
+	}
+}
+
+func TestAllHookEvents(t *testing.T) {
+	// Verify all event constants have corresponding hook names
+	events := []struct {
+		event string
+		hook  string
+	}{
+		{EventCreate, HookOnCreate},
+		{EventUpdate, HookOnUpdate},
+		{EventClose, HookOnClose},
+		{EventMessage, HookOnMessage},
+	}
+
+	for _, e := range events {
+		t.Run(e.event, func(t *testing.T) {
+			result := eventToHook(e.event)
+			if result != e.hook {
+				t.Errorf("eventToHook(%q) = %q, want %q", e.event, result, e.hook)
+			}
+		})
+	}
+}
--- a/internal/storage/sqlite/graph_links_test.go
+++ b/internal/storage/sqlite/graph_links_test.go
@@ -0,0 +1,499 @@
+package sqlite
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/steveyegge/beads/internal/types"
+)
+
+func TestRelatesTo(t *testing.T) {
+	store, cleanup := setupTestDB(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// Create two issues
+	issue1 := &types.Issue{
+		Title:     "Issue 1",
+		Status:    types.StatusOpen,
+		Priority:  2,
+		IssueType: types.TypeTask,
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+	}
+	issue2 := &types.Issue{
+		Title:     "Issue 2",
+		Status:    types.StatusOpen,
+		Priority:  2,
+		IssueType: types.TypeTask,
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+	}
+
+	if err := store.CreateIssue(ctx, issue1, "test"); err != nil {
+		t.Fatalf("Failed to create issue1: %v", err)
+	}
+	if err := store.CreateIssue(ctx, issue2, "test"); err != nil {
+		t.Fatalf("Failed to create issue2: %v", err)
+	}
+
+	// Add relates_to link (bidirectional)
+	relatesTo1, _ := json.Marshal([]string{issue2.ID})
+	if err := store.UpdateIssue(ctx, issue1.ID, map[string]interface{}{
+		"relates_to": string(relatesTo1),
+	}, "test"); err != nil {
+		t.Fatalf("Failed to update issue1 relates_to: %v", err)
+	}
+
+	relatesTo2, _ := json.Marshal([]string{issue1.ID})
+	if err := store.UpdateIssue(ctx, issue2.ID, map[string]interface{}{
+		"relates_to": string(relatesTo2),
+	}, "test"); err != nil {
+		t.Fatalf("Failed to update issue2 relates_to: %v", err)
+	}
+
+	// Verify links
+	updated1, err := store.GetIssue(ctx, issue1.ID)
+	if err != nil {
+		t.Fatalf("GetIssue failed: %v", err)
+	}
+	if len(updated1.RelatesTo) != 1 || updated1.RelatesTo[0] != issue2.ID {
+		t.Errorf("issue1.RelatesTo = %v, want [%s]", updated1.RelatesTo, issue2.ID)
+	}
+
+	updated2, err := store.GetIssue(ctx, issue2.ID)
+	if err != nil {
+		t.Fatalf("GetIssue failed: %v", err)
+	}
+	if len(updated2.RelatesTo) != 1 || updated2.RelatesTo[0] != issue1.ID {
+		t.Errorf("issue2.RelatesTo = %v, want [%s]", updated2.RelatesTo, issue1.ID)
+	}
+}
+
+func TestRelatesTo_MultipleLinks(t *testing.T) {
+	store, cleanup := setupTestDB(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// Create three issues
+	issues := make([]*types.Issue, 3)
+	for i := range issues {
+		issues[i] = &types.Issue{
+			Title:     "Issue",
+			Status:    types.StatusOpen,
+			Priority:  2,
+			IssueType: types.TypeTask,
+			CreatedAt: time.Now(),
+			UpdatedAt: time.Now(),
+		}
+		if err := store.CreateIssue(ctx, issues[i], "test"); err != nil {
+			t.Fatalf("Failed to create issue %d: %v", i, err)
+		}
+	}
+
+	// Link issue0 to both issue1 and issue2
+	relatesTo, _ := json.Marshal([]string{issues[1].ID, issues[2].ID})
+	if err := store.UpdateIssue(ctx, issues[0].ID, map[string]interface{}{
+		"relates_to": string(relatesTo),
+	}, "test"); err != nil {
+		t.Fatalf("Failed to update relates_to: %v", err)
+	}
+
+	// Verify
+	updated, err := store.GetIssue(ctx, issues[0].ID)
+	if err != nil {
+		t.Fatalf("GetIssue failed: %v", err)
+	}
+	if len(updated.RelatesTo) != 2 {
+		t.Errorf("RelatesTo has %d links, want 2", len(updated.RelatesTo))
+	}
+}
+
+func TestDuplicateOf(t *testing.T) {
+	store, cleanup := setupTestDB(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// Create canonical and duplicate issues
+	canonical := &types.Issue{
+		Title:     "Canonical Issue",
+		Status:    types.StatusOpen,
+		Priority:  2,
+		IssueType: types.TypeBug,
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+	}
+	duplicate := &types.Issue{
+		Title:     "Duplicate Issue",
+		Status:    types.StatusOpen,
+		Priority:  2,
+		IssueType: types.TypeBug,
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+	}
+
+	if err := store.CreateIssue(ctx, canonical, "test"); err != nil {
+		t.Fatalf("Failed to create canonical: %v", err)
+	}
+	if err := store.CreateIssue(ctx, duplicate, "test"); err != nil {
+		t.Fatalf("Failed to create duplicate: %v", err)
+	}
+
+	// Mark as duplicate and close
+	if err := store.UpdateIssue(ctx, duplicate.ID, map[string]interface{}{
+		"duplicate_of": canonical.ID,
+		"status":       string(types.StatusClosed),
+	}, "test"); err != nil {
+		t.Fatalf("Failed to mark as duplicate: %v", err)
+	}
+
+	// Verify
+	updated, err := store.GetIssue(ctx, duplicate.ID)
+	if err != nil {
+		t.Fatalf("GetIssue failed: %v", err)
+	}
+	if updated.DuplicateOf != canonical.ID {
+		t.Errorf("DuplicateOf = %q, want %q", updated.DuplicateOf, canonical.ID)
+	}
+	if updated.Status != types.StatusClosed {
+		t.Errorf("Status = %q, want %q", updated.Status, types.StatusClosed)
+	}
+}
+
+func TestSupersededBy(t *testing.T) {
+	store, cleanup := setupTestDB(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// Create old and new versions
+	oldVersion := &types.Issue{
+		Title:     "Design Doc v1",
+		Status:    types.StatusOpen,
+		Priority:  2,
+		IssueType: types.TypeTask,
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+	}
+	newVersion := &types.Issue{
+		Title:     "Design Doc v2",
+		Status:    types.StatusOpen,
+		Priority:  2,
+		IssueType: types.TypeTask,
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+	}
+
+	if err := store.CreateIssue(ctx, oldVersion, "test"); err != nil {
+		t.Fatalf("Failed to create old version: %v", err)
+	}
+	if err := store.CreateIssue(ctx, newVersion, "test"); err != nil {
+		t.Fatalf("Failed to create new version: %v", err)
+	}
+
+	// Mark old as superseded
+	if err := store.UpdateIssue(ctx, oldVersion.ID, map[string]interface{}{
+		"superseded_by": newVersion.ID,
+		"status":        string(types.StatusClosed),
+	}, "test"); err != nil {
+		t.Fatalf("Failed to mark as superseded: %v", err)
+	}
+
+	// Verify
+	updated, err := store.GetIssue(ctx, oldVersion.ID)
+	if err != nil {
+		t.Fatalf("GetIssue failed: %v", err)
+	}
+	if updated.SupersededBy != newVersion.ID {
+		t.Errorf("SupersededBy = %q, want %q", updated.SupersededBy, newVersion.ID)
+	}
+	if updated.Status != types.StatusClosed {
+		t.Errorf("Status = %q, want %q", updated.Status, types.StatusClosed)
+	}
+}
+
+func TestRepliesTo(t *testing.T) {
+	store, cleanup := setupTestDB(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// Create original message and reply
+	original := &types.Issue{
+		Title:       "Original Message",
+		Description: "Original content",
+		Status:      types.StatusOpen,
+		Priority:    2,
+		IssueType:   types.TypeMessage,
+		Sender:      "alice",
+		Assignee:    "bob",
+		Ephemeral:   true,
+		CreatedAt:   time.Now(),
+		UpdatedAt:   time.Now(),
+	}
+	reply := &types.Issue{
+		Title:       "Re: Original Message",
+		Description: "Reply content",
+		Status:      types.StatusOpen,
+		Priority:    2,
+		IssueType:   types.TypeMessage,
+		Sender:      "bob",
+		Assignee:    "alice",
+		Ephemeral:   true,
+		CreatedAt:   time.Now(),
+		UpdatedAt:   time.Now(),
+	}
+
+	if err := store.CreateIssue(ctx, original, "test"); err != nil {
+		t.Fatalf("Failed to create original: %v", err)
+	}
+
+	// Set replies_to before creation
+	reply.RepliesTo = original.ID
+	if err := store.CreateIssue(ctx, reply, "test"); err != nil {
+		t.Fatalf("Failed to create reply: %v", err)
+	}
+
+	// Verify thread link
+	savedReply, err := store.GetIssue(ctx, reply.ID)
+	if err != nil {
+		t.Fatalf("GetIssue failed: %v", err)
+	}
+	if savedReply.RepliesTo != original.ID {
+		t.Errorf("RepliesTo = %q, want %q", savedReply.RepliesTo, original.ID)
+	}
+}
+
+func TestRepliesTo_Chain(t *testing.T) {
+	store, cleanup := setupTestDB(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// Create a chain of replies
+	messages := make([]*types.Issue, 3)
+	var prevID string
+
+	for i := range messages {
+		messages[i] = &types.Issue{
+			Title:     "Message",
+			Status:    types.StatusOpen,
+			Priority:  2,
+			IssueType: types.TypeMessage,
+			Sender:    "user",
+			Assignee:  "inbox",
+			Ephemeral: true,
+			RepliesTo: prevID,
+			CreatedAt: time.Now(),
+			UpdatedAt: time.Now(),
+		}
+		if err := store.CreateIssue(ctx, messages[i], "test"); err != nil {
+			t.Fatalf("Failed to create message %d: %v", i, err)
+		}
+		prevID = messages[i].ID
+	}
+
+	// Verify chain
+	for i := 1; i < len(messages); i++ {
+		saved, err := store.GetIssue(ctx, messages[i].ID)
+		if err != nil {
+			t.Fatalf("GetIssue failed for message %d: %v", i, err)
+		}
+		if saved.RepliesTo != messages[i-1].ID {
+			t.Errorf("Message %d: RepliesTo = %q, want %q", i, saved.RepliesTo, messages[i-1].ID)
+		}
+	}
+}
+
+func TestEphemeralField(t *testing.T) {
+	store, cleanup := setupTestDB(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// Create ephemeral issue
+	ephemeral := &types.Issue{
+		Title:     "Ephemeral Issue",
+		Status:    types.StatusOpen,
+		Priority:  2,
+		IssueType: types.TypeMessage,
+		Ephemeral: true,
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+	}
+
+	// Create non-ephemeral issue
+	permanent := &types.Issue{
+		Title:     "Permanent Issue",
+		Status:    types.StatusOpen,
+		Priority:  2,
+		IssueType: types.TypeTask,
+		Ephemeral: false,
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+	}
+
+	if err := store.CreateIssue(ctx, ephemeral, "test"); err != nil {
+		t.Fatalf("Failed to create ephemeral: %v", err)
+	}
+	if err := store.CreateIssue(ctx, permanent, "test"); err != nil {
+		t.Fatalf("Failed to create permanent: %v", err)
+	}
+
+	// Verify ephemeral flag
+	savedEphemeral, err := store.GetIssue(ctx, ephemeral.ID)
+	if err != nil {
+		t.Fatalf("GetIssue failed: %v", err)
+	}
+	if !savedEphemeral.Ephemeral {
+		t.Error("Ephemeral issue should have Ephemeral=true")
+	}
+
+	savedPermanent, err := store.GetIssue(ctx, permanent.ID)
+	if err != nil {
+		t.Fatalf("GetIssue failed: %v", err)
+	}
+	if savedPermanent.Ephemeral {
+		t.Error("Permanent issue should have Ephemeral=false")
+	}
+}
+
+func TestEphemeralFilter(t *testing.T) {
+	store, cleanup := setupTestDB(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// Create mix of ephemeral and non-ephemeral issues
+	for i := 0; i < 3; i++ {
+		ephemeral := &types.Issue{
+			Title:     "Ephemeral",
+			Status:    types.StatusClosed, // Closed for cleanup test
+			Priority:  2,
+			IssueType: types.TypeMessage,
+			Ephemeral: true,
+			CreatedAt: time.Now(),
+			UpdatedAt: time.Now(),
+		}
+		if err := store.CreateIssue(ctx, ephemeral, "test"); err != nil {
+			t.Fatalf("Failed to create ephemeral %d: %v", i, err)
+		}
+	}
+
+	for i := 0; i < 2; i++ {
+		permanent := &types.Issue{
+			Title:     "Permanent",
+			Status:    types.StatusClosed,
+			Priority:  2,
+			IssueType: types.TypeTask,
+			Ephemeral: false,
+			CreatedAt: time.Now(),
+			UpdatedAt: time.Now(),
+		}
+		if err := store.CreateIssue(ctx, permanent, "test"); err != nil {
+			t.Fatalf("Failed to create permanent %d: %v", i, err)
+		}
+	}
+
+	// Filter for ephemeral only
+	ephemeralTrue := true
+	closedStatus := types.StatusClosed
+	ephemeralFilter := types.IssueFilter{
+		Status:    &closedStatus,
+		Ephemeral: &ephemeralTrue,
+	}
+
+	ephemeralIssues, err := store.SearchIssues(ctx, "", ephemeralFilter)
+	if err != nil {
+		t.Fatalf("SearchIssues failed: %v", err)
+	}
+	if len(ephemeralIssues) != 3 {
+		t.Errorf("Expected 3 ephemeral issues, got %d", len(ephemeralIssues))
+	}
+
+	// Filter for non-ephemeral only
+	ephemeralFalse := false
+	nonEphemeralFilter := types.IssueFilter{
+		Status:    &closedStatus,
+		Ephemeral: &ephemeralFalse,
+	}
+
+	permanentIssues, err := store.SearchIssues(ctx, "", nonEphemeralFilter)
+	if err != nil {
+		t.Fatalf("SearchIssues failed: %v", err)
+	}
+	if len(permanentIssues) != 2 {
+		t.Errorf("Expected 2 non-ephemeral issues, got %d", len(permanentIssues))
+	}
+}
+
+func TestSenderField(t *testing.T) {
+	store, cleanup := setupTestDB(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// Create issue with sender
+	msg := &types.Issue{
+		Title:     "Message",
+		Status:    types.StatusOpen,
+		Priority:  2,
+		IssueType: types.TypeMessage,
+		Sender:    "alice@example.com",
+		Assignee:  "bob@example.com",
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+	}
+
+	if err := store.CreateIssue(ctx, msg, "test"); err != nil {
+		t.Fatalf("Failed to create message: %v", err)
+	}
+
+	// Verify sender is preserved
+	saved, err := store.GetIssue(ctx, msg.ID)
+	if err != nil {
+		t.Fatalf("GetIssue failed: %v", err)
+	}
+	if saved.Sender != "alice@example.com" {
+		t.Errorf("Sender = %q, want %q", saved.Sender, "alice@example.com")
+	}
+}
+
+func TestMessageType(t *testing.T) {
+	store, cleanup := setupTestDB(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// Create a message type issue
+	msg := &types.Issue{
+		Title:     "Test Message",
+		Status:    types.StatusOpen,
+		Priority:  2,
+		IssueType: types.TypeMessage,
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+	}
+
+	if err := store.CreateIssue(ctx, msg, "test"); err != nil {
+		t.Fatalf("Failed to create message: %v", err)
+	}
+
+	// Verify type is preserved
+	saved, err := store.GetIssue(ctx, msg.ID)
+	if err != nil {
+		t.Fatalf("GetIssue failed: %v", err)
+	}
+	if saved.IssueType != types.TypeMessage {
+		t.Errorf("IssueType = %q, want %q", saved.IssueType, types.TypeMessage)
+	}
+
+	// Filter by message type
+	messageType := types.TypeMessage
+	filter := types.IssueFilter{
+		IssueType: &messageType,
+	}
+
+	messages, err := store.SearchIssues(ctx, "", filter)
+	if err != nil {
+		t.Fatalf("SearchIssues failed: %v", err)
+	}
+	if len(messages) != 1 {
+		t.Errorf("Expected 1 message, got %d", len(messages))
+	}
+}
--- a/internal/storage/sqlite/queries.go
+++ b/internal/storage/sqlite/queries.go
@@ -1552,6 +1552,15 @@ func (s *SQLiteStorage) SearchIssues(ctx context.Context, query string, filter t
 		whereClauses = append(whereClauses, fmt.Sprintf("id IN (%s)", strings.Join(placeholders, ", ")))
 	}

+	// Ephemeral filtering (bd-kwro.9)
+	if filter.Ephemeral != nil {
+		if *filter.Ephemeral {
+			whereClauses = append(whereClauses, "ephemeral = 1")
+		} else {
+			whereClauses = append(whereClauses, "(ephemeral = 0 OR ephemeral IS NULL)")
+		}
+	}
+
 	whereSQL := ""
 	if len(whereClauses) > 0 {
 		whereSQL = "WHERE " + strings.Join(whereClauses, " AND ")
--- a/internal/storage/sqlite/transaction.go
+++ b/internal/storage/sqlite/transaction.go
@@ -1068,6 +1068,15 @@ func (t *sqliteTxStorage) SearchIssues(ctx context.Context, query string, filter
 		whereClauses = append(whereClauses, fmt.Sprintf("id IN (%s)", strings.Join(placeholders, ", ")))
 	}

+	// Ephemeral filtering (bd-kwro.9)
+	if filter.Ephemeral != nil {
+		if *filter.Ephemeral {
+			whereClauses = append(whereClauses, "ephemeral = 1")
+		} else {
+			whereClauses = append(whereClauses, "(ephemeral = 0 OR ephemeral IS NULL)")
+		}
+	}
+
 	whereSQL := ""
 	if len(whereClauses) > 0 {
 		whereSQL = "WHERE " + strings.Join(whereClauses, " AND ")
--- a/internal/types/types.go
+++ b/internal/types/types.go
@@ -389,6 +389,9 @@ type IssueFilter struct {

 	// Tombstone filtering (bd-1bu)
 	IncludeTombstones bool // If false (default), exclude tombstones from results
+
+	// Ephemeral filtering (bd-kwro.9)
+	Ephemeral *bool // Filter by ephemeral flag (nil = any, true = only ephemeral, false = only non-ephemeral)
 }

 // SortPolicy determines how ready work is ordered