From 8d1cb6b4edb64b5f672fcf22411573366fa6afbe Mon Sep 17 00:00:00 2001
From: Brian Ketelsen <bketelsen@gmail.com>
Date: Sun, 19 Apr 2026 00:33:18 -0400
Subject: [PATCH 1/2] feat: add --api-key flag for persistent external API
 access

Adds a static, non-expiring API key that enables external tools to access
the Mesa API without relying on ephemeral per-run agent keys.

Changes:
- New --api-key <key> CLI flag (also MESA_API_KEY_EXTERNAL env)
- Auth middleware checks the external key before DB lookup
- External key resolves to a synthetic 'external' agent in context
- New GET /api/v1/issues endpoint for listing all issues (with ?status= and ?limit= filters)
- 3 new tests covering external key auth (valid, wrong value, not set)

The external key is intended for orchestration tools, CI/CD pipelines,
and external agents that need to create issues, read status, or post
comments without being part of the internal agent roster.

Usage:
  mesa --api-key my-secret-key -t enterprise 3001
  curl -H 'Authorization: Bearer my-secret-key' http://localhost:3001/api/v1/issues
---
 cmd/mesa/main.go                   | 26 ++++++++++-
 internal/handlers/api.go           | 64 ++++++++++++++++++++++---
 internal/handlers/handlers_test.go | 75 ++++++++++++++++++++++++++++++
 3 files changed, 156 insertions(+), 9 deletions(-)

diff --git a/cmd/mesa/main.go b/cmd/mesa/main.go
index 8ba8711..3271a69 100644
--- a/cmd/mesa/main.go
+++ b/cmd/mesa/main.go
@@ -58,17 +58,19 @@ func main() {
 	verbosity := 0
 
 	dashboardAuth := false
+	externalAPIKey := ""
 
-	// CLI: mesa [-t <template>] [-m <model>] [-v|-vv|-vvv] [--auth] [doctor|wiki-search] [port]
+	// CLI: mesa [-t <template>] [-m <model>] [-v|-vv|-vvv] [--auth] [--api-key <key>] [doctor|wiki-search] [port]
 	args := os.Args[1:]
 	for i := 0; i < len(args); i++ {
 		arg := args[i]
 		if arg == "-h" || arg == "--help" {
-			fmt.Println("Usage: mesa [-t <template>] [-m <model>] [-v|-vv|-vvv] [--auth] [doctor|wiki-search] [port]")
+			fmt.Println("Usage: mesa [-t <template>] [-m <model>] [-v|-vv|-vvv] [--auth] [--api-key <key>] [doctor|wiki-search] [port]")
 			fmt.Println("  -t, --template  Team template: startup, dev-team, enterprise, saas, agency (default: startup)")
 			fmt.Println("  -m, --model     Default agent runner: claude, gemini, codex, opencode (default: claude)")
 			fmt.Println("  -v              Verbosity: -v info, -vv debug, -vvv debug+cmd")
 			fmt.Println("  --auth          Enable dashboard authentication with auto-generated token")
+			fmt.Println("  --api-key       Static API key for external access (non-expiring, not agent-scoped)")
 			fmt.Println("  doctor          Check that required CLI binaries are available")
 			fmt.Println("  wiki-search     Search wiki pages (usage: wiki-search <query>)")
 			fmt.Println("  port            HTTP port (default: 3001, or PORT env)")
@@ -104,11 +106,23 @@ func main() {
 			modelProvided = true
 		} else if arg == "--auth" {
 			dashboardAuth = true
+		} else if arg == "--api-key" {
+			if i+1 >= len(args) {
+				fmt.Fprintln(os.Stderr, "error: --api-key requires a value")
+				os.Exit(1)
+			}
+			i++
+			externalAPIKey = args[i]
 		} else {
 			port = arg
 		}
 	}
 
+	// Also allow env override for external API key
+	if k := os.Getenv("MESA_API_KEY_EXTERNAL"); k != "" {
+		externalAPIKey = k
+	}
+
 	switch {
 	case verbosity >= 3:
 		logLevel.Set(slog.Level(-8)) // trace: per-line agent output
@@ -250,6 +264,9 @@ func main() {
 
 	// Handlers
 	api := handlers.NewAPI(database, sse, tmpl, wake, tg, dc)
+	if externalAPIKey != "" {
+		api.SetExternalKey(externalAPIKey)
+	}
 	ui := handlers.NewUI(database, sse, tmpl, wake, sched)
 	// Routes
 	mux := http.NewServeMux()
@@ -320,6 +337,7 @@ func main() {
 
 	// API routes (auth-wrapped)
 	mux.HandleFunc("GET /api/v1/inbox", api.Auth(api.Inbox))
+	mux.HandleFunc("GET /api/v1/issues", api.Auth(api.ListIssues))
 	mux.HandleFunc("GET /api/v1/issues/{key}", api.Auth(api.GetIssue))
 	mux.HandleFunc("POST /api/v1/issues/{key}/checkout", api.Auth(api.CheckoutIssue))
 	mux.HandleFunc("PATCH /api/v1/issues/{key}", api.Auth(api.UpdateIssue))
@@ -396,6 +414,10 @@ func main() {
 			fmt.Fprintf(os.Stderr, "\n  Dashboard auth enabled\n")
 			fmt.Fprintf(os.Stderr, "  Open: http://localhost:%s/dashboard?token=%s\n\n", port, dashToken)
 		}
+		if externalAPIKey != "" {
+			fmt.Fprintf(os.Stderr, "  External API key enabled\n")
+			fmt.Fprintf(os.Stderr, "  Usage: curl -H 'Authorization: Bearer %s' http://localhost:%s/api/v1/issues\n\n", externalAPIKey, port)
+		}
 		slog.Info("mesa running", "url", "http://localhost:"+port)
 		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
 			slog.Error("http server error", "error", err)
diff --git a/internal/handlers/api.go b/internal/handlers/api.go
index 91b881e..67e8460 100644
--- a/internal/handlers/api.go
+++ b/internal/handlers/api.go
@@ -33,19 +33,43 @@ type DiscordNotifier interface {
 }
 
 type API struct {
-	db       *db.DB
-	sse      *SSEHub
-	tmpl     *template.Template
-	wake     func(agent *models.Agent, issue *models.Issue)
-	telegram TelegramNotifier
-	discord  DiscordNotifier
+	db              *db.DB
+	sse             *SSEHub
+	tmpl            *template.Template
+	wake            func(agent *models.Agent, issue *models.Issue)
+	telegram        TelegramNotifier
+	discord         DiscordNotifier
+	externalKeyHash string // SHA-256 hex of the --api-key value; empty = disabled
 }
 
 func NewAPI(database *db.DB, sse *SSEHub, tmpl *template.Template, wake func(*models.Agent, *models.Issue), tg TelegramNotifier, dc DiscordNotifier) *API {
 	return &API{db: database, sse: sse, tmpl: tmpl, wake: wake, telegram: tg, discord: dc}
 }
 
-// Auth middleware extracts agent from API key
+// SetExternalKey configures a static API key for external access.
+// The key is hashed and compared against Bearer tokens in the Auth middleware.
+func (a *API) SetExternalKey(rawKey string) {
+	if rawKey == "" {
+		return
+	}
+	hash := sha256.Sum256([]byte(rawKey))
+	a.externalKeyHash = hex.EncodeToString(hash[:])
+}
+
+// externalAgent returns a synthetic agent used for external API key access.
+// It has a fixed ID and name so that endpoints requiring agent context work correctly.
+func externalAgent() *models.Agent {
+	return &models.Agent{
+		ID:            "external",
+		Name:          "External",
+		Slug:          "external",
+		ArchetypeSlug: "external",
+		Active:        true,
+	}
+}
+
+// Auth middleware extracts agent from API key.
+// If an external API key is configured (via --api-key), it is checked first.
 func (a *API) Auth(next http.HandlerFunc) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		token := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")
@@ -55,6 +79,14 @@ func (a *API) Auth(next http.HandlerFunc) http.HandlerFunc {
 		}
 		hash := sha256.Sum256([]byte(token))
 		keyHash := hex.EncodeToString(hash[:])
+
+		// Check external key first (non-expiring, not agent-scoped)
+		if a.externalKeyHash != "" && keyHash == a.externalKeyHash {
+			r = r.WithContext(withAgent(r.Context(), externalAgent()))
+			next(w, r)
+			return
+		}
+
 		agent, err := a.db.GetAgentByAPIKey(keyHash)
 		if err != nil {
 			http.Error(w, `{"error":"invalid api key"}`, http.StatusUnauthorized)
@@ -75,6 +107,24 @@ func (a *API) Inbox(w http.ResponseWriter, r *http.Request) {
 	jsonOK(w, issues)
 }
 
+// ListIssues returns all issues, optionally filtered by ?status= and ?limit=.
+// Available to any authenticated caller (including external API keys).
+func (a *API) ListIssues(w http.ResponseWriter, r *http.Request) {
+	status := r.URL.Query().Get("status")
+	limit := 100
+	if l := r.URL.Query().Get("limit"); l != "" {
+		if n, err := strconv.Atoi(l); err == nil && n > 0 {
+			limit = n
+		}
+	}
+	issues, err := a.db.ListIssues(status, limit)
+	if err != nil {
+		jsonError(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	jsonOK(w, issues)
+}
+
 func (a *API) GetIssue(w http.ResponseWriter, r *http.Request) {
 	key := r.PathValue("key")
 	issue, err := a.db.GetIssue(key)
diff --git a/internal/handlers/handlers_test.go b/internal/handlers/handlers_test.go
index 3409b9c..2846246 100644
--- a/internal/handlers/handlers_test.go
+++ b/internal/handlers/handlers_test.go
@@ -243,6 +243,81 @@ func TestAuthValidKey(t *testing.T) {
 	}
 }
 
+func TestAuthExternalKey(t *testing.T) {
+	d := testDB(t)
+	hub := NewSSEHub()
+	defer hub.Close()
+	api := NewAPI(d, hub, nil, nil, &stubTelegram{}, nil)
+	api.SetExternalKey("my-external-key")
+
+	var gotAgent *models.Agent
+	handler := api.Auth(func(w http.ResponseWriter, r *http.Request) {
+		gotAgent = agentFromContext(r.Context())
+		w.WriteHeader(http.StatusOK)
+	})
+
+	req := httptest.NewRequest("GET", "/", nil)
+	req.Header.Set("Authorization", "Bearer my-external-key")
+	w := httptest.NewRecorder()
+	handler(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("status = %d, want 200", w.Code)
+	}
+	if gotAgent == nil {
+		t.Fatal("expected agent in context")
+	}
+	if gotAgent.ID != "external" {
+		t.Errorf("agent ID = %q, want external", gotAgent.ID)
+	}
+	if gotAgent.Slug != "external" {
+		t.Errorf("agent slug = %q, want external", gotAgent.Slug)
+	}
+}
+
+func TestAuthExternalKeyWrongValue(t *testing.T) {
+	d := testDB(t)
+	hub := NewSSEHub()
+	defer hub.Close()
+	api := NewAPI(d, hub, nil, nil, &stubTelegram{}, nil)
+	api.SetExternalKey("my-external-key")
+
+	handler := api.Auth(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+
+	req := httptest.NewRequest("GET", "/", nil)
+	req.Header.Set("Authorization", "Bearer wrong-key")
+	w := httptest.NewRecorder()
+	handler(w, req)
+
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401", w.Code)
+	}
+}
+
+func TestAuthExternalKeyNotSet(t *testing.T) {
+	d := testDB(t)
+	hub := NewSSEHub()
+	defer hub.Close()
+	api := NewAPI(d, hub, nil, nil, &stubTelegram{}, nil)
+	// No SetExternalKey called
+
+	handler := api.Auth(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+
+	req := httptest.NewRequest("GET", "/", nil)
+	req.Header.Set("Authorization", "Bearer some-key")
+	w := httptest.NewRecorder()
+	handler(w, req)
+
+	// Should fail because no external key is set and "some-key" isn't a valid DB key
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401", w.Code)
+	}
+}
+
 // --- SSE ServeHTTP ---
 
 func TestSSEServeHTTP(t *testing.T) {

From 54a69c8bd8b94247b0ebe393071bbb8f98400287 Mon Sep 17 00:00:00 2001
From: Brian Ketelsen <bketelsen@gmail.com>
Date: Mon, 20 Apr 2026 14:23:56 -0400
Subject: [PATCH 2/2] feat(SO-19): add fuzzy title similarity endpoint POST
 /api/v1/issues/similarity

Implements duplicate-detection endpoint per SO-19 acceptance criteria.
- New POST /api/v1/issues/similarity accepts {title} and returns
  [{key, title, similarity_score}] for active (non-terminal) issues
  above 0.70 normalized Levenshtein threshold, sorted desc by score.
- ListActiveIssueTitles DB method scans todo/in_progress/in_review/blocked issues.
- Unit tests cover exact match, near-match, below-threshold, empty DB,
  terminal-issue filtering, sorted order, and missing-title 400.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 cmd/mesa/main.go                     |   1 +
 internal/db/queries.go               |  28 +++
 internal/handlers/similarity.go      | 132 ++++++++++++++
 internal/handlers/similarity_test.go | 246 +++++++++++++++++++++++++++
 4 files changed, 407 insertions(+)
 create mode 100644 internal/handlers/similarity.go
 create mode 100644 internal/handlers/similarity_test.go

diff --git a/cmd/mesa/main.go b/cmd/mesa/main.go
index 3271a69..6668ff9 100644
--- a/cmd/mesa/main.go
+++ b/cmd/mesa/main.go
@@ -343,6 +343,7 @@ func main() {
 	mux.HandleFunc("PATCH /api/v1/issues/{key}", api.Auth(api.UpdateIssue))
 	mux.HandleFunc("DELETE /api/v1/issues/{key}", api.Auth(api.DeleteIssue))
 	mux.HandleFunc("POST /api/v1/issues/{key}/comments", api.Auth(api.CreateComment))
+	mux.HandleFunc("POST /api/v1/issues/similarity", api.Auth(api.SimilarIssues))
 	mux.HandleFunc("POST /api/v1/issues", api.Auth(api.CreateIssue))
 	mux.HandleFunc("GET /api/v1/agents", api.Auth(api.ListAgents))
 	mux.HandleFunc("GET /api/v1/agents/me", api.Auth(api.AgentMe))
diff --git a/internal/db/queries.go b/internal/db/queries.go
index 57a9ba8..63c71b5 100644
--- a/internal/db/queries.go
+++ b/internal/db/queries.go
@@ -380,6 +380,34 @@ func (d *DB) CountIssues() (int, int, error) {
 	return total, open, err
 }
 
+// IssueTitleRow is a lightweight projection used for similarity scanning.
+type IssueTitleRow struct {
+	Key   string
+	Title string
+}
+
+// ListActiveIssueTitles returns key+title for all non-terminal issues
+// (todo, in_progress, in_review, blocked, board_review).
+func (d *DB) ListActiveIssueTitles() ([]IssueTitleRow, error) {
+	rows, err := d.Query(`SELECT key, title FROM issues
+		WHERE status NOT IN ('done','cancelled','wont_do')
+		ORDER BY created_at DESC`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var out []IssueTitleRow
+	for rows.Next() {
+		var r IssueTitleRow
+		if err := rows.Scan(&r.Key, &r.Title); err != nil {
+			return nil, err
+		}
+		out = append(out, r)
+	}
+	return out, rows.Err()
+}
+
 func (d *DB) GetChildIssues(parentKey string) ([]models.Issue, error) {
 	rows, err := d.Query(fmt.Sprintf(`SELECT %s
 		FROM issues i LEFT JOIN agents a ON i.assignee_agent_id = a.id
diff --git a/internal/handlers/similarity.go b/internal/handlers/similarity.go
new file mode 100644
index 0000000..536cdec
--- /dev/null
+++ b/internal/handlers/similarity.go
@@ -0,0 +1,132 @@
+package handlers
+
+import (
+	"encoding/json"
+	"math"
+	"net/http"
+	"strings"
+)
+
+const (
+	// SimilarityThreshold is the minimum normalized Levenshtein similarity (0–1)
+	// required to include an issue in similarity results.
+	SimilarityThreshold = 0.70
+)
+
+// SimilarIssueResult is a single result returned by the similarity endpoint.
+type SimilarIssueResult struct {
+	Key             string  `json:"key"`
+	Title           string  `json:"title"`
+	SimilarityScore float64 `json:"similarity_score"`
+}
+
+// SimilarIssues handles POST /api/v1/issues/similarity.
+// Body: {"title": "proposed title"}
+// Returns a JSON array of {key, title, similarity_score} for open/in-progress
+// issues whose title similarity exceeds SimilarityThreshold, sorted desc.
+func (a *API) SimilarIssues(w http.ResponseWriter, r *http.Request) {
+	var body struct {
+		Title string `json:"title"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil || strings.TrimSpace(body.Title) == "" {
+		jsonError(w, "title required", http.StatusBadRequest)
+		return
+	}
+
+	candidates, err := a.db.ListActiveIssueTitles()
+	if err != nil {
+		jsonError(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	var results []SimilarIssueResult
+	for _, c := range candidates {
+		score := titleSimilarity(body.Title, c.Title)
+		if score >= SimilarityThreshold {
+			results = append(results, SimilarIssueResult{
+				Key:             c.Key,
+				Title:           c.Title,
+				SimilarityScore: math.Round(score*1000) / 1000,
+			})
+		}
+	}
+
+	// Sort by similarity_score descending (insertion sort is fine for small slices).
+	for i := 1; i < len(results); i++ {
+		for j := i; j > 0 && results[j].SimilarityScore > results[j-1].SimilarityScore; j-- {
+			results[j], results[j-1] = results[j-1], results[j]
+		}
+	}
+
+	if results == nil {
+		results = []SimilarIssueResult{}
+	}
+	jsonOK(w, results)
+}
+
+// titleSimilarity returns the normalized Levenshtein similarity between two strings,
+// case-folded. Result is in [0.0, 1.0]: 1.0 = identical, 0.0 = completely different.
+func titleSimilarity(a, b string) float64 {
+	a = strings.ToLower(strings.TrimSpace(a))
+	b = strings.ToLower(strings.TrimSpace(b))
+	if a == b {
+		return 1.0
+	}
+	maxLen := len([]rune(a))
+	if lb := len([]rune(b)); lb > maxLen {
+		maxLen = lb
+	}
+	if maxLen == 0 {
+		return 1.0
+	}
+	d := levenshtein(a, b)
+	return 1.0 - float64(d)/float64(maxLen)
+}
+
+// levenshtein computes the edit distance between two strings.
+func levenshtein(a, b string) int {
+	ra, rb := []rune(a), []rune(b)
+	la, lb := len(ra), len(rb)
+
+	if la == 0 {
+		return lb
+	}
+	if lb == 0 {
+		return la
+	}
+
+	prev := make([]int, lb+1)
+	curr := make([]int, lb+1)
+	for j := 0; j <= lb; j++ {
+		prev[j] = j
+	}
+
+	for i := 1; i <= la; i++ {
+		curr[0] = i
+		for j := 1; j <= lb; j++ {
+			cost := 1
+			if ra[i-1] == rb[j-1] {
+				cost = 0
+			}
+			del := prev[j] + 1
+			ins := curr[j-1] + 1
+			sub := prev[j-1] + cost
+			curr[j] = min3(del, ins, sub)
+		}
+		prev, curr = curr, prev
+	}
+	return prev[lb]
+}
+
+func min3(a, b, c int) int {
+	if a < b {
+		if a < c {
+			return a
+		}
+		return c
+	}
+	if b < c {
+		return b
+	}
+	return c
+}
diff --git a/internal/handlers/similarity_test.go b/internal/handlers/similarity_test.go
new file mode 100644
index 0000000..c2ef7c1
--- /dev/null
+++ b/internal/handlers/similarity_test.go
@@ -0,0 +1,246 @@
+package handlers
+
+import (
+	"bytes"
+	"encoding/json"
+	"math"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/msoedov/mesa/internal/models"
+	"github.com/msoedov/mesa/internal/templates"
+)
+
+// --- unit tests for titleSimilarity / levenshtein ---
+
+func TestLevenshteinExact(t *testing.T) {
+	if d := levenshtein("hello", "hello"); d != 0 {
+		t.Fatalf("want 0, got %d", d)
+	}
+}
+
+func TestLevenshteinEmpty(t *testing.T) {
+	if d := levenshtein("", "abc"); d != 3 {
+		t.Fatalf("want 3, got %d", d)
+	}
+	if d := levenshtein("abc", ""); d != 3 {
+		t.Fatalf("want 3, got %d", d)
+	}
+}
+
+func TestLevenshteinSingleEdit(t *testing.T) {
+	if d := levenshtein("cat", "bat"); d != 1 {
+		t.Fatalf("want 1, got %d", d)
+	}
+}
+
+func TestTitleSimilarityExact(t *testing.T) {
+	s := titleSimilarity("Add login page", "Add login page")
+	if s != 1.0 {
+		t.Fatalf("exact match: want 1.0, got %v", s)
+	}
+}
+
+func TestTitleSimilarityNearMatch(t *testing.T) {
+	// One word different — should be well above 0.70 threshold
+	s := titleSimilarity("Add user login page", "Add user login form")
+	if s < SimilarityThreshold {
+		t.Fatalf("near-match: want >= %.2f, got %.4f", SimilarityThreshold, s)
+	}
+}
+
+func TestTitleSimilarityBelowThreshold(t *testing.T) {
+	s := titleSimilarity("Add login page", "Fix database migration issue")
+	if s >= SimilarityThreshold {
+		t.Fatalf("unrelated: want < %.2f, got %.4f", SimilarityThreshold, s)
+	}
+}
+
+func TestTitleSimilarityEmptyBoth(t *testing.T) {
+	s := titleSimilarity("", "")
+	if s != 1.0 {
+		t.Fatalf("both empty: want 1.0, got %v", s)
+	}
+}
+
+func TestTitleSimilarityCaseInsensitive(t *testing.T) {
+	a := titleSimilarity("Add Login Page", "add login page")
+	if a != 1.0 {
+		t.Fatalf("case fold: want 1.0, got %v", a)
+	}
+}
+
+// --- HTTP handler tests ---
+
+func makeAPIWithIssues(t *testing.T, issues []models.Issue) *API {
+	t.Helper()
+	d := testDB(t)
+	for i := range issues {
+		if err := d.CreateIssue(&issues[i]); err != nil {
+			t.Fatalf("seed issue: %v", err)
+		}
+	}
+	hub := NewSSEHub()
+	t.Cleanup(hub.Close)
+	tmpl, _ := templates.Parse()
+	return NewAPI(d, hub, tmpl, nil, nil, nil)
+}
+
+func TestSimilarIssues_ExactMatch(t *testing.T) {
+	api := makeAPIWithIssues(t, []models.Issue{
+		{Key: "SO-1", Title: "Add login page", Status: models.StatusTodo, Type: "task"},
+		{Key: "SO-2", Title: "Fix database bug", Status: models.StatusInProgress, Type: "task"},
+	})
+
+	body, _ := json.Marshal(map[string]string{"title": "Add login page"})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/issues/similarity", bytes.NewReader(body))
+	req = req.WithContext(withAgent(req.Context(), &models.Agent{ID: "a1", Slug: "bot", ArchetypeSlug: "bot"}))
+	w := httptest.NewRecorder()
+
+	api.SimilarIssues(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status %d, body: %s", w.Code, w.Body)
+	}
+	var results []SimilarIssueResult
+	if err := json.Unmarshal(w.Body.Bytes(), &results); err != nil {
+		t.Fatal(err)
+	}
+	if len(results) == 0 {
+		t.Fatal("expected at least one result for exact match")
+	}
+	if results[0].Key != "SO-1" {
+		t.Errorf("top result key = %q, want SO-1", results[0].Key)
+	}
+	if math.Abs(results[0].SimilarityScore-1.0) > 0.001 {
+		t.Errorf("exact match score = %v, want ~1.0", results[0].SimilarityScore)
+	}
+}
+
+func TestSimilarIssues_NearMatch(t *testing.T) {
+	api := makeAPIWithIssues(t, []models.Issue{
+		{Key: "SO-1", Title: "Add user login page", Status: models.StatusTodo, Type: "task"},
+		{Key: "SO-2", Title: "Fix unrelated database migration", Status: models.StatusTodo, Type: "task"},
+	})
+
+	body, _ := json.Marshal(map[string]string{"title": "Add user login form"})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/issues/similarity", bytes.NewReader(body))
+	req = req.WithContext(withAgent(req.Context(), &models.Agent{ID: "a1", Slug: "bot", ArchetypeSlug: "bot"}))
+	w := httptest.NewRecorder()
+
+	api.SimilarIssues(w, req)
+
+	var results []SimilarIssueResult
+	json.Unmarshal(w.Body.Bytes(), &results)
+
+	found := false
+	for _, r := range results {
+		if r.Key == "SO-1" {
+			found = true
+			if r.SimilarityScore < SimilarityThreshold {
+				t.Errorf("near-match score %.4f below threshold %.2f", r.SimilarityScore, SimilarityThreshold)
+			}
+		}
+	}
+	if !found {
+		t.Errorf("near-match SO-1 not returned; results: %+v", results)
+	}
+}
+
+func TestSimilarIssues_BelowThreshold(t *testing.T) {
+	api := makeAPIWithIssues(t, []models.Issue{
+		{Key: "SO-1", Title: "Fix database migration bug", Status: models.StatusTodo, Type: "task"},
+	})
+
+	body, _ := json.Marshal(map[string]string{"title": "Implement OAuth2 provider integration"})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/issues/similarity", bytes.NewReader(body))
+	req = req.WithContext(withAgent(req.Context(), &models.Agent{ID: "a1", Slug: "bot", ArchetypeSlug: "bot"}))
+	w := httptest.NewRecorder()
+
+	api.SimilarIssues(w, req)
+
+	var results []SimilarIssueResult
+	json.Unmarshal(w.Body.Bytes(), &results)
+	if len(results) != 0 {
+		t.Errorf("expected empty results for unrelated title, got %+v", results)
+	}
+}
+
+func TestSimilarIssues_EmptyDatabase(t *testing.T) {
+	api := makeAPIWithIssues(t, nil)
+
+	body, _ := json.Marshal(map[string]string{"title": "Add login page"})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/issues/similarity", bytes.NewReader(body))
+	req = req.WithContext(withAgent(req.Context(), &models.Agent{ID: "a1", Slug: "bot", ArchetypeSlug: "bot"}))
+	w := httptest.NewRecorder()
+
+	api.SimilarIssues(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status %d", w.Code)
+	}
+	var results []SimilarIssueResult
+	json.Unmarshal(w.Body.Bytes(), &results)
+	if len(results) != 0 {
+		t.Errorf("expected empty results, got %+v", results)
+	}
+}
+
+func TestSimilarIssues_SkipsTerminalIssues(t *testing.T) {
+	api := makeAPIWithIssues(t, []models.Issue{
+		{Key: "SO-1", Title: "Add login page", Status: models.StatusDone, Type: "task"},
+		{Key: "SO-2", Title: "Add login page", Status: models.StatusCancelled, Type: "task"},
+	})
+
+	body, _ := json.Marshal(map[string]string{"title": "Add login page"})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/issues/similarity", bytes.NewReader(body))
+	req = req.WithContext(withAgent(req.Context(), &models.Agent{ID: "a1", Slug: "bot", ArchetypeSlug: "bot"}))
+	w := httptest.NewRecorder()
+
+	api.SimilarIssues(w, req)
+
+	var results []SimilarIssueResult
+	json.Unmarshal(w.Body.Bytes(), &results)
+	if len(results) != 0 {
+		t.Errorf("done/cancelled issues should not appear in similarity results, got %+v", results)
+	}
+}
+
+func TestSimilarIssues_SortedByScore(t *testing.T) {
+	api := makeAPIWithIssues(t, []models.Issue{
+		{Key: "SO-1", Title: "Add user login form", Status: models.StatusTodo, Type: "task"},
+		{Key: "SO-2", Title: "Add login page", Status: models.StatusTodo, Type: "task"},
+	})
+
+	body, _ := json.Marshal(map[string]string{"title": "Add user login page"})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/issues/similarity", bytes.NewReader(body))
+	req = req.WithContext(withAgent(req.Context(), &models.Agent{ID: "a1", Slug: "bot", ArchetypeSlug: "bot"}))
+	w := httptest.NewRecorder()
+
+	api.SimilarIssues(w, req)
+
+	var results []SimilarIssueResult
+	json.Unmarshal(w.Body.Bytes(), &results)
+
+	for i := 1; i < len(results); i++ {
+		if results[i].SimilarityScore > results[i-1].SimilarityScore {
+			t.Errorf("results not sorted desc at index %d: %v > %v", i, results[i].SimilarityScore, results[i-1].SimilarityScore)
+		}
+	}
+}
+
+func TestSimilarIssues_MissingTitle(t *testing.T) {
+	api := makeAPIWithIssues(t, nil)
+
+	body := []byte(`{}`)
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/issues/similarity", bytes.NewReader(body))
+	req = req.WithContext(withAgent(req.Context(), &models.Agent{ID: "a1", Slug: "bot", ArchetypeSlug: "bot"}))
+	w := httptest.NewRecorder()
+
+	api.SimilarIssues(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("want 400, got %d", w.Code)
+	}
+}