elliot-stack 1.0.38 → 1.0.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elliot-stack",
-  "version": "1.0.38",
+  "version": "1.0.39",
   "description": "Elliot's skill stack for Claude Code — install via npx elliot-stack@latest",
   "bin": {
     "elliot-stack": "bin/install.cjs"

package/skills/estack-read-claude-session-history/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: estack-read-claude-session-history
-version: 1.1.0
+version: 1.2.1
 description: >-
   (read-claude-session-history) Invoke for ANY task involving Claude Code
   session history, transcripts, or .jsonl files - this is the only way to read,
@@ -96,6 +96,7 @@ What are you trying to do?
 │  ├─ One session ─────────────────────────────── --mode search --file …
 │  ├─ One project ─────────────────────────────── --mode search --cwd …
 │  ├─ All projects ────────────────────────────── --mode search --all-projects
+│  ├─ Expand a wide search to full windows ───── --full
 │  └─ Filter to user msgs / tool-use inputs ──── --role user --in tool_use
 │
 ├─ Forensics on a session
@@ -128,7 +129,7 @@ What are you trying to do?
 | `advisor` | `--file` | All `advisor_tool_result` payloads |
 | `pre-compact` | `--file` | 40 exchanges before the most recent `/compact` |
 | `dump` | `--file` | Human-readable dump (auto-degrades on transcripts >5MB) |
-| `search` | `--query` + scope | Matches windowed for context (supports `--role`, `--in text|tool_use|thinking|all`) |
+| `search` | `--query` + scope | Single file: full match windows. Wide scope (`--cwd`/`--project`/`--all-projects`): per-session summary by default; `--full` expands to windows. Either way the full view is bounded by a char budget and degrades back to a summary (with a note) if it would overflow. Supports `--role`, `--in text\|tool_use\|tool_result\|thinking\|all` |
 | `debug` | `--file` | Entry/block type distributions + probes |
 | `brief` | `--file` | 6-line summary: uuid·project·mtime·status / intent / last / edits / tools / subagents |
 | `list` | `--cwd` or `--all-projects` | Rich table: mtime, size, uuid, msg count, flags, status, title |
@@ -157,6 +158,7 @@ What are you trying to do?
 - `--all-projects` — walk every project under `--root`.
 - `--project <name>` — filter projects by name substring, case-insensitive, matches encoded or decoded form (`--project keel`, `--project "Other Claude Code"`). Works on `list`, `journal`, `search`, `count`, `find`, `timeline`, `engagement`, `tool-usage`. Use this instead of `--cwd` when you know the project's name but not its exact path. (Note: for `engagement`, scope filters which sessions are *reported* — the attention stream is always computed across all projects so parallel chats never double-count.)
 - `--file <path>` — single-session scope.
+- `--full` — for wide-scope `search` (`--cwd`/`--project`/`--all-projects`), expand the default per-session summary into full match windows. Single-file searches (`--file`) are always full and ignore this flag. In every case the full view is bounded by a character budget (~10k tokens); if the windows would overflow it, the output degrades back to the summary with a note.
 - `--since <spec>` / `--until <spec>` — accepts ISO date, ISO datetime, relative (`30m`, `24h`, `7d`, `1w`, `1mo`), named (`today`, `yesterday`, `now`).
 - `--date <spec>` — single-day window for `timeline` (`--date yesterday`, `--date 2026-06-01`).
 - `--gap <spec>` — idle-gap threshold for `timeline` blocks (`15m` default, `1h`).

package/skills/estack-read-claude-session-history/references/modes.md

@@ -15,6 +15,7 @@ python read_transcript.py [--root <root>] [--cwd <path> | --all-projects | --pro
 ```
 
 Global flag notes:
+- `--since <spec>` / `--until <spec>` — the time window is half-open `[since, until)`: `since` is inclusive, `until` is exclusive, so an event stamped exactly at `--until` is not included. This holds for every message-level mode (`search`, `timeline`, `engagement`, `tool-usage`). Session-level modes (`list`, `journal`, `count`) instead filter whole sessions by file mtime, so a session last written at or before `--until` is shown.
 - `--project <name>` — case-insensitive substring filter on project directory names (encoded or decoded form). Applies to `list`, `journal`, `search`, `count`, `find`, `timeline`, `engagement`, `tool-usage`. Exit 1 when nothing matches.
 - `--tz <spec>` — display timezone: IANA name (`America/New_York`), `UTC`, or fixed offset (`+5`, `-4`, `+05:30`, `UTC-4`). Default is system local time. All displayed timestamps AND `--since/--until/--date` interpretation use this zone.
 - `--format json` (alias `--json`) — structured output on every mode except the legacy `--list`/`--list-subagents` aliases. Shapes per mode are listed below.
@@ -188,17 +189,27 @@ python read_transcript.py --cwd <path> --mode search --query "<q>"
 
 # All projects
 python read_transcript.py --all-projects --mode search --query "<q>"
+
+# Expand a wide search to full match windows
+python read_transcript.py --all-projects --mode search --query "<q>" --full
 ```
 
 Flags:
 - `--role {user,assistant,both}` (default `both`)
-- `--in {text,tool_use,thinking,all}` (default `text`)
+- `--in {text,tool_use,tool_result,thinking,all}` (default `text`)
+- `--full` — wide scope only (see Output below)
 - `--since` / `--until`
 
 `--in tool_use` searches the `name + JSON-stringified input` of every `tool_use` block — useful for finding "the session where I ran `git push --force`".
 
 `--in thinking` searches `thinking` blocks (model reasoning).
 
+`--in tool_result` searches the text content of `tool_result` blocks (what tools returned). `--in all` covers text + tool_use + tool_result + thinking.
+
+**Output.** A single-file search (`--file`) prints full match windows. A wide search (`--cwd` / `--project` / `--all-projects`) prints a **per-session summary** by default — one line per session (`mtime · uuid8 · project · hit-count · first snippet`), sorted newest first, with a header counting total hits and sessions. This keeps cross-project searches well under the harness's ~25k-token Read cap instead of dumping tens of thousands of tokens that the reader then refuses. Add `--full` to expand a wide search into full windows. In every case the full view (single-file, or wide + `--full`) is bounded by a character budget (~10k tokens) and degrades back to the summary with a note if it would overflow — so even a single huge session can't blow the Read cap. Sessions past the 200-line summary cap are counted in a footer, never silently dropped. JSON mirrors this: wide scope returns compact per-session metadata (`uuid`, `project`, `hits`, `first_snippet`) by default, full per-match objects (with `window`) under `--full`.
+
+Progress (`Searching i/N…`) prints to stderr only when stderr is an interactive terminal — captured/piped runs stay clean.
+
 ### `count`
 
 Count sessions matching a query.
@@ -434,7 +445,7 @@ Output is prefixed `A>` / `B>` (or with subagent id shorts).
 | `tool-calls` / `subagent-tools` | `[{timestamp, tool, summary, input}]` |
 | `tool-usage` | `{total, sessions, tools: [{tool, count}], skills: [{skill, count}]}` |
 | `file-edits` / `subagent-files` | `[{path, ops}]` |
-| `search` | `[{session, mtime_iso, role, where, timestamp, window}]` |
+| `search` | single-file or `--full`: `[{session, mtime_iso, role, where, timestamp, window}]`; wide scope default: `[{session, uuid, project, mtime_iso, hits, first_snippet}]` |
 | `count` | `{sessions, messages, matches}` |
 | `subagent-list` | `[{id, agentType, description, path, size_kb, mtime_iso}]` |
 | `subagent-finals` | `[{id, agentType, text}]` |

package/skills/estack-read-claude-session-history/scripts/lib/parser.py

@@ -282,9 +282,10 @@ def filter_by_time(
         # Strip tzinfo for naive comparison
         if ts.tzinfo is not None:
             ts = ts.replace(tzinfo=None)
+        # Half-open window [since, until): since inclusive, until exclusive.
         if since is not None and ts < since:
             continue
-        if until is not None and ts > until:
+        if until is not None and ts >= until:
             continue
         out.append(m)
     return out

package/skills/estack-read-claude-session-history/scripts/lib/search.py

@@ -70,6 +70,16 @@ def _entry_search_text(obj: dict, in_channel: str) -> list[tuple[str, str]]:
     return out
 
 
+def _show_progress(progress: bool) -> bool:
+    """Progress is for a live terminal only.
+
+    When stderr is captured to a file or pipe (e.g. by a tool harness), the
+    per-file ``Searching i/N…\\r`` stream lands as hundreds of literal lines and
+    inflates the captured output. Suppress it unless stderr is an interactive TTY.
+    """
+    return progress and sys.stderr.isatty()
+
+
 def _window(text: str, q: str, n: int = 200) -> str:
     """Return up to n chars of context around the first match of q."""
     if not text or not q:
@@ -90,7 +100,7 @@ def search_session(
     path: Path,
     query: str,
     role: Literal["user", "assistant", "both"] = "both",
-    in_channel: Literal["text", "tool_use", "thinking", "all"] = "text",
+    in_channel: Literal["text", "tool_use", "tool_result", "thinking", "all"] = "text",
     since: datetime | None = None,
     until: datetime | None = None,
 ) -> list[Match]:
@@ -117,9 +127,10 @@ def search_session(
                 continue
             if ts_dt.tzinfo is not None:
                 ts_dt = ts_dt.replace(tzinfo=None)
+            # Half-open window [since, until): since inclusive, until exclusive.
             if since is not None and ts_dt < since:
                 continue
-            if until is not None and ts_dt > until:
+            if until is not None and ts_dt >= until:
                 continue
         for where, text in _entry_search_text(obj, in_channel):
             if q in text.lower():
@@ -138,15 +149,19 @@ def search_project(
     project_dir: Path,
     query: str,
     role: Literal["user", "assistant", "both"] = "both",
-    in_channel: Literal["text", "tool_use", "thinking", "all"] = "text",
+    in_channel: Literal["text", "tool_use", "tool_result", "thinking", "all"] = "text",
     since: datetime | None = None,
     until: datetime | None = None,
     progress: bool = True,
 ) -> Iterator[Match]:
     """Search every transcript in a project directory, newest first."""
-    files = _paths.list_transcripts(project_dir, since=since, until=until)
+    # Filter files by mtime >= since only. A session last written after `until`
+    # may still contain messages inside the window, so we don't bound file mtime
+    # above — search_session() applies the `until` cut per-message instead.
+    files = _paths.list_transcripts(project_dir, since=since)
+    show = _show_progress(progress)
     for i, f in enumerate(files, 1):
-        if progress:
+        if show:
             print(
                 f"Searching {i}/{len(files)}: {f.name}...",
                 file=sys.stderr,
@@ -156,8 +171,11 @@ def search_project(
             for m in search_session(f, query, role, in_channel, since, until):
                 yield m
         except Exception as e:
-            print(f"\nError reading {f.name}: {e}", file=sys.stderr)
-    if progress:
+            # Lead with \n only to clear an active \r progress line; when progress
+            # is suppressed there's no line to clear, so don't add a blank one.
+            prefix = "\n" if show else ""
+            print(f"{prefix}Error reading {f.name}: {e}", file=sys.stderr)
+    if show:
         print(file=sys.stderr)
 
 
@@ -165,14 +183,14 @@ def search_all_projects(
     root: Path,
     query: str,
     role: Literal["user", "assistant", "both"] = "both",
-    in_channel: Literal["text", "tool_use", "thinking", "all"] = "text",
+    in_channel: Literal["text", "tool_use", "tool_result", "thinking", "all"] = "text",
     since: datetime | None = None,
     until: datetime | None = None,
     progress: bool = True,
 ) -> Iterator[Match]:
     """Walk every project directory under root."""
     for project_dir in _paths.list_projects(root):
-        if progress:
+        if _show_progress(progress):
             print(f"--- {project_dir.name} ---", file=sys.stderr)
         yield from search_project(
             project_dir, query, role, in_channel, since, until, progress

package/skills/estack-read-claude-session-history/scripts/read_transcript.py

@@ -33,6 +33,16 @@ from lib import search as S  # noqa: E402
 from lib import subagents as SA  # noqa: E402
 
 
+# Wide-scope search output budget. Full match windows across many sessions can
+# balloon past the harness's ~25k-token Read cap, forcing a write-then-can't-read
+# round trip. We summarize by default and degrade --full back to a summary once
+# the rendered text would exceed this many characters (~10k tokens at ~4 ch/tok).
+SEARCH_CHAR_BUDGET = 40_000
+# Cap session lines in the summary view so the summary itself stays bounded.
+# Overflow is counted and noted, never silently dropped.
+SEARCH_SUMMARY_SESSION_CAP = 200
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Legacy mode implementations (kept byte-identical to v1 for backwards-compat)
 # ─────────────────────────────────────────────────────────────────────────────
@@ -107,24 +117,6 @@ def mode_dump(lines, limit=80):
     return "\n\n".join(output)
 
 
-def mode_search_legacy(lines, query: str):
-    """Legacy single-file search: assistant text only, case-insensitive."""
-    messages = PR.get_messages(lines)
-    results = []
-    q = query.lower()
-    for m in messages:
-        if m["role"] == "assistant":
-            combined = " ".join(m["texts"])
-            if q in combined.lower():
-                results.append(combined)
-    if not results:
-        return None
-    output = [f"=== {len(results)} match(es) for '{query}' ===\n"]
-    for i, r in enumerate(results, 1):
-        output.append(f"--- Match #{i} ---\n{r[:1500]}")
-    return "\n\n".join(output)
-
-
 def mode_debug(lines):
     output = []
     type_counts: dict[str, int] = {}
@@ -579,6 +571,81 @@ def mode_tool_calls(path: Path, tool_filter: set[str] | None, fmt: str = "text")
     return "\n".join(out).lstrip("\n")
 
 
+def _one_line(text: str, n: int) -> str:
+    """Collapse whitespace to a single line and truncate to n chars."""
+    s = " ".join((text or "").split())
+    return s[:n] + ("…" if len(s) > n else "")
+
+
+def _sessions_by_mtime(matches) -> list:
+    """Group matches by session, return (session_path, matches) sorted newest first."""
+    by_session: dict[Path, list] = {}
+    for m in matches:
+        by_session.setdefault(m.session_path, []).append(m)
+    return sorted(by_session.items(), key=lambda kv: kv[1][0].mtime, reverse=True)
+
+
+def _render_search_full(matches) -> str:
+    """Full per-match windows grouped by session, newest first (the detailed view)."""
+    out = []
+    for sp, ms in _sessions_by_mtime(matches):
+        out.append(f"{'=' * 60}\nSession: {sp.name}  ({_fmt_mtime(ms[0].mtime)})\n{'=' * 60}")
+        for i, m in enumerate(ms, 1):
+            label = f"--- Match #{i} [{m.role}/{m.where}] ---"
+            out.append(f"{label}\n{m.window_text[:1500]}")
+    return "\n\n".join(out)
+
+
+def _render_search_summary(query: str, matches, already_full: bool = False) -> str:
+    """One line per session: mtime · uuid8 · project · hits · first snippet.
+
+    Every hit is counted in the header; sessions past the cap are counted in a
+    footer note, never silently dropped. When ``already_full`` is set (the
+    summary is a degraded ``--full`` result), the footer drops the "use --full"
+    suggestion the caller already tried.
+    """
+    sessions = _sessions_by_mtime(matches)
+    total_hits = len(matches)
+    total_sessions = len(sessions)
+    shown = sessions[:SEARCH_SUMMARY_SESSION_CAP]
+    hit_w = "match" if total_hits == 1 else "matches"
+    sess_w = "session" if total_sessions == 1 else "sessions"
+    lines = [f'=== "{query}": {total_hits} {hit_w} across {total_sessions} {sess_w} ===']
+    for sp, ms in shown:
+        uuid8 = sp.stem[:8]
+        project = P.decode_project_name(sp.parent.name)
+        snippet = _one_line(ms[0].window_text, 120)
+        n = len(ms)
+        # Pad the unit so singular ("hit ") and plural ("hits") align the snippet column.
+        hits = f'{n:>4} hit' + ('s' if n != 1 else ' ')
+        lines.append(f'{_fmt_mtime(ms[0].mtime)}  {uuid8}  {project[:28]:<28}  {hits}  · "{snippet}"')
+    if total_sessions > len(shown):
+        lines.append(
+            f"… and {total_sessions - len(shown)} more session(s) not shown — "
+            f"narrow with --project or a tighter --query."
+        )
+    # On a degrade (already_full) the [note] prefix already carries the actionable
+    # hint, so don't append a second — possibly conflicting — guidance line.
+    if not already_full:
+        lines.append("Use --full for match windows, or narrow with --project / a tighter --query.")
+    return "\n".join(lines)
+
+
+def _search_summary_json(matches) -> list:
+    """Compact per-session metadata (no windows) for structured consumers."""
+    return [
+        {
+            "session": str(sp),
+            "uuid": sp.stem,
+            "project": P.decode_project_name(sp.parent.name),
+            "mtime_iso": _fmt_mtime(ms[0].mtime),
+            "hits": len(ms),
+            "first_snippet": _one_line(ms[0].window_text, 120),
+        }
+        for sp, ms in _sessions_by_mtime(matches)
+    ]
+
+
 def mode_search_v2(
     root: Path,
     cwd: str | None,
@@ -593,6 +660,7 @@ def mode_search_v2(
     fmt: str = "text",
     exclude_current: bool = False,
     current_uuid: str | None = None,
+    full: bool = False,
 ):
     """Cross-scope search with role/in-channel filters."""
     matches: list = []
@@ -607,12 +675,21 @@ def mode_search_v2(
         pd = P.find_project_dir(cwd, root)
         matches = list(S.search_project(pd, query, role, in_channel, since, until))
     else:
-        return "Provide --file, --cwd, --project, or --all-projects"
+        # Unreachable from the CLI (the dispatch guarantees a scope flag), but keep
+        # the direct-call contract honest: JSON callers get a JSON object.
+        msg = "Provide --file, --cwd, --project, or --all-projects"
+        return {"error": msg} if fmt == "json" else msg
 
     if exclude_current and current_uuid:
         matches = [m for m in matches if m.session_path.stem != current_uuid]
 
+    # Single-file scope is narrow and won't overflow — render full by default.
+    # Wide scope (cwd / project / all-projects) summarizes unless --full is set.
+    wide = file_path is None
+
     if fmt == "json":
+        if wide and not full:
+            return _search_summary_json(matches)
         return [
             {
                 "session": str(m.session_path),
@@ -628,17 +705,25 @@ def mode_search_v2(
     if not matches:
         return f"No matches for '{query}'."
 
-    # Group by session for readable output
-    by_session: dict[Path, list] = {}
-    for m in matches:
-        by_session.setdefault(m.session_path, []).append(m)
-    out = []
-    for sp, ms in by_session.items():
-        out.append(f"\n{'=' * 60}\nSession: {sp.name}  ({_fmt_mtime(ms[0].mtime)})\n{'=' * 60}")
-        for i, m in enumerate(ms, 1):
-            label = f"--- Match #{i} [{m.role}/{m.where}] ---"
-            out.append(f"{label}\n{m.window_text[:1500]}")
-    return "\n\n".join(out)
+    if wide and not full:
+        return _render_search_summary(query, matches)
+
+    # Full render (single-file, or wide + --full), bounded by the char budget so
+    # the output never exceeds what the reader accepts. Degrade to summary if it would.
+    full_text = _render_search_full(matches)
+    if len(full_text) > SEARCH_CHAR_BUDGET:
+        # Ceiling-round the size so it always reads as strictly over the budget.
+        size_k = (len(full_text) + 999) // 1000
+        if wide:
+            hint = "Use a tighter --query / --role / --in, or --file <session> to read one session in full."
+        else:
+            hint = "This one session has many matches; use a tighter --query / --role / --in to narrow."
+        note = (
+            f"[note: full output is ~{size_k}K chars (> "
+            f"{SEARCH_CHAR_BUDGET // 1000}K budget) — showing a summary instead. {hint}]"
+        )
+        return note + "\n" + _render_search_summary(query, matches, already_full=True)
+    return full_text
 
 
 def mode_subagent_list(path: Path, fmt: str = "text"):
@@ -774,9 +859,10 @@ def _tally_tool_usage(
                         continue
                     if ts.tzinfo is not None:
                         ts = ts.replace(tzinfo=None)
+                    # Half-open window [since, until): since inclusive, until exclusive.
                     if since is not None and ts < since:
                         continue
-                    if until is not None and ts > until:
+                    if until is not None and ts >= until:
                         continue
                 name = c["name"] or "(unknown)"
                 tool_counts[name] = tool_counts.get(name, 0) + 1
@@ -1509,6 +1595,9 @@ def build_parser() -> argparse.ArgumentParser:
 
     # Mode-specific flags
     p.add_argument("--query", help="Search query (for search/count modes)")
+    p.add_argument("--full", action="store_true",
+                   help="Wide-scope search: expand to full match windows instead of "
+                        "the per-session summary (bounded; degrades back to summary if oversized)")
     p.add_argument("--uuid", help="UUID prefix (for lookup/resume-cmd modes)")
     p.add_argument("--title", help="Title substring (for find mode)")
     p.add_argument("--first-prompt", dest="first_prompt", help="First-prompt substring (for find mode)")
@@ -1590,40 +1679,6 @@ def main() -> int:
     since = _resolve_time(args.since)
     until = _resolve_time(args.until)
 
-    # Legacy --mode search with --cwd (no --file) preserved byte-for-byte.
-    if args.mode == "search" and args.cwd and not args.file and not args.all_projects \
-            and not args.project and fmt == "text" \
-            and args.role == "both" and args.in_channel == "text":
-        if not args.query:
-            print("--query required with --mode search", file=sys.stderr)
-            return 1
-        files = P.list_transcripts(P.find_project_dir(args.cwd, root))
-        if not files:
-            print("No transcript files found.")
-            return 0
-        total_matches = 0
-        for i, f in enumerate(files, 1):
-            print(f"Searching {i}/{len(files)}: {f.name}...", file=sys.stderr, end="\r")
-            try:
-                lines = PR.parse_lines(f)
-                result = mode_search_legacy(lines, args.query)
-            except Exception as e:
-                print(f"\nError reading {f.name}: {e}", file=sys.stderr)
-                continue
-            if result is not None:
-                mtime = _fmt_mtime(f.stat().st_mtime)
-                print(f"\n{'=' * 60}")
-                print(f"Session: {f.name}  ({mtime})")
-                print("=" * 60)
-                print(result)
-                total_matches += 1
-        print(file=sys.stderr)
-        if total_matches == 0:
-            print(f"No matches for '{args.query}' found across {len(files)} session(s).")
-        else:
-            print(f"\n--- Found matches in {total_matches}/{len(files)} session(s) ---")
-        return 0
-
     mode = args.mode
 
     # Discovery modes — don't need --file
@@ -1769,8 +1824,8 @@ def main() -> int:
             return 1
         _emit(mode_diff(Path(args.file_a), Path(args.file_b), fmt=fmt))
         return 0
-    # (cwd-scoped searches with non-default role/in/json land here — the
-    # byte-compat legacy path above already handled the default-flag case.)
+    # All scoped searches (--file / --cwd / --project / --all-projects) route here.
+    # Wide scope summarizes by default; --full expands to bounded match windows.
     if mode == "search" and (args.file or args.all_projects or args.project or args.cwd):
         if not args.query:
             print("--query required", file=sys.stderr)
@@ -1780,8 +1835,12 @@ def main() -> int:
                              args.role, args.in_channel, since, until,
                              project=args.project, fmt=fmt,
                              exclude_current=args.exclude_current,
-                             current_uuid=current_uuid))
+                             current_uuid=current_uuid, full=args.full))
         return 0
+    if mode == "search":
+        # Reached only when no scope flag was given — search needs one of these.
+        print("search requires --file, --cwd, --project, or --all-projects", file=sys.stderr)
+        return 1
 
     # File-required modes
     if mode == "subagent-tools":
@@ -1874,13 +1933,6 @@ def main() -> int:
             if args.include_subagents:
                 body += _append_subagents(path)
             print(body)
-    elif mode == "search":
-        if not args.query:
-            print("--query required with --mode search", file=sys.stderr)
-            return 1
-        result = mode_search_legacy(lines, args.query)
-        print(result if result is not None
-              else f"No assistant messages containing '{args.query}' found.")
     elif mode == "debug":
         print(mode_debug(lines))
 

package/skills/estack-read-claude-session-history/scripts/tests/test_parser.py

@@ -1,7 +1,7 @@
 """Tests for lib.parser."""
 
 import json
-from datetime import datetime
+from datetime import datetime, timedelta
 from pathlib import Path
 
 import pytest
@@ -132,6 +132,15 @@ def test_filter_by_time(fixtures_dir):
     )
 
 
+def test_filter_by_time_until_is_exclusive():
+    # Half-open [since, until): a message stamped exactly at `until` is excluded.
+    # Derive the bound from the parser so the test is timezone-independent.
+    msgs = [{"timestamp": "2026-05-01T10:00:00Z"}]
+    at = PR._parse_timestamp(msgs[0]["timestamp"])
+    assert PR.filter_by_time(msgs, since=None, until=at) == []
+    assert PR.filter_by_time(msgs, since=None, until=at + timedelta(seconds=1)) == msgs
+
+
 def test_truncated_line_dropped(fixtures_dir, capsys):
     # Should not raise, and warning should be on stderr
     lines = _load(fixtures_dir, "truncated.jsonl")

package/skills/estack-read-claude-session-history/scripts/tests/test_search.py

@@ -1,8 +1,9 @@
 """Tests for lib.search."""
 
-from datetime import datetime
+from datetime import datetime, timedelta
 from pathlib import Path
 
+from lib import parser as PR
 from lib import search as S
 
 
@@ -67,6 +68,21 @@ def test_search_with_time_filter(fixtures_dir):
     assert matches == []
 
 
+def test_search_until_is_exclusive(fixtures_dir):
+    # The "Hello" user message is stamped 2026-05-01T10:00:00Z. Derive the bound
+    # from the parser (it converts to local naive time) so this is tz-independent.
+    # Half-open [since, until): until at that instant excludes it; one second later includes it.
+    at = PR._parse_timestamp("2026-05-01T10:00:00Z")
+    assert S.search_session(
+        fixtures_dir / "basic-session.jsonl", "Hello", role="both", until=at
+    ) == []
+    # "Hello" matches only the user message at the boundary instant, so +1s yields exactly 1.
+    assert len(S.search_session(
+        fixtures_dir / "basic-session.jsonl", "Hello", role="both",
+        until=at + timedelta(seconds=1)
+    )) == 1
+
+
 def test_search_project(fixtures_dir, tmp_path):
     # Copy 2 fixtures into a fake project dir and search
     import shutil

package/skills/estack-read-claude-session-history/scripts/tests/test_search_output.py

@@ -0,0 +1,161 @@
+"""Tests for cross-scope search output budgeting: summary-by-default, --full,
+the char-budget degrade, and TTY-gated progress."""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+import read_transcript as RT
+from lib.search import Match
+
+
+def _run_cli(cli_path, *args):
+    env = dict(os.environ)
+    env["PYTHONIOENCODING"] = "utf-8"
+    return subprocess.run(
+        [sys.executable, str(cli_path), *args],
+        capture_output=True, text=True, encoding="utf-8", env=env,
+    )
+
+
+# A realistic epoch base so _fmt_mtime renders sane dates if output is printed.
+_BASE_MTIME = 1_700_000_000
+
+
+def _mk(stem, project, mtime, window, role="assistant", where="text"):
+    sp = Path("/root") / project / f"{stem}.jsonl"
+    return Match(session_path=sp, mtime=mtime, role=role, where=where,
+                 timestamp=None, window_text=window)
+
+
+@pytest.fixture
+def wide_root(fixtures_dir, tmp_path):
+    """A fake projects root with two projects, each holding a session."""
+    root = tmp_path / "projects"
+    keel = root / "C--Users-x-Keel-Project"
+    other = root / "C--Users-x-Other-Claude-Code"
+    keel.mkdir(parents=True)
+    other.mkdir(parents=True)
+    shutil.copy(fixtures_dir / "basic-session.jsonl", keel / "keelsession.jsonl")
+    shutil.copy(fixtures_dir / "basic-session.jsonl", other / "othersession.jsonl")
+    return root
+
+
+# ── unit: renderers ──────────────────────────────────────────────────────────
+
+def test_one_line_collapses_and_truncates():
+    assert RT._one_line("a\n  b   c", 100) == "a b c"
+    assert RT._one_line("x" * 200, 10) == "x" * 10 + "…"
+    assert RT._one_line("", 10) == ""
+
+
+def test_summary_counts_all_hits_and_orders_newest_first():
+    matches = [
+        _mk("aaaaaaaa11", "C--Users-x-Proj", _BASE_MTIME, "hello world"),
+        _mk("aaaaaaaa11", "C--Users-x-Proj", _BASE_MTIME, "hello again"),
+        _mk("bbbbbbbb22", "C--Users-x-Proj", _BASE_MTIME + 100, "hello there"),
+    ]
+    out = RT._render_search_summary("hello", matches)
+    assert '"hello": 3 matches across 2 sessions' in out
+    assert "2 hits" in out  # the aaaa session has 2
+    # bbbb (BASE+100, newer) sorts before aaaa (BASE, older) — newest first
+    assert out.index("bbbbbbbb") < out.index("aaaaaaaa")
+    assert "--- Match #" not in out  # no full windows in summary
+
+
+def test_summary_caps_sessions_but_counts_all(monkeypatch):
+    monkeypatch.setattr(RT, "SEARCH_SUMMARY_SESSION_CAP", 2)
+    matches = [_mk(f"sess{i:04d}xx", "C--Users-x-Proj", _BASE_MTIME + i, "hit") for i in range(5)]
+    out = RT._render_search_summary("hit", matches)
+    assert "5 matches across 5 sessions" in out  # header counts everything
+    assert "3 more session" in out  # 5 total - 2 shown
+
+
+def test_search_summary_json_has_no_windows():
+    matches = [_mk("aaaaaaaa11", "C--Users-x-My-Proj", _BASE_MTIME, "hello world snippet")]
+    js = RT._search_summary_json(matches)
+    assert js[0]["uuid"] == "aaaaaaaa11"
+    assert js[0]["hits"] == 1
+    assert "window" not in js[0]
+    assert js[0]["first_snippet"] == "hello world snippet"
+
+
+def test_single_file_full_degrades_to_summary_when_oversized(monkeypatch, fixtures_dir):
+    # Even a single-file search degrades if its full windows exceed the budget.
+    monkeypatch.setattr(RT, "SEARCH_CHAR_BUDGET", 10)
+    out = RT.mode_search_v2(
+        root=Path("."), cwd=None, all_projects=False,
+        file_path=fixtures_dir / "basic-session.jsonl",
+        query="Hello", role="both", in_channel="text",
+        since=None, until=None, fmt="text",
+    )
+    assert out.startswith("[note: full output")
+    assert '"Hello":' in out  # summary header is appended after the note
+
+
+def test_wide_full_degrades_to_summary_when_oversized(monkeypatch, wide_root):
+    # The advertised path: wide scope + --full, oversized, degrades to summary.
+    monkeypatch.setattr(RT, "SEARCH_CHAR_BUDGET", 10)
+    out = RT.mode_search_v2(
+        root=wide_root, cwd=None, all_projects=True, file_path=None,
+        query="Hello", role="both", in_channel="text",
+        since=None, until=None, fmt="text", full=True,
+    )
+    assert out.startswith("[note: full output")
+    assert "matches across" in out  # summary header appended
+    assert "--- Match #" not in out  # degraded — no windows survive
+
+
+# ── CLI: end-to-end ──────────────────────────────────────────────────────────
+
+def test_wide_search_summarizes_by_default(cli_path, wide_root):
+    r = _run_cli(cli_path, "--root", str(wide_root), "--mode", "search",
+                 "--query", "Hello", "--all-projects")
+    assert r.returncode == 0
+    assert '"Hello":' in r.stdout and "matches across" in r.stdout  # real summary header
+    assert "--- Match #" not in r.stdout  # summary, not windows
+
+
+def test_wide_search_full_shows_windows(cli_path, wide_root):
+    r = _run_cli(cli_path, "--root", str(wide_root), "--mode", "search",
+                 "--query", "Hello", "--all-projects", "--full")
+    assert r.returncode == 0
+    assert "--- Match #" in r.stdout  # full windows present
+
+
+def test_progress_suppressed_when_stderr_not_a_tty(cli_path, wide_root):
+    # stderr is captured (not a TTY) — the Searching i/N progress must not appear.
+    r = _run_cli(cli_path, "--root", str(wide_root), "--mode", "search",
+                 "--query", "Hello", "--all-projects")
+    assert "Searching" not in r.stderr
+
+
+def test_cwd_search_matches_user_messages(cli_path, wide_root):
+    # "Hello" lives only in the user message of basic-session.jsonl. A --cwd
+    # search now routes through mode_search_v2 (role=both), so it must be found —
+    # the old assistant-only --cwd path would have missed it.
+    found = _run_cli(cli_path, "--root", str(wide_root), "--mode", "search",
+                     "--query", "Hello", "--cwd", "Keel")
+    assert found.returncode == 0
+    assert '"Hello":' in found.stdout and "across" in found.stdout
+    assert "keelsess" in found.stdout
+
+    # Restricting to assistant role excludes the user-only hit.
+    asst = _run_cli(cli_path, "--root", str(wide_root), "--mode", "search",
+                    "--query", "Hello", "--cwd", "Keel", "--role", "assistant")
+    assert asst.returncode == 0
+    assert "No matches" in asst.stdout
+
+
+def test_json_role_filter_excludes_user_only_match(cli_path, wide_root):
+    # JSON path honors --role too: assistant-only over a user-only term → empty list.
+    r = _run_cli(cli_path, "--root", str(wide_root), "--mode", "search",
+                 "--query", "Hello", "--cwd", "Keel",
+                 "--role", "assistant", "--format", "json")
+    assert r.returncode == 0
+    assert json.loads(r.stdout) == []

package/skills/estack-read-claude-session-history/scripts/tests/test_timezone_and_project.py

@@ -186,11 +186,24 @@ def test_cli_list_project_filter(cli_path, multi_root):
 
 
 def test_cli_search_project_filter(cli_path, multi_root):
+    # Wide scope summarizes by default: the session shows as its uuid8 prefix,
+    # and the off-project session must not appear.
     r = _run_cli(
         cli_path, "--root", str(multi_root), "--mode", "search",
         "--query", "help", "--project", "keel",
     )
     assert r.returncode == 0
+    assert "keelsess" in r.stdout
+    assert "othersess" not in r.stdout
+
+
+def test_cli_search_project_filter_full(cli_path, multi_root):
+    # --full expands to match windows, which include the full session filename.
+    r = _run_cli(
+        cli_path, "--root", str(multi_root), "--mode", "search",
+        "--query", "help", "--project", "keel", "--full",
+    )
+    assert r.returncode == 0
     assert "keelsession" in r.stdout