osdy-pi 1.11.16 → 1.11.17

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 installed-voice selector and 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, one saved installed 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,34 @@ 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 voices, 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 short English sample in the draft voice, 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 and offers supported voices already installed on the Pi host; it does not download voices. Empty/unavailable voice lists leave narration controls accessible. Rate tuning is not exposed. 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**.
+
+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 +685,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/extensions/osdy-pi/control-center-speech.test.ts

@@ -0,0 +1,258 @@
+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("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 installed 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 macOS speech; 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 short English sample of the draft voice; does not save or enable narration."] },
+				]),
+			],
+		};
+	};
+	return {
+		async read() {
+			const nextSettings = await speech.settings();
+			let nextVoices: readonly string[] = [];
+			voiceNote = "No installed 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);
+		},
+	};
+}

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

@@ -100,7 +100,7 @@ void test("Agents navigation and Cancel never apply; confirmation freezes input
 			{ label: "Joker", current: false, action: { kind: "agents-provider", mode: "joker" }, details: ["Target: /synthetic/settings.json", "Install Joker if absent; owned filters only. Unrelated resources preserved. Reload; restart if it fails."] },
 		] }), apply: () => { calls++; return new Promise(resolve => { finish = resolve; }); },
 	} }, () => { reloads++; });
-	f.resize(30); f.panel.handleInput("\x1b[F"); await settle();
+	f.resize(30); f.panel.handleInput("\x1b[F"); f.panel.handleInput(up); await settle();
 	assert.match(f.panel.render(120).join("\n"), /Agent mode: gentle/); assert.equal(calls, 0);
 	f.panel.handleInput(right); f.panel.handleInput("\r");
 	assert.match(f.panel.render(120).join("\n"), /> Cancel/);
@@ -124,7 +124,7 @@ void test("Agents failed, rejected and disposed successful responses never reloa
 				{ label: "Gentle", current: false, action: { kind: "agents-provider", mode: "gentle" }, details: ["Owned filters; reload follows."] },
 			] }), apply: () => new Promise((resolve, reject) => { finish = () => outcome === "error" ? reject(new Error("owner failure")) : resolve({ kind: outcome === "disposed" ? "reload" : "rejected", message: "owner failure" }); }),
 		} }, () => { reloads++; });
-		f.panel.handleInput("\x1b[F"); await settle(); f.panel.handleInput(right); f.panel.handleInput("\r");
+		f.panel.handleInput("\x1b[F"); f.panel.handleInput(up); await settle(); f.panel.handleInput(right); f.panel.handleInput("\r");
 		f.panel.render(100); f.panel.handleInput(down); f.panel.handleInput("\r");
 		if (outcome === "disposed") f.dispose();
 		const renders = f.renders(); finish(); await settle();
@@ -146,7 +146,7 @@ void test("Agent letters match visible choices, are lowercase-only and retain fu
 			read: () => Promise.resolve({ summary: "Agent mode: gentle", note: "Configured, not loaded", rows: agentRows() }),
 			apply: action => { calls.push(action); return Promise.resolve({ kind: "rejected", message: "Synthetic rejection" }); },
 		} }, () => { throw new Error("No reload on rejection"); });
-		f.resize(30); f.panel.handleInput("\x1b[F"); await settle();
+		f.resize(30); f.panel.handleInput("\x1b[F"); f.panel.handleInput(up); await settle();
 		f.panel.handleInput(key); assert.doesNotMatch(plain(f.panel.render(120)), /Confirm Agents/);
 		f.panel.handleInput(right);
 		const overview = plain(f.panel.render(120));
@@ -179,7 +179,7 @@ void test("Agent bindings derive only from available typed rows and preserve sel
 		read: () => Promise.resolve({ summary: "Agents", note: "Read only", rows }),
 		apply: () => { throw new Error("Navigation never applies"); },
 	} });
-	f.panel.handleInput("\x1b[F"); await settle(); f.panel.handleInput(right); f.panel.handleInput(up);
+	f.panel.handleInput("\x1b[F"); f.panel.handleInput(up); await settle(); f.panel.handleInput(right); f.panel.handleInput(up);
 	assert.match(plain(f.panel.render(100)), /> \[j\] Joker/);
 	f.panel.handleInput(left); f.panel.handleInput(up); await settle();
 	rows = agentRows().reverse();
@@ -203,7 +203,7 @@ void test("Ambiguous Agent projections expose no colliding letter or manufacture
 		read: () => Promise.resolve({ summary: "Agents", note: "", rows }),
 		apply: () => { throw new Error("Ambiguous binding must not apply"); },
 	} });
-	f.panel.handleInput("\x1b[F"); await settle(); f.panel.handleInput(right);
+	f.panel.handleInput("\x1b[F"); f.panel.handleInput(up); await settle(); f.panel.handleInput(right);
 	assert.doesNotMatch(plain(f.panel.render(100)), /\[j\]|j Joker/);
 	f.panel.handleInput("j"); assert.doesNotMatch(plain(f.panel.render(100)), /Confirm Agents/);
 	f.panel.handleInput("g"); assert.match(plain(f.panel.render(100)), /Select Gentle agents/);
@@ -229,7 +229,7 @@ void test("Agent hints and navigation stay bounded and keys have no profile/glob
 		read: () => Promise.resolve({ summary: "Agents", note: "Inspection only", rows: agentRows() }),
 		apply: () => { throw new Error("No apply without confirmation"); },
 	} });
-	f.panel.handleInput("\x1b[F"); await settle(); f.panel.handleInput(right);
+	f.panel.handleInput("\x1b[F"); f.panel.handleInput(up); await settle(); f.panel.handleInput(right);
 	for (const key of ["v", "s", "d", "c", "r", "b"]) f.panel.handleInput(key);
 	assert.doesNotMatch(plain(f.panel.render(100)), /Confirm Agents/);
 	for (const width of [1, 8, 24, 48, 100]) {
@@ -252,7 +252,7 @@ void test("Agent direct letters never cross loading, query, save or text input b
 		apply: () => { calls++; return new Promise(resolve => { finishSave = () => resolve({ kind: "rejected", message: "Busy finished" }); }); },
 	};
 	const f = fixture(undefined, undefined, { agents }, () => {});
-	f.panel.handleInput("\x1b[F"); f.panel.handleInput(right);
+	f.panel.handleInput("\x1b[F"); f.panel.handleInput(up); f.panel.handleInput(right);
 	for (const key of ["g", "j", "\r"]) f.panel.handleInput(key);
 	assert.equal(calls, 0); assert.doesNotMatch(plain(f.panel.render(100)), /Confirm Agents/);
 	finishRead({ summary: "Agents", note: "", rows: agentRows() }); await settle();
@@ -504,7 +504,7 @@ void test("empty feedback preserves the current theme summary on short terminals
 
 void test("empty feedback preserves focus and position with ANSI colors", () => {
 	const f = fixture();
-	assert.match(f.panel.render(80).join("\n"), /categories: 1\/10/);
+	assert.match(f.panel.render(80).join("\n"), /categories: 1\/11/);
 	f.panel.handleInput(right);
 	assert.match(f.panel.render(80).join("\n"), /detail: 1\/2/);
 	f.panel.handleInput(down);