[Bugfix #32] refactor: single-pass glob and cap candidates to 5 in _find_thought_path

- Merge two glob() calls into one traversal: collect exact match and prefix
  matches in a single loop; return on exact hit without scanning the rest
- Cap AmbiguousThoughtID candidates at 5 entries; add total_matches field so
  callers can report "showing 5 of N matches" to the agent
- Update test assertion to verify total_matches == 2

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: timeleft--

src/fava_trails/trail.py

@@ -44,11 +44,14 @@
 class AmbiguousThoughtID(Exception):
     """Raised when a shortened thought ID prefix matches more than one thought file."""
 
-    def __init__(self, prefix: str, candidates: list[dict]) -> None:
+    def __init__(self, prefix: str, candidates: list[dict], total_matches: int) -> None:
         self.prefix = prefix
-        self.candidates = candidates  # list of {thought_id, namespace, source_type, created_at, content_preview}
+        self.candidates = candidates  # up to 5 entries: {thought_id, namespace, source_type, created_at, content_preview}
+        self.total_matches = total_matches
+        shown = len(candidates)
+        detail = f"showing {shown} of {total_matches}" if total_matches > shown else f"{total_matches} matches"
         super().__init__(
-            f"Prefix '{prefix}' is ambiguous — matches {len(candidates)} thoughts. "
+            f"Prefix '{prefix}' is ambiguous — {detail}. "
             "Provide a longer prefix or the full ULID."
         )
 
@@ -117,42 +120,41 @@ def _thought_path(self, thought_id: str, namespace: str = DEFAULT_NAMESPACE) ->
     def _find_thought_path(self, thought_id: str) -> Path | None:
         """Find a thought file by ULID across all namespaces.
 
-        Supports prefix matching: if thought_id is shorter than a full ULID (26 chars),
-        all thought files whose stem starts with the prefix are collected.
-        - Exact match (full ULID): returns immediately.
+        Single-pass traversal: collects exact match and prefix matches together.
+        - Exact match (full ULID): returns immediately on first hit.
         - Unique prefix match: returns the single matching path.
-        - Ambiguous prefix match: raises AmbiguousThoughtID with candidate info.
+        - Ambiguous prefix match: raises AmbiguousThoughtID (capped at 5 candidates,
+          total_matches count included so callers can report "showing 5 of N").
         - No match: returns None.
         """
-        # Fast path: exact match
+        is_prefix = len(thought_id) < 26  # ULIDs are 26 chars
+        prefix_matches: list[Path] = []
+
         for p in self.trail_path.glob("thoughts/**/*.md"):
             if p.stem == thought_id:
-                return p
-
-        # Prefix match (only attempted when no exact match found)
-        if len(thought_id) < 26:  # ULIDs are 26 chars
-            matches = [
-                p for p in self.trail_path.glob("thoughts/**/*.md")
-                if p.stem.startswith(thought_id)
-            ]
-            if len(matches) == 1:
-                return matches[0]
-            if len(matches) > 1:
-                candidates = []
-                for p in matches:
-                    try:
-                        record = ThoughtRecord.from_markdown(p.read_text())
-                        fm = record.frontmatter
-                        candidates.append({
-                            "thought_id": fm.thought_id,
-                            "namespace": self._get_namespace_from_path(p),
-                            "source_type": fm.source_type.value,
-                            "created_at": fm.created_at.isoformat() if fm.created_at else None,
-                            "content_preview": record.content[:100] + ("..." if len(record.content) > 100 else ""),
-                        })
-                    except Exception:
-                        candidates.append({"thought_id": p.stem, "namespace": self._get_namespace_from_path(p)})
-                raise AmbiguousThoughtID(thought_id, candidates)
+                return p  # exact match — fast path
+            if is_prefix and p.stem.startswith(thought_id):
+                prefix_matches.append(p)
+
+        if len(prefix_matches) == 1:
+            return prefix_matches[0]
+        if len(prefix_matches) > 1:
+            total = len(prefix_matches)
+            candidates = []
+            for p in prefix_matches[:5]:
+                try:
+                    record = ThoughtRecord.from_markdown(p.read_text())
+                    fm = record.frontmatter
+                    candidates.append({
+                        "thought_id": fm.thought_id,
+                        "namespace": self._get_namespace_from_path(p),
+                        "source_type": fm.source_type.value,
+                        "created_at": fm.created_at.isoformat() if fm.created_at else None,
+                        "content_preview": record.content[:100] + ("..." if len(record.content) > 100 else ""),
+                    })
+                except Exception:
+                    candidates.append({"thought_id": p.stem, "namespace": self._get_namespace_from_path(p)})
+            raise AmbiguousThoughtID(thought_id, candidates, total_matches=total)
 
         return None
 

tests/test_tools.py

@@ -1066,6 +1066,7 @@ async def test_prefix_match_ambiguous_raises(trail_manager):
 
     err = exc_info.value
     assert err.prefix == shared_prefix
+    assert err.total_matches == 2
     assert len(err.candidates) == 2
     candidate_ids = {c["thought_id"] for c in err.candidates}
     assert r1.thought_id in candidate_ids