elliot-stack 1.0.38 → 1.0.40

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: estack-migrate-claude-session-history
-version: 1.0.1
+version: 1.0.2
 description: >-
   (migrate-claude-session-history) Use whenever the user wants to move a Claude
   Code session (the .jsonl transcript plus its subagent sidecar files) from one
@@ -204,7 +204,8 @@ These are the failure modes that have actually happened — read `references/tro
 
 - `scripts/migrate-claude-history.js` — the migration script. Supports full-project and single-session modes, CLI overrides for old/new repo, auto-append of the migration note (on by default), `--no-migration-note` opt-out, and `--dry-run`. Run `node scripts/migrate-claude-history.js --help` for the full CLI.
 - `scripts/validate-migration.py` — post-migration validator. Runs structural, schema, path-consistency, sidecar, and (optional) backup-cross-validation checks on a migrated `.jsonl`. Exits 0 if every check passes, 1 otherwise. Run `python scripts/validate-migration.py --help` for the full CLI. Use this in step 7 instead of writing ad-hoc Python.
-- `scripts/test-append-note.js` — a self-contained smoke test for the note-append routine. Run with `node scripts/test-append-note.js`. Useful if you edit the migration script and want to sanity-check the duplicate-detection and non-meta entry shape.
+- `tests/estack-migrate-claude-session-history/test-append-note.js` — smoke test for the note-append routine (path relative to repo root). Run with `node tests/estack-migrate-claude-session-history/test-append-note.js` from the repo root. Useful if you edit the migration script and want to sanity-check the duplicate-detection and non-meta entry shape.
+- `tests/estack-migrate-claude-session-history/test-validate-migration.py` — self-test for the validator (path relative to repo root). Runs 27 synthetic cases covering every check. Run with `python tests/estack-migrate-claude-session-history/test-validate-migration.py` from the repo root. Exit 0 on full pass, 1 if any case fails.
 - `references/path-encoding.md` — the 9 path-encoding variants, why each exists, which entries use which form.
 - `references/troubleshooting.md` — recoveries for stale-reference false positives, missed sidecars, ambiguous lookups, and the true-stale grep recipe.
 ---

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.3.0
 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,
@@ -60,6 +60,12 @@ python "$PY" --mode timeline --date yesterday
 # How much focused time did today actually consume? (your attention, not Claude's)
 python "$PY" --mode engagement --date today
 
+# Per-session "what did I do" report — one block each: active+ran time, you/assistant
+# message counts, intent, last message. The whole "review my day" answer in one call.
+python "$PY" --mode session-report --date yesterday
+# Scope to part of a day with --since/--until (omit --date — date wins over since):
+python "$PY" --mode session-report --since "2026-06-19 19:00" --until "2026-06-20 00:00"
+
 # Any mode as structured JSON for piping into the next step
 python "$PY" --mode list --project keel --since 7d --format json
 ```
@@ -96,7 +102,8 @@ What are you trying to do?
 │  ├─ One session ─────────────────────────────── --mode search --file …
 │  ├─ One project ─────────────────────────────── --mode search --cwd …
 │  ├─ All projects ────────────────────────────── --mode search --all-projects
-│  └─ Filter to user msgs / tool-use inputs ──── --role user --in tool_use
+│  ├─ Expand a wide search to full windows ───── --full
+│  └─ Filter by role / content channel ──────── --role user --in tool_use|tool_result|thinking|all
 │
 ├─ Forensics on a session
 │  ├─ Chronological tool-call log ────────────── --mode changelog
@@ -110,6 +117,7 @@ What are you trying to do?
 │  └─ Forensics on one subagent ──────────────── --mode subagent-tools|subagent-files --subagent …
 │
 ├─ Cross-cutting reporting
+│  ├─ "What did I do, per session?" (day review) ─ --mode session-report --date … | --since/--until …
 │  ├─ "What did I do this week?" ──────────────── --mode journal --since 7d
 │  ├─ "What was I doing, when?" / day map ─────── --mode timeline --date yesterday
 │  ├─ "How long did X actually take ME?" ──────── --mode engagement --date … | --project … | --file …
@@ -128,7 +136,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 |
@@ -147,7 +155,8 @@ What are you trying to do?
 | `count` | `--query` (+ scope) | `<N>` to stdout, summary to stderr |
 | `journal` | `--since` (+ scope) | Per-session 5-line block: date·uuid / prompt / ended / edits / tools |
 | `timeline` | `--date` or `--since/--until` (defaults: today, all projects) | Map of WHAT was active WHEN: blocks + idle gaps (no attention claim — that's `engagement`) |
-| `engagement` | `--date` or `--since/--until` or `--file` (defaults: today, all projects) | YOUR attention time: active vs elapsed + ratio per session, parallel-chat-safe totals, breaks |
+| `engagement` | `--date` or `--since/--until` or `--file` (defaults: today, all projects) | YOUR attention time: active vs elapsed + ratio per session, **you/assistant message counts**, parallel-chat-safe totals, breaks |
+| `session-report` | `--date` or `--since/--until` (defaults: today, all projects) | Per-session day review, chronological: one numbered block each with both clocks (ran = own span, overlaps OK; active = deduped attention), you/assistant message counts, intent, last message, files edited. All windowed to the range. The one-call "review my day" answer. |
 | `diff` | `--file-a` + `--file-b` OR `--subagents-of` | Timestamp-interleaved A>/B> output |
 
 ## Global flags
@@ -157,6 +166,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`).
@@ -201,6 +211,8 @@ See `references/recipes.md` → "Deletion-incident recovery" for the full playbo
 | Find "that session where I asked about supabase rate limits" | `--mode search --all-projects --query "supabase rate limits"` |
 | Resume a project after a few days away | `--mode resume-prev --cwd "<project path>"` |
 | Daily/weekly journal | `--mode journal --since 7d --all-projects` |
+| "What did I do yesterday, per session?" (day review) | `--mode session-report --date yesterday` |
+| "Break down what I did from 7pm on" | `--mode session-report --since "<date> 19:00" --until "<date+1> 00:00"` |
 | "Where did yesterday go?" (map of activity) | `--mode timeline --date yesterday` |
 | "How much did I actually work today?" | `--mode engagement --date today` |
 | "How much time on Keel today?" | `--mode engagement --project keel --date today` |
@@ -210,6 +222,20 @@ See `references/recipes.md` → "Deletion-incident recovery" for the full playbo
 
 See `references/recipes.md` for fuller multi-step workflows.
 
+## Presentation defaults for a human day-review
+
+When the user asks a natural-language "what did I do" / "review my day" / "break down what I worked on" question (as opposed to feeding JSON to a script), lead with `session-report` — it carries everything one such answer needs in a single call — and present it this way unless the user says otherwise:
+
+- **Number the sessions** and separate them into clear blocks. Users read a numbered, sectioned list far more easily than a wall of prose.
+- **Drop UUIDs.** They are noise in a human review; only surface them if the user is going to resume or look one up.
+- **One to two sentences per session** describing what they did and why — synthesized from the `intent` + `last` + files, not a raw dump of either. The mode hands you the inputs; you write the sentence.
+- **Show both clocks and name the overlap.** `active` is deduped attention (parallel chats never double-counted); `ran`/elapsed is the session's own first→last span and *will* overlap others. Say so once — users work on several things at once and want the overlap reflected in the span but removed from active minutes.
+- **Counts are clean already.** `you N msgs` is real typed prompts (tool-results and hook/skill injections excluded); `assistant N msgs` is text replies (tool-only turns excluded). Do NOT hand-count raw `type:user`/`type:assistant` entries from the .jsonl — that over-counts both (tool-result envelopes inflate "user"; multi-block turns inflate "assistant"). Trust the mode's numbers.
+- **24-hour time** as the CLI emits it; convert only if the user asks.
+- **Scope to a sub-window with `--since/--until`** (omit `--date` — `--date` overrides `--since`). The metrics are windowed to the range, so "from 7pm" counts and active-time reflect only that slice.
+
+For a normal day (16–20 sessions) `session-report` text output stays well within the read budget; prefer it over `--mode list --format json`, which dumps full per-session arrays and can overflow into a persisted-file round-trip.
+
 ## Windows notes
 
 - Use `python` (not `python3`) on this Windows setup.

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.
@@ -341,11 +352,17 @@ How it works — three deterministic rules over ONE merged stream:
 3. Everything else is a break and contributes zero. A session left open with no
    prompts accrues nothing.
 
-Output: one row per session (active, ratio = active/elapsed, prompt count,
-first–last), a totals line (already interval-merged — safe to quote), breaks in
-the merged stream, and (single-session view) median/p90 prompt gaps. Ratio is
-capped at 1.0: composing time leading into a chat's first prompt is credited to
-that chat, so raw active can slightly exceed its first–last span.
+Output: one row per session (active, ratio = active/elapsed, `you`/`ai` message
+counts, first–last), a totals line (already interval-merged — safe to quote),
+breaks in the merged stream, and (single-session view) median/p90 prompt gaps.
+Ratio is capped at 1.0: composing time leading into a chat's first prompt is
+credited to that chat, so raw active can slightly exceed its first–last span.
+
+Message counts are honest, not raw entry counts: `you` (`user_messages`) is real
+typed prompts only — tool-result envelopes, hook/skill `isMeta` injections, and
+compact continuations are excluded; `ai` (`assistant_messages`) is assistant
+turns bearing visible text — tool-only turns don't count. Both are windowed to
+`[since, until)`.
 
 Scoping caveat: `--project`/`--cwd`/`--file` filter which sessions are
 *reported*; the stream is always computed across all projects under `--root` so
@@ -361,8 +378,47 @@ Flags:
 
 JSON shape: `{since, until, break_minutes, sessions: [{uuid, project, title,
 path, first, last, elapsed_minutes, active_minutes, active_seconds, ratio,
-user_messages}], totals: {sessions, active_minutes, active_seconds,
-span_minutes}, stream_breaks: [{start, end, minutes}]}`.
+user_messages, assistant_messages}], totals: {sessions, active_minutes,
+active_seconds, span_minutes}, stream_breaks: [{start, end, minutes}]}`.
+
+### `session-report`
+
+The per-session "what did I do" day review. Same windowed, overlap-safe
+attention engine as `engagement`, but rendered as one numbered block per
+session, **chronological** (oldest first by first prompt), carrying everything a
+human review needs in a single call — so a "break down my day" answer doesn't
+require stitching `timeline` + `lookup` + `engagement` + raw message counts by
+hand.
+
+```bash
+# Yesterday, every project
+python read_transcript.py --mode session-report --date yesterday
+
+# Just the evening — omit --date so --since/--until take effect
+python read_transcript.py --mode session-report --since "2026-06-19 19:00" --until "2026-06-20 00:00"
+
+# One project
+python read_transcript.py --mode session-report --project keel --date today
+```
+
+Each block shows: title, project, first–last span with **both clocks** —
+`ran` (the session's own first→last elapsed, which can overlap other sessions)
+and `active` (deduped attention, parallel chats never double-counted) — then
+`you`/`assistant` message counts (same honest definitions as `engagement`),
+files edited, the `intent` (first prompt) and `last` (final assistant message).
+The intent/last are raw inputs for you to synthesize a one-sentence description
+from, not the description itself. A totals line closes with deduped active time
+and the overlap-inclusive span.
+
+Flags: same as `engagement` (`--break`, `--date`/`--since`/`--until`,
+`--cwd`/`--project`/`--all-projects`, `--tz`, `--exclude-current`). As with
+`engagement`, `--date` takes precedence over `--since`/`--until`; to scope to a
+sub-window of a day, pass `--since`/`--until` and omit `--date`.
+
+JSON shape: `{since, until, break_minutes, sessions: [{uuid, project, title,
+path, first, last, elapsed_minutes, active_minutes, user_messages,
+assistant_messages, edits, intent, last_message}], totals: {sessions,
+active_minutes, span_minutes}}`. Sessions are ordered chronologically.
 
 ### `tool-usage`
 
@@ -434,7 +490,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/references/recipes.md

@@ -236,13 +236,19 @@ python "$PY" --file <unknown-session>.jsonl --mode changelog | tail -30
 ## 8. Tool-call forensics ("when did I last `git push --force`?")
 
 ```bash
-# Find every tool_use whose JSON args contain a substring, across all sessions
+# Find which sessions contain a matching tool_use, across all projects
+# (returns a per-session summary by default: one line per session with hit count + snippet)
 python "$PY" --all-projects --mode search --query "git push --force" --in tool_use
 
+# Add --full to expand to match windows instead of the per-session summary
+python "$PY" --all-projects --mode search --query "git push --force" --in tool_use --full
+
 # Get full forensics on the session that matched
 python "$PY" --file <matching-session>.jsonl --mode tool-calls --tool Bash
 ```
 
+Wide-scope search (`--all-projects`, `--cwd`, `--project`) returns a **per-session summary** by default — one line per matching session with a hit count and first snippet — so the output stays under the harness's Read cap. Add `--full` to expand to match windows (bounded by a ~10k-token budget; degrades back to summary with a note if it overflows). Single-file search (`--file`) always returns full windows.
+
 ---
 
 ## 8b. "Which skills (or tools) do I actually use?" — true invocation counts

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