docs: voice+awareness spec and plan; gitignore sample wavs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.gitattributes

@@ -0,0 +1 @@
+*.webp filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -226,5 +226,9 @@ assets/*.png
 # Visual check harness output
 tools/_visual/
 
-# Synthesized audio previews (sting.py writes these; audio is synth at runtime)
+# Synthesized / sample audio (synth at runtime; never commit binaries)
 *preview*.wav
+sample_*.wav
+
+# Throwaway TTS validation venv
+.venv-tts/

docs/superpowers/plans/2026-06-13-presence-voice-and-awareness.md

@@ -0,0 +1,525 @@
+# Presence: Voice + Awareness — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax.
+
+**Goal:** Make Hollow feel present. **A)** The child speaks (whispered Kokoro TTS on the recall and on every Hollow line in the finales). **B)** The child is aware (notices how you write, brings up your memories unprompted, and speaks first when you go silent).
+
+**Architecture:** Qwen3-8B is untouched. A new CPU-only `voice.py` synthesizes audio via Kokoro-82M with a locked DSP recipe and returns base64 WAV. A new hidden `voice_panel` (gr.HTML) carries the voice `<audio>` on its own channel so it never disturbs the entity panel's stable-HTML heartbeat. B is mostly prompt+state; B1 uses a validated `gr.Timer`.
+
+**Both unknowns are validated:** Kokoro runs offline on CPU (voice cast = `af_nicole`, filter 28%); `gr.Timer` fires, reads/writes `gr.State`, and appends to the Chatbot.
+
+**Tech stack:** Kokoro-82M (`kokoro` pkg), numpy DSP, Gradio 6.17 (`gr.Timer`, `gr.HTML`), pytest.
+
+---
+
+## Critical background for the implementer
+
+- **The local dev venv is Python 3.13; Kokoro requires <3.13.** So `import kokoro` FAILS locally. `voice.py` MUST guard its import: on failure, `speak()` returns `None` and the app runs **silent**. Voice works on the Space (pinned to 3.11). Tests run on the 3.13 venv, so **tests must not require kokoro** — mock it / test the guard + the pure DSP.
+- **The entity panel relies on byte-identical HTML across finale steps** so the looped heartbeat audio doesn't remount (see `render.py` build mode). Therefore voice audio MUST NOT go in the entity HTML during finales — it goes in a separate `voice_panel`. (On a normal recall turn there's no heartbeat, but we use the same `voice_panel` everywhere for uniformity.)
+- **Output tuples grow 7→8.** Every `yield` in `chat()` and the three finale players, plus `_reset`, plus the event `outputs=[...]` lists, gain `voice_panel` as the **last** element. Existing tests index `outs[-1][0..6]`, so appending at index 7 keeps them valid.
+- Audio is inlined as `<audio autoplay src="data:audio/wav;base64,...">` — the exact mechanism the chimes/sting use (no JS).
+- Reuse `from sting import _wav` to encode float audio → WAV bytes.
+- Run tests: `.venv/Scripts/python -m pytest -q` (183 currently green; keep them green).
+
+---
+
+# PART A — VOICE
+
+### Task A1: `voice.py` — Kokoro pipeline + locked DSP + guarded `speak()`
+
+**Files:** Create `voice.py`; Create `tests/test_voice.py`.
+
+- [ ] **Step 1: Write the failing tests** (`tests/test_voice.py`):
+
+```python
+"""voice.py must be import-safe even without kokoro (the 3.13 test venv has
+none): the DSP is pure numpy and testable; speak() degrades to None."""
+import numpy as np
+
+import voice
+
+
+def test_dsp_functions_are_pure_numpy():
+    x = np.sin(np.linspace(0, 20, 24000)).astype(np.float32)
+    up = voice._pitch_up(x, 1.16)
+    assert up.dtype == np.float32 and len(up) < len(x)   # pitch-up shortens
+    fogged = voice._fog(x, intensity=0.28)
+    assert np.max(np.abs(fogged)) <= 0.86                # normalized headroom
+
+
+def test_speak_returns_none_when_pipeline_unavailable():
+    # the 3.13 test venv has no kokoro -> _PIPELINE is None -> silent
+    if voice._PIPELINE is None:
+        assert voice.speak("the sea. i grew up near the sea.") is None
+
+
+def test_speak_is_guarded_against_errors(monkeypatch):
+    # even if a pipeline exists, a synth error must degrade to None, never raise
+    monkeypatch.setattr(voice, "_PIPELINE", object())  # a bogus pipeline
+    assert voice.speak("anything") is None
+```
+
+- [ ] **Step 2: Run, verify fail**
+
+`.venv/Scripts/python -m pytest tests/test_voice.py -q` → ImportError (no `voice`).
+
+- [ ] **Step 3: Implement `voice.py`**
+
+```python
+"""Hollow's voice: Kokoro-82M whispered through a locked DSP recipe (the
+validated 'af_nicole, 28% fog' cast). CPU only — no GPU budget. Import is
+guarded: where kokoro is unavailable (e.g. the Python 3.13 dev venv) the app
+runs silent instead of crashing."""
+import base64
+
+import numpy as np
+
+from sting import _wav
+
+_SR = 24000
+_VOICE = "af_nicole"
+_SPEED = 0.80
+_FILTER_INTENSITY = 0.28   # the "verylight" setting the user picked
+
+try:
+    from kokoro import KPipeline
+    _PIPELINE = KPipeline(lang_code="a")
+except Exception as e:          # no kokoro / no model / wrong python -> silent
+    print(f"[voice] disabled ({e!r})")
+    _PIPELINE = None
+
+
+def _pitch_up(x, factor):
+    n = int(len(x) / factor)
+    idx = np.linspace(0, len(x) - 1, n)
+    return np.interp(idx, np.arange(len(x)), x).astype(np.float32)
+
+
+def _breath(x, amount):
+    rng = np.random.default_rng(3)
+    env = np.abs(x)
+    k = np.hanning(441); k /= k.sum()
+    env = np.convolve(env, k, mode="same")
+    noise = rng.standard_normal(len(x)).astype(np.float32) * env
+    return x * (1 - amount) + noise * amount * 2.0
+
+
+def _fog_reverb(x, taps):
+    out = x.copy()
+    for delay_s, gain in taps:
+        d = int(delay_s * _SR)
+        if d < len(x):
+            echo = np.zeros_like(x)
+            echo[d:] = x[:-d] * gain
+            out = out + echo
+    return out
+
+
+def _fog(x, intensity=_FILTER_INTENSITY, pitch=1.16):
+    y = _pitch_up(x, pitch)
+    y = _breath(y, amount=0.38 * intensity)
+    taps = [(0.06, 0.5 * intensity), (0.13, 0.32 * intensity),
+            (0.23, 0.18 * intensity)]
+    y = _fog_reverb(y, taps)
+    return (y / (np.max(np.abs(y)) + 1e-9) * 0.85).astype(np.float32)
+
+
+def speak(text: str) -> str | None:
+    """Synthesize `text` as Hollow's whisper; return base64 WAV, or None if
+    voice is unavailable or anything fails (never raises)."""
+    if _PIPELINE is None or not text or not text.strip():
+        return None
+    try:
+        audio = None
+        for _, _, chunk in _PIPELINE(text, voice=_VOICE, speed=_SPEED):
+            audio = chunk if audio is None else np.concatenate([audio, chunk])
+        audio = np.asarray(audio, dtype=np.float32)
+        audio = audio / (np.max(np.abs(audio)) + 1e-9) * 0.9
+        return base64.b64encode(_wav(_fog(audio), _SR)).decode()
+    except Exception as e:
+        print(f"[voice] speak failed: {e!r}")
+        return None
+```
+
+- [ ] **Step 4: Run, verify pass** → `.venv/Scripts/python -m pytest tests/test_voice.py -q` (3 pass; on the 3.13 venv `_PIPELINE is None`).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add voice.py tests/test_voice.py
+git commit -m "feat: voice.py — guarded Kokoro whisper with locked DSP
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task A2: Space build — deps, system packages, Python pin
+
+**Files:** Modify `requirements.txt`; Create `packages.txt`; Modify `README.md`.
+
+No unit tests (verified at deploy). This makes the Space able to import Kokoro.
+
+- [ ] **Step 1: `requirements.txt`** — append:
+
+```
+kokoro
+misaki[en]
+soundfile
+spacy
+en_core_web_sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl
+```
+
+- [ ] **Step 2: Create `packages.txt`** (HF installs these via apt):
+
+```
+espeak-ng
+```
+
+- [ ] **Step 3: `README.md` frontmatter** — add under `app_file: app.py`:
+
+```yaml
+python_version: "3.11"
+```
+
+(Kokoro needs Python <3.13; without this pin the Space may default to 3.13 and the build breaks.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add requirements.txt packages.txt README.md
+git commit -m "build: Space deps for Kokoro voice (python 3.11, espeak-ng, spacy)
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task A3: `voice_panel` plumbing — thread an 8th output everywhere (refactor)
+
+**Files:** Modify `app.py`; Modify `tests/test_app.py` (only if a test constructs output tuples).
+
+Add a hidden `voice_panel = gr.HTML()` and thread an 8th output (empty string by default) through every yield and event. Keep all 183 tests green. **No voice content yet** — this is pure plumbing so later tasks just fill the slot.
+
+- [ ] **Step 1:** In the Blocks layout, add after `treasure_panel`:
+
+```python
+        voice_panel = gr.HTML(visible=False)   # carries Hollow's voice <audio>
+```
+
+- [ ] **Step 2:** Add a module helper near `_PENDING`:
+
+```python
+def _voice_html(b64: str | None) -> str:
+    # autoplay the whisper from its own channel so the entity heartbeat HTML
+    # stays byte-identical (never remounts). Empty when silent.
+    if not b64:
+        return ""
+    return f'<audio autoplay src="data:audio/wav;base64,{b64}"></audio>'
+```
+
+- [ ] **Step 3:** Append `_voice_html(None)` (i.e. `""`) as the **last** element of every yield tuple in `chat()`, `_play_finale`, `_play_finale_bad`, `_play_finale_good`, and the return tuple of `_reset`. Every tuple goes from 7 to 8 elements, last element `""` for now.
+
+- [ ] **Step 4:** Add `voice_panel` as the **last** entry of the `outputs=[...]` list in BOTH `.then(fn=chat, ...)` chains and in `restart_btn.click(...)`.
+
+- [ ] **Step 5:** Run the full suite: `.venv/Scripts/python -m pytest -q` → **183 pass** (indices 0–6 unchanged; new index 7 is `""`).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app.py tests/test_app.py
+git commit -m "refactor: add hidden voice_panel as the 8th output channel
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task A4: Voice on the recall turn + mute toggle
+
+**Files:** Modify `app.py`; Modify `tests/test_app.py`.
+
+- [ ] **Step 1: Write failing tests** (append to `tests/test_app.py`):
+
+```python
+class TestVoice:
+    def test_recall_turn_speaks_the_reply(self, monkeypatch):
+        monkeypatch.setattr(app, "run_turn",
+                            lambda *a, **k: ("the sea. that was me.", '{"affinity_delta":1}'))
+        monkeypatch.setattr(app.time, "sleep", lambda s: None)
+        monkeypatch.setattr(app, "should_recall", lambda s: (True, "grew up near the sea"))
+        monkeypatch.setattr(app, "speak", lambda text: "FAKEB64")  # voice available
+        state = _state(affinity=60, treasure=["grew up near the sea"], claimed=[], tone=0)
+        outs = list(app.chat("hi", state, []))
+        assert "FAKEB64" in outs[-1][7]          # voice channel carries audio
+
+    def test_no_voice_when_muted(self, monkeypatch):
+        monkeypatch.setattr(app, "run_turn",
+                            lambda *a, **k: ("the sea. that was me.", '{"affinity_delta":1}'))
+        monkeypatch.setattr(app.time, "sleep", lambda s: None)
+        monkeypatch.setattr(app, "should_recall", lambda s: (True, "grew up near the sea"))
+        monkeypatch.setattr(app, "speak", lambda text: "FAKEB64")
+        state = _state(affinity=60, treasure=["grew up near the sea"], claimed=[],
+                       tone=0, voice_on=False)
+        outs = list(app.chat("hi", state, []))
+        assert outs[-1][7] == ""                 # muted -> silent
+```
+
+- [ ] **Step 2: Run, verify fail.**
+
+- [ ] **Step 3: Implement.**
+  - Import: `from voice import speak` at the top of `app.py`.
+  - Add `"voice_on": True` to `_pristine_state()` and every seeded state in `_init_state` (and the test helper `_state` default).
+  - On the recall turn in `chat()` (where `do_recall and recall_memory and not turn_failed`), compute `voice = _voice_html(speak(reply)) if state.get("voice_on", True) else ""` and yield it as the 8th element of the final recall yield. For non-recall turns the 8th element stays `""`.
+  - Mute toggle UI: add a button in the title row:
+    `voice_btn = gr.Button("🔊", elem_classes="voice-btn", scale=0)`
+    and a handler `_toggle_voice(state)` that flips `state["voice_on"]` and returns `(state, gr.update(value="🔊" if on else "🔇"))`; wire `voice_btn.click(_toggle_voice, [state], [state, voice_btn])`.
+
+- [ ] **Step 4: Run** the recall + full app suite → green.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app.py tests/test_app.py
+git commit -m "feat: voice on the recall turn + mute toggle
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task A5: Voice on every Hollow finale line
+
+**Files:** Modify `app.py`; Modify `tests/test_app.py`.
+
+- [ ] **Step 1: Write failing tests:**
+
+```python
+class TestFinaleVoice:
+    def test_good_finale_voices_hollow_lines(self, monkeypatch):
+        monkeypatch.setattr(app, "speak", lambda text: "FAKEB64")
+        outs = _drive(_state(), monkeypatch)          # _drive sets voice_on True by default
+        assert any("FAKEB64" in o[7] for o in outs)   # at least one spoken line
+
+    def test_finale_voice_respects_mute(self, monkeypatch):
+        monkeypatch.setattr(app, "speak", lambda text: "FAKEB64")
+        outs = _drive(_state(voice_on=False), monkeypatch)
+        assert all(o[7] == "" for o in outs)
+```
+
+- [ ] **Step 2: Run, verify fail.**
+
+- [ ] **Step 3: Implement.** In each of the three finale players, for every step where `speaker == "hollow"` (in `_play_finale_good` all steps are hollow; in `_play_finale`/`_play_finale_bad` check `step["speaker"]`), compute the 8th yield element:
+
+```python
+        voice = (_voice_html(speak(step["text"]))
+                 if state.get("voice_on", True) and step["speaker"] == "hollow"
+                 else "")
+```
+
+and pass `voice` as the last element of that step's `yield`. Visitor lines (`speaker == "visitor"`) and the final locked yield use `""`. The multi-second `step["pause"]` absorbs synth latency.
+
+- [ ] **Step 4: Run** the full suite → green.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app.py tests/test_app.py
+git commit -m "feat: voice every Hollow line in the three finales
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+# PART B — AWARENESS
+
+### Task B1 (B3 in spec): Notices how you write
+
+**Files:** Modify `memory.py`, `character.py`, `app.py`; Modify tests.
+
+- [ ] **Step 1: Failing test** (`tests/test_memory.py`):
+
+```python
+from memory import style_signal
+
+class TestStyleSignal:
+    def test_short_messages_read_as_guarded(self):
+        assert style_signal([3, 4, 2]) == "short"
+    def test_long_messages_read_as_pouring_out(self):
+        assert style_signal([40, 55, 60]) == "long"
+    def test_mixed_or_empty_is_neutral(self):
+        assert style_signal([]) is None
+```
+
+- [ ] **Step 2: Run, verify fail.**
+
+- [ ] **Step 3: Implement** in `memory.py`:
+
+```python
+def style_signal(msg_lengths: list[int]) -> str | None:
+    """A coarse read of how the visitor has been writing lately (word counts).
+    None when there isn't enough signal."""
+    if not msg_lengths:
+        return None
+    avg = sum(msg_lengths) / len(msg_lengths)
+    if avg <= 5:
+        return "short"
+    if avg >= 30:
+        return "long"
+    return None
+```
+
+- [ ] **Step 4:** In `character.py`, `build_system_prompt(...)` gains a `style: str | None = None` kwarg. When set, append one line, e.g.:
+
+```python
+    if style == "short":
+        parts.append("The visitor's messages have been short and guarded. You may quietly notice this — name it once, softly, then let it go.")
+    elif style == "long":
+        parts.append("The visitor has been pouring words out tonight. You may quietly notice how much they're giving you.")
+```
+
+- [ ] **Step 5:** In `app.py` `chat()`: maintain `state["msg_lengths"]` (append `len(user_msg.split())`, cap last 5) and pass `style=style_signal(state["msg_lengths"])` into `build_system_prompt(...)`. Add `"msg_lengths": []` to pristine/seeded states.
+
+- [ ] **Step 6:** Run suite → green. **Commit** `feat: B3 — Hollow notices how you write`.
+
+---
+
+### Task B2 (B2 in spec): Brings up your memories unprompted
+
+**Files:** Modify `memory.py`, `character.py`, `app.py`; Modify tests.
+
+- [ ] **Step 1: Failing test** (`tests/test_memory.py`):
+
+```python
+from memory import pick_aware_memory
+
+class TestPickAwareMemory:
+    def test_picks_an_unclaimed_memory_not_the_recall_one(self):
+        s = {"treasure": ["a", "b", "c"], "claimed": ["a"], "last_aware_memory": None}
+        m = pick_aware_memory(s, exclude="b")
+        assert m in {"c"}                      # not claimed(a), not excluded(b)
+    def test_avoids_repeating_the_last_one(self):
+        s = {"treasure": ["a", "b"], "claimed": [], "last_aware_memory": "a"}
+        assert pick_aware_memory(s, exclude=None) == "b"
+    def test_none_when_nothing_eligible(self):
+        s = {"treasure": ["a"], "claimed": ["a"], "last_aware_memory": None}
+        assert pick_aware_memory(s, exclude=None) is None
+```
+
+- [ ] **Step 2: Run, verify fail.**
+
+- [ ] **Step 3: Implement** in `memory.py`:
+
+```python
+def pick_aware_memory(state: dict, exclude: str | None) -> str | None:
+    """An earlier memory Hollow may quietly resurface this turn: unclaimed, not
+    the one being recalled, not the one it just resurfaced. None if none fit."""
+    claimed = set(state.get("claimed", []))
+    last = state.get("last_aware_memory")
+    pool = [m for m in state.get("treasure", [])
+            if m not in claimed and m != exclude and m != last]
+    return pool[-1] if pool else None        # newest eligible (deterministic)
+```
+
+- [ ] **Step 4:** `build_system_prompt` gains `aware_memory: str | None = None`; when set, append: `f"Earlier the visitor told you: \"{aware_memory}\". You may bring it up unprompted, gently, as if it's been on your mind."`
+
+- [ ] **Step 5:** In `chat()`, only on **non-recall** turns and occasionally (e.g. `state["turn"] % 3 == 0`), set `aware = pick_aware_memory(state, exclude=recall_memory)`, pass it in, and on success set `state["last_aware_memory"] = aware`. Add `"last_aware_memory": None` to states.
+
+- [ ] **Step 6:** Run suite → green. **Commit** `feat: B2 — Hollow resurfaces your memories unprompted`.
+
+---
+
+### Task B3 (B1 in spec): Speaks first on silence (`gr.Timer`)
+
+**Files:** Modify `app.py`, `character.py`; Modify tests.
+
+`gr.Timer` is validated. Idle lines are **canned** (no model call). Voice (A) speaks them too.
+
+- [ ] **Step 1: Failing tests** (`tests/test_app.py`):
+
+```python
+class TestIdle:
+    def test_idle_appends_a_canned_line_when_silent(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
+        out_state, hist, voice = app._on_idle(state, [{"role": "assistant", "content": "x"}])
+        assert hist[-1]["role"] == "assistant"
+        assert hist[-1]["content"] in app._IDLE_LINES
+
+    def test_idle_silent_when_recently_active_or_ended(self, monkeypatch):
+        import time as _t
+        # recently active -> no line
+        s1 = _state(); s1["last_activity"] = _t.time()
+        assert app._on_idle(s1, [])[1] == []
+        # ended -> no line
+        s2 = _state(ended=True); s2["last_activity"] = _t.time() - 999
+        assert app._on_idle(s2, [])[1] == []
+```
+
+- [ ] **Step 2: Run, verify fail.**
+
+- [ ] **Step 3: Implement** in `app.py`:
+
+```python
+_IDLE_LINES = [
+    "...are you still there?",
+    "the fog is getting thicker. say something.",
+    "don't go. not yet.",
+    "i can still feel you out there.",
+]
+_IDLE_AFTER = 12.0   # seconds of silence before Hollow speaks first
+
+def _on_idle(state: dict, history: list):
+    import time as _t
+    if (state.get("ended") or not history
+            or _t.time() - state.get("last_activity", _t.time()) < _IDLE_AFTER):
+        return state, history, ""
+    state = dict(state)
+    i = state.get("idle_count", 0)
+    line = _IDLE_LINES[i % len(_IDLE_LINES)]
+    state["idle_count"] = i + 1
+    state["last_activity"] = _t.time()          # wait again before the next one
+    history = history + [{"role": "assistant", "content": line}]
+    voice = _voice_html(speak(line)) if state.get("voice_on", True) else ""
+    return state, history, voice
+```
+
+- [ ] **Step 4:** Reset `state["last_activity"] = time.time()` at the top of `chat()` (on a real user turn) and add `"last_activity": 0.0` / `"idle_count": 0` to pristine/seeded states. In `_start_turn`, also stamp `last_activity`.
+
+- [ ] **Step 5:** Wire the timer in the Blocks body:
+
+```python
+    idle_timer = gr.Timer(4.0)
+    idle_timer.tick(_on_idle, [state, chatbot], [state, chatbot, voice_panel],
+                    show_progress="hidden")
+```
+
+- [ ] **Step 6:** Run the full suite → green.
+
+- [ ] **Step 7: Commit** `feat: B1 — Hollow speaks first when you go silent (gr.Timer)`.
+
+---
+
+### Task FINAL: Full verification + deploy
+
+- [ ] **Step 1:** `.venv/Scripts/python -m pytest -q` → all green.
+- [ ] **Step 2: Local sanity** (voice is silent locally on 3.13 — expected): `HOLLOW_FAST_FINALE=good .venv/Scripts/python app.py`, screenshot, confirm layout intact, mute button present, no errors. Idle line should appear after ~12s of no input.
+- [ ] **Step 3: Voice smoke test (3.12 venv):** in the `.venv-tts` env, `python -c "import voice; print(bool(voice.speak('the sea. that was me.')))"` → `True` (proves the real pipeline path end-to-end).
+- [ ] **Step 4: Deploy** both Spaces; wait ~3–4 min (the Kokoro/spacy build is heavier), Ctrl+F5. On the Space, verify: recall is spoken, finale lines are spoken, mute works, idle fires.
+
+```bash
+git push space main && git push hackathon main
+```
+
+Commit trailer for every commit: `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`.
+
+---
+
+## Self-review notes
+- If the Space build fails, it's almost certainly the Python pin or the spaCy wheel — check those first; voice is import-guarded so a *runtime* voice failure never takes down the app, but a *build* failure does.
+- Keep the entity heartbeat HTML stable — never put voice audio in the entity panel; it lives in `voice_panel`.
+- B2/B3 must stay occasional (every-N-turns / gated) so they don't flatten the voice into a tic.
+- The idle timer must reset on every user turn and never fire during a finale or after the end.

docs/superpowers/specs/2026-06-13-presence-voice-and-awareness-design.md

@@ -0,0 +1,149 @@
+# Presence: Voice + Awareness — Design Spec
+
+> Goal: make Hollow feel like a *presence*, not a text box. Two additions on top
+> of the existing Qwen3-8B game: **A) the child speaks** (whispered TTS on the
+> recall and the finales) and **B) the child is aware** (speaks first on silence,
+> brings up your memories unprompted, notices how you write).
+
+**Status:** design — voice validated end-to-end (Kokoro runs offline on CPU,
+voice cast locked). The one remaining technical unknown is `gr.Timer` for B1,
+to be validated before that task is committed.
+
+**Non-goals:** no model swap (Qwen3-8B stays — it's on-brand for the small-model
+track and the calibrated pacing depends on it). No voice on every reply (latency).
+No sponsor model bolt-ons. No new visual generation (the grayscale fog art is the
+brand).
+
+---
+
+## A — Voice (the child whispers)
+
+### What it does
+On the **recall** (Hollow retelling your memory in the first person) and on
+**Hollow's lines during the three finales**, the text is also spoken in a
+whispered, childlike, suffering voice. Hearing your own memory whispered back is
+the wow; the finales become genuinely frightening.
+
+### Locked voice recipe (validated)
+- **Model:** `hexgrad/Kokoro-82M` (Apache-2.0, 82M), `KPipeline(lang_code="a")`,
+  voice **`af_nicole`**, `speed=0.80`. Runs on **CPU** — no GPU budget consumed.
+- **Post-processing (numpy, the same approach as `sting.py`):**
+  - `pitch_up(1.16)` — raises toward a child timbre.
+  - `breath(amount = 0.38 * 0.28)` — light whispered air.
+  - `fog_reverb` taps `[(0.06, 0.5*0.28), (0.13, 0.32*0.28), (0.23, 0.18*0.28)]` —
+    a faint in-the-fog space.
+  - i.e. the "verylight" (28%) filter the user picked.
+- Output 24 kHz mono WAV → base64 → inlined `<audio autoplay>` (the exact
+  mechanism the chimes/sting already use; **no JS**).
+
+### Where it plugs in
+- **Recall turns:** in `chat()`, when `do_recall and recall_memory`, synthesize
+  the reply text and attach the audio to the rendered output (alongside the
+  existing `flash_strong` entity render).
+- **Finale lines:** each `speaker == "hollow"` step in the three finale players
+  synthesizes its line. The multi-second `pause` between steps absorbs the
+  ~1–2 s synthesis time, so pacing is unaffected.
+- **Not** on ordinary replies (keeps every turn fast; the recall is the wow).
+
+### Mute toggle
+A small control (e.g. a 🔊/🔇 button near the title) sets a `voice_on` flag in
+state. README already warns of sudden sound; default ON, one click to silence.
+
+### Failure safety
+TTS is wrapped: if Kokoro errors or is slow, the turn degrades to **silent**
+(text still shows). Voice never blocks or breaks a turn. The pipeline is loaded
+**once at import** (like the model), guarded so an import failure disables voice
+rather than crashing the app.
+
+### Space build requirements (the real risk surface — "don't break the build")
+- **Pin `python_version: "3.11"`** in README frontmatter (Kokoro requires
+  Python <3.13; HF default may be 3.13 → would break the build).
+- **`requirements.txt`** adds: `kokoro`, `misaki[en]`, `soundfile`, `spacy`, and
+  the spaCy model `en_core_web_sm` (installed via its wheel URL — discovered in
+  validation that misaki needs it).
+- **`packages.txt`** adds `espeak-ng` as a G2P fallback (validation ran without
+  it on Windows via misaki, but include it for OOV safety on the Space).
+- First run downloads the Kokoro weights (~330 MB) — happens once at Space build.
+
+---
+
+## B — Awareness (the child watches and thinks)
+
+Three behaviors, all amplifying the existing "it reads you" theme. B4 (continuity)
+folds into B2 — it falls out of the history + B2 naturally.
+
+### B2 — Brings up your memories unprompted (prompt + state, low risk)
+Mid-conversation (not only on the scripted recall), Hollow may weave in a
+fragment of an earlier `treasure` memory: *"you said you were afraid of the dark.
+i think about that."*
+- **How:** the system prompt gains an optional "you may quietly recall this
+  earlier thing the visitor told you: <memory>" line, picking a random *unclaimed,
+  not-currently-recalled* treasure memory, gated so it surfaces only sometimes
+  (e.g. a probability or an every-N-turns rule) and never the same one twice in a
+  row (track `last_aware_memory` in state).
+- **Risk:** low — prompt + one state field. Must not collide with the scripted
+  recall (skip on recall turns).
+
+### B3 — Notices how you write (prompt + state, low risk)
+Hollow comments on your *style*, making the surveillance explicit: short messages
+→ *"you're being careful with me."*; long → *"you have so much to say tonight."*;
+cold → *"you've gone quiet inside."*
+- **How:** track a light rolling signal in state (recent message lengths; the
+  existing tone). Inject a hint into the prompt: "the visitor's recent messages
+  have been {short|long|warm|cold} — you may quietly notice this." The model
+  already mimics tone; this nudges it to *name* it. Gated so it's occasional, not
+  every turn.
+- **Risk:** low — prompt + derived signal, no new deps.
+
+### B1 — Speaks first on silence (needs a small tech validation)
+If the visitor is idle for a while, Hollow says something unprompted:
+*"...are you still there? don't go."* / *"the fog is getting thicker. say something."*
+- **How:** a Gradio **`gr.Timer`** (fires every few seconds) checks: is the
+  visitor idle past a threshold (an `last_activity` timestamp in state), the game
+  not generating, not ended, not mid-finale? If so, append a **canned** in-character
+  idle line (a small rotating pool) to the chat — **no model call, no GPU**, so it's
+  deterministic, instant, and free. Idle lines may also be voiced (A) for extra
+  presence.
+- **Gating (critical):** must not fire during generation, during a finale, after
+  the game ends, or immediately after the user just spoke. Reset the idle timer on
+  every user message and finale step.
+- **Risk:** medium — this is the only piece with new wiring. **Validate `gr.Timer`
+  first** (does it work with our generator + `gr.State` in Gradio 6.x; does it
+  conflict with the `.then()` chains): a throwaway probe, exactly like we did for
+  Kokoro, before committing the task.
+
+---
+
+## State additions
+```python
+# A
+"voice_on": True,            # mute toggle
+# B
+"last_aware_memory": None,   # B2 — avoid repeating the same surfaced memory
+"msg_lengths": [],           # B3 — rolling recent message lengths (cap ~5)
+"last_activity": <ts>,       # B1 — idle detection; reset on each user turn
+```
+All read with `.get(...)` for pre-deploy sessions (existing convention).
+
+## Files touched (anticipated)
+- `voice.py` (new) — Kokoro pipeline + the locked post-processing; `speak(text)
+  -> base64 wav | None`. Guarded import; CPU only.
+- `render.py` — helper to inline a voice `<audio>` (reuse the existing pattern).
+- `engine.py` / `character.py` — B2/B3 prompt injection; no model/backend change.
+- `app.py` — wire voice into recall + finale players; mute toggle; `gr.Timer` for
+  B1; state fields.
+- `requirements.txt`, `packages.txt`, `README.md` (python pin) — Space build.
+- `memory.py` — B2/B3 small pure helpers (pick-aware-memory, style-signal) + tests.
+- `tests/` — voice (mocked/guarded), B2/B3 pure logic, idle-line selection.
+
+## Risks & validations (before/within the plan)
+1. **`gr.Timer` (B1)** — validate with a probe before committing the task.
+2. **Space build (A)** — python pin + the spaCy/misaki/espeak chain is the most
+   likely build breaker; stage it carefully and keep voice import-guarded so a
+   failure disables voice, never the app.
+3. **Latency (A)** — measure synth time; recall + finale only, pauses absorb it.
+4. **Off-grid intact** — Kokoro is a local model; the off-grid badge stays.
+
+## Out of scope (explicitly)
+Model swap; voice on every reply; sponsor models; generated backgrounds/animations;
+the shareable end-card (plan C — deferred).