vibeaudio 0.18.0 → 0.20.0

package/README.md

@@ -147,7 +147,7 @@ Want the music to follow what the agent is doing — calm while it reads, busies
 vibe --reactive --install-hooks
 ```
 
-Prefer a guided setup? Run `vibe` with nothing after it: a menu asks for your agent, genre and volume (press `p` to hear a genre first) and installs the hooks for you.
+Prefer a guided setup? Run `vibe` with nothing after it: a menu asks for your agent, genre and volume (press `p` to hear a genre first) and installs the hooks for you. The menu's last entry, **Alerts & extras**, flips the saved toggles (banners, spoken announcements, `vibe --announce`, music, a one-hour mute) without a flag to remember. Installing hooks doesn't start the agent: open it whenever you like, and the music plays from your first prompt. ("Just launch it" and "This session only" do start it.)
 
 Now run your agent normally, with no prefix. Music starts when you submit a prompt and stops with a chime when the agent finishes. [Details below.](#-agent-hooks-no-wrapper-needed)
 
@@ -314,7 +314,8 @@ Every session of an agent is tracked separately, by the session id in its hook p
 * **The music plays while any session is working.** A second prompt doesn't restart it, and it stops only when the last working session finishes.
 * **Every session gets its own chime.** A quick question that finishes while another agent is still busy chimes "done" and the music carries on underneath.
 
-* **Which one?** With three terminals going, a chime says something finished and leaves you alt-tabbing to find out what. `vibe --notify` adds a desktop banner — `api: finished`, `web: needs you (Bash)` — named after the project the session runs in. Off by default, since a banner is more intrusive than a sound; macOS (`osascript`) and Linux (`notify-send`, needs a notification daemon), nothing on Windows yet. A mute silences the banner too.
+* **Which one?** With three terminals going, a chime says something finished and leaves you alt-tabbing to find out what. `vibe --notify` adds a desktop banner (`api: finished`, `web: needs you (Bash)`) and [`vibe --speak`](#-spoken-announcements-vibe---speak) adds a spoken line. Both are off by default. [Banner details below.](#-desktop-banners-vibe---notify)
+* **Say it out loud.** `vibe --speak` adds a spoken line after the chime (*"api: done."*) when two or more sessions are going. [Details below.](#-spoken-announcements-vibe---speak)
 
 <details>
 <summary><b>The rest of how sessions share one stream</b></summary>
@@ -333,6 +334,44 @@ Sessions with no id in their payload share a single slot, so they behave as one.
 
 > **One player is shared.** Prompt two agents at once and the last prompt owns the music. One person, one set of speakers — deliberate, not a limitation being worked around.
 
+### 🔔 Desktop banners: `vibe --notify`
+
+```bash
+vibe --notify       # on
+vibe --no-notify    # off again (the default)
+```
+
+A banner names the project when a turn **finishes**, **fails**, **needs you** (a permission dialog or a question) or **looks stuck**: `api: finished`, `web: needs you (Bash)`. It is saved, so it applies from your next prompt with nothing to reinstall. `vibe --status` shows it on the `notify` line, the **Alerts & extras** screen in the `vibe` menu toggles it, and `VIBE_NOTIFY=1` turns it on for one shell.
+
+- **Platforms.** macOS through `osascript`, Linux through `notify-send` (it needs a notification daemon, which most desktops have). **Windows has no banner yet**; `vibe --doctor` says so when `--notify` is on and nothing can show one. The macOS command runs without error, but how the banner looks on screen has not been checked, and the Linux path has not been run.
+- **Off by default**, because a banner is more intrusive than a sound.
+- **Safe by construction.** The project name reaches the notifier as an argument, never as part of a script, because a directory name is whatever its owner called it.
+- **Mute.** `--mute` and `VIBE_DISABLE` silence banners with everything else.
+- **Scripts.** With it on, `vibe --announce "deploy finished"` shows its text as a banner too.
+
+### 🔊 Spoken announcements: `vibe --speak`
+
+A chime says that something finished, not which project. With `--speak`, the system voice adds one short sentence after the chime:
+
+> "api: done." · "api: failed." · "web needs you: Bash." · "payments looks stuck."
+
+```bash
+vibe --speak          # on: only when two or more sessions are going
+vibe --speak-always   # on: every time, even with one session
+vibe --no-speak       # off again (the default)
+```
+
+It is saved, so it applies from your next prompt with nothing to reinstall, and `vibe --status` shows the current setting on its `speak` line. The `vibe` menu has it too: **Alerts & extras**, then Enter on "Spoken announcements" steps through off, auto and always. `VIBE_SPEAK=off` turns it off for one shell.
+
+**To hear it once:** `vibe --speak-always`, then run any agent turn (and `vibe --unmute` first if you muted).
+
+- **Why only with two sessions by default.** The sentence answers "which one?". With a single session the chime already told you, so `--speak` stays quiet and `--speak-always` is the opt-in for every time.
+- **What it says.** A project name and one of four fixed states. It never reads the agent's output, and it names a tool only if it is one of the built-in ones (`Bash`, `Edit`, ...), not an MCP tool whose name someone else chose. Names like `my-app_v2` are spoken as "my app v2".
+- **Voices.** macOS `say`, Linux `spd-say` (or `espeak-ng` / `espeak`), Windows `System.Speech` through PowerShell. Nothing is installed by VibeAudio; with no voice present it stays silent, and `vibe --doctor` says so. Verified against the real macOS `say` and stub voices; **not run on Linux or Windows**.
+- **Safety.** The text reaches the voice as an argument (an environment variable on Windows), never as part of a shell command or script, and embedded speech commands such as `[[volm 0]]` are stripped.
+- **Several at once.** Sessions that finish together speak one after another, not over each other, and the same sentence twice within five seconds is said once. Not done: merging them into "api and web: done", and lowering the music while it speaks.
+- **Muting.** `--mute` and `VIBE_DISABLE` silence it with everything else. `vibe --announce "deploy finished"` text is spoken as well when speech is on.
+
 ### As a plugin (Claude Code and Codex)
 
 If Claude Code or Codex is the agent you use, the plugin installs the same hooks with no npm step. Inside a Claude Code session, type:
@@ -522,7 +561,7 @@ Each session is `working`, `stuck` (4 of its last 8 tool calls failed) or `waiti
 {"v":1,"at":1791026130000,"event":"waiting","session":"…","project":"/work/api","tool":"Bash","status":"waiting"}
 ```
 
-Events: `started`, `waiting`, `resumed`, `stuck`, `recovered`, `finished` (with `outcome`: `success` or `failure`), `interrupted`, `ended` (with `reason` when `vibe --stop` or `--uninstall-hooks` ended it). Every line also carries `status`, the machine's state after the event, so a consumer that only cares about the overall state can read that one field.
+Events: `started`, `waiting`, `resumed`, `stuck`, `recovered`, `finished` (with `outcome`: `success` or `failure`), `interrupted`, `ended` (with `reason` when `vibe --stop` or `--uninstall-hooks` ended it) and `announced` (from [`vibe --announce`](#-beyond-agents-vibe---announce), with `text` and `outcome`, and no session). Every line also carries `status`, the machine's state after the event, so a consumer that only cares about the overall state can read that one field.
 
 #### 📟 Status Bar & Desktop Integrations
 
@@ -563,11 +602,18 @@ The parentheses matter: Starship hides a group whose variables are empty, so the
 vibe --events | jq --unbuffered -c 'select(.event=="waiting" or .event=="stuck") | {event, project}' \
   | while read -r line; do curl -s -X POST -H 'Content-Type: application/json' -d "$line" https://example.com/hook; done
 ```
-The `select` also drops the snapshot `--events` prints first (it has no `event` field), so only changes after you start it are sent: a session already waiting at that moment is not announced. For the current state, call `vibe --state` once.
+The `select` also drops the snapshot `--events` prints first (its `event` is `state`), so only changes after you start it are sent: a session already waiting at that moment is not announced. For the current state, call `vibe --state` once.
+
+**Home Assistant (or any smart light)** — send the machine's overall state on every change, and let the receiving side choose the colour. Home Assistant takes this as a [webhook trigger](https://www.home-assistant.io/docs/automation/trigger/#webhook-trigger); replace the URL and the id:
+```bash
+vibe --events | jq --unbuffered -c 'select(.event != "state") | {status, event, project}' \
+  | while read -r line; do curl -s -X POST -H 'Content-Type: application/json' -d "$line" http://homeassistant.local:8123/api/webhook/vibeaudio; done
+```
+`status` is `idle`, `working`, `stuck` or `waiting`, already the most urgent across all your sessions, so the automation is a plain switch on one field (for example amber for `waiting`, red for `stuck`, off for `idle`) and never has to count sessions itself. A web request goes out on every change, so point it at a local bridge rather than a metered service.
 
 *Not covered yet: a macOS menu bar plugin (SwiftBar/xbar) and Linux desktop alerts. Neither has been run on a real setup, so neither is documented. `--notify` already raises a banner when a turn finishes or needs you.*
 
-*Verified on macOS arm64 with Node 24, tmux 3.7 and Starship 1.26: the tmux and Starship segments showed `working`, `working ×2` and `waiting: web` and disappeared when idle; the `say` and webhook pipelines fired once per `waiting` event while the stream stayed open. Not run on Linux or Windows.*
+*Verified on macOS arm64 with Node 24, tmux 3.7 and Starship 1.26 (the Home Assistant recipe: the request it sends, against a local stand-in server, was `{"status":"waiting","event":"waiting","project":"/work/api"}` on a permission dialog; not run against Home Assistant itself): the tmux and Starship segments showed `working`, `working ×2` and `waiting: web` and disappeared when idle; the `say` and webhook pipelines fired once per `waiting` event while the stream stayed open. Not run on Linux or Windows.*
 
 The stream is a local file (`~/.vibeaudio/events.jsonl`, rotated at 256 KB), so it never leaves your machine. It keeps updating while you're muted, because a mute silences sound and a light isn't sound. The `v` field is the format version, and any breaking change will increment it.
 
@@ -594,10 +640,12 @@ vibe --announce "deploy" --outcome attention     # the "needs you" chime
 gh run watch; vibe --announce "CI finished" --exit-code $?
 ```
 
-It plays the chime for the outcome, shows the `--notify` banner if you have it on, and appends an `announced` event (`source: "cli"`, the text and the outcome) to `~/.vibeaudio/events.jsonl`, so a light or dashboard built on `--events` reacts too. It never starts or stops music and never touches an agent session. A mute silences the sound and banner but not the event, like every event.
+It plays the chime for the outcome, shows the `--notify` banner and says the text aloud if you have those on, and appends an `announced` event (`source: "cli"`, the text and the outcome) to `~/.vibeaudio/events.jsonl`, so a light or dashboard built on `--events` reacts too. It never starts or stops music and never touches an agent session. A mute silences the sound and banner but not the event, like every event.
 
 It always exits 0, so it can't turn a pipeline red, and the text is only ever passed as an argument, never through a shell. Text is capped at 200 characters, and the same text announced again within five seconds is dropped, so a loop can't machine-gun your speakers. `--no-chime` keeps it to the banner and event.
 
+To switch it off for good, for a script you can't edit: `vibe --announcements off` (or `VIBE_ANNOUNCE=off` for one shell, or the **Alerts & extras** screen in the `vibe` menu). It then does nothing and still exits 0, without even writing the event. A mute is different: it silences the sound but keeps the event.
+
 ## 🖥️ Everything Else (Claude Desktop, VS Code… via MCP)
 
 **Claude Code, [Codex](https://github.com/openai/codex), [Cursor](https://cursor.com/docs/hooks), [Grok](https://docs.x.ai/build/features/hooks), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Copilot CLI](https://docs.github.com/en/copilot/reference/hooks-configuration), [Qwen Code](https://github.com/QwenLM/qwen-code) [Windsurf](https://docs.devin.ai/desktop/cascade/hooks) and [Antigravity](https://antigravity.google/docs/hooks) have hook systems, and `--install-hooks` writes to all nine** — use [hooks](#-agent-hooks-no-wrapper-needed) there, they're strictly better. This section is for everything else. MCP is the way in: it's plain stdio JSON-RPC, so the setup is identical everywhere and only the config file differs.
@@ -781,6 +829,8 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--status` | Show what's installed, running and detected, then exit | — |
 | `--doctor` | Check the setup; every problem comes with the command that fixes it. Exits 1 on a failure, so it scripts | — |
 | `--notify` / `--no-notify` | Also show a desktop banner naming the project when a turn finishes, fails or needs you. Saved to `config.json` | off |
+| `--speak` / `--speak-always` / `--no-speak` | Say which project finished, failed or needs you, after the chime: only with two or more sessions going (`--speak`), or every time (`--speak-always`). Saved to `config.json` | off |
+| `--announcements <on\|off>` | Turn `vibe --announce` on or off for good. Saved to `config.json` | on |
 | `--report [days]` | How long you waited on agents, and on which projects, from the local turn log | `7` days |
 | `--statusline` | The same state as one plain line for tmux or a shell prompt (`working ×2`, `waiting: api`); prints nothing when idle | — |
 | `--state` | What every agent on the machine is doing, as one line of JSON: `idle`, `working`, `stuck` or `waiting` | — |
@@ -813,6 +863,8 @@ export VIBE_SEED=7              # Same arrangement everywhere, ignoring the dire
 export VIBE_DISABLE=1           # Mute, without uninstalling anything
 export VIBE_MUSIC=off           # Signals only: chimes and banners, no music, for this shell
 export VIBE_NOTIFY=1            # Desktop banner naming the project, for this shell
+export VIBE_SPEAK=auto           # Spoken announcements (auto, always or off), for this shell
+export VIBE_ANNOUNCE=off         # Make vibe --announce do nothing, for this shell
 export VIBE_NO_HISTORY=1        # Do not log finished turns (what --report reads)
 export VIBE_NO_UPDATE_CHECK=1   # Never ask npm whether a newer version is out
 export VIBE_NO_FADE=1           # macOS: play with plain afplay, no fade in/out

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Procedural focus music while your AI coding tools (Claude Code, Codex, Cursor, Grok, Gemini, Copilot) think — a different arrangement per project.",
   "bin": {
     "vibeaudio": "bin/vibeaudio.js",

package/src/cli.js

@@ -61,7 +61,9 @@ Procedural focus music while your AI coding tools think.
   vibe --preview jazz
   gh run watch; vibe --announce "CI finished" --exit-code $?   \x1b[90m# the chime for a CI run or a script\x1b[0m
   vibe --render                  \x1b[90m# save this repo's sound as a .wav to share\x1b[0m
-  vibe                           \x1b[90m# menu: pick a tool and a sound (p auditions a genre)\x1b[0m
+  vibe --notify                  \x1b[90m# a desktop banner naming the project when a turn finishes or needs you (macOS, Linux)\x1b[0m
+  vibe --speak                   \x1b[90m# a voice names the project after the chime (--no-speak turns it off)\x1b[0m
+  vibe                           \x1b[90m# menu: pick a tool and a sound (p auditions a genre); "Alerts & extras" flips banners, speech, announce, music, mute\x1b[0m
 
 \x1b[1mOPTIONS:\x1b[0m
   -g, --genre <name>           Select genre: lofi (default), synthwave, 8bit, electronic, jazz, zen, piano, drone, rain, ocean, random
@@ -79,10 +81,13 @@ Procedural focus music while your AI coding tools think.
       --preview <genre>        Play one loop of a genre and exit
       --render [file]          Write this project's music to a .wav and exit (full scale, ignores --volume)
       --status                 Show what is installed, running and detected, then exit
-      --notify | --no-notify   Also show a desktop banner naming the project when a turn finishes or needs you (off by default)
+      --notify | --no-notify   Also show a desktop banner naming the project when a turn finishes, fails, needs you or looks stuck (macOS and Linux; off by default)
+      --speak | --no-speak     Also say which project finished, failed or needs you, after the chime - with two or more sessions going (off by default)
+      --speak-always           Like --speak, but every time, even with one session
+      --announcements <on|off> Turn vibe --announce on or off for good (a saved setting; on by default)
       --report [days]          How long you waited on agents, and where (default: 7 days)
       --state                  Print what every agent is doing as JSON: idle, working, stuck or waiting
-      --announce <text>        Play the signals for something that is not an agent (CI, a deploy, a script), then exit
+      --announce <text>        Play the signals for something that is not an agent (CI, a deploy, a script), then exit (spoken too when --speak is on)
       --outcome <o>            With --announce: success (default), failure or attention
       --exit-code <n>          With --announce: 0 is success, anything else failure (use $?)
       --dashboard              Serve a read-only live view of every agent on this machine, and open it
@@ -102,7 +107,7 @@ Procedural focus music while your AI coding tools think.
       --dry-run                With --install-hooks: show what would change, write nothing
       --uninstall-hooks        Remove the hooks again, from every agent
   -h, --help                   Show this help message
-      --version                Show version
+      --version                Show version (update with: npm i -g vibeaudio)
 
 \x1b[1mSETTINGS:\x1b[0m
   A genre or volume with no command after it is saved as your default:
@@ -115,15 +120,45 @@ Procedural focus music while your AI coding tools think.
   \x1b[1m--here\x1b[0m setting beats the global one, so a one-off
   \x1b[1mvibe --genre 8bit npm test\x1b[0m stays a one-off.
 
+\x1b[1mINTEGRATIONS:\x1b[0m
+  Every agent's state, as one stream you can build on (lights, banners, webhooks):
+
+      vibe --events                  \x1b[90m# the current state, then one JSON line per change\x1b[0m
+      vibe --state                   \x1b[90m# one snapshot: idle, working, stuck or waiting\x1b[0m
+      vibe --statusline              \x1b[90m# one plain line for tmux or a prompt\x1b[0m
+
+  Events: started, waiting, resumed, stuck, recovered, finished, interrupted, ended, announced.
+  Recipes (tmux, Starship, voice, webhook, Home Assistant): https://kiril6.github.io/vibeaudio/
+
+\x1b[1mUNINSTALL:\x1b[0m
+  In this order, so no agent is left running a hook that points at nothing:
+
+      vibe --uninstall-hooks         \x1b[90m# 1. unwire every agent, and stop any player still running\x1b[0m
+      npm rm -g vibeaudio            \x1b[90m# 2. remove the CLI\x1b[0m
+      rm -rf ~/.vibeaudio            \x1b[90m# 3. optional: cached audio, saved settings, state\x1b[0m
+
 \x1b[1mENVIRONMENT:\x1b[0m
   VIBE_GENRE=<name>            Override the saved genre for this shell
   VIBE_VOLUME=<5-100>          Override the saved volume for this shell
   VIBE_CHIME_VOLUME=<5-100>    Override the saved chime volume for this shell
   VIBE_GRACE_MS=<ms>           Override the saved grace window, in ms
   VIBE_MUSIC=<on|off>          Override the saved music setting for this shell
+  VIBE_NOTIFY=<on|off>         Override the saved desktop-banner setting for this shell
+  VIBE_SPEAK=<auto|always|off> Override the saved spoken-announcement setting for this shell
+  VIBE_ANNOUNCE=<on|off>       Turn vibe --announce off for this shell
   VIBE_SEED=<n>                Pin the arrangement instead of deriving it from the directory
   VIBE_DISABLE=1               Mute automatic playback without uninstalling anything
   VIBE_NO_UPDATE_CHECK=1       Never check npm for a newer version
+
+\x1b[1mNO SOUND?\x1b[0m
+  vibe --doctor                  \x1b[90m# checks the setup; each problem comes with its fix\x1b[0m
+  vibe --status                  \x1b[90m# shows whether you are muted, and what is installed\x1b[0m
+  vibe --unmute                  \x1b[90m# clears a mute\x1b[0m
+
+\x1b[1mMORE:\x1b[0m
+  Settings and state: ~/.vibeaudio
+  Docs: https://kiril6.github.io/vibeaudio/
+  Problems and ideas: https://github.com/kiril6/vibeaudio/issues
 `);
   printUpdateNotice();
 }
@@ -148,6 +183,7 @@ const VALUE_FLAGS = new Set([
   "-cv", "--chime-volume",
   "--grace",
   "--music",
+  "--announcements",
   "--seed",
   "--tools",
   "--event",
@@ -199,6 +235,8 @@ function parseArgs(argv) {
   let eventsFlag = false;
   let doctorFlag = false;
   let notifyFlag = null;
+  let speakFlag = null;
+  let announcementsFlag = null;
   let reportDays = null;
   let stopFlag = false;
   let muteFlag = null;
@@ -400,6 +438,23 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--speak" || arg === "--speak-always" || arg === "--no-speak") {
+      speakFlag = arg === "--speak" ? "auto" : arg === "--speak-always" ? "always" : "off";
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--announcements") {
+      const value = args[i + 1].toLowerCase();
+      if (value !== "on" && value !== "off") {
+        console.error(`\x1b[31m[vibeaudio] --announcements takes on or off, not '${args[i + 1]}'.\x1b[0m`);
+        process.exit(1);
+      }
+      announcementsFlag = value === "on";
+      i += 2;
+      continue;
+    }
+
     if (arg === "--doctor") {
       doctorFlag = true;
       i += 1;
@@ -578,6 +633,8 @@ function parseArgs(argv) {
     events: eventsFlag,
     doctor: doctorFlag,
     notify: notifyFlag,
+    speak: speakFlag,
+    announcements: announcementsFlag,
     report: reportDays,
     stop: stopFlag,
     mute: muteFlag,
@@ -717,6 +774,7 @@ function installHookTargets(ids, genre, volume, reactive, dryRun = false, typed
   const live = ids.filter((id) => hooks.TARGETS[id].liveReload !== false).map((id) => hooks.TARGETS[id].name);
   if (live.length) console.log(`  ${live.join(", ")}: takes effect on your next prompt - no restart needed.`);
   console.log(`  \x1b[90mChange the sound any time with: vibe --genre <name> --volume <n> — no reinstall.\x1b[0m`);
+  console.log(`  \x1b[90mCheck it with vibe --status · quiet for a call: vibe --mute · everything else: vibe --help\x1b[0m`);
   if (ids.length > 1) {
     console.log(`  \x1b[90mOne player is shared: whichever agent you prompt last owns the music.\x1b[0m`);
   }
@@ -824,6 +882,10 @@ function printStatus() {
   console.log(`  volume    ${on(`${Math.round(volumeNow() * 100)}%`)}${source("VIBE_VOLUME", "volume")}`);
   console.log(`            ${off("change either with: vibe --genre <name> --volume <n>")}`);
   console.log(`  notify    ${hooks.notifyEnabled() ? on("on") : off("off")}${off("  desktop banner naming the project — vibe --notify / --no-notify")}`);
+  const speech = require("./speech");
+  const speakNow = speech.speakMode(process.env, loadConfig());
+  console.log(`  speak     ${speakNow === "off" ? off("off") : on(speakNow)}${off(speakNow === "off" ? "  a voice names the project after the chime — vibe --speak / --speak-always" : speakNow === "auto" ? "  only with two or more sessions — vibe --speak-always / --no-speak" : "  every time — vibe --no-speak")}${speakNow !== "off" && !speech.voiceAvailable() ? "  \x1b[33mno voice found on this machine\x1b[0m" : ""}`);
+  console.log(`  announce  ${hooks.announceEnabled() ? on("on") : "\x1b[33moff\x1b[0m"}${off(hooks.announceEnabled() ? "  vibe --announce <text> for scripts and CI — vibe --announcements off to disable" : "  vibe --announce does nothing — vibe --announcements on")}`);
 
   // Audio backend
   const backend = detect();
@@ -1030,6 +1092,22 @@ function doctorChecks() {
   if (playbackDisabled()) add("warn", "VIBE_DISABLE", `set to "${process.env.VIBE_DISABLE}" — automatic playback is off`, "unset VIBE_DISABLE");
   if (mute === null && !playbackDisabled()) add("ok", "Mute", "not muted");
   if (!musicEnabled()) add("ok", "Music", "off — chimes and banners only, by your setting (vibe --music on)");
+  if (hooks.notifyEnabled()) {
+    if (process.platform === "darwin") add("ok", "Desktop banners", "on, through osascript");
+    else if (process.platform === "linux") {
+      if (require("./interactive").isInstalled("notify-send")) add("ok", "Desktop banners", "on, through notify-send");
+      else add("warn", "Desktop banners", "on, but notify-send was not found, so no banner appears", "install libnotify (notify-send) and a notification daemon");
+    } else add("warn", "Desktop banners", "on, but this platform has no banner backend yet, so none appears", "vibe --no-notify");
+  }
+  {
+    const speech = require("./speech");
+    const mode = speech.speakMode(process.env, loadConfig());
+    if (mode !== "off") {
+      if (speech.voiceAvailable()) add("ok", "Spoken announcements", `${mode} — a voice is available`);
+      else add("warn", "Spoken announcements", `${mode}, but no voice was found, so nothing is said`,
+        process.platform === "linux" ? "install spd-say, espeak-ng or espeak" : "this system has no speech command on PATH");
+    }
+  }
 
   const pid = readDaemonPid(hooks.PID_FILE);
   if (pid === null) add("ok", "Background player", "not running");
@@ -1659,6 +1737,44 @@ function executeCommand(cmdArgs, genre, volume, chimeVolume, grace = DEFAULT_GRA
   process.on("SIGTERM", () => relaySignal("SIGTERM"));
 }
 
+/**
+ * Acts on what the menu returned, and says whether to launch the tool.
+ *
+ * Choosing hooks is setup: it installs them and stops. Nothing is started, so
+ * someone running several agents can set one up now and open it when they
+ * like - the music plays from their first prompt either way. Only "just launch
+ * it" and "this session only" go on to start the tool. A failed install is an
+ * error with a non-zero exit, not a launch without the hooks that were asked for.
+ */
+function applyMenuSelection(selection, volume) {
+  if (!selection.installHooks) return true;
+  const hooks = require("./hooks");
+  try {
+    installHookTargets([selection.hookTarget], selection.genre, volume, selection.reactive, false,
+      { genre: selection.genre, volume });
+  } catch (err) {
+    console.error(`\x1b[31m[vibeaudio] ${err.message}\x1b[0m`);
+    process.exit(1);
+  }
+  const saved = loadConfig();
+  // Everything VibeAudio is hooked into on this machine, not just this run's
+  // pick: with several agents, "which ones are set up?" is the question, and
+  // which one to open first is the user's call.
+  const hooked = Object.entries(hooks.TARGETS).filter(([id]) => hooks.userHooksInstalled(null, id));
+  const names = hooked.map(([, t]) => t.name).join(", ");
+  const cmds = hooked.map(([, t]) => t.cmd).join(", ");
+  console.log(
+    `\n\x1b[32m✔ VibeAudio v${pkg.version} is hooked into: ${names} (${saved.genre} @ ${saved.volume}%).\x1b[0m ` +
+    `Nothing was started: open ${hooked.length > 1 ? "any of them" : "it"} whenever you like (\x1b[1m${cmds}\x1b[0m), and the music plays from your first prompt.\n` +
+    `  \x1b[90mMore agents? Run vibe again for each, or vibe --install-hooks to set up every one it finds.\x1b[0m\n` +
+    `  \x1b[90mStay current: run npm i -g ${pkg.name} now and then (hooks keep working); vibe --status tells you when a newer version is out.\x1b[0m\n` +
+    `  \x1b[90mOptional: vibe --speak adds a spoken line naming the project after the chime (vibe --no-speak turns it off).\x1b[0m\n` +
+    `  \x1b[90mAll commands and options: vibe --help\x1b[0m\n`
+  );
+  printUpdateNotice();
+  return false;
+}
+
 async function run() {
   const {
     genre,
@@ -1677,6 +1793,8 @@ async function run() {
     events: followEvents,
     doctor: showDoctor,
     notify: notifyChange,
+    speak: speakChange,
+    announcements: announcementsChange,
     report: reportDays,
     stop: shouldStop,
     mute: muteChange,
@@ -1714,6 +1832,23 @@ async function run() {
     }
   }
 
+  // These act on their own and then exit. With a command after them the command
+  // used to be dropped without a word and the exit code was 0, so
+  // `vibe --notify npm test && deploy` deployed without running the tests.
+  {
+    const own = muteChange !== null ? (muteChange ? "--mute" : "--unmute")
+      : notifyChange !== null ? (notifyChange ? "--notify" : "--no-notify")
+      : speakChange !== null ? (speakChange === "off" ? "--no-speak" : speakChange === "always" ? "--speak-always" : "--speak")
+      : announcementsChange !== null ? "--announcements"
+      : announceReq.text !== null ? "--announce"
+      : null;
+    if (own && cmdArgs.length > 0) {
+      console.error(`\x1b[31m[vibeaudio] ${own} does not wrap a command, so '${cmdArgs.join(" ")}' was not run.\x1b[0m ` +
+        (own === "--announce" ? `Put it after the command instead: ${cmdArgs.join(" ")}; vibe --announce "..." --exit-code $?` : `Run ${own} on its own, then the command.`));
+      process.exit(1);
+    }
+  }
+
   if (announceReq.text === null && (announceReq.outcome !== null || announceReq.exitCode !== null)) {
     console.error("\x1b[31m[vibeaudio] --outcome and --exit-code go with --announce <text>.\x1b[0m");
     process.exit(1);
@@ -1771,6 +1906,25 @@ async function run() {
     return;
   }
 
+  if (speakChange !== null) {
+    saveConfig({ speak: speakChange });
+    console.log(speakChange === "off"
+      ? "\x1b[90mSpoken announcements off.\x1b[0m"
+      : `\x1b[32m✔ Spoken announcements on${speakChange === "always" ? " (every time)" : " (when two or more sessions are going)"}.\x1b[0m After the chime, a voice says which project finished, failed or needs you.`);
+    if (speakChange !== "off" && !require("./speech").voiceAvailable()) {
+      console.log("  \x1b[33mNo voice found on this machine\x1b[0m, so nothing will be said. Linux needs spd-say, espeak-ng or espeak.");
+    }
+    return;
+  }
+
+  if (announcementsChange !== null) {
+    saveConfig({ announce: announcementsChange });
+    console.log(announcementsChange
+      ? "\x1b[32m✔ vibe --announce is on.\x1b[0m"
+      : "\x1b[90mvibe --announce is off: it now does nothing, and exits 0.\x1b[0m");
+    return;
+  }
+
   if (shouldStop) {
     const hooks = require("./hooks");
     const stopped = hooks.stopDaemon();
@@ -1874,19 +2028,10 @@ async function run() {
       process.exit(0);
     }
 
-    const chosenVol = selection.volume !== undefined ? selection.volume : volume;
+    if (selection.settings) return; // the toggles were saved on the way out of that screen
 
-    if (selection.installHooks) {
-      // The install can refuse (npx checkout) or abort (malformed settings).
-      // Either way, say so and still launch the tool the user asked for -
-      // they came here to start an agent, not to configure one.
-      try {
-        installHookTargets([selection.hookTarget], selection.genre, chosenVol, selection.reactive, false,
-          { genre: selection.genre, volume: chosenVol });
-      } catch (err) {
-        console.error(`\x1b[31m[vibeaudio] ${err.message}\x1b[0m`);
-      }
-    }
+    const chosenVol = selection.volume !== undefined ? selection.volume : volume;
+    if (!applyMenuSelection(selection, chosenVol)) return;
 
     return executeCommand(selection.cmd, selection.genre, chosenVol, chimeVolume, grace, noChime, noHud, music);
   }
@@ -1898,6 +2043,7 @@ module.exports = {
   run,
   parseArgs,
   hooksAlreadyCover,
+  applyMenuSelection,
   previewAudioFile,
   windowsCommandNeedsShell
 };

package/src/hooks.js

@@ -17,6 +17,7 @@ const path = require("path");
 const { spawn, execFileSync } = require("child_process");
 const { AudioPlayer, loadConfig, playbackDisabled } = require("./player");
 const { recordTurn } = require("./history");
+const speech = require("./speech");
 
 const STATE_DIR = path.join(os.homedir(), ".vibeaudio");
 const PID_FILE = path.join(STATE_DIR, "daemon.pid");
@@ -1159,6 +1160,37 @@ function notify(raw, message) {
   return banner(`${sessionLabel(parsePayload(raw))}: ${message}`);
 }
 
+/**
+ * `--announce` can be switched off for good (menu, `--announcements off`,
+ * `VIBE_ANNOUNCE=off`) for a script that cannot be edited. On unless said
+ * otherwise; env beats the saved setting.
+ */
+function announceEnabled(env = process.env, config = loadConfig()) {
+  const raw = String(env.VIBE_ANNOUNCE ?? config.announce ?? "").trim().toLowerCase();
+  return !["0", "false", "off", "no"].includes(raw);
+}
+
+/**
+ * The spoken line for a hook event (#33), after its chime. `sessionCount` is
+ * how many sessions are in flight, this one included: in `auto` mode it takes
+ * two to be worth saying, since the point is "which one?". `chimed` says a
+ * chime was started detached, so the sentence waits for it; one that already
+ * played to the end (the Stop hook plays it inline) needs no wait. Only a
+ * built-in tool is named: an MCP tool's name is third-party text.
+ */
+function speakEvent(raw, kind, sessionCount, { chimed = false, volume = 0.4, tool = "" } = {}) {
+  try {
+    if (!speech.shouldSpeak(speech.speakMode(process.env, loadConfig()), sessionCount)) return false;
+    const named = tool && Object.hasOwn(TOOL_TIERS, tool) ? tool : "";
+    return speech.speak(speech.phrase(kind, sessionLabel(parsePayload(raw)), named), {
+      delayMs: speech.chimeDelayMs(kind, chimed),
+      volume
+    });
+  } catch (e) {
+    return false; // speech must never fail the hook
+  }
+}
+
 const ANNOUNCE_FILE = path.join(STATE_DIR, "announce.json");
 const ANNOUNCE_MAX_CHARS = 200;
 const ANNOUNCE_REPEAT_MS = 5000;
@@ -1180,6 +1212,7 @@ const ANNOUNCE_OUTCOMES = ["success", "failure", "attention"];
  */
 function announce(text, { outcome = "success", volume = 0.4, chimeVolume = null, noChime = false, genre } = {}) {
   try {
+    if (!announceEnabled()) return false; // switched off: inert, event included
     const clean = String(text).replace(/[\u0000-\u001f\u007f]+/g, " ").trim().slice(0, ANNOUNCE_MAX_CHARS);
     const now = Date.now();
     try {
@@ -1193,6 +1226,11 @@ function announce(text, { outcome = "success", volume = 0.4, chimeVolume = null,
     banner(`${clean}${outcome === "failure" ? " (failed)" : outcome === "attention" ? " (needs you)" : ""}`);
     // Detached: a pipeline should not wait out the chime.
     if (!noChime) new AudioPlayer().stop({ playChime: true, outcome, volume, chimeVolume, genre, detach: true });
+    // The caller's own text, read after the chime. No session count to wait on:
+    // a script has no "which one", so `auto` and `always` both speak it.
+    if (speech.speakMode(process.env, loadConfig()) !== "off") {
+      speech.speak(clean, { delayMs: speech.chimeDelayMs(outcome, !noChime), volume: chimeVolume !== null ? chimeVolume : volume });
+    }
     return true;
   } catch (e) {
     return true; // a notifier must never fail the script that called it
@@ -1201,6 +1239,7 @@ function announce(text, { outcome = "success", volume = 0.4, chimeVolume = null,
 
 function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChime = false, genre, raw = "" } = {}) {
   const id = sessionId(payloadSession(parsePayload(raw)));
+  const active = listSessions().length; // this session included, until its file goes
   // A turn that ends while paused for the user - a denied tool that nothing
   // resumed after - still finished, so its session counts either way.
   const session = readSession(id);
@@ -1223,10 +1262,16 @@ function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChi
   if (!others) fs.rmSync(INTENSITY_FILE, { force: true });
   if (!(tracked || wasPlaying)) return false;
   notify(raw, outcome === "failure" ? "failed" : "finished");
-  if (noChime) return false;
+  const speakVolume = chimeVolume !== null ? chimeVolume : volume;
+  if (noChime) {
+    speakEvent(raw, outcome === "failure" ? "failure" : "success", active, { volume: speakVolume });
+    return false;
+  }
 
-  // Chime plays in this short-lived hook process.
+  // Chime plays in this short-lived hook process, to the end; the sentence
+  // starts after it, so it needs no delay of its own.
   new AudioPlayer().stop({ playChime: true, outcome, volume, chimeVolume, genre });
+  speakEvent(raw, outcome === "failure" ? "failure" : "success", active, { volume: speakVolume });
   return true;
 }
 
@@ -1278,6 +1323,11 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
   const tool = payloadToolName(raw);
   notify(raw, tool ? `needs you (${tool})` : "needs you");
   if (!noChime) new AudioPlayer().stop({ playChime: true, outcome: "attention", volume, chimeVolume, detach: true });
+  speakEvent(raw, "attention", listSessions().length, {
+    chimed: !noChime && !playbackDisabled(),
+    volume: chimeVolume !== null ? chimeVolume : volume,
+    tool
+  });
   return true;
 }
 
@@ -1314,6 +1364,10 @@ function hookResume(raw, genre, volume, { reactive = false, follow = false, musi
     // loop to put one under, so the pulse plays once on its own. Detached: the
     // agent waits on this hook.
     if (!music && !noChime) new AudioPlayer().stop({ playChime: true, outcome: "stuck", volume, chimeVolume, detach: true });
+    speakEvent(raw, "stuck", listSessions().length, {
+      chimed: !music && !noChime && !playbackDisabled(),
+      volume: chimeVolume !== null ? chimeVolume : volume
+    });
   }
 
   // An empty key is a wait that named nothing (a Notification): the next tool
@@ -1671,6 +1725,7 @@ module.exports = {
   qwenHome,
   grokHome,
   announce,
+  announceEnabled,
   recentEvents,
   emitEvent,
   ANNOUNCE_OUTCOMES,

package/src/interactive.js

@@ -3,15 +3,36 @@
  * Zero dependencies - Pure Node.js ANSI and Readline
  */
 
-const { spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
 const readline = require("readline");
 
-// Windows has no `which`; without this every tool shows as missing there.
-const LOOKUP_CMD = process.platform === "win32" ? "where" : "which";
-
-function isInstalled(cmd) {
-  // An argument vector, not a command string: nothing in `cmd` reaches a shell.
-  return spawnSync(LOOKUP_CMD, [cmd], { stdio: "ignore", timeout: 3000, killSignal: "SIGKILL" }).status === 0;
+/**
+ * Is `cmd` an executable on PATH? Read off the filesystem, not by asking
+ * `which`/`where`: a lookup is a process spawn, and on CI runners that spawn
+ * has hung and missed its timeout (#58), where a directory scan cannot. It
+ * also needs no `which` to exist, and nothing in `cmd` reaches a shell.
+ * A name with a separator is a path, as `which` treats it.
+ */
+function isInstalled(cmd, env = process.env) {
+  if (typeof cmd !== "string" || !cmd) return false;
+  const win = process.platform === "win32";
+  const exts = win ? String(env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean) : [""];
+  const dirs = /[\\/]/.test(cmd) ? [""] : String(env.PATH ?? env.Path ?? "").split(path.delimiter).filter(Boolean);
+  const hasExt = win && exts.some((e) => cmd.toLowerCase().endsWith(e.toLowerCase()));
+  for (const dir of dirs) {
+    for (const ext of hasExt ? ["", ...exts] : exts) {
+      const file = path.join(dir, cmd + ext);
+      try {
+        if (!fs.statSync(file).isFile()) continue;
+        if (!win) fs.accessSync(file, fs.constants.X_OK);
+        return true;
+      } catch (e) {
+        // Not here, or not executable: keep looking.
+      }
+    }
+  }
+  return false;
 }
 
 // Convenience only - the wrapper runs any command, and "Custom command..."
@@ -35,7 +56,8 @@ const AI_TOOLS = [
   { name: "Antigravity CLI", cmd: ["agy"], check: "agy", hookTarget: "antigravity" },
   { name: "Aider", cmd: ["aider"], check: "aider" },
   { name: "Ollama (Llama 3)", cmd: ["ollama", "run", "llama3"], check: "ollama" },
-  { name: "Custom command...", cmd: null }
+  { name: "Custom command...", cmd: null },
+  { name: "⚙️  Alerts & extras...", cmd: null, settings: true }
 ];
 
 const GENRES = [
@@ -263,7 +285,7 @@ const DELIVERY_FRESH = [
   {
     id: "hooks",
     name: "Agent hooks",
-    desc: "Music follows the agent's thinking. Set once, no wrapper needed"
+    desc: "Music follows the agent's thinking. Installs, then returns to your shell: nothing starts"
   },
   {
     id: "wrapper",
@@ -285,7 +307,7 @@ const DELIVERY_INSTALLED = [
   {
     id: "hooks",
     name: "Reconfigure the hooks",
-    desc: "Pick a new genre, volume or reactive setting"
+    desc: "Pick a new genre, volume or reactive setting. Nothing starts"
   }
 ];
 
@@ -294,6 +316,64 @@ const REACTIVE = [
   { id: true, name: "Reactive", desc: "Intensity follows the tool in use - noticeable, by design" }
 ];
 
+const NEXT_SPEAK = { off: "auto", auto: "always", always: "off" };
+
+/**
+ * The saved toggles that have no flag a person would think to look for:
+ * banners, the spoken line, `vibe --announce`, music and the mute. One screen,
+ * not a question per setting in the setup flow, which runs every time a tool
+ * is picked. Enter flips the highlighted one and the list comes back with its
+ * new value; every change is saved at once and lands on the next prompt, like
+ * `vibe --genre`. A variable set in this shell outranks the saved value, so the
+ * row says so rather than letting the toggle look dead.
+ */
+async function promptSettings() {
+  const { loadConfig, saveConfig, muteState, setMuted, musicEnabled, DEFAULT_MUTE_MINUTES } = require("./player");
+  const hooks = require("./hooks");
+  const speech = require("./speech");
+
+  for (;;) {
+    const config = loadConfig();
+    const pinned = (name) => (process.env[name] !== undefined ? ` (${name} is set in this shell and wins)` : "");
+    const speak = speech.speakMode(process.env, config);
+    const items = [
+      { id: "notify", name: "Desktop banners", value: hooks.notifyEnabled(process.env, config) ? "on" : "off",
+        desc: `name the project when a turn finishes or needs you${pinned("VIBE_NOTIFY")}` },
+      { id: "speak", name: "Spoken announcements", value: speak,
+        desc: `a voice names the project after the chime: off, auto (two or more sessions) or always${pinned("VIBE_SPEAK")}${speak !== "off" && !speech.voiceAvailable() ? " - no voice found on this machine" : ""}` },
+      { id: "announce", name: "vibe --announce", value: hooks.announceEnabled(process.env, config) ? "on" : "off",
+        desc: `the chime for CI runs and scripts${pinned("VIBE_ANNOUNCE")}` },
+      { id: "music", name: "Music", value: musicEnabled() ? "on" : "off",
+        desc: `off keeps the chimes, banners and events, and drops the music${pinned("VIBE_MUSIC")}` },
+      { id: "mute", name: "Mute", value: muteState() !== null ? "on" : "off",
+        desc: `silence everything for ${DEFAULT_MUTE_MINUTES} minutes (vibe --unmute ends it)` },
+      { id: "done", name: "Done", value: "", desc: "" }
+    ];
+
+    const chosen = await selectMenu(
+      "Alerts & extras  \x1b[0m\x1b[90m(Enter flips the highlighted one)\x1b[0m",
+      items,
+      (item, num) => item.id === "done"
+        ? `${num}. ${item.name}`
+        : `${num}. ${item.name}: ${item.value === "off" ? "\x1b[33moff\x1b[0m" : `\x1b[32m${item.value}\x1b[0m`} \x1b[90m— ${item.desc}\x1b[0m`
+    );
+
+    if (chosen.id === "done") break;
+    if (chosen.id === "notify") saveConfig({ notify: chosen.value !== "on" });
+    else if (chosen.id === "speak") saveConfig({ speak: NEXT_SPEAK[chosen.value] });
+    else if (chosen.id === "announce") saveConfig({ announce: chosen.value !== "on" });
+    else if (chosen.id === "music") saveConfig({ music: chosen.value !== "on" });
+    else if (chosen.id === "mute") {
+      if (chosen.value === "on") setMuted(false);
+      else {
+        setMuted(true, DEFAULT_MUTE_MINUTES);
+        hooks.stopDaemon({ keepSessions: true }); // silence what is playing now, not just the next prompt
+      }
+    }
+  }
+  console.log("\n\x1b[32m✔ Saved.\x1b[0m Changes apply from your next prompt. Nothing was started.\n");
+}
+
 /**
  * `hooksInstalledFor` is asked about the tool the user picked, not about
  * Claude: the caller cannot know which tool that is until this menu runs, and
@@ -323,6 +403,11 @@ async function promptInteractive({ hooksInstalledFor = () => false } = {}) {
     }
   );
 
+  if (selectedTool.settings) {
+    await promptSettings();
+    return { settings: true };
+  }
+
   let finalCmd = selectedTool.cmd;
   if (!finalCmd) {
     finalCmd = await promptCustomCommand();
@@ -387,4 +472,4 @@ async function promptInteractive({ hooksInstalledFor = () => false } = {}) {
   };
 }
 
-module.exports = { promptInteractive, tokenizeCommand, isInstalled, hookTargetOf, playPreview, stopPreview, AI_TOOLS };
+module.exports = { promptInteractive, promptSettings, tokenizeCommand, isInstalled, hookTargetOf, playPreview, stopPreview, AI_TOOLS };

package/src/speech.js

@@ -0,0 +1,260 @@
+/**
+ * Spoken announcements (#33): the sentence after the chime that says *which*
+ * project finished, failed or needs you. A chime says that something happened
+ * and leaves you alt-tabbing to find out what.
+ *
+ * Opt-in (`--speak`, `speak` in config.json, `VIBE_SPEAK`). Three modes:
+ * `auto` speaks only when two or more sessions are going - the one case where
+ * the chime cannot answer "which one?"; with a single session the sentence
+ * would repeat what the chime already said. `always` speaks every time.
+ *
+ * The voice is the operating system's own (`say`, `spd-say` / `espeak`,
+ * `System.Speech`), so nothing is installed and nothing leaves the machine.
+ * The words are fixed: a project name and a state, never the agent's output.
+ * The project name is user-controlled text, so it travels as argv (or an
+ * environment variable on Windows), never spliced into a shell or a script.
+ *
+ * Speech runs in a detached process of its own (`node speech.js --run ...`):
+ * the agent waits on the hook, and the sentence has to start after the chime,
+ * not on top of it. That process takes a lock for the length of the sentence,
+ * so sessions that finish together speak one after another, not over each
+ * other. Merging them into one sentence is not done.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawn } = require("child_process");
+
+const STATE_DIR = path.join(os.homedir(), ".vibeaudio");
+const LOCK_FILE = path.join(STATE_DIR, "speech.lock");
+const LAST_FILE = path.join(STATE_DIR, "speech.json");
+
+const SPEECH_MAX_CHARS = 200;
+const REPEAT_MS = 5000; // the same sentence inside this window is dropped
+const LOCK_STALE_MS = 30000; // a holder this old died without releasing
+const LOCK_WAIT_MS = 20000; // a queue this long is not worth joining
+const SPEAK_TIMEOUT_MS = 15000; // a voice that hangs is killed
+
+// How long each chime plays, plus a breath: the sentence starts after it.
+const CHIME_MS = { success: 1600, failure: 1800, attention: 1300, stuck: 1800 };
+const CHIME_GAP_MS = 150;
+
+const MODES = ["off", "auto", "always"];
+
+function parseMode(value) {
+  const raw = String(value ?? "").trim().toLowerCase();
+  if (raw === "always") return "always";
+  if (["1", "true", "on", "yes", "auto"].includes(raw)) return "auto";
+  return "off";
+}
+
+/** Env beats the saved setting, like every other one. */
+function speakMode(env = process.env, config = {}) {
+  return parseMode(env.VIBE_SPEAK ?? config.speak);
+}
+
+/** Whether to speak now: `auto` needs two or more sessions to be worth it. */
+function shouldSpeak(mode, sessionCount) {
+  return mode === "always" || (mode === "auto" && sessionCount >= 2);
+}
+
+/**
+ * Text that is safe to hand a voice: no control characters, and no embedded
+ * speech commands. macOS `say` reads `[[volm 0]]` and its kin out of the text,
+ * so a project directory called that would otherwise steer the voice.
+ */
+function cleanText(text, max = SPEECH_MAX_CHARS) {
+  let out = String(text).replace(/[\u0000-\u001f\u007f]+/g, " ");
+  while (/\[\[[^\]]*\]\]/.test(out)) out = out.replace(/\[\[[^\]]*\]\]/g, " ");
+  out = out.replace(/\[\[|\]\]/g, " "); // what nesting left behind
+  return out.replace(/\s+/g, " ").trim().slice(0, max);
+}
+
+/** "my-app_v2" reads better as "my app v2" than as "my dash app underscore v2". */
+function speakableLabel(label) {
+  return cleanText(String(label).replace(/[-_.]+/g, " "), 60) || "a session";
+}
+
+/**
+ * The fixed sentences. `tool` is only passed for a built-in tool name: an MCP
+ * tool's name is third-party text, and the line never speaks it.
+ */
+function phrase(kind, label, tool = "") {
+  const who = speakableLabel(label);
+  const what = cleanText(String(tool).replace(/_/g, " "), 40);
+  switch (kind) {
+    case "failure": return `${who}: failed.`;
+    case "attention": return what ? `${who} needs you: ${what}.` : `${who} needs you.`;
+    case "stuck": return `${who} looks stuck.`;
+    default: return `${who}: done.`;
+  }
+}
+
+const POWERSHELL_SCRIPT =
+  "Add-Type -AssemblyName System.Speech; " +
+  "$s = New-Object System.Speech.Synthesis.SpeechSynthesizer; " +
+  "$s.Volume = [int]$env:VIBE_SPEECH_VOLUME; " +
+  "$s.Speak($env:VIBE_SPEECH_TEXT)";
+
+/**
+ * The command that speaks `text`, or null where this machine has no voice.
+ * `volume` is VibeAudio's 0-1 setting where the voice has a way to take it:
+ * macOS `say` follows the system volume unless told otherwise, and `spd-say`
+ * has no usable scale, so it speaks at its own level.
+ */
+function voiceCommand(platform, text, volume = 0.4, has = () => false) {
+  const v = Math.max(0.05, Math.min(1, Number(volume) || 0.4));
+  if (platform === "darwin") {
+    return has("say") ? { cmd: "say", args: ["--", `[[volm ${v.toFixed(2)}]] ${text}`] } : null;
+  }
+  if (platform === "win32") {
+    return {
+      cmd: "powershell.exe",
+      args: ["-NoProfile", "-NonInteractive", "-Command", POWERSHELL_SCRIPT],
+      env: { VIBE_SPEECH_TEXT: text, VIBE_SPEECH_VOLUME: String(Math.round(v * 100)) }
+    };
+  }
+  if (has("spd-say")) return { cmd: "spd-say", args: ["-w", "--", text] };
+  for (const cmd of ["espeak-ng", "espeak"]) {
+    if (has(cmd)) return { cmd, args: ["-a", String(Math.round(v * 200)), "--", text] };
+  }
+  return null;
+}
+
+function currentVoice(text, volume) {
+  const { isInstalled } = require("./interactive");
+  return voiceCommand(process.platform, text, volume, isInstalled);
+}
+
+/** `--doctor`: is there anything to speak with here? */
+function voiceAvailable() {
+  return currentVoice("test", 0.4) !== null;
+}
+
+/**
+ * Hand a sentence to a detached process that waits `delayMs` (for the chime),
+ * takes its turn on the lock, and speaks. Returns false when nothing was
+ * started. Never throws and never waits: the caller is a hook.
+ */
+function speak(text, { delayMs = 0, volume = 0.4 } = {}) {
+  try {
+    const { playbackDisabled } = require("./player");
+    if (playbackDisabled()) return false; // a mute means quiet, speech included
+    const clean = cleanText(text);
+    if (!clean || !currentVoice(clean, volume)) return false;
+    const child = spawn(process.execPath, [__filename, "--run", String(Math.max(0, Math.round(delayMs))), String(volume), clean], {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/** How long to wait so a sentence starts after the chime that was just played. */
+function chimeDelayMs(outcome, played = true) {
+  return played ? (CHIME_MS[outcome] || CHIME_MS.success) + CHIME_GAP_MS : 0;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+
+/** One speaker at a time across processes: exclusive create, with a stale check. */
+async function acquireLock(waitMs = LOCK_WAIT_MS) {
+  fs.mkdirSync(STATE_DIR, { recursive: true });
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    try {
+      fs.writeFileSync(LOCK_FILE, JSON.stringify({ pid: process.pid, at: Date.now() }), { flag: "wx" });
+      return () => fs.rmSync(LOCK_FILE, { force: true });
+    } catch (e) {
+      if (e.code !== "EEXIST") return null;
+    }
+    try {
+      const held = JSON.parse(fs.readFileSync(LOCK_FILE, "utf8"));
+      if (Date.now() - held.at > LOCK_STALE_MS || !pidAlive(held.pid)) fs.rmSync(LOCK_FILE, { force: true });
+    } catch (e) {
+      // Unreadable (being written, or just removed): look again.
+    }
+    if (Date.now() > deadline) return null;
+    await sleep(100);
+  }
+}
+
+function speakNow(text, volume) {
+  return new Promise((resolve) => {
+    const voice = currentVoice(text, volume);
+    if (!voice) return resolve(false);
+    let done = false;
+    const finish = (ok) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve(ok);
+    };
+    let child;
+    try {
+      child = spawn(voice.cmd, voice.args, { stdio: "ignore", env: { ...process.env, ...(voice.env || {}) } });
+    } catch (e) {
+      return resolve(false);
+    }
+    const timer = setTimeout(() => {
+      try { child.kill("SIGKILL"); } catch (e) { /* gone already */ }
+      finish(false);
+    }, SPEAK_TIMEOUT_MS);
+    child.on("error", () => finish(false));
+    child.on("close", (code) => finish(code === 0));
+  });
+}
+
+/** The body of the detached process. */
+async function run(delayMs, volume, text) {
+  const { playbackDisabled } = require("./player");
+  await sleep(delayMs);
+  const release = await acquireLock();
+  if (!release) return; // could not get a turn: drop it rather than talk over someone
+  try {
+    if (playbackDisabled()) return; // muted while it waited
+    try {
+      const last = JSON.parse(fs.readFileSync(LAST_FILE, "utf8"));
+      if (last.text === text && Date.now() - last.at < REPEAT_MS) return;
+    } catch (e) { /* first one, or unreadable: nothing to compare */ }
+    fs.writeFileSync(LAST_FILE, JSON.stringify({ text, at: Date.now() }));
+    await speakNow(text, volume);
+  } finally {
+    release();
+  }
+}
+
+if (require.main === module && process.argv[2] === "--run") {
+  run(Number(process.argv[3]) || 0, Number(process.argv[4]) || 0.4, String(process.argv[5] || ""))
+    .catch(() => {})
+    .finally(() => process.exit(0));
+}
+
+module.exports = {
+  MODES,
+  speakMode,
+  shouldSpeak,
+  cleanText,
+  phrase,
+  voiceCommand,
+  voiceAvailable,
+  speak,
+  chimeDelayMs,
+  acquireLock,
+  LOCK_FILE,
+  LAST_FILE,
+  SPEECH_MAX_CHARS
+};