osdy-pi 1.11.16 → 1.11.18

package/README.md

@@ -8,7 +8,9 @@ Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive te
 
 **Audio notifications share a bundled 180 ms default sound on macOS and Windows**, with a persistent master mute in `/osdyConfig` → **Sounds**. Custom paths take precedence: startup flag → saved global path → bundled default. Muting preserves those paths and visual alerts; explicit **Test effective** still plays while muted. See [Audio notifications](#audio-notifications).
 
-**The Control Center consolidates Osdy controls in `/osdyConfig`**: ten categories cover appearance, Git, sounds, accounts, usage, and TODO/Agents provider settings. Account quota previews query a selected stored Codex profile without switching it. The header shows the installed Osdy package version when it fits; constrained layouts show only the centered mascot. See [Control Center in Pi](#control-center-in-pi) for confirmation and persistence boundaries.
+**Local response narration is opt-in on macOS**: `/osdyConfig` → **Speech** offers a one-line selector for installed macOS voices and optional local Kokoro voices, with explicit previews without saving or enabling narration. Stop from chat with **Ctrl+Option+S** or `/osdy-pi speech stop`. Speech stays independent of notification sounds and their mute. See [Response speech](#response-speech).
+
+**The Control Center consolidates Osdy controls in `/osdyConfig`**: eleven categories cover appearance, Git, sounds, accounts, usage, TODO/Agents provider settings, and opt-in response speech. Account quota previews query a selected stored Codex profile without switching it. The header shows the installed Osdy package version when it fits; constrained layouts show only the centered mascot. See [Control Center in Pi](#control-center-in-pi) for confirmation and persistence boundaries.
 
 **Codex banked resets show counts and per-reset local expiry** in `/usage` and the Control Center. Press **u** in `/usage` or select **Usage → Use or check banked reset** for Cancel-first, active-account use or pending-attempt checks; stored-profile previews stay read-only. See [Use or check a banked reset](#use-or-check-a-banked-reset).
 
@@ -16,7 +18,8 @@ Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive te
 
 | Area | What ships |
 | --- | --- |
-| Control Center | **Ctrl+Option+O** or `/osdyConfig` opens ten categories, including confirmed TODO/Agents provider selection and explicit per-profile Codex quota previews. |
+| Control Center | **Ctrl+Option+O** or `/osdyConfig` opens eleven categories, including confirmed TODO/Agents provider selection, explicit per-profile Codex quota previews, and Speech. |
+| Speech | Default-off local macOS narration, optional Spanish Kokoro voices, one saved voice, explicit draft previews, and chat-accessible Stop. |
 | Audio | Shared bundled default, per-event custom paths, and persistent automatic-audio mute; [explicit tests remain available](#audio-notifications). |
 | Local analytics (1.10.0) | `/osdy-usage` opens Summary, Profiles, Models, and History pages for recorded tokens and estimated cost—not billing or subscription quota. |
 | Themes introduced in 1.11.0 | Spider-Man Classic, Miles Morales, and Spider-Verse add three distinct dark palettes. |
@@ -62,14 +65,15 @@ Osdy Pi's own extension and themes are bundled—do not install them separately.
 
 ### Control Center in Pi
 
-Press **Ctrl+Option+O** or run **`/osdyConfig`** in interactive Pi to open the Osdy Control Center. The ten categories—**Theme, Header, Mascot, Editor, Git, Sounds, Account, Usage, TODO, and Agents**—provide inline controls or data in the same modal. Existing commands remain available.
+Press **Ctrl+Option+O** or run **`/osdyConfig`** in interactive Pi to open the Osdy Control Center. The eleven categories—**Theme, Header, Mascot, Editor, Git, Sounds, Account, Usage, TODO, Agents, and Speech**—provide inline controls or data in the same modal. Existing commands remain available.
 
-| Shortcut | Panel | Command fallback |
+| Shortcut | Action | Command fallback |
 | --- | --- | --- |
 | **Ctrl+Option+O** | Osdy Control Center | `/osdyConfig` |
 | **Ctrl+Option+U** | Active Codex subscription quota—not local token/cost analytics | `/usage` |
+| **Ctrl+Option+S** | Stop speech from chat | `/osdy-pi speech stop` |
 
-On macOS, **Option = Alt** in Pi's shortcut names: these bindings register as `ctrl+alt+o` and `ctrl+alt+u`. On other platforms, use **Ctrl+Alt+O** and **Ctrl+Alt+U**. Your terminal must send Option as **Alt/Meta** and support **Ctrl+Alt chords**; registration does not guarantee actual hardware delivery. Check **`/hotkeys`** for bindings, and use **`/osdyConfig`** or **`/usage`** if the terminal, OS, or another extension intercepts or cannot deliver the chord.
+On macOS, **Option = Alt** in Pi's shortcut names: these bindings register as `ctrl+alt+o`, `ctrl+alt+u`, and `ctrl+alt+s`. On other platforms, use **Ctrl+Alt+O**, **Ctrl+Alt+U**, and **Ctrl+Alt+S**. Your terminal must send Option as **Alt/Meta** and support **Ctrl+Alt chords**; registration does not guarantee actual hardware delivery. Check **`/hotkeys`** for bindings, and use the command fallback if the terminal, OS, or another extension intercepts or cannot deliver the chord.
 
 **Ctrl+Option+O capability limits:** Account **Switch**, **Set default**, and **Clear default** refuse changes while Pi is busy; retry when idle. The same actions through `/osdyConfig` retain idle waiting, as does switching through `/osdy-account`. Read-only account quota previews remain available while busy. Successful TODO/Agents selection from Ctrl+Option+O saves settings, closes/disposes the panel, releases its editor hold, then asks you to run **`/reload` manually** (or restart Pi). From `/osdyConfig`, the same sequence still reloads automatically once; restart Pi if reload fails.
 
@@ -89,6 +93,7 @@ Positive counts also trigger a best-effort read-only reset-details GET within th
 - **Git** shows the current branch (or detached HEAD), changed-entry count/clean status, and the current widget position as a read-only session detail. Working-tree enablement applies and saves through the same owner as `/osdy-pi working-tree`; Git inspection never writes Git. `/osdy-pi diff` and position commands are unchanged.
 - **Sounds** shows each event's saved and effective path/source. Configure opens a single-line path editor **inside this overlay**: enter a readable `.mp3`/`.wav` path, then **Enter** to validate and save immediately, or **Esc** to cancel editing. Relative paths resolve against the project directory and save as absolute paths. Clear removes only that event's saved path from the existing v1 audio store (`<agent-dir>/extensions/osdy-pi/audio-notifications.json`). Notifications read this store afresh; refresh failures are reported separately from save failures.
 - **Sounds → Mute automatic audio / Enable automatic audio** is a persistent master switch, enabled by default (including existing v1 files). Muting suppresses all automatic event sounds, even startup-flag paths, without losing saved paths or changing visual notifications. It applies to the next notification without reload; already-started playback is not stopped. **Test effective** still plays while muted; opening categories and configuring paths never play. Startup `--osdy-pi-sound-<event>` flags override saved paths, so **clearing a saved path does not disable flag-configured playback**. Tests report unavailable files/platforms or playback failures; playback remains macOS/Windows only. Configure, Clear, and the legacy `/osdy-pi sound setup` wizard preserve the master state.
+- **Speech** shows enabled state, saved voice, and rate, with **Enable/Disable**, **Read last response**, **Stop**, one horizontal **Voice** selector, and explicit **Preview voice**. On the Voice row, **←/→** browses a draft and **Enter** saves; **Tab** returns to categories. Preview plays a fixed sample of the draft without saving or enabling narration. Speech is independent of Sounds mute. See [Response speech](#response-speech).
 - **Account** shows one row per validated profile, marked **Active** and **Default** where applicable. Select a profile, then use its visible context bar: **v View usage**, **s Switch** (inactive profiles), **d Set default**, and **c Clear default** (when a default exists). **v** or **Enter** explicitly queries that profile's stored Codex credentials without activating it; no second action list appears. Opening, navigating or highlighting never queries; stored profiles are never polled. A dedicated quota view reuses `/usage` dashboard content: Session/Weekly cards, additional bucket groups, remaining-capacity bars, resets, and the quotas/account summary with plan and credits when available. Identity belongs to the selected stored profile; unknown provider/model metadata is labeled honestly. Checked and updated times use local time; absent data is unknown, not zero. Refresh/Back controls and query feedback stay pinned while long dashboard content scrolls. **r Refresh** repeats the selected profile query; **s Switch**, when available, confirms activation of the currently viewed inactive profile. Cancelling that confirmation preserves the quota view and scroll position. **b Back** or **Esc** returns to the overview with the profile selected, without closing the overlay. In quota details, **↑/↓** selects Refresh/Back and **Enter** activates it; **Page Up/Down** and **Home/End** scroll long quota data. Switch, set default, and clear default require an **in-screen confirmation** with Cancel selected initially; **Esc** cancels confirmation without closing the overlay. Single blank separators group the confirmation title, complete effects, choices, and instructions; gaps yield on short viewports. Resize if the full confirmation cannot fit—acceptance stays hidden and blocked. Switching through `/osdyConfig` waits for Pi to become idle; Ctrl+Option+O refuses busy account changes. Successful switching activates through the existing backend and refreshes subscription usage. Login remains Pi-owned (`/login`); create/rename/remove remain available in `/osdy-account`. Category navigation never changes profiles or credentials.
 - **Usage** shows the runtime's cached active Codex subscription quota (remaining-capacity bars and percentages, window, reset/fetch times) and the existing local history owner's recorded token/cache totals, cost gaps, and model detail. Select **Range: day/week/month** for the current local calendar period; toggle **Accounts: all/current** for local analytics (unmanaged when no valid current profile exists). Quota always belongs to the active account, not the analytics filter; local token/cost totals never become quota percentages. Select **Refresh quota and local history** explicitly; rendering and filters never fetch. Empty, loading, unavailable, and limited/incomplete coverage are reported honestly. Estimates are not billing or subscription quota. `/usage` remains the subscription dashboard; `/osdy-usage` remains local analytics.
 - **Esc** closes without undoing live or saved changes, except when cancelling a confirmation/input or returning from Account quota details. Account read-only queries are cancelled on Back/Esc, category exit or close; late results are ignored even if cancellation is not honored. Other in-flight operations still finish and are not claimed cancelled. Late results cannot replace a closed overlay or another category. On narrow terminals, categories and details share the viewport; use Tab to switch.
@@ -438,6 +443,8 @@ The enabled state, editor mode, working-tree visibility preference, header, and
 | Working tree | `/osdy-pi working-tree on\|off\|toggle\|status` |
 | Working tree | `/osdy-pi working-tree position top\|bottom\|status` |
 | Audio | `/osdy-pi sound setup` |
+| Response speech | `/osdy-pi speech on\|off\|status\|stop\|last` |
+| Response speech Stop | **Ctrl+Option+S** or `/osdy-pi speech stop` |
 | Diff | `/osdy-pi diff` |
 | Package | `/osdy-pi uninstall` |
 | Codex subscription | **Ctrl+Option+U** or `/usage` |
@@ -567,6 +574,52 @@ Use `working-tree position top` or `bottom` to place the summary above or below
 | Go back | `esc`, `backspace`, `left`, or `h` |
 | Close | `q` or `ctrl+c` |
 
+## Response speech
+
+**Off by default.** Interactive Pi can read the settled final assistant response locally on macOS using the feminine **Paulina** voice (Spanish, Mexico), initially at **180 words/minute**. No cloud speech service is used. For npm installs, confirm the resolved release includes Speech; merging source alone does not prove publication.
+
+| Command | Action |
+| --- | --- |
+| `/osdy-pi speech on` | Save automatic narration enabled. |
+| `/osdy-pi speech off` | Save automatic narration disabled and stop pending/active narration. |
+| `/osdy-pi speech status` | Show enabled state, voice, rate, and platform availability. |
+| `/osdy-pi speech last` | Read the current session's last successful final prose, even while automatic narration is off; refuses while Pi is busy. |
+| `/osdy-pi speech stop` | Cancel pending starts and active narration without changing the enabled preference. |
+
+From chat, press **Ctrl+Option+S** on macOS (**Ctrl+Alt+S** elsewhere) for the same Stop action, including preview playback. It works while Pi is busy without aborting the agent, editing your input, or changing the saved enabled/voice/rate settings. Explicit Stop suppresses automatic speech for the rest of the current run, not later runs. Run `/reload` or restart Pi after updating Osdy; check `/hotkeys` and use `/osdy-pi speech stop` if your terminal cannot deliver the chord.
+
+Open **`/osdyConfig` → Speech** (the last category) to enable/disable narration, read the last response, stop playback, or select a voice:
+
+1. Use **↑/↓** to reach the single **Voice: ‹ … ›** row. **←/→** browses installed macOS voices and **Kokoro Dora / Kokoro Alex / Kokoro Santa**, wrapping at both ends. The row marks the draft **saved** or **unsaved**; the summary always identifies the saved voice. Browsing never saves or plays audio.
+2. Select **Preview voice** and press **Enter** to hear a fixed Spanish sample for Kokoro or the existing fixed English sample for native voices, independent of the last response. Preview does **not** save the draft or enable narration, and works while narration is disabled. It may replace current playback. Leaving Speech or closing the panel cancels only its preview, not unrelated narration.
+3. Return to **Voice** and press **Enter** to save the draft for subsequent narration. Preview, other controls, and failed saves preserve the draft. **Read last response** uses the saved voice, not an unsaved draft. Saving never plays audio, enables narration, or changes already-playing audio.
+
+Opening Speech starts at the playback controls; **Home** returns there, **Tab** returns to categories, and arrows outside the Voice row retain normal pane focus behavior. The feminine Paulina voice remains the default until you save another voice.
+
+The panel shows enabled/saved-voice/rate state. Native speech uses supported voices already installed on the Pi host and needs no server or model download. Optional **Kokoro** needs a separately started local MLX-Audio server and an explicitly downloaded model; listing or saving a voice does not download anything. See [local Kokoro setup](docs/kokoro.md) for prerequisites and validation status. The extension never installs dependencies or starts the server automatically. Empty/unavailable voice lists leave narration controls accessible. Rate tuning is not exposed; the existing wpm display maps to Kokoro speed as **rate / 180**, not a guarantee of identical spoken wpm. Selection saves globally in the independent `<agent-dir>/extensions/osdy-pi/speech.json` store and survives reload/restart; **Sounds mute and event notifications are unchanged and independent**.
+
+### Optional Kokoro voices
+
+On Apple Silicon Macs, the same selector includes three local Spanish voices:
+
+| Voice | Preset |
+| --- | --- |
+| **Kokoro Dora** | Feminine, `ef_dora` |
+| **Kokoro Alex** | Masculine, `em_alex` |
+| **Kokoro Santa** | Masculine, `em_santa` |
+
+Follow [the Kokoro setup and startup guide](docs/kokoro.md) to prepare the isolated Python environment, explicitly download the free model, and start MLX-Audio on **`http://127.0.0.1:8000`**. Keep that service running while using Kokoro: the extension does **not** start it automatically. A preview reporting **`Kokoro synthesis failed`** can mean the server is stopped; check the service and the optional `OSDY_PI_KOKORO_URL` loopback origin before reinstalling anything. Native voices do not need this service.
+
+After starting it, browse to a Kokoro voice and use **Preview voice** to listen without changing your saved voice or enabling narration. Save only when you want subsequent narration to use that voice. Generation is local, but the complete WAV is produced before playback; this is not streamed narration. Initial model loading is slower than warm requests.
+
+**Known limit:** long Spanish responses may be truncated by the current upstream phonemizer. Osdy normalizes newlines, so adding line breaks is not a workaround in this integration. Prefer an installed native voice for long responses until chunking/completeness is evaluated. The [guide](docs/kokoro.md#observed-local-synthesis) records tested versions and short-sample measurements; these are not quality or latency guarantees.
+
+### Narration lifecycle and compatibility
+
+Automatic narration waits for final settlement, including retries, compaction, and queued continuations—not every message or intermediate agent end. Only successful final text is read, omitting fenced code, tools, thinking, and Markdown noise. Cancelled, failed, empty, and tool-only newest responses never fall back to older text automatically. Explicit replay retains the last successful response only in memory for this session; switching sessions, reload, and shutdown clear it. New input/runs stop narration, and queued follow-ups remain eligible once their final response settles. Explicit **Stop** also cancels pending starts and suppresses automatic narration for the rest of that run; explicit replay remains available when idle. Cancelling post-run compaction discards that run's pending response. Speech launch never waits for the full spoken playback in an agent lifecycle handler.
+
+Speech is **TUI only**: child RPC, JSON, and print runs never play it. Unsupported platforms or an unavailable selected voice report failure for explicit playback; no substitute voice is silently used. Automatic failures stay silent rather than interrupting the agent. Audio plays on the **Pi host**: over SSH, that means the remote host's audio output, not your local terminal speakers.
+
 ## Audio notifications
 
 Osdy Pi plays one shared, short, subtle original bundled WAV by default for every unconfigured audio event on macOS and Windows. Automatic audio is enabled by default; mute it in **Sounds** to turn it off without changing visual alerts. Custom readable `.mp3` or `.wav` files can replace the default per event. Other platforms safely skip playback. macOS playback requires the system `afplay` command; Windows playback requires `powershell.exe` and the Windows Media Player COM component (`WMPlayer.OCX`).
@@ -650,10 +703,11 @@ This launches `pi` from `PATH`, loads this checkout with `-e`, and uses `.pi-dev
 The explicit argument bypasses the launcher's default-account activation; Pi's `--no-session` disables session persistence, **not settings writes or provider access**.
 An isolated agent directory does **not** make custom audio paths or real provider accounts harmless. Use intentional disposable test profiles/files for profile writes, switches, default confirmations, and audio tests; do not assume an isolated account store makes real credentials safe.
 
-- Check `/hotkeys` lists `ctrl+alt+o` and `ctrl+alt+u`. On macOS, configure Option to send Alt/Meta and verify the terminal supports Ctrl+Alt chords; actual Ctrl+Option delivery still needs a hardware check. Open both **Ctrl+Option+O** and `/osdyConfig` in regular and fullscreen Pi (Ctrl+Alt+O on other platforms); use the slash command if the chord is intercepted or unsupported. Check arrows/Home/End/Page Up/Down, Tab or left/right, Enter, and Esc; shrink and restore the terminal, checking both panes remain reachable. With disposable TODO/Agents settings, verify Ctrl+Option+O asks for manual `/reload` only after closing, while `/osdyConfig` reloads automatically.
+- Check `/hotkeys` lists `ctrl+alt+o`, `ctrl+alt+u`, and `ctrl+alt+s`. On macOS, configure Option to send Alt/Meta and verify the terminal supports Ctrl+Alt chords; actual Ctrl+Option delivery still needs a hardware check. Open both **Ctrl+Option+O** and `/osdyConfig` in regular and fullscreen Pi (Ctrl+Alt+O on other platforms); use the slash command if the chord is intercepted or unsupported. Check arrows/Home/End/Page Up/Down, Tab or left/right, Enter, and Esc; shrink and restore the terminal, checking both panes remain reachable. With disposable TODO/Agents settings, verify Ctrl+Option+O asks for manual `/reload` only after closing, while `/osdyConfig` reloads automatically.
 - In disposable settings, change a visual preference, wait for **Saved globally**, close and reopen, then reload/restart to check persistence. Esc does not undo changes; distinguish save/application errors from success.
 - Account (manual): with disposable profiles only, check Cancel-first switch/set-default/clear-default confirmations, Esc cancellation, idle switching, and current/default labels. Verify Ctrl+Option+O refuses all three changes while busy, succeeds when idle, and `/osdyConfig` still waits for idle. Check one row per profile with **v/s/d/c** context actions and **Enter** usage fallback, without a second action list. From **v** quota details, check eligible **s Switch** opens the same Cancel-first confirmation, with blank separators between the title/effects, choices, and instructions; Cancel/Esc must retain the quota view and scroll position. Check gaps yield on short viewports without hiding safety content or enabling acceptance when the full confirmation cannot fit. Check remaining-capacity bars, **r Refresh**, **b Back/Esc** returning to the selected profile, long-view scrolling, no query on navigation, no stored-profile polling, and cancellation on exit. Create/rename/remove stay in `/osdy-account`, login in `/login`.
 - Subscription quota (manual): compare **Ctrl+Option+U** and `/usage` (Ctrl+Alt+U on other platforms), including **r Refresh** and Esc/q closing. Verify actual terminal chord delivery; use `/usage` if intercepted or unsupported.
+- Speech Stop (manual): during intentional narration or a voice preview, press **Ctrl+Option+S** in chat; confirm audio stops without aborting the agent or changing editor text/settings. Check actual terminal delivery, with `/osdy-pi speech stop` as fallback. Registration and automated callback tests do not establish a hardware pass.
 - Usage (manual): check day/week/month and all/current filters, empty/unavailable/limited states, and explicit refresh. Authenticated quota and post-switch account correctness need an intentionally authorized live provider check; local estimates are not billing.
 - Sounds (manual): use disposable readable `.mp3`/`.wav` files to check configure, cancel, clear, and startup-flag precedence. Only choose **Test effective** when playback is intended. The user reported successful live playback of the bundled default; exhaustive macOS/Windows coverage still needs a live check.
 

package/docs/kokoro.md

@@ -0,0 +1,91 @@
+# Optional local Spanish speech with Kokoro
+
+Kokoro adds **Kokoro Dora**, **Kokoro Alex**, and **Kokoro Santa** to the existing Speech selector. Native macOS speech remains the default: **Paulina**, narration **off**, **180 wpm**. Native voices never need a server. Kokoro uses a free local model, not cloud speech or voice cloning; initial playback support is macOS only.
+
+## Quick path
+
+1. On an Apple Silicon Mac, explicitly prepare the isolated Python environment below and start the local MLX-Audio service in a separate terminal.
+2. In Pi, open **`/osdyConfig` → Speech → Voice**, browse with **←/→**, then choose **Preview voice**. Kokoro previews use a fixed Spanish sample; native voices retain their fixed English sample. Preview uses the unsaved draft without saving it or enabling narration.
+3. Return to **Voice** and press **Enter** to save the draft. **Read last response** uses the saved voice even while narration is disabled. Enable automatic narration only if wanted.
+4. Use **Stop**, **Ctrl+Option+S** from chat, or **`/osdy-pi speech stop`** to cancel pending synthesis or playback. If the terminal cannot deliver the shortcut, use the command. Leaving Speech or closing its panel stops only its preview, not unrelated narration.
+
+## Explicit environment setup
+
+Prerequisites: an **Apple Silicon Mac** and **uv**. The example explicitly downloads a managed Python 3.11 interpreter inside the project rather than installing Python packages globally. No npm runtime dependency is added.
+
+The isolated environment was prepared successfully on an **M3 Pro / 18 GiB RAM** with **Python 3.11.15**, **MLX-Audio 0.5.9**, **Misaki 0.9.4**, and **espeakng-loader 0.2.4**. A Spanish `EspeakG2P(language="es")` probe returned phonemes successfully. `espeakng-loader` supplies the native library used by Misaki in this setup; no separate global Homebrew install was needed. All three Spanish voices also produced valid 24 kHz mono WAV through the local HTTP server. Audible playback and subjective listening quality were not evaluated.
+
+Run from the project root. These environment variables must also be set in every terminal that runs setup, model download, or the server:
+
+```bash
+export KOKORO_HOME="$PWD/.pi-dev/kokoro"
+export UV_CACHE_DIR="$KOKORO_HOME/cache/uv"
+export UV_PYTHON_INSTALL_DIR="$KOKORO_HOME/python"
+export HF_HOME="$KOKORO_HOME/cache/huggingface"
+export HF_HUB_CACHE="$HF_HOME/hub"
+export HUGGINGFACE_HUB_CACHE="$HF_HUB_CACHE"
+export XDG_CACHE_HOME="$KOKORO_HOME/cache/xdg"
+export PIP_CACHE_DIR="$KOKORO_HOME/cache/pip"
+export TORCH_HOME="$KOKORO_HOME/cache/torch"
+export NUMBA_CACHE_DIR="$KOKORO_HOME/cache/numba"
+export MPLCONFIGDIR="$KOKORO_HOME/cache/matplotlib"
+export PYTHONPYCACHEPREFIX="$KOKORO_HOME/cache/pycache"
+export HF_HUB_DISABLE_TELEMETRY=1
+mkdir -p "$KOKORO_HOME"
+uv --no-config venv --managed-python --python 3.11 "$KOKORO_HOME/venv"
+uv --no-config pip install --python "$KOKORO_HOME/venv/bin/python" \
+  'mlx-audio[server,tts]==0.5.9' 'misaki[en]==0.9.4' \
+  'espeakng-loader==0.2.4' soundfile
+# Explicitly download before playback: a first download can exceed the request timeout.
+"$KOKORO_HOME/venv/bin/python" -c \
+  'from huggingface_hub import snapshot_download; snapshot_download("mlx-community/Kokoro-82M-bf16")'
+```
+
+The managed interpreter, virtualenv, package caches, and model cache are explicitly project-contained. If you prefer an existing Python 3.10+ interpreter, omit `--managed-python` and supply its path to `--python`. Do not silently fall back to a global package environment. Keep any additional dependency caches project-local too.
+
+### Start the server separately
+
+With the same environment variables, start the server. These bind flags were exercised successfully with MLX-Audio 0.5.9; inspect `--help` when changing versions:
+
+```bash
+"$KOKORO_HOME/venv/bin/python" -m mlx_audio.server --help
+"$KOKORO_HOME/venv/bin/python" -m mlx_audio.server --host 127.0.0.1 --port 8000
+```
+
+Bind only to **127.0.0.1:8000**, never `0.0.0.0` or a LAN address. Leave the process running to keep the model warm. Model files are downloaded only during explicit model setup or the first explicit Kokoro request, not by catalog browsing, selection, or native speech. The extension never installs Python packages, downloads models on startup, or launches the server automatically. Dependency/model setup can require internet access; synthesis sends response text only to the local service. Use a trusted local service that does not forward or log sensitive text.
+
+## Integration contract
+
+| Setting | Fixed behavior |
+| --- | --- |
+| Default origin | `http://127.0.0.1:8000` |
+| Optional override | `OSDY_PI_KOKORO_URL`, set in Pi's launch environment |
+| Allowed origins | HTTP with literal `127.0.0.1` or `[::1]` only; optional port, no path beyond `/`, credentials, query, or fragment. Hostnames including `localhost` are not accepted. Redirects are never followed. |
+| Model | `mlx-community/Kokoro-82M-bf16` |
+| Voices | `Kokoro Dora` → `ef_dora`; `Kokoro Alex` → `em_alex`; `Kokoro Santa` → `em_santa` |
+| Language / format | Spanish `lang_code: "e"`; complete WAV generated before playback |
+| Rate | Existing wpm setting mapped to bounded Kokoro `speed = rate / 180`; 180 maps to 1.0, not a measured words-per-minute promise |
+| Settings | Existing v1 voice-name setting; no new engine selector, command grammar, or migration |
+
+This is **not audio streaming**. Automatic speech waits for the successful settled final assistant response; it does not speak unfinished responses, thinking, tools, or fenced code. The first cold request may include model download/loading and be much slower than warm synthesis. Long responses also wait for the full WAV before playback; no latency or quality target is established here.
+
+## Failures and verification
+
+An unavailable server, missing Spanish dependency, rejected origin, synthesis failure, or playback failure is an error—not permission to silently substitute a native voice. Explicit playback reports failure; automatic speech failures do not interrupt the agent. Choose an installed native voice explicitly if you want to continue without Kokoro. Speech remains independent of Sounds mute.
+
+### Observed local synthesis
+
+An isolated MLX-Audio 0.5.9 server on an M3 Pro / 18 GiB generated the same short Spanish sample through `/v1/audio/speech` with the fixed model/language/WAV contract:
+
+| Request | Complete WAV generation | Audio duration |
+| --- | --- | --- |
+| Dora, first inference after download | 5.664 s | 4.350 s |
+| Dora, same sample with warm model | 0.268 s | 4.350 s |
+| Alex | 1.176 s | 4.325 s |
+| Santa | 1.123 s | 4.325 s |
+
+The one-time model download took about 291 seconds. These are short-sample measurements, not general latency guarantees or time-to-first-stream benchmarks. Generated WAVs were validated without playing sound; no subjective naturalness or accent ranking is established. Automated tests and independent public-interface probes passed for request cancellation, native independence, selector drafts and settings preservation. The independent check also exercised a real filesystem and a harmless child process: private directory/file modes were 0700/0600, Stop terminated the process, and WAV cleanup waited for child close. No audible player was invoked.
+
+**Long Spanish responses are not yet validated.** MLX-Audio's Spanish phonemizer warns: `Chunking logic not yet implemented, so long texts may be truncated unless you split them with '\n'.` Osdy currently normalizes newlines before synthesis, so adding newlines to a response is not an app-level workaround. Prefer a native voice for long responses until Kokoro chunking/completeness is evaluated. Listening quality, audible-device playback, physical shortcut delivery, clean-machine installation and installed-package execution remain unverified.
+
+Primary references: [MLX-Audio server and TTS guidance](https://github.com/Blaizzy/mlx-audio) and [Kokoro-82M model/language documentation](https://huggingface.co/hexgrad/Kokoro-82M).

package/extensions/osdy-pi/control-center-speech.test.ts

@@ -0,0 +1,280 @@
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { registerHooks } from "node:module";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SpeechSettings } from "./speech-types.js";
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+registerHooks({ resolve(specifier, context, nextResolve) {
+	if (specifier.startsWith(".") && specifier.endsWith(".js") && context.parentURL?.endsWith(".ts")) {
+		const url = new URL(`${specifier.slice(0, -3)}.ts`, context.parentURL);
+		if (existsSync(fileURLToPath(url))) return { shortCircuit: true, url: url.href };
+	}
+	return nextResolve(specifier, context);
+} });
+const { CONTROL_CENTER_CATEGORIES, ControlCenter } = await import("./control-center.js");
+const { createControlCenterSpeech } = await import("./control-center-speech.js");
+
+void test("Speech appends after all existing categories without changing their indices", () => {
+	assert.deepEqual([...CONTROL_CENTER_CATEGORIES], ["Theme", "Header", "Mascot", "Editor", "Git", "Sounds", "Account", "Usage", "TODO", "Agents", "Speech"]);
+});
+
+void test("Speech displays enabled/voice/rate and routes only Enable/Disable, Read last response and Stop", async () => {
+	let settings: SpeechSettings = { version: 1, enabled: false, voice: "Paulina", rate: 180 };
+	const actions: string[] = [];
+	const speech = createControlCenterSpeech({ settings: () => Promise.resolve(settings),
+		voices: () => Promise.resolve([]),
+		selectVoice: () => Promise.resolve({ failed: false, message: "Voice saved" }),
+		previewVoice: () => Promise.resolve({ failed: false, message: "Preview started" }), stopPreview: () => {},
+		command: args => {
+			actions.push(args.join(" "));
+			if (args[0] === "on" || args[0] === "off") settings = { ...settings, enabled: args[0] === "on" };
+			return Promise.resolve({ failed: args[0] === "last", message: args[0] === "last" ? "No successful final response" : "Speech applied" });
+		} }, {} as ExtensionContext);
+	const initial = await speech.read();
+	assert.match(initial.summary, /disabled.*Paulina.*180 wpm/);
+	assert.deepEqual(initial.rows.map(row => row.label), ["Enable", "Read last response", "Stop"]);
+	const panel = new ControlCenter({ speech,
+		theme: () => ({ name: "dark", appearance: "dark", fg: (_color, text) => text }),
+		readThemes: () => [], applyTheme: () => ({ success: true }), requestRender: () => {}, height: () => 30, close: () => {},
+	});
+	panel.handleInput("\x1b[F"); await settle();
+	assert.deepEqual(actions, [], "opening and rendering never play");
+	assert.match(panel.render(120).join("\n"), /Paulina.*180/);
+	panel.handleInput("\x1b[C"); panel.handleInput("\r"); await settle();
+	assert.deepEqual(actions, ["on"]); assert.match(panel.render(120).join("\n"), /Disable/);
+	panel.handleInput("\r"); await settle(); assert.deepEqual(actions, ["on", "off"]);
+	panel.handleInput("\x1b[B"); panel.handleInput("\r"); await settle();
+	assert.match(panel.render(120).join("\n"), /No successful final response/);
+	panel.handleInput("\x1b[B"); panel.handleInput("\r"); await settle();
+	assert.deepEqual(actions, ["on", "off", "last", "stop"]);
+	panel.dispose();
+});
+void test("Speech explains native and optional Kokoro previews without adding controls", async () => {
+ const previews: string[] = [];
+ const speech = createControlCenterSpeech({
+  settings: () => Promise.resolve({ version: 1, enabled: false, voice: "Paulina", rate: 180 }),
+  voices: () => Promise.resolve(["Paulina", "Kokoro Dora"]),
+  selectVoice: () => { throw new Error("must not save while browsing or previewing"); },
+  previewVoice: voice => { previews.push(voice); return Promise.resolve({ failed: false, message: "Preview started" }); },
+  stopPreview: () => {}, command: () => { throw new Error("must not enable narration"); },
+ }, {} as ExtensionContext);
+ const initial = await speech.read();
+ assert.match(initial.note, /installed macOS voices/);
+ assert.match(initial.note, /optional Kokoro.*local server/i);
+ assert.equal(initial.rows.length, 5);
+ const draft = speech.moveVoice(1)!;
+ assert.match(draft.summary, /disabled.*Paulina.*180 wpm/);
+ assert.deepEqual(draft.rows[3]?.action, { kind: "speech-voice", voice: "Kokoro Dora" });
+ assert.deepEqual(draft.rows[4]?.action, { kind: "speech-preview", voice: "Kokoro Dora" });
+ assert.match(draft.rows[4]?.details?.join(" ") ?? "", /Spanish.*Kokoro.*English.*native/);
+ await speech.apply({ kind: "speech-preview", voice: "Kokoro Dora" });
+ assert.deepEqual(previews, ["Kokoro Dora"]);
+ assert.match((await speech.read()).rows[3]!.label, /Kokoro Dora.*unsaved/);
+});
+void test("Stale Control Center speech actions cannot launch in a replaced session", async () => {
+	let calls = 0;
+	const speech = createControlCenterSpeech({
+		settings: () => Promise.resolve({ version: 1, enabled: false, voice: "Paulina", rate: 180 }),
+		voices: () => Promise.resolve([]),
+		previewVoice: () => { calls++; return Promise.resolve({ failed: false, message: "Preview started" }); }, stopPreview: () => {},
+		selectVoice: () => { calls++; return Promise.resolve({ failed: false, message: "saved" }); },
+		command: () => { calls++; return Promise.resolve({ failed: false, message: "started" }); },
+	}, {} as ExtensionContext, () => false);
+	for (const action of [{ kind: "speech-last" }, { kind: "speech-preview", voice: "Paulina" }, { kind: "speech-voice", voice: "Paulina" }] as const) {
+		const result = await speech.apply(action);
+		assert.equal(result.failed, true); assert.match(result.message, /session changed/);
+	}
+	assert.equal(calls, 0);
+});
+void test("One horizontal Voice selector wraps silently and Enter alone saves among many voices", async () => {
+	let settings: SpeechSettings = { version: 1, enabled: true, voice: "Voice 050", rate: 180 };
+	const names = Array.from({ length: 120 }, (_, i) => `Voice ${String(i).padStart(3, "0")}`);
+	const selected: string[] = [];
+	const playback: string[] = [];
+	const speech = createControlCenterSpeech({
+		settings: () => Promise.resolve(settings), voices: () => Promise.resolve(names),
+		previewVoice: voice => { playback.push(voice); return Promise.resolve({ failed: false, message: "Preview started" }); }, stopPreview: () => {},
+		selectVoice: (voice: string) => {
+			selected.push(voice); settings = { ...settings, voice };
+			return Promise.resolve({ failed: false, message: `Voice saved globally: ${voice}` });
+		},
+		command: args => { playback.push(args.join(" ")); return Promise.resolve({ failed: false, message: "Speech applied" }); },
+	}, {} as ExtensionContext);
+	const view = await speech.read();
+	assert.equal(view.rows.length, 5);
+	assert.match(view.rows[3]!.label, /Voice: ‹ Voice 050 ›/);
+	const panel = new ControlCenter({ speech,
+		theme: () => ({ name: "dark", appearance: "dark", fg: (_color, text) => text }),
+		readThemes: () => [], applyTheme: () => ({ success: true }), requestRender: () => {}, height: () => 18, close: () => {},
+	});
+	panel.handleInput("\x1b[F"); await settle(); panel.handleInput("\x1b[C");
+	assert.match(panel.render(100).join("\n"), /> Disable/);
+	for (let i = 0; i < 3; i++) panel.handleInput("\x1b[B");
+	for (let i = 0; i < 70; i++) panel.handleInput("\x1b[C");
+	assert.match(panel.render(100).join("\n"), /> Voice: ‹ Voice 000 ›.*unsaved/);
+	panel.handleInput("\x1b[D");
+	assert.match(panel.render(100).join("\n"), /> Voice: ‹ Voice 119 ›.*unsaved/);
+	assert.deepEqual(selected, []); assert.deepEqual(playback, []);
+	panel.handleInput("\r"); await settle();
+	assert.deepEqual(selected, ["Voice 119"]); assert.deepEqual(playback, []);
+	assert.match(panel.render(100).join("\n"), /Voice saved globally: Voice 119/);
+	assert.match((await speech.read()).rows[3]!.label, /Voice: ‹ Voice 119 ›.*saved/);
+	panel.handleInput("\x1b[H"); panel.handleInput("\x1b[B"); panel.handleInput("\r"); await settle();
+	assert.deepEqual(playback, ["last"]);
+	panel.dispose();
+});
+
+void test("Default voice aliases mark one installed entry; failed discovery keeps narration controls", async () => {
+	const owner = {
+		settings: () => Promise.resolve<SpeechSettings>({ version: 1, enabled: false, voice: "Paulina", rate: 180 }),
+		voices: () => Promise.resolve<readonly string[]>(["Paulina (Enhanced)", "Paulina (Español (México))"]),
+		previewVoice: () => Promise.resolve({ failed: false, message: "Preview started" }), stopPreview: () => {},
+		selectVoice: () => Promise.resolve({ failed: false, message: "saved" }),
+		command: () => Promise.resolve({ failed: false, message: "applied" }),
+	};
+	const speech = createControlCenterSpeech(owner, {} as ExtensionContext);
+	const initial = await speech.read();
+	assert.equal(initial.rows.filter(row => row.current).length, 1);
+	assert.deepEqual(initial.rows[3]?.action, { kind: "speech-voice", voice: "Paulina (Enhanced)" });
+	owner.voices = () => Promise.reject(new Error("voice catalog unavailable"));
+	const unavailable = await speech.read();
+	assert.deepEqual(unavailable.rows.map(row => row.label), ["Enable", "Read last response", "Stop"]);
+	assert.match(unavailable.note, /voice catalog unavailable/);
+});
+void test("Explicit preview uses the unsaved draft, preserves it through failed saves and cleans up only previews", async () => {
+	const previews: string[] = [];
+	const saves: string[] = [];
+	const commands: string[] = [];
+	let stops = 0;
+	let finishPreview: ((result: { failed: boolean; message: string }) => void) | undefined;
+	const speech = createControlCenterSpeech({
+		settings: () => Promise.resolve({ version: 1, enabled: false, voice: "Paulina", rate: 180 }),
+		voices: () => Promise.resolve(["Paulina", "Samantha"]),
+		selectVoice: voice => { saves.push(voice); return Promise.resolve({ failed: true, message: "Save refused" }); },
+		previewVoice: voice => { previews.push(voice); return new Promise(resolve => { finishPreview = resolve; }); },
+		stopPreview: () => { stops++; },
+		command: args => { commands.push(args.join(" ")); return Promise.resolve({ failed: false, message: "Applied" }); },
+	}, {} as ExtensionContext);
+	const panel = new ControlCenter({ speech,
+		theme: () => ({ name: "dark", appearance: "dark", fg: (_color, text) => text }),
+		readThemes: () => [], applyTheme: () => ({ success: true }), requestRender: () => {}, height: () => 30, close: () => {},
+	});
+	panel.handleInput("\x1b[F"); await settle(); panel.handleInput("\x1b[C");
+	for (let i = 0; i < 3; i++) panel.handleInput("\x1b[B");
+	panel.handleInput("\x1b[C");
+	assert.deepEqual(saves, []); assert.deepEqual(previews, []);
+	panel.handleInput("\x1b[B"); panel.handleInput("\r");
+	assert.deepEqual(previews, ["Samantha"]);
+	assert.doesNotMatch(panel.render(100).join("\n"), /Saving globally/);
+	finishPreview?.({ failed: false, message: "Preview started" }); await settle();
+	assert.match(panel.render(100).join("\n"), /Voice: ‹ Samantha ›.*unsaved/);
+	panel.handleInput("\x1b[A"); panel.handleInput("\r"); await settle();
+	assert.deepEqual(saves, ["Samantha"]);
+	assert.match(panel.render(100).join("\n"), /Voice: ‹ Samantha ›.*unsaved/);
+	panel.handleInput("\x1b[H"); panel.handleInput("\x1b[B"); panel.handleInput("\r"); await settle();
+	assert.deepEqual(commands, ["last"]);
+	assert.match(panel.render(100).join("\n"), /Voice: ‹ Samantha ›.*unsaved/);
+	panel.handleInput("\t"); panel.handleInput("\x1b[A"); await settle();
+	assert.equal(stops, 1, "leaving Speech stops only preview");
+	panel.dispose(); panel.dispose();
+	assert.equal(stops, 2, "disposal is idempotent");
+	assert.deepEqual(commands, ["last"], "cleanup never issues narration Stop");
+	panel.handleInput("\r"); assert.deepEqual(previews, ["Samantha"]);
+});
+void test("Empty and single catalogs retain controls; only the ready selector owns arrows and narrow rendering fits", async () => {
+	for (const names of [[], ["Paulina"]]) {
+		const actions: string[] = [];
+		let resolveVoices: ((voices: readonly string[]) => void) | undefined;
+		let loading = true;
+		const speech = createControlCenterSpeech({
+			settings: () => Promise.resolve({ version: 1, enabled: false, voice: "Paulina", rate: 180 }),
+			voices: () => loading ? new Promise(resolve => { resolveVoices = resolve; }) : Promise.resolve(names),
+			selectVoice: voice => { actions.push(`save:${voice}`); return Promise.resolve({ failed: false, message: "Saved" }); },
+			previewVoice: voice => { actions.push(`preview:${voice}`); return Promise.resolve({ failed: false, message: "Preview" }); },
+			stopPreview: () => {}, command: args => { actions.push(args.join(" ")); return Promise.resolve({ failed: false, message: "Applied" }); },
+		}, {} as ExtensionContext);
+		const panel = new ControlCenter({ speech,
+			theme: () => ({ name: "dark", appearance: "dark", fg: (_color, text) => text }),
+			readThemes: () => [], applyTheme: () => ({ success: true }), requestRender: () => {}, height: () => 18, close: () => {},
+		});
+		panel.handleInput("\x1b[F"); await settle();
+		panel.handleInput("\x1b[C"); panel.handleInput("\r"); assert.deepEqual(actions, [], "loading blocks activation");
+		panel.handleInput("\x1b[D");
+		assert.match(panel.render(100).join("\n"), /> Speech/, "loading arrows still change pane focus");
+		loading = false; resolveVoices?.(names); await settle();
+		panel.handleInput("\x1b[C");
+		assert.match(panel.render(100).join("\n"), /> Enable/);
+		panel.handleInput("\x1b[D");
+		assert.match(panel.render(100).join("\n"), /> Speech/, "controls do not capture arrows");
+		panel.handleInput("\x1b[C"); panel.handleInput("\x1b[F");
+		if (names.length) {
+			panel.handleInput("\x1b[A");
+			for (const key of ["\x1b[D", "\x1b[C"]) {
+				panel.handleInput(key);
+				assert.match(panel.render(100).join("\n"), /> Voice: ‹ Paulina ›.*saved/);
+			}
+			for (const width of [1, 12, 29, 57, 58, 100]) {
+				const lines = panel.render(width);
+				assert.ok(lines.length <= 18);
+				assert.ok(lines.every(line => visibleWidth(line) <= width));
+			}
+			panel.handleInput("\t"); assert.match(panel.render(100).join("\n"), /> Speech/);
+		} else {
+			assert.equal((await speech.read()).rows.length, 3);
+			assert.match(panel.render(100).join("\n"), /> Stop/);
+		}
+		assert.deepEqual(actions, []); panel.dispose();
+	}
+});
+
+void test("Closing a pending preview cancels its sample only and ignores all late completion and input", async () => {
+	let finish: ((result: { failed: boolean; message: string }) => void) | undefined;
+	let stops = 0;
+	let previews = 0;
+	let commands = 0;
+	let closed = 0;
+	const speech = createControlCenterSpeech({
+		settings: () => Promise.resolve({ version: 1, enabled: false, voice: "Paulina", rate: 180 }),
+		voices: () => Promise.resolve(["Paulina", "Samantha"]),
+		selectVoice: () => Promise.resolve({ failed: false, message: "Saved" }),
+		previewVoice: () => { previews++; return new Promise(resolve => { finish = resolve; }); },
+		stopPreview: () => { stops++; },
+		command: () => { commands++; return Promise.resolve({ failed: false, message: "Applied" }); },
+	}, {} as ExtensionContext);
+	const panel = new ControlCenter({ speech,
+		theme: () => ({ name: "dark", appearance: "dark", fg: (_color, text) => text }),
+		readThemes: () => [], applyTheme: () => ({ success: true }), requestRender: () => {}, height: () => 30, close: () => { closed++; },
+	});
+	panel.handleInput("\x1b[F"); await settle(); panel.handleInput("\x1b[C"); panel.handleInput("\x1b[F");
+	panel.handleInput("\r"); panel.handleInput("\r"); assert.equal(previews, 1, "busy blocks duplicates");
+	panel.handleInput("\x1b[A"); panel.handleInput("\x1b[C");
+	assert.match(panel.render(100).join("\n"), /Voice: ‹ Paulina ›.*saved/, "busy cannot browse draft");
+	panel.handleInput("\x1b"); panel.dispose();
+	assert.equal(stops, 1); assert.equal(closed, 1); assert.equal(commands, 0);
+	finish?.({ failed: false, message: "Late preview" }); await settle();
+	panel.handleInput("\r"); assert.equal(previews, 1); assert.deepEqual(panel.render(100), []);
+});
+
+void test("Clean drafts follow saved aliases but dirty drafts survive external changes and catalog errors", async () => {
+	let voice = "Paulina";
+	let unavailable = false;
+	const speech = createControlCenterSpeech({
+		settings: () => Promise.resolve({ version: 1, enabled: false, voice, rate: 180 }),
+		voices: () => unavailable ? Promise.reject(new Error("catalog failed")) : Promise.resolve(["Paulina (Enhanced)", "Samantha", "Victoria"]),
+		selectVoice: () => Promise.resolve({ failed: true, message: "Save failed" }),
+		previewVoice: () => Promise.resolve({ failed: false, message: "Preview" }), stopPreview: () => {},
+		command: () => Promise.resolve({ failed: false, message: "Applied" }),
+	}, {} as ExtensionContext);
+	assert.match((await speech.read()).rows[3]!.label, /Paulina \(Enhanced\).*saved/);
+	voice = "Samantha";
+	assert.match((await speech.read()).rows[3]!.label, /Samantha.*saved/);
+	assert.match(speech.moveVoice(1)!.rows[3]!.label, /Victoria.*unsaved/);
+	voice = "Paulina";
+	assert.match((await speech.read()).rows[3]!.label, /Victoria.*unsaved/);
+	unavailable = true; assert.equal((await speech.read()).rows.length, 3);
+	unavailable = false; assert.match((await speech.read()).rows[3]!.label, /Victoria.*unsaved/);
+});
+const settle = async () => { for (let i = 0; i < 12; i++) await Promise.resolve(); };

package/extensions/osdy-pi/control-center-speech.ts

@@ -0,0 +1,82 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ControlCenterDetail, ControlCenterService } from "./control-center.js";
+import type { ResponseSpeech } from "./response-speech.js";
+import type { SpeechSettings } from "./speech-types.js";
+
+export type ControlCenterSpeechAction =
+	| { kind: "speech-enabled"; value: boolean }
+	| { kind: "speech-last" }
+	| { kind: "speech-stop" }
+	| { kind: "speech-voice"; voice: string }
+	| { kind: "speech-preview"; voice: string };
+
+export interface ControlCenterSpeechService extends ControlCenterService<ControlCenterSpeechAction> {
+	moveVoice(direction: -1 | 1): ControlCenterDetail | undefined;
+	stopPreview(): void;
+}
+
+/** Presentation projection only; the lifecycle owner performs every speech action. */
+export function createControlCenterSpeech(speech: ResponseSpeech, ctx: ExtensionContext,
+	isCurrent: () => boolean = () => true): ControlCenterSpeechService {
+	let settings: SpeechSettings | undefined;
+	let voices: readonly string[] = [];
+	let savedVoice: string | undefined;
+	let draft: string | undefined;
+	let voiceNote = "No voices available.";
+	const project = (): ControlCenterDetail => {
+		if (!settings) return { summary: "Speech unavailable", note: voiceNote, rows: [] };
+		return {
+			summary: `Speech: ${settings.enabled ? "enabled" : "disabled"} · Saved voice: ${settings.voice} · Rate: ${settings.rate} wpm`,
+			note: `Local speech: installed macOS voices or optional Kokoro (requires a separately started local server). Independent of Sounds mute. Read last response uses the saved voice while disabled. ${voiceNote}`,
+			rows: [
+				{ label: settings.enabled ? "Disable" : "Enable", current: false, action: { kind: "speech-enabled", value: !settings.enabled } },
+				{ label: "Read last response", current: false, action: { kind: "speech-last" } },
+				{ label: "Stop", current: false, action: { kind: "speech-stop" } },
+				...(!voices.length || draft === undefined ? [] : [
+					{ label: `Voice: ‹ ${draft} › (${draft === savedVoice ? "saved" : "unsaved"})`, current: draft === savedVoice,
+						action: { kind: "speech-voice" as const, voice: draft }, speechSelector: true,
+						details: ["←/→ browse draft (wraps); Enter saves. Browsing and saving never play audio.", `Saved voice: ${settings.voice}. Preview voice explicitly plays the draft without saving.`] },
+					{ label: "Preview voice", current: false, action: { kind: "speech-preview" as const, voice: draft },
+						details: ["Play a fixed sample: Spanish for Kokoro, English for native voices; does not save or enable narration."] },
+				]),
+			],
+		};
+	};
+	return {
+		async read() {
+			const nextSettings = await speech.settings();
+			let nextVoices: readonly string[] = [];
+			voiceNote = "No voices available.";
+			try {
+				nextVoices = await speech.voices(ctx);
+				if (nextVoices.length) voiceNote = "←/→ on Voice browses; Enter saves; Preview voice plays an explicit sample. Tab returns to categories.";
+			} catch (error) {
+				voiceNote = `Voices unavailable: ${error instanceof Error ? error.message : "Unknown error"}`;
+			}
+			const nextSaved = nextVoices.find(voice => voice === nextSettings.voice) ??
+				nextVoices.find(voice => voice.startsWith(`${nextSettings.voice} (`) && voice.endsWith(")"));
+			// Follow external saved changes only while the draft was clean. Never discard an unsaved choice on refresh.
+			if (nextVoices.length) {
+				if (draft === undefined || draft === savedVoice || !nextVoices.includes(draft)) draft = nextSaved ?? nextVoices[0];
+				savedVoice = nextSaved;
+			}
+			settings = nextSettings;
+			voices = nextVoices;
+			return project();
+		},
+		moveVoice(direction) {
+			if (!isCurrent() || !voices.length || draft === undefined) return undefined;
+			const index = voices.indexOf(draft);
+			draft = voices[(index + direction + voices.length) % voices.length];
+			return project();
+		},
+		stopPreview() { speech.stopPreview(ctx); },
+		apply(action) {
+			if (!isCurrent()) return Promise.resolve({ failed: true, message: "Speech session changed; reopen Control Center." });
+			if (action.kind === "speech-preview") return speech.previewVoice(action.voice, ctx);
+			if (action.kind === "speech-voice") return speech.selectVoice(action.voice, ctx);
+			if (action.kind === "speech-enabled") return speech.command([action.value ? "on" : "off"], ctx);
+			return speech.command([action.kind === "speech-last" ? "last" : "stop"], ctx);
+		},
+	};
+}