feat: broadcast Timmy state changes via WS relay (#380)

Co-authored-by: Kimi Agent <kimi@timmy.local>
Co-committed-by: Kimi Agent <kimi@timmy.local>

tests/timmy/test_workshop_state.py

@@ -98,7 +98,8 @@ def test_state_hash_detects_mood_change():
 # ---------------------------------------------------------------------------
 
 
-def test_write_if_changed_writes_on_first_call(tmp_path):
+@pytest.mark.asyncio
+async def test_write_if_changed_writes_on_first_call(tmp_path):
     target = tmp_path / "presence.json"
     hb = WorkshopHeartbeat(interval=60, path=target)
 
@@ -109,7 +110,7 @@ def test_write_if_changed_writes_on_first_call(tmp_path):
             "current_focus": "testing",
             "mood": "focused",
         }
-        hb._write_if_changed()
+        await hb._write_if_changed()
 
     assert target.exists()
     data = json.loads(target.read_text())
@@ -117,22 +118,24 @@ def test_write_if_changed_writes_on_first_call(tmp_path):
     assert data["current_focus"] == "testing"
 
 
-def test_write_if_changed_skips_when_unchanged(tmp_path):
+@pytest.mark.asyncio
+async def test_write_if_changed_skips_when_unchanged(tmp_path):
     target = tmp_path / "presence.json"
     hb = WorkshopHeartbeat(interval=60, path=target)
 
     fixed_state = {"version": 1, "liveness": "t1", "mood": "idle"}
 
     with patch("timmy.workshop_state.get_state_dict", return_value=fixed_state):
-        hb._write_if_changed()  # First write
+        await hb._write_if_changed()  # First write
         target.write_text("")  # Clear to detect if second write happens
-        hb._write_if_changed()  # Should skip — state unchanged
+        await hb._write_if_changed()  # Should skip — state unchanged
 
     # File should still be empty (second write was skipped)
     assert target.read_text() == ""
 
 
-def test_write_if_changed_writes_on_state_change(tmp_path):
+@pytest.mark.asyncio
+async def test_write_if_changed_writes_on_state_change(tmp_path):
     target = tmp_path / "presence.json"
     hb = WorkshopHeartbeat(interval=60, path=target)
 
@@ -140,15 +143,54 @@ def test_write_if_changed_writes_on_state_change(tmp_path):
     state_b = {"version": 1, "liveness": "t2", "mood": "focused"}
 
     with patch("timmy.workshop_state.get_state_dict", return_value=state_a):
-        hb._write_if_changed()
+        await hb._write_if_changed()
 
     with patch("timmy.workshop_state.get_state_dict", return_value=state_b):
-        hb._write_if_changed()
+        await hb._write_if_changed()
 
     data = json.loads(target.read_text())
     assert data["mood"] == "focused"
 
 
+@pytest.mark.asyncio
+async def test_write_if_changed_calls_on_change(tmp_path):
+    """on_change callback is invoked with state dict when state changes."""
+    target = tmp_path / "presence.json"
+    received = []
+
+    async def capture(state_dict):
+        received.append(state_dict)
+
+    hb = WorkshopHeartbeat(interval=60, path=target, on_change=capture)
+
+    state = {"version": 1, "liveness": "t1", "mood": "focused"}
+    with patch("timmy.workshop_state.get_state_dict", return_value=state):
+        await hb._write_if_changed()
+
+    assert len(received) == 1
+    assert received[0]["mood"] == "focused"
+
+
+@pytest.mark.asyncio
+async def test_write_if_changed_skips_on_change_when_unchanged(tmp_path):
+    """on_change is NOT called when state hash is unchanged."""
+    target = tmp_path / "presence.json"
+    call_count = 0
+
+    async def counter(_):
+        nonlocal call_count
+        call_count += 1
+
+    hb = WorkshopHeartbeat(interval=60, path=target, on_change=counter)
+
+    state = {"version": 1, "liveness": "t1", "mood": "idle"}
+    with patch("timmy.workshop_state.get_state_dict", return_value=state):
+        await hb._write_if_changed()
+        await hb._write_if_changed()
+
+    assert call_count == 1
+
+
 # ---------------------------------------------------------------------------
 # WorkshopHeartbeat — notify
 # ---------------------------------------------------------------------------