elliot-stack 1.0.39 → 1.0.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elliot-stack",
-  "version": "1.0.39",
+  "version": "1.0.41",
   "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.2.1
+version: 1.3.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,
@@ -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
 ```
@@ -74,6 +80,13 @@ output. If you need a different zone, pass `--tz` (IANA name like
 `America/New_York`, `UTC`, or an offset like `-4`) — never convert manually.
 `--since/--until/--date` specs are interpreted in that same display timezone.
 
+**Report times to the user in 12-hour format unless they ask otherwise.** The
+report modes (`session-report`, `engagement`, `timeline`) already emit each clock
+time as `7:00pm (19:00)` — 12-hour with the 24-hour value in parens — so quoting
+them directly satisfies this. When you paraphrase or summarize a time instead of
+quoting raw output, keep the 12-hour form (the parenthetical 24-hour is optional
+in prose). Switch to 24-hour only if the user requests it.
+
 ## Decision tree
 
 ```
@@ -97,7 +110,7 @@ What are you trying to do?
 │  ├─ 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
+│  └─ Filter by role / content channel ──────── --role user --in tool_use|tool_result|thinking|all
 │
 ├─ Forensics on a session
 │  ├─ Chronological tool-call log ────────────── --mode changelog
@@ -111,6 +124,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 …
@@ -148,7 +162,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
@@ -203,6 +218,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` |
@@ -212,6 +229,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.
+- **12-hour time** as the report modes emit it (`7:00pm (19:00)` — 12-hour with 24-hour in parens); keep the 12-hour form in prose, and switch to 24-hour 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

@@ -18,6 +18,7 @@ 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.
+- **Clock format:** the report modes (`session-report`, `engagement`, `timeline`) render every time-of-day as 12-hour with the 24-hour value in parens — `7:00pm (19:00)` — and date-prefix it (`2026-06-19 7:00pm (19:00)`) when the window spans more than one day; their headers carry a `12h (24h)` label. Forensic modes (`changelog`, `tool-calls`) keep `HH:MM:SS` for density. JSON output is always ISO-8601 (unaffected by the 12-hour rendering).
 - `--format json` (alias `--json`) — structured output on every mode except the legacy `--list`/`--list-subagents` aliases. Shapes per mode are listed below.
 
 Legacy flags are preserved unchanged:
@@ -352,11 +353,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
@@ -372,8 +379,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`
 

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/read_transcript.py

@@ -1036,6 +1036,21 @@ def _fmt_dur(td: timedelta) -> str:
     return f"{h}h{m:02d}m" if h else f"{m}m"
 
 
+def _fmt_tod(dt: datetime) -> str:
+    """Time-of-day as 12-hour with 24-hour in parens: '7:00pm (19:00)'.
+
+    Computed by hand (not strftime %-I/%#I) so it's identical on every platform.
+    """
+    h12 = dt.hour % 12 or 12
+    ampm = "am" if dt.hour < 12 else "pm"
+    return f"{h12}:{dt.minute:02d}{ampm} ({dt.hour:02d}:{dt.minute:02d})"
+
+
+def _fmt_clock(dt: datetime, with_date: bool) -> str:
+    """A report clock value — `_fmt_tod`, date-prefixed when the window spans days."""
+    return f"{dt:%Y-%m-%d} {_fmt_tod(dt)}" if with_date else _fmt_tod(dt)
+
+
 _GAP_RE = re.compile(r"^(\d+)\s*(m|h)?$", re.IGNORECASE)
 
 
@@ -1112,10 +1127,9 @@ def render_timeline(data: dict, tz_label: str) -> str:
     since, until = data["since"], data["until"]
     blocks, sessions = data["blocks"], data["sessions"]
     multi_day = (until - since) > timedelta(days=1)
-    tfmt = "%Y-%m-%d %H:%M" if multi_day else "%H:%M"
     head = (
-        f"=== Timeline {since:%Y-%m-%d %H:%M} → {until:%Y-%m-%d %H:%M} "
-        f"(times: {tz_label}, gap={data['gap_minutes']}m) ==="
+        f"=== Timeline {_fmt_clock(since, True)} → {_fmt_clock(until, True)} "
+        f"(times: {tz_label} 12h (24h), gap={data['gap_minutes']}m) ==="
     )
     if not blocks:
         return head + "\n\n(no activity in range)"
@@ -1125,7 +1139,7 @@ def render_timeline(data: dict, tz_label: str) -> str:
         if prev_end is not None:
             out.append(f"     ── idle {_fmt_dur(b['start'] - prev_end)} ──")
         dur = b["end"] - b["start"]
-        out.append(f"{b['start'].strftime(tfmt)}–{b['end'].strftime('%H:%M')}  ({_fmt_dur(dur)})")
+        out.append(f"{_fmt_clock(b['start'], multi_day)}–{_fmt_tod(b['end'])}  ({_fmt_dur(dur)})")
         for f, n in sorted(b["counts"].items(), key=lambda x: -x[1]):
             out.append(f"   · {_session_label(sessions[f])} — {n} msgs")
         prev_end = b["end"]
@@ -1135,7 +1149,7 @@ def render_timeline(data: dict, tz_label: str) -> str:
     # no claim about user attention time. For that, use --mode engagement.
     out.append(
         f"Total: {len(blocks)} block(s) across a {_fmt_dur(span)} span "
-        f"({blocks[0]['start'].strftime(tfmt)}–{blocks[-1]['end'].strftime('%H:%M')}), "
+        f"({_fmt_clock(blocks[0]['start'], multi_day)}–{_fmt_tod(blocks[-1]['end'])}), "
         f"{len(sessions)} session(s)"
     )
     return "\n".join(out)
@@ -1202,17 +1216,38 @@ def _is_real_user_prompt(obj: dict) -> bool:
     return False
 
 
+def _assistant_has_text(obj: dict) -> bool:
+    """True if an assistant entry carries human-visible text, not just tool_use.
+
+    A turn that only fires tools (no text block) is plumbing, not a reply the
+    user reads, so it does not count as an assistant message.
+    """
+    content = obj.get("message", {}).get("content", "")
+    if isinstance(content, str):
+        return bool(content.strip())
+    if isinstance(content, list):
+        return any(
+            isinstance(b, dict) and b.get("type") == "text" and b.get("text", "").strip()
+            for b in content
+        )
+    return False
+
+
 def _engagement_event_streams(
     path: Path, since: datetime | None, until: datetime | None
-) -> tuple[list[datetime], list[datetime]]:
-    """One session's (user_events, claude_events) inside [since, until).
+) -> tuple[list[datetime], list[datetime], list[datetime]]:
+    """One session's (user_events, claude_events, assistant_events) in [since, until).
 
     user_events — real user prompts only (see _is_real_user_prompt).
     claude_events — assistant messages and tool results: evidence Claude was
     working. Used only to grant waiting-on-Claude credit for long gaps.
+    assistant_events — assistant turns bearing visible text (see
+    _assistant_has_text): the replies the user actually reads, counted clean of
+    tool-only turns and tool-result envelopes.
     """
     user_ev: list[datetime] = []
     claude_ev: list[datetime] = []
+    assistant_ev: list[datetime] = []
     for obj in PR.parse_lines(path):
         cls = PR.classify_entry(obj)
         if cls in ("noise", "title", "compact"):
@@ -1229,9 +1264,12 @@ def _engagement_event_streams(
                 claude_ev.append(ts)  # tool_result entries
         else:  # assistant
             claude_ev.append(ts)
+            if _assistant_has_text(obj):
+                assistant_ev.append(ts)
     user_ev.sort()
     claude_ev.sort()
-    return user_ev, claude_ev
+    assistant_ev.sort()
+    return user_ev, claude_ev, assistant_ev
 
 
 def build_engagement(
@@ -1265,6 +1303,7 @@ def build_engagement(
 
     user_events: dict[Path, list[datetime]] = {}
     claude_events: dict[Path, list[datetime]] = {}
+    assistant_events: dict[Path, list[datetime]] = {}
     walk_dirs = P.list_projects(root)
     files: list[Path] = []
     for pd in walk_dirs:
@@ -1279,10 +1318,11 @@ def build_engagement(
     for f in files:
         if exclude_current and current_uuid and f.stem == current_uuid:
             continue
-        u, c = _engagement_event_streams(f, since, until)
+        u, c, a = _engagement_event_streams(f, since, until)
         if u or c:
             user_events[f] = u
             claude_events[f] = c
+            assistant_events[f] = a
 
     stream = sorted(
         (ts, f) for f, evs in user_events.items() for ts in evs
@@ -1320,6 +1360,7 @@ def build_engagement(
             "first": evs[0],
             "last": evs[-1],
             "user_messages": len(evs),
+            "assistant_messages": len(assistant_events.get(f, [])),
             "active": active.get(f, timedelta()),
         }
 
@@ -1349,10 +1390,9 @@ def render_engagement(data: dict, tz_label: str) -> str:
     since, until = data["since"], data["until"]
     sessions = data["sessions"]
     multi_day = (until - since) > timedelta(days=1)
-    tfmt = "%Y-%m-%d %H:%M" if multi_day else "%H:%M"
     head = (
-        f"=== Engagement {since:%Y-%m-%d %H:%M} → {until:%Y-%m-%d %H:%M} "
-        f"(times: {tz_label}, break={data['break_minutes']}m) ==="
+        f"=== Engagement {_fmt_clock(since, True)} → {_fmt_clock(until, True)} "
+        f"(times: {tz_label} 12h (24h), break={data['break_minutes']}m) ==="
     )
     if not sessions:
         return head + "\n\n(no user messages in range)"
@@ -1367,8 +1407,9 @@ def render_engagement(data: dict, tz_label: str) -> str:
             if elapsed.total_seconds() > 0 else "  — "
         )
         out.append(
-            f"{_fmt_dur(s['active']):>7}  ratio {ratio}  msgs {s['user_messages']:<4} "
-            f"{s['first'].strftime(tfmt)}–{s['last'].strftime('%H:%M')}  "
+            f"{_fmt_dur(s['active']):>7}  ratio {ratio}  "
+            f"you {s['user_messages']:<3} ai {s['assistant_messages']:<4} "
+            f"{_fmt_clock(s['first'], multi_day)}–{_fmt_tod(s['last'])}  "
             f"{_session_label(s['summary'])}"
         )
     total_active = sum((s["active"] for s in sessions.values()), timedelta())
@@ -1377,13 +1418,13 @@ def render_engagement(data: dict, tz_label: str) -> str:
     out.append("")
     out.append(
         f"Total: {_fmt_dur(total_active)} active across {len(sessions)} session(s), "
-        f"{first.strftime(tfmt)}–{last.strftime('%H:%M')} span ({_fmt_dur(last - first)})"
+        f"{_fmt_clock(first, multi_day)}–{_fmt_tod(last)} span ({_fmt_dur(last - first)})"
     )
     breaks = data["breaks"]
     if breaks:
         shown = breaks[:6]
         items = ", ".join(
-            f"{a.strftime(tfmt)}→{b.strftime('%H:%M')} ({_fmt_dur(b - a)})"
+            f"{_fmt_clock(a, multi_day)}→{_fmt_tod(b)} ({_fmt_dur(b - a)})"
             for a, b in shown
         )
         more = f" (+{len(breaks) - len(shown)} more)" if len(breaks) > len(shown) else ""
@@ -1394,7 +1435,7 @@ def render_engagement(data: dict, tz_label: str) -> str:
         (f, s), = sessions.items()
         # recompute the session's own user events from the stored bounds is not
         # enough — pull them again (cached parse, cheap)
-        evs, _ = _engagement_event_streams(f, data["since"], data["until"])
+        evs, _, _ = _engagement_event_streams(f, data["since"], data["until"])
         pct = _gap_percentiles(evs)
         if pct:
             out.append(f"Prompt gaps: median {pct[0]}m, p90 {pct[1]}m")
@@ -1432,6 +1473,7 @@ def engagement_json(data: dict) -> dict:
                 if elapsed.total_seconds() > 0 else None
             ),
             "user_messages": s["user_messages"],
+            "assistant_messages": s["assistant_messages"],
         })
     span_min = 0
     if data["sessions"]:
@@ -1460,6 +1502,101 @@ def engagement_json(data: dict) -> dict:
     }
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Session-report mode — the per-session "what did I do" view
+# ─────────────────────────────────────────────────────────────────────────────
+# Reuses the engagement engine (windowed, overlap-safe attention time) but
+# renders one numbered block per session, chronological, with both clocks
+# (ran = own first→last span, which overlaps others; active = deduped
+# attention), per-role message counts, and the intent/last-message inputs a
+# human day-review is written from.
+
+def render_session_report(data: dict, tz_label: str) -> str:
+    since, until = data["since"], data["until"]
+    sessions = data["sessions"]
+    multi_day = (until - since) > timedelta(days=1)
+    head = (
+        f"=== Session report {_fmt_clock(since, True)} → {_fmt_clock(until, True)} "
+        f"(times: {tz_label} 12h (24h), break={data['break_minutes']}m) ==="
+    )
+    if not sessions:
+        return head + "\n\n(no user activity in range)"
+    out = [head, ""]
+    rows = sorted(sessions.items(), key=lambda kv: kv[1]["first"])  # chronological
+    for i, (f, s) in enumerate(rows, 1):
+        summary = s["summary"]
+        elapsed = s["last"] - s["first"]
+        title = summary.get("title") or summary.get("first_prompt") or "(untitled)"
+        out.append(f"{i}. {title}")
+        out.append(
+            f"   {summary['decoded_project']}  ·  "
+            f"{_fmt_clock(s['first'], multi_day)}–{_fmt_tod(s['last'])}  "
+            f"(ran {_fmt_dur(elapsed)} · active {_fmt_dur(s['active'])})"
+        )
+        out.append(
+            f"   you {s['user_messages']} msgs · "
+            f"assistant {s['assistant_messages']} msgs · "
+            f"{summary['edit_count']} files edited"
+        )
+        out.append(f"   intent: {summary.get('first_prompt') or '(no user prompt)'}")
+        out.append(f"   last:   {summary.get('last_assistant') or '(no assistant message)'}")
+        out.append("")
+    total_active = sum((s["active"] for s in sessions.values()), timedelta())
+    first = min(s["first"] for s in sessions.values())
+    last = max(s["last"] for s in sessions.values())
+    out.append(
+        f"Total: {len(sessions)} session(s) · {_fmt_dur(total_active)} active "
+        f"(overlap removed) across a {_fmt_dur(last - first)} span "
+        f"({_fmt_clock(first, multi_day)}–{_fmt_tod(last)})."
+    )
+    out.append(
+        "(active = your attention, parallel chats never double-counted; "
+        "ran = each session's own first→last span, which can overlap others.)"
+    )
+    return "\n".join(out)
+
+
+def session_report_json(data: dict) -> dict:
+    rows = sorted(data["sessions"].items(), key=lambda kv: kv[1]["first"])
+    sessions_out = []
+    total_active = timedelta()
+    for f, s in rows:
+        summary = s["summary"]
+        elapsed = s["last"] - s["first"]
+        total_active += s["active"]
+        sessions_out.append({
+            "uuid": summary["uuid"],
+            "project": summary["decoded_project"],
+            "title": summary.get("title") or summary.get("first_prompt") or "",
+            "path": str(f),
+            "first": s["first"].isoformat(),
+            "last": s["last"].isoformat(),
+            "elapsed_minutes": int(elapsed.total_seconds() // 60),
+            "active_minutes": int(s["active"].total_seconds() // 60),
+            "user_messages": s["user_messages"],
+            "assistant_messages": s["assistant_messages"],
+            "edits": summary["edit_count"],
+            "intent": summary.get("first_prompt") or "",
+            "last_message": summary.get("last_assistant") or "",
+        })
+    span_min = 0
+    if data["sessions"]:
+        first = min(s["first"] for s in data["sessions"].values())
+        last = max(s["last"] for s in data["sessions"].values())
+        span_min = int((last - first).total_seconds() // 60)
+    return {
+        "since": data["since"].isoformat(),
+        "until": data["until"].isoformat(),
+        "break_minutes": data["break_minutes"],
+        "sessions": sessions_out,
+        "totals": {
+            "sessions": len(sessions_out),
+            "active_minutes": int(total_active.total_seconds() // 60),
+            "span_minutes": span_min,
+        },
+    }
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # JSON builders for legacy single-file modes
 # ─────────────────────────────────────────────────────────────────────────────
@@ -1552,6 +1689,7 @@ NEW_MODES = {
     "changelog", "file-edits", "tool-calls", "tool-usage",
     "subagent-list", "subagent-finals", "subagent-tools", "subagent-files",
     "resume-prev", "count", "journal", "diff", "timeline", "engagement",
+    "session-report",
 }
 
 ALL_MODES = LEGACY_MODES | NEW_MODES
@@ -1767,7 +1905,7 @@ def main() -> int:
         else:
             print(render_timeline(data, tz_label=args.tz or "local"))
         return 0
-    if mode == "engagement":
+    if mode in ("engagement", "session-report"):
         try:
             break_minutes = _parse_gap(args.break_spec, default=10)
             if args.date:
@@ -1786,7 +1924,7 @@ def main() -> int:
             return 1
         if report_file and e_since is None:
             # Window defaults to the file's own first→last user prompt.
-            evs, _ = _engagement_event_streams(report_file, None, None)
+            evs, _, _ = _engagement_event_streams(report_file, None, None)
             if not evs:
                 print("(no user messages in this session)")
                 return 0
@@ -1805,7 +1943,12 @@ def main() -> int:
             root, report_dirs, report_file, e_since, e_until, break_minutes,
             current_uuid, exclude_current=args.exclude_current,
         )
-        if fmt == "json":
+        if mode == "session-report":
+            if fmt == "json":
+                _print_json(session_report_json(data))
+            else:
+                print(render_session_report(data, tz_label=args.tz or "local"))
+        elif fmt == "json":
             _print_json(engagement_json(data))
         else:
             print(render_engagement(data, tz_label=args.tz or "local"))

package/skills/estack-migrate-claude-session-history/scripts/test-append-note.js

@@ -1,48 +0,0 @@
-'use strict';
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-const mod = require('./migrate-claude-history.js');
-
-// Set up a tiny synthetic .jsonl in a temp dir
-const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'migrate-test-'));
-const testFile = path.join(tmp, 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee.jsonl');
-const sampleEntries = [
-  { type: 'permission-mode', permissionMode: 'default', sessionId: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' },
-  { type: 'user', message: { role: 'user', content: 'Hello' }, uuid: '11111111-1111-1111-1111-111111111111', parentUuid: null, sessionId: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee', timestamp: '2026-05-24T18:00:00.000Z', cwd: 'C:\\fake\\old', version: '2.1.0' },
-];
-fs.writeFileSync(testFile, sampleEntries.map((e) => JSON.stringify(e)).join('\n') + '\n', 'utf8');
-
-const oldRepo = mod.parseWindowsRepoPath('C:\\fake\\old', 'old');
-const newRepo = mod.parseWindowsRepoPath('C:\\fake\\new', 'new');
-
-const summary = { migrationNotesAppended: 0, migrationNotesSkipped: 0 };
-
-// First call — should append
-mod.appendMigrationNote({ filePath: testFile, oldRepo, newRepo, dryRun: false, summary });
-console.log('After first call:', summary);
-
-// Second call — should detect duplicate and skip
-mod.appendMigrationNote({ filePath: testFile, oldRepo, newRepo, dryRun: false, summary });
-console.log('After second call:', summary);
-
-// Inspect the appended entry
-const lines = fs.readFileSync(testFile, 'utf8').split('\n').filter((l) => l.trim());
-const appended = JSON.parse(lines[lines.length - 1]);
-
-console.log('');
-console.log('=== Appended entry shape ===');
-console.log('type:    ', appended.type);
-console.log('isMeta:  ', 'isMeta' in appended ? appended.isMeta : '<not set>');
-console.log('parent:  ', appended.parentUuid);
-console.log('uuid:    ', appended.uuid);
-console.log('cwd:     ', appended.cwd);
-console.log('');
-console.log('=== content (first 200 chars) ===');
-console.log(appended.message.content.slice(0, 200) + '...');
-
-// Cleanup
-fs.rmSync(tmp, { recursive: true, force: true });
-console.log('');
-console.log('Test passed:', summary.migrationNotesAppended === 1 && summary.migrationNotesSkipped === 1 && !('isMeta' in appended) ? 'YES' : 'NO');