vibeaudio 0.8.1 → 0.9.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>
 
@@ -458,7 +460,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 +482,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 +498,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 +526,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 +551,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 +563,10 @@ 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 |
 | `--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 +585,13 @@ 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_UPDATE_CHECK=1   # Never ask npm whether a newer version is out
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.8.1",
+  "version": "0.9.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,10 @@ 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)
+      --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 +173,8 @@ function parseArgs(argv) {
   let render = null;
   let clearCacheFlag = false;
   let statusFlag = false;
+  let doctorFlag = false;
+  let notifyFlag = null;
   let stopFlag = false;
   let muteFlag = null;
   let muteMinutes = null;
@@ -281,6 +285,18 @@ function parseArgs(argv) {
       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 +439,8 @@ function parseArgs(argv) {
     render,
     clearCache: clearCacheFlag,
     status: statusFlag,
+    doctor: doctorFlag,
+    notify: notifyFlag,
     stop: stopFlag,
     mute: muteFlag,
     muteMinutes,
@@ -660,6 +678,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 +761,130 @@ 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)");
+  }
+
+  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;
+}
+
+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.
@@ -1210,6 +1353,8 @@ async function run() {
     render,
     clearCache: shouldClear,
     status: showStatus,
+    doctor: showDoctor,
+    notify: notifyChange,
     stop: shouldStop,
     mute: muteChange,
     muteMinutes,
@@ -1270,6 +1415,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 +1438,10 @@ async function run() {
     return printStatus();
   }
 
+  if (showDoctor) {
+    return printDoctor();
+  }
+
   if (shouldClear) {
     console.log(`\x1b[32m[vibeaudio] Cleared cache at ${clearCache()}\x1b[0m`);
     return;

package/src/hooks.js

@@ -15,7 +15,7 @@ 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 STATE_DIR = path.join(os.homedir(), ".vibeaudio");
 const PID_FILE = path.join(STATE_DIR, "daemon.pid");
@@ -679,6 +679,56 @@ function readPayload(done, timeoutMs = 500) {
   setTimeout(finish, timeoutMs).unref();
 }
 
+/**
+ * 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, raw = "" } = {}) {
   const id = sessionId(parsePayload(raw).session_id);
   // A turn that ends while paused for the user - a denied tool that nothing
@@ -691,7 +741,9 @@ function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChi
   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 });
@@ -742,6 +794,8 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
 
   writeSession(id, { ...session, waiting: waitKey(raw) });
   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;
 }
@@ -1018,7 +1072,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 +1136,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/player.js

@@ -14,6 +14,8 @@ 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");
@@ -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);
@@ -294,9 +306,21 @@ function seedDir(seed) {
   return path.join(CACHE_DIR, `s${seed >>> 0}`);
 }
 
-/** Keep a small working set of projects cached; regenerating costs ~100ms. */
+/**
+ * Keep a small working set of projects cached; regenerating costs ~100ms.
+ *
+ * A directory touched within PRUNE_MIN_AGE_MS is left alone whoever owns it.
+ * Another process may be part-way through a render there - it creates the
+ * directory, then writes its .tmp into it - and deleting it underneath that
+ * write throws ENOENT on the playback path, which is the one thing audio is
+ * never allowed to do. Time is the only signal we have across processes;
+ * skipping only our own directory would not have helped the other one.
+ */
+const PRUNE_MIN_AGE_MS = 10_000;
+
 function pruneSeedDirs(keep = 3) {
   try {
+    const now = Date.now();
     const dirs = fs
       .readdirSync(CACHE_DIR, { withFileTypes: true })
       .filter((e) => e.isDirectory() && /^s\d+$/.test(e.name))
@@ -307,6 +331,7 @@ function pruneSeedDirs(keep = 3) {
       .sort((a, b) => b.mtime - a.mtime);
 
     for (const stale of dirs.slice(keep)) {
+      if (now - stale.mtime < PRUNE_MIN_AGE_MS) continue;
       fs.rmSync(stale.full, { recursive: true, force: true });
     }
   } catch (e) {
@@ -549,6 +574,23 @@ function writeCacheFileAtomic(filePath, buffer) {
   } catch (e) {
     fs.rmSync(tmp, { force: true });
 
+    // The seed directory can be pruned by another process between our mkdir
+    // and this write. The mtime floor in pruneSeedDirs makes that rare rather
+    // than impossible, so recreate the directory and try once more - a second
+    // ENOENT would mean a prune landed inside a window of microseconds.
+    if (e.code === "ENOENT") {
+      try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(tmp, buffer);
+        fs.renameSync(tmp, filePath);
+        return;
+      } catch (retryErr) {
+        fs.rmSync(tmp, { force: true });
+        if (fs.existsSync(filePath)) return;
+        throw retryErr;
+      }
+    }
+
     // POSIX rename replaces the destination silently. Windows does not: it
     // fails with EPERM/EACCES when another process holds the destination
     // open - which is precisely the concurrent case this function exists to
@@ -789,6 +831,8 @@ class AudioPlayer {
 module.exports = {
   AudioPlayer,
   getAudioPath,
+  pruneSeedDirs,
+  writeCacheFileAtomic,
   getChimePath,
   clearCache,
   detectPlayer,

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 };