docs: presence-polish plan (voice-every-reply, idle anger, mute fix, fog-veil, finale speed)

docs/superpowers/plans/2026-06-13-presence-polish.md

@@ -0,0 +1,351 @@
+# Presence Polish — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan phase-by-phase. Steps use checkbox (`- [ ]`) syntax. Stay on git branch `feat/voice-awareness`.
+
+**Goal:** Five fixes/changes on top of the voice+awareness work: (1) Hollow speaks **every** reply, (2) ignoring Hollow **drops the bond and turns it hostile**, (3) the **mute button actually works**, (4) the child **materializes through fog/darkness instead of a blur** (the blur read as a broken image), (5) the **finale narration is slightly faster**.
+
+**Context:** This continues the `feat/voice-awareness` branch (voice via Kokoro on the Space, silent on the local 3.13 `.venv`; voice works in the 3.12 `.venv-tts`). Output tuples for the chat event have 8 elements (index 7 = voice channel). The idle behavior runs on a `gr.Timer` via `_on_idle`. Run tests with `.venv/Scripts/python -m pytest -q` (currently 199 green — keep them green). Voice smoke test runs in `.venv-tts`.
+
+**Decisions already made (do not reopen):** materialization = sharp child veiled in fog + darkness (no blur); ignoring = drops affinity + tone AND escalates to hostile lines.
+
+---
+
+## PHASE 1 — Hollow speaks every reply
+
+**Files:** Modify `app.py`, `tests/test_app.py`.
+
+Today voice plays only on recall turns. Make every Hollow reply spoken (still gated by the mute flag). Latency cost ~1–2 s/turn is acceptable.
+
+- [ ] **Step 1: Failing test** (append to `tests/test_app.py`, class `TestVoice`):
+
+```python
+    def test_every_reply_is_spoken_not_just_recall(self, monkeypatch):
+        monkeypatch.setattr(app, "run_turn",
+                            lambda *a, **k: ("the wind is cold tonight.", '{"affinity_delta":1}'))
+        monkeypatch.setattr(app.time, "sleep", lambda s: None)
+        monkeypatch.setattr(app, "should_recall", lambda s: (False, None))  # NO recall
+        monkeypatch.setattr(app, "speak", lambda text: "FAKEB64")
+        state = _state(affinity=30, treasure=[], claimed=[], tone=0)
+        outs = list(app.chat("hello", state, []))
+        assert "FAKEB64" in outs[-1][7]          # a plain reply is spoken too
+```
+
+- [ ] **Step 2: Run, verify fail** — `.venv/Scripts/python -m pytest tests/test_app.py -k every_reply -q` (the non-recall reply currently yields "" at index 7).
+
+- [ ] **Step 3: Implement.** In `chat()`, find the normal-turn voice computation (added for recall):
+```python
+    voice = (_voice_html(speak(reply))
+             if do_recall and recall_memory and not turn_failed
+             and state.get("voice_on", True)
+             else "")
+```
+Replace with (speak every reply; `speak` returns None safely on failure, and a voiced fog-fallback reply is fine — it's in character):
+```python
+    voice = _voice_html(speak(reply)) if state.get("voice_on", True) else ""
+```
+
+- [ ] **Step 4: Run** `tests/test_app.py -k Voice` then the full suite → green.
+
+- [ ] **Step 5: Commit**
+```bash
+git add app.py tests/test_app.py
+git commit -m "feat: Hollow speaks every reply, not just the recall
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+## PHASE 2 — Finale narration slightly faster
+
+**Files:** Modify `voice.py`, `app.py`.
+
+Two levers: a small TTS speed bump and less padding between finale lines.
+
+- [ ] **Step 1:** In `voice.py`, change `_SPEED = 0.80` to `_SPEED = 0.88`.
+
+- [ ] **Step 2:** In `app.py` `_voice_and_pause`, reduce the inter-line gap: change `pause = max(pause, _audio_seconds(b64) + 0.4)` to `pause = max(pause, _audio_seconds(b64) + 0.15)`.
+
+- [ ] **Step 3:** Run the full suite → green (no test asserts the speed constant; behavior unchanged structurally).
+
+- [ ] **Step 4: Commit**
+```bash
+git add voice.py app.py
+git commit -m "tune: slightly faster finale narration (TTS speed 0.88, less gap)
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+> Note for the orchestrator: after deploy, the user re-confirms the voice still sounds right at 0.88 by ear. Easy to revert toward 0.80 if needed.
+
+---
+
+## PHASE 3 — Make the mute button work
+
+**Files:** Modify `app.py`, `tests/test_app.py`.
+
+Root cause: `_toggle_voice` copies the state (`dict(state)`), so a streaming finale keeps its old `voice_on`; and it never clears audio already playing. Fix: mutate in place + clear the voice channel on mute.
+
+- [ ] **Step 1: Failing test** (append to `tests/test_app.py`, e.g. new class `TestMute`):
+
+```python
+class TestMute:
+    def test_toggle_mutates_in_place_and_clears_audio_on_mute(self):
+        state = {"voice_on": True}
+        new_state, btn, voice = app._toggle_voice(state)
+        assert new_state is state                 # same object (in place)
+        assert state["voice_on"] is False         # muted
+        assert voice == ""                        # current audio cleared
+        # toggle back on
+        new_state2, btn2, voice2 = app._toggle_voice(state)
+        assert state["voice_on"] is True
+        assert not isinstance(voice2, str)        # no-op update when un-muting
+```
+
+- [ ] **Step 2: Run, verify fail** — current `_toggle_voice` returns a copy and only 2 values.
+
+- [ ] **Step 3: Implement.** Replace `_toggle_voice`:
+```python
+def _toggle_voice(state):
+    # mutate IN PLACE so a finale already streaming sees the change; clear the
+    # voice channel when muting so audio already playing stops immediately
+    on = not state.get("voice_on", True)
+    state["voice_on"] = on
+    voice = gr.update() if on else ""
+    return state, gr.update(value="🔊" if on else "🔇"), voice
+```
+
+- [ ] **Step 4:** Update the wiring to also output `voice_panel`. Find:
+```python
+    voice_btn.click(_toggle_voice, [state], [state, voice_btn], show_progress="hidden")
+```
+Replace with:
+```python
+    voice_btn.click(_toggle_voice, [state], [state, voice_btn, voice_panel], show_progress="hidden")
+```
+
+- [ ] **Step 5:** Run the full suite → green.
+
+- [ ] **Step 6: Commit**
+```bash
+git add app.py tests/test_app.py
+git commit -m "fix: mute toggle mutates in place + clears current audio
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+> Orchestrator manual check (in `.venv-tts`): mute during normal play silences the next reply; mute during a finale stops further lines (in-place flag) and clears the current audio. If Gradio serializes the click behind a streaming finale, mute applies as soon as the event runs — document actual behavior.
+
+---
+
+## PHASE 4 — Ignoring Hollow drops the bond and turns it hostile
+
+**Files:** Modify `app.py`, `tests/test_app.py`.
+
+The idle nudge becomes tiered (plead → hurt → hostile by `idle_count`) and each nudge lowers affinity + tone. The Bond meter must update live, so `_on_idle` gains a 4th output (`bond_panel`).
+
+- [ ] **Step 1: Failing tests** (replace the existing `TestIdle` body's relevant tests; `_on_idle` now returns 4 values):
+
+```python
+class TestIdle:
+    def test_idle_appends_a_canned_line_and_drops_bond(self, monkeypatch):
+        import time as _t
+        monkeypatch.setattr(app, "speak", lambda text: None)
+        state = _state(affinity=30, treasure=[], claimed=[], tone=0)
+        state["last_activity"] = _t.time() - 999     # long idle
+        state["greeted"] = True
+        new_state, hist, voice, bond = app._on_idle(
+            state, [{"role": "assistant", "content": "x"}])
+        assert hist[-1]["role"] == "assistant"
+        assert new_state["affinity"] < 30            # ignoring lowers the bond
+        assert new_state["tone"] < 0                 # and sours the tone
+        assert "bond-meter" in bond                  # the meter re-rendered
+
+    def test_idle_escalates_to_hostile(self, monkeypatch):
+        import time as _t
+        monkeypatch.setattr(app, "speak", lambda text: None)
+        state = _state(affinity=40, treasure=[], claimed=[], tone=0)
+        state["greeted"] = True
+        state["idle_count"] = 5                       # already ignored a lot
+        state["last_activity"] = _t.time() - 999
+        _, hist, _, _ = app._on_idle(state, [{"role": "assistant", "content": "x"}])
+        assert hist[-1]["content"] in app._IDLE_TIERS[2]   # the hostile tier
+
+    def test_idle_silent_returns_four_noops_when_active_or_ended(self, monkeypatch):
+        import time as _t
+        monkeypatch.setattr(app, "speak", lambda text: None)
+        s1 = _state(); s1["greeted"] = True; s1["last_activity"] = _t.time()
+        out = app._on_idle(s1, [{"role": "assistant", "content": "x"}])
+        assert len(out) == 4
+        assert not isinstance(out[1], list)          # chatbot untouched
+
+    def test_first_tick_voices_the_opening_once(self, monkeypatch):
+        import time as _t
+        monkeypatch.setattr(app, "speak", lambda text: "GREETB64")
+        state = _state(affinity=20, treasure=[], claimed=[], turn=0)
+        new_state, chat_update, voice, bond = app._on_idle(
+            state, [{"role": "assistant", "content": OPENING_LINE}])
+        assert new_state["greeted"] is True
+        assert "GREETB64" in voice
+        assert not isinstance(chat_update, list)
+```
+
+- [ ] **Step 2: Run, verify fail** — `_on_idle` currently returns 3 values, no tiers, no bond drop.
+
+- [ ] **Step 3: Implement.** Replace `_IDLE_LINES` with tiers and add decay constants:
+```python
+_IDLE_TIERS = [
+    ["...are you still there?", "don't go. not yet."],                 # plead
+    ["you're not even listening.", "you said you would stay."],         # hurt
+    ["fine. ignore me. they all do, before the end.",                   # hostile
+     "you think i cannot reach you out there?"],
+]
+_IDLE_AFTER = 12.0          # seconds of silence before Hollow speaks first
+_IDLE_AFFINITY_DROP = 3     # bond lost per ignored nudge
+_IDLE_TONE_DROP = 2         # tone soured per ignored nudge
+```
+Rewrite `_on_idle` to return `(state, chatbot, voice, bond)`:
+```python
+def _on_idle(state: dict, history: list):
+    """gr.Timer tick. Greets once early; otherwise, when the visitor has gone
+    quiet, Hollow speaks first — escalating plead -> hurt -> hostile — and each
+    nudge lowers the bond and sours the tone. Returns (state, chatbot, voice,
+    bond); non-speaking ticks return no-op updates so a streaming finale is
+    never clobbered."""
+    # greet once, early (plays on the visitor's first gesture)
+    if (not state.get("greeted") and not state.get("ended")
+            and state.get("turn", 0) == 0):
+        state = dict(state)
+        state["greeted"] = True
+        state["last_activity"] = time.time()       # start the idle clock now
+        voice = (_voice_html(speak(OPENING_LINE))
+                 if state.get("voice_on", True) else gr.update())
+        return state, gr.update(), voice, gr.update()
+    if (state.get("ended") or not history
+            or time.time() - state.get("last_activity", time.time()) < _IDLE_AFTER):
+        return state, gr.update(), gr.update(), gr.update()
+    state = dict(state)
+    i = state.get("idle_count", 0)
+    tier = _IDLE_TIERS[min(i // 2, len(_IDLE_TIERS) - 1)]
+    line = tier[i % len(tier)]
+    state["idle_count"] = i + 1
+    state["last_activity"] = time.time()
+    state["affinity"] = max(0, state.get("affinity", 20) - _IDLE_AFFINITY_DROP)
+    state["tone"] = max(-100, state.get("tone", 0) - _IDLE_TONE_DROP)
+    history = history + [{"role": "assistant", "content": line}]
+    voice = _voice_html(speak(line)) if state.get("voice_on", True) else ""
+    bond = _render_bond(state["affinity"], get_tier(state["affinity"]))
+    return state, history, voice, bond
+```
+
+- [ ] **Step 4:** Update the timer wiring to add `bond_panel` as the 4th output:
+```python
+    idle_timer.tick(_on_idle, [state, chatbot],
+                    [state, chatbot, voice_panel, bond_panel],
+                    show_progress="hidden")
+```
+
+- [ ] **Step 5:** Run the full suite → green. (Confirm the old 3-value idle tests are replaced by the 4-value versions above.)
+
+- [ ] **Step 6: Commit**
+```bash
+git add app.py tests/test_app.py
+git commit -m "feat: ignoring Hollow drops the bond and escalates to hostility
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+## PHASE 5 — Materialize through fog + darkness, not blur
+
+**Files:** Modify `render.py`, `tests/test_render.py`.
+
+Replace the CSS blur (which reads as a broken/loading image) with brightness (shadow → light) + denser fog at low bond. The child stays sharp.
+
+- [ ] **Step 1: Read** `render.py` `render_entity` top (the `t = min(a, 45) / 45` materialization block and the `look = f"filter:blur(...)..."` line, plus the `entity-almost` overlay which also uses `blur`).
+
+- [ ] **Step 2: Failing test** (append to `tests/test_render.py`):
+
+```python
+class TestMaterialization:
+    def test_low_bond_uses_darkness_and_fog_not_blur(self):
+        html = render_entity(10, "idle", seq=0)      # barely materialized
+        assert "blur(" not in html                    # no loading-look blur
+        assert "brightness(" in html                  # shadowed instead
+    def test_high_bond_is_bright_and_clear(self):
+        html = render_entity(45, "idle", seq=0)
+        assert "brightness(1" in html or "brightness(0.9" in html
+```
+
+- [ ] **Step 3: Run, verify fail** (idle render still emits `blur(`).
+
+- [ ] **Step 4: Implement.** In `render_entity`, replace the materialization computation:
+```python
+    t = min(a, 45) / 45  # fully materialized by bond 45
+    # veil the SHARP child in shadow + fog instead of blurring it (a blur reads
+    # as a broken/loading image): dark and fog-shrouded at low bond, emerging
+    brightness = round(0.4 + 0.6 * t, 2)
+    opacity = round(0.7 + 0.3 * t, 2)
+    almost_on = a >= 76
+    flash_key = f"flash-{seq % 2}"
+
+    # the fog curtain stays denser while the child is still a shadow
+    fog_op = round(1 - 0.7 * t, 2)
+    grain_op = round(0.13 - 0.08 * t, 2)
+    vig_op = round(1 - 0.5 * t, 2)
+
+    look = f"filter:brightness({brightness});opacity:{opacity};"
+```
+(Remove the old `blur = ...` line and the old `look = f"filter:blur({blur}px);opacity:{opacity};"`.)
+
+Then in the `else` (idle/default) branch, the `entity-almost` overlay currently uses `blur`:
+```python
+            f'<img class="entity-img entity-almost" src="{_src("almost")}" '
+            f'style="filter:blur({blur}px);opacity:{almost_op};">'
+```
+Change it to brightness too:
+```python
+            f'<img class="entity-img entity-almost" src="{_src("almost")}" '
+            f'style="filter:brightness({brightness});opacity:{almost_op};">'
+```
+Search the whole function for any remaining reference to the now-deleted `blur` variable and remove/replace it (the fixed modes like rage/end/peace use literal `filter:blur(0px)` strings — those are fine to leave as-is, they're a literal 0 blur on the final faces).
+
+- [ ] **Step 5: Run** `tests/test_render.py` → green. Fix any existing render test that asserted `blur(` in the idle render.
+
+- [ ] **Step 6: Visual verification (REQUIRED — CSS lies in the harness).** Orchestrator launches the app and screenshots at low and mid bond:
+  - `.venv/Scripts/python app.py` (normal start = affinity 20), headless screenshot, Read the PNG: the child should look like a dark shape in fog (intentional), NOT a blurry broken image.
+  - Confirm it brightens/clears as bond rises (can seed via `HOLLOW_FAST_FINALE=good` to see a high-bond render, or trust the formula).
+  - Kill the port owner after.
+
+- [ ] **Step 7: Commit**
+```bash
+git add render.py tests/test_render.py
+git commit -m "feat: materialize the child through fog + shadow, not a blur
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+## FINAL — full verification
+
+- [ ] **Step 1:** `.venv/Scripts/python -m pytest -q` → all green.
+- [ ] **Step 2: Voice smoke** (`.venv-tts`): `python -c "import voice; print(voice._SPEED, bool(voice.speak('the sea. that was me.')))"` → `0.88 True`.
+- [ ] **Step 3: Live local test** (`.venv-tts`, voice active): play a normal turn (needs Ollama for real replies — `ollama serve` + `qwen3:8b`) and confirm: every reply is spoken; muting silences it; ignoring for ~30 s drops the Bond meter and turns the lines hostile; the child looks fog-shrouded not blurry; the finale narration is a touch faster.
+- [ ] **Step 4: Deploy mirror-first** (orchestrator, with the user's go-ahead): merge `feat/voice-awareness` → `main`, push to the personal mirror (`space`), verify the build + voice live, THEN push to the submission (`hackathon`).
+
+```bash
+git push space main      # mirror first
+# verify, then:
+git push hackathon main
+```
+
+---
+
+## Self-review notes
+- Phases are independent; ship order 1→5. If time runs short, 1+3+5 alone are clear wins.
+- `_on_idle` now returns **4** values and the timer outputs **4** — keep them in sync.
+- Never put voice audio in the entity panel (it breaks the heartbeat-stable HTML); voice lives in `voice_panel`.
+- The materialization change is visual — verify against the RUNNING app, never the static harness.
+- Voice is import-guarded: locally (3.13) it's silent; that's expected. All voice assertions in tests monkeypatch `speak`.