eval: add IR-style search benchmark + regression tests for 50d1a4d

New developer tool: `--search-eval [--queries path.toml] [--report path.json]`
runs a labeled query set through the same pipeline as the live TUI and
reports standard information-retrieval metrics:

- MRR (mean reciprocal rank) — primary "find the right one" metric
- P@1 — did we nail it first try?
- Recall@5 / @10 / @20 — does target appear in the top N?
- Failure list — queries below rank 20

Metrics are aggregated overall and per category, so a change that helps
one query shape but regresses another is visible instead of averaged out.

Privacy: real query text and session ids stay local. The committed
`eval/search-queries.example.toml` shows the schema with synthetic
placeholders. `eval/search-queries.toml` is gitignored. Per-run JSON
reports go to `eval/runs/<sha>.json` (also gitignored) for diffing.

Workflow:
  1. Capture baseline before any search change: `--search-eval --report ...`
  2. Make the change
  3. Re-run; diff JSON to see per-query rank deltas
  4. If MRR drops or a category regresses, fix or revert

Also adds regression tests in src/log_search.rs for the bug fixes from
the previous commit (per testing.instructions.md regression-test policy):

- read_tail_returns_whole_small_file — verifies the 2 MB threshold
- read_tail_big_file_captures_head_and_tail — covers the short-read fix
- search_uses_or_semantics_so_missing_term_does_not_kill_recall —
  covers the AND→OR default switch

129 unit tests pass; clippy clean on both crates.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: yeelam-gordon

eval/.gitignore

@@ -0,0 +1,6 @@
+# Private query set with real session ids and topic words.
+# Generated from eval/search-queries.example.toml — replaced with real data.
+search-queries.toml
+
+# Per-run JSON reports — large, noisy in diffs, regenerate on demand.
+runs/

eval/search-queries.example.toml

@@ -0,0 +1,42 @@
+# Search evaluation queries — EXAMPLE
+#
+# Copy this file to `eval/search-queries.toml` and replace with real queries
+# from your own session history. `eval/search-queries.toml` is gitignored
+# so private query text + real session ids stay local.
+#
+# Each [[query]] entry needs:
+#   text     = the query string you'd type in the TUI
+#   target   = the expected session id (UUID for Copilot, hash for Claude, etc.)
+#   category = bucket for per-category aggregation
+#   notes    = optional human note, not used in scoring
+#
+# Suggested categories — keep coverage balanced across these so the report
+# tells you where strengths and weaknesses live:
+#
+#   exact-title         query is verbatim (or near-verbatim) of the title
+#   partial-recall      most words right, some missing or out of order
+#   typo                misspelled or phonetic spelling
+#   semantic-only       target uses different vocabulary; semantic only
+#   keyword             tool/library name lookup (e.g. "ratatui mouse")
+#   person-name         queries with a teammate's name
+#   time-fuzzy          "last week", "this morning", etc.
+#
+# Run with:
+#   agent-session-tui --search-eval
+#   agent-session-tui --search-eval --report eval/runs/<sha>.json
+
+[[query]]
+text     = "rust tantivy index threshold"
+target   = "00000000-0000-0000-0000-000000000000"
+category = "keyword"
+notes    = "Replace target with a real session id from your own data."
+
+[[query]]
+text     = "memo summarizer prototype"
+target   = "00000000-0000-0000-0000-000000000001"
+category = "exact-title"
+
+[[query]]
+text     = "yaml provider config refactor"
+target   = "00000000-0000-0000-0000-000000000002"
+category = "partial-recall"

src/lib.rs

@@ -12,6 +12,7 @@ pub mod models;
 pub mod process_info;
 pub mod provider;
 pub mod search;
+pub mod search_eval;
 pub mod supervisor;
 pub mod testing;
 pub mod ui;

src/log_search.rs

@@ -518,3 +518,86 @@ fn escape_query(q: &str) -> String {
     }
     out
 }
+
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Write;
+
+    /// Regression for `WHOLE_FILE_THRESHOLD` (raised 512 KB → 2 MB in commit
+    /// 50d1a4d). A small file must be returned in full, not head/tail-split.
+    #[test]
+    fn read_tail_returns_whole_small_file() {
+        let tmp = tempfile::tempdir().unwrap();
+        let path = tmp.path().join("small.jsonl");
+        let body = "first line\nsecond line\n".repeat(100);
+        std::fs::write(&path, &body).unwrap();
+        let out = read_tail(&path).expect("read_tail should succeed");
+        assert_eq!(out, body, "small file must be returned verbatim");
+    }
+
+    /// Regression for the short-read bug fixed in 50d1a4d. Previously the
+    /// big-file branch used `f.read(&mut head_bytes)` which is permitted to
+    /// return fewer bytes than requested. Now it uses `take().read_to_end()`,
+    /// which loops until EOF or the cap. We verify head + tail contain the
+    /// expected markers placed at known offsets in a 3 MB file.
+    #[test]
+    fn read_tail_big_file_captures_head_and_tail() {
+        let tmp = tempfile::tempdir().unwrap();
+        let path = tmp.path().join("big.jsonl");
+        let mut f = std::fs::File::create(&path).unwrap();
+        // ~3 MB total: HEAD_TOKEN near start, filler, TAIL_TOKEN near end.
+        write!(f, "HEAD_TOKEN_AT_START\n").unwrap();
+        let filler = "x".repeat(3 * 1024 * 1024);
+        f.write_all(filler.as_bytes()).unwrap();
+        write!(f, "\nTAIL_TOKEN_AT_END\n").unwrap();
+        drop(f);
+        let out = read_tail(&path).expect("read_tail should succeed");
+        assert!(
+            out.contains("HEAD_TOKEN_AT_START"),
+            "head slice must include the start marker"
+        );
+        assert!(
+            out.contains("TAIL_TOKEN_AT_END"),
+            "tail slice must include the end marker"
+        );
+        // Sanity: head + tail strictly smaller than the whole file (skipped middle).
+        assert!(
+            (out.len() as u64) < (HEAD_BYTES + TAIL_BYTES + 1024 + 1024),
+            "big-file branch must NOT return the whole file"
+        );
+    }
+
+    /// Regression for the AND-default-killed-recall bug (50d1a4d). When the
+    /// query contains a term not present in any indexed document, the search
+    /// must still return matches on the other terms — not silently drop them.
+    #[test]
+    fn search_uses_or_semantics_so_missing_term_does_not_kill_recall() {
+        let tmp = tempfile::tempdir().unwrap();
+        let searcher = LogSearcher::open_or_create(tmp.path()).expect("open index");
+        // Hand-add one doc via the searcher's own writer mutex — opening a
+        // second writer on the same Index would deadlock on tantivy's lock.
+        {
+            let mut writer = searcher.writer.lock().unwrap();
+            let mut doc = TantivyDocument::default();
+            doc.add_text(searcher.session_id_field, "session-1");
+            doc.add_text(
+                searcher.content_field,
+                "alpha beta gamma delta epsilon zeta",
+            );
+            writer.add_document(doc).expect("add doc");
+            writer.commit().expect("commit");
+        }
+        searcher.reader.reload().expect("reload");
+
+        // Two of three terms exist; "xyzzy" does not appear anywhere.
+        // Strict AND would return 0; OR-default must still find session-1.
+        let hits = searcher.search("alpha beta xyzzy");
+        assert!(
+            hits.contains_key("session-1"),
+            "OR-default must surface docs matching ≥1 query term, got hits: {:?}",
+            hits
+        );
+    }
+}

src/main.rs

@@ -10,6 +10,7 @@ mod models;
 mod process_info;
 mod provider;
 mod search;
+mod search_eval;
 mod supervisor;
 mod ui;
 mod util;
@@ -278,6 +279,26 @@ async fn main() -> Result<()> {
     }
     // -----------------------------------------------------------------------
 
+    // --- search-eval IR benchmark -------------------------------------------
+    // `--search-eval [--queries path/to/queries.toml] [--report out.json]`
+    // runs a labeled query set through the same pipeline and reports
+    // MRR / P@1 / Recall@K aggregated overall and per category. Default
+    // queries file is `eval/search-queries.toml` (gitignored) with fallback
+    // to `eval/search-queries.example.toml`.
+    if args.iter().any(|a| a == "--search-eval") {
+        let queries: Option<String> = args
+            .iter()
+            .position(|a| a == "--queries")
+            .and_then(|i| args.get(i + 1).cloned());
+        let report: Option<String> = args
+            .iter()
+            .position(|a| a == "--report")
+            .and_then(|i| args.get(i + 1).cloned());
+        search_eval::run_search_eval(&registry, &config, queries.as_deref(), report.as_deref())?;
+        return Ok(());
+    }
+    // -----------------------------------------------------------------------
+
     let registry = Arc::new(registry);
 
     let (event_tx, event_rx) = mpsc::unbounded_channel();