vibeaudio 0.10.0 → 0.11.1

package/README.md

@@ -4,7 +4,7 @@
 
 > **Procedural focus music while your AI coding tools think.**
 > Every project gets its own arrangement. Zero dependencies, zero audio files.
-> Works with Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI, Qwen Code, Aider — and any terminal command.
+> Works with Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI, Qwen Code, Windsurf, Aider — and any terminal command.
 
 **[Install](#-install)** · **[Agent hooks](#-agent-hooks-no-wrapper-needed)** · **[Genres](#-music-genres)** · **[Flags](#-options--flags)** · **[Troubleshooting](#-troubleshooting)** · **[Uninstall](#-uninstall)**
 
@@ -27,7 +27,7 @@ AI coding agents take 15–45 seconds to reason, read files and write code. Star
 * 🎛️ **Music that follows the work** ([reactive mode](#reactive-mode-opt-in), opt-in). Calm while the agent reads, fuller while it edits, busiest when it runs commands or hands work to sub-agents — you can hear *what* it's doing, not just for how long.
 * 🔔 **Outcome-aware chimes.** Ascending on success, a soft descending minor chord on failure, and **silence on `Ctrl+C`** — an abort is never reported as done.
 * ✋ **A "your turn" chime.** When Claude Code stops to ask permission (or an MCP server asks for input), the music pauses and a rising two-note chime asks for you; it picks back up once you've answered.
-* 🔌 **Universal drop-in.** Hooks for **Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI and Qwen Code**; MCP for **Claude Desktop and Antigravity**; the wrapper (`vibe <command>`) for anything else.
+* 🔌 **Universal drop-in.** Hooks for **Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI, Qwen Code and Windsurf**; MCP for **Claude Desktop and Antigravity**; the wrapper (`vibe <command>`) for anything else.
 
 <details>
 <summary><b>And the quieter four</b> — silence on fast commands, several sessions at once, exit codes, the HUD</summary>
@@ -223,7 +223,7 @@ Adding an entry to the launcher is one line in [`src/interactive.js`](src/intera
 
 ## 🪝 Agent Hooks (no wrapper needed)
 
-> **`--install-hooks` supports Claude Code, Codex, Cursor, Grok, Gemini CLI, GitHub Copilot CLI and Qwen Code.** Everything else uses the [wrapper or MCP](#-everything-else-claude-desktop-antigravity-via-mcp) instead.
+> **`--install-hooks` supports Claude Code, Codex, Cursor, Grok, Gemini CLI, GitHub Copilot CLI, Qwen Code and Windsurf.** Everything else uses the [wrapper or MCP](#-everything-else-claude-desktop-antigravity-via-mcp) instead.
 
 Wrapping (`vibe claude`) infers "the AI is thinking" from how long the process runs. Hooks know for certain — so music starts the moment you submit a prompt and stops the moment the agent finishes, with no grace-window guessing and no aliases.
 
@@ -236,12 +236,12 @@ vibe --genre jazz --volume 25 --install-hooks    # install, and save these as yo
 vibe --install-hooks --dry-run                   # show what would change, write nothing
 ```
 
-**It auto-detects.** With no `--tools`, VibeAudio wires up each supported agent it finds on your machine — one counts as present when its config directory exists or its CLI is on your `PATH`. `--tools claude,codex,cursor,grok,gemini,copilot,qwen` overrides that. Add `--dry-run` to see, per event, what would be added or changed in each file before anything is written.
+**It auto-detects.** With no `--tools`, VibeAudio wires up each supported agent it finds on your machine — one counts as present when its config directory exists or its CLI is on your `PATH`. `--tools claude,codex,cursor,grok,gemini,copilot,qwen,windsurf` overrides that. Add `--dry-run` to see, per event, what would be added or changed in each file before anything is written.
 
 That's it — run your agent normally, with no `vibe` prefix.
 
 <details>
-<summary><b>Which file and which events, per agent</b> — seven dialects, all written for you</summary>
+<summary><b>Which file and which events, per agent</b> — eight dialects, all written for you</summary>
 
 Each tool spells its events its own way, and VibeAudio writes whichever dialect the file expects:
 
@@ -254,6 +254,7 @@ Each tool spells its events its own way, and VibeAudio writes whichever dialect
 | **Gemini CLI** | `~/.gemini/settings.json` | `BeforeAgent` | `AfterAgent` | `BeforeTool` |
 | **Copilot CLI** | `~/.copilot/hooks/vibeaudio.json` | `UserPromptSubmit` | `Stop` | `PreToolUse` |
 | **Qwen Code** | `~/.qwen/settings.json` | `UserPromptSubmit` | `Stop` | `PreToolUse` |
+| **Windsurf** | `~/.codeium/windsurf/hooks.json` | `pre_user_prompt` | `post_cascade_response` | `pre_run_command` |
 
 Where an agent reports more than start and stop, VibeAudio listens for that too — and only where the event was confirmed against the tool itself:
 
@@ -264,7 +265,7 @@ Where an agent reports more than start and stop, VibeAudio listens for that too
 | **Gemini CLI** | `Notification` (tool permission) | `AfterTool` | — | `SessionEnd` |
 | **Copilot CLI** | `Notification` (permission prompt) | `PostToolUse`, `PostToolUseFailure` | — | `SessionEnd` |
 | **Qwen Code** | `PermissionRequest` | `PostToolUse`, `PostToolUseFailure` | `StopFailure` | `SessionEnd` |
-| **Cursor, Grok** | — | — | — | — |
+| **Cursor, Grok, Windsurf** | — | — | — | — |
 
 </details>
 
@@ -302,7 +303,7 @@ Sessions with no id in their payload share a single slot, so they behave as one.
 
 </details>
 
-> **No restart needed, even mid-session — for Claude Code, Codex, Cursor and Grok.** Each re-reads its hook file every time a hook fires, so changes land on your **next prompt**. A daemon already playing keeps its old settings until that prompt replaces it — at most the tail of one turn. Whether an open Gemini CLI, Copilot CLI or Qwen Code session does the same hasn't been checked, so start a new session there to be sure.
+> **No restart needed, even mid-session — for Claude Code, Codex, Cursor and Grok.** Each re-reads its hook file every time a hook fires, so changes land on your **next prompt**. A daemon already playing keeps its old settings until that prompt replaces it — at most the tail of one turn. Whether an open Gemini CLI, Copilot CLI, Qwen Code or Windsurf session does the same hasn't been checked, so start a new session there to be sure.
 
 > **The Claude Code desktop app is covered too**, not just the terminal — both read the same `~/.claude/settings.json`. (The separate **Claude Desktop** chat app is a different product with no hooks; that one needs [MCP](#-everything-else-claude-desktop-antigravity-via-mcp).)
 
@@ -409,9 +410,9 @@ Changes land at the next loop boundary, so it shifts musically rather than cutti
 
 ## 🖥️ Everything Else (Claude Desktop, Antigravity… via MCP)
 
-**Claude Code, [Codex](https://github.com/openai/codex), [Cursor](https://cursor.com/docs/hooks), [Grok](https://docs.x.ai/build/features/hooks), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Copilot CLI](https://docs.github.com/en/copilot/reference/hooks-configuration) and [Qwen Code](https://github.com/QwenLM/qwen-code) have hook systems, and `--install-hooks` writes to all seven** — use [hooks](#-agent-hooks-no-wrapper-needed) there, they're strictly better. This section is for everything else. MCP is the way in: it's plain stdio JSON-RPC, so the setup is identical everywhere and only the config file differs.
+**Claude Code, [Codex](https://github.com/openai/codex), [Cursor](https://cursor.com/docs/hooks), [Grok](https://docs.x.ai/build/features/hooks), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Copilot CLI](https://docs.github.com/en/copilot/reference/hooks-configuration), [Qwen Code](https://github.com/QwenLM/qwen-code) and [Windsurf](https://docs.devin.ai/desktop/cascade/hooks) have hook systems, and `--install-hooks` writes to all eight** — use [hooks](#-agent-hooks-no-wrapper-needed) there, they're strictly better. This section is for everything else. MCP is the way in: it's plain stdio JSON-RPC, so the setup is identical everywhere and only the config file differs.
 
-> **This is weaker than hooks, by nature.** Hooks fire on an event; MCP tools are *model-invoked*, so the assistant has to decide to call `vibe_play` and remember `vibe_stop`. Expect the occasional silent turn — say "play some focus music while you work on this" if you want it reliably. **On any of the seven agents above, use [hooks](#-agent-hooks-no-wrapper-needed) instead.**
+> **This is weaker than hooks, by nature.** Hooks fire on an event; MCP tools are *model-invoked*, so the assistant has to decide to call `vibe_play` and remember `vibe_stop`. Expect the occasional silent turn — say "play some focus music while you work on this" if you want it reliably. **On any of the eight agents above, use [hooks](#-agent-hooks-no-wrapper-needed) instead.**
 
 Use an **absolute path**, not the bare `vibe` command: GUI apps launched from Finder don't inherit your shell's `PATH`, and version managers like `fnm` or `nvm` put `vibe` on a per-shell path that won't resolve. Print yours with:
 
@@ -591,7 +592,7 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--clear-cache` | Delete all cached audio, then exit | — |
 | `--mcp` | Run as an MCP stdio server for desktop apps | — |
 | `--install-hooks` | Wire music into your agent's hooks (no wrapper needed) | — |
-| `--tools <list>` | With `--install-hooks`: `claude,codex,cursor,grok,gemini,copilot,qwen` | auto-detect |
+| `--tools <list>` | With `--install-hooks`: `claude,codex,cursor,grok,gemini,copilot,qwen,windsurf` | auto-detect |
 | `--reactive` | With `--install-hooks`: intensity follows the tool in use | off |
 | `--dry-run` | With `--install-hooks`: show what would change in each file, write nothing | off |
 | `--uninstall-hooks` | Remove the hooks again, from every agent | — |
@@ -612,6 +613,7 @@ export VIBE_DISABLE=1           # Mute, without uninstalling anything
 export VIBE_NOTIFY=1            # Desktop banner naming the project, for this shell
 export VIBE_NO_HISTORY=1        # Do not log finished turns (what --report reads)
 export VIBE_NO_UPDATE_CHECK=1   # Never ask npm whether a newer version is out
+export VIBE_NO_FADE=1           # macOS: play with plain afplay, no fade in/out
 ```
 
 **`VIBE_DISABLE=1` is for a shell you always want quiet** — a CI job, a shared machine, a terminal profile you keep silent. It's read at playback time and covers hooks, wrapper and MCP alike.
@@ -738,7 +740,7 @@ rm -rf ~/.vibeaudio             # 3. optional: cached audio, saved settings, dae
 
 Step 1 also **stops a background player that's still going**. That matters: once the hooks are gone nothing will ever send the `Stop` event, and after step 2 there's no `vibe` left to stop it with — music would simply play on until its 15-minute cap. If you ever need to do it by hand: `pkill -f "vibeaudio.js --daemon"`.
 
-> **Order matters.** `npm rm -g` deletes the binary but not your hook config. Removing the package first strands hook entries that point at a path that no longer exists, and your agent will run a failing hook on every prompt. If you already did it in the wrong order, reinstall, run `vibe --uninstall-hooks`, then remove again — or delete the `vibeaudio` entries from `~/.claude/settings.json`, `~/.codex/hooks.json`, `~/.cursor/hooks.json`, `~/.gemini/settings.json` and `~/.qwen/settings.json` by hand, and delete `~/.grok/hooks/vibeaudio.json`, `~/.copilot/hooks/vibeaudio.json` and `~/.claude/commands/vibe.md`.
+> **Order matters.** `npm rm -g` deletes the binary but not your hook config. Removing the package first strands hook entries that point at a path that no longer exists, and your agent will run a failing hook on every prompt. If you already did it in the wrong order, reinstall, run `vibe --uninstall-hooks`, then remove again — or delete the `vibeaudio` entries from `~/.claude/settings.json`, `~/.codex/hooks.json`, `~/.cursor/hooks.json`, `~/.gemini/settings.json`, `~/.qwen/settings.json` and `~/.codeium/windsurf/hooks.json` by hand, and delete `~/.grok/hooks/vibeaudio.json`, `~/.copilot/hooks/vibeaudio.json` and `~/.claude/commands/vibe.md`.
 
 Step 3 reclaims disk — the audio cache, pruned to the 3 most recent projects — and drops your saved genre and volume. Both come back on their own, so skip it if you're reinstalling.
 
@@ -746,7 +748,7 @@ Step 3 reclaims disk — the audio cache, pruned to the 3 most recent projects
 
 | Leftover | Why, and how to remove it |
 | :--- | :--- |
-| `*.vibeaudio.bak` next to each shared hook config | Your config as it was before the first install — one each for Claude Code, Codex, Cursor, Gemini CLI and Qwen Code. A safety net we won't delete for you; `rm` them once you're happy the real files are correct, and `vibe --uninstall-hooks` prints the path of every one it finds. (Grok and Copilot CLI leave nothing: their files are ours alone, so uninstall deletes them outright.) |
+| `*.vibeaudio.bak` next to each shared hook config | Your config as it was before the first install — one each for Claude Code, Codex, Cursor, Gemini CLI, Qwen Code and Windsurf. A safety net we won't delete for you; `rm` them once you're happy the real files are correct, and `vibe --uninstall-hooks` prints the path of every one it finds. (Grok and Copilot CLI leave nothing: their files are ours alone, so uninstall deletes them outright.) |
 | `vibeaudio` entries in other apps' MCP configs | VibeAudio never edits those files, so it can't clean them either. Drop the entry from [whichever config you added it to](#-everything-else-claude-desktop-antigravity-via-mcp). |
 
 Apart from those two, the three commands above remove everything VibeAudio writes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "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

@@ -85,7 +85,7 @@ Procedural focus music while your AI coding tools think.
       --clear-cache            Delete cached audio, then exit
       --mcp                    Run as Model Context Protocol (MCP) server for Desktop apps
       --install-hooks          Wire music into your agent's hooks (no wrapper needed)
-      --tools <list>           With --install-hooks: claude,codex,cursor,grok,gemini,copilot,qwen (auto-detect)
+      --tools <list>           With --install-hooks: claude,codex,cursor,grok,gemini,copilot,qwen,windsurf (auto-detect)
       --reactive               With --install-hooks: intensity follows the tool in use
       --dry-run                With --install-hooks: show what would change, write nothing
       --uninstall-hooks        Remove the hooks again, from every agent
@@ -1085,6 +1085,7 @@ function detectAiTools(hooked = new Set()) {
     { cmd: "gemini", name: "Gemini CLI", integration: viaHooks("gemini") },
     { cmd: "copilot", name: "GitHub Copilot CLI", integration: viaHooks("copilot") },
     { cmd: "qwen", name: "Qwen Code", integration: viaHooks("qwen") },
+    { cmd: "windsurf", name: "Windsurf", integration: viaHooks("windsurf") },
     { cmd: "aider", name: "Aider", integration: "wrapper — vibe aider" },
     { cmd: "ollama", name: "Ollama", integration: "wrapper — vibe ollama run <model>" }
   ];

package/src/hooks.js

@@ -100,7 +100,14 @@ function payloadToolName(raw) {
   const payload = parsePayload(raw);
   // Claude Code, Codex and Cursor send tool_name; Grok sends toolName.
   // Reading only one of them would silently pin that agent to tier 2.
-  return String(payload.tool_name || payload.toolName || "");
+  // Windsurf names no tool: the event is the signal, and only the shell one is wired.
+  const byEvent = payload.agent_action_name === "pre_run_command" ? "Shell" : "";
+  return String(payload.tool_name || payload.toolName || byEvent);
+}
+
+// Windsurf calls the conversation `trajectory_id`.
+function payloadSession(payload) {
+  return payload.session_id || payload.trajectory_id;
 }
 
 /**
@@ -292,6 +299,24 @@ const TARGETS = {
     // Unlike the four above, not verified to re-read hooks mid-session.
     liveReload: false,
     note: "Not checked whether an open Qwen Code session reloads hooks — start a new one to be sure."
+  },
+  windsurf: {
+    name: "Windsurf",
+    cmd: "windsurf",
+    // Checked against Windsurf's hooks documentation only: it was not installed
+    // here, so nothing was run. User-level file, a flat {command} entry with no
+    // timeout field, and the conversation named `trajectory_id` rather than
+    // session_id. post_cascade_response is the end-of-reply event; Windsurf has
+    // no permission-dialog, failure or session-end event, so none is wired, and
+    // its pre-tool events are per kind - pre_run_command is the one reactive
+    // mode listens to.
+    file: () => path.join(os.homedir(), ".codeium", "windsurf", "hooks.json"),
+    events: { start: "pre_user_prompt", stop: "post_cascade_response", tool: "pre_run_command" },
+    entry: (command) => ({ command }),
+    commands: (entry) => (entry.command ? [entry.command] : []),
+    seed: () => ({}),
+    liveReload: false,
+    note: "Windsurf's hooks do not load in Restricted Mode, and whether an open session reloads them is not documented — start a new one to be sure."
   }
 };
 
@@ -425,7 +450,44 @@ function fileSize(file) {
 function newTurn(raw) {
   const payload = parsePayload(raw);
   const transcript = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
-  return { session: String(payload.session_id || ""), transcript, offset: transcript ? fileSize(transcript) : 0 };
+  const offset = transcript ? fileSize(transcript) : 0;
+  return { session: String(payloadSession(payload) || ""), transcript, offset, blocked: blockedJustBefore(transcript, offset) };
+}
+
+const BLOCK_LOOKBACK_MS = 3000;
+
+/**
+ * Whether another hook has already rejected this very prompt. Hooks run side
+ * by side and a native blocker is faster to start than we are, so its transcript
+ * entry can land *before* the offset taken above - where the daemon, which reads
+ * only what follows, would never see it. Looked at the tail instead, and only
+ * for an entry stamped within the last moments, so an earlier blocked prompt
+ * does not silence this one.
+ */
+function blockedJustBefore(transcript, offset) {
+  if (!transcript || !offset) return false;
+  try {
+    const len = Math.min(offset, 16384);
+    const fd = fs.openSync(transcript, "r");
+    const buf = Buffer.alloc(len);
+    try {
+      fs.readSync(fd, buf, 0, len, offset - len);
+    } finally {
+      fs.closeSync(fd);
+    }
+    const lines = buf.toString("utf8").split("\n");
+    if (len < offset) lines.shift(); // Began mid-line.
+    return lines.some((line) => {
+      if (!isInterruptEntry(line)) return false;
+      try {
+        return Date.now() - Date.parse(JSON.parse(line).timestamp) <= BLOCK_LOOKBACK_MS;
+      } catch (e) {
+        return false;
+      }
+    });
+  } catch (e) {
+    return false;
+  }
 }
 
 // The id ends up in a file name.
@@ -485,11 +547,16 @@ const working = (sessions) => sessions.filter((s) => s.waiting == null);
 // Claude Code's entry for Esc / the stop button: a user message whose text is
 // "[Request interrupted by user]" or "... for tool use]".
 const INTERRUPT_MARK = "[Request interrupted by user";
+const BLOCKED_MARK = "UserPromptSubmit operation blocked by hook";
 
 function isInterruptEntry(line) {
-  if (!line.includes(INTERRUPT_MARK)) return false; // Cheap filter before parsing.
+  if (!line.includes(INTERRUPT_MARK) && !line.includes(BLOCKED_MARK)) return false; // Cheap filter before parsing.
   try {
     const entry = JSON.parse(line);
+    // A prompt another hook blocked: hooks run side by side, so ours had already
+    // started the music, and no Stop will ever follow. The turn is over before
+    // it began, which is the same silent end as an interrupt.
+    if (entry.type === "system" && typeof entry.content === "string") return entry.content.startsWith(BLOCKED_MARK);
     if (entry.type !== "user" || !entry.message) return false;
     // Structural, not substring: a transcript that merely quotes the phrase -
     // in a tool result, a file, a prompt about this very feature - is not one.
@@ -623,6 +690,7 @@ function spawnDaemon(genre, volume, reactive) {
  * music carries on: restarting it would cut every other session's stream.
  */
 function hookStart(genre, volume, { reactive = false, turn = null } = {}) {
+  if (turn && turn.blocked) return null; // Rejected before it began: nothing to play for.
   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, started: Date.now(), blockedMs: 0 });
@@ -731,7 +799,7 @@ function notify(raw, message) {
 }
 
 function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChime = false, genre, raw = "" } = {}) {
-  const id = sessionId(parsePayload(raw).session_id);
+  const id = sessionId(payloadSession(parsePayload(raw)));
   // A turn that ends while paused for the user - a denied tool that nothing
   // resumed after - still finished, so its session counts either way.
   const session = readSession(id);
@@ -796,7 +864,7 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
   const type = payload.notification_type ?? payload.notificationType;
   if (type !== undefined && !WAIT_NOTIFICATIONS.has(String(type))) return false;
 
-  const id = sessionId(payload.session_id);
+  const id = sessionId(payloadSession(payload));
   const session = readSession(id);
   if (!session || session.waiting != null) return false;
 
@@ -822,7 +890,7 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
  * job. Match on tool_input as well if that ever shows up in practice.
  */
 function hookResume(raw, genre, volume, { reactive = false } = {}) {
-  const id = sessionId(parsePayload(raw).session_id);
+  const id = sessionId(payloadSession(parsePayload(raw)));
   const session = readSession(id);
   if (!session || session.waiting == null) return false; // Not waiting - the common case, on every tool call.
   // An empty key is a wait that named nothing (a Notification): the next tool
@@ -845,7 +913,7 @@ function hookResume(raw, genre, volume, { reactive = false } = {}) {
  * applies.
  */
 function hookEnd(raw) {
-  const id = sessionId(parsePayload(raw).session_id);
+  const id = sessionId(payloadSession(parsePayload(raw)));
   if (!readSession(id)) return false;
 
   fs.rmSync(sessionFile(id), { force: true });

package/src/interactive.js

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

package/src/mac-player.jxa

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

package/src/player.js

@@ -110,6 +110,18 @@ const PLAYER_CANDIDATES = [
 let cachedPlayer;
 let warnedNoPlayer = false;
 
+// macOS: one long-lived AVAudioPlayer process instead of an afplay per loop,
+// which is what lets music fade in and out rather than start and end mid-note.
+// afplay stays the fallback: a helper that cannot start is not worth a silent
+// run, and it is used for the rest of the process once one has failed.
+const MAC_HELPER = path.join(__dirname, "mac-player.jxa");
+const FADE_IN_S = 0.5;
+let helperFailed = false;
+
+function helperUsable(backend) {
+  return process.platform === "darwin" && backend.cmd === "afplay" && !helperFailed && !process.env.VIBE_NO_FADE;
+}
+
 function detectPlayer() {
   if (cachedPlayer !== undefined) return cachedPlayer;
 
@@ -708,6 +720,7 @@ class AudioPlayer {
   constructor() {
     this.isPlaying = false;
     this.procs = new Set();
+    this.helper = null;
     this.startTime = 0;
     this.genre = "lofi";
     this.volume = 0.42;
@@ -789,6 +802,13 @@ class AudioPlayer {
     const audioFile = getAudioPath(this.genre, this.currentTier, this.seed, gain, this.bar);
     // Advanced after the choice, so the bar that plays first is bar 0.
     this.bar = (this.bar + 1) % LOOP_BARS;
+    if (!(helperUsable(backend) && this.playViaHelper(audioFile, backend))) this.spawnLoop(audioFile, backend);
+
+    const durationMs = wavDurationMs(audioFile) || 6500;
+    this.nextTimer = setTimeout(() => this.playLoop(), Math.max(250, durationMs - LOOP_OVERLAP_MS));
+  }
+
+  spawnLoop(audioFile, backend) {
     const proc = spawn(backend.cmd, backend.args(audioFile, this.volume), { stdio: "ignore" });
 
     this.procs.add(proc);
@@ -798,12 +818,55 @@ class AudioPlayer {
       this.isPlaying = false;
       warnNoPlayer();
     });
+  }
 
-    const durationMs = wavDurationMs(audioFile) || 6500;
-    this.nextTimer = setTimeout(() => this.playLoop(), Math.max(250, durationMs - LOOP_OVERLAP_MS));
+  /**
+   * Hands one loop to the macOS helper, starting it on first use. Returns false
+   * when the helper could not be started, so the caller plays it with afplay.
+   * A helper that dies while we are playing is dropped and the loop that was
+   * meant for it replayed, so a failure costs one restart, not the music.
+   */
+  playViaHelper(audioFile, backend) {
+    try {
+      if (!this.helper) {
+        const helper = spawn("osascript", ["-l", "JavaScript", MAC_HELPER], { stdio: ["pipe", "ignore", "ignore"] });
+        helper.stdin.on("error", () => {}); // EPIPE once it is gone.
+        const dropped = () => {
+          if (this.helper !== helper) return;
+          this.helper = null;
+          helperFailed = true;
+          if (this.isPlaying) this.spawnLoop(audioFile, backend);
+        };
+        helper.on("error", dropped);
+        helper.on("exit", dropped);
+        this.helper = helper;
+        this.helperFirst = true;
+      }
+      const fade = this.helperFirst ? FADE_IN_S : 0; // Later loops carry their own boundary fades.
+      this.helperFirst = false;
+      this.helper.stdin.write(`play ${this.volume} ${fade} ${audioFile}\n`);
+      return true;
+    } catch (e) {
+      helperFailed = true;
+      this.helper = null;
+      return false;
+    }
   }
 
   killProcs() {
+    // Closing the helper's input is the stop: it fades out and exits on its own,
+    // so the music ends on a decay, and a daemon that dies without cleanup closes
+    // the pipe just the same.
+    if (this.helper) {
+      const helper = this.helper;
+      this.helper = null;
+      try {
+        helper.stdin.end();
+        helper.unref();
+      } catch (e) {
+        // Already gone.
+      }
+    }
     for (const proc of this.procs) {
       try {
         proc.kill("SIGTERM");