elliot-stack 1.0.18 → 1.0.20

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

@@ -0,0 +1,40 @@
+"""Shared pytest fixtures and import-path setup."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+
+# Ensure UTF-8 output regardless of console code page (Windows)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != "utf-8":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, OSError):
+        pass
+
+
+THIS_DIR = Path(__file__).resolve().parent
+SCRIPTS_DIR = THIS_DIR.parent
+FIXTURES_DIR = THIS_DIR / "fixtures"
+
+# Make `from lib...` work in tests
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+
+@pytest.fixture
+def fixtures_dir() -> Path:
+    return FIXTURES_DIR
+
+
+@pytest.fixture
+def scripts_dir() -> Path:
+    return SCRIPTS_DIR
+
+
+@pytest.fixture
+def cli_path() -> Path:
+    return SCRIPTS_DIR / "read_transcript.py"

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/README.md

@@ -0,0 +1,20 @@
+# Test fixtures
+
+Hand-crafted minimal JSONL files, one scenario per file. Keep them small (≤50 lines) — they're easier to reason about than real session snapshots and don't carry PII.
+
+| File | Purpose |
+|---|---|
+| `basic-session.jsonl` | One user + one assistant exchange. Sanity check for the parser. |
+| `with-compact.jsonl` | Conversation interrupted by a single `/compact` marker. |
+| `multi-compact.jsonl` | Two `/compact` markers — exercises "most recent" logic. |
+| `with-advisor.jsonl` | Contains an `advisor_tool_result` block. |
+| `with-thinking.jsonl` | Contains a `thinking` block plus normal text. |
+| `all-noise.jsonl` | Only `ai-title` + `attachment` entries — should look empty to signal queries. |
+| `subagent-parent.jsonl` | Parent session that spawns one subagent via the `Agent` tool. |
+| `subagent-no-meta.jsonl` | Parent session with a sibling subagent file but no `.meta.json` sidecar — `load_meta` must fall back. |
+| `tool-zoo.jsonl` | One call to each of Bash, Read, Edit, Write, Agent, Skill, Glob, Grep. |
+| `time-spread.jsonl` | Six messages over a known time range — exercises `--since`/`--until`. |
+| `truncated.jsonl` | Final line is missing its newline AND is malformed JSON — should be dropped silently. |
+| `unicode.jsonl` | Contains emoji + CJK characters — exercises UTF-8 decoding. |
+| `pending-user.jsonl` | Last assistant message ends with `?` — `infer_status` should return `pending-user`. |
+| `interrupted.jsonl` | Final assistant message has a `tool_use` block with no matching `tool_result` — status `interrupted`. |

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

@@ -0,0 +1,4 @@
+{"type":"ai-title","aiTitle":"Test session"}
+{"type":"attachment","data":{"path":"foo.png"}}
+{"type":"permission-mode","mode":"plan"}
+{"type":"file-history-snapshot","content":{"file":"bar.py"}}

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

@@ -0,0 +1,2 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"Hello Claude"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:05Z","message":{"role":"assistant","content":[{"type":"text","text":"Hi there. Here is help."}]}}

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/fixtures/interrupted.jsonl

@@ -0,0 +1,2 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"Run a tool"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:05Z","message":{"role":"assistant","content":[{"type":"text","text":"Running."},{"type":"tool_use","id":"toolu_999","name":"Bash","input":{"command":"sleep 999"}}]}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/multi-compact.jsonl

@@ -0,0 +1,8 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"First"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:05Z","message":{"role":"assistant","content":[{"type":"text","text":"R1"}]}}
+{"type":"user","timestamp":"2026-05-01T10:30:00Z","message":{"role":"user","content":"This session is being continued from a previous conversation. Round 1"}}
+{"type":"user","timestamp":"2026-05-01T11:00:00Z","message":{"role":"user","content":"Mid"}}
+{"type":"assistant","timestamp":"2026-05-01T11:00:05Z","message":{"role":"assistant","content":[{"type":"text","text":"R2"}]}}
+{"type":"user","timestamp":"2026-05-01T11:30:00Z","message":{"role":"user","content":"This session is being continued from a previous conversation. Round 2"}}
+{"type":"user","timestamp":"2026-05-01T12:00:00Z","message":{"role":"user","content":"Last"}}
+{"type":"assistant","timestamp":"2026-05-01T12:00:05Z","message":{"role":"assistant","content":[{"type":"text","text":"R3"}]}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/pending-user.jsonl

@@ -0,0 +1,2 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"Hello"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:05Z","message":{"role":"assistant","content":[{"type":"text","text":"Sure, do you want me to A, B, or C?"}]}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/subagent-no-meta/subagents/agent-aaa.jsonl

@@ -0,0 +1,2 @@
+{"type":"user","timestamp":"2026-05-01T10:00:10Z","message":{"role":"user","content":"Do thing"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:20Z","message":{"role":"assistant","content":[{"type":"text","text":"Done."}]}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/subagent-no-meta.jsonl

@@ -0,0 +1,2 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"Run an agent"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:05Z","message":{"role":"assistant","content":[{"type":"text","text":"Agent ran."}]}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/subagent-parent/subagents/agent-xyz123.jsonl

@@ -0,0 +1,2 @@
+{"type":"user","timestamp":"2026-05-01T10:00:10Z","message":{"role":"user","content":"Find the bug in foo.py"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:20Z","message":{"role":"assistant","content":[{"type":"text","text":"Found it: foo.py line 42 — off-by-one in loop bound."}]}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/subagent-parent/subagents/agent-xyz123.meta.json

@@ -0,0 +1 @@
+{"agentType": "Explore", "description": "Find the bug in foo.py"}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/subagent-parent.jsonl

@@ -0,0 +1,4 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"Investigate the bug"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:05Z","message":{"role":"assistant","content":[{"type":"tool_use","id":"toolu_01abc","name":"Agent","input":{"description":"Find the bug","prompt":"Look at file X","subagent_type":"Explore"}}]}}
+{"type":"user","timestamp":"2026-05-01T10:00:30Z","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_01abc","content":"Found it in foo.py:42"}]}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:35Z","message":{"role":"assistant","content":[{"type":"text","text":"Got the report, patching foo.py."}]}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/time-spread.jsonl

@@ -0,0 +1,6 @@
+{"type":"user","timestamp":"2026-04-15T08:00:00Z","message":{"role":"user","content":"Apr 15 morning"}}
+{"type":"assistant","timestamp":"2026-04-15T08:00:05Z","message":{"role":"assistant","content":[{"type":"text","text":"Apr 15 reply"}]}}
+{"type":"user","timestamp":"2026-05-01T12:00:00Z","message":{"role":"user","content":"May 1 noon"}}
+{"type":"assistant","timestamp":"2026-05-01T12:00:05Z","message":{"role":"assistant","content":[{"type":"text","text":"May 1 reply"}]}}
+{"type":"user","timestamp":"2026-05-15T20:00:00Z","message":{"role":"user","content":"May 15 evening"}}
+{"type":"assistant","timestamp":"2026-05-15T20:00:05Z","message":{"role":"assistant","content":[{"type":"text","text":"May 15 reply"}]}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/timeline-day-test.jsonl

@@ -0,0 +1,5 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"Start the CRM cleanup"}}
+{"type":"assistant","timestamp":"2026-05-01T10:05:00Z","message":{"role":"assistant","content":[{"type":"text","text":"Working on it."}]}}
+{"type":"assistant","timestamp":"2026-05-01T10:08:00Z","message":{"role":"assistant","content":[{"type":"text","text":"First pass done."}]}}
+{"type":"user","timestamp":"2026-05-01T12:00:00Z","message":{"role":"user","content":"Back — continue"}}
+{"type":"assistant","timestamp":"2026-05-01T12:02:00Z","message":{"role":"assistant","content":[{"type":"text","text":"Resumed and finished."}]}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/tool-zoo.jsonl

@@ -0,0 +1,10 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"Run all the tools"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:01Z","message":{"role":"assistant","content":[{"type":"tool_use","id":"t1","name":"Bash","input":{"command":"ls -la /tmp"}}]}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:02Z","message":{"role":"assistant","content":[{"type":"tool_use","id":"t2","name":"PowerShell","input":{"command":"Get-ChildItem"}}]}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:03Z","message":{"role":"assistant","content":[{"type":"tool_use","id":"t3","name":"Read","input":{"file_path":"C:\\foo.py","offset":1,"limit":50}}]}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:04Z","message":{"role":"assistant","content":[{"type":"tool_use","id":"t4","name":"Edit","input":{"file_path":"C:\\foo.py","old_string":"a","new_string":"b"}}]}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:05Z","message":{"role":"assistant","content":[{"type":"tool_use","id":"t5","name":"Write","input":{"file_path":"C:\\bar.py","content":"print('hi')"}}]}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:06Z","message":{"role":"assistant","content":[{"type":"tool_use","id":"t6","name":"Agent","input":{"description":"Find X","subagent_type":"Explore"}}]}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:07Z","message":{"role":"assistant","content":[{"type":"tool_use","id":"t7","name":"Skill","input":{"skill":"using-superpowers"}}]}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:08Z","message":{"role":"assistant","content":[{"type":"tool_use","id":"t8","name":"Glob","input":{"pattern":"**/*.py"}}]}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:09Z","message":{"role":"assistant","content":[{"type":"tool_use","id":"t9","name":"Grep","input":{"pattern":"TODO"}}]}}

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

@@ -0,0 +1,3 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"Valid line"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:05Z","message":{"role":"assistant","content":[{"type":"text","text":"Valid reply"}]}}
+{"type":"user","timestamp":"2026-05-01T10:01:00Z","message":{"role":"user","content":"Trunc

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

@@ -0,0 +1,2 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"Hello 🌍, 你好"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:05Z","message":{"role":"assistant","content":[{"type":"text","text":"Привет — 안녕하세요!"}]}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/with-advisor.jsonl

@@ -0,0 +1,3 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"Get advice"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:05Z","message":{"role":"assistant","content":[{"type":"text","text":"Calling advisor..."},{"type":"advisor_tool_result","content":{"text":"The advisor says do X then Y."}}]}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:10Z","message":{"role":"assistant","content":[{"type":"text","text":"OK, doing X."}]}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/with-compact.jsonl

@@ -0,0 +1,5 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"First question"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:05Z","message":{"role":"assistant","content":[{"type":"text","text":"First answer"}]}}
+{"type":"user","timestamp":"2026-05-01T11:00:00Z","message":{"role":"user","content":"This session is being continued from a previous conversation. Summary follows..."}}
+{"type":"user","timestamp":"2026-05-01T11:00:10Z","message":{"role":"user","content":"After compact"}}
+{"type":"assistant","timestamp":"2026-05-01T11:00:15Z","message":{"role":"assistant","content":[{"type":"text","text":"Post-compact reply"}]}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/with-thinking.jsonl

@@ -0,0 +1,2 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"Solve this"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:05Z","message":{"role":"assistant","content":[{"type":"thinking","thinking":"Let me think step by step..."},{"type":"text","text":"The answer is 42."}]}}

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

@@ -0,0 +1,56 @@
+"""Tests for backup-root resolution (--root mirror|snapshot-*|<abs-path>)."""
+
+from pathlib import Path
+
+import pytest
+
+from lib import paths as P
+
+
+def test_root_live_default():
+    assert P.resolve_root(None) == P.DEFAULT_LIVE_PROJECTS
+    assert P.resolve_root("live") == P.DEFAULT_LIVE_PROJECTS
+
+
+def test_root_mirror_path_shape():
+    r = P.resolve_root("mirror")
+    parts = r.parts
+    assert ".claude-backups" in parts
+    assert "mirror" in parts
+    assert parts[-1] == "projects"
+
+
+def test_root_snapshot_24h_path_shape():
+    r = P.resolve_root("snapshot-24h")
+    assert "snapshot-24h" in r.parts
+    assert r.name == "projects"
+
+
+def test_root_all_known():
+    for name in ("mirror", "snapshot-24h", "snapshot-1w", "snapshot-1mo"):
+        r = P.resolve_root(name)
+        assert name in r.parts
+
+
+def test_root_absolute_path(tmp_path: Path):
+    fake = tmp_path / "weird-root"
+    fake.mkdir()
+    assert P.resolve_root(str(fake)) == fake
+
+
+def test_root_unknown_relative_raises():
+    with pytest.raises(ValueError):
+        P.resolve_root("bogus")
+
+
+def test_find_project_dir_uses_root(tmp_path: Path):
+    # Build a fake root with a fake project dir
+    proj = tmp_path / "C--Users-foo-bar"
+    proj.mkdir()
+    found = P.find_project_dir("C:\\Users\\foo\\bar", root=tmp_path)
+    assert found == proj
+
+
+def test_find_project_dir_not_found(tmp_path: Path):
+    with pytest.raises(FileNotFoundError):
+        P.find_project_dir("C:\\does\\not\\exist", root=tmp_path)

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