memclaw-client 0.2.0__py3-none-any.whl

memclaw_client/__init__.py

@@ -0,0 +1,20 @@
+"""Official Python client for MemClaw — governed shared memory for AI agent fleets."""
+
+from __future__ import annotations
+
+from .client import DEFAULT_BASE_URL, MemClaw
+from .exceptions import AuthError, MemClawAPIError, MemClawError, NotFoundError
+from .models import Memory, RecallResult
+
+__all__ = [
+    "MemClaw",
+    "Memory",
+    "RecallResult",
+    "MemClawError",
+    "MemClawAPIError",
+    "AuthError",
+    "NotFoundError",
+    "DEFAULT_BASE_URL",
+]
+
+__version__ = "0.1.0"

memclaw_client/client.py

@@ -0,0 +1,219 @@
+"""Synchronous MemClaw client.
+
+A thin wrapper over the MemClaw REST API. Point it at a managed
+(``https://memclaw.net``) or self-hosted (``http://localhost:8000``) deployment.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+from typing import Any
+
+import httpx
+
+from .exceptions import AuthError, MemClawAPIError, NotFoundError
+from .models import Memory, RecallResult
+
+DEFAULT_BASE_URL = "https://memclaw.net"
+
+
+class MemClaw:
+    """Client for a MemClaw deployment.
+
+    Example::
+
+        from memclaw_client import MemClaw
+
+        mc = MemClaw("mc_xxx", tenant_id="my-team", agent_id="my-agent")
+        mc.write("Q3 revenue target is $4M, set on 2026-04-15.")
+        for m in mc.search("Q3 revenue target"):
+            print(m.title, m.content)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        tenant_id: str,
+        base_url: str = DEFAULT_BASE_URL,
+        agent_id: str | None = None,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        if not tenant_id:
+            raise ValueError("tenant_id is required")
+        self.tenant_id = tenant_id
+        self.agent_id = agent_id
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
+            timeout=timeout,
+            transport=transport,
+        )
+
+    # ------------------------------------------------------------------ ops
+    def write(
+        self,
+        content: str,
+        *,
+        agent_id: str | None = None,
+        memory_type: str | None = None,
+        fleet_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        **extra: Any,
+    ) -> Memory:
+        """Persist a memory. Returns the enriched ``Memory`` (POST /api/v1/memories)."""
+        body: dict[str, Any] = {"tenant_id": self.tenant_id, "content": content}
+        resolved_agent = agent_id or self.agent_id
+        if resolved_agent:
+            body["agent_id"] = resolved_agent
+        if memory_type:
+            body["memory_type"] = memory_type
+        if fleet_id:
+            body["fleet_id"] = fleet_id
+        if metadata is not None:
+            body["metadata"] = metadata
+        body.update(extra)
+        return Memory.from_dict(self._post("/api/v1/memories", body))
+
+    def search(
+        self,
+        query: str,
+        *,
+        top_k: int = 5,
+        fleet_ids: list[str] | None = None,
+        filter_agent_id: str | None = None,
+        **extra: Any,
+    ) -> list[Memory]:
+        """Hybrid vector + keyword search. Returns ranked ``Memory`` objects (POST /api/v1/search)."""
+        body: dict[str, Any] = {"tenant_id": self.tenant_id, "query": query, "top_k": top_k}
+        if fleet_ids:
+            body["fleet_ids"] = fleet_ids
+        if filter_agent_id:
+            body["filter_agent_id"] = filter_agent_id
+        body.update(extra)
+        data = self._post("/api/v1/search", body)
+        if not isinstance(data, dict):
+            raise MemClawAPIError(200, "search response must be a JSON object")
+        if "items" not in data:
+            raise MemClawAPIError(200, 'search response missing "items" list')
+        items = data["items"]
+        if not isinstance(items, list):
+            raise MemClawAPIError(200, 'search response "items" must be a list')
+        return [Memory.from_dict(m) for m in items]
+
+    def recall(self, query: str, *, top_k: int = 5, **extra: Any) -> RecallResult:
+        """Search + LLM summary. Returns a ``RecallResult`` context brief (POST /api/v1/recall)."""
+        body: dict[str, Any] = {"tenant_id": self.tenant_id, "query": query, "top_k": top_k}
+        body.update(extra)
+        return RecallResult.from_dict(self._post("/api/v1/recall", body))
+
+    def health(self) -> dict[str, Any]:
+        """Liveness probe (GET /api/v1/health)."""
+        response = self._http.get("/api/v1/health")
+        return response.json()
+
+    def get_document(
+        self,
+        doc_id: str,
+        *,
+        collection: str,
+        tenant_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Fetch one structured document (GET /api/v1/documents/{doc_id}).
+
+        Returns the full ``DocOut`` envelope — the stored record is under
+        the ``"data"`` key. Raises ``NotFoundError`` if absent.
+        """
+        # Percent-encode the path segment: httpx does not encode f-string
+        # paths, so a doc_id containing '/' would hit a different route and
+        # '?' would inject query params.
+        encoded = urllib.parse.quote(doc_id, safe="")
+        response = self._http.get(
+            f"/api/v1/documents/{encoded}",
+            params={"tenant_id": tenant_id or self.tenant_id, "collection": collection},
+        )
+        self._raise_for_status(response)
+        return response.json()
+
+    def submit_interview(
+        self,
+        *,
+        node_id: str,
+        agent_id: str,
+        cursor_from: int,
+        cursor_to: int,
+        events: list[dict[str, Any]],
+        tenant_id: str | None = None,
+        fleet_id: str | None = None,
+        command_id: str | None = None,
+        timeout: float = 120.0,
+    ) -> dict[str, Any]:
+        """Submit one Interviewer window (POST /api/v1/interview/submit).
+
+        The server interviews the window synchronously (its budget is 90s),
+        so ``timeout`` defaults well above the client-wide 30s. Returns the
+        response body plus ``"http_status"`` so callers can distinguish a
+        207 partial from a 200 committed. Raises on 4xx/5xx via the shared
+        error mapping (403 → ``AuthError``: tenant not enabled / bad key).
+        """
+        body: dict[str, Any] = {
+            "tenant_id": tenant_id or self.tenant_id,
+            "node_id": node_id,
+            "agent_id": agent_id,
+            "cursor_from": cursor_from,
+            "cursor_to": cursor_to,
+            "events": events,
+        }
+        if fleet_id:
+            body["fleet_id"] = fleet_id
+        if command_id:
+            body["command_id"] = command_id
+        response = self._http.post("/api/v1/interview/submit", json=body, timeout=timeout)
+        self._raise_for_status(response)
+        result = response.json()
+        if isinstance(result, dict):
+            result["http_status"] = response.status_code
+        return result
+
+    # ------------------------------------------------------------- internals
+    def _post(self, path: str, body: dict[str, Any]) -> Any:
+        response = self._http.post(path, json=body)
+        self._raise_for_status(response)
+        return response.json()
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        try:
+            payload: Any = response.json()
+        except ValueError:
+            payload = {}
+        message = ""
+        details: Any = None
+        if isinstance(payload, dict):
+            error = payload.get("error")
+            if isinstance(error, dict):
+                message = error.get("message") or ""
+                details = error.get("details")
+            message = message or payload.get("detail") or payload.get("message") or response.text
+        else:
+            message = response.text
+        if response.status_code in (401, 403):
+            raise AuthError(response.status_code, message or "authentication failed", details=details)
+        if response.status_code == 404:
+            raise NotFoundError(response.status_code, message or "not found", details=details)
+        raise MemClawAPIError(response.status_code, message or "request failed", details=details)
+
+    # ------------------------------------------------------------- lifecycle
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> MemClaw:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

memclaw_client/exceptions.py

@@ -0,0 +1,30 @@
+"""Exceptions raised by the MemClaw client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class MemClawError(Exception):
+    """Base class for all MemClaw client errors."""
+
+
+class MemClawAPIError(MemClawError):
+    """Raised when the MemClaw API returns a non-success status code.
+
+    The structured ``error`` envelope (``{"error": {"code", "message", "details"}}``)
+    is parsed when present; otherwise the raw body is used as the message.
+    """
+
+    def __init__(self, status_code: int, message: str, *, details: Any = None) -> None:
+        self.status_code = status_code
+        self.details = details
+        super().__init__(f"[{status_code}] {message}")
+
+
+class AuthError(MemClawAPIError):
+    """Raised on 401/403 — bad or insufficiently-scoped credential."""
+
+
+class NotFoundError(MemClawAPIError):
+    """Raised on 404."""

memclaw_client/interviewer/__init__.py

@@ -0,0 +1,10 @@
+"""memclaw-interviewer — the Claude Code disk-parser adapter (Interviewer Phase 2).
+
+Reads Claude Code session transcripts (``~/.claude/projects/<slug>/<uuid>.jsonl``)
+READ-ONLY, tracks per-file cursors via the server's forward-only watermark
+documents, and submits event windows to ``POST /api/v1/interview/submit``.
+No local state; no server changes; the trail belongs to Claude Code and is
+never modified.
+"""
+
+from __future__ import annotations

memclaw_client/interviewer/cli.py

@@ -0,0 +1,328 @@
+"""memclaw-interviewer CLI — run / status / hook.
+
+Config precedence: flags > env > defaults. Env vars:
+  MEMCLAW_API_KEY (required)      MEMCLAW_TENANT_ID (required)
+  MEMCLAW_BASE_URL                MEMCLAW_AGENT_ID (default user@host)
+  MEMCLAW_FLEET_ID                MEMCLAW_INTERVIEWER_PROJECTS (comma-sep globs)
+
+Exit codes: 0 success / nothing to do; 1 every attempted file failed;
+2 configuration or authorization error. ``hook`` ALWAYS exits 0 — a
+memory-harvest failure must never fail a Claude Code session hook.
+"""
+
+from __future__ import annotations
+
+import argparse
+import errno
+import getpass
+import json
+import os
+import socket
+import sys
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from ..client import MemClaw
+from ..exceptions import AuthError
+from .discovery import (
+    DEFAULT_PROJECTS_ROOT,
+    Transcript,
+    find_transcripts,
+    list_project_dirs,
+    project_allowed,
+)
+from .machine import machine_id_short
+from .parser import count_lines
+from .runner import RunConfig, node_id_for, read_watermark, run_all
+
+DEFAULT_BASE_URL = "https://memclaw.net"
+
+
+def _default_agent_id() -> str:
+    return f"cc-{getpass.getuser()}@{socket.gethostname()}"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="memclaw-interviewer",
+        description="MemClaw Interviewer adapter for Claude Code transcripts (read-only).",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def common(p: argparse.ArgumentParser) -> None:
+        p.add_argument("--base-url", default=os.environ.get("MEMCLAW_BASE_URL", DEFAULT_BASE_URL))
+        p.add_argument("--api-key", default=os.environ.get("MEMCLAW_API_KEY", ""))
+        p.add_argument("--tenant-id", default=os.environ.get("MEMCLAW_TENANT_ID", ""))
+        p.add_argument("--agent-id", default=os.environ.get("MEMCLAW_AGENT_ID", "") or _default_agent_id())
+        p.add_argument("--fleet-id", default=os.environ.get("MEMCLAW_FLEET_ID", "") or None)
+        p.add_argument(
+            "--projects",
+            nargs="+",
+            default=None,
+            help="project-dir globs to allow (default: MEMCLAW_INTERVIEWER_PROJECTS env; DEFAULT-DENY without either)",
+        )
+        p.add_argument("--all-projects", action="store_true", help="explicit opt-in: harvest every project dir")
+        p.add_argument("--projects-root", type=Path, default=DEFAULT_PROJECTS_ROOT)
+        p.add_argument("-v", "--verbose", action="store_true")
+
+    run_p = sub.add_parser("run", help="scan transcripts and submit due interview windows")
+    common(run_p)
+    run_p.add_argument("--transcript", type=Path, default=None, help="drain ONE transcript file (bypasses discovery)")
+    run_p.add_argument("--dry-run", action="store_true", help="parse + window, submit nothing")
+    run_p.add_argument("--max-windows", type=int, default=8)
+    run_p.add_argument("--since-hours", type=float, default=168.0, help="only files modified in this window (0 = all)")
+    run_p.add_argument("--min-events", type=int, default=10, help="dribble gate for the final window")
+    run_p.add_argument("--max-event-chars", type=int, default=4_000)
+    run_p.add_argument("--flush", action="store_true", help="submit even below the dribble gate")
+
+    status_p = sub.add_parser("status", help="show per-file cursor vs local line counts")
+    common(status_p)
+    status_p.add_argument("--since-hours", type=float, default=168.0)
+
+    hook_p = sub.add_parser("hook", help="Claude Code SessionEnd hook: drain the session transcript (stdin JSON)")
+    common(hook_p)
+    hook_p.add_argument("--max-windows", type=int, default=2)
+    hook_p.add_argument("--max-event-chars", type=int, default=4_000)
+    return parser
+
+
+def _resolve_allowlist(args: argparse.Namespace) -> list[str]:
+    if args.projects is not None:
+        return list(args.projects)
+    env = os.environ.get("MEMCLAW_INTERVIEWER_PROJECTS", "")
+    return [g.strip() for g in env.split(",") if g.strip()]
+
+
+def _require_config(args: argparse.Namespace) -> Optional[str]:
+    if not args.api_key:
+        return "MEMCLAW_API_KEY (or --api-key) is required"
+    if not args.tenant_id:
+        return "MEMCLAW_TENANT_ID (or --tenant-id) is required"
+    return None
+
+
+def _deny_guidance(args: argparse.Namespace) -> str:
+    projects = list_project_dirs(args.projects_root)
+    lines = [
+        "No project allowlist configured - refusing to harvest by default.",
+        "Claude Code transcripts can contain sensitive work across ALL projects;",
+        "opt in explicitly with --projects <glob...>, MEMCLAW_INTERVIEWER_PROJECTS,",
+        "or --all-projects.",
+        "",
+        "Discovered project dirs:",
+    ]
+    lines += [f"  {p}" for p in projects] or ["  (none)"]
+    return "\n".join(lines)
+
+
+def _acquire_lock() -> Optional[object]:
+    """Best-effort cross-invocation guard (cron + hook overlap).
+
+    The REAL safety is the server's deterministic attempt-id dedup; this
+    just avoids burning duplicate LLM windows. Never blocks. On platforms
+    without ``fcntl`` (Windows) the guard degrades to a no-op — dedup
+    still protects correctness.
+    """
+    try:
+        import fcntl
+    except ImportError:
+        # No fcntl (Windows): PROCEED without a lock rather than treating
+        # it as "already locked" — returning None here would make every
+        # Windows run exit immediately. Dedup still protects correctness.
+        return object()
+    # Per-user filename: a shared /tmp lock owned by another user would
+    # fail our open() with EACCES forever, reading as "always locked".
+    lock_path = Path(tempfile.gettempdir()) / f"memclaw-interviewer-{getpass.getuser()}.lock"
+    handle = None
+    try:
+        handle = open(lock_path, "w")
+        fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        return handle
+    except OSError as exc:
+        if handle is not None:
+            handle.close()
+        if exc.errno in (errno.EAGAIN, errno.EWOULDBLOCK):
+            return None  # genuine contention: another run holds the lock
+        # Unrecoverable environment error (EACCES on the lock file,
+        # read-only tmpdir, ...): warn and PROCEED lockless, like the
+        # no-fcntl path — treating it as contention would silently
+        # disable the CLI on that machine forever.
+        print(f"[interviewer] lock unavailable ({exc}); proceeding without it", file=sys.stderr)
+        return object()
+
+
+def _make_client(args: argparse.Namespace) -> MemClaw:
+    return MemClaw(
+        args.api_key,
+        tenant_id=args.tenant_id,
+        base_url=args.base_url,
+        agent_id=args.agent_id,
+    )
+
+
+def _make_config(args: argparse.Namespace, *, flush: bool = False, dry_run: bool = False) -> RunConfig:
+    return RunConfig(
+        agent_id=args.agent_id,
+        machine12=machine_id_short(),
+        fleet_id=args.fleet_id,
+        max_event_chars=getattr(args, "max_event_chars", 4_000),
+        max_windows=getattr(args, "max_windows", 8),
+        min_events=getattr(args, "min_events", 10),
+        flush=flush,
+        dry_run=dry_run,
+        verbose=args.verbose,
+    )
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    if error := _require_config(args):
+        print(f"[interviewer] {error}", file=sys.stderr)
+        return 2
+    allow = _resolve_allowlist(args)
+    if args.transcript is not None:
+        if not args.transcript.is_file():
+            print(f"[interviewer] no such transcript: {args.transcript}", file=sys.stderr)
+            return 2
+        # --transcript must not bypass the project allowlist — including
+        # the EMPTY-allowlist case (default-deny has no carve-outs; same
+        # pattern as _cmd_hook and the discovery path below).
+        project = args.transcript.parent.name
+        if not args.all_projects and not (allow and project_allowed(project, allow)):
+            print(
+                f"[interviewer] transcript project '{project}' not in allowlist; "
+                "pass --all-projects or --projects to opt in",
+                file=sys.stderr,
+            )
+            return 2
+        transcripts = [Transcript(path=args.transcript, project=project)]
+    else:
+        if not allow and not args.all_projects:
+            print(_deny_guidance(args), file=sys.stderr)
+            return 2
+        transcripts = find_transcripts(
+            root=args.projects_root,
+            allow_globs=allow,
+            since_hours=args.since_hours or None,
+            all_projects=args.all_projects,
+        )
+    if not transcripts:
+        print("[interviewer] nothing to do (no matching transcripts)")
+        return 0
+
+    lock = _acquire_lock()
+    if lock is None:
+        print("[interviewer] another run holds the lock; exiting", file=sys.stderr)
+        return 0
+    try:
+        cfg = _make_config(args, flush=args.flush, dry_run=args.dry_run)
+        with _make_client(args) as mc:
+            summary = run_all(mc, transcripts, cfg)
+    finally:
+        # Deterministic flock release: on non-CPython runtimes the ref-count
+        # drop is not prompt, and a lingering handle blocks the next
+        # cron/hook invocation until GC. (The Windows sentinel has no close.)
+        if hasattr(lock, "close"):
+            lock.close()
+
+    submitted = sum(f.windows_submitted for f in summary.files)
+    memories = sum(f.memories_written for f in summary.files)
+    print(
+        f"[interviewer] {len(summary.files)} file(s): {submitted} window(s) submitted, "
+        f"{memories} memories written"
+        + (" [dry-run]" if args.dry_run else "")
+    )
+    if summary.aborted:
+        return 2
+    if summary.failed_all:
+        return 1
+    return 0
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    if error := _require_config(args):
+        print(f"[interviewer] {error}", file=sys.stderr)
+        return 2
+    allow = _resolve_allowlist(args)
+    if not allow and not args.all_projects:
+        print(_deny_guidance(args), file=sys.stderr)
+        return 2
+    transcripts = find_transcripts(
+        root=args.projects_root,
+        allow_globs=allow,
+        since_hours=args.since_hours or None,
+        all_projects=args.all_projects,
+    )
+    machine12 = machine_id_short()
+    with _make_client(args) as mc:
+        for transcript in transcripts:
+            node_id = node_id_for(machine12, transcript.path)
+            try:
+                last_seq = read_watermark(mc, node_id)
+                # Inside the guard: the transcript can vanish between
+                # discovery and here (same TOCTOU as discovery's stat).
+                lines = count_lines(transcript.path)
+            except AuthError as exc:
+                print(f"[interviewer] ABORT: {exc}", file=sys.stderr)
+                return 2
+            except Exception as exc:  # noqa: BLE001 - one bad file must not kill status
+                print(
+                    f"{transcript.project}/{transcript.path.name}: status check failed: {exc}",
+                    file=sys.stderr,
+                )
+                continue
+            pending = max(0, lines - (last_seq + 1))
+            print(f"{transcript.project}/{transcript.path.name}: lines={lines} cursor={last_seq} pending={pending}")
+    return 0
+
+
+def _cmd_hook(args: argparse.Namespace) -> int:
+    """SessionEnd hook: read {transcript_path,...} JSON from stdin, drain
+    that one file. ALWAYS exit 0 — never fail the user's session."""
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+        transcript_path = Path(str(payload.get("transcript_path") or ""))
+        if not transcript_path.is_file():
+            return 0
+        allow = _resolve_allowlist(args)
+        project = transcript_path.parent.name
+        if not args.all_projects and not (allow and project_allowed(project, allow)):
+            # Warn so operators can tell a config gap from an empty
+            # session; exit code stays 0 (never fail the session hook).
+            print(
+                f"[interviewer] hook: project '{project}' not in allowlist; skipping "
+                "(set MEMCLAW_INTERVIEWER_PROJECTS or --all-projects)",
+                file=sys.stderr,
+            )
+            return 0
+        if error := _require_config(args):
+            print(f"[interviewer] hook: {error}; skipping", file=sys.stderr)
+            return 0
+        lock = _acquire_lock()
+        if lock is None:
+            return 0
+        try:
+            cfg = _make_config(args, flush=True)  # session over: drain the tail
+            with _make_client(args) as mc:
+                run_all(mc, [Transcript(path=transcript_path, project=project)], cfg)
+        finally:
+            if hasattr(lock, "close"):
+                lock.close()
+    except Exception as exc:  # noqa: BLE001 - hook must never fail the session
+        print(f"[interviewer] hook error (ignored): {exc}", file=sys.stderr)
+    return 0
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    args = _build_parser().parse_args(argv)
+    if args.command == "run":
+        return _cmd_run(args)
+    if args.command == "status":
+        return _cmd_status(args)
+    if args.command == "hook":
+        return _cmd_hook(args)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

memclaw_client/interviewer/discovery.py

@@ -0,0 +1,66 @@
+"""Transcript discovery under ~/.claude/projects with allowlist gating.
+
+Privacy posture (user-confirmed): DEFAULT-DENY. With no allowlist the CLI
+lists what it found and exits with guidance — transcripts can contain
+NDA/client work and pasted secrets across every project on the machine,
+and installing the tool is not consent to harvest all of them.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_PROJECTS_ROOT = Path.home() / ".claude" / "projects"
+
+
+@dataclass
+class Transcript:
+    path: Path
+    project: str  # project dir name (the slug)
+
+
+def list_project_dirs(root: Path = DEFAULT_PROJECTS_ROOT) -> list[str]:
+    if not root.is_dir():
+        return []
+    return sorted(p.name for p in root.iterdir() if p.is_dir())
+
+
+def project_allowed(project: str, allow_globs: list[str]) -> bool:
+    return any(fnmatch.fnmatch(project, glob) for glob in allow_globs)
+
+
+def find_transcripts(
+    *,
+    root: Path = DEFAULT_PROJECTS_ROOT,
+    allow_globs: list[str],
+    since_hours: Optional[float] = None,
+    all_projects: bool = False,
+) -> list[Transcript]:
+    """Enumerate top-level session ``.jsonl`` files in allowed projects.
+
+    Skips subagent transcripts (``<uuid>/subagents/``) and offloaded tool
+    results by construction — only files DIRECTLY under a project dir are
+    session transcripts. ``since_hours`` prefilters by mtime so steady-state
+    runs don't rescan months of history.
+    """
+    if not root.is_dir():
+        return []
+    cutoff = time.time() - since_hours * 3600 if since_hours else None
+    found: list[Transcript] = []
+    for project_dir in sorted(root.iterdir()):
+        if not project_dir.is_dir():
+            continue
+        if not all_projects and not project_allowed(project_dir.name, allow_globs):
+            continue
+        for path in sorted(project_dir.glob("*.jsonl")):
+            try:
+                if cutoff is not None and path.stat().st_mtime < cutoff:
+                    continue
+            except OSError:
+                continue  # deleted/renamed between glob and stat (TOCTOU)
+            found.append(Transcript(path=path, project=project_dir.name))
+    return found