nexo-brain 7.23.2 → 7.23.4

package/src/scripts/post_disk_recovery_sweep.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Nudge background sync apps after disk pressure has been relieved."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+SOURCE_ROOT = Path(__file__).resolve().parents[1]
+if str(SOURCE_ROOT) not in sys.path:
+    sys.path.insert(0, str(SOURCE_ROOT))
+
+import paths
+from disk_recovery.registry import run_sweep
+
+
+def _network_snapshot() -> dict:
+    # Best-effort and intentionally coarse: enough to confirm activity changed
+    # without collecting destinations or user content.
+    try:
+        import psutil  # type: ignore
+
+        counters = psutil.net_io_counters()
+        return {"bytes_sent": int(counters.bytes_sent), "bytes_recv": int(counters.bytes_recv)}
+    except Exception:
+        return {"bytes_sent": None, "bytes_recv": None}
+
+
+def _network_delta(before: dict, after: dict) -> dict:
+    out: dict[str, int | None] = {}
+    for key in ("bytes_sent", "bytes_recv"):
+        a = after.get(key)
+        b = before.get(key)
+        out[key] = int(a) - int(b) if isinstance(a, int) and isinstance(b, int) else None
+    return out
+
+
+def append_log(payload: dict) -> None:
+    log_path = paths.operations_dir() / "post-disk-recovery-sweep.jsonl"
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    with log_path.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(payload, sort_keys=True) + "\n")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Run post-disk-recovery sync sweep")
+    parser.add_argument("--platform", help="Override platform for tests: darwin/windows")
+    parser.add_argument("--dry-run", action="store_true", help="Plan actions without running commands")
+    parser.add_argument("--json", action="store_true", help="Print JSON report")
+    parser.add_argument("--network-window-seconds", type=float, default=0, help="Seconds between network snapshots")
+    parser.add_argument("--reason", default="manual", help="Reason written to the operations log")
+    args = parser.parse_args(argv)
+
+    before = _network_snapshot()
+    report = run_sweep(platform=args.platform, dry_run=args.dry_run)
+    if args.network_window_seconds > 0:
+        time.sleep(args.network_window_seconds)
+    after = _network_snapshot()
+    payload = {
+        "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "reason": args.reason,
+        "network_window_seconds": args.network_window_seconds,
+        "network_delta": _network_delta(before, after),
+        **report,
+    }
+    append_log(payload)
+    if args.json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    return 0 if payload.get("ok") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/scripts/prune_runtime_backups.py

@@ -115,6 +115,8 @@ TEMPORARY_RE = re.compile(r"(^|.*[.])tmp([.-].*)?$|.*\.tmp\..*|.*-journal$|.*\.d
 # Big ad-hoc DB files at the root — rare, include for reporting but never auto-prune.
 ROOT_DB_RE = re.compile(r"^(pre-obs-clean|pre-sleep-wrapper-apply|pre-.*)-\d{4}-\d{2}-\d{2}-\d{4}\.db$")
 DEFAULT_MAX_BYTES = 50 * 1024 * 1024 * 1024
+MIN_ADAPTIVE_MAX_BYTES = 10 * 1024 * 1024 * 1024
+MAX_ADAPTIVE_MAX_BYTES = 50 * 1024 * 1024 * 1024
 
 # Timestamp patterns embedded in directory names.
 TS_PATTERNS = (
@@ -214,6 +216,20 @@ def parse_size_bytes(value: str | int | None, *, default: int = DEFAULT_MAX_BYTE
         return default
 
 
+def effective_max_bytes(backups_root: Path, raw_max_bytes: int) -> int:
+    """Apply the adaptive default cap without blocking emergency lower caps."""
+    if raw_max_bytes < MIN_ADAPTIVE_MAX_BYTES:
+        return raw_max_bytes
+    probe = backups_root if backups_root.exists() else backups_root.parent
+    try:
+        total = int(shutil.disk_usage(str(probe)).total)
+        adaptive = int(total * 0.05)
+    except Exception:
+        adaptive = DEFAULT_MAX_BYTES
+    adaptive = max(MIN_ADAPTIVE_MAX_BYTES, min(MAX_ADAPTIVE_MAX_BYTES, adaptive))
+    return min(raw_max_bytes, adaptive)
+
+
 def gather_entries(backups_root: Path) -> list[dict]:
     items: list[dict] = []
     for entry in backups_root.iterdir():
@@ -303,7 +319,7 @@ def plan_prunes(
         else:
             to_keep.append(it)
 
-    for klass, keep_count in (("LOCAL_CONTEXT_DB", local_context_keep), ("HOURLY_DB", hourly_keep)):
+    for klass, keep_count in (("LOCAL_CONTEXT_DB", local_context_keep),):
         group = [it for it in items if it["class"] == klass]
         group.sort(key=lambda x: (x["ts"] or datetime.min.replace(tzinfo=timezone.utc)), reverse=True)
         for it in group[:max(0, keep_count)]:
@@ -321,12 +337,10 @@ def plan_prunes(
             for it in items:
                 by_budget_family.setdefault((it["class"], it["family"]), []).append(it)
             for (klass, _family), group in by_budget_family.items():
-                if klass not in {"TECHNICAL", "LOCAL_CONTEXT_DB", "HOURLY_DB", "TEMPORARY"}:
+                if klass not in {"TECHNICAL", "LOCAL_CONTEXT_DB", "TEMPORARY"}:
                     continue
                 min_keep = 0
-                if klass == "HOURLY_DB":
-                    min_keep = max(1, hourly_keep)
-                elif klass == "LOCAL_CONTEXT_DB":
+                if klass == "LOCAL_CONTEXT_DB":
                     min_keep = max(0, local_context_keep)
                 group.sort(key=lambda x: (x["ts"] or datetime.min.replace(tzinfo=timezone.utc)), reverse=True)
                 for it in group[:min_keep]:
@@ -336,7 +350,7 @@ def plan_prunes(
                 it for it in items
                 if id(it) not in delete_ids
                 and id(it) not in protected_keep_ids
-                and it["class"] in {"TECHNICAL", "LOCAL_CONTEXT_DB", "HOURLY_DB", "TEMPORARY"}
+                and it["class"] in {"TECHNICAL", "LOCAL_CONTEXT_DB", "TEMPORARY"}
             ]
             budget_candidates.sort(
                 key=lambda x: (
@@ -358,6 +372,28 @@ def plan_prunes(
     return to_delete, to_keep
 
 
+def restore_point_guard(items: list[dict], to_delete: list[dict]) -> tuple[bool, list[str], dict]:
+    """Validate that apply mode never removes protected restore classes."""
+    delete_ids = {id(item) for item in to_delete}
+    protected_classes = {"BUSINESS", "HOURLY_DB", "ROOT_DB", "UNKNOWN"}
+    protected_names = set(PROTECTED_NAMES)
+    violations: list[str] = []
+    for item in items:
+        if id(item) not in delete_ids:
+            continue
+        if item["class"] in protected_classes or item["name"] in protected_names:
+            violations.append(f"{item['name']} ({item['class']})")
+    hourly_count = sum(1 for item in items if item["class"] == "HOURLY_DB")
+    weekly_present = any(item["name"] == "weekly" for item in items)
+    business_count = sum(1 for item in items if item["class"] == "BUSINESS")
+    return not violations, violations, {
+        "hourly_db_present": hourly_count,
+        "weekly_present": weekly_present,
+        "business_protected": business_count,
+        "protected_delete_violations": violations,
+    }
+
+
 def run(args: argparse.Namespace) -> int:
     backups_root = Path(args.root or (default_nexo_home() / "runtime" / "backups"))
     if not backups_root.is_dir():
@@ -371,7 +407,7 @@ def run(args: argparse.Namespace) -> int:
     local_context_items = [i for i in items if i["class"] == "LOCAL_CONTEXT_DB"]
     temporary_items = [i for i in items if i["class"] == "TEMPORARY"]
     unknown_items = [i for i in items if i["class"] == "UNKNOWN"]
-    max_bytes = parse_size_bytes(args.max_bytes)
+    max_bytes = effective_max_bytes(backups_root, parse_size_bytes(args.max_bytes))
 
     to_delete, to_keep = plan_prunes(
         items,
@@ -384,6 +420,16 @@ def run(args: argparse.Namespace) -> int:
         hourly_keep=max(0, args.hourly_keep),
     )
 
+    if args.delete_all_technical:
+        delete_ids = {id(item) for item in to_delete}
+        for item in items:
+            if item["class"] in {"TECHNICAL", "TEMPORARY"} and id(item) not in delete_ids:
+                to_delete.append(item)
+                delete_ids.add(id(item))
+        to_keep = [item for item in items if id(item) not in delete_ids]
+
+    restore_guard_ok, restore_guard_violations, restore_guard = restore_point_guard(items, to_delete)
+
     total_all = sum(i["size"] for i in items)
     total_del = sum(i["size"] for i in to_delete)
 
@@ -396,9 +442,11 @@ def run(args: argparse.Namespace) -> int:
             "only": args.only,
             "max_bytes": max_bytes,
             "max_human": human_size(max_bytes),
+            "delete_all_technical": args.delete_all_technical,
             "tmp_ttl_minutes": args.tmp_ttl_minutes,
             "local_context_keep": args.local_context_keep,
             "hourly_keep": args.hourly_keep,
+            "restore_point_guard": restore_guard,
         },
         "totals": {
             "all_bytes": total_all,
@@ -429,9 +477,7 @@ def run(args: argparse.Namespace) -> int:
         "unknown": [i["name"] for i in unknown_items],
     }
 
-    if args.json:
-        print(json.dumps(report, indent=2))
-    else:
+    if not args.json:
         print(f"NEXO backup prune — root: {backups_root}")
         print(f"  total on disk:   {human_size(total_all)}  ({len(items)} entries)")
         print(f"    technical:     {len(tech_items)}")
@@ -457,10 +503,21 @@ def run(args: argparse.Namespace) -> int:
                 print(f"  ? {it['name']}")
 
     if not args.apply:
+        if args.json:
+            print(json.dumps(report, indent=2))
+            return 0
         if not args.json:
             print("\n(dry-run: pass --apply to delete)")
         return 0
 
+    if not restore_guard_ok:
+        print(
+            "ERROR: refusing to prune protected restore artifacts: "
+            + ", ".join(restore_guard_violations),
+            file=sys.stderr,
+        )
+        return 1
+
     deleted = 0
     failed = 0
     freed = 0
@@ -476,7 +533,16 @@ def run(args: argparse.Namespace) -> int:
         except OSError as e:
             failed += 1
             print(f"WARN: failed to delete {p}: {e}", file=sys.stderr)
-    print(f"\nDELETED {deleted} entries, freed {human_size(freed)}, failures: {failed}")
+    report["apply"] = {
+        "deleted": deleted,
+        "freed_bytes": freed,
+        "freed_human": human_size(freed),
+        "failures": failed,
+    }
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print(f"\nDELETED {deleted} entries, freed {human_size(freed)}, failures: {failed}")
     return 0 if failed == 0 else 1
 
 
@@ -489,6 +555,7 @@ def main() -> int:
     ap.add_argument("--window-days", type=int, default=90, help="month-spaced retention window (default: 90)")
     ap.add_argument("--only", help="restrict to one technical family (e.g. 'pre-backfill-owner')")
     ap.add_argument("--max-bytes", default=os.environ.get("NEXO_BACKUP_MAX_BYTES", str(DEFAULT_MAX_BYTES)), help="global product-generated backup hard cap, bytes or K/M/G/T (default: 50G)")
+    ap.add_argument("--delete-all-technical", action="store_true", help="emergency mode: delete all technical rollback snapshots; protected business/weekly/hourly DB backups remain untouched")
     ap.add_argument("--tmp-ttl-minutes", type=int, default=int(os.environ.get("NEXO_BACKUP_TMP_TTL_MINUTES", "30")), help="delete orphan temporary backup files older than this (default: 30)")
     ap.add_argument("--local-context-keep", type=int, default=int(os.environ.get("NEXO_LOCAL_CONTEXT_BACKUP_KEEP_LAST", "1")), help="local-context backup files to keep under the global cap (default: 1)")
     ap.add_argument("--hourly-keep", type=int, default=int(os.environ.get("NEXO_BACKUP_KEEP_LAST", "3")), help="hourly nexo DB backups to keep under the global cap (default: 3)")

package/src/server.py

@@ -1429,7 +1429,7 @@ def nexo_saved_not_used_audit(markdown: bool = False) -> str:
 
 @mcp.tool
 def nexo_automation_supervisor(markdown: bool = False) -> str:
-    """Read-only supervisor report for automations, cron runs and cron spool, excluding Evolution."""
+    """Read-only supervisor report for automations, cron runs, cron spool and Evolution policy."""
     from automation_supervisor import audit_automation, format_markdown
 
     report = audit_automation()
@@ -1438,6 +1438,18 @@ def nexo_automation_supervisor(markdown: bool = False) -> str:
     return json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True)
 
 
+@mcp.tool
+def nexo_automation_reconcile(apply: bool = False) -> str:
+    """Build or apply the safe automation reconciliation plan."""
+    from automation_reconciler import apply_reconciliation_plan, build_reconciliation_plan
+
+    plan = build_reconciliation_plan()
+    if apply:
+        result = apply_reconciliation_plan(plan)
+        return json.dumps({"ok": result.get("ok", False), "plan": plan, "apply": result}, ensure_ascii=False, indent=2)
+    return json.dumps(plan, ensure_ascii=False, indent=2)
+
+
 @mcp.tool
 def nexo_system_catalog(section: str = "", query: str = "", limit: int = 20) -> str:
     """Read NEXO's live system catalog built from core tools, plugins, skills, scripts, crons, projects, and artifacts."""

package/src/storage_router.py

@@ -3,6 +3,7 @@
 import os
 
 import paths
+from cognitive_paths import resolve_cognitive_db
 
 NEXO_HOME = os.environ.get("NEXO_HOME", os.path.expanduser("~/.nexo"))
 
@@ -20,9 +21,7 @@ class StorageRouter:
 
     def cognitive_db_path(self) -> str:
         if self.tenant_id == "default":
-            cognitive_dir = paths.cognitive_dir()
-            cognitive_dir.mkdir(parents=True, exist_ok=True)
-            return str(cognitive_dir / "cognitive.db")
+            return str(resolve_cognitive_db(for_write=True))
         return os.path.join(NEXO_HOME, "tenants", self.tenant_id, "cognitive.db")
 
 

package/src/support_snapshot.py

@@ -111,6 +111,30 @@ def _recent_logs(lines: int = 80) -> dict[str, Any]:
     }
 
 
+def _backup_retention_status(lines: int = 20) -> dict[str, Any]:
+    root = paths.backups_dir()
+    status: dict[str, Any] = {
+        "root": str(root),
+        "exists": root.exists(),
+        "cap_bytes": paths.backup_retention_cap_bytes(backups_root=root),
+        "min_free_bytes": paths.backup_min_free_bytes(),
+        "free_bytes": paths.backup_free_bytes(backups_root=root),
+        "recent_events": [],
+    }
+    event_log = paths.operations_dir() / "backup-retention-events.jsonl"
+    if event_log.is_file():
+        try:
+            raw = event_log.read_text(encoding="utf-8", errors="ignore").splitlines()[-lines:]
+            for line in raw:
+                try:
+                    status["recent_events"].append(json.loads(line))
+                except Exception:
+                    continue
+        except Exception as exc:
+            status["recent_events"] = [{"error": str(exc)}]
+    return status
+
+
 def collect_snapshot(*, log_lines: int = 80, include_doctor: bool = False) -> dict[str, Any]:
     system = platform.system()
     release = platform.release()
@@ -130,6 +154,7 @@ def collect_snapshot(*, log_lines: int = 80, include_doctor: bool = False) -> di
         },
         "paths": _path_status(),
         "health": collect_health(),
+        "backup_retention": _backup_retention_status(),
         "logs": _recent_logs(log_lines),
     }
 

package/src/transcript_index.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+"""Structured transcript metadata index for pre-answer continuity.
+
+This index stores compact, redacted metadata and short snippets only. Raw JSONL
+transcripts remain a last-resort fallback and are not copied into the database.
+"""
+
+import hashlib
+import json
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from db import get_db
+from transcript_utils import (
+    DEFAULT_TRANSCRIPT_HOURS,
+    _score_text_match,
+    _tokenize,
+    _truncate,
+    list_recent_transcripts,
+)
+
+
+def _ensure_transcript_index_table() -> None:
+    conn = get_db()
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS transcript_index (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            source_client TEXT NOT NULL,
+            conversation_id TEXT DEFAULT '',
+            session_id TEXT DEFAULT '',
+            message_count INTEGER DEFAULT 0,
+            user_message_count INTEGER DEFAULT 0,
+            first_user_at TEXT DEFAULT '',
+            last_user_at TEXT DEFAULT '',
+            path_ref TEXT NOT NULL,
+            display_name TEXT DEFAULT '',
+            indexed_at TEXT DEFAULT (datetime('now')),
+            modified_at TEXT DEFAULT '',
+            content_hash TEXT NOT NULL,
+            sanitized_summary TEXT DEFAULT '',
+            metadata_json TEXT DEFAULT '{}',
+            UNIQUE(source_client, path_ref)
+        )
+    """)
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_transcript_index_client_modified ON transcript_index(source_client, modified_at)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_transcript_index_session ON transcript_index(session_id)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_transcript_index_conversation ON transcript_index(conversation_id)")
+    conn.commit()
+
+
+def _session_identity(session: dict[str, Any]) -> tuple[str, str, str, str]:
+    source_client = str(session.get("client") or "")
+    session_id = str(session.get("session_uid") or session.get("session_file") or session.get("display_name") or "")
+    conversation_id = str(session.get("conversation_id") or session.get("session_uid") or session_id)
+    path_ref = str(session.get("session_path") or session.get("path") or "")
+    return source_client, session_id, conversation_id, path_ref
+
+
+def _session_modified_at(session: dict[str, Any]) -> str:
+    modified = str(session.get("modified") or "").strip()
+    if modified:
+        return modified
+    path_ref = str(session.get("session_path") or "").strip()
+    if not path_ref:
+        return ""
+    try:
+        return datetime.fromtimestamp(Path(path_ref).stat().st_mtime).isoformat()
+    except OSError:
+        return ""
+
+
+def _content_hash(session: dict[str, Any]) -> str:
+    digest = hashlib.sha256()
+    digest.update(str(session.get("client") or "").encode())
+    digest.update(str(session.get("session_file") or "").encode())
+    for message in session.get("messages") or []:
+        digest.update(str(message.get("role") or "").encode())
+        digest.update(str(message.get("index") or "").encode())
+        digest.update(str(message.get("text") or "").encode())
+    return digest.hexdigest()
+
+
+def _sanitized_summary(session: dict[str, Any], *, limit: int = 900) -> str:
+    user_snippets: list[str] = []
+    assistant_snippets: list[str] = []
+    for message in session.get("messages") or []:
+        role = str(message.get("role") or "")
+        text = _truncate(str(message.get("text") or ""), 180)
+        if not text:
+            continue
+        if role == "user" and len(user_snippets) < 3:
+            user_snippets.append(text)
+        elif role == "assistant" and len(assistant_snippets) < 2:
+            assistant_snippets.append(text)
+    parts = []
+    if user_snippets:
+        parts.append("user: " + " | ".join(user_snippets))
+    if assistant_snippets:
+        parts.append("assistant: " + " | ".join(assistant_snippets))
+    summary = " ".join(parts)
+    return _truncate(summary, limit)
+
+
+def index_transcript_session(session: dict[str, Any]) -> dict[str, Any]:
+    """Upsert a single transcript metadata row and return it."""
+    _ensure_transcript_index_table()
+    source_client, session_id, conversation_id, path_ref = _session_identity(session)
+    if not source_client or not path_ref:
+        raise ValueError("transcript session requires client and session_path")
+
+    metadata = {
+        "source": session.get("source", ""),
+        "cwd": session.get("cwd", ""),
+        "originator": session.get("originator", ""),
+        "tool_use_count": session.get("tool_use_count", 0),
+    }
+    conn = get_db()
+    conn.execute(
+        """
+        INSERT INTO transcript_index (
+            source_client, conversation_id, session_id, message_count,
+            user_message_count, first_user_at, last_user_at, path_ref,
+            display_name, indexed_at, modified_at, content_hash,
+            sanitized_summary, metadata_json
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), ?, ?, ?, ?)
+        ON CONFLICT(source_client, path_ref) DO UPDATE SET
+            conversation_id = excluded.conversation_id,
+            session_id = excluded.session_id,
+            message_count = excluded.message_count,
+            user_message_count = excluded.user_message_count,
+            first_user_at = excluded.first_user_at,
+            last_user_at = excluded.last_user_at,
+            display_name = excluded.display_name,
+            indexed_at = datetime('now'),
+            modified_at = excluded.modified_at,
+            content_hash = excluded.content_hash,
+            sanitized_summary = excluded.sanitized_summary,
+            metadata_json = excluded.metadata_json
+        """,
+        (
+            source_client,
+            conversation_id,
+            session_id,
+            int(session.get("message_count") or len(session.get("messages") or [])),
+            int(session.get("user_message_count") or 0),
+            str(session.get("first_user_at") or ""),
+            str(session.get("last_user_at") or ""),
+            path_ref,
+            str(session.get("display_name") or ""),
+            _session_modified_at(session),
+            _content_hash(session),
+            _sanitized_summary(session),
+            json.dumps(metadata, ensure_ascii=False, sort_keys=True),
+        ),
+    )
+    conn.commit()
+    row = conn.execute(
+        "SELECT * FROM transcript_index WHERE source_client = ? AND path_ref = ?",
+        (source_client, path_ref),
+    ).fetchone()
+    return dict(row) if row else {}
+
+
+def index_recent_transcripts(
+    *,
+    hours: int = DEFAULT_TRANSCRIPT_HOURS,
+    client: str = "",
+    limit: int = 200,
+    min_user_messages: int = 1,
+) -> list[dict[str, Any]]:
+    rows = list_recent_transcripts(
+        hours=hours,
+        client=client,
+        limit=limit,
+        min_user_messages=min_user_messages,
+    )
+    indexed = []
+    for session in rows:
+        try:
+            indexed.append(index_transcript_session(session))
+        except Exception:
+            continue
+    return indexed
+
+
+def search_transcript_index(
+    query: str = "",
+    *,
+    hours: int = 72,
+    client: str = "",
+    limit: int = 10,
+) -> list[dict[str, Any]]:
+    _ensure_transcript_index_table()
+    conn = get_db()
+    params: list[Any] = []
+    where = "1=1"
+    if client:
+        where += " AND source_client = ?"
+        params.append(client)
+    rows = [dict(row) for row in conn.execute(
+        f"SELECT * FROM transcript_index WHERE {where} ORDER BY modified_at DESC LIMIT 500",
+        tuple(params),
+    ).fetchall()]
+
+    cutoff = datetime.now() - timedelta(hours=max(1, int(hours or 72)))
+    query_tokens = _tokenize(query)
+    matches = []
+    for row in rows:
+        modified = str(row.get("modified_at") or "")
+        if modified:
+            try:
+                if datetime.fromisoformat(modified) < cutoff:
+                    continue
+            except Exception:
+                pass
+        if not query_tokens:
+            row["_score"] = 0.0
+            matches.append(row)
+            continue
+        haystack = " ".join(
+            str(row.get(field) or "")
+            for field in ("sanitized_summary", "display_name", "session_id", "conversation_id", "metadata_json")
+        )
+        score = _score_text_match(query_tokens, haystack)
+        if score <= 0:
+            continue
+        row["_score"] = round(score, 4)
+        matches.append(row)
+
+    matches.sort(key=lambda row: (float(row.get("_score") or 0), str(row.get("modified_at") or "")), reverse=True)
+    return matches[: max(1, int(limit or 10))]

package/src/transcript_utils.py

@@ -118,7 +118,15 @@ def find_codex_session_files() -> list[Path]:
     return files
 
 
-def extract_claude_session(jsonl_path: Path) -> dict | None:
+def _min_user_messages(value: int | str | None = MIN_USER_MESSAGES) -> int:
+    try:
+        parsed = int(value if value is not None else MIN_USER_MESSAGES)
+    except Exception:
+        parsed = MIN_USER_MESSAGES
+    return max(1, parsed)
+
+
+def extract_claude_session(jsonl_path: Path, *, min_user_messages: int = MIN_USER_MESSAGES) -> dict | None:
     messages = []
     tool_uses = []
     user_msg_count = 0
@@ -183,7 +191,7 @@ def extract_claude_session(jsonl_path: Path) -> dict | None:
     except Exception:
         return None
 
-    if user_msg_count < MIN_USER_MESSAGES:
+    if user_msg_count < _min_user_messages(min_user_messages):
         return None
 
     return {
@@ -200,7 +208,7 @@ def extract_claude_session(jsonl_path: Path) -> dict | None:
     }
 
 
-def extract_codex_session(jsonl_path: Path) -> dict | None:
+def extract_codex_session(jsonl_path: Path, *, min_user_messages: int = MIN_USER_MESSAGES) -> dict | None:
     messages = []
     tool_uses = []
     user_msg_count = 0
@@ -266,7 +274,7 @@ def extract_codex_session(jsonl_path: Path) -> dict | None:
     except Exception:
         return None
 
-    if user_msg_count < MIN_USER_MESSAGES:
+    if user_msg_count < _min_user_messages(min_user_messages):
         return None
 
     return {
@@ -286,7 +294,12 @@ def extract_codex_session(jsonl_path: Path) -> dict | None:
     }
 
 
-def collect_transcripts_since(since_iso: str, until_iso: str = "") -> list[dict]:
+def collect_transcripts_since(
+    since_iso: str,
+    until_iso: str = "",
+    *,
+    min_user_messages: int = MIN_USER_MESSAGES,
+) -> list[dict]:
     since_dt = datetime.fromisoformat(since_iso)
     until_dt = datetime.fromisoformat(until_iso) if until_iso else datetime.now()
     sessions = []
@@ -302,7 +315,11 @@ def collect_transcripts_since(since_iso: str, until_iso: str = "") -> list[dict]
             continue
         if not (since_dt < mtime <= until_dt):
             continue
-        session = extract_codex_session(session_file) if client == "codex" else extract_claude_session(session_file)
+        session = (
+            extract_codex_session(session_file, min_user_messages=min_user_messages)
+            if client == "codex"
+            else extract_claude_session(session_file, min_user_messages=min_user_messages)
+        )
         if session:
             session["modified"] = mtime.isoformat()
             sessions.append(session)
@@ -310,10 +327,16 @@ def collect_transcripts_since(since_iso: str, until_iso: str = "") -> list[dict]
     return sessions
 
 
-def list_recent_transcripts(hours: int = DEFAULT_TRANSCRIPT_HOURS, client: str = "", limit: int = 10) -> list[dict]:
+def list_recent_transcripts(
+    hours: int = DEFAULT_TRANSCRIPT_HOURS,
+    client: str = "",
+    limit: int = 10,
+    *,
+    min_user_messages: int = MIN_USER_MESSAGES,
+) -> list[dict]:
     window = clamp_transcript_hours(hours)
     since = datetime.now() - timedelta(hours=window)
-    sessions = collect_transcripts_since(since.isoformat())
+    sessions = collect_transcripts_since(since.isoformat(), min_user_messages=min_user_messages)
     filtered = []
     for item in sessions:
         if client and item.get("client") != client: