@rm0nroe/coach-claw 1.0.6

package/coach/tests/test_install_pyyaml_fallback.py

@@ -0,0 +1,142 @@
+"""Regression test for the PyYAML preflight fallback chain in install.sh.
+
+A previous round of the installer recommended `brew install pyyaml` as
+the Homebrew-blessed recovery path. The formula does not exist in
+Homebrew core (`brew info pyyaml` → `Error: No available formula`). The
+strategy and the error message that included it were dead code — the
+recovery instructions pointed users at a command that fails.
+
+These tests pin the current shape:
+
+  • install.sh does not mention `brew install pyyaml` anywhere in source
+  • when both legitimate pip strategies fail, the recovery message
+    surfaces only real options (`pip --break-system-packages` and venv)
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+
+def _git_env() -> dict:
+    return {
+        "GIT_AUTHOR_NAME": "Coach Tests",
+        "GIT_AUTHOR_EMAIL": "coach-tests@example.invalid",
+        "GIT_COMMITTER_NAME": "Coach Tests",
+        "GIT_COMMITTER_EMAIL": "coach-tests@example.invalid",
+    }
+
+
+def test_install_sh_does_not_reference_dead_brew_pyyaml() -> None:
+    repo = Path(__file__).resolve().parents[2]
+    if not (repo / "install.sh").exists():
+        pytest.skip("install.sh is only present in the shareable repo checkout")
+
+    src = (repo / "install.sh").read_text()
+    assert "brew install pyyaml" not in src, (
+        "install.sh references `brew install pyyaml`, but no such "
+        "formula exists in Homebrew core. Use `pip install --user "
+        "--break-system-packages pyyaml` or a venv instead."
+    )
+
+
+def test_install_pyyaml_fallback_message_excludes_dead_brew_path(
+    tmp_path: Path,
+) -> None:
+    """Run install.sh with python3 PATH-shimmed to simulate missing
+    PyYAML and refusing pip. The installer must fail with exit != 0
+    and an error message that:
+
+      • shows BOTH legitimate strategies were tried (pip --user, then
+        pip --user --break-system-packages),
+      • offers --break-system-packages and venv as manual recovery,
+      • does NOT mention `brew install pyyaml` or claim Homebrew Python
+        gets a special blessed strategy.
+    """
+    repo = Path(__file__).resolve().parents[2]
+    if not (repo / "install.sh").exists():
+        pytest.skip("install.sh is only present in the shareable repo checkout")
+
+    real_python3 = shutil.which("python3")
+    assert real_python3, "real python3 must be on PATH for the shim to delegate"
+
+    shim_dir = tmp_path / "bin"
+    shim_dir.mkdir()
+    shim = shim_dir / "python3"
+    # Bash shim: blocks `-c "import yaml"` and `-m pip ...` by exiting 1;
+    # delegates everything else (version check via heredoc, etc.) to the
+    # real python3.
+    shim.write_text(
+        """#!/bin/bash
+case "$1" in
+  -c)
+    case "$2" in
+      *"import yaml"*) exit 1 ;;
+    esac
+    ;;
+  -m)
+    case "$2" in
+      pip) exit 1 ;;
+    esac
+    ;;
+esac
+exec "$COACH_REAL_PYTHON3" "$@"
+"""
+    )
+    shim.chmod(0o755)
+
+    claude_dir = tmp_path / "claude_dir"
+    env = os.environ.copy()
+    env.update(
+        {
+            "CLAUDE_DIR": str(claude_dir),
+            "PATH": f"{shim_dir}{os.pathsep}{env['PATH']}",
+            "COACH_REAL_PYTHON3": real_python3,
+            **_git_env(),
+        }
+    )
+
+    result = subprocess.run(
+        ["bash", str(repo / "install.sh")],
+        cwd=repo,
+        env=env,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        timeout=30,
+    )
+
+    out = result.stdout + result.stderr
+
+    assert result.returncode != 0, (
+        f"installer succeeded with pip stubbed to fail; "
+        f"preflight should have aborted:\n{out}"
+    )
+
+    # Both legitimate strategies must have been attempted before the
+    # error message fires.
+    assert "pip install --user pyyaml" in out, (
+        f"strategy 1 (pip --user) was not attempted:\n{out}"
+    )
+    assert "pip install --user --break-system-packages pyyaml" in out, (
+        f"strategy 2 (pip --break-system-packages) was not attempted:\n{out}"
+    )
+
+    # Dead Homebrew path must not appear anywhere — neither as a strategy
+    # the installer claims to try, nor in the recovery instructions.
+    assert "brew install pyyaml" not in out, (
+        f"installer output references the dead `brew install pyyaml` "
+        f"recovery path:\n{out}"
+    )
+    assert "Homebrew Python detected" not in out, (
+        f"installer announces a Homebrew strategy that no longer exists:\n{out}"
+    )
+
+    # Recovery message must give actionable manual alternatives.
+    assert "--break-system-packages" in out
+    assert "venv" in out

package/coach/tests/test_marker_consumption.py

@@ -0,0 +1,167 @@
+"""coach-user-prompt.py: per-session marker consumption.
+
+Regression guard for BACKLOG P2 — pending marker files (`.pending_levelup`
+etc.) used to be read-and-deleted by whichever UserPromptSubmit hook fired
+first, so a target Claude Code session could lose its celebration banner
+to an unrelated concurrent session. The fix tracks `consumed_by` inside
+the marker JSON + a 24h TTL, so each session sees the marker once and
+abandoned markers don't accumulate.
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture(scope="module")
+def cup():
+    """Load coach-user-prompt.py as a module."""
+    repo_path = Path(__file__).resolve().parents[2] / "hooks" / "coach-user-prompt.py"
+    path = repo_path if repo_path.exists() else Path.home() / ".claude" / "hooks" / "coach-user-prompt.py"
+    if not path.exists():
+        pytest.skip(f"hook not installed at {path}")
+    spec = importlib.util.spec_from_file_location("cup_marker_test", str(path))
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def _write_marker(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload))
+
+
+def test_two_sessions_each_see_marker_once(cup, tmp_path):
+    marker = tmp_path / ".pending_graduation"
+    now = datetime.now(timezone.utc)
+    _write_marker(marker, {
+        "graduations": [{"id": "x", "name": "X"}],
+        "created_at": now.isoformat(),
+        "consumed_by": [],
+    })
+
+    a = cup._read_and_consume(marker, "session-A", now)
+    assert a is not None
+    assert a["graduations"] == [{"id": "x", "name": "X"}]
+
+    b = cup._read_and_consume(marker, "session-B", now)
+    assert b is not None
+    assert b["graduations"] == [{"id": "x", "name": "X"}]
+
+    # Marker still on disk (not deleted), with both sessions recorded.
+    raw = json.loads(marker.read_text())
+    assert sorted(raw["consumed_by"]) == ["session-A", "session-B"]
+
+
+def test_same_session_polling_twice_renders_once(cup, tmp_path):
+    marker = tmp_path / ".pending_levelup"
+    now = datetime.now(timezone.utc)
+    _write_marker(marker, {
+        "from": "Drafter", "from_idx": 0,
+        "to": "Builder", "to_idx": 1,
+        "xp_at_levelup": 50,
+        "created_at": now.isoformat(),
+        "consumed_by": [],
+    })
+
+    first = cup._read_and_consume(marker, "session-A", now)
+    assert first is not None
+    assert first["to"] == "Builder"
+
+    second = cup._read_and_consume(marker, "session-A", now)
+    assert second is None, "same session should not re-render the same marker"
+
+
+def test_marker_older_than_ttl_is_cleaned_up(cup, tmp_path):
+    marker = tmp_path / ".pending_regression"
+    long_ago = datetime.now(timezone.utc) - timedelta(hours=cup.MARKER_TTL_HOURS + 1)
+    _write_marker(marker, {
+        "regressions": [{"id": "y", "name": "Y"}],
+        "created_at": long_ago.isoformat(),
+        "consumed_by": [],
+    })
+
+    now = datetime.now(timezone.utc)
+    result = cup._read_and_consume(marker, "session-A", now)
+    assert result is None
+    assert not marker.exists(), "expired marker should be unlinked on read"
+
+
+def test_legacy_marker_without_created_at_is_treated_as_fresh(cup, tmp_path):
+    """v0.1 markers were written without created_at / consumed_by fields.
+    The reader must accept them on first encounter and stamp them."""
+    marker = tmp_path / ".pending_streak_rewards"
+    _write_marker(marker, {"rewards": [{"id": "z", "name": "Z", "streak": 2}]})
+
+    now = datetime.now(timezone.utc)
+    result = cup._read_and_consume(marker, "session-A", now)
+    assert result is not None
+    assert result["rewards"] == [{"id": "z", "name": "Z", "streak": 2}]
+
+    # Stamped on first read.
+    raw = json.loads(marker.read_text())
+    assert "created_at" in raw
+    assert raw["consumed_by"] == ["session-A"]
+
+
+def test_corrupt_marker_json_is_swallowed(cup, tmp_path):
+    marker = tmp_path / ".pending_graduation"
+    marker.parent.mkdir(parents=True, exist_ok=True)
+    marker.write_text("{not json")
+
+    now = datetime.now(timezone.utc)
+    result = cup._read_and_consume(marker, "session-A", now)
+    assert result is None
+    # Corrupt file is cleaned up to prevent a poll-loop.
+    assert not marker.exists()
+
+
+def test_consumed_by_overflow_drops_oldest(cup, tmp_path):
+    marker = tmp_path / ".pending_levelup"
+    now = datetime.now(timezone.utc)
+    cap = cup.MARKER_CONSUMED_BY_CAP
+    initial = [f"old-session-{i}" for i in range(cap)]
+    _write_marker(marker, {
+        "from": "X", "from_idx": 0, "to": "Y", "to_idx": 1, "xp_at_levelup": 1,
+        "created_at": now.isoformat(),
+        "consumed_by": list(initial),
+    })
+
+    result = cup._read_and_consume(marker, "new-session", now)
+    assert result is not None
+    raw = json.loads(marker.read_text())
+    assert len(raw["consumed_by"]) == cap
+    assert "new-session" in raw["consumed_by"]
+    assert raw["consumed_by"][0] != "old-session-0"  # oldest dropped
+
+
+def test_missing_session_key_uses_fallback(cup, tmp_path):
+    """If both transcript_path and session_id are absent, the hook passes
+    None for session_key. The reader uses 'unknown' so the marker still
+    deduplicates instead of re-firing on every prompt."""
+    marker = tmp_path / ".pending_graduation"
+    now = datetime.now(timezone.utc)
+    _write_marker(marker, {
+        "graduations": [{"id": "g", "name": "G"}],
+        "created_at": now.isoformat(),
+        "consumed_by": [],
+    })
+
+    first = cup._read_and_consume(marker, None, now)
+    assert first is not None
+
+    second = cup._read_and_consume(marker, None, now)
+    assert second is None, "successive None-keyed polls should still dedupe"
+
+    raw = json.loads(marker.read_text())
+    assert raw["consumed_by"] == ["unknown"]
+
+
+def test_missing_marker_returns_none(cup, tmp_path):
+    marker = tmp_path / ".pending_graduation"  # never created
+    now = datetime.now(timezone.utc)
+    assert cup._read_and_consume(marker, "session-A", now) is None

package/coach/tests/test_marker_writer_locking.py

@@ -0,0 +1,305 @@
+"""Marker writer locking — guards against the v0.2.0 race where readers
+acquired a sidecar flock but writers in `merge.py` / `stats.py` did not.
+
+Race the test reproduces:
+  1. Marker exists with [old], consumed_by=[].
+  2. Reader (no lock yet) reads → snapshot of [old].
+  3. /coach-insights writer commits new → marker becomes [old, new].
+  4. Reader replaces with stale snapshot → marker drops back to [old].
+  5. The "new" event is silently lost.
+
+Fix under test: writers acquire the same `<marker>.lock` flock the reader
+takes in `_read_and_consume()`, so the read-modify-write windows are
+serialized and a stale-snapshot reader can't clobber a writer's commit.
+"""
+from __future__ import annotations
+
+import fcntl
+import importlib.util
+import json
+import threading
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture
+def merge_mod(tmp_path, monkeypatch):
+    """Load coach/bin/merge.py with marker paths redirected to tmp_path."""
+    path = Path(__file__).resolve().parents[1] / "bin" / "merge.py"
+    spec = importlib.util.spec_from_file_location(
+        f"merge_locking_{tmp_path.name}", str(path)
+    )
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    monkeypatch.setattr(mod, "GRADUATION_MARKER", tmp_path / ".pending_graduation")
+    monkeypatch.setattr(mod, "REGRESSION_MARKER", tmp_path / ".pending_regression")
+    monkeypatch.setattr(mod, "STREAK_REWARD_MARKER", tmp_path / ".pending_streak_rewards")
+    return mod
+
+
+@pytest.fixture
+def stats_mod(tmp_path, monkeypatch):
+    """Load coach/bin/stats.py with marker paths redirected to tmp_path."""
+    path = Path(__file__).resolve().parents[1] / "bin" / "stats.py"
+    spec = importlib.util.spec_from_file_location(
+        f"stats_locking_{tmp_path.name}", str(path)
+    )
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    monkeypatch.setattr(mod, "LEVELUP_MARKER", tmp_path / ".pending_levelup")
+    monkeypatch.setattr(mod, "LEVEL_STATE", tmp_path / ".level_state.json")
+    return mod
+
+
+@pytest.fixture
+def cup_mod(tmp_path, monkeypatch):
+    """Load hooks/coach-user-prompt.py with tip state redirected to tmp_path."""
+    path = Path(__file__).resolve().parents[2] / "hooks" / "coach-user-prompt.py"
+    spec = importlib.util.spec_from_file_location(
+        f"cup_locking_{tmp_path.name}", str(path)
+    )
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    monkeypatch.setattr(mod, "TIP_STATE", tmp_path / ".tip_state.json")
+    return mod
+
+
+def _hold_lock(lock_path: Path):
+    """Open and exclusively lock a sidecar lockfile. Returns the file
+    handle so the caller can release it explicitly."""
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    fh = open(lock_path, "w")
+    fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+    return fh
+
+
+def test_graduation_writer_blocks_when_reader_lock_held(merge_mod, tmp_path):
+    """The graduation marker writer must wait on the same sidecar flock
+    the reader uses. Without writer locking this thread would complete
+    immediately and a stale-snapshot reader could clobber its write."""
+    marker = tmp_path / ".pending_graduation"
+    lock_path = tmp_path / ".pending_graduation.lock"
+    holder = _hold_lock(lock_path)
+    completed = threading.Event()
+
+    def writer():
+        merge_mod._append_graduation_marker(
+            [{"id": "new", "name": "New"}],
+            datetime.now(timezone.utc),
+        )
+        completed.set()
+
+    t = threading.Thread(target=writer, daemon=True)
+    t.start()
+
+    # Writer must NOT complete while the lock is held.
+    assert not completed.wait(timeout=0.3), (
+        "writer should be blocked on the marker sidecar lock"
+    )
+
+    fcntl.flock(holder.fileno(), fcntl.LOCK_UN)
+    holder.close()
+
+    assert completed.wait(timeout=2.0), (
+        "writer should complete promptly after lock is released"
+    )
+    t.join(timeout=1.0)
+
+    raw = json.loads(marker.read_text())
+    assert raw["graduations"] == [{"id": "new", "name": "New"}]
+    assert raw["consumed_by"] == []  # fresh write resets
+
+
+def test_regression_writer_takes_lock(merge_mod, tmp_path):
+    marker = tmp_path / ".pending_regression"
+    lock_path = tmp_path / ".pending_regression.lock"
+    holder = _hold_lock(lock_path)
+    completed = threading.Event()
+
+    def writer():
+        merge_mod._append_regression_marker(
+            [{"id": "r1", "name": "R1"}],
+            datetime.now(timezone.utc),
+        )
+        completed.set()
+
+    t = threading.Thread(target=writer, daemon=True)
+    t.start()
+    assert not completed.wait(timeout=0.3)
+    fcntl.flock(holder.fileno(), fcntl.LOCK_UN)
+    holder.close()
+    assert completed.wait(timeout=2.0)
+    t.join(timeout=1.0)
+    assert json.loads(marker.read_text())["regressions"] == [{"id": "r1", "name": "R1"}]
+
+
+def test_streak_reward_writer_takes_lock(merge_mod, tmp_path):
+    marker = tmp_path / ".pending_streak_rewards"
+    lock_path = tmp_path / ".pending_streak_rewards.lock"
+    holder = _hold_lock(lock_path)
+    completed = threading.Event()
+
+    def writer():
+        merge_mod._append_streak_reward_marker(
+            [{"id": "s1", "name": "S1", "streak": 2}],
+            datetime.now(timezone.utc),
+        )
+        completed.set()
+
+    t = threading.Thread(target=writer, daemon=True)
+    t.start()
+    assert not completed.wait(timeout=0.3)
+    fcntl.flock(holder.fileno(), fcntl.LOCK_UN)
+    holder.close()
+    assert completed.wait(timeout=2.0)
+    t.join(timeout=1.0)
+    assert json.loads(marker.read_text())["rewards"] == [
+        {"id": "s1", "name": "S1", "streak": 2}
+    ]
+
+
+def test_levelup_writer_takes_lock(stats_mod, tmp_path):
+    """`stats.py:_check_and_mark_level_up` must lock around its level-up
+    marker write so a stale-snapshot reader can't drop a fresh celebration."""
+    marker = tmp_path / ".pending_levelup"
+    lock_path = tmp_path / ".pending_levelup.lock"
+    holder = _hold_lock(lock_path)
+    completed = threading.Event()
+
+    def writer():
+        # First-ever level-up path: last_state is None, current_idx > 0.
+        stats_mod._check_levelup(
+            current_idx=2,
+            current_name=stats_mod.LEVELS[2][1],
+            xp=120,
+        )
+        completed.set()
+
+    t = threading.Thread(target=writer, daemon=True)
+    t.start()
+    assert not completed.wait(timeout=0.3), (
+        "level-up writer should block on marker sidecar lock"
+    )
+
+    fcntl.flock(holder.fileno(), fcntl.LOCK_UN)
+    holder.close()
+
+    assert completed.wait(timeout=2.0)
+    t.join(timeout=1.0)
+
+    raw = json.loads(marker.read_text())
+    assert raw["to_idx"] == 2
+    assert raw["xp_at_levelup"] == 120
+    assert raw["consumed_by"] == []
+
+
+def test_level_state_writer_takes_lock(stats_mod, tmp_path):
+    """The high-water level-state file must be serialized too.
+
+    Without this lock, concurrent statusline renders could both observe a stale
+    or missing .level_state.json and duplicate the same level-up marker.
+    """
+    lock_path = tmp_path / ".level_state.json.lock"
+    holder = _hold_lock(lock_path)
+    completed = threading.Event()
+
+    def writer():
+        stats_mod._check_levelup(
+            current_idx=0,
+            current_name=stats_mod.LEVELS[0][1],
+            xp=0,
+        )
+        completed.set()
+
+    t = threading.Thread(target=writer, daemon=True)
+    t.start()
+    assert not completed.wait(timeout=0.3), (
+        "level-state writer should block on the level-state sidecar lock"
+    )
+
+    fcntl.flock(holder.fileno(), fcntl.LOCK_UN)
+    holder.close()
+
+    assert completed.wait(timeout=2.0)
+    t.join(timeout=1.0)
+    assert json.loads((tmp_path / ".level_state.json").read_text()) == {"level_idx": 0}
+
+
+def test_tip_state_writer_takes_lock(cup_mod, tmp_path):
+    lock_path = tmp_path / ".tip_state.json.lock"
+    holder = _hold_lock(lock_path)
+    completed = threading.Event()
+
+    def writer():
+        cup_mod._save_tip_state({"last_global_fire": "2026-05-06T00:00:00+00:00"})
+        completed.set()
+
+    t = threading.Thread(target=writer, daemon=True)
+    t.start()
+    assert not completed.wait(timeout=0.3), (
+        "tip-state writer should block on the tip-state sidecar lock"
+    )
+
+    fcntl.flock(holder.fileno(), fcntl.LOCK_UN)
+    holder.close()
+
+    assert completed.wait(timeout=2.0)
+    t.join(timeout=1.0)
+    raw = json.loads((tmp_path / ".tip_state.json").read_text())
+    assert raw["last_global_fire"] == "2026-05-06T00:00:00+00:00"
+
+
+def test_existing_entries_preserved_across_writes(merge_mod, tmp_path):
+    """Two sequential writer calls must merge into a combined list, not
+    overwrite. consumed_by + created_at reset on each write so newly-added
+    entries reach previously-consumed sessions."""
+    now = datetime.now(timezone.utc)
+    merge_mod._append_graduation_marker(
+        [{"id": "old", "name": "Old"}], now
+    )
+    raw_before = json.loads((tmp_path / ".pending_graduation").read_text())
+    assert [g["id"] for g in raw_before["graduations"]] == ["old"]
+
+    # Pretend a session consumed it.
+    raw_before["consumed_by"] = ["session-A"]
+    (tmp_path / ".pending_graduation").write_text(json.dumps(raw_before))
+
+    merge_mod._append_graduation_marker(
+        [{"id": "new", "name": "New"}], now
+    )
+    raw_after = json.loads((tmp_path / ".pending_graduation").read_text())
+    assert [g["id"] for g in raw_after["graduations"]] == ["old", "new"]
+    assert raw_after["consumed_by"] == [], (
+        "writer must reset consumed_by so already-consumed sessions still see "
+        "the new entry on their next poll"
+    )
+
+
+def test_concurrent_writers_dont_lose_entries(merge_mod, tmp_path):
+    """Stress test: 20 concurrent _append_graduation_marker calls must
+    land all 20 entries (no race-window drops). With unlocked writers
+    this would lose entries; with locking it must not."""
+    now = datetime.now(timezone.utc)
+    threads = []
+    for i in range(20):
+        ident = f"g{i}"
+        t = threading.Thread(
+            target=lambda i=ident: merge_mod._append_graduation_marker(
+                [{"id": i, "name": i}], now
+            ),
+            daemon=True,
+        )
+        threads.append(t)
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join(timeout=5.0)
+        assert not t.is_alive()
+
+    raw = json.loads((tmp_path / ".pending_graduation").read_text())
+    ids = sorted(g["id"] for g in raw["graduations"])
+    expected = sorted(f"g{i}" for i in range(20))
+    assert ids == expected, f"expected all 20 entries, got {ids}"