@rm0nroe/coach-claw 1.0.6

package/coach/bin/redact.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""
+Transcript redactor — stdin → stdout.
+
+Runs BEFORE the deterministic cron analyzer (`analyze.py` invoked by
+`insights.sh`) reads any transcript byte. P0 privacy gate: strips known
+credential shapes out of transcript content so they cannot be echoed into
+the coach profile and subsequently injected as additionalContext on every
+SessionStart.
+
+The on-demand `/coach-insights` skill does NOT call `redact.py` — that
+path defers the analytical step to Claude Code's built-in `/insights`,
+which is an Anthropic-side LLM step the user is already authorized for
+by virtue of running Claude Code. Coach still never writes raw
+transcript content to `profile.yaml` on either path.
+
+Usage:
+    cat transcript.jsonl | redact.py > redacted.jsonl
+
+This is deliberately conservative — it over-redacts rather than miss a
+secret. False positives are fine; leaked keys are not.
+"""
+from __future__ import annotations
+
+import re
+import sys
+
+PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    # Provider-specific API key shapes
+    (re.compile(r"sk-ant-[A-Za-z0-9_\-]{20,}"), "[REDACTED:anthropic-key]"),
+    (re.compile(r"sk-[A-Za-z0-9]{32,}"), "[REDACTED:openai-key]"),
+    # Stripe live + test secret keys (underscore not hyphen — the openai
+    # `sk-` rule above will not match these).
+    (re.compile(r"sk_live_[A-Za-z0-9]{24,}"), "[REDACTED:stripe-live-key]"),
+    (re.compile(r"sk_test_[A-Za-z0-9]{24,}"), "[REDACTED:stripe-test-key]"),
+    (re.compile(r"AKIA[0-9A-Z]{16}"), "[REDACTED:aws-access-key]"),
+    (re.compile(r"ASIA[0-9A-Z]{16}"), "[REDACTED:aws-sts-key]"),
+    (re.compile(r"aws_secret_access_key\s*[:=]\s*[A-Za-z0-9/+=]{40}", re.IGNORECASE),
+     "aws_secret_access_key=[REDACTED]"),
+    (re.compile(r"gh[pousr]_[A-Za-z0-9]{30,}"), "[REDACTED:github-token]"),
+    (re.compile(r"github_pat_[A-Za-z0-9_]{60,}"), "[REDACTED:github-pat]"),
+    (re.compile(r"xox[baprs]-[A-Za-z0-9-]{10,}"), "[REDACTED:slack-token]"),
+    (re.compile(r"AIza[0-9A-Za-z_\-]{35}"), "[REDACTED:google-api-key]"),
+    (re.compile(r"ya29\.[0-9A-Za-z_\-]{50,}"), "[REDACTED:google-oauth]"),
+    # Hugging Face user access tokens (start with `hf_`, ~37 chars).
+    (re.compile(r"\bhf_[A-Za-z0-9]{30,}"), "[REDACTED:huggingface-token]"),
+    # npm automation/publish tokens.
+    (re.compile(r"\bnpm_[A-Za-z0-9]{30,}"), "[REDACTED:npm-token]"),
+
+    # Generic bearer tokens and authorization headers
+    (re.compile(r"Bearer\s+[A-Za-z0-9\-._~+/]{20,}=*", re.IGNORECASE), "Bearer [REDACTED]"),
+    (re.compile(r"Authorization:\s*[A-Za-z]+\s+[A-Za-z0-9\-._~+/]{20,}=*", re.IGNORECASE),
+     "Authorization: [REDACTED]"),
+
+    # Private keys (PEM blocks — collapse the whole block)
+    (re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]+?-----END [A-Z ]*PRIVATE KEY-----"),
+     "[REDACTED:private-key-block]"),
+
+    # JWT-shaped tokens (three base64url segments separated by dots)
+    (re.compile(r"eyJ[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}"),
+     "[REDACTED:jwt]"),
+
+    # Hex-form secrets that look like 32+ hex chars on their own
+    (re.compile(r"\b[a-fA-F0-9]{40,}\b"), "[REDACTED:hex-secret?]"),
+
+    # .env-style assignments for suspicious key names
+    (re.compile(
+        r"(?mi)^\s*(\w*(?:SECRET|TOKEN|PASSWORD|API[_-]?KEY|PRIVATE[_-]?KEY|ACCESS[_-]?KEY|CREDENTIAL)\w*)"
+        r"\s*[:=]\s*[\"']?([^\"'\n\s]{8,})[\"']?"),
+     r"\1=[REDACTED]"),
+]
+
+
+def redact(text: str) -> str:
+    for pat, replacement in PATTERNS:
+        text = pat.sub(replacement, text)
+    return text
+
+
+def main() -> None:
+    data = sys.stdin.read()
+    sys.stdout.write(redact(data))
+
+
+if __name__ == "__main__":
+    main()

package/coach/bin/render_env.py

@@ -0,0 +1,148 @@
+"""Render-environment detection for coach output.
+
+Coach banners need different markdown shapes depending on whether they're
+rendered by terminal Claude Code (which dims blockquotes via theme) or an
+IDE chat panel (which uses a WebView markdown renderer with different
+feature support — notably, no GFM admonitions and weak blockquote styling).
+
+`detect_render_env()` returns "ide" or "terminal" based on Claude Code's
+own `CLAUDE_CODE_ENTRYPOINT` env var. Allowlist semantics: known IDE
+entrypoints get the IDE shape; everything else falls through to the
+terminal shape, which renders correctly across all surfaces.
+
+Single source of truth — imported by both hooks (which append coach/bin/
+to sys.path before importing).
+"""
+from __future__ import annotations
+
+import os
+from typing import Literal, Mapping
+
+# Entrypoints whose output is rendered by an IDE chat panel WebView.
+#   vscode, jetbrains, ide-onboarding: confirmed in Claude Code binary
+#   claude-vscode, claude-jetbrains:   speculative — kept as defensive
+#     fallback for prefixed variants. If absent, detection falls through
+#     to the terminal shape, which renders correctly in IDE panels too
+#     (just less prominently than the HR-framed shape).
+IDE_ENTRYPOINTS = frozenset({
+    "vscode",
+    "claude-vscode",
+    "jetbrains",
+    "claude-jetbrains",
+    "ide-onboarding",
+})
+
+RenderEnv = Literal["ide", "terminal"]
+
+
+def detect_render_env(env: Mapping[str, str] | None = None) -> RenderEnv:
+    """Return "ide" if the hook is being invoked from an IDE chat panel,
+    otherwise "terminal".
+
+    Allowlist: unknown / future entrypoints default to "terminal" — the
+    terminal shape uses universal markdown that renders acceptably
+    everywhere, so it's the safe fallback when we don't recognize the
+    surface.
+
+    Honors COACH_RENDER_ENV={ide,terminal} as a manual override (useful
+    for testing the IDE branch from a terminal session, or vice versa).
+
+    Args:
+        env: environment mapping. Defaults to os.environ. Explicit param
+             so tests can pass a fake without monkeypatching.
+    """
+    if env is None:
+        env = os.environ
+
+    override = env.get("COACH_RENDER_ENV", "").strip().lower()
+    if override in ("ide", "terminal"):
+        return override  # type: ignore[return-value]
+
+    entrypoint = env.get("CLAUDE_CODE_ENTRYPOINT", "").strip().lower()
+    if entrypoint in IDE_ENTRYPOINTS:
+        return "ide"
+    return "terminal"
+
+
+# -----------------------------------------------------------------------------
+# Glyph-capability probes — lets bespoke banner themes ask "can this terminal
+# render U+2694 ⚔ as a single cell?" before committing to it. Falls back to a
+# 1-cell ASCII alternative (e.g., ✕) when the answer is no.
+#
+# Memoized at module level — probing the env is idempotent within a process,
+# and every UserPromptSubmit hook spawns a fresh interpreter, so a per-process
+# cache is enough. Tests pass an explicit `env` mapping to bypass the cache.
+
+_DUAL_BLADE_CACHE: bool | None = None
+
+
+def _is_truthy(value: str) -> bool:
+    return value.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _is_falsy(value: str) -> bool:
+    return value.strip().lower() in ("0", "false", "no", "off")
+
+
+def supports_dual_blade(env: Mapping[str, str] | None = None) -> bool:
+    """Return True if ⚔ (U+2694 CROSSED SWORDS) can be expected to render as
+    a single cell in this terminal. Themes that build streak meters out of ⚔
+    use this to fall back to ✕ when the renderer would mis-width the glyph.
+
+    Detection order:
+      1. COACH_FORCE_ASCII_GLYPHS truthy → False  (generic kill-switch — also
+         applies to other dual-cell-risk glyphs added later).
+      2. COACH_SUPPORTS_DUAL_BLADE set → honor explicitly (for tests + power
+         users overriding a wrong default).
+      3. Locale (LANG / LC_ALL / LC_CTYPE) lacks UTF-8 → False.
+      4. TERM in {"dumb", "linux"} → False.
+      5. Default → True. Modern terminals dominate; safer to render the
+         intended glyph than to ASCII-degrade the majority.
+
+    Args:
+        env: environment mapping. Defaults to os.environ. When provided,
+             the module-level cache is bypassed (so tests can pin shapes).
+    """
+    global _DUAL_BLADE_CACHE
+    if env is None:
+        if _DUAL_BLADE_CACHE is not None:
+            return _DUAL_BLADE_CACHE
+        env = os.environ
+        cache = True
+    else:
+        cache = False
+
+    result = _probe_dual_blade(env)
+    if cache:
+        _DUAL_BLADE_CACHE = result
+    return result
+
+
+def _probe_dual_blade(env: Mapping[str, str]) -> bool:
+    if _is_truthy(env.get("COACH_FORCE_ASCII_GLYPHS", "")):
+        return False
+
+    explicit = env.get("COACH_SUPPORTS_DUAL_BLADE", "")
+    if _is_truthy(explicit):
+        return True
+    if _is_falsy(explicit):
+        return False
+
+    # POSIX locale precedence: LC_ALL > LC_CTYPE > LANG. The first
+    # non-empty value is the effective locale — OR-merging across all
+    # three means an explicit `LC_ALL=C` is silently overridden by an
+    # otherwise-unused `LANG=en_US.UTF-8`, which is the bug.
+    effective = ""
+    for var in ("LC_ALL", "LC_CTYPE", "LANG"):
+        val = env.get(var, "").strip()
+        if val:
+            effective = val.lower()
+            break
+    if effective and "utf-8" not in effective and "utf8" not in effective:
+        return False
+
+    term = env.get("TERM", "").strip().lower()
+    if term in ("dumb", "linux"):
+        return False
+
+    return True

package/coach/bin/reward_hints.py

@@ -0,0 +1,87 @@
+"""
+Shared reward-hint inference for the Coach system.
+
+A `reward_hint` attached to a profile.yaml entry specifies what user action
+completes a tip for that pattern, and how much XP each action earns. Shape:
+
+    reward_hint:
+      action: test_run | commit | skill_invoke   # named action
+      xp: 2                                      # per-action XP
+      description: "test run (pytest / ...)"      # human-readable for tip
+
+This module infers reasonable defaults from an entry's id + nudge text when
+no explicit hint is set. It's imported by:
+
+  - coach/bin/merge.py              — to populate reward_hint at entry creation
+  - hooks/coach-user-prompt.py      — as read-time fallback for existing entries
+
+Single source of truth for the keyword heuristic + detector vocabulary.
+Hooks can't simply `import reward_hints` because they run from ~/.claude/
+with a different cwd; they must append coach/bin/ to sys.path first.
+"""
+from __future__ import annotations
+
+# (keyword, reward_hint payload). First match wins. Keywords are case-
+# insensitive and checked against BOTH the entry id and the nudge text,
+# so a pattern with id="over-mocks" whose nudge says "wrote code without
+# running tests" still trips test_run via the nudge.
+_HEURISTIC: list[tuple[str, dict]] = [
+    # Test-run signals (broadest coverage: id-tokens + common nudge phrasings)
+    ("without-test",     {"action": "test_run", "xp": 2,
+                          "description": "test run (pytest / jest / cargo test / …)"}),
+    ("without test",     {"action": "test_run", "xp": 2, "description": "test run"}),
+    ("no test",          {"action": "test_run", "xp": 2, "description": "test run"}),
+    ("no tests",         {"action": "test_run", "xp": 2, "description": "test run"}),
+    ("untested",         {"action": "test_run", "xp": 2, "description": "test run"}),
+    ("skip-test",        {"action": "test_run", "xp": 2, "description": "test run"}),
+    ("skip test",        {"action": "test_run", "xp": 2, "description": "test run"}),
+    ("skipped test",     {"action": "test_run", "xp": 2, "description": "test run"}),
+    ("skipping test",    {"action": "test_run", "xp": 2, "description": "test run"}),
+    ("tests skipped",    {"action": "test_run", "xp": 2, "description": "test run"}),
+    ("tests were skipped", {"action": "test_run", "xp": 2, "description": "test run"}),
+    ("running tests",    {"action": "test_run", "xp": 2, "description": "test run"}),
+    ("run tests",        {"action": "test_run", "xp": 2, "description": "test run"}),
+    ("test run",         {"action": "test_run", "xp": 2, "description": "test run"}),
+    ("test suite",       {"action": "test_run", "xp": 2, "description": "test run"}),
+    # Commit signals
+    ("without-commit",     {"action": "commit", "xp": 1, "description": "git commit"}),
+    ("without committing", {"action": "commit", "xp": 1, "description": "git commit"}),
+    ("not committing",     {"action": "commit", "xp": 1, "description": "git commit"}),
+]
+
+
+def infer_reward_hint(entry: dict) -> dict | None:
+    """Guess the reward_hint for a profile entry (or a detection dict) that
+    doesn't have one set. Inspects both the id and the nudge text for
+    keyword hits. Returns None when nothing matches → graduation-only pattern.
+
+    Accepts either:
+      - a profile.yaml entry dict (has `id`, `nudge`, ...)
+      - an analyze.py detection dict (has `id`, `nudge`, ...)
+    Both share the same relevant keys.
+    """
+    if not isinstance(entry, dict):
+        return None
+    eid = str(entry.get("id") or "").lower()
+    nudge = str(entry.get("nudge") or "").lower()
+    haystack = f"{eid} {nudge}"
+    for keyword, hint in _HEURISTIC:
+        if keyword in haystack:
+            return dict(hint)  # copy so callers can't mutate our defaults
+    return None
+
+
+def effective_reward_hint(entry: dict) -> dict | None:
+    """Return the entry's explicit reward_hint if present and valid, else
+    infer. Centralizes the "explicit overrides inference" rule so every
+    caller gets the same precedence."""
+    if not isinstance(entry, dict):
+        return None
+    explicit = entry.get("reward_hint")
+    if (
+        isinstance(explicit, dict)
+        and explicit.get("action")
+        and int(explicit.get("xp", 0) or 0) > 0
+    ):
+        return explicit
+    return infer_reward_hint(entry)

package/coach/bin/run-insights.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Wrapper invoked by launchd to run the Coach insights pass once. Logs to
+# /tmp. Runs the deterministic insights.sh — does NOT go through the
+# claude CLI, so no cold-start cost and no slash-command routing issues.
+# (The on-demand `/coach-insights` skill is the LLM-driven counterpart
+# that runs from inside Claude Code; this wrapper is launchd-only.)
+
+set -u
+export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+export HOME="${HOME:-$(eval echo ~$(whoami))}"
+
+LOG="/tmp/claude-coach.log"
+TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+echo "[$TS] starting insights.sh 1d" >> "$LOG"
+
+"$HOME/.claude/coach/bin/insights.sh" 1d >> "$LOG" 2>&1
+EXIT=$?
+
+echo "[$TS] insights.sh exited $EXIT" >> "$LOG"
+exit "$EXIT"

package/coach/bin/run_with_lock.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Run a command while holding an exclusive flock on a sidecar file.
+
+Used by insights-llm.sh to serialize concurrent weekly-insights runs.
+Two Claude Code SessionStart hooks firing within the ~90s window of a
+slow `claude -p "/insights"` call will both see `.last_weekly_insights`
+as stale and try to spawn the wrapper. Without this lock, both run the
+LLM call, both aggregate, both merge — wasting an LLM call and
+prematurely advancing debounce/graduation streaks. Under the lock, the
+second wrapper rechecks the throttle (which the first wrapper just
+refreshed) and skips cleanly.
+
+Usage:
+  run_with_lock.py <lock_path> <cmd> [args...]
+
+Behavior:
+  - Acquires `fcntl.LOCK_EX | LOCK_NB` on the lock file (created if
+    absent). Failure to acquire (because another process holds it)
+    prints a one-line "skipped (concurrent ...)" notice to stdout and
+    exits SKIP_EXIT_CODE (10). The caller should treat this as
+    benign — coordination, not error.
+  - On success, runs `cmd` as a subprocess and returns its exit code.
+    Sets `COACH_LLM_LOCK_HELD=1` in the child env so the wrapped
+    script can detect it's already inside the lock and skip a
+    re-exec loop.
+  - Lock auto-releases when this process exits (per fcntl semantics);
+    we also explicitly unlock + close on the way out.
+"""
+from __future__ import annotations
+
+import fcntl
+import os
+import subprocess
+import sys
+
+
+SKIP_EXIT_CODE = 10
+
+
+def main() -> int:
+    if len(sys.argv) < 3:
+        print(
+            "usage: run_with_lock.py <lock_path> <cmd> [args...]",
+            file=sys.stderr,
+        )
+        return 64
+
+    lock_path = sys.argv[1]
+    cmd = sys.argv[2:]
+
+    # Ensure the lock file's parent dir exists (test fixtures sometimes
+    # point at not-yet-created paths).
+    parent = os.path.dirname(lock_path) or "."
+    try:
+        os.makedirs(parent, exist_ok=True)
+    except OSError:
+        pass
+
+    fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o644)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except BlockingIOError:
+        os.close(fd)
+        print("skipped (concurrent weekly run in progress)")
+        return SKIP_EXIT_CODE
+
+    env = os.environ.copy()
+    env.setdefault("COACH_LLM_LOCK_HELD", "1")
+
+    try:
+        proc = subprocess.run(cmd, env=env)
+        return proc.returncode
+    finally:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        except OSError:
+            pass
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/coach/bin/scoring.py

@@ -0,0 +1,260 @@
+"""
+Shared transcript-scoring primitives for the Coach system.
+
+One source of truth for action detection (regexes, tool-type matchers) and
+per-action XP so that `stats.py`, `bank.py`, and the `coach-user-prompt.py`
+hook all agree on what counts as what.
+
+Exports:
+  - TEST_RE, COMMIT_RE, COLLECT_ONLY_RE — position-anchored bash regexes
+  - BASELINE_ACTIONS                     — {name -> xp} baseline reward table
+  - matches_action(tool_use, action)     — shared per-tool-use matcher
+  - score_transcript_with_breakdown()    — explainable uncapped/capped score
+  - score_transcript(path, profile)      — returns capped session XP
+      baseline XP for test_run / commit / skill_invoke, plus any
+      additional XP for reward_hint actions found on active profile
+      entries whose `action` is NOT already baseline (no double-counting).
+
+Stats.py, bank.py, status.py, and the hook all call this module so their
+definitions of "test run", "commit", "skill invoke", and dynamic actions do
+not drift.
+
+IMPORTANT: if you add a new action detector, extend ACTION_DETECTORS below
+and also add a reward_hints.py heuristic entry so `/coach-insights` patterns can
+auto-bind to it.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+
+# --- Position-anchored regexes --------------------------------------------------
+# Start-of-line or after ; && || |, with optional env-var or cd-prefix.
+# Prevents false positives on "pytest" / "git commit" inside commit-message
+# bodies.
+TEST_RE = re.compile(
+    r"(?:^|[;&|])\s*"
+    r"(?:\w+=\S+\s+)*"
+    r"(?:cd\s+\S+\s*&&\s*)?"
+    r"(?:pytest|jest|vitest|mocha|rspec|phpunit|"
+    r"cargo\s+test|go\s+test|pnpm\s+test|npm\s+test|bun\s+test|"
+    r"yarn\s+test|mix\s+test)"
+    r"\b"
+)
+COMMIT_RE = re.compile(
+    r"(?:^|[;&|])\s*"
+    r"(?:\w+=\S+\s+)*"
+    r"(?:cd\s+\S+\s*&&\s*)?"
+    r"git\s+commit\b"
+)
+# pytest --collect-only farms XP without running anything
+COLLECT_ONLY_RE = re.compile(r"pytest\s+.*--co(llect)?-only")
+
+# --- Baseline reward table -----------------------------------------------------
+# Baseline actions always scored, regardless of profile contents. Matches
+# what reward_hint can specify — if a pattern has `reward_hint: { action:
+# test_run }`, that's the SAME +2 the baseline awards, not an additional one.
+BASELINE_ACTIONS = {
+    "test_run":     2,
+    "commit":       1,
+    "skill_invoke": 1,
+}
+
+SESSION_XP_CAP = 15
+
+
+# --- Per-action detectors ------------------------------------------------------
+# Each detector takes a tool_use dict (`{type, name, input}`) and returns
+# True if that tool_use counts as one occurrence of this action.
+def _detect_test_run(tu: dict) -> bool:
+    if tu.get("name") != "Bash":
+        return False
+    cmd = (tu.get("input") or {}).get("command", "") or ""
+    if COLLECT_ONLY_RE.search(cmd):
+        return False
+    return bool(TEST_RE.search(cmd))
+
+
+def _detect_commit(tu: dict) -> bool:
+    if tu.get("name") != "Bash":
+        return False
+    cmd = (tu.get("input") or {}).get("command", "") or ""
+    return bool(COMMIT_RE.search(cmd))
+
+
+# skill_invoke is counted by unique-skill-id set, not per-event, so it's
+# handled specially in score_transcript — not in this dispatch.
+
+def _detect_doc_write(tu: dict) -> bool:
+    """Write/Edit on a markdown file. Reward for doc-skipping patterns."""
+    name = tu.get("name", "")
+    if name not in ("Write", "Edit", "MultiEdit"):
+        return False
+    path = (tu.get("input") or {}).get("file_path") or ""
+    return isinstance(path, str) and path.endswith(".md")
+
+
+# action-name → (event-detector-or-None, per-event-xp). None means
+# "this action is scored specially in score_transcript" (e.g. skill_invoke
+# which tallies unique skill ids).
+ACTION_DETECTORS = {
+    "test_run":     (_detect_test_run, 2),
+    "commit":       (_detect_commit,   1),
+    "skill_invoke": (None,             1),   # special: unique-set tally
+    "doc_write":    (_detect_doc_write, 1),  # extension slot; /coach-insights can bind here
+}
+
+
+def matches_action(
+    tool_use: dict,
+    action: str,
+    *,
+    skill_id: str | None = None,
+) -> bool:
+    """Return True if one transcript tool_use satisfies an action.
+
+    `skill_id` optionally narrows `skill_invoke` to one slash command / skill.
+    Other actions are handled by ACTION_DETECTORS. Unknown actions are False
+    rather than errors so hooks can fail closed.
+    """
+    if not isinstance(tool_use, dict):
+        return False
+    if action == "skill_invoke":
+        if tool_use.get("name") not in ("SlashCommand", "Skill"):
+            return False
+        inp = tool_use.get("input") or {}
+        sid = (inp.get("command") or inp.get("skill") or "").lstrip("/")
+        if not sid:
+            return False
+        if skill_id:
+            return sid == skill_id.lstrip("/")
+        return True
+    detector, _xp = ACTION_DETECTORS.get(action, (None, 0))
+    if detector is None:
+        return False
+    return bool(detector(tool_use))
+
+
+def _iter_tool_uses(path: Path):
+    """Yield every tool_use dict from a transcript JSONL, tolerating junk.
+
+    Intentional: skips the redact() pre-pass that analyze.py uses. The only
+    outputs that escape this function (via score_transcript_with_breakdown,
+    line ~243) are integer counts and skill_id slugs — no transcript bytes
+    are returned or persisted. If the output shape ever expands to include
+    user content, add the redact() pass to match analyze.py.
+    """
+    try:
+        with path.open() as fh:
+            for line in fh:
+                try:
+                    obj = json.loads(line)
+                except Exception:
+                    continue
+                msg = obj.get("message") or {}
+                content = msg.get("content")
+                if not isinstance(content, list):
+                    continue
+                for item in content:
+                    if isinstance(item, dict) and item.get("type") == "tool_use":
+                        yield item
+    except Exception:
+        return
+
+
+def _dynamic_actions_from_profile(profile: dict) -> dict:
+    """Return {action_name: xp} for reward_hint.action values present in
+    profile that are NOT already baseline. Deduplicates — if two patterns
+    reference the same action, it's still one scoring rule."""
+    out: dict[str, int] = {}
+    if not isinstance(profile, dict):
+        return out
+    for e in profile.get("entries", []) or []:
+        if not isinstance(e, dict):
+            continue
+        h = e.get("reward_hint")
+        if not isinstance(h, dict):
+            continue
+        action = h.get("action")
+        xp = int(h.get("xp", 0) or 0)
+        if not action or xp <= 0:
+            continue
+        if action in BASELINE_ACTIONS:
+            continue   # already scored via baseline
+        if action not in ACTION_DETECTORS:
+            continue   # no detector registered; stats.py can't score it
+        # If multiple patterns reference the same non-baseline action with
+        # different xp values, keep the max — conservative upper bound.
+        out[action] = max(out.get(action, 0), xp)
+    return out
+
+
+def score_transcript(path: Path, profile: dict | None = None) -> int:
+    """Return capped session XP for a single transcript.
+
+    Always scores the three baseline actions (test_run, commit, skill_invoke).
+    If `profile` is provided, also scores any additional reward_hint actions
+    registered in ACTION_DETECTORS. Total capped at SESSION_XP_CAP.
+    """
+    return int(score_transcript_with_breakdown(path, profile)["capped_xp"])
+
+
+def score_transcript_with_breakdown(
+    path: Path,
+    profile: dict | None = None,
+) -> dict:
+    """Return an explainable session score for one transcript.
+
+    Shape is intentionally simple for CLI renderers:
+      tests, commits, skills_n, skills_list, dynamic_actions,
+      raw_xp, capped_xp, capped.
+    """
+    test_runs = 0
+    commits = 0
+    skills: set[str] = set()
+    dynamic_counts: dict[str, int] = {}
+    dynamic_actions = _dynamic_actions_from_profile(profile or {})
+
+    for tu in _iter_tool_uses(path):
+        if matches_action(tu, "test_run"):
+            test_runs += 1
+        if matches_action(tu, "commit"):
+            commits += 1
+        if matches_action(tu, "skill_invoke"):
+            sid = ((tu.get("input") or {}).get("command")
+                   or (tu.get("input") or {}).get("skill") or "").lstrip("/")
+            if sid:
+                skills.add(sid)
+        for action in dynamic_actions:
+            if matches_action(tu, action):
+                dynamic_counts[action] = dynamic_counts.get(action, 0) + 1
+
+    dynamic_breakdown = {}
+    for action, count in sorted(dynamic_counts.items()):
+        xp_each = dynamic_actions[action]
+        dynamic_breakdown[action] = {
+            "count": count,
+            "xp_each": xp_each,
+            "xp": count * xp_each,
+        }
+
+    raw_xp = (
+        test_runs * BASELINE_ACTIONS["test_run"]
+        + commits * BASELINE_ACTIONS["commit"]
+        + len(skills) * BASELINE_ACTIONS["skill_invoke"]
+        + sum(item["xp"] for item in dynamic_breakdown.values())
+    )
+
+    return {
+        "tests": test_runs,
+        "commits": commits,
+        "skills_n": len(skills),
+        "skills_list": sorted(skills),
+        "dynamic_actions": dynamic_breakdown,
+        "available_dynamic_actions": dict(sorted(dynamic_actions.items())),
+        "raw_xp": raw_xp,
+        "capped_xp": min(raw_xp, SESSION_XP_CAP),
+        "capped": raw_xp > SESSION_XP_CAP,
+    }