elliot-stack 1.0.19 → 1.0.21

package/bin/install.cjs

@@ -11,13 +11,74 @@ const readline = require('readline');
 const HOME = os.homedir();
 const CLAUDE_DIR = path.join(HOME, '.claude');
 const SKILLS_DIR = path.join(CLAUDE_DIR, 'skills');
-const BACKUP_DIR = path.join(CLAUDE_DIR, '.estack-backup');
+const BACKUP_DIR = path.join(HOME, '.estack-backup');
 const CHECKSUMS_FILE = path.join(CLAUDE_DIR, '.estack-checksums.json');
 const SETTINGS_FILE = path.join(CLAUDE_DIR, 'settings.json');
 const PACKAGE_SKILLS_DIR = path.join(__dirname, '..', 'skills');
 const HOOKS_DIR = path.join(CLAUDE_DIR, 'hooks');
 const PACKAGE_HOOKS_DIR = path.join(__dirname, '..', 'hooks');
 
+// ── Migrate backup dir from old location (inside .claude) to user root ──────
+(function migrateBackupDir() {
+  const OLD_BACKUP_DIR = path.join(CLAUDE_DIR, '.estack-backup');
+  if (!fs.existsSync(OLD_BACKUP_DIR)) return;
+  if (fs.existsSync(BACKUP_DIR)) return; // new location already exists, leave both alone
+  const silent = process.argv.includes('--silent');
+  const isDryRun = process.argv.includes('--dry-run') ||
+    (!__dirname.includes('node_modules') && !process.argv.includes('--install'));
+  if (isDryRun) {
+    if (!silent) {
+      process.stderr.write(
+        'estack: [dry run] Would move backup dir from ~/.claude/.estack-backup/ to ~/.estack-backup/\n'
+      );
+    }
+    return;
+  }
+  try {
+    fs.renameSync(OLD_BACKUP_DIR, BACKUP_DIR);
+    if (!silent) {
+      process.stderr.write(
+        'estack: moved backup dir from ~/.claude/.estack-backup/ to ~/.estack-backup/\n'
+      );
+    }
+  } catch (e) {
+    // rename across drives/filesystems — fall back to copy+delete
+    try {
+      copyDirRaw(OLD_BACKUP_DIR, BACKUP_DIR);
+      removeDirRaw(OLD_BACKUP_DIR);
+      if (!silent) {
+        process.stderr.write(
+          'estack: migrated backup dir from ~/.claude/.estack-backup/ to ~/.estack-backup/\n'
+        );
+      }
+    } catch (e2) {
+      process.stderr.write(
+        'estack: WARNING — could not migrate backup dir from ' + OLD_BACKUP_DIR +
+        ' to ' + BACKUP_DIR + ': ' + e2.message + '\n'
+      );
+    }
+  }
+})();
+
+function copyDirRaw(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDirRaw(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+function removeDirRaw(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) removeDirRaw(full);
+    else fs.unlinkSync(full);
+  }
+  fs.rmdirSync(dir);
+}
+
 // ── Flags ──────────────────────────────────────────────────────────────────
 const SILENT = process.argv.includes('--silent');
 const STARTUP = process.argv.includes('--startup');
@@ -560,7 +621,7 @@ async function main() {
       if (modifiedAction === 'merge') {
         if (!DRY_RUN) backupSkill(name);
         mergedSkills.push(name);
-        console.log((DRY_RUN ? '  [dry run] Would back up ' : '  Backed up ') + name + ' → ~/.claude/.estack-backup/' + name);
+        console.log((DRY_RUN ? '  [dry run] Would back up ' : '  Backed up ') + name + ' → ~/.estack-backup/' + name);
       }
       // overwrite or merge — fall through to install
     } else if (!needsUpdate.includes(name) && fs.existsSync(path.join(SKILLS_DIR, name))) {
@@ -595,7 +656,7 @@ async function main() {
       if (modifiedAction === 'merge') {
         if (!DRY_RUN) backupHook(filename);
         mergedHooks.push(filename);
-        console.log((DRY_RUN ? '  [dry run] Would back up hook ' : '  Backed up hook ') + filename + ' → ~/.claude/.estack-backup/hooks/' + filename);
+        console.log((DRY_RUN ? '  [dry run] Would back up hook ' : '  Backed up hook ') + filename + ' → ~/.estack-backup/hooks/' + filename);
       }
       // overwrite or merge — fall through to install
     } else if (!hooksNeedingUpdate.includes(filename) && fs.existsSync(path.join(HOOKS_DIR, filename))) {
@@ -647,12 +708,12 @@ async function main() {
   if (mergedSkills.length > 0) {
     console.log('\nLocal changes backed up for: ' + mergedSkills.join(', '));
     console.log('Ask Claude to merge your changes:');
-    console.log('  "Merge my estack changes from ~/.claude/.estack-backup/"');
+    console.log('  "Merge my estack changes from ~/.estack-backup/"');
   }
 
   if (mergedHooks.length > 0) {
     console.log('\nLocal hook changes backed up for: ' + mergedHooks.join(', '));
-    console.log('Backed up to ~/.claude/.estack-backup/hooks/');
+    console.log('Backed up to ~/.estack-backup/hooks/');
   }
 
   if (DRY_RUN) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elliot-stack",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "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
-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, parse, or search them; do not attempt to use Bash or Read on .jsonl directly. Use for: recovering context after /compact ("what were we doing before compact"), advisor response retrieval ("what did the advisor say"), subagent output collection ("get all subagent finals"), cross-project session search by keyword, session listing and triage, UUID and title lookup, resume-command generation, file-edit and tool-call forensics, session diff between two sessions or subagents, weekly work journal, day timeline of activity blocks and idle gaps, recovering from .claude-backups after data loss, session count queries, and reading the last agent message before a crash or interrupt. Trigger phrases: "session history", "before compact", "what did claude do", "what did I work on", "search my sessions", "find that session", "what did the advisor say", "what did the agent edit", "from the backup", "list my sessions", "subagent outputs", "session journal", "resume previous", "which files did claude touch", "go back and look", "what did I do yesterday", "where did my day go", "timeline of my day", "how much time on".
+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, parse, or search them; do not attempt to use Bash or Read on .jsonl directly. Use for: recovering context after /compact ("what were we doing before compact"), advisor response retrieval ("what did the advisor say"), subagent output collection ("get all subagent finals"), cross-project session search by keyword, session listing and triage, UUID and title lookup, resume-command generation, file-edit and tool-call forensics, session diff between two sessions or subagents, weekly work journal, day timeline of activity blocks and idle gaps, engagement/attention-time accounting (active vs elapsed time, break detection, parallel-chat-safe totals), recovering from .claude-backups after data loss, session count queries, and reading the last agent message before a crash or interrupt. Trigger phrases: "session history", "before compact", "what did claude do", "what did I work on", "search my sessions", "find that session", "what did the advisor say", "what did the agent edit", "from the backup", "list my sessions", "subagent outputs", "session journal", "resume previous", "which files did claude touch", "go back and look", "what did I do yesterday", "where did my day go", "timeline of my day", "how much time on", "how long did that actually take", "how much did I actually work", "active time", "time I spent".
 ---
 
 # Read Claude Session History
@@ -35,6 +35,9 @@ python "$PY" --file <parent.jsonl> --mode subagent-finals
 # Block-grouped timeline of a whole day across all sessions, with idle gaps
 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
+
 # Any mode as structured JSON for piping into the next step
 python "$PY" --mode list --project keel --since 7d --format json
 ```
@@ -85,8 +88,8 @@ What are you trying to do?
 │
 ├─ Cross-cutting reporting
 │  ├─ "What did I do this week?" ──────────────── --mode journal --since 7d
-│  ├─ "Where did my day go?" / day timeline ───── --mode timeline --date yesterday
-│  ├─ "How much time on <project>?" ───────────── --mode timeline --project <name> --date …
+│  ├─ "What was I doing, when?" / day map ─────── --mode timeline --date yesterday
+│  ├─ "How long did X actually take ME?" ──────── --mode engagement --date … | --project … | --file …
 │  ├─ Count sessions matching a query ─────────── --mode count --query …
 │  └─ Resume where I left off in this project ─── --mode resume-prev --cwd …
 │
@@ -119,7 +122,8 @@ What are you trying to do?
 | `resume-prev` | `--cwd` | Banner + dump-style tail of last 10 exchanges |
 | `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) | Block-grouped day timeline across sessions with idle gaps + active-time totals |
+| `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 |
 | `diff` | `--file-a` + `--file-b` OR `--subagents-of` | Timestamp-interleaved A>/B> output |
 
 ## Global flags
@@ -127,14 +131,15 @@ What are you trying to do?
 - `--root {live|mirror|snapshot-24h|snapshot-1w|snapshot-1mo|<abs-path>}` — read from a `.claude-backups` mirror or snapshot instead of live. Default `live`.
 - `--cwd <path>` — single-project scope. Use the original working directory (e.g. `"C:\Users\2supe\Other Claude Code"`).
 - `--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`. Use this instead of `--cwd` when you know the project's name but not its exact path.
+- `--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`. 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.
 - `--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`).
+- `--break <spec>` — break threshold for `engagement` (`10m` default; `5m` strict, `20m` forgiving). Gaps between your prompts longer than this count as breaks unless you replied right after Claude finished working.
 - `--tz <spec>` — display timezone override (IANA name, `UTC`, or offset like `-4`). Default: system local time.
 - `--format json` (or `--json`) — structured JSON output on every mode (except the legacy `--list`/`--list-subagents` aliases). Pipe-friendly: paths are strings, timestamps ISO.
-- `--exclude-current` — drop the current session (detected via `CLAUDE_SESSION_ID`) from `list`, `journal`, `search`, `count`, and `timeline`.
+- `--exclude-current` — drop the current session (detected via `CLAUDE_SESSION_ID`) from `list`, `journal`, `search`, `count`, `timeline`, and `engagement`.
 - `--include-subagents` — fold subagent finals into `brief`, `last`, `dump` output, each tagged `[subagent <id-short> · <agentType>]`.
 - `--force-dump` — bypass the 5 MB `dump` guard.
 - `-n N` — count modifier (default 5 for `last`, 80 for `dump`, 10 for `resume-prev`).
@@ -172,8 +177,10 @@ 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` |
-| "Where did yesterday go?" | `--mode timeline --date yesterday` |
-| "How much time on Keel today?" | `--mode timeline --project keel --date today` |
+| "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` |
+| "How long did that session take me?" | `--mode engagement --file <session.jsonl>` |
 | Feed session data into a script | any mode + `--format json` |
 
 See `references/recipes.md` for fuller multi-step workflows.

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

@@ -15,7 +15,7 @@ python read_transcript.py [--root <root>] [--cwd <path> | --all-projects | --pro
 ```
 
 Global flag notes:
-- `--project <name>` — case-insensitive substring filter on project directory names (encoded or decoded form). Applies to `list`, `journal`, `search`, `count`, `find`, `timeline`. Exit 1 when nothing matches.
+- `--project <name>` — case-insensitive substring filter on project directory names (encoded or decoded form). Applies to `list`, `journal`, `search`, `count`, `find`, `timeline`, `engagement`. 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.
 
@@ -277,8 +277,9 @@ JSON shape: array of session-summary objects (same fields as `list`).
 ### `timeline`
 
 Block-grouped activity timeline across all sessions in a time window, with idle
-gaps and active-time totals. Answers "where did my day go?" and "how much time on
-X?". Defaults to all projects and today.
+gaps. Answers "what was I doing, when?". It is a *map* of session activity —
+Claude's work included — and makes no claim about attention time; for "how much
+time did this consume?" use `engagement`. Defaults to all projects and today.
 
 ```bash
 # Yesterday, everything
@@ -295,7 +296,7 @@ How it works: every signal-message timestamp in the window is an activity event;
 events across all sessions are merged chronologically and grouped into blocks
 separated by gaps longer than `--gap` (default 15m). Each block lists the sessions
 active in it with message counts; idle gaps are printed between blocks; a totals
-line gives block count, summed active time, span, and session count.
+line gives block count, span, and session count.
 
 Flags:
 - `--date <spec>` — single-day window (midnight to midnight). Wins over `--since/--until`.
@@ -306,7 +307,62 @@ Flags:
 
 JSON shape: `{since, until, gap_minutes, blocks: [{start, end, duration_minutes,
 sessions: [{uuid, project, title, path, events}]}], totals: {blocks,
-active_minutes, sessions}}`.
+span_minutes, sessions}}`.
+
+### `engagement`
+
+Attention-time accounting: how much focused time a window, project, or session
+actually consumed — *your* time, not Claude's. Answers "how long did X actually
+take me?". Defaults to all projects and today; with `--file` and no time flags,
+the window is the session's own first→last prompt.
+
+```bash
+# Today's real work time, everything
+python read_transcript.py --mode engagement --date today
+
+# One project over a week
+python read_transcript.py --mode engagement --project keel --since 7d
+
+# One session, strict 5-minute break threshold
+python read_transcript.py --mode engagement --file <session.jsonl> --break 5m
+```
+
+How it works — three deterministic rules over ONE merged stream:
+
+1. Real user prompts (typed messages and slash commands — not tool results,
+   hook/skill injections, or compact continuations) from EVERY project are
+   merged into a single chronological stream. A gap between consecutive prompts
+   ≤ `--break` (default 10m) counts fully as active time, attributed to the
+   session of the *later* prompt — the chat being read/typed in. One stream
+   means a moment of wall clock is never counted twice across parallel chats.
+2. A longer gap still counts in full if Claude was working in that session
+   during the gap and the user replied within `--break` of Claude's last event
+   (sitting-there-waiting credit). Long runs you walked away from get nothing.
+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.
+
+Scoping caveat: `--project`/`--cwd`/`--file` filter which sessions are
+*reported*; the stream is always computed across all projects under `--root` so
+parallel-chat math stays correct. A scoped total can be less than the global
+total for the same window.
+
+Flags:
+- `--break <spec>` — break threshold: `5m`, `20m`, `1h` (default 10m).
+- `--date` / `--since` / `--until` — window (same semantics as timeline).
+- `--cwd` / `--project` / `--all-projects` / `--file` — reporting scope.
+- `--tz` — display timezone.
+- `--exclude-current` — drop the current session from stream and report.
+
+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}]}`.
 
 ---
 
@@ -353,6 +409,7 @@ Output is prefixed `A>` / `B>` (or with subagent id shorts).
 | `resume-prev` | `{session, path, mtime_iso, messages}` |
 | `diff` | `{a, b, messages: [{source, role, timestamp, text}]}` |
 | `timeline` | see the `timeline` section above |
+| `engagement` | see the `engagement` section above |
 
 Session-summary object fields: `path, uuid, mtime, mtime_iso, size, exists, title,
 first_prompt, last_assistant, last_activity, msg_count, edit_count, tool_counts,

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

@@ -133,10 +133,44 @@ python "$PY" --mode timeline --since 2026-06-01 --until 2026-06-03
 
 Reading the output: each block is a contiguous stretch of activity (events ≤ gap
 apart); the sessions inside it are listed with message counts; `── idle Xm ──`
-lines mark the breaks; the totals line gives summed active time vs. span.
+lines mark the breaks; the totals line gives block count, span, and session count.
 
-Caveat: this measures *Claude-visible* activity only — message timestamps, not
-attention or time spent away from Claude.
+Caveat: timeline maps *session* activity (Claude's work included) — it makes no
+claim about your attention time. For "how long did this actually take ME?", use
+`--mode engagement` (recipe 5d).
+
+---
+
+## 5d. Attention accounting ("how long did X actually take me?")
+
+`engagement` measures *your* time, not the session's. It merges your real
+prompts from ALL projects into one stream, so two parallel chats split the
+clock instead of double-counting it, and long Claude runs you sat waiting on
+are credited (you replied right after Claude finished) while runs you walked
+away from are not.
+
+```bash
+# How much focused time did today actually consume?
+python "$PY" --mode engagement --date today
+
+# One project over a week
+python "$PY" --mode engagement --project keel --since 7d
+
+# One session, window auto-derived from its first→last prompt
+python "$PY" --mode engagement --file <session.jsonl>
+
+# Strict mode: anything over 5 minutes quiet is a break
+python "$PY" --mode engagement --date today --break 5m
+```
+
+Reading the output: one row per session (`active / ratio / msgs / first–last`),
+a total line (sum of attributed time — already interval-merged, safe to quote),
+and the breaks in the merged stream. `ratio` = active/elapsed; 0.50 means half
+the wall-clock span was real attention.
+
+Scoping caveat: `--project`/`--file` filter which sessions are *reported*; the
+attention stream is always computed across all projects so the math stays
+honest. A scoped total can therefore be less than the same window's global total.
 
 ---
 
@@ -150,8 +184,8 @@ git-bash) — they work exactly as written:
 python "$PY" --mode list --all-projects --since yesterday --format json \
   | python -c "import json,sys; [print(s['path']) for s in json.load(sys.stdin)]"
 
-# Machine-readable day totals
-python "$PY" --mode timeline --date yesterday --format json \
+# Machine-readable day totals (attention time → engagement, not timeline)
+python "$PY" --mode engagement --date yesterday --format json \
   | python -c "import json,sys; t=json.load(sys.stdin)['totals']; print(t['active_minutes'], 'min across', t['sessions'], 'sessions')"
 ```
 

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

@@ -829,10 +829,10 @@ def _fmt_dur(td: timedelta) -> str:
 _GAP_RE = re.compile(r"^(\d+)\s*(m|h)?$", re.IGNORECASE)
 
 
-def _parse_gap(spec: str | None) -> int:
-    """Parse a --gap spec ('15m', '1h', '20') into minutes. Default 15."""
+def _parse_gap(spec: str | None, default: int = 15) -> int:
+    """Parse a gap/break spec ('15m', '1h', '20') into minutes."""
     if not spec:
-        return 15
+        return default
     m = _GAP_RE.match(spec.strip())
     if not m:
         raise ValueError(f"Unrecognized gap spec: {spec!r}. Use forms like 15m or 1h.")
@@ -910,22 +910,21 @@ def render_timeline(data: dict, tz_label: str) -> str:
     if not blocks:
         return head + "\n\n(no activity in range)"
     out = [head, ""]
-    active = timedelta()
     prev_end: datetime | None = None
     for b in blocks:
         if prev_end is not None:
             out.append(f"     ── idle {_fmt_dur(b['start'] - prev_end)} ──")
         dur = b["end"] - b["start"]
-        active += dur
         out.append(f"{b['start'].strftime(tfmt)}–{b['end'].strftime('%H:%M')}  ({_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"]
     span = blocks[-1]["end"] - blocks[0]["start"]
     out.append("")
+    # Timeline is a map of WHEN sessions were active (Claude included) — it makes
+    # no claim about user attention time. For that, use --mode engagement.
     out.append(
-        f"Total: {len(blocks)} active block(s), {_fmt_dur(active)} active "
-        f"within a {_fmt_dur(span)} span "
+        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"{len(sessions)} session(s)"
     )
@@ -935,10 +934,8 @@ def render_timeline(data: dict, tz_label: str) -> str:
 def timeline_json(data: dict) -> dict:
     sessions = data["sessions"]
     blocks_out = []
-    active_min = 0
     for b in data["blocks"]:
         dur_min = int((b["end"] - b["start"]).total_seconds() // 60)
-        active_min += dur_min
         blocks_out.append({
             "start": b["start"].isoformat(),
             "end": b["end"].isoformat(),
@@ -954,6 +951,11 @@ def timeline_json(data: dict) -> dict:
                 for f, n in sorted(b["counts"].items(), key=lambda x: -x[1])
             ],
         })
+    span_min = 0
+    if data["blocks"]:
+        span_min = int(
+            (data["blocks"][-1]["end"] - data["blocks"][0]["start"]).total_seconds() // 60
+        )
     return {
         "since": data["since"].isoformat(),
         "until": data["until"].isoformat(),
@@ -961,12 +963,293 @@ def timeline_json(data: dict) -> dict:
         "blocks": blocks_out,
         "totals": {
             "blocks": len(blocks_out),
-            "active_minutes": active_min,
+            "span_minutes": span_min,
             "sessions": len(sessions),
         },
     }
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Engagement mode — user attention time, not session activity
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _is_real_user_prompt(obj: dict) -> bool:
+    """True only for an actual human action: typed prompt or slash command.
+
+    Excludes tool results (user-role, no text blocks), hook/skill injections
+    (isMeta), and compact continuations (classified upstream).
+    """
+    if obj.get("isMeta"):
+        return False
+    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).
+
+    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.
+    """
+    user_ev: list[datetime] = []
+    claude_ev: list[datetime] = []
+    for obj in PR.parse_lines(path):
+        cls = PR.classify_entry(obj)
+        if cls in ("noise", "title", "compact"):
+            continue
+        ts = PR._parse_timestamp(obj.get("timestamp"))
+        if ts is None or (since and ts < since) or (until and ts >= until):
+            continue
+        if cls == "user":
+            if obj.get("isMeta"):
+                continue
+            if _is_real_user_prompt(obj):
+                user_ev.append(ts)
+            else:
+                claude_ev.append(ts)  # tool_result entries
+        else:  # assistant
+            claude_ev.append(ts)
+    user_ev.sort()
+    claude_ev.sort()
+    return user_ev, claude_ev
+
+
+def build_engagement(
+    root: Path,
+    report_dirs: list[Path] | None,
+    report_file: Path | None,
+    since: datetime,
+    until: datetime,
+    break_minutes: int,
+    current_uuid: str | None,
+    exclude_current: bool = False,
+) -> dict:
+    """Attention-time accounting over ONE merged user-prompt stream.
+
+    Real user prompts from EVERY project are merged into a single global
+    stream, so a moment of wall-clock time is never counted twice across
+    parallel chats. Three rules:
+
+    1. A gap between consecutive prompts ≤ break_minutes counts fully as
+       active time, attributed to the session of the LATER prompt (that's
+       the chat being read/typed in).
+    2. A longer gap still counts in full if Claude was working in the later
+       prompt's session during the gap AND the user replied within
+       break_minutes of Claude's last event (sitting-there-waiting credit).
+    3. Anything else is a break: contributes nothing.
+
+    report_dirs/report_file only filter which sessions are REPORTED — the
+    stream itself always spans all projects under root for correctness.
+    """
+    import bisect
+
+    user_events: dict[Path, list[datetime]] = {}
+    claude_events: dict[Path, list[datetime]] = {}
+    walk_dirs = P.list_projects(root)
+    files: list[Path] = []
+    for pd in walk_dirs:
+        # mtime >= since only; a session still active after `until` may hold
+        # events inside the window (same reasoning as timeline).
+        files.extend(P.list_transcripts(pd, since=since))
+    if report_file:
+        report_file = report_file.resolve()
+        files = [f.resolve() for f in files]
+        if report_file not in files:
+            files.append(report_file)  # e.g. --file under a different root
+    for f in files:
+        if exclude_current and current_uuid and f.stem == current_uuid:
+            continue
+        u, c = _engagement_event_streams(f, since, until)
+        if u or c:
+            user_events[f] = u
+            claude_events[f] = c
+
+    stream = sorted(
+        (ts, f) for f, evs in user_events.items() for ts in evs
+    )
+
+    brk = timedelta(minutes=break_minutes)
+    active: dict[Path, timedelta] = {}
+    breaks: list[tuple[datetime, datetime]] = []
+    for (t0, _f0), (t1, f1) in zip(stream, stream[1:]):
+        gap = t1 - t0
+        if gap <= brk:
+            active[f1] = active.get(f1, timedelta()) + gap
+            continue
+        # Waiting-on-Claude credit: last Claude event in f1 inside the gap.
+        cl = claude_events.get(f1, [])
+        i = bisect.bisect_left(cl, t1)
+        t_done = cl[i - 1] if i > 0 and cl[i - 1] > t0 else None
+        if t_done is not None and (t1 - t_done) <= brk:
+            active[f1] = active.get(f1, timedelta()) + gap
+        else:
+            breaks.append((t0, t1))
+
+    # Reporting scope
+    report_dir_set = {d.resolve() for d in report_dirs} if report_dirs else None
+    sessions: dict[Path, dict] = {}
+    for f, evs in user_events.items():
+        if not evs:
+            continue
+        if report_file and f != report_file:
+            continue
+        if report_dir_set is not None and f.parent.resolve() not in report_dir_set:
+            continue
+        sessions[f] = {
+            "summary": PR.session_summary(f, current_session_id=current_uuid),
+            "first": evs[0],
+            "last": evs[-1],
+            "user_messages": len(evs),
+            "active": active.get(f, timedelta()),
+        }
+
+    return {
+        "since": since,
+        "until": until,
+        "break_minutes": break_minutes,
+        "sessions": sessions,
+        "breaks": breaks,
+        "stream_events": len(stream),
+    }
+
+
+def _gap_percentiles(evs: list[datetime]) -> tuple[int, int] | None:
+    """(median, p90) of intra-session user-prompt gaps, in whole minutes."""
+    if len(evs) < 2:
+        return None
+    gaps = sorted(
+        (b - a).total_seconds() / 60 for a, b in zip(evs, evs[1:])
+    )
+    median = gaps[len(gaps) // 2]
+    p90 = gaps[min(len(gaps) - 1, int(len(gaps) * 0.9))]
+    return int(median), int(p90)
+
+
+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) ==="
+    )
+    if not sessions:
+        return head + "\n\n(no user messages in range)"
+    out = [head, ""]
+    rows = sorted(sessions.items(), key=lambda kv: -kv[1]["active"].total_seconds())
+    for f, s in rows:
+        elapsed = s["last"] - s["first"]
+        # Composing time leading into a chat's first prompt is credited to it,
+        # so active can slightly exceed first–last; cap the ratio at 1.0.
+        ratio = (
+            f"{min(1.0, s['active'].total_seconds() / elapsed.total_seconds()):.2f}"
+            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"{_session_label(s['summary'])}"
+        )
+    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("")
+    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)})"
+    )
+    breaks = data["breaks"]
+    if breaks:
+        shown = breaks[:6]
+        items = ", ".join(
+            f"{a.strftime(tfmt)}→{b.strftime('%H:%M')} ({_fmt_dur(b - a)})"
+            for a, b in shown
+        )
+        more = f" (+{len(breaks) - len(shown)} more)" if len(breaks) > len(shown) else ""
+        out.append(f"Breaks >{data['break_minutes']}m in the merged stream: "
+                   f"{len(breaks)} — {items}{more}")
+    # Single-session detail: prompt-gap percentiles
+    if len(sessions) == 1:
+        (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"])
+        pct = _gap_percentiles(evs)
+        if pct:
+            out.append(f"Prompt gaps: median {pct[0]}m, p90 {pct[1]}m")
+    out.append(
+        "(active time = your message cadence merged across ALL projects; "
+        "parallel chats split the clock, never double-count. "
+        "Long gaps count only when you replied right after Claude finished.)"
+    )
+    return "\n".join(out)
+
+
+def engagement_json(data: dict) -> dict:
+    sessions_out = []
+    rows = sorted(
+        data["sessions"].items(), key=lambda kv: -kv[1]["active"].total_seconds()
+    )
+    total_active = timedelta()
+    for f, s in rows:
+        elapsed = s["last"] - s["first"]
+        active = s["active"]
+        total_active += active
+        summary = s["summary"]
+        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(active.total_seconds() // 60),
+            "active_seconds": int(active.total_seconds()),
+            "ratio": (
+                min(1.0, round(active.total_seconds() / elapsed.total_seconds(), 2))
+                if elapsed.total_seconds() > 0 else None
+            ),
+            "user_messages": s["user_messages"],
+        })
+    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),
+            "active_seconds": int(total_active.total_seconds()),
+            "span_minutes": span_min,
+        },
+        "stream_breaks": [
+            {
+                "start": a.isoformat(),
+                "end": b.isoformat(),
+                "minutes": int((b - a).total_seconds() // 60),
+            }
+            for a, b in data["breaks"]
+        ],
+    }
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # JSON builders for legacy single-file modes
 # ─────────────────────────────────────────────────────────────────────────────
@@ -1058,7 +1341,7 @@ NEW_MODES = {
     "list", "lookup", "find", "resume-cmd", "brief",
     "changelog", "file-edits", "tool-calls",
     "subagent-list", "subagent-finals", "subagent-tools", "subagent-files",
-    "resume-prev", "count", "journal", "diff", "timeline",
+    "resume-prev", "count", "journal", "diff", "timeline", "engagement",
 }
 
 ALL_MODES = LEGACY_MODES | NEW_MODES
@@ -1086,6 +1369,8 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--until", help="Upper time bound (same forms as --since)")
     p.add_argument("--date", help="Single-day window for timeline mode (ISO date / yesterday / today)")
     p.add_argument("--gap", help="Idle-gap threshold for timeline blocks (e.g. 15m, 1h; default 15m)")
+    p.add_argument("--break", dest="break_spec",
+                   help="Break threshold for engagement mode (e.g. 5m, 20m; default 10m)")
     p.add_argument(
         "--tz", default=None,
         help="Display timezone override: IANA name (America/New_York), UTC, or offset (+5, -4). "
@@ -1289,6 +1574,49 @@ def main() -> int:
         else:
             print(render_timeline(data, tz_label=args.tz or "local"))
         return 0
+    if mode == "engagement":
+        try:
+            break_minutes = _parse_gap(args.break_spec, default=10)
+            if args.date:
+                day = P.parse_timespec(args.date).replace(
+                    hour=0, minute=0, second=0, microsecond=0
+                )
+                e_since, e_until = day, day + timedelta(days=1)
+            else:
+                e_since, e_until = since, until
+        except ValueError as e:
+            print(str(e), file=sys.stderr)
+            return 1
+        report_file = Path(args.file) if args.file else None
+        if report_file and not report_file.exists():
+            print(f"File not found: {report_file}", file=sys.stderr)
+            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)
+            if not evs:
+                print("(no user messages in this session)")
+                return 0
+            e_since = evs[0]
+            e_until = e_until or evs[-1] + timedelta(seconds=1)
+        else:
+            e_since = e_since or P.parse_timespec("today")
+            e_until = e_until or P.parse_timespec("now")
+        # Scope filters reporting only; the attention stream is always global.
+        report_dirs = None
+        if not report_file:
+            report_dirs = _scoped_project_dirs(
+                root, args.cwd, args.all_projects, args.project, default_all=True
+            )
+        data = build_engagement(
+            root, report_dirs, report_file, e_since, e_until, break_minutes,
+            current_uuid, exclude_current=args.exclude_current,
+        )
+        if fmt == "json":
+            _print_json(engagement_json(data))
+        else:
+            print(render_engagement(data, tz_label=args.tz or "local"))
+        return 0
     if mode == "diff":
         if args.subagents_of:
             parent = Path(args.subagents_of)

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/engagement-gaps.jsonl

@@ -0,0 +1,9 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"Start the analysis"}}
+{"type":"assistant","timestamp":"2026-05-01T10:01:00Z","message":{"role":"assistant","content":[{"type":"text","text":"On it."}]}}
+{"type":"user","timestamp":"2026-05-01T10:05:00Z","message":{"role":"user","content":"Looks good, continue"}}
+{"type":"assistant","timestamp":"2026-05-01T10:06:00Z","message":{"role":"assistant","content":[{"type":"text","text":"Done with phase 1."}]}}
+{"type":"user","timestamp":"2026-05-01T10:08:00Z","message":{"role":"user","content":"Next phase"}}
+{"type":"assistant","timestamp":"2026-05-01T10:09:00Z","message":{"role":"assistant","content":[{"type":"text","text":"Phase 2 complete."}]}}
+{"type":"user","timestamp":"2026-05-01T10:40:00Z","message":{"role":"user","content":"Back from a break, keep going"}}
+{"type":"assistant","timestamp":"2026-05-01T10:41:00Z","message":{"role":"assistant","content":[{"type":"text","text":"Resumed."}]}}
+{"type":"user","timestamp":"2026-05-01T10:45:00Z","message":{"role":"user","content":"Wrap it up"}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/engagement-noise.jsonl

@@ -0,0 +1,7 @@
+{"type":"user","timestamp":"2026-05-01T09:00:00Z","isMeta":true,"message":{"role":"user","content":[{"type":"text","text":"SessionStart hook output — not a human action"}]}}
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"This session is being continued from a previous conversation. Summary: we were doing things."}}
+{"type":"user","timestamp":"2026-05-01T10:01:00Z","message":{"role":"user","content":"Real prompt one"}}
+{"type":"assistant","timestamp":"2026-05-01T10:02:00Z","message":{"role":"assistant","content":[{"type":"tool_use","name":"Read","input":{"file_path":"x"},"id":"t9"}]}}
+{"type":"user","timestamp":"2026-05-01T10:03:00Z","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"t9","content":"file contents"}]}}
+{"type":"user","timestamp":"2026-05-01T10:05:00Z","isMeta":true,"message":{"role":"user","content":[{"type":"text","text":"Skill expansion injected text"}]}}
+{"type":"user","timestamp":"2026-05-01T10:06:00Z","message":{"role":"user","content":"Real prompt two"}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/engagement-parallel-a.jsonl

@@ -0,0 +1,3 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"Chat A start"}}
+{"type":"assistant","timestamp":"2026-05-01T10:01:00Z","message":{"role":"assistant","content":[{"type":"text","text":"Working in A."}]}}
+{"type":"user","timestamp":"2026-05-01T10:30:00Z","message":{"role":"user","content":"Chat A follow-up"}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/engagement-parallel-b.jsonl

@@ -0,0 +1,3 @@
+{"type":"user","timestamp":"2026-05-01T10:10:00Z","message":{"role":"user","content":"Chat B start"}}
+{"type":"assistant","timestamp":"2026-05-01T10:11:00Z","message":{"role":"assistant","content":[{"type":"text","text":"Working in B."}]}}
+{"type":"user","timestamp":"2026-05-01T10:20:00Z","message":{"role":"user","content":"Chat B follow-up"}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/engagement-waiting.jsonl

@@ -0,0 +1,5 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"Run the long migration"}}
+{"type":"assistant","timestamp":"2026-05-01T10:02:00Z","message":{"role":"assistant","content":[{"type":"tool_use","name":"Bash","input":{"command":"migrate"},"id":"t1"}]}}
+{"type":"user","timestamp":"2026-05-01T10:15:00Z","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"t1","content":"step 1 done"}]}}
+{"type":"assistant","timestamp":"2026-05-01T10:30:00Z","message":{"role":"assistant","content":[{"type":"text","text":"Migration finished."}]}}
+{"type":"user","timestamp":"2026-05-01T10:32:00Z","message":{"role":"user","content":"Great, now verify it"}}

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

@@ -0,0 +1,239 @@
+"""Tests for the engagement mode (attention-time accounting)."""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timedelta
+
+import pytest
+
+import read_transcript as RT
+from lib import parser as PR
+
+
+def _run_cli(cli_path, *args, env_overrides=None):
+    env = dict(os.environ)
+    env["PYTHONIOENCODING"] = "utf-8"
+    if env_overrides:
+        env.update(env_overrides)
+    return subprocess.run(
+        [sys.executable, str(cli_path), *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        env=env,
+    )
+
+
+@pytest.fixture
+def utc_tz():
+    PR.set_timezone("UTC")
+    yield
+    PR.set_timezone(None)
+
+
+def _fake_root(tmp_path, **projects):
+    """Build a fake projects root: {project_dir_name: [(fixture, uuid), ...]}."""
+    root = tmp_path / "projects"
+    for proj_name, files in projects.items():
+        pd = root / proj_name
+        pd.mkdir(parents=True)
+        for src, uuid in files:
+            shutil.copy(src, pd / f"{uuid}.jsonl")
+    return root
+
+
+def _build(root, **kw):
+    defaults = dict(
+        report_dirs=None,
+        report_file=None,
+        since=datetime(2026, 5, 1),
+        until=datetime(2026, 5, 2),
+        break_minutes=10,
+        current_uuid=None,
+    )
+    defaults.update(kw)
+    return RT.build_engagement(root, **defaults)
+
+
+# ── unit: gap math ───────────────────────────────────────────────────────────
+
+def test_gaps_straddle_threshold(fixtures_dir, tmp_path, utc_tz):
+    root = _fake_root(
+        tmp_path, **{"C--proj-a": [(fixtures_dir / "engagement-gaps.jsonl", "aaaa1111")]}
+    )
+    data = _build(root)
+    (s,) = data["sessions"].values()
+    # 5m + 3m active, 32m break (Claude finished 10:09, reply 10:40 — too late),
+    # then 5m active = 13m.
+    assert s["active"] == timedelta(minutes=13)
+    assert s["user_messages"] == 5
+    assert len(data["breaks"]) == 1
+    assert data["breaks"][0][0] == datetime(2026, 5, 1, 10, 8)
+    assert data["breaks"][0][1] == datetime(2026, 5, 1, 10, 40)
+
+
+def test_waiting_on_claude_credit(fixtures_dir, tmp_path, utc_tz):
+    root = _fake_root(
+        tmp_path, **{"C--proj-a": [(fixtures_dir / "engagement-waiting.jsonl", "bbbb2222")]}
+    )
+    data = _build(root)
+    (s,) = data["sessions"].values()
+    # 32m gap, but Claude's last event was 10:30 and the user replied 10:32
+    # (2m ≤ 10m) — the whole gap counts as waiting-on-Claude.
+    assert s["active"] == timedelta(minutes=32)
+    assert data["breaks"] == []
+
+
+def test_noise_exclusion(fixtures_dir, tmp_path, utc_tz):
+    root = _fake_root(
+        tmp_path, **{"C--proj-a": [(fixtures_dir / "engagement-noise.jsonl", "cccc3333")]}
+    )
+    data = _build(root)
+    (s,) = data["sessions"].values()
+    # Only the two real prompts (10:01, 10:06) count: compact continuation,
+    # isMeta injections, and tool results are all excluded from the user stream.
+    assert s["user_messages"] == 2
+    assert s["first"] == datetime(2026, 5, 1, 10, 1)
+    assert s["active"] == timedelta(minutes=5)
+
+
+def test_parallel_sessions_never_double_count(fixtures_dir, tmp_path, utc_tz):
+    root = _fake_root(
+        tmp_path,
+        **{
+            "C--proj-a": [(fixtures_dir / "engagement-parallel-a.jsonl", "aaaa1111")],
+            "C--proj-b": [(fixtures_dir / "engagement-parallel-b.jsonl", "bbbb2222")],
+        },
+    )
+    data = _build(root)
+    by_uuid = {s["summary"]["uuid"]: s for s in data["sessions"].values()}
+    # Stream: 10:00 A, 10:10 B, 10:20 B, 10:30 A. Each segment goes to the
+    # session of the LATER prompt: B gets 10:00–10:20 (20m), A gets 10:20–10:30
+    # (10m). Total 30m == wall clock, not the naive 40m.
+    assert by_uuid["bbbb2222"]["active"] == timedelta(minutes=20)
+    assert by_uuid["aaaa1111"]["active"] == timedelta(minutes=10)
+    total = sum((s["active"] for s in data["sessions"].values()), timedelta())
+    assert total == timedelta(minutes=30)
+
+
+def test_single_message_session(tmp_path, utc_tz):
+    root = tmp_path / "projects"
+    pd = root / "C--proj-a"
+    pd.mkdir(parents=True)
+    (pd / "dddd4444.jsonl").write_text(
+        '{"type":"user","timestamp":"2026-05-01T10:00:00Z",'
+        '"message":{"role":"user","content":"one and done"}}\n',
+        encoding="utf-8",
+    )
+    data = _build(root)
+    (s,) = data["sessions"].values()
+    assert s["active"] == timedelta(0)
+    assert s["user_messages"] == 1
+
+
+def test_report_scope_filters_but_stream_stays_global(fixtures_dir, tmp_path, utc_tz):
+    root = _fake_root(
+        tmp_path,
+        **{
+            "C--proj-a": [(fixtures_dir / "engagement-parallel-a.jsonl", "aaaa1111")],
+            "C--proj-b": [(fixtures_dir / "engagement-parallel-b.jsonl", "bbbb2222")],
+        },
+    )
+    data = _build(root, report_dirs=[root / "C--proj-a"])
+    # Only A is reported, but B's prompts still split the stream — A gets its
+    # interval-correct 10m, not a naive 30m.
+    (s,) = data["sessions"].values()
+    assert s["summary"]["uuid"] == "aaaa1111"
+    assert s["active"] == timedelta(minutes=10)
+
+
+# ── CLI ──────────────────────────────────────────────────────────────────────
+
+def test_engagement_cli_text(cli_path, fixtures_dir, tmp_path):
+    root = _fake_root(
+        tmp_path, **{"C--proj-a": [(fixtures_dir / "engagement-gaps.jsonl", "aaaa1111")]}
+    )
+    r = _run_cli(
+        cli_path, "--root", str(root), "--tz", "UTC",
+        "--mode", "engagement", "--date", "2026-05-01",
+    )
+    assert r.returncode == 0
+    assert "13m" in r.stdout
+    assert "break=10m" in r.stdout
+    assert "Breaks >10m" in r.stdout
+
+
+def test_engagement_cli_json(cli_path, fixtures_dir, tmp_path):
+    root = _fake_root(
+        tmp_path, **{"C--proj-a": [(fixtures_dir / "engagement-gaps.jsonl", "aaaa1111")]}
+    )
+    r = _run_cli(
+        cli_path, "--root", str(root), "--tz", "UTC",
+        "--mode", "engagement", "--date", "2026-05-01", "--format", "json",
+    )
+    assert r.returncode == 0
+    data = json.loads(r.stdout)
+    assert data["break_minutes"] == 10
+    assert data["totals"]["active_minutes"] == 13
+    assert data["totals"]["sessions"] == 1
+    s = data["sessions"][0]
+    assert s["uuid"] == "aaaa1111"
+    assert s["elapsed_minutes"] == 45
+    assert s["ratio"] == round(13 / 45, 2)
+    assert len(data["stream_breaks"]) == 1
+    assert data["stream_breaks"][0]["minutes"] == 32
+
+
+def test_engagement_cli_file_window_derived(cli_path, fixtures_dir, tmp_path):
+    root = _fake_root(
+        tmp_path, **{"C--proj-a": [(fixtures_dir / "engagement-waiting.jsonl", "bbbb2222")]}
+    )
+    f = root / "C--proj-a" / "bbbb2222.jsonl"
+    r = _run_cli(
+        cli_path, "--root", str(root), "--tz", "UTC",
+        "--mode", "engagement", "--file", str(f),
+    )
+    assert r.returncode == 0
+    assert "32m" in r.stdout
+    assert "Prompt gaps" in r.stdout
+
+
+def test_engagement_cli_custom_break(cli_path, fixtures_dir, tmp_path):
+    root = _fake_root(
+        tmp_path, **{"C--proj-a": [(fixtures_dir / "engagement-gaps.jsonl", "aaaa1111")]}
+    )
+    r = _run_cli(
+        cli_path, "--root", str(root), "--tz", "UTC",
+        "--mode", "engagement", "--date", "2026-05-01",
+        "--break", "1h", "--format", "json",
+    )
+    assert r.returncode == 0
+    data = json.loads(r.stdout)
+    # 1h threshold swallows the 32m gap — everything is active: 45m.
+    assert data["totals"]["active_minutes"] == 45
+    assert data["stream_breaks"] == []
+
+
+def test_engagement_cli_invalid_break(cli_path, tmp_path):
+    root = tmp_path / "projects"
+    root.mkdir()
+    r = _run_cli(
+        cli_path, "--root", str(root),
+        "--mode", "engagement", "--break", "soon",
+    )
+    assert r.returncode == 1
+
+
+def test_engagement_cli_empty_range(cli_path, fixtures_dir, tmp_path):
+    root = _fake_root(
+        tmp_path, **{"C--proj-a": [(fixtures_dir / "engagement-gaps.jsonl", "aaaa1111")]}
+    )
+    r = _run_cli(
+        cli_path, "--root", str(root), "--tz", "UTC",
+        "--mode", "engagement", "--date", "2020-01-01",
+    )
+    assert r.returncode == 0
+    assert "no user messages" in r.stdout

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

@@ -112,7 +112,9 @@ def test_timeline_cli_text(cli_path, fake_root):
     assert "10:00" in r.stdout
     assert "12:02" in r.stdout
     assert "idle" in r.stdout
-    assert "2 active block(s)" in r.stdout
+    assert "2 block(s)" in r.stdout
+    # Timeline makes no attention claim — that's engagement mode's job.
+    assert "active" not in r.stdout
 
 
 def test_timeline_cli_json(cli_path, fake_root):
@@ -124,6 +126,8 @@ def test_timeline_cli_json(cli_path, fake_root):
     data = json.loads(r.stdout)
     assert data["totals"]["blocks"] == 2
     assert data["totals"]["sessions"] == 1
+    assert data["totals"]["span_minutes"] == 122  # 10:00 → 12:02
+    assert "active_minutes" not in data["totals"]
     assert data["blocks"][0]["start"].endswith("10:00:00")
     assert data["blocks"][0]["sessions"][0]["uuid"] == "abc12345"