vibeaudio 0.9.0 → 0.11.0

package/README.md

@@ -4,7 +4,7 @@
 
 > **Procedural focus music while your AI coding tools think.**
 > Every project gets its own arrangement. Zero dependencies, zero audio files.
-> Works with Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI, Qwen Code, Aider — and any terminal command.
+> Works with Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI, Qwen Code, Windsurf, Aider — and any terminal command.
 
 **[Install](#-install)** · **[Agent hooks](#-agent-hooks-no-wrapper-needed)** · **[Genres](#-music-genres)** · **[Flags](#-options--flags)** · **[Troubleshooting](#-troubleshooting)** · **[Uninstall](#-uninstall)**
 
@@ -27,7 +27,7 @@ AI coding agents take 15–45 seconds to reason, read files and write code. Star
 * 🎛️ **Music that follows the work** ([reactive mode](#reactive-mode-opt-in), opt-in). Calm while the agent reads, fuller while it edits, busiest when it runs commands or hands work to sub-agents — you can hear *what* it's doing, not just for how long.
 * 🔔 **Outcome-aware chimes.** Ascending on success, a soft descending minor chord on failure, and **silence on `Ctrl+C`** — an abort is never reported as done.
 * ✋ **A "your turn" chime.** When Claude Code stops to ask permission (or an MCP server asks for input), the music pauses and a rising two-note chime asks for you; it picks back up once you've answered.
-* 🔌 **Universal drop-in.** Hooks for **Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI and Qwen Code**; MCP for **Claude Desktop and Antigravity**; the wrapper (`vibe <command>`) for anything else.
+* 🔌 **Universal drop-in.** Hooks for **Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI, Qwen Code and Windsurf**; MCP for **Claude Desktop and Antigravity**; the wrapper (`vibe <command>`) for anything else.
 
 <details>
 <summary><b>And the quieter four</b> — silence on fast commands, several sessions at once, exit codes, the HUD</summary>
@@ -223,7 +223,7 @@ Adding an entry to the launcher is one line in [`src/interactive.js`](src/intera
 
 ## 🪝 Agent Hooks (no wrapper needed)
 
-> **`--install-hooks` supports Claude Code, Codex, Cursor, Grok, Gemini CLI, GitHub Copilot CLI and Qwen Code.** Everything else uses the [wrapper or MCP](#-everything-else-claude-desktop-antigravity-via-mcp) instead.
+> **`--install-hooks` supports Claude Code, Codex, Cursor, Grok, Gemini CLI, GitHub Copilot CLI, Qwen Code and Windsurf.** Everything else uses the [wrapper or MCP](#-everything-else-claude-desktop-antigravity-via-mcp) instead.
 
 Wrapping (`vibe claude`) infers "the AI is thinking" from how long the process runs. Hooks know for certain — so music starts the moment you submit a prompt and stops the moment the agent finishes, with no grace-window guessing and no aliases.
 
@@ -236,12 +236,12 @@ vibe --genre jazz --volume 25 --install-hooks    # install, and save these as yo
 vibe --install-hooks --dry-run                   # show what would change, write nothing
 ```
 
-**It auto-detects.** With no `--tools`, VibeAudio wires up each supported agent it finds on your machine — one counts as present when its config directory exists or its CLI is on your `PATH`. `--tools claude,codex,cursor,grok,gemini,copilot,qwen` overrides that. Add `--dry-run` to see, per event, what would be added or changed in each file before anything is written.
+**It auto-detects.** With no `--tools`, VibeAudio wires up each supported agent it finds on your machine — one counts as present when its config directory exists or its CLI is on your `PATH`. `--tools claude,codex,cursor,grok,gemini,copilot,qwen,windsurf` overrides that. Add `--dry-run` to see, per event, what would be added or changed in each file before anything is written.
 
 That's it — run your agent normally, with no `vibe` prefix.
 
 <details>
-<summary><b>Which file and which events, per agent</b> — seven dialects, all written for you</summary>
+<summary><b>Which file and which events, per agent</b> — eight dialects, all written for you</summary>
 
 Each tool spells its events its own way, and VibeAudio writes whichever dialect the file expects:
 
@@ -254,6 +254,7 @@ Each tool spells its events its own way, and VibeAudio writes whichever dialect
 | **Gemini CLI** | `~/.gemini/settings.json` | `BeforeAgent` | `AfterAgent` | `BeforeTool` |
 | **Copilot CLI** | `~/.copilot/hooks/vibeaudio.json` | `UserPromptSubmit` | `Stop` | `PreToolUse` |
 | **Qwen Code** | `~/.qwen/settings.json` | `UserPromptSubmit` | `Stop` | `PreToolUse` |
+| **Windsurf** | `~/.codeium/windsurf/hooks.json` | `pre_user_prompt` | `post_cascade_response` | `pre_run_command` |
 
 Where an agent reports more than start and stop, VibeAudio listens for that too — and only where the event was confirmed against the tool itself:
 
@@ -264,7 +265,7 @@ Where an agent reports more than start and stop, VibeAudio listens for that too
 | **Gemini CLI** | `Notification` (tool permission) | `AfterTool` | — | `SessionEnd` |
 | **Copilot CLI** | `Notification` (permission prompt) | `PostToolUse`, `PostToolUseFailure` | — | `SessionEnd` |
 | **Qwen Code** | `PermissionRequest` | `PostToolUse`, `PostToolUseFailure` | `StopFailure` | `SessionEnd` |
-| **Cursor, Grok** | — | — | — | — |
+| **Cursor, Grok, Windsurf** | — | — | — | — |
 
 </details>
 
@@ -302,7 +303,7 @@ Sessions with no id in their payload share a single slot, so they behave as one.
 
 </details>
 
-> **No restart needed, even mid-session — for Claude Code, Codex, Cursor and Grok.** Each re-reads its hook file every time a hook fires, so changes land on your **next prompt**. A daemon already playing keeps its old settings until that prompt replaces it — at most the tail of one turn. Whether an open Gemini CLI, Copilot CLI or Qwen Code session does the same hasn't been checked, so start a new session there to be sure.
+> **No restart needed, even mid-session — for Claude Code, Codex, Cursor and Grok.** Each re-reads its hook file every time a hook fires, so changes land on your **next prompt**. A daemon already playing keeps its old settings until that prompt replaces it — at most the tail of one turn. Whether an open Gemini CLI, Copilot CLI, Qwen Code or Windsurf session does the same hasn't been checked, so start a new session there to be sure.
 
 > **The Claude Code desktop app is covered too**, not just the terminal — both read the same `~/.claude/settings.json`. (The separate **Claude Desktop** chat app is a different product with no hooks; that one needs [MCP](#-everything-else-claude-desktop-antigravity-via-mcp).)
 
@@ -357,6 +358,23 @@ Removing them is one command:
 vibe --uninstall-hooks
 ```
 
+### Know where your time goes: `vibe --report`
+
+Hooks log each finished turn — which project, how long, how it ended, and how much of it the agent spent blocked on a dialog of yours — to `~/.vibeaudio/history.jsonl`. `vibe --report` (or `--report 30`) totals it:
+
+```
+  Turns             30  3 failed
+  You waited        3h 55m  on agents, 7m 51s per turn
+  Agents waited     5m 35s  on you — permission dialogs and questions
+  Typical turn      2m 57s  median
+```
+
+plus where the time went by project and, for windows up to two weeks, by day. "You waited" is the agent's own working time; the time it spent blocked on you is shown separately, because they are different problems. The log stays on your machine, never leaves it, is capped at about 1 MB, and `VIBE_NO_HISTORY=1` turns it off. Only hook-driven turns are logged — a command wrapped as `vibe <command>` is not, since its lifetime isn't the same thing as an agent's working time.
+
+### The chime is in the music's key
+
+The success chime is the tonic chord of whatever key your genre sits in — C major for lofi, 8bit, jazz and piano, D minor for synthwave and electronic, D major for zen, A minor for drone — so it lands as the resolution of the piece rather than a bell over it. `rain`, `ocean` and `random` have no single key to match and keep the original C major chime.
+
 ### Reactive mode (opt-in)
 
 ```bash
@@ -392,9 +410,9 @@ Changes land at the next loop boundary, so it shifts musically rather than cutti
 
 ## 🖥️ Everything Else (Claude Desktop, Antigravity… 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) and [Qwen Code](https://github.com/QwenLM/qwen-code) have hook systems, and `--install-hooks` writes to all seven** — 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.
+**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) and [Windsurf](https://docs.devin.ai/desktop/cascade/hooks) have hook systems, and `--install-hooks` writes to all eight** — 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.
 
-> **This is weaker than hooks, by nature.** Hooks fire on an event; MCP tools are *model-invoked*, so the assistant has to decide to call `vibe_play` and remember `vibe_stop`. Expect the occasional silent turn — say "play some focus music while you work on this" if you want it reliably. **On any of the seven agents above, use [hooks](#-agent-hooks-no-wrapper-needed) instead.**
+> **This is weaker than hooks, by nature.** Hooks fire on an event; MCP tools are *model-invoked*, so the assistant has to decide to call `vibe_play` and remember `vibe_stop`. Expect the occasional silent turn — say "play some focus music while you work on this" if you want it reliably. **On any of the eight agents above, use [hooks](#-agent-hooks-no-wrapper-needed) instead.**
 
 Use an **absolute path**, not the bare `vibe` command: GUI apps launched from Finder don't inherit your shell's `PATH`, and version managers like `fnm` or `nvm` put `vibe` on a per-shell path that won't resolve. Print yours with:
 
@@ -567,13 +585,14 @@ 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 |
+| `--report [days]` | How long you waited on agents, and on which projects, from the local turn log | `7` days |
 | `--stop` | Stop the background player, then exit | — |
 | `--mute [minutes]` | Silence everything for a call, then exit | `60` min (`0` = until unmuted) |
 | `--unmute` | Resume normal playback, then exit | — |
 | `--clear-cache` | Delete all cached audio, then exit | — |
 | `--mcp` | Run as an MCP stdio server for desktop apps | — |
 | `--install-hooks` | Wire music into your agent's hooks (no wrapper needed) | — |
-| `--tools <list>` | With `--install-hooks`: `claude,codex,cursor,grok,gemini,copilot,qwen` | auto-detect |
+| `--tools <list>` | With `--install-hooks`: `claude,codex,cursor,grok,gemini,copilot,qwen,windsurf` | auto-detect |
 | `--reactive` | With `--install-hooks`: intensity follows the tool in use | off |
 | `--dry-run` | With `--install-hooks`: show what would change in each file, write nothing | off |
 | `--uninstall-hooks` | Remove the hooks again, from every agent | — |
@@ -592,7 +611,9 @@ export VIBE_GRACE_MS=3000       # Wait 3s of thinking before any music
 export VIBE_SEED=7              # Same arrangement everywhere, ignoring the directory
 export VIBE_DISABLE=1           # Mute, without uninstalling anything
 export VIBE_NOTIFY=1            # Desktop banner naming the project, 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
 ```
 
 **`VIBE_DISABLE=1` is for a shell you always want quiet** — a CI job, a shared machine, a terminal profile you keep silent. It's read at playback time and covers hooks, wrapper and MCP alike.
@@ -624,6 +645,9 @@ The expiry is deliberate too. A call is a bounded thing; a mute you forget about
 **No sound at all**
 Check that a player exists for your platform (see [Requirements](#-requirements)). VibeAudio prints a notice to stderr when it can't find one. On Linux: `sudo apt install pulseaudio-utils` (or `ffmpeg` / `alsa-utils`).
 
+**Silent after connecting a monitor or headphones (macOS)**
+`afplay` plays on macOS's *default output device*, which moves when a display or headphones connect. A monitor often has no system volume control at all and speakers much quieter than the laptop's, so a quiet setting — a sparse genre like `piano` at 25% — can fall below what you can hear. `vibe --doctor` shows where sound is going and warns if that output is muted or has no volume control. Then try `vibe --genre lofi --volume 60` for one prompt, and check the monitor's own speaker volume.
+
 **Music starts immediately instead of after the grace window**
 It usually is waiting — your AI tool's own startup (auth, session load) just takes longer than 1.5s, so music and the tool's first output appear together. Raise the window: `vibe --grace 3000 claude`.
 
@@ -716,7 +740,7 @@ rm -rf ~/.vibeaudio             # 3. optional: cached audio, saved settings, dae
 
 Step 1 also **stops a background player that's still going**. That matters: once the hooks are gone nothing will ever send the `Stop` event, and after step 2 there's no `vibe` left to stop it with — music would simply play on until its 15-minute cap. If you ever need to do it by hand: `pkill -f "vibeaudio.js --daemon"`.
 
-> **Order matters.** `npm rm -g` deletes the binary but not your hook config. Removing the package first strands hook entries that point at a path that no longer exists, and your agent will run a failing hook on every prompt. If you already did it in the wrong order, reinstall, run `vibe --uninstall-hooks`, then remove again — or delete the `vibeaudio` entries from `~/.claude/settings.json`, `~/.codex/hooks.json`, `~/.cursor/hooks.json`, `~/.gemini/settings.json` and `~/.qwen/settings.json` by hand, and delete `~/.grok/hooks/vibeaudio.json`, `~/.copilot/hooks/vibeaudio.json` and `~/.claude/commands/vibe.md`.
+> **Order matters.** `npm rm -g` deletes the binary but not your hook config. Removing the package first strands hook entries that point at a path that no longer exists, and your agent will run a failing hook on every prompt. If you already did it in the wrong order, reinstall, run `vibe --uninstall-hooks`, then remove again — or delete the `vibeaudio` entries from `~/.claude/settings.json`, `~/.codex/hooks.json`, `~/.cursor/hooks.json`, `~/.gemini/settings.json`, `~/.qwen/settings.json` and `~/.codeium/windsurf/hooks.json` by hand, and delete `~/.grok/hooks/vibeaudio.json`, `~/.copilot/hooks/vibeaudio.json` and `~/.claude/commands/vibe.md`.
 
 Step 3 reclaims disk — the audio cache, pruned to the 3 most recent projects — and drops your saved genre and volume. Both come back on their own, so skip it if you're reinstalling.
 
@@ -724,7 +748,7 @@ Step 3 reclaims disk — the audio cache, pruned to the 3 most recent projects
 
 | Leftover | Why, and how to remove it |
 | :--- | :--- |
-| `*.vibeaudio.bak` next to each shared hook config | Your config as it was before the first install — one each for Claude Code, Codex, Cursor, Gemini CLI and Qwen Code. A safety net we won't delete for you; `rm` them once you're happy the real files are correct, and `vibe --uninstall-hooks` prints the path of every one it finds. (Grok and Copilot CLI leave nothing: their files are ours alone, so uninstall deletes them outright.) |
+| `*.vibeaudio.bak` next to each shared hook config | Your config as it was before the first install — one each for Claude Code, Codex, Cursor, Gemini CLI, Qwen Code and Windsurf. A safety net we won't delete for you; `rm` them once you're happy the real files are correct, and `vibe --uninstall-hooks` prints the path of every one it finds. (Grok and Copilot CLI leave nothing: their files are ours alone, so uninstall deletes them outright.) |
 | `vibeaudio` entries in other apps' MCP configs | VibeAudio never edits those files, so it can't clean them either. Drop the entry from [whichever config you added it to](#-everything-else-claude-desktop-antigravity-via-mcp). |
 
 Apart from those two, the three commands above remove everything VibeAudio writes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.9.0",
+  "version": "0.11.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

@@ -77,6 +77,7 @@ Procedural focus music while your AI coding tools think.
       --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)
+      --report [days]          How long you waited on agents, and where (default: 7 days)
       --doctor                 Check the setup; each problem comes with its fix (exit 1 if any)
       --stop                   Stop the background player, then exit
       --mute [minutes]         Silence everything for a call (default: 60 min, 0 = until unmuted)
@@ -84,7 +85,7 @@ Procedural focus music while your AI coding tools think.
       --clear-cache            Delete cached audio, then exit
       --mcp                    Run as Model Context Protocol (MCP) server for Desktop apps
       --install-hooks          Wire music into your agent's hooks (no wrapper needed)
-      --tools <list>           With --install-hooks: claude,codex,cursor,grok,gemini,copilot,qwen (auto-detect)
+      --tools <list>           With --install-hooks: claude,codex,cursor,grok,gemini,copilot,qwen,windsurf (auto-detect)
       --reactive               With --install-hooks: intensity follows the tool in use
       --dry-run                With --install-hooks: show what would change, write nothing
       --uninstall-hooks        Remove the hooks again, from every agent
@@ -175,6 +176,7 @@ function parseArgs(argv) {
   let statusFlag = false;
   let doctorFlag = false;
   let notifyFlag = null;
+  let reportDays = null;
   let stopFlag = false;
   let muteFlag = null;
   let muteMinutes = null;
@@ -285,6 +287,17 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--report") {
+      // Optional window in days, like --mute's minutes: `vibe --report 30`.
+      i += 1;
+      reportDays = 7;
+      if (args[i] !== undefined && /^\d+$/.test(args[i])) {
+        reportDays = Math.min(Math.max(parseInt(args[i], 10), 1), 365);
+        i += 1;
+      }
+      continue;
+    }
+
     if (arg === "--notify" || arg === "--no-notify") {
       notifyFlag = arg === "--notify";
       i += 1;
@@ -441,6 +454,7 @@ function parseArgs(argv) {
     status: statusFlag,
     doctor: doctorFlag,
     notify: notifyFlag,
+    report: reportDays,
     stop: stopFlag,
     mute: muteFlag,
     muteMinutes,
@@ -800,6 +814,24 @@ function doctorChecks() {
     add("ok", "Saved settings", "config.json parses (or none saved)");
   }
 
+  // afplay plays on the default output device, which moves when a monitor or
+  // headphones connect - and an external display often has no system volume at
+  // all, or speakers far quieter than the laptop's. Say where sound is going.
+  const out = require("./output").macOutput();
+  if (out) {
+    const where = out.device ? `${out.device.name}${out.device.transport ? ` (${out.device.transport})` : ""}` : "the default output";
+    if (out.muted) {
+      add("warn", "Sound output", `${where} is muted in macOS — nothing will be heard`, "unmute it in the menu bar, or: osascript -e 'set volume output muted false'");
+    } else if (out.volume === null) {
+      add("warn", "Sound output", `${where} has no system volume control, so VibeAudio's own volume is the only one — and its speakers may be quiet`,
+        "raise it with: vibe --volume 60 (and check the monitor's own speaker volume)");
+    } else if (out.volume < 10) {
+      add("warn", "Sound output", `${where}, system volume ${out.volume}%`, "raise the macOS volume");
+    } else {
+      add("ok", "Sound output", `${where}, system volume ${out.volume}%`);
+    }
+  }
+
   const detected = hooks.detectTargets();
   for (const id of Object.keys(hooks.TARGETS)) {
     const t = hooks.TARGETS[id];
@@ -870,6 +902,93 @@ function doctorChecks() {
   return checks;
 }
 
+/** 95 -> "1m 35s", 4_000_000 -> "1h 06m". */
+function formatDuration(ms) {
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${String(s % 60).padStart(2, "0")}s`;
+  return `${Math.floor(m / 60)}h ${String(m % 60).padStart(2, "0")}m`;
+}
+
+/**
+ * The summary of ~/.vibeaudio/history.jsonl. "You waited" is the agent's own
+ * working time - a turn's length minus the stretches it spent blocked on a
+ * dialog of yours - because the two are different complaints: one is the
+ * agent being slow, the other is you being away.
+ */
+function printReport(days, now = Date.now()) {
+  const { readTurns } = require("./history");
+  const turns = readTurns(days, now);
+  const dim = (s) => `\x1b[90m${s}\x1b[0m`;
+  const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+  console.log(`\n\x1b[1m\x1b[36mVibeAudio\x1b[0m report — last ${days === 1 ? "day" : `${days} days`}\n`);
+
+  if (!turns.length) {
+    console.log(`  No turns recorded yet.`);
+    console.log(dim(`  Turns are logged when your agent's hooks fire (vibe --install-hooks). A command wrapped as \`vibe <command>\` is not.`));
+    console.log(dim(`  The log stays on this machine; VIBE_NO_HISTORY=1 turns it off.`));
+    console.log();
+    return;
+  }
+
+  const working = (t) => t.ms - (t.blockedMs || 0);
+  const sum = (xs) => xs.reduce((a, b) => a + b, 0);
+  const sorted = turns.map((t) => t.ms).sort((a, b) => a - b);
+  const median = sorted[Math.floor(sorted.length / 2)];
+  const longest = turns.reduce((a, b) => (b.ms > a.ms ? b : a));
+  const failed = turns.filter((t) => t.outcome === "failure").length;
+  const waitedOnAgents = sum(turns.map(working));
+  const blocked = sum(turns.map((t) => t.blockedMs || 0));
+
+  // Two projects called `api` under different parents stay apart.
+  const names = new Map();
+  for (const t of turns) {
+    const parts = String(t.project || "?").split(/[\\/]/).filter(Boolean);
+    const clash = [...names.entries()].some(([p, n]) => p !== t.project && n === parts.slice(-1)[0]);
+    names.set(t.project, clash ? parts.slice(-2).join("/") : parts.slice(-1)[0] || "?");
+  }
+  const label = (t) => names.get(t.project);
+
+  const row = (k, v, extra = "") => console.log(`  ${k.padEnd(18)}${bold(v)}${extra ? dim(`  ${extra}`) : ""}`);
+  row("Turns", String(turns.length), failed ? `${failed} failed` : "");
+  row("You waited", formatDuration(waitedOnAgents), `on agents, ${formatDuration(waitedOnAgents / turns.length)} per turn`);
+  if (blocked >= 1000) row("Agents waited", formatDuration(blocked), "on you — permission dialogs and questions");
+  row("Typical turn", formatDuration(median), "median");
+  row("Longest turn", formatDuration(longest.ms), label(longest));
+
+  const byProject = new Map();
+  for (const t of turns) {
+    const p = byProject.get(label(t)) || { ms: 0, n: 0 };
+    p.ms += working(t);
+    p.n += 1;
+    byProject.set(label(t), p);
+  }
+  const top = [...byProject.entries()].sort((a, b) => b[1].ms - a[1].ms).slice(0, 5);
+  const widest = top[0][1].ms || 1;
+  console.log(`\n${bold("Where the time went")}`);
+  for (const [name, p] of top) {
+    console.log(`  ${name.slice(0, 18).padEnd(19)}${formatDuration(p.ms).padStart(8)}  ${"█".repeat(Math.max(1, Math.round((p.ms / widest) * 14))).padEnd(14)} ${dim(`${p.n} ${p.n === 1 ? "turn" : "turns"}`)}`);
+  }
+
+  if (days <= 14) {
+    console.log(`\n${bold("By day")}`);
+    const byDay = new Map();
+    for (const t of turns) {
+      const key = new Date(t.at).toLocaleDateString("en-CA");
+      byDay.set(key, (byDay.get(key) || 0) + working(t));
+    }
+    const maxDay = Math.max(...byDay.values()) || 1;
+    for (let d = days - 1; d >= 0; d--) {
+      const date = new Date(now - d * 86400000);
+      const ms = byDay.get(date.toLocaleDateString("en-CA")) || 0;
+      const name = `${date.toLocaleDateString("en-US", { weekday: "short" })} ${date.getDate()}`;
+      console.log(`  ${name.padEnd(8)}${(ms ? formatDuration(ms) : "—").padStart(8)}  ${"█".repeat(ms ? Math.max(1, Math.round((ms / maxDay) * 14)) : 0)}`);
+    }
+  }
+  console.log();
+}
+
 function printDoctor() {
   const mark = { ok: "\x1b[32m✔\x1b[0m", warn: "\x1b[33m!\x1b[0m", fail: "\x1b[31m✘\x1b[0m" };
   const checks = doctorChecks();
@@ -966,6 +1085,7 @@ function detectAiTools(hooked = new Set()) {
     { cmd: "gemini", name: "Gemini CLI", integration: viaHooks("gemini") },
     { cmd: "copilot", name: "GitHub Copilot CLI", integration: viaHooks("copilot") },
     { cmd: "qwen", name: "Qwen Code", integration: viaHooks("qwen") },
+    { cmd: "windsurf", name: "Windsurf", integration: viaHooks("windsurf") },
     { cmd: "aider", name: "Aider", integration: "wrapper — vibe aider" },
     { cmd: "ollama", name: "Ollama", integration: "wrapper — vibe ollama run <model>" }
   ];
@@ -1163,6 +1283,7 @@ function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive,
           volume,
           chimeVolume,
           noChime,
+          genre,
           raw
         });
       });
@@ -1355,6 +1476,7 @@ async function run() {
     status: showStatus,
     doctor: showDoctor,
     notify: notifyChange,
+    report: reportDays,
     stop: shouldStop,
     mute: muteChange,
     muteMinutes,
@@ -1442,6 +1564,10 @@ async function run() {
     return printDoctor();
   }
 
+  if (reportDays !== null) {
+    return printReport(reportDays);
+  }
+
   if (shouldClear) {
     console.log(`\x1b[32m[vibeaudio] Cleared cache at ${clearCache()}\x1b[0m`);
     return;

package/src/history.js

@@ -0,0 +1,57 @@
+/**
+ * A local log of finished turns - what `vibe --report` reads. One JSON object
+ * per line in ~/.vibeaudio/history.jsonl: when the turn ended, which project,
+ * how long it took, how much of that the agent spent blocked on you, and how
+ * it ended. It never leaves the machine; VIBE_NO_HISTORY=1 turns it off.
+ */
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const HISTORY_FILE = path.join(os.homedir(), ".vibeaudio", "history.jsonl");
+const MAX_BYTES = 1024 * 1024;
+const KEEP_LINES = 4000;
+
+/** Appends one turn. Never throws: a log is not worth failing a hook over. */
+function recordTurn({ project, ms, blockedMs = 0, outcome = "success", at = Date.now() }, file = HISTORY_FILE) {
+  if (process.env.VIBE_NO_HISTORY) return false;
+  if (!Number.isFinite(ms) || ms < 0) return false;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify({ at, project, ms, blockedMs: Math.min(Math.max(blockedMs, 0), ms), outcome })}\n`);
+    // Bounded, so a year of use is still a small file. Rewritten rarely, from
+    // the tail, so the newest turns are always the ones kept.
+    if (fs.statSync(file).size > MAX_BYTES) {
+      const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+      const tmp = `${file}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, `${lines.slice(-KEEP_LINES).join("\n")}\n`);
+      fs.renameSync(tmp, file);
+    }
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/** Turns that ended within the last `days` days. A line that does not parse is skipped, not fatal. */
+function readTurns(days, now = Date.now(), file = HISTORY_FILE) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch (e) {
+    return [];
+  }
+  const since = now - days * 86400000;
+  const turns = [];
+  for (const line of raw.split("\n")) {
+    if (!line) continue;
+    try {
+      const t = JSON.parse(line);
+      if (t && Number.isFinite(t.at) && Number.isFinite(t.ms) && t.at >= since) turns.push(t);
+    } catch (e) { /* a torn or hand-edited line */ }
+  }
+  return turns;
+}
+
+module.exports = { HISTORY_FILE, recordTurn, readTurns };

package/src/hooks.js

@@ -16,6 +16,7 @@ const os = require("os");
 const path = require("path");
 const { spawn, execFileSync } = require("child_process");
 const { AudioPlayer, loadConfig, playbackDisabled } = require("./player");
+const { recordTurn } = require("./history");
 
 const STATE_DIR = path.join(os.homedir(), ".vibeaudio");
 const PID_FILE = path.join(STATE_DIR, "daemon.pid");
@@ -99,7 +100,14 @@ function payloadToolName(raw) {
   const payload = parsePayload(raw);
   // Claude Code, Codex and Cursor send tool_name; Grok sends toolName.
   // Reading only one of them would silently pin that agent to tier 2.
-  return String(payload.tool_name || payload.toolName || "");
+  // Windsurf names no tool: the event is the signal, and only the shell one is wired.
+  const byEvent = payload.agent_action_name === "pre_run_command" ? "Shell" : "";
+  return String(payload.tool_name || payload.toolName || byEvent);
+}
+
+// Windsurf calls the conversation `trajectory_id`.
+function payloadSession(payload) {
+  return payload.session_id || payload.trajectory_id;
 }
 
 /**
@@ -291,6 +299,24 @@ const TARGETS = {
     // Unlike the four above, not verified to re-read hooks mid-session.
     liveReload: false,
     note: "Not checked whether an open Qwen Code session reloads hooks — start a new one to be sure."
+  },
+  windsurf: {
+    name: "Windsurf",
+    cmd: "windsurf",
+    // Checked against Windsurf's hooks documentation only: it was not installed
+    // here, so nothing was run. User-level file, a flat {command} entry with no
+    // timeout field, and the conversation named `trajectory_id` rather than
+    // session_id. post_cascade_response is the end-of-reply event; Windsurf has
+    // no permission-dialog, failure or session-end event, so none is wired, and
+    // its pre-tool events are per kind - pre_run_command is the one reactive
+    // mode listens to.
+    file: () => path.join(os.homedir(), ".codeium", "windsurf", "hooks.json"),
+    events: { start: "pre_user_prompt", stop: "post_cascade_response", tool: "pre_run_command" },
+    entry: (command) => ({ command }),
+    commands: (entry) => (entry.command ? [entry.command] : []),
+    seed: () => ({}),
+    liveReload: false,
+    note: "Windsurf's hooks do not load in Restricted Mode, and whether an open session reloads them is not documented — start a new one to be sure."
   }
 };
 
@@ -424,7 +450,7 @@ function fileSize(file) {
 function newTurn(raw) {
   const payload = parsePayload(raw);
   const transcript = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
-  return { session: String(payload.session_id || ""), transcript, offset: transcript ? fileSize(transcript) : 0 };
+  return { session: String(payloadSession(payload) || ""), transcript, offset: transcript ? fileSize(transcript) : 0 };
 }
 
 // The id ends up in a file name.
@@ -484,11 +510,16 @@ const working = (sessions) => sessions.filter((s) => s.waiting == null);
 // Claude Code's entry for Esc / the stop button: a user message whose text is
 // "[Request interrupted by user]" or "... for tool use]".
 const INTERRUPT_MARK = "[Request interrupted by user";
+const BLOCKED_MARK = "UserPromptSubmit operation blocked by hook";
 
 function isInterruptEntry(line) {
-  if (!line.includes(INTERRUPT_MARK)) return false; // Cheap filter before parsing.
+  if (!line.includes(INTERRUPT_MARK) && !line.includes(BLOCKED_MARK)) return false; // Cheap filter before parsing.
   try {
     const entry = JSON.parse(line);
+    // A prompt another hook blocked: hooks run side by side, so ours had already
+    // started the music, and no Stop will ever follow. The turn is over before
+    // it began, which is the same silent end as an interrupt.
+    if (entry.type === "system" && typeof entry.content === "string") return entry.content.startsWith(BLOCKED_MARK);
     if (entry.type !== "user" || !entry.message) return false;
     // Structural, not substring: a transcript that merely quotes the phrase -
     // in a tool result, a file, a prompt about this very feature - is not one.
@@ -624,7 +655,7 @@ function spawnDaemon(genre, volume, reactive) {
 function hookStart(genre, volume, { reactive = false, turn = null } = {}) {
   const id = sessionId(turn && turn.session);
   // Before the spawn: the daemon reads it on startup.
-  writeSession(id, { transcript: (turn && turn.transcript) || "", offset: (turn && turn.offset) || 0, waiting: null });
+  writeSession(id, { transcript: (turn && turn.transcript) || "", offset: (turn && turn.offset) || 0, waiting: null, started: Date.now(), blockedMs: 0 });
   if (working(listSessions()).some((s) => s.id !== id) && daemonRunning()) return readPid();
 
   stopDaemon({ keepSessions: true });
@@ -729,12 +760,19 @@ function notify(raw, message) {
   }
 }
 
-function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChime = false, raw = "" } = {}) {
-  const id = sessionId(parsePayload(raw).session_id);
+function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChime = false, genre, raw = "" } = {}) {
+  const id = sessionId(payloadSession(parsePayload(raw)));
   // 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 tracked = readSession(id) !== null;
+  const session = readSession(id);
+  const tracked = session !== null;
   fs.rmSync(sessionFile(id), { force: true });
+  if (session && Number.isFinite(session.started)) {
+    const now = Date.now();
+    // A turn that ends while still paused for you has been blocked since then.
+    const blockedMs = (session.blockedMs || 0) + (session.waiting != null && session.waitStart ? now - session.waitStart : 0);
+    recordTurn({ project: parsePayload(raw).cwd || process.cwd(), ms: now - session.started, blockedMs, outcome, at: now });
+  }
 
   // The music is every working session's, so it ends with the last of them.
   // Everyone else's carries on, and this session still gets its own chime.
@@ -746,7 +784,7 @@ function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChi
   if (noChime) return false;
 
   // Chime plays in this short-lived hook process.
-  new AudioPlayer().stop({ playChime: true, outcome, volume, chimeVolume });
+  new AudioPlayer().stop({ playChime: true, outcome, volume, chimeVolume, genre });
   return true;
 }
 
@@ -788,11 +826,11 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
   const type = payload.notification_type ?? payload.notificationType;
   if (type !== undefined && !WAIT_NOTIFICATIONS.has(String(type))) return false;
 
-  const id = sessionId(payload.session_id);
+  const id = sessionId(payloadSession(payload));
   const session = readSession(id);
   if (!session || session.waiting != null) return false;
 
-  writeSession(id, { ...session, waiting: waitKey(raw) });
+  writeSession(id, { ...session, waiting: waitKey(raw), waitStart: Date.now() });
   if (working(listSessions()).length === 0) stopDaemon({ keepSessions: true });
   const tool = payloadToolName(raw);
   notify(raw, tool ? `needs you (${tool})` : "needs you");
@@ -814,14 +852,15 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
  * job. Match on tool_input as well if that ever shows up in practice.
  */
 function hookResume(raw, genre, volume, { reactive = false } = {}) {
-  const id = sessionId(parsePayload(raw).session_id);
+  const id = sessionId(payloadSession(parsePayload(raw)));
   const session = readSession(id);
   if (!session || session.waiting == null) return false; // Not waiting - the common case, on every tool call.
   // An empty key is a wait that named nothing (a Notification): the next tool
   // to finish is the first sign of work carrying on.
   if (session.waiting !== "" && session.waiting !== waitKey(raw)) return false;
 
-  writeSession(id, { ...session, waiting: null });
+  const blockedMs = (session.blockedMs || 0) + (session.waitStart ? Date.now() - session.waitStart : 0);
+  writeSession(id, { ...session, waiting: null, waitStart: null, blockedMs });
   if (!daemonRunning()) spawnDaemon(genre, volume, reactive);
   return true;
 }
@@ -836,7 +875,7 @@ function hookResume(raw, genre, volume, { reactive = false } = {}) {
  * applies.
  */
 function hookEnd(raw) {
-  const id = sessionId(parsePayload(raw).session_id);
+  const id = sessionId(payloadSession(parsePayload(raw)));
   if (!readSession(id)) return false;
 
   fs.rmSync(sessionFile(id), { force: true });

package/src/interactive.js

@@ -35,6 +35,7 @@ const AI_TOOLS = [
   { name: "Cursor CLI", cmd: ["cursor-agent"], check: "cursor-agent", hookTarget: "cursor" },
   { name: "GitHub Copilot CLI", cmd: ["copilot"], check: "copilot", hookTarget: "copilot" },
   { name: "Qwen Code", cmd: ["qwen"], check: "qwen", hookTarget: "qwen" },
+  { name: "Windsurf", cmd: ["windsurf"], check: "windsurf", hookTarget: "windsurf" },
   { name: "Aider", cmd: ["aider"], check: "aider" },
   { name: "Ollama (Llama 3)", cmd: ["ollama", "run", "llama3"], check: "ollama" },
   { name: "Custom command...", cmd: null }

package/src/mac-player.jxa

@@ -0,0 +1,46 @@
+// VibeAudio macOS player: one long-lived process driving AVAudioPlayer, run by
+// `osascript -l JavaScript`. Lines on stdin:
+//   play <volume 0-1> <fade-in seconds> <path to wav>
+// End of input - a closed pipe, or the daemon dying - fades out and exits, so
+// the audio can never outlive whoever started it.
+ObjC.import("Foundation");
+ObjC.import("AVFoundation");
+
+const FADE_OUT_S = 0.3;
+const players = [];
+
+function sleep(seconds) {
+  $.NSThread.sleepForTimeInterval(seconds);
+}
+
+function play(volume, fadeIn, path) {
+  const url = $.NSURL.fileURLWithPath(path);
+  const p = $.AVAudioPlayer.alloc.initWithContentsOfURLError(url, null);
+  if (!p || !p.prepareToPlay) return;
+  p.volume = fadeIn > 0 ? 0 : volume;
+  p.play;
+  if (fadeIn > 0) p.setVolumeFadeDuration(volume, fadeIn);
+  players.push(p);
+  // Finished loops are done with: keep only what is still sounding.
+  for (let i = players.length - 2; i >= 0; i--) if (!players[i].playing) players.splice(i, 1);
+}
+
+function handle(line) {
+  const m = /^play (\S+) (\S+) (.+)$/.exec(line);
+  if (m) play(parseFloat(m[1]), parseFloat(m[2]), m[3]);
+}
+
+const stdin = $.NSFileHandle.fileHandleWithStandardInput;
+let pending = "";
+for (;;) {
+  const data = stdin.availableData; // Blocks; playback runs on its own thread.
+  if (Number(data.length) === 0) break; // JXA hands NSData.length back as a string.
+  pending += $.NSString.alloc.initWithDataEncoding(data, $.NSUTF8StringEncoding).js;
+  const lines = pending.split("\n");
+  pending = lines.pop();
+  lines.forEach(handle);
+}
+
+for (const p of players) if (p.playing) p.setVolumeFadeDuration(0, FADE_OUT_S);
+sleep(FADE_OUT_S + 0.05);
+for (const p of players) p.stop;

package/src/output.js

@@ -0,0 +1,57 @@
+/**
+ * What macOS is actually sending sound to. `afplay` plays on the default
+ * output device, which is not always the one you are listening on: connect a
+ * monitor and the default can move to it, where the system volume may be
+ * missing or the speakers quiet. Read only by `--doctor`; nothing else asks.
+ */
+
+const { spawnSync } = require("child_process");
+
+/** "output volume:39, input volume:88, alert volume:63, output muted:false" */
+function parseVolumeSettings(text) {
+  const volume = /output volume:\s*(\d+)/.exec(text);
+  const muted = /output muted:\s*(true|false)/.exec(text);
+  return {
+    // "missing value" is what macOS reports for a device with no software
+    // volume control - common for monitors - so absent means no knob, not zero.
+    volume: volume ? Number(volume[1]) : null,
+    muted: muted ? muted[1] === "true" : null
+  };
+}
+
+const TRANSPORTS = {
+  coreaudio_device_type_usb: "USB",
+  coreaudio_device_type_hdmi: "HDMI",
+  coreaudio_device_type_displayport: "DisplayPort",
+  coreaudio_device_type_builtin: "built-in",
+  coreaudio_device_type_bluetooth: "Bluetooth",
+  coreaudio_device_type_airplay: "AirPlay",
+  coreaudio_device_type_virtual: "virtual"
+};
+
+/** The device `afplay` will use, from `system_profiler SPAudioDataType -json`. */
+function parseDefaultOutput(json) {
+  try {
+    const items = (JSON.parse(json).SPAudioDataType || []).flatMap((group) => group._items || []);
+    const item = items.find((i) => i.coreaudio_default_audio_output_device === "spaudio_yes");
+    if (!item) return null;
+    return { name: item._name, transport: TRANSPORTS[item.coreaudio_device_transport] || null };
+  } catch (e) {
+    return null;
+  }
+}
+
+/** null off macOS, or when either lookup fails: absence of an answer is not a finding. */
+function macOutput() {
+  if (process.platform !== "darwin") return null;
+  const run = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 5000 });
+    return r.status === 0 ? r.stdout : null;
+  };
+  const settings = run("osascript", ["-e", "get volume settings"]);
+  if (settings === null) return null;
+  const profile = run("system_profiler", ["SPAudioDataType", "-json"]);
+  return { ...parseVolumeSettings(settings), device: profile ? parseDefaultOutput(profile) : null };
+}
+
+module.exports = { parseVolumeSettings, parseDefaultOutput, macOutput };

package/src/player.js

@@ -18,7 +18,7 @@ const { generateRainLoop } = require("./synth/rain");
 const { generateOceanLoop } = require("./synth/ocean");
 const { generatePianoLoop } = require("./synth/piano");
 const { generateJazzLoop } = require("./synth/jazz");
-const { generateSuccessChime, generateFailureChime, generateAttentionChime } = require("./synth/chime");
+const { generateSuccessChime, generateFailureChime, generateAttentionChime, DEFAULT_CHIME_KEY, SUCCESS_CHIME_NOTES } = require("./synth/chime");
 const { hashString } = require("./synth/generator");
 const pkg = require("../package.json");
 
@@ -110,6 +110,18 @@ const PLAYER_CANDIDATES = [
 let cachedPlayer;
 let warnedNoPlayer = false;
 
+// macOS: one long-lived AVAudioPlayer process instead of an afplay per loop,
+// which is what lets music fade in and out rather than start and end mid-note.
+// afplay stays the fallback: a helper that cannot start is not worth a silent
+// run, and it is used for the rest of the process once one has failed.
+const MAC_HELPER = path.join(__dirname, "mac-player.jxa");
+const FADE_IN_S = 0.5;
+let helperFailed = false;
+
+function helperUsable(backend) {
+  return process.platform === "darwin" && backend.cmd === "afplay" && !helperFailed && !process.env.VIBE_NO_FADE;
+}
+
 function detectPlayer() {
   if (cachedPlayer !== undefined) return cachedPlayer;
 
@@ -633,13 +645,45 @@ const CHIMES = {
   attention: generateAttentionChime
 };
 
-function getChimePath(outcome = "success", gain = 1) {
+/**
+ * The key each genre sits in, so the success chime can resolve onto it. Read
+ * off the generators: lofi, 8bit, jazz and piano are C major (or its relative
+ * A minor, which shares the chord); synthwave and electronic are D minor; zen
+ * is D major; drone's roots (D, A, E) all take an A minor chord. Rain and
+ * ocean are noise with no pitch, and `random` is resolved by whoever started
+ * the music, so those keep the original chime.
+ */
+const GENRE_KEYS = {
+  lofi: "C major",
+  "8bit": "C major",
+  jazz: "C major",
+  piano: "C major",
+  synthwave: "D minor",
+  electronic: "D minor",
+  zen: "D major",
+  drone: "A minor"
+};
+
+function chimeKeyFor(genre) {
+  // resolveGenre would roll the dice here, and a chime in a key picked at
+  // random is no more matched than the default.
+  if (String(genre || "").trim().toLowerCase() === "random") return DEFAULT_CHIME_KEY;
+  const key = GENRE_KEYS[resolveGenre(genre || "")];
+  return key && SUCCESS_CHIME_NOTES[key] ? key : DEFAULT_CHIME_KEY;
+}
+
+function getChimePath(outcome = "success", gain = 1, key = DEFAULT_CHIME_KEY) {
   ensureCacheDir();
   const kind = outcome === "error" ? "failure" : CHIMES[outcome] ? outcome : "success";
-  const filePath = path.join(CACHE_DIR, `chime_${kind}${gainSuffix(gain)}.wav`);
+  // Only the success chime has keys, and the default keeps its original file
+  // name so an upgrade does not leave a cached copy behind.
+  const keyed = kind === "success" && key !== DEFAULT_CHIME_KEY && SUCCESS_CHIME_NOTES[key];
+  const suffix = keyed ? `_${key.replace(" ", "")}` : "";
+  const filePath = path.join(CACHE_DIR, `chime_${kind}${suffix}${gainSuffix(gain)}.wav`);
 
   if (!fs.existsSync(filePath)) {
-    writeCacheFileAtomic(filePath, applyGain(CHIMES[kind](), gain));
+    const wav = keyed ? generateSuccessChime(1.6, key) : CHIMES[kind]();
+    writeCacheFileAtomic(filePath, applyGain(wav, gain));
   }
   return filePath;
 }
@@ -676,6 +720,7 @@ class AudioPlayer {
   constructor() {
     this.isPlaying = false;
     this.procs = new Set();
+    this.helper = null;
     this.startTime = 0;
     this.genre = "lofi";
     this.volume = 0.42;
@@ -757,6 +802,13 @@ class AudioPlayer {
     const audioFile = getAudioPath(this.genre, this.currentTier, this.seed, gain, this.bar);
     // Advanced after the choice, so the bar that plays first is bar 0.
     this.bar = (this.bar + 1) % LOOP_BARS;
+    if (!(helperUsable(backend) && this.playViaHelper(audioFile, backend))) this.spawnLoop(audioFile, backend);
+
+    const durationMs = wavDurationMs(audioFile) || 6500;
+    this.nextTimer = setTimeout(() => this.playLoop(), Math.max(250, durationMs - LOOP_OVERLAP_MS));
+  }
+
+  spawnLoop(audioFile, backend) {
     const proc = spawn(backend.cmd, backend.args(audioFile, this.volume), { stdio: "ignore" });
 
     this.procs.add(proc);
@@ -766,12 +818,55 @@ class AudioPlayer {
       this.isPlaying = false;
       warnNoPlayer();
     });
+  }
 
-    const durationMs = wavDurationMs(audioFile) || 6500;
-    this.nextTimer = setTimeout(() => this.playLoop(), Math.max(250, durationMs - LOOP_OVERLAP_MS));
+  /**
+   * Hands one loop to the macOS helper, starting it on first use. Returns false
+   * when the helper could not be started, so the caller plays it with afplay.
+   * A helper that dies while we are playing is dropped and the loop that was
+   * meant for it replayed, so a failure costs one restart, not the music.
+   */
+  playViaHelper(audioFile, backend) {
+    try {
+      if (!this.helper) {
+        const helper = spawn("osascript", ["-l", "JavaScript", MAC_HELPER], { stdio: ["pipe", "ignore", "ignore"] });
+        helper.stdin.on("error", () => {}); // EPIPE once it is gone.
+        const dropped = () => {
+          if (this.helper !== helper) return;
+          this.helper = null;
+          helperFailed = true;
+          if (this.isPlaying) this.spawnLoop(audioFile, backend);
+        };
+        helper.on("error", dropped);
+        helper.on("exit", dropped);
+        this.helper = helper;
+        this.helperFirst = true;
+      }
+      const fade = this.helperFirst ? FADE_IN_S : 0; // Later loops carry their own boundary fades.
+      this.helperFirst = false;
+      this.helper.stdin.write(`play ${this.volume} ${fade} ${audioFile}\n`);
+      return true;
+    } catch (e) {
+      helperFailed = true;
+      this.helper = null;
+      return false;
+    }
   }
 
   killProcs() {
+    // Closing the helper's input is the stop: it fades out and exits on its own,
+    // so the music ends on a decay, and a daemon that dies without cleanup closes
+    // the pipe just the same.
+    if (this.helper) {
+      const helper = this.helper;
+      this.helper = null;
+      try {
+        helper.stdin.end();
+        helper.unref();
+      } catch (e) {
+        // Already gone.
+      }
+    }
     for (const proc of this.procs) {
       try {
         proc.kill("SIGTERM");
@@ -787,7 +882,7 @@ class AudioPlayer {
    * that must hand control back at once - an agent waits on its hooks, and a
    * blocking chime held the permission dialog back for its whole length.
    */
-  stop({ playChime = true, outcome = "success", volume = 0.35, chimeVolume = null, detach = false } = {}) {
+  stop({ playChime = true, outcome = "success", volume = 0.35, chimeVolume = null, detach = false, genre = this.genre } = {}) {
     const wasPlaying = this.isPlaying;
     this.isPlaying = false;
 
@@ -809,7 +904,7 @@ class AudioPlayer {
 
       const targetVol = chimeVolume !== null ? chimeVolume : Math.min(0.65, Math.max(0.35, volume * 1.1));
       const clamped = Math.max(0.05, Math.min(1.0, targetVol));
-      const chimeFile = getChimePath(outcome, bakedGain(backend, clamped));
+      const chimeFile = getChimePath(outcome, bakedGain(backend, clamped), chimeKeyFor(genre));
 
       try {
         if (detach) {
@@ -834,6 +929,8 @@ module.exports = {
   pruneSeedDirs,
   writeCacheFileAtomic,
   getChimePath,
+  chimeKeyFor,
+  GENRE_KEYS,
   clearCache,
   detectPlayer,
   bakedGain,

package/src/synth/chime.js

@@ -10,16 +10,30 @@ const {
   createWavBuffer
 } = require("./generator");
 
-function generateSuccessChime(durationSec = 1.6) {
+// The success chime is the tonic chord of whatever key the music is in - root,
+// fifth, octave, third - so it lands as the resolution of the piece instead of
+// a stranger's bell over it. The default is the original C major chime.
+const DEFAULT_CHIME_KEY = "C major";
+const SUCCESS_CHIME_NOTES = {
+  "C major": ["C5", "G5", "C6", "E6"],
+  "D major": ["D5", "A5", "D6", "F#6"],
+  "D minor": ["D5", "A5", "D6", "F6"],
+  // Sits low on purpose: A, E and C are consonant over each of the drone's
+  // three roots (D, A, E), so one chime serves all of them.
+  "A minor": ["A4", "E5", "A5", "C6"]
+};
+
+function generateSuccessChime(durationSec = 1.6, key = DEFAULT_CHIME_KEY) {
+  const names = SUCCESS_CHIME_NOTES[key] || SUCCESS_CHIME_NOTES[DEFAULT_CHIME_KEY];
   const totalSamples = Math.floor(SAMPLE_RATE * durationSec);
   const left = new Float64Array(totalSamples);
   const right = new Float64Array(totalSamples);
 
   const chimeNotes = [
-    { note: "C5", delay: 0.00, pan: 0.4 },
-    { note: "G5", delay: 0.09, pan: 0.6 },
-    { note: "C6", delay: 0.18, pan: 0.45 },
-    { note: "E6", delay: 0.27, pan: 0.55 }
+    { note: names[0], delay: 0.00, pan: 0.4 },
+    { note: names[1], delay: 0.09, pan: 0.6 },
+    { note: names[2], delay: 0.18, pan: 0.45 },
+    { note: names[3], delay: 0.27, pan: 0.55 }
   ];
 
   for (const c of chimeNotes) {
@@ -130,6 +144,8 @@ function generateAttentionChime(durationSec = 1.3) {
 }
 
 module.exports = {
+  DEFAULT_CHIME_KEY,
+  SUCCESS_CHIME_NOTES,
   generateChime: generateSuccessChime,
   generateSuccessChime,
   generateFailureChime,