fix(mcp): dedupe reasoning mirrors, rename harness→mode, improve errors & docs (#199)

Author: eric-tramel

apps/moraine/src/main.rs

@@ -2799,6 +2799,38 @@ async fn main() -> Result<ExitCode> {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::ffi::OsString;
+    use std::sync::{Mutex, MutexGuard};
+
+    static ENV_VAR_LOCK: Mutex<()> = Mutex::new(());
+
+    struct EnvVarGuard {
+        key: &'static str,
+        original: Option<OsString>,
+    }
+
+    impl EnvVarGuard {
+        fn capture(key: &'static str) -> Self {
+            Self {
+                key,
+                original: std::env::var_os(key),
+            }
+        }
+    }
+
+    impl Drop for EnvVarGuard {
+        fn drop(&mut self) {
+            if let Some(value) = &self.original {
+                std::env::set_var(self.key, value);
+            } else {
+                std::env::remove_var(self.key);
+            }
+        }
+    }
+
+    fn lock_env_vars() -> MutexGuard<'static, ()> {
+        ENV_VAR_LOCK.lock().expect("env-var lock poisoned")
+    }
 
     fn temp_dir(name: &str) -> PathBuf {
         let stamp = SystemTime::now()
@@ -3126,6 +3158,10 @@ mod tests {
 
     #[test]
     fn resolve_service_binary_prefers_env_then_config() {
+        let _env_lock = lock_env_vars();
+        let _service_bin_dir_guard = EnvVarGuard::capture("MORAINE_SERVICE_BIN_DIR");
+        let _source_tree_mode_guard = EnvVarGuard::capture("MORAINE_SOURCE_TREE_MODE");
+
         let root = temp_dir("resolver");
         let env_dir = root.join("env");
         let cfg_dir = root.join("cfg");
@@ -3156,6 +3192,10 @@ mod tests {
 
     #[test]
     fn resolve_service_binary_reports_missing_without_path_fallback() {
+        let _env_lock = lock_env_vars();
+        let _service_bin_dir_guard = EnvVarGuard::capture("MORAINE_SERVICE_BIN_DIR");
+        let _source_tree_mode_guard = EnvVarGuard::capture("MORAINE_SOURCE_TREE_MODE");
+
         let root = temp_dir("resolver-path");
         let mut cfg = AppConfig::default();
         cfg.runtime.service_bin_dir = root.join("missing").to_string_lossy().to_string();
@@ -3177,6 +3217,10 @@ mod tests {
 
     #[test]
     fn require_service_binary_includes_remediation() {
+        let _env_lock = lock_env_vars();
+        let _service_bin_dir_guard = EnvVarGuard::capture("MORAINE_SERVICE_BIN_DIR");
+        let _source_tree_mode_guard = EnvVarGuard::capture("MORAINE_SOURCE_TREE_MODE");
+
         let root = temp_dir("resolver-remediation");
         let mut cfg = AppConfig::default();
         cfg.runtime.service_bin_dir = root.join("missing").to_string_lossy().to_string();

crates/moraine-conversations/src/clickhouse_repo.rs

@@ -1600,13 +1600,25 @@ FORMAT JSONEachRow",
                 || row.payload_type == "event_msg")
     }
 
+    fn is_reasoning_search_row(row: &SearchRow) -> bool {
+        row.event_class == "reasoning"
+    }
+
+    fn is_event_msg_reasoning_search_row(row: &SearchRow) -> bool {
+        row.event_class == "event_msg" && row.payload_type == "agent_reasoning"
+    }
+
     fn compact_preview_for_dedup(text: &str) -> String {
         text.split_whitespace().collect::<Vec<_>>().join(" ")
     }
 
     fn search_rows_are_mirrors(a: &SearchRow, b: &SearchRow) -> bool {
-        let same_kind_pair = (Self::is_message_search_row(a) && Self::is_event_msg_search_row(b))
+        let is_message_pair = (Self::is_message_search_row(a) && Self::is_event_msg_search_row(b))
             || (Self::is_event_msg_search_row(a) && Self::is_message_search_row(b));
+        let is_reasoning_pair = (Self::is_reasoning_search_row(a)
+            && Self::is_event_msg_reasoning_search_row(b))
+            || (Self::is_event_msg_reasoning_search_row(a) && Self::is_reasoning_search_row(b));
+        let same_kind_pair = is_message_pair || is_reasoning_pair;
         if !same_kind_pair {
             return false;
         }
@@ -1627,9 +1639,10 @@ FORMAT JSONEachRow",
     }
 
     fn search_row_kind_priority(row: &SearchRow) -> u8 {
-        if Self::is_message_search_row(row) {
+        if Self::is_message_search_row(row) || Self::is_reasoning_search_row(row) {
             0
-        } else if Self::is_event_msg_search_row(row) {
+        } else if Self::is_event_msg_search_row(row) || Self::is_event_msg_reasoning_search_row(row)
+        {
             1
         } else {
             2
@@ -3088,7 +3101,9 @@ FORMAT JSONEachRow",
 
         let terms_with_qf = tokenize_query(query_text, self.cfg.bm25_max_query_terms);
         if terms_with_qf.is_empty() {
-            return Err(RepoError::invalid_argument("query has no searchable terms"));
+            return Err(RepoError::invalid_argument(
+                "query has no searchable terms (tokens shorter than 2 characters are excluded)",
+            ));
         }
         let terms: Vec<String> = terms_with_qf.iter().map(|(term, _)| term.clone()).collect();
 
@@ -3252,7 +3267,9 @@ FORMAT JSONEachRow",
 
         let terms_with_qf = tokenize_query(query_text, self.cfg.bm25_max_query_terms);
         if terms_with_qf.is_empty() {
-            return Err(RepoError::invalid_argument("query has no searchable terms"));
+            return Err(RepoError::invalid_argument(
+                "query has no searchable terms (tokens shorter than 2 characters are excluded)",
+            ));
         }
         let terms: Vec<String> = terms_with_qf.iter().map(|(term, _)| term.clone()).collect();
 
@@ -3799,6 +3816,66 @@ mod tests {
         assert_eq!(deduped.len(), 2);
     }
 
+    #[test]
+    fn dedupe_search_rows_prefers_reasoning_over_event_msg_reasoning_mirror() {
+        let rows = vec![
+            sample_search_row(
+                "uid-event-msg-reasoning",
+                "sess-a",
+                "event_msg",
+                "agent_reasoning",
+                "assistant",
+                "Let me think about this",
+                12.50,
+                2,
+            ),
+            sample_search_row(
+                "uid-reasoning",
+                "sess-a",
+                "reasoning",
+                "reasoning",
+                "assistant",
+                "Let me think about this",
+                12.50,
+                2,
+            ),
+        ];
+
+        let deduped = ClickHouseConversationRepository::dedupe_search_rows(rows, 5);
+        assert_eq!(deduped.len(), 1);
+        assert_eq!(deduped[0].event_uid, "uid-reasoning");
+        assert_eq!(deduped[0].event_class, "reasoning");
+    }
+
+    #[test]
+    fn dedupe_search_rows_reasoning_mirrors_do_not_collapse_with_messages() {
+        let rows = vec![
+            sample_search_row(
+                "uid-reasoning",
+                "sess-a",
+                "reasoning",
+                "reasoning",
+                "assistant",
+                "same text",
+                10.0,
+                2,
+            ),
+            sample_search_row(
+                "uid-message",
+                "sess-a",
+                "message",
+                "message",
+                "assistant",
+                "same text",
+                10.0,
+                2,
+            ),
+        ];
+
+        let deduped = ClickHouseConversationRepository::dedupe_search_rows(rows, 5);
+        assert_eq!(deduped.len(), 2);
+    }
+
     #[test]
     fn low_information_system_event_classifier_targets_open_noise() {
         assert!(

crates/moraine-mcp-core/src/lib.rs

@@ -303,7 +303,7 @@ struct SessionListProseSession {
     #[serde(default)]
     event_count: u64,
     #[serde(default)]
-    harness_type: String,
+    mode: String,
 }
 
 #[derive(Clone)]
@@ -387,15 +387,15 @@ impl AppState {
             "tools": [
                 {
                     "name": "search",
-                    "description": "BM25 lexical search over Moraine indexed conversation events.",
+                    "description": "BM25 lexical search over Moraine indexed conversation events. Bag-of-words ranking: no phrase matching, no stemming. Word order does not matter.",
                     "inputSchema": {
                         "type": "object",
                         "properties": {
                             "query": { "type": "string" },
                             "limit": { "type": "integer", "minimum": limit_min, "maximum": limit_max },
                             "session_id": { "type": "string" },
                             "min_score": { "type": "number" },
-                            "min_should_match": { "type": "integer", "minimum": 1 },
+                            "min_should_match": { "type": "integer", "minimum": 1, "description": "Minimum number of query terms that must match. Values exceeding the number of query terms are clamped." },
                             "include_tool_events": { "type": "boolean" },
                             "event_kind": {
                                 "oneOf": [
@@ -452,7 +452,7 @@ impl AppState {
                             "query": { "type": "string" },
                             "limit": { "type": "integer", "minimum": limit_min, "maximum": limit_max },
                             "min_score": { "type": "number" },
-                            "min_should_match": { "type": "integer", "minimum": 1 },
+                            "min_should_match": { "type": "integer", "minimum": 1, "description": "Minimum number of query terms that must match. Values exceeding the number of query terms are clamped." },
                             "from_unix_ms": { "type": "integer" },
                             "to_unix_ms": { "type": "integer" },
                             "mode": {
@@ -483,7 +483,8 @@ impl AppState {
                             "to_unix_ms": { "type": "integer" },
                             "mode": {
                                 "type": "string",
-                                "enum": ["web_search", "mcp_internal", "tool_calling", "chat"]
+                                "enum": ["web_search", "mcp_internal", "tool_calling", "chat"],
+                                "description": SEARCH_CONVERSATIONS_MODE_DOC
                             },
                             "verbosity": {
                                 "type": "string",
@@ -665,7 +666,7 @@ impl AppState {
                     "assistant_messages": summary.assistant_messages,
                     "tool_calls": summary.tool_calls,
                     "tool_results": summary.tool_results,
-                    "harness_type": summary.mode.as_str(),
+                    "mode": summary.mode.as_str(),
                 })
             })
             .collect::<Vec<_>>();
@@ -991,17 +992,17 @@ fn format_session_list_prose(payload: &Value) -> Result<String> {
     }
 
     for (idx, session) in parsed.sessions.iter().enumerate() {
-        let harness = if session.harness_type.is_empty() {
+        let mode = if session.mode.is_empty() {
             "chat"
         } else {
-            session.harness_type.as_str()
+            session.mode.as_str()
         };
 
         out.push_str(&format!(
-            "\n{}) session={} harness={} events={}\n",
+            "\n{}) session={} mode={} events={}\n",
             idx + 1,
             session.session_id,
-            harness,
+            mode,
             session.event_count
         ));
         out.push_str(&format!(
@@ -1380,15 +1381,15 @@ mod tests {
                     "end_time": "2026-01-02 12:05:00",
                     "end_unix_ms": 1767355500000_i64,
                     "event_count": 22_u64,
-                    "harness_type": "web_search"
+                    "mode": "web_search"
                 }
             ],
             "next_cursor": "cursor-token"
         });
 
         let text = format_session_list_prose(&payload).expect("format");
         assert!(text.contains("session=sess-1"));
-        assert!(text.contains("harness=web_search"));
+        assert!(text.contains("mode=web_search"));
         assert!(text.contains("next_cursor: cursor-token"));
     }
 }