elliot-stack 1.0.40 → 1.0.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elliot-stack",
-  "version": "1.0.40",
+  "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-read-claude-session-history/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: estack-read-claude-session-history
-version: 1.3.0
+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,
@@ -80,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
 
 ```
@@ -231,7 +238,7 @@ When the user asks a natural-language "what did I do" / "review my day" / "break
 - **One to two sentences per session** describing what they did and why — synthesized from the `intent` + `last` + files, not a raw dump of either. The mode hands you the inputs; you write the sentence.
 - **Show both clocks and name the overlap.** `active` is deduped attention (parallel chats never double-counted); `ran`/elapsed is the session's own first→last span and *will* overlap others. Say so once — users work on several things at once and want the overlap reflected in the span but removed from active minutes.
 - **Counts are clean already.** `you N msgs` is real typed prompts (tool-results and hook/skill injections excluded); `assistant N msgs` is text replies (tool-only turns excluded). Do NOT hand-count raw `type:user`/`type:assistant` entries from the .jsonl — that over-counts both (tool-result envelopes inflate "user"; multi-block turns inflate "assistant"). Trust the mode's numbers.
-- **24-hour time** as the CLI emits it; convert only if the user asks.
+- **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.

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:

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)
@@ -1376,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)"
@@ -1396,7 +1409,7 @@ def render_engagement(data: dict, tz_label: str) -> str:
         out.append(
             f"{_fmt_dur(s['active']):>7}  ratio {ratio}  "
             f"you {s['user_messages']:<3} ai {s['assistant_messages']:<4} "
-            f"{s['first'].strftime(tfmt)}–{s['last'].strftime('%H:%M')}  "
+            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())
@@ -1405,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 ""
@@ -1502,10 +1515,9 @@ 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)
-    tfmt = "%Y-%m-%d %H:%M" if multi_day else "%H:%M"
     head = (
-        f"=== Session report {since:%Y-%m-%d %H:%M} → {until:%Y-%m-%d %H:%M} "
-        f"(times: {tz_label}, break={data['break_minutes']}m) ==="
+        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)"
@@ -1518,7 +1530,7 @@ def render_session_report(data: dict, tz_label: str) -> str:
         out.append(f"{i}. {title}")
         out.append(
             f"   {summary['decoded_project']}  ·  "
-            f"{s['first'].strftime(tfmt)}–{s['last'].strftime('%H:%M')}  "
+            f"{_fmt_clock(s['first'], multi_day)}–{_fmt_tod(s['last'])}  "
             f"(ran {_fmt_dur(elapsed)} · active {_fmt_dur(s['active'])})"
         )
         out.append(
@@ -1535,7 +1547,7 @@ def render_session_report(data: dict, tz_label: str) -> str:
     out.append(
         f"Total: {len(sessions)} session(s) · {_fmt_dur(total_active)} active "
         f"(overlap removed) across a {_fmt_dur(last - first)} span "
-        f"({first.strftime(tfmt)}–{last.strftime('%H:%M')})."
+        f"({_fmt_clock(first, multi_day)}–{_fmt_tod(last)})."
     )
     out.append(
         "(active = your attention, parallel chats never double-counted; "