@rm0nroe/coach-claw 1.0.6

package/coach/bin/insights-llm.sh

@@ -0,0 +1,264 @@
+#!/bin/bash
+# Coach Claw — LLM-triggered weekly insights pass.
+#
+# Pipeline:
+#   1. Generate a unique RUN_ID with the `insights-weekly-` prefix so
+#      downstream consumers (changelog, recent_runs) can distinguish from
+#      the daily deterministic path's `insights-<ts>` runs.
+#   2. Invoke `claude -p "/insights"` with COACH_DISABLE=1 to refresh
+#      Anthropic-side facets/*.json sidecars. The CLI's stdout is
+#      DISCARDED — we run it for the side effect on disk only.
+#   3. Aggregate the refreshed facets via aggregate_facets.py (pure
+#      Python, deterministic) → detections JSON.
+#   4. Hand to merge.py. Same merge logic as the daily path. No schema
+#      change. Run-id prefix is the only discriminator.
+#   5. Auto-commit + touch .last_weekly_insights to throttle the
+#      SessionStart trigger to ≥7 days.
+#
+# Flags:
+#   --dry-run    aggregate + print detections JSON; do not call merge.py
+#                or touch the throttle marker.
+#   --force      run even if .last_weekly_insights mtime is < 7 days ago.
+#                Without this flag the script exits 0 silently when the
+#                throttle is fresh.
+#
+# Exit codes:
+#   0   success (full run completed, or skipped on stale-marker throttle,
+#       or skipped on --dry-run after printing detections)
+#   2   python3 not on PATH (or unknown CLI arg)
+#   4   merge.py failed
+#   5   aggregate_facets.py failed (nonzero exit OR unparseable JSON);
+#       wrapper bails BEFORE merge + marker touch so the next session
+#       can retry from scratch
+#   6   LLM refresh step failed (claude missing / nonzero exit / timeout);
+#       wrapper bails BEFORE merge + marker touch. Same reasoning as
+#       exit 5 — without a successful refresh, aggregating stale or
+#       empty facets and merging the result would advance absence-based
+#       streaks on phantom evidence.
+#   7   no current-window evidence (n_sessions == 0 in window); wrapper
+#       bails BEFORE merge + marker touch. Aggregator emits exit 3
+#       (EXIT_NO_EVIDENCE) for this case; wrapper translates to 7. An
+#       empty detections list with zero sessions in window is "no
+#       evidence," which must NOT advance absence-based streaks. (Empty
+#       detections WITH n_sessions > 0 IS valid — a clean week — and
+#       merges normally.)
+#   10  concurrent run already in progress (lock held by another
+#       insights-llm.sh on the same .weekly_insights.lock); emitted by
+#       run_with_lock.py during the at-startup re-exec. The losing
+#       wrapper exits cleanly without invoking aggregator/merge.
+#
+# Cross-platform notes:
+#   - Resolves python3 from PATH (no /usr/bin/python3 hardcode).
+#   - mktemp templates use trailing Xs (BSD-safe, see CLAUDE.md gotcha).
+#   - Date math is delegated to Python — no BSD-vs-GNU `date` flag drift.
+
+set -uo pipefail
+
+# Plugin-context PATH wedge: when invoked from inside a Claude Code
+# plugin install (CLAUDE_PLUGIN_DATA env var set + venv exists),
+# prepend the plugin's venv bin/ to PATH so subsequent `python3`
+# resolutions in this script (and child python processes) pick up
+# the venv's interpreter — and therefore PyYAML. CLI users never
+# have CLAUDE_PLUGIN_DATA set; this is a no-op for them. See
+# artifacts/e2e-validation-2026-05-09.md for context.
+if [[ -n "${CLAUDE_PLUGIN_DATA:-}" && -x "$CLAUDE_PLUGIN_DATA/venv/bin/python3" ]]; then
+  export PATH="$CLAUDE_PLUGIN_DATA/venv/bin:$PATH"
+fi
+
+# Resolve env-derived paths + python BEFORE arg parsing so the
+# concurrent-run guard can re-exec us with the original argv.
+COACH_DIR="${COACH_DIR_OVERRIDE:-$HOME/.claude/coach}"
+THROTTLE_MARKER="$COACH_DIR/.last_weekly_insights"
+FACETS_DIR="${COACH_FACETS_DIR:-$HOME/.claude/usage-data/facets}"
+
+# Resolve sibling scripts via the shipping bash file's own location, not via
+# COACH_DIR. Lets the test suite point COACH_DIR_OVERRIDE at a throwaway
+# tmpdir while still loading aggregate_facets.py/merge.py from the installed
+# (or source-tree) bin/ next to this script.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+PY="$(command -v python3 || true)"
+if [[ -z "$PY" ]]; then
+  echo "python3 not found in PATH" >&2
+  exit 2
+fi
+
+# --- Concurrent-run guard --------------------------------------------------
+# Two SessionStart hooks firing within the slow `claude -p "/insights"`
+# window will both see `.last_weekly_insights` as stale and try to spawn
+# this wrapper. Re-exec ourselves through `run_with_lock.py` so the
+# second invocation either sees the post-refresh fresh marker (under
+# the lock, after the first finishes) and skips on throttle, or hits
+# the lock itself and skips on contention. Either way, exactly one
+# wrapper does the LLM call + merge.
+#
+# Must precede arg parsing — otherwise `"$@"` is empty after the parse
+# loop and the re-execed copy can't see --dry-run / --force.
+#
+# COACH_LLM_LOCK_HELD=1 is the re-entry sentinel — set by
+# run_with_lock.py on the wrapped process so we don't loop.
+if [[ -z "${COACH_LLM_LOCK_HELD:-}" ]]; then
+  mkdir -p "$COACH_DIR" 2>/dev/null
+  exec "$PY" "$SCRIPT_DIR/run_with_lock.py" \
+    "$COACH_DIR/.weekly_insights.lock" \
+    bash "${BASH_SOURCE[0]}" "$@"
+fi
+
+# --- Below this line we hold the weekly-insights lock ---------------------
+
+DRY_RUN=0
+FORCE=0
+TIMEOUT_SECS="${COACH_INSIGHTS_LLM_TIMEOUT:-300}"
+THROTTLE_DAYS="${COACH_INSIGHTS_LLM_THROTTLE_DAYS:-7}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run) DRY_RUN=1; shift ;;
+    --force)   FORCE=1;   shift ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+# RUN_ID generation is inside the lock so two retried invocations of
+# the same SessionStart wave can't stamp identical timestamps if the
+# system clock resolves at one-second granularity.
+RUN_ID="insights-weekly-$(date -u +%Y%m%dT%H%M%SZ)"
+
+# --- Throttle check (skipped on --force / --dry-run) -----------------------
+if [[ "$FORCE" -eq 0 && "$DRY_RUN" -eq 0 ]]; then
+  if [[ -f "$THROTTLE_MARKER" ]]; then
+    AGE_SECS="$("$PY" - "$THROTTLE_MARKER" <<'PY'
+import os, sys, time
+try:
+    mtime = os.path.getmtime(sys.argv[1])
+    print(int(time.time() - mtime))
+except Exception:
+    print(-1)
+PY
+)"
+    THROTTLE_SECS=$(( THROTTLE_DAYS * 86400 ))
+    if [[ "$AGE_SECS" -ge 0 && "$AGE_SECS" -lt "$THROTTLE_SECS" ]]; then
+      echo "skipped (throttle: last run ${AGE_SECS}s ago, threshold ${THROTTLE_SECS}s)"
+      exit 0
+    fi
+  fi
+fi
+
+echo "run_id=$RUN_ID dry_run=$DRY_RUN force=$FORCE timeout=${TIMEOUT_SECS}s"
+
+# --- Step 1: refresh facets via /insights subprocess -----------------------
+# We discard stdout/stderr — only the side effect on facets/*.json matters.
+# COACH_DISABLE=1 prevents the nested Claude session from loading Coach's
+# own hooks (which would contaminate the analysis).
+#
+# COACH_INSIGHTS_LLM_SKIP_REFRESH=1 lets tests bypass the subprocess and
+# operate on a pre-seeded fixture facets dir.
+if [[ -z "${COACH_INSIGHTS_LLM_SKIP_REFRESH:-}" ]]; then
+  CLAUDE_BIN="$(command -v claude || true)"
+  if [[ -z "$CLAUDE_BIN" ]]; then
+    # Fail-hard: aggregating stale-or-empty facets and merging the result
+    # would touch .last_weekly_insights and advance absence-based streaks
+    # on phantom evidence. Mirror the aggregator-fail-hard treatment
+    # below — bail before merge so the next session retries cleanly.
+    echo "claude CLI not on PATH — bailing before merge (LLM refresh failed)" >&2
+    exit 6
+  fi
+  # POSIX-portable timeout: spawn claude in background, kill if it
+  # outlives TIMEOUT_SECS. macOS has no `timeout` builtin and `gtimeout`
+  # may not be installed.
+  (
+    COACH_DISABLE=1 "$CLAUDE_BIN" -p "/insights" > /dev/null 2>&1
+  ) &
+  CLAUDE_PID=$!
+  SECS=0
+  TIMED_OUT=0
+  while kill -0 "$CLAUDE_PID" 2>/dev/null; do
+    sleep 2
+    SECS=$((SECS + 2))
+    if [[ "$SECS" -ge "$TIMEOUT_SECS" ]]; then
+      kill -TERM "$CLAUDE_PID" 2>/dev/null
+      sleep 2
+      kill -KILL "$CLAUDE_PID" 2>/dev/null
+      TIMED_OUT=1
+      break
+    fi
+  done
+  wait "$CLAUDE_PID" 2>/dev/null
+  CLAUDE_RC=$?
+  if [[ "$TIMED_OUT" -eq 1 ]]; then
+    echo "claude -p /insights timed out after ${TIMEOUT_SECS}s — bailing before merge (LLM refresh failed)" >&2
+    exit 6
+  fi
+  if [[ "$CLAUDE_RC" -ne 0 ]]; then
+    echo "claude -p /insights exited rc=$CLAUDE_RC — bailing before merge (LLM refresh failed)" >&2
+    exit 6
+  fi
+fi
+
+# --- Step 2: aggregate facets → detections JSON ----------------------------
+DET="$(mktemp /tmp/coach-weekly-detections-XXXXXX)"
+trap 'rm -f "$DET"' EXIT
+
+COACH_FACETS_DIR="$FACETS_DIR" "$PY" "$SCRIPT_DIR/aggregate_facets.py" \
+  --window-days "$THROTTLE_DAYS" \
+  > "$DET"
+AGG_RC=$?
+if [[ "$AGG_RC" -eq 3 ]]; then
+  # Aggregator's EXIT_NO_EVIDENCE: n_sessions == 0 in the requested
+  # window. Treat the same as any other "bail before merge" case —
+  # don't merge, don't touch the throttle marker. The next session
+  # retries from a fresh facets read. Distinct wrapper exit 7 so ops
+  # can see "no evidence" vs "aggregator crashed" in logs.
+  echo "no current-window evidence (n_sessions=0) — bailing before merge" >&2
+  exit 7
+fi
+if [[ "$AGG_RC" -ne 0 ]]; then
+  # Aggregator failure → bail BEFORE merge and BEFORE touching the
+  # throttle marker. A nonzero aggregator may have written a partial
+  # or empty $DET; merging that as `[]` would commit a clean-evidence
+  # run that didn't actually happen, prematurely advancing debounce/
+  # graduation streaks and consuming the weekly cadence. Re-running
+  # the wrapper next session will retry from a fresh facets read.
+  echo "aggregate_facets.py failed (rc=$AGG_RC) — bailing before merge" >&2
+  exit 5
+fi
+N_DETS=$("$PY" - "$DET" <<'PY'
+import json, sys
+try:
+    print(len(json.load(open(sys.argv[1]))))
+except Exception:
+    print(-1)
+PY
+)
+if [[ "$N_DETS" -lt 0 ]]; then
+  # Aggregator exited 0 but produced unparseable JSON → still bail.
+  # Same reasoning as the rc check above; an empty/garbled $DET
+  # cannot be merged safely.
+  echo "aggregate_facets.py produced unparseable output — bailing before merge" >&2
+  exit 5
+fi
+echo "detections=$N_DETS"
+
+# --- Step 3: dry-run short-circuit -----------------------------------------
+if [[ "$DRY_RUN" -eq 1 ]]; then
+  cat "$DET"
+  echo "(dry-run; merge skipped, throttle marker unchanged)"
+  exit 0
+fi
+
+# --- Step 4: merge ---------------------------------------------------------
+"$PY" "$SCRIPT_DIR/merge.py" \
+  --profile    "$COACH_DIR/profile.yaml" \
+  --changelog  "$COACH_DIR/changelog.md" \
+  --lock       "$COACH_DIR/.lock" \
+  --detections "$DET" \
+  --run-id     "$RUN_ID" || {
+    echo "merge.py failed" >&2
+    exit 4
+  }
+
+# --- Step 5: commit + throttle marker --------------------------------------
+( cd "$COACH_DIR" && git add -A && git commit -q -m "$RUN_ID" ) || true
+touch "$THROTTLE_MARKER"
+
+echo "done"

package/coach/bin/insights.sh

@@ -0,0 +1,163 @@
+#!/bin/bash
+# Headless Coach insights pass — the deterministic cron path.
+#
+# Does NOT go through the claude CLI — runs the analyzer directly for speed
+# and reliability (no LLM cold-start, no -p slash-command routing). The
+# interactive `/coach-insights` skill is the on-demand counterpart (it
+# delegates to Claude Code's built-in `/insights` for LLM-native analysis);
+# this script is what launchd/cron invokes daily.
+#
+# The script's filename stays `insights.sh` for launchd-plist stability —
+# the plist registered in v0.1+ has this path baked in, so renaming would
+# force every existing user to re-run `install-launchd.sh` on upgrade.
+#
+# Usage: insights.sh [WINDOW]     (default 1d; also accepts 7d, 30d, etc.)
+#
+# Cross-platform notes:
+#  - Resolves `python3` from PATH (no /usr/bin/python3 hardcode) so it works
+#    on Homebrew / pyenv / system Python.
+#  - Computes the since-time via Python so we don't depend on BSD `date -v`
+#    (macOS) vs GNU `date -d` (Linux) flag availability.
+
+set -uo pipefail
+
+# Plugin-context PATH wedge: when invoked under a plugin install
+# (CLAUDE_PLUGIN_DATA env var set + venv exists), prepend the plugin's
+# venv bin/ to PATH so `python3` resolves to the venv interpreter that
+# has PyYAML. CLI users never have CLAUDE_PLUGIN_DATA set; no-op for
+# them. Currently the daily cron is CLI-only (the plugin nudges users
+# to install it via `npx coach-claw launchd`), so this is defensive —
+# but cheap, and unblocks plugin-only cron once we ship that path.
+if [[ -n "${CLAUDE_PLUGIN_DATA:-}" && -x "$CLAUDE_PLUGIN_DATA/venv/bin/python3" ]]; then
+  export PATH="$CLAUDE_PLUGIN_DATA/venv/bin:$PATH"
+fi
+
+WINDOW="${1:-1d}"
+COACH_DIR="$HOME/.claude/coach"
+RUN_ID="insights-$(date -u +%Y%m%dT%H%M%SZ)"
+
+PY="$(command -v python3 || true)"
+if [[ -z "$PY" ]]; then
+  echo "python3 not found in PATH" >&2
+  exit 2
+fi
+
+# Filter transcripts by mtime in Python so we don't depend on BSD
+# `find -newermt`, which interprets bare timestamps in the host's
+# *local* timezone — wrong on every non-UTC host. insights_window.py
+# does the cutoff math against an explicit UTC-aware datetime and
+# compares to POSIX st_mtime, so the result is TZ-independent.
+TRANSCRIPTS=()
+TRANSCRIPT_OUTPUT="$("$PY" "$COACH_DIR/bin/insights_window.py" "$HOME/.claude/projects" "$WINDOW")"
+WINDOW_STATUS=$?
+if [[ "$WINDOW_STATUS" -ne 0 ]]; then
+  exit "$WINDOW_STATUS"
+fi
+while IFS= read -r line; do
+  [[ -n "$line" ]] && TRANSCRIPTS+=("$line")
+done <<< "$TRANSCRIPT_OUTPUT"
+
+N="${#TRANSCRIPTS[@]}"
+echo "run_id=$RUN_ID window=$WINDOW transcripts=$N"
+
+# Analyzer run (or empty detections if no transcripts)
+DET="$(mktemp /tmp/coach-detections-XXXXXX)"
+USED_JSON="$(mktemp /tmp/coach-skills-used-XXXXXX)"
+HINTS_JSON="$(mktemp /tmp/coach-skill-hints-XXXXXX)"
+DELTA_JSON="$(mktemp /tmp/coach-skills-by-project-delta-XXXXXX)"
+EFFECTIVE_JSON="$(mktemp /tmp/coach-skills-by-project-effective-XXXXXX)"
+trap 'rm -f "$DET" "$USED_JSON" "$HINTS_JSON" "$DELTA_JSON" "$EFFECTIVE_JSON"' EXIT
+
+if [[ "$N" -eq 0 ]]; then
+  echo "[]" > "$DET"
+  echo "{}" > "$USED_JSON"
+  echo "{}" > "$DELTA_JSON"
+  echo "no transcripts in window"
+else
+  # Delegate to the analyzer — it handles redaction internally.
+  ANALYSIS="$("$PY" "$COACH_DIR/bin/analyze.py" "${TRANSCRIPTS[@]}")" || {
+    echo "analyzer failed" >&2
+    exit 3
+  }
+  "$PY" - "$ANALYSIS" "$DET" "$USED_JSON" "$DELTA_JSON" <<'PY'
+import json, sys
+analysis_json, det_path, used_path, delta_path = sys.argv[1:5]
+d = json.loads(analysis_json)
+detections = d.get("detections", []) or []
+summary = d.get("summary") or {}
+with open(det_path, "w") as f:
+    json.dump(detections, f, indent=2)
+with open(used_path, "w") as f:
+    json.dump(summary.get("skills_used", {}) or {}, f)
+with open(delta_path, "w") as f:
+    json.dump(summary.get("skills_by_project", {}) or {}, f)
+print(f"detections={len(detections)} summary={summary}")
+PY
+fi
+
+# Build the EFFECTIVE skills_by_project tempfile = profile's existing
+# rolling accumulator + this run's delta. skill_inventory.py reads this
+# to infer per-skill project scope; merge.py separately receives just
+# the delta and accumulates it into the profile after.
+"$PY" - "$COACH_DIR/profile.yaml" "$DELTA_JSON" "$EFFECTIVE_JSON" <<'PY'
+import json, sys
+from pathlib import Path
+profile_path, delta_path, effective_path = (Path(p) for p in sys.argv[1:4])
+existing: dict = {}
+try:
+    import yaml
+    data = yaml.safe_load(profile_path.read_text()) if profile_path.exists() else {}
+    if isinstance(data, dict):
+        raw = data.get("skills_by_project") or {}
+        if isinstance(raw, dict):
+            for proj, skills in raw.items():
+                if isinstance(skills, dict):
+                    existing[str(proj)] = {str(k): int(v) for k, v in skills.items()
+                                            if isinstance(v, (int, float))}
+except Exception:
+    existing = {}
+try:
+    delta = json.loads(delta_path.read_text() or "{}")
+    if not isinstance(delta, dict):
+        delta = {}
+except Exception:
+    delta = {}
+effective: dict = {p: dict(s) for p, s in existing.items()}
+for proj, skills in delta.items():
+    if not isinstance(skills, dict):
+        continue
+    bucket = effective.setdefault(str(proj), {})
+    for sid, count in skills.items():
+        if isinstance(count, (int, float)):
+            bucket[str(sid)] = bucket.get(str(sid), 0) + int(count)
+effective_path.write_text(json.dumps(effective))
+PY
+
+# Build skill_hints snapshot (installed ∖ used-in-window)
+"$PY" "$COACH_DIR/bin/skill_inventory.py" \
+  --used-json "$USED_JSON" \
+  --skills-by-project "$EFFECTIVE_JSON" \
+  > "$HINTS_JSON" || {
+    echo "[]" > "$HINTS_JSON"
+  }
+N_HINTS=$("$PY" - "$HINTS_JSON" <<'PY'
+import json, sys
+print(len(json.load(open(sys.argv[1]))))
+PY
+)
+echo "skill_hints=$N_HINTS"
+
+# Apply merge (safeguards + atomic write + changelog)
+"$PY" "$COACH_DIR/bin/merge.py" \
+  --profile                  "$COACH_DIR/profile.yaml" \
+  --changelog                "$COACH_DIR/changelog.md" \
+  --lock                     "$COACH_DIR/.lock" \
+  --detections               "$DET" \
+  --skill-hints              "$HINTS_JSON" \
+  --skills-by-project-delta  "$DELTA_JSON" \
+  --run-id                   "$RUN_ID"
+
+# Git auto-commit (no-op if nothing changed)
+( cd "$COACH_DIR" && git add -A && git commit -q -m "insights $RUN_ID" ) || true
+
+echo "done"

package/coach/bin/insights_window.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Compute the set of recent JSONL transcripts for the /coach-insights window.
+
+Replaces an earlier BSD `find -newermt "$SINCE_TS"` invocation that
+read its timestamp argument in the host's *local* timezone. The Python
+heredoc that produced the timestamp emitted UTC, so on any non-UTC
+host the window was off by `tz_offset` hours every cron run — under-
+counting or double-counting transcripts depending on the sign.
+
+This module does the cutoff math entirely in Python with a UTC-aware
+`datetime.now(timezone.utc)` and compares against `path.stat().st_mtime`
+(POSIX seconds-since-epoch — also TZ-independent). The result is
+correct regardless of the host's `TZ` env var.
+
+Usage from the shell:
+
+    python3 insights_window.py <projects_dir> <window>
+
+…where `<window>` is `1d` / `7d` / `2h` / `30m` etc. Prints one
+absolute path per line, sorted, and excludes `/subagents/` transcripts
+(those are agent-tool spawns, not main sessions).
+"""
+from __future__ import annotations
+
+import re
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+_WINDOW_RE = re.compile(r"(\d+)([dhm])")
+
+
+def parse_window(spec: str) -> timedelta:
+    """Parse a window spec like ``1d`` / ``7d`` / ``2h`` / ``60m``.
+
+    Raises ``ValueError`` on any other shape so the caller can surface
+    a clear error instead of silently picking a default.
+    """
+    m = _WINDOW_RE.fullmatch(spec.strip())
+    if not m:
+        raise ValueError(f"bad window: {spec!r} (expected 1d/7d/2h/30m)")
+    n, unit = int(m.group(1)), m.group(2)
+    return {
+        "d": timedelta(days=n),
+        "h": timedelta(hours=n),
+        "m": timedelta(minutes=n),
+    }[unit]
+
+
+def cutoff_epoch(window: str, now: datetime | None = None) -> float:
+    """Return the POSIX-epoch cutoff for the window.
+
+    `now` may be supplied for testing; if given, it must be tz-aware
+    so the cutoff is computed against an absolute moment in time.
+    Defaults to ``datetime.now(timezone.utc)``.
+    """
+    if now is None:
+        now = datetime.now(timezone.utc)
+    elif now.tzinfo is None:
+        raise ValueError("now must be tz-aware")
+    return (now - parse_window(window)).timestamp()
+
+
+def recent_transcripts(
+    projects_dir: Path,
+    window: str,
+    now: datetime | None = None,
+) -> list[Path]:
+    """Return main-session JSONL transcripts modified inside the window.
+
+    The path-string filter for ``/subagents/`` matches the same exclusion
+    used by ``bank.py:_recent_main_transcripts`` — the two callers share
+    the same definition of "main session."
+    """
+    cutoff = cutoff_epoch(window, now)
+    if not projects_dir.exists():
+        return []
+    out: list[Path] = []
+    for p in projects_dir.rglob("*.jsonl"):
+        if "/subagents/" in str(p):
+            continue
+        try:
+            if p.stat().st_mtime >= cutoff:
+                out.append(p)
+        except OSError:
+            # Permission denied / vanished mid-walk / etc — skip silently.
+            continue
+    return sorted(out)
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        print(
+            "usage: insights_window.py <projects_dir> <window>",
+            file=sys.stderr,
+        )
+        return 2
+    projects_dir = Path(sys.argv[1])
+    window = sys.argv[2]
+    try:
+        paths = recent_transcripts(projects_dir, window)
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
+        return 2
+    for p in paths:
+        print(p)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/coach/bin/marker_io.py

@@ -0,0 +1,154 @@
+"""Atomic, locked I/O for celebration marker files.
+
+Single source of truth for marker writes. Used by `merge.py` (graduation,
+regression, streak markers) and `stats.py` (levelup marker). The
+UserPromptSubmit hook's `_read_and_consume()` takes the SAME sidecar
+flock (`<path>.lock`), so reader/writer interleaves are serialized:
+
+  • A reader holding the lock won't see a half-written marker.
+  • A writer holding the lock can't be clobbered by a reader's
+    atomic-replace landing after a stale read.
+
+Why this module exists: the v0.2.0 release introduced `consumed_by`
+tracking on the read side but left writers unlocked, so a stale-snapshot
+reader could overwrite a freshly-appended writer payload and silently
+drop an event. This module closes that gap.
+
+Helpers never raise — celebration markers are UX, not correctness, and a
+write failure must never break `/coach-insights` or the statusline.
+"""
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import tempfile
+from datetime import datetime
+from pathlib import Path
+
+
+def _lock_path_for(path: Path) -> Path:
+    return path.with_suffix(path.suffix + ".lock")
+
+
+def _atomic_write_under_lock(path: Path, payload: dict) -> None:
+    """tempfile + os.replace inside the caller's flock context.
+
+    Caller MUST already hold the sidecar lock. This helper is intentionally
+    private — public surface goes through `atomic_marker_rmw_append` or
+    `atomic_marker_replace` so the lock-acquisition is not optional.
+    """
+    fd, tmp_name = tempfile.mkstemp(
+        prefix="." + path.name + ".",
+        suffix=".tmp",
+        dir=str(path.parent),
+    )
+    try:
+        with os.fdopen(fd, "w") as fh:
+            fh.write(json.dumps(payload))
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp_name, path)
+    except Exception:
+        try:
+            os.unlink(tmp_name)
+        except Exception:
+            pass
+        raise
+
+
+def atomic_marker_rmw_append(
+    path: Path,
+    items_key: str,
+    new_items: list[dict],
+    now: datetime,
+) -> None:
+    """Read-modify-write append for celebration markers.
+
+    Acquires the sidecar flock, reads any existing items under that key,
+    appends `new_items`, and atomic-replaces the file. Resets `consumed_by`
+    to [] and `created_at` to `now` on every successful write — this is
+    deliberate: if `/coach-insights` runs twice in <MARKER_TTL_HOURS, the second
+    batch is genuinely new news and a session that already consumed the
+    prior version still needs to see the additions. The cost is a one-time
+    re-render of prior entries, which is the right trade vs missing the
+    new ones entirely.
+
+    `oldest_entry_at` is preserved across appends (never reset) so the
+    catch-up framing line in `<coach-celebrate>` correctly fires when an
+    older queued entry is carried into a fresh append. `created_at`
+    continues to track the latest write (drives the 24h TTL on the read
+    side); `oldest_entry_at` tracks the first unconsumed write. On the
+    first append against a legacy marker (pre-v0.4.2, no
+    `oldest_entry_at`), the existing `created_at` is promoted into
+    `oldest_entry_at` so carried-over entries still drive catch-up.
+
+    Args:
+        path: marker file path (e.g. ~/.claude/coach/.pending_graduation)
+        items_key: top-level key in the JSON payload (e.g. "graduations")
+        new_items: list of dicts to append
+        now: timestamp for the new `created_at`
+    """
+    if not new_items:
+        return
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(_lock_path_for(path), "w") as lock_fh:
+            try:
+                fcntl.flock(lock_fh.fileno(), fcntl.LOCK_EX)
+            except Exception:
+                # flock unsupported on this fs — proceed best-effort.
+                # Worst case is the legacy race; we still atomic-replace.
+                pass
+            existing: list[dict] = []
+            oldest_entry_at: str | None = None
+            if path.exists():
+                try:
+                    data = json.loads(path.read_text())
+                    if isinstance(data, dict):
+                        prior = data.get(items_key)
+                        if isinstance(prior, list):
+                            existing = [x for x in prior if isinstance(x, dict)]
+                        prior_oldest = data.get("oldest_entry_at")
+                        if isinstance(prior_oldest, str):
+                            oldest_entry_at = prior_oldest
+                        elif isinstance(data.get("created_at"), str):
+                            # Legacy marker (pre-v0.4.2): promote existing
+                            # created_at so carried-over entries still
+                            # drive catch-up framing.
+                            oldest_entry_at = data["created_at"]
+                except Exception:
+                    existing = []
+            if oldest_entry_at is None:
+                # Fresh marker (or unreadable prior file) — anchor at now.
+                oldest_entry_at = now.isoformat()
+            payload = {
+                items_key: existing + new_items,
+                "created_at": now.isoformat(),
+                "oldest_entry_at": oldest_entry_at,
+                "consumed_by": [],
+            }
+            _atomic_write_under_lock(path, payload)
+    except Exception:
+        pass
+
+
+def atomic_marker_replace(path: Path, payload: dict) -> None:
+    """Atomic full-replace for single-event markers (e.g. levelup).
+
+    Levelup is a high-water-mark event — each new level-up replaces any
+    prior payload rather than merging. The lock is still required so
+    reader/writer interleave doesn't drop a fresh level-up announcement.
+    Caller is responsible for setting `created_at` and `consumed_by` on
+    the payload.
+    """
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(_lock_path_for(path), "w") as lock_fh:
+            try:
+                fcntl.flock(lock_fh.fileno(), fcntl.LOCK_EX)
+            except Exception:
+                pass
+            _atomic_write_under_lock(path, payload)
+    except Exception:
+        pass