vibeaudio 0.8.2 → 0.10.0

package/README.md

@@ -139,7 +139,7 @@ vibe npm test
 vibe claude -p "explain this repo"
 ```
 
-**Lost?** `vibe --help` lists every flag, and `vibe --status` reads your live setup back to you — what's installed, what's playing, and which agents it found.
+**Lost?** `vibe --help` lists every flag, and `vibe --status` reads your live setup back to you — what's installed, what's playing, and which agents it found. If something seems broken, `vibe --doctor` checks it and prints the fix for each problem.
 
 > **Which one you want:** the wrapper plays music for as long as the wrapped process lives. That's exactly right for a command that exits when its work is done — and wrong for an interactive REPL like `claude`, where the process stays alive while you read and type, so the music never stops. Hooks know when the agent is actually thinking; the wrapper can only time the process.
 
@@ -289,6 +289,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.
+
 <details>
 <summary><b>The rest of how sessions share one stream</b></summary>
 
@@ -355,6 +357,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
@@ -458,7 +477,7 @@ VIBE_VOLUME = "25"
 Restart the app afterwards — this one is read from the environment the server was launched with, so unlike the saved default it can't change under a running client.
 
 #### Exposed MCP Tools:
-* `vibe_play`: Start procedural focus music (`genre`: `lofi`, `synthwave`, `8bit`, `electronic`, `jazz`, `zen`, `piano`, `drone`, `random`; `volume`: `5-100`).
+* `vibe_play`: Start procedural focus music (`genre`: `lofi`, `synthwave`, `8bit`, `electronic`, `jazz`, `zen`, `piano`, `drone`, `rain`, `ocean`, `random`; `volume`: `5-100`).
 * `vibe_stop`: Stop music and play the completion chime (`outcome`: `success` or `failure`).
 * `vibe_status`: Return current playback state and active tier.
 
@@ -480,7 +499,9 @@ VibeAudio includes **8 procedural music styles** synthesized entirely in code:
 | `zen` | 🎋 **Zen Ambient** | Meditative Tibetan singing bowls & celestial drone (zero rhythm) |
 | `piano` | 🎹 **Sparse Piano** | Single struck notes and long silences — Satie-ish |
 | `drone` | 🌫️ **Deep Drone** | A held tone and filtered noise — **no melody at all** |
-| `random` | 🎲 **Shuffle Mode** | Picks a surprise genre for the run — **never `drone`** |
+| `rain` | 🌧️ **Rain** | Band-passed rainfall with sparse droplets — **no melody at all** |
+| `ocean` | 🌊 **Ocean** | Low surf on a slow swell that rises and drains — **no melody at all** |
+| `random` | 🎲 **Shuffle Mode** | Picks a surprise genre for the run — **never `drone`, `rain` or `ocean`** |
 
 **Aliases also work**, so you can ask for a genre the way you'd say it — `vibe --preview chill` is `lofi`:
 
@@ -494,14 +515,16 @@ VibeAudio includes **8 procedural music styles** synthesized entirely in code:
 | `zen` | `ambient`, `calm`, `meditation` |
 | `piano` | `sparse`, `satie`, `keys`, `minimal` |
 | `drone` | `noise`, `focus`, `hum`, `whitenoise`, `white-noise` |
+| `rain` | `storm`, `drizzle` |
+| `ocean` | `waves`, `sea`, `surf` |
 
 Matching is case-insensitive, so `BOSSA` works too.
 
-> **If any melody distracts you, use `drone`.** Every other genre plays something — notes, a progression, a bass line — and some people can't read while that happens. `drone` holds one low tone under a slow-breathing noise bed and never moves: closer to a fan or rainfall than to music. Tiers add weight rather than movement.
+> **If any melody distracts you, use `drone`.** Every other genre plays something — notes, a progression, a bass line — and some people can't read while that happens. `drone` holds one low tone under a slow-breathing noise bed and never moves: closer to a fan or rainfall than to music. Tiers add weight rather than movement. If you want the fan-and-rainfall idea literally, `rain` and `ocean` are synthesized the same way (seeded noise, no recorded files): rain adds more droplets as the turn runs longer, ocean adds a second swell and then foam.
 >
 > **`piano` is the gentler version of that idea.** It still plays notes — two in eight seconds at tier 1 — but they're single struck tones with silence between them and nothing running underneath. Higher tiers fill the gaps rather than adding a groove. Try it before `drone` if you want *something* there.
 >
-> For the same reason **`random` never picks `drone`**. Shuffle is for a surprise *mood*, and drone isn't one — landing on a fan noise when you asked for variety reads as broken audio, not as range. Ask for it by name (or `noise` / `focus`) when you want it.
+> For the same reason **`random` never picks `drone`, `rain` or `ocean`**. Shuffle is for a surprise *mood*, and drone isn't one — landing on a fan noise when you asked for variety reads as broken audio, not as range. Ask for it by name (or `noise` / `focus`) when you want it.
 
 ### Usage Examples:
 ```bash
@@ -520,7 +543,7 @@ vibe --genre jazz --volume 25
 Saved to `~/.vibeaudio/config.json` and read by all three ways of running VibeAudio — wrapper, agent hooks, MCP. It applies on your next prompt.
 
 ```bash
-vibe --genre jazz          # lofi, synthwave, 8bit, electronic, jazz, zen, piano, drone, random
+vibe --genre jazz          # lofi, synthwave, 8bit, electronic, jazz, zen, piano, drone, rain, ocean, random
 vibe --volume 25           # or --whisper / --quiet / --loud
 vibe --chime-volume 70
 vibe --status              # what's saved, and what's overriding it
@@ -545,7 +568,7 @@ The full order, highest first: **a flag** → **an environment variable** → **
 
 | Flag | Description | Default |
 | :--- | :--- | :--- |
-| `-g, --genre <name>` | Music style: `lofi`, `synthwave`, `8bit`, `electronic`, `jazz`, `zen`, `piano`, `drone`, `random`. With no command after it, saves your default | `lofi` |
+| `-g, --genre <name>` | Music style: `lofi`, `synthwave`, `8bit`, `electronic`, `jazz`, `zen`, `piano`, `drone`, `rain`, `ocean`, `random`. With no command after it, saves your default | `lofi` |
 | `-v, --volume <5-100>` | Set playback volume. With no command after it, saves your default | `40` |
 | `-cv, --chime-volume <5-100>` | Set independent completion chime volume | `volume × 1.1`, kept within 35–65 |
 | `--grace <ms>` | Silence window before music starts | `1500` |
@@ -557,8 +580,11 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--no-chime` | Disable the resolution completion chime | `false` |
 | `--no-hud` | Disable terminal window/tab title animation | `false` |
 | `--preview <genre>` | Play one loop of a genre and exit | — |
-| `--render [file]` | Write this project's music to a `.wav` and exit | `vibeaudio-<genre>.wav` |
+| `--render [file]` | Write this project's music to a `.wav` and exit (full scale, ignores `--volume`) | `vibeaudio-<genre>.wav` |
 | `--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 | — |
@@ -577,12 +603,14 @@ The full order, highest first: **a flag** → **an environment variable** → **
 **Defaults live in `~/.vibeaudio/config.json` now** — `vibe --genre jazz` is the short way to set one. These override it for a single shell, which is what you want for one terminal that should sound different, or for a machine you don't want writing config at all:
 
 ```bash
-export VIBE_GENRE=jazz          # lofi, synthwave, 8bit, electronic, jazz, zen, piano, drone, random
+export VIBE_GENRE=jazz          # lofi, synthwave, 8bit, electronic, jazz, zen, piano, drone, rain, ocean, random
 export VIBE_VOLUME=25           # Background music at 25%
 export VIBE_CHIME_VOLUME=70     # Crisp completion chime at 70%
 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
 ```
 
@@ -615,6 +643,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`.
 

package/package.json

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

@@ -62,7 +62,7 @@ Procedural focus music while your AI coding tools think.
   vibe                           \x1b[90m# menu: pick a tool and a sound (p auditions a genre)\x1b[0m
 
 \x1b[1mOPTIONS:\x1b[0m
-  -g, --genre <name>           Select genre: lofi (default), synthwave, 8bit, electronic, jazz, zen, piano, drone, random
+  -g, --genre <name>           Select genre: lofi (default), synthwave, 8bit, electronic, jazz, zen, piano, drone, rain, ocean, random
   -v, --volume <5-100>         Set playback volume (default: 40)
   -cv, --chime-volume <5-100>   Set independent completion chime volume
       --grace <ms>             Silence window before music starts, in ms (default: ${DEFAULT_GRACE_PERIOD_MS})
@@ -74,8 +74,11 @@ Procedural focus music while your AI coding tools think.
       --no-chime               Disable the resolution completion chime
       --no-hud                 Disable terminal window/tab title animation
       --preview <genre>        Play one loop of a genre and exit
-      --render [file]          Write this project's music to a .wav 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)
+      --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)
       --unmute                 Resume normal playback, then exit
@@ -171,6 +174,9 @@ function parseArgs(argv) {
   let render = null;
   let clearCacheFlag = false;
   let statusFlag = false;
+  let doctorFlag = false;
+  let notifyFlag = null;
+  let reportDays = null;
   let stopFlag = false;
   let muteFlag = null;
   let muteMinutes = null;
@@ -281,6 +287,29 @@ 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;
+      continue;
+    }
+
+    if (arg === "--doctor") {
+      doctorFlag = true;
+      i += 1;
+      continue;
+    }
+
     if (arg === "--stop") {
       stopFlag = true;
       i += 1;
@@ -423,6 +452,9 @@ function parseArgs(argv) {
     render,
     clearCache: clearCacheFlag,
     status: statusFlag,
+    doctor: doctorFlag,
+    notify: notifyFlag,
+    report: reportDays,
     stop: stopFlag,
     mute: muteFlag,
     muteMinutes,
@@ -660,6 +692,7 @@ function printStatus() {
   console.log(`  genre     ${on(genreNow())}${source("VIBE_GENRE", "genre")}`);
   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")}`);
 
   // Audio backend
   const backend = detect();
@@ -742,6 +775,235 @@ function printStatus() {
   printUpdateNotice();
 }
 
+/**
+ * --status reads the setup back; this judges it. Each check is pass ("ok"),
+ * worth knowing ("warn" - deliberate or self-healing states) or broken
+ * ("fail"), and anything but "ok" carries the exact command that fixes it.
+ * Only "fail" makes the exit code non-zero: a mute someone set on purpose is
+ * not a reason for `vibe --doctor && ...` to stop a script.
+ */
+function doctorChecks() {
+  const hooks = require("./hooks");
+  const { detectPlayer: detect, muteState, muteRemainingText, playbackDisabled, CACHE_ROOT, CONFIG_FILE } = require("./player");
+  const checks = [];
+  const add = (level, label, detail = "", fix = "") => checks.push({ level, label, detail, fix });
+
+  const backend = detect();
+  if (backend) {
+    add("ok", "Audio player", `${backend.cmd}${backend.volume ? "" : " (no volume flag — gain is baked into the file)"}`);
+  } else {
+    add("fail", "Audio player", "none found — VibeAudio runs silently",
+      process.platform === "linux" ? "install one of: pulseaudio-utils (paplay), ffmpeg (ffplay), alsa-utils (aplay)"
+        : process.platform === "win32" ? "PowerShell's SoundPlayer should be present — check that powershell is on PATH"
+        : "afplay ships with macOS — check that /usr/bin is on PATH");
+  }
+
+  // loadConfig() swallows a parse error on purpose so playback never stops,
+  // which is exactly why a typo here is silent and needs a check of its own.
+  let configProblem = null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) configProblem = "not a JSON object";
+  } catch (e) {
+    if (e.code !== "ENOENT") configProblem = e.message;
+  }
+  if (configProblem) {
+    add("fail", "Saved settings", `${CONFIG_FILE}: ${configProblem} — ignored, defaults are in use`,
+      `fix or delete ${CONFIG_FILE}, then: vibe --genre <name> --volume <n>`);
+  } else {
+    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];
+    const installed = readVibeHooks(t.file(), t);
+    const label = `${t.name} hooks`;
+    if (!installed.length) {
+      if (detected.includes(id)) add("warn", label, "agent found, hooks not installed", "vibe --install-hooks");
+      continue;
+    }
+
+    // Hooks hold absolute paths to node and to this CLI; an evicted npx cache
+    // or an uninstalled node leaves the agent firing a command that fails.
+    const missing = new Set();
+    for (const { command } of installed) {
+      const tokens = [...command.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)].map((m) => m[1] ?? m[2] ?? m[3]);
+      for (const p of tokens.slice(0, 2)) if (!fs.existsSync(p)) missing.add(p);
+    }
+    if (missing.size) {
+      add("fail", label, `points at a file that no longer exists: ${[...missing].join(", ")}`, "vibe --install-hooks");
+    } else if (installed.some(({ command }) => /--genre /.test(command))) {
+      add("warn", label, "pinned to a genre/volume by an older install, which overrides your saved settings", "vibe --install-hooks");
+    } else {
+      add("ok", label, `${installed.length} entries`);
+    }
+
+    // Codex runs a hook only after the user approves it, and records that in
+    // config.toml under "<file>:<event>:<group>:<index>".
+    if (id === "codex") {
+      let toml = "";
+      try { toml = fs.readFileSync(path.join(os.homedir(), ".codex", "config.toml"), "utf8"); } catch (e) { /* none yet */ }
+      const pending = [];
+      try {
+        const file = t.file();
+        for (const [event, entries] of Object.entries(JSON.parse(fs.readFileSync(file, "utf8")).hooks || {})) {
+          (entries || []).forEach((entry, g) => {
+            t.commands(entry).forEach((command, i) => {
+              const key = `${file}:${event.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase()}:${g}:${i}`;
+              if (hooks.VIBE_HOOK_FLAG.test(command || "") && !toml.includes(`"${key}"`)) pending.push(event);
+            });
+          });
+        }
+      } catch (e) { /* unreadable: the hooks check above already said so */ }
+      if (pending.length) {
+        add("warn", "Codex hook trust", `${pending.length} hooks not yet approved (${[...new Set(pending)].join(", ")}) — Codex will not run them`,
+          "start codex and approve each VibeAudio hook once");
+      }
+    }
+  }
+
+  const mute = muteState();
+  if (mute !== null) add("warn", "Mute", `muted ${muteRemainingText(mute)}`, "vibe --unmute");
+  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");
+
+  const pid = readDaemonPid(hooks.PID_FILE);
+  if (pid === null) add("ok", "Background player", "not running");
+  else if (!hooks.daemonPlaying()) add("warn", "Background player", `stale pid file (${pid} is not ours) — harmless, cleared on the next prompt`, "vibe --stop");
+  else add("ok", "Background player", `playing, pid ${pid}`);
+
+  try {
+    fs.mkdirSync(CACHE_ROOT, { recursive: true });
+    fs.accessSync(CACHE_ROOT, fs.constants.W_OK);
+    add("ok", "Audio cache", `writable (${CACHE_ROOT})`);
+  } catch (e) {
+    add("fail", "Audio cache", `${CACHE_ROOT} is not writable: ${e.code || e.message}`, `check permissions on ${path.dirname(CACHE_ROOT)}`);
+  }
+
+  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();
+  console.log(`\n\x1b[1m\x1b[36mVibeAudio\x1b[0m v${pkg.version} doctor\n`);
+  for (const c of checks) {
+    console.log(`  ${mark[c.level]} ${c.label.padEnd(26)}\x1b[90m${c.detail}\x1b[0m`);
+    if (c.fix) console.log(`      fix: ${c.fix}`);
+  }
+  const failed = checks.filter((c) => c.level === "fail").length;
+  const warned = checks.filter((c) => c.level === "warn").length;
+  console.log(failed ? `\n\x1b[31m${failed} problem${failed > 1 ? "s" : ""}\x1b[0m${warned ? `, ${warned} to look at` : ""}.\n`
+    : `\n\x1b[32mNo problems\x1b[0m${warned ? `, ${warned} to look at` : ""}.\n`);
+  if (failed) process.exitCode = 1;
+}
+
 /**
  * The effective genre and volume, resolved the same way parseArgs does it, so
  * --status reports what would actually play rather than a second opinion.
@@ -1020,6 +1282,7 @@ function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive,
           volume,
           chimeVolume,
           noChime,
+          genre,
           raw
         });
       });
@@ -1210,6 +1473,9 @@ async function run() {
     render,
     clearCache: shouldClear,
     status: showStatus,
+    doctor: showDoctor,
+    notify: notifyChange,
+    report: reportDays,
     stop: shouldStop,
     mute: muteChange,
     muteMinutes,
@@ -1270,6 +1536,14 @@ async function run() {
     return;
   }
 
+  if (notifyChange !== null) {
+    saveConfig({ notify: notifyChange });
+    console.log(notifyChange
+      ? "\x1b[32m✔ Notifications on.\x1b[0m A banner names the project when a turn finishes, fails or needs you."
+      : "\x1b[90mNotifications off.\x1b[0m");
+    return;
+  }
+
   if (shouldStop) {
     const hooks = require("./hooks");
     const stopped = hooks.stopDaemon();
@@ -1285,6 +1559,14 @@ async function run() {
     return printStatus();
   }
 
+  if (showDoctor) {
+    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

@@ -15,7 +15,8 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const { spawn, execFileSync } = require("child_process");
-const { AudioPlayer } = require("./player");
+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");
@@ -624,7 +625,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 });
@@ -679,22 +680,81 @@ function readPayload(done, timeoutMs = 500) {
   setTimeout(finish, timeoutMs).unref();
 }
 
-function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChime = false, raw = "" } = {}) {
+/**
+ * Opt-in desktop notification, for the moment a chime cannot answer "which
+ * one?": with several terminals going, a sound says something finished and
+ * leaves you alt-tabbing to find out what. Off by default - a banner is more
+ * intrusive than a sound. Env beats the saved setting, like every other one.
+ */
+function notifyEnabled(env = process.env, config = loadConfig()) {
+  const raw = String(env.VIBE_NOTIFY ?? config.notify ?? "").trim().toLowerCase();
+  return ["1", "true", "on", "yes"].includes(raw);
+}
+
+/** The project a hook fired in: the payload's cwd (Claude, Codex, Gemini), else ours. */
+function sessionLabel(payload, cwd = process.cwd()) {
+  const dir = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : cwd;
+  return path.basename(dir.replace(/[\\/]+$/, "")) || "a session";
+}
+
+/**
+ * The command that shows a notification, or null where there is no built-in
+ * way to (Windows, for now). Title and body travel as argv, never spliced into
+ * a script string: a project directory is user-controlled text.
+ */
+function notifyCommand(platform, title, body) {
+  if (platform === "darwin") {
+    return {
+      cmd: "osascript",
+      args: ["-e", "on run argv", "-e", "display notification (item 1 of argv) with title (item 2 of argv)", "-e", "end run", body, title]
+    };
+  }
+  if (platform === "linux") return { cmd: "notify-send", args: ["--", title, body] };
+  return null;
+}
+
+// Detached and unref'd: the agent waits on this hook, and a missing
+// osascript/notify-send (a Linux box with no notification daemon) must be
+// invisible rather than an error in someone's agent.
+function notify(raw, message) {
+  if (!notifyEnabled() || playbackDisabled()) return false; // a mute means quiet, banners included
+  const command = notifyCommand(process.platform, "VibeAudio", `${sessionLabel(parsePayload(raw))}: ${message}`);
+  if (!command) return false;
+  try {
+    const child = spawn(command.cmd, command.args, { detached: true, stdio: "ignore" });
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChime = false, genre, raw = "" } = {}) {
   const id = sessionId(parsePayload(raw).session_id);
   // 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.
   const others = working(listSessions()).length > 0;
   const wasPlaying = others ? false : stopDaemon({ keepSessions: true });
   if (!others) fs.rmSync(INTENSITY_FILE, { force: true });
-  if (!(tracked || wasPlaying) || noChime) return false;
+  if (!(tracked || wasPlaying)) return false;
+  notify(raw, outcome === "failure" ? "failed" : "finished");
+  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;
 }
 
@@ -740,8 +800,10 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
   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");
   if (!noChime) new AudioPlayer().stop({ playChime: true, outcome: "attention", volume, chimeVolume, detach: true });
   return true;
 }
@@ -767,7 +829,8 @@ function hookResume(raw, genre, volume, { reactive = false } = {}) {
   // 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;
 }
@@ -1018,7 +1081,7 @@ single short sentence. Do nothing else.
 - \`volume <5-100>\`: \`${cli} --volume <n>\`
   Both save the user's default and reach the hooks on the next prompt - there
   is nothing to reinstall, so do not run --install-hooks for these.
-  Genres: lofi, synthwave, 8bit, electronic, jazz, zen, piano, drone, random.
+  Genres: lofi, synthwave, 8bit, electronic, jazz, zen, piano, drone, rain, ocean, random.
 
 For anything else, show the user the list above instead of running a command.
 `;
@@ -1082,6 +1145,9 @@ module.exports = {
   hookEnd,
   newTurn,
   outcomeFromPayload,
+  notifyEnabled,
+  notifyCommand,
+  sessionLabel,
   readPayload,
   toolTier,
   readIntensity,

package/src/interactive.js

@@ -49,6 +49,8 @@ const GENRES = [
   { name: "🎋 Zen Ambient", desc: "Meditative singing bowls & floating celestial pads", id: "zen" },
   { name: "🎹 Sparse Piano", desc: "Single struck notes & long silences — Satie-ish", id: "piano" },
   { name: "🌫️ Deep Drone", desc: "Held tone & filtered noise — no melody at all", id: "drone" },
+  { name: "🌧️ Rain", desc: "Soft rainfall & distant droplets — no melody at all", id: "rain" },
+  { name: "🌊 Ocean", desc: "Slow surf rising and draining — no melody at all", id: "ocean" },
   { name: "🎲 Shuffle / Random", desc: "Picks a surprise vibe each time", id: "random" }
 ];
 

package/src/mcp.js

@@ -27,7 +27,7 @@ const TOOLS = [
       properties: {
         genre: {
           type: "string",
-          description: "Music genre: lofi, synthwave, 8bit, electronic, jazz, zen, piano (sparse), drone (no melody), or random",
+          description: "Music genre: lofi, synthwave, 8bit, electronic, jazz, zen, piano (sparse), drone/rain/ocean (no melody), or random",
           enum: [...AVAILABLE_GENRES, "random"]
         },
         volume: {

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

@@ -14,9 +14,11 @@ const { generateChiptuneLoop } = require("./synth/chiptune");
 const { generateElectronicLoop } = require("./synth/electronic");
 const { generateZenLoop } = require("./synth/zen");
 const { generateDroneLoop } = require("./synth/drone");
+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");
 
@@ -52,15 +54,16 @@ function synthFingerprint(dir = path.join(__dirname, "synth")) {
 }
 
 const CACHE_DIR = path.join(CACHE_ROOT, `v${pkg.version}-${synthFingerprint()}`);
-const AVAILABLE_GENRES = ["lofi", "synthwave", "8bit", "electronic", "jazz", "zen", "piano", "drone"];
+const AVAILABLE_GENRES = ["lofi", "synthwave", "8bit", "electronic", "jazz", "zen", "piano", "drone", "rain", "ocean"];
 
 /**
- * What `random` may land on. Drone is deliberately excluded: it is the "no
- * melody at all" option people choose on purpose, not a mood in the same
- * series as the others. Rolling it by chance reads as broken audio rather
- * than as variety, so it stays opt-in by name (or via the noise/focus alias).
+ * What `random` may land on. The non-melodic genres are deliberately excluded:
+ * they are the "no melody at all" options people choose on purpose, not moods
+ * in the same series as the others. Rolling one by chance reads as broken
+ * audio rather than as variety, so each stays opt-in by name (or by alias).
  */
-const SHUFFLE_GENRES = AVAILABLE_GENRES.filter((g) => g !== "drone");
+const NON_MELODIC_GENRES = ["drone", "rain", "ocean"];
+const SHUFFLE_GENRES = AVAILABLE_GENRES.filter((g) => !NON_MELODIC_GENRES.includes(g));
 
 // Next loop starts slightly before the current one ends, so the per-loop
 // boundary fades crossfade instead of leaving a process-spawn gap.
@@ -218,6 +221,11 @@ const GENRE_ALIASES = {
   hum: "drone",
   whitenoise: "drone",
   "white-noise": "drone",
+  storm: "rain",
+  drizzle: "rain",
+  waves: "ocean",
+  sea: "ocean",
+  surf: "ocean",
   sparse: "piano",
   satie: "piano",
   keys: "piano",
@@ -271,6 +279,10 @@ function generateLoop(genre, tier, seed, bar = 0) {
       return generateDroneLoop(7.0, tier, seed, bar);
     case "piano":
       return generatePianoLoop(7.6, tier, seed, bar);
+    case "rain":
+      return generateRainLoop(7.0, tier, seed, bar);
+    case "ocean":
+      return generateOceanLoop(8.0, tier, seed, bar);
     case "lofi":
     default:
       return generateLofiLoop(6.4, tier, seed, bar);
@@ -621,13 +633,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;
 }
@@ -775,7 +819,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;
 
@@ -797,7 +841,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) {
@@ -822,6 +866,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,

package/src/synth/ocean.js

@@ -0,0 +1,97 @@
+/**
+ * Ocean Procedural Synth Engine
+ * Low-passed noise under a slow swell: the surf rises, breaks and drains once
+ * per loop. No notes, no rhythm, no melody.
+ *
+ * The swell is exactly one cycle per loop (plus an exact second harmonic at
+ * tier 2+), so it lines up at the boundary and the loop reads as one
+ * continuous tide. Tiers add weight and foam, never a beat.
+ */
+
+const {
+  SAMPLE_RATE,
+  makeRng,
+  rotate,
+  ornamentRng,
+  createWavBuffer
+} = require("./generator");
+
+// The seed picks the sea, not a tune: how dark the water is, how deep the
+// swell runs, and how sharply it breaks. `level` evens the three out: a darker
+// filter passes less noise, so each needs its own make-up to land at the
+// level of the other genres (jazz: peak 0.64 / RMS 0.108).
+const OCEAN_VARIANTS = [
+  { lp: 380, depth: 0.80, shape: 1.6, level: 1.48, label: "slow swell" },
+  { lp: 620, depth: 0.65, shape: 1.2, level: 1.03, label: "shore" },
+  { lp: 260, depth: 0.90, shape: 2.0, level: 1.97, label: "deep water" }
+];
+
+const TIER_GAIN = { 1: 1.0, 2: 1.1, 3: 1.2 };
+const onePole = (hz) => 1 - Math.exp((-2 * Math.PI * hz) / SAMPLE_RATE);
+
+function generateOceanLoop(durationSec = 8.0, tier = 2, seed = 0, bar = 0) {
+  // Drawn before any tier gating, so gating a layer can't shift these.
+  const orn = ornamentRng(seed);
+  const variant = rotate(orn, OCEAN_VARIANTS, bar);
+  const chopPhase = orn();
+  const widthShift = 0.05 + orn() * 0.06;
+
+  const totalSamples = Math.floor(SAMPLE_RATE * durationSec);
+  const left = new Float64Array(totalSamples);
+  const right = new Float64Array(totalSamples);
+
+  // Noise streams are consumed identically at every tier.
+  const noiseRng = makeRng(seed ^ 0x7f4a7c15);
+  const foamRng = ornamentRng(seed ^ 0x1b873593);
+  const gain = variant.level * (TIER_GAIN[tier] || TIER_GAIN[2]);
+  let lpL = 0, lpR = 0, foamL = 0, foamR = 0;
+
+  // One swell cycle per loop; the right ear trails the left for width.
+  const swell = (cycles) => {
+    const s = 0.5 - 0.5 * Math.cos(2 * Math.PI * cycles);
+    return variant.depth * Math.pow(s, variant.shape) + (1 - variant.depth);
+  };
+
+  for (let i = 0; i < totalSamples; i++) {
+    const c = i / totalSamples;
+    let envL = swell(c);
+    let envR = swell(c - widthShift);
+    // Tier 2+: a second, shorter swell (exactly two cycles, so it tiles too)
+    // rides on the first - more water, not more rhythm.
+    if (tier >= 2) {
+      const chop = (x) => 0.18 * (0.5 - 0.5 * Math.cos(4 * Math.PI * x + chopPhase * 2 * Math.PI));
+      envL += chop(c);
+      envR += chop(c - widthShift);
+    }
+
+    // The surf opens up as the swell builds: louder and brighter together.
+    const kL = onePole(variant.lp * (0.45 + 0.55 * envL));
+    const kR = onePole(variant.lp * (0.45 + 0.55 * envR));
+    lpL += kL * (noiseRng() * 2 - 1 - lpL);
+    lpR += kR * (noiseRng() * 2 - 1 - lpR);
+    left[i] = lpL * envL * gain;
+    right[i] = lpR * envR * gain;
+
+    // Tier 3 only: foam, a high hiss that only exists while the wave breaks.
+    if (tier === 3) {
+      foamL += 0.35 * (foamRng() * 2 - 1 - foamL);
+      foamR += 0.35 * (foamRng() * 2 - 1 - foamR);
+      left[i] += foamL * 0.05 * Math.pow(envL, 3);
+      right[i] += foamR * 0.05 * Math.pow(envR, 3);
+    }
+  }
+
+  // Both ends fade to silence, or the loop point clicks every repeat.
+  const fadeLen = Math.floor(0.12 * SAMPLE_RATE);
+  for (let i = 0; i < fadeLen; i++) {
+    const s = i / fadeLen;
+    left[i] *= s;
+    right[i] *= s;
+    left[totalSamples - 1 - i] *= s;
+    right[totalSamples - 1 - i] *= s;
+  }
+
+  return createWavBuffer({ left, right, sampleRate: SAMPLE_RATE });
+}
+
+module.exports = { generateOceanLoop };

package/src/synth/rain.js

@@ -0,0 +1,95 @@
+/**
+ * Rain Procedural Synth Engine
+ * A band-passed noise bed with sparse droplet transients on top. No notes, no
+ * rhythm, no melody - like `drone`, it is a floor of sound rather than music.
+ *
+ * Tiers add density, not movement: a heavier bed and more drops falling into
+ * the same piece, never a pulse.
+ */
+
+const {
+  SAMPLE_RATE,
+  sine,
+  makeRng,
+  rotate,
+  ornamentRng,
+  createWavBuffer
+} = require("./generator");
+
+// The seed picks how the rain sounds, not what it plays: where the band sits,
+// how many drops land, and how high they ring.
+const RAIN_VARIANTS = [
+  { hp: 800, lp: 5000, drops: 1.0, pitch: [2200, 4200], label: "steady" },
+  { hp: 500, lp: 3600, drops: 0.7, pitch: [1800, 3400], label: "roof" },
+  { hp: 1300, lp: 7000, drops: 1.3, pitch: [2800, 5200], label: "window" }
+];
+
+const DROP_POOL = 40;
+const DROPS_BY_TIER = { 1: 0.25, 2: 0.5, 3: 1.0 };
+// Band-passed noise is far hotter than the melodic genres, so this is made
+// down to their level (jazz: peak 0.64 / RMS 0.108) rather than up to it.
+const BED_GAIN = { 1: 0.27, 2: 0.33, 3: 0.44 };
+
+const onePole = (hz) => 1 - Math.exp((-2 * Math.PI * hz) / SAMPLE_RATE);
+
+function generateRainLoop(durationSec = 7.0, tier = 2, seed = 0, bar = 0) {
+  const orn = ornamentRng(seed);
+  const variant = rotate(orn, RAIN_VARIANTS, bar);
+
+  const totalSamples = Math.floor(SAMPLE_RATE * durationSec);
+  const left = new Float64Array(totalSamples);
+  const right = new Float64Array(totalSamples);
+
+  // 1. Bed: white noise through a high-pass and a low-pass. Drawn identically
+  //    at every tier, or the same seed would render a different bed as time
+  //    passes.
+  const noiseRng = makeRng(seed ^ 0x51ed270b);
+  const kLp = onePole(variant.lp);
+  const kHp = onePole(variant.hp);
+  let lpL = 0, lpR = 0, hpL = 0, hpR = 0;
+  const bedGain = BED_GAIN[tier] || BED_GAIN[2];
+
+  for (let i = 0; i < totalSamples; i++) {
+    lpL += kLp * (noiseRng() * 2 - 1 - lpL);
+    lpR += kLp * (noiseRng() * 2 - 1 - lpR);
+    hpL += kHp * (lpL - hpL);
+    hpR += kHp * (lpR - hpR);
+    left[i] += (lpL - hpL) * bedGain;
+    right[i] += (lpR - hpR) * bedGain;
+  }
+
+  // 2. Droplets. The whole pool is drawn up front, from a stream of its own,
+  //    and a tier only chooses how much of it to play - so tier 1 is tier 3's
+  //    drops with the rest left out, not a different shower.
+  const dropRng = ornamentRng(seed ^ 0x2545f491);
+  const pool = Array.from({ length: DROP_POOL }, () => ({
+    at: Math.floor(dropRng() * totalSamples),
+    hz: variant.pitch[0] + dropRng() * (variant.pitch[1] - variant.pitch[0]),
+    pan: dropRng(),
+    amp: 0.35 + 0.65 * dropRng() * dropRng()
+  }));
+  const count = Math.min(DROP_POOL, Math.round(DROP_POOL * variant.drops * (DROPS_BY_TIER[tier] || 0.5)));
+  const dropLen = Math.floor(0.045 * SAMPLE_RATE);
+  for (const d of pool.slice(0, count)) {
+    for (let j = 0; j < dropLen && d.at + j < totalSamples; j++) {
+      const t = j / SAMPLE_RATE;
+      const v = sine(d.hz * t) * Math.exp(-t / 0.009) * d.amp * 0.11;
+      left[d.at + j] += v * (1 - d.pan);
+      right[d.at + j] += v * d.pan;
+    }
+  }
+
+  // Both ends fade to silence, or the loop point clicks every repeat.
+  const fadeLen = Math.floor(0.12 * SAMPLE_RATE);
+  for (let i = 0; i < fadeLen; i++) {
+    const s = i / fadeLen;
+    left[i] *= s;
+    right[i] *= s;
+    left[totalSamples - 1 - i] *= s;
+    right[totalSamples - 1 - i] *= s;
+  }
+
+  return createWavBuffer({ left, right, sampleRate: SAMPLE_RATE });
+}
+
+module.exports = { generateRainLoop };