vibeaudio 0.11.1 → 0.13.0

package/README.md

@@ -8,9 +8,11 @@
 
 **[Install](#-install)** · **[Agent hooks](#-agent-hooks-no-wrapper-needed)** · **[Genres](#-music-genres)** · **[Flags](#-options--flags)** · **[Troubleshooting](#-troubleshooting)** · **[Uninstall](#-uninstall)**
 
-> **🔊 [Listen to every genre →](https://kiril6.github.io/vibeaudio/)** — hear all 8 genres, the tier escalation, and the three chimes, rendered from the real synth.
+> **🔊 [Listen to every genre →](https://kiril6.github.io/vibeaudio/)** — hear all 10 genres, the tier escalation, and the three chimes, rendered from the real synth.
 
 > **In a hurry?** `npm i -g vibeaudio`, then `vibe --install-hooks`. Your next prompt has music.
+>
+> **Claude Code only?** Skip npm: `claude plugin marketplace add kiril6/vibeaudio`, then `claude plugin install vibeaudio@vibeaudio` ([details](#as-a-claude-code-plugin)).
 
 ---
 
@@ -25,7 +27,9 @@ AI coding agents take 15–45 seconds to reason, read files and write code. Star
 * 📈 **Escalating layers.** Tier 1 (0–15s) gentle intro → Tier 2 (15–45s) main groove → Tier 3 (45s+) deep focus. You can hear how deep into the task the agent is.
 * 🔁 **A phrase, not a loop.** Each piece is three bars that rotate through your project's own progressions, so a long turn moves through a ~21-second phrase instead of replaying one 7-second bar for half an hour.
 * 🎛️ **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.
+* 🌅 **It fades, it doesn't cut.** On macOS the music eases in and out instead of starting and stopping mid-note, and `vibe --volume` reaches music that is already playing within a second.
 * 🔔 **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 heartbeat when an agent looks stuck.** If 4 of a session's last 8 tool calls fail — the test-edit-test loop that goes nowhere — a soft pulse on the music's tonic joins the music until things start passing again. It's rare by design: on 4,497 real turns it fired in under 1%.
 * ✋ **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, Qwen Code and Windsurf**; MCP for **Claude Desktop and Antigravity**; the wrapper (`vibe <command>`) for anything else.
 
@@ -276,7 +280,7 @@ Where an agent reports more than start and stop, VibeAudio listens for that too
 | | |
 | :--- | :--- |
 | **Five agents tell you when they're waiting on you** | When a permission dialog opens the music stops rather than sounding busy while the agent is stuck on you, and it resumes once the thing you answered has run. Claude Code covers the terminal, desktop app and IDEs alike, plus MCP servers asking for input. Copilot CLI's own `PermissionRequest` fires before *every* permission check — dialog or not — so VibeAudio listens for its permission-prompt notification instead. Cursor and Grok have no such event that's been verified, so they keep playing through a prompt. |
-| **Claude Code turns that never reach `Stop` still end the music** | An API error or rate limit ends the turn with `StopFailure` instead, which plays the failure chime. Interrupting (Esc, or the stop button in the desktop app) fires no hook at all, so the background player watches the session transcript for Claude Code's interrupt entry and stops silently within half a second — whether the agent was writing or running a tool. Closing the session mid-turn stops it too — but only if that session started the music, so closing an idle terminal never silences another one. |
+| **Claude Code turns that never reach `Stop` still end the music** | An API error or rate limit ends the turn with `StopFailure` instead, which plays the failure chime. Interrupting (Esc, or the stop button in the desktop app) fires no hook at all, so the background player watches the session transcript for Claude Code's interrupt entry and stops silently within half a second — whether the agent was writing or running a tool. A prompt that another hook blocks (a token-saving proxy, say) never reaches `Stop` either, so the same watcher ends the music on Claude Code's "prompt blocked" entry — or never starts it, when the blocker was quicker than we were. Closing the session mid-turn stops it too — but only if that session started the music, so closing an idle terminal never silences another one. |
 | **Codex asks you to trust the hook once** | Codex keeps a per-hook trust hash in `~/.codex/config.toml` and won't run a hook it hasn't been told to trust, so the install isn't live until you approve each one the first time it fires. |
 | **Only Cursor can play the failure chime** | Its stop event reports whether the turn completed, aborted or errored. The others send no verdict, so a turn there always ends on the success chime — VibeAudio won't invent a failure the agent never claimed. |
 | **Grok and Copilot CLI get a file of their own** | Each reads every `*.json` in its `hooks/` directory, so VibeAudio writes `vibeaudio.json` rather than merging into anyone else's — which makes uninstalling it a delete, and leaves no backup file behind. Copilot's honours `COPILOT_HOME`. |
@@ -309,6 +313,22 @@ Sessions with no id in their payload share a single slot, so they behave as one.
 
 > **One player is shared.** Prompt two agents at once and the last prompt owns the music. One person, one set of speakers — deliberate, not a limitation being worked around.
 
+### As a Claude Code plugin
+
+If Claude Code is the only agent you use, the plugin installs the same hooks with no npm step:
+
+```bash
+claude plugin marketplace add kiril6/vibeaudio
+claude plugin install vibeaudio@vibeaudio
+```
+
+It needs Node 18+ on your `PATH` (the hooks run `node`), and it also adds `/vibeaudio:vibe`, the plugin's spelling of [`/vibe`](#vibe-inside-claude-code). Update with `claude plugin update vibeaudio@vibeaudio`; remove with `claude plugin uninstall vibeaudio@vibeaudio` (music already playing stops on its own within 15 minutes, or run `/vibeaudio:vibe stop` first).
+
+- **Settings are the same file.** `vibe --genre jazz` and the rest work as always, but the `vibe` command comes from `npm i -g vibeaudio`; the plugin alone puts nothing on your `PATH`. Use `/vibeaudio:vibe genre jazz` instead.
+- **Both at once is safe.** If `--install-hooks` has also been run, the plugin's hooks step aside and the installed ones play, so there's no double chime. Remove the installed hooks first if you want the plugin to own it.
+- **Claude Code only.** Codex, Cursor, Gemini and the others still use `vibe --install-hooks`.
+- **Not reactive.** `--reactive` is an `--install-hooks` option; the plugin doesn't carry it.
+
 ### `/vibe` inside Claude Code
 
 Installing the Claude Code hooks also adds a `/vibe` command (`~/.claude/commands/vibe.md`), so you can control the music without leaving the session:
@@ -350,7 +370,7 @@ vibe --reactive --install-hooks     # on
 vibe --install-hooks                # off again
 ```
 
-Music already playing keeps the old genre until the next prompt swaps the daemon — `vibe --stop` cuts it short.
+Music already playing keeps the old genre until the next prompt swaps the daemon — `vibe --stop` cuts it short. A new **volume** is the exception: the music playing now eases to it within a second.
 
 Removing them is one command:
 
@@ -367,14 +387,24 @@ Hooks log each finished turn — which project, how long, how it ended, and how
   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
+  Back to it        41s  median from done to your next prompt, 27 times
+                    32s with a chime  1m 50s without (muted or --no-chime)
 ```
 
-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.
+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. "Back to it" is the other direction: how long a finished turn sat before your next prompt in the same session — gaps over 30 minutes count as breaks and are left out. Once both sides have five turns, it is split by whether a chime announced the turn, so you can see what the chime is worth to you. 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.
 
+### When an agent looks stuck
+
+The worst stretch of agent work is twenty minutes of the same thing failing while the music says all is well. So when **4 of a session's last 8 tool calls fail**, a soft heartbeat — two low beats about once a second, on the tonic of your genre — joins the music at the next loop boundary, and leaves once enough calls succeed. With `--notify` on, you also get one banner when the session crosses the line ("api: looks stuck"), not one per failure.
+
+The threshold was picked against 4,497 real Claude Code turns (46,032 tool calls). It fires in about 1% of turns, at around minute 3, and those turns typically ran for another 3 minutes — time you could have spent stepping in. "3 in a row" was rejected because the usual loop has a successful edit between every failing test run. Each new prompt starts with a clean slate, and an interrupt (Esc) never counts as a failure.
+
+It needs the agent to report failed tool calls, which **Claude Code, Copilot CLI and Qwen Code** do (`PostToolUseFailure`). Codex, Cursor, Gemini, Grok and Windsurf don't, so for them the music never adds the heartbeat.
+
 ### Reactive mode (opt-in)
 
 ```bash
@@ -408,6 +438,35 @@ Changes land at the next loop boundary, so it shifts musically rather than cutti
 
 ---
 
+### Build on it: `vibe --state` and `vibe --events`
+
+The hard part of VibeAudio isn't the music. It's turning eight agents' different hook events into one set of states that mean the same thing everywhere. The music is one consumer of those states, and anything else can be another: a smart light, a menu bar icon, a tmux status line, a Stream Deck key.
+
+```bash
+vibe --state
+# {"v":1,"status":"waiting","sessions":[{"session":"…","project":"/work/api","state":"waiting","since":1791026124771,"tool":"Bash"}]}
+```
+
+Each session is `working`, `stuck` (4 of its last 8 tool calls failed) or `waiting` (on you: a permission dialog or a question). `status` is the machine's overall state: the most urgent of its sessions, in the order `waiting` > `stuck` > `working` > `idle`. One session waiting on you matters more than three working.
+
+`vibe --events` prints that snapshot once, then a JSON line for every change, as it happens:
+
+```json
+{"v":1,"at":1791026130000,"event":"waiting","session":"…","project":"/work/api","tool":"Bash","status":"waiting"}
+```
+
+Events: `started`, `waiting`, `resumed`, `stuck`, `recovered`, `finished` (with `outcome`: `success` or `failure`), `interrupted`, `ended`. Every line also carries `status`, the machine's state after the event, so a consumer that only cares about the overall state can read that one field. Some examples:
+
+```bash
+# tmux: show the state in the status bar
+set -g status-right '#(vibe --state | jq -r .status)'
+
+# macOS: say it out loud when any agent needs you
+vibe --events | jq --unbuffered -r 'select(.event=="waiting") | .project' | while read p; do say "$(basename "$p") needs you"; done
+```
+
+The stream is a local file (`~/.vibeaudio/events.jsonl`, rotated at 256 KB), so it never leaves your machine. It keeps updating while you're muted, because a mute silences sound and a light isn't sound. The `v` field is the format version, and any breaking change will increment it.
+
 ## 🖥️ 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), [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.
@@ -586,6 +645,8 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--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 |
+| `--state` | What every agent on the machine is doing, as one line of JSON: `idle`, `working`, `stuck` or `waiting` | — |
+| `--events` | Stream agent state changes as JSON lines, starting with the current state, until stopped | — |
 | `--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 | — |
@@ -681,7 +742,7 @@ This needs a PulseAudio-compatible sound server on **your local machine**: a Lin
 If the second connection fails with the socket "already in use", an earlier session left it behind: `rm /tmp/vibe-pulse.sock` on the server, or set `StreamLocalBindUnlink yes` in the server's `sshd_config`. If `paplay` says access denied, your local PulseAudio requires its cookie — copy `~/.config/pulse/cookie` to the same path on the server.
 
 **Volume flag does nothing**
-Shouldn't happen any more — where the player can't attenuate (`aplay`, PowerShell), the gain is baked into the audio instead. A `--volume` change lands at the next loop boundary, and on hooks at your next prompt; `vibe --status` shows the volume in effect and what set it.
+Shouldn't happen any more — where the player can't attenuate (`aplay`, PowerShell), the gain is baked into the audio instead. A `--volume` change reaches music already playing within a second on macOS hooks (it eases there), at the next loop boundary elsewhere, and in the wrapper or MCP on their next run; `vibe --status` shows the volume in effect and what set it.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.11.1",
+  "version": "0.13.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",
@@ -10,6 +10,7 @@
   "scripts": {
     "test": "node test/test-synth.js",
     "start": "node bin/vibeaudio.js",
+    "version": "node -e \"const f='.claude-plugin/plugin.json',j=require('./'+f);j.version=require('./package.json').version;require('fs').writeFileSync(f,JSON.stringify(j,null,2)+'\\n')\" && git add .claude-plugin/plugin.json",
     "postinstall": "node scripts/postinstall.js"
   },
   "publishConfig": {

package/src/cli.js

@@ -78,6 +78,8 @@ Procedural focus music while your AI coding tools think.
       --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)
+      --state                  Print what every agent is doing as JSON: idle, working, stuck or waiting
+      --events                 Stream agent state changes as JSON lines, until stopped
       --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)
@@ -174,6 +176,8 @@ function parseArgs(argv) {
   let render = null;
   let clearCacheFlag = false;
   let statusFlag = false;
+  let stateFlag = false;
+  let eventsFlag = false;
   let doctorFlag = false;
   let notifyFlag = null;
   let reportDays = null;
@@ -183,6 +187,8 @@ function parseArgs(argv) {
   let hookAction = null;
   let mcp = false;
   let reactive = false;
+  let followVolume = false;
+  let plugin = false;
   let here_flag = false;
   let dryRun = false;
   let tools = null;
@@ -287,6 +293,13 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--state" || arg === "--events") {
+      if (arg === "--state") stateFlag = true;
+      else eventsFlag = true;
+      i += 1;
+      continue;
+    }
+
     if (arg === "--report") {
       // Optional window in days, like --mute's minutes: `vibe --report 30`.
       i += 1;
@@ -352,6 +365,22 @@ function parseArgs(argv) {
       continue;
     }
 
+    // Internal, set by the hooks: a daemon with no volume of its own follows
+    // the saved one while it plays.
+    if (arg === "--follow-volume") {
+      followVolume = true;
+      i += 1;
+      continue;
+    }
+
+    // Internal, set by the plugin's hooks.json: yield to hooks that
+    // --install-hooks already wrote, so both being present is not a double chime.
+    if (arg === "--plugin") {
+      plugin = true;
+      i += 1;
+      continue;
+    }
+
     if (arg === "--dry-run") {
       dryRun = true;
       i += 1;
@@ -452,6 +481,8 @@ function parseArgs(argv) {
     render,
     clearCache: clearCacheFlag,
     status: statusFlag,
+    state: stateFlag,
+    events: eventsFlag,
     doctor: doctorFlag,
     notify: notifyFlag,
     report: reportDays,
@@ -461,6 +492,8 @@ function parseArgs(argv) {
     hookAction,
     mcp,
     reactive,
+    followVolume,
+    plugin,
     dryRun,
     tools,
     typed,
@@ -751,8 +784,9 @@ function printStatus() {
     // What it was started with, which is not necessarily what is saved: a
     // daemon keeps its settings until the next prompt replaces it, and
     // "I changed the genre and nothing happened" is that gap.
+    const level = playing.follows ? Math.round(volumeNow() * 100) : playing.volume; // A following daemon plays what is saved.
     const now = playing.genre
-      ? ` ${on(playing.genre)}${playing.volume === null ? "" : on(` @ ${playing.volume}%`)}${playing.reactive ? off(", reactive") : ""}`
+      ? ` ${on(playing.genre)}${level === null ? "" : on(` @ ${level}%`)}${playing.reactive ? off(", reactive") : ""}`
       : "";
     console.log(`  ${on("playing")}${now}${off(`   pid ${pid}`)}`);
     if (playing.genre && playing.genre !== genreNow()) {
@@ -915,10 +949,12 @@ function formatDuration(ms) {
  * 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.
+ * agent being slow, the other is you being away. "Back to it" is the other
+ * direction: how long a finished turn waited for your next prompt, with gaps
+ * over RETURN_WINDOW_MS read as breaks and left out.
  */
 function printReport(days, now = Date.now()) {
-  const { readTurns } = require("./history");
+  const { readTurns, returnTimes } = require("./history");
   const turns = readTurns(days, now);
   const dim = (s) => `\x1b[90m${s}\x1b[0m`;
   const bold = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -957,6 +993,19 @@ function printReport(days, now = Date.now()) {
   row("Typical turn", formatDuration(median), "median");
   row("Longest turn", formatDuration(longest.ms), label(longest));
 
+  // How fast you came back once a turn was done - the human half of the loop.
+  const middle = (xs) => xs.slice().sort((a, b) => a - b)[Math.floor(xs.length / 2)];
+  const gaps = returnTimes(turns);
+  if (gaps.length) {
+    row("Back to it", formatDuration(middle(gaps.map((g) => g.ms))), `median from done to your next prompt, ${gaps.length} ${gaps.length === 1 ? "time" : "times"}`);
+    // Only once both sides have enough to mean something; three turns is an anecdote.
+    const withChime = gaps.filter((g) => g.chimed === true).map((g) => g.ms);
+    const without = gaps.filter((g) => g.chimed === false).map((g) => g.ms);
+    if (withChime.length >= 5 && without.length >= 5) {
+      row("", `${formatDuration(middle(withChime))} with a chime`, `${formatDuration(middle(without))} without (muted or --no-chime)`);
+    }
+  }
+
   const byProject = new Map();
   for (const t of turns) {
     const p = byProject.get(label(t)) || { ms: 0, n: 0 };
@@ -1128,6 +1177,9 @@ function saveDefaults(typed, hereOnly = false) {
   if (playing && patch.genre && playing.genre && playing.genre !== patch.genre) {
     console.log(`  \x1b[90m${playing.genre} is still playing — vibe --stop cuts it short.\x1b[0m`);
   }
+  if (playing && playing.follows && patch.volume !== undefined) {
+    console.log(`  \x1b[90mThe music playing now follows the new volume within a second.\x1b[0m`);
+  }
 
   // An install from before the settings moved out of the hook command line
   // still carries its own genre, and a flag beats this file. Saying nothing
@@ -1259,18 +1311,23 @@ function renderToFile(target, genre) {
   console.log(`  \x1b[90mAnother project's sound: run it there, or vibe --seed <n> --render.\x1b[0m\n`);
 }
 
-function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive, tools, dryRun, typed = {} }) {
+function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, tools, dryRun, typed = {} }) {
   const hooks = require("./hooks");
 
+  // The plugin's hooks and --install-hooks' hooks are the same events: with both
+  // present every prompt would restart the music and every turn chime twice.
+  // The installed ones win because they carry the user's --reactive choice.
+  if (plugin && action.startsWith("hook-") && hooks.userHooksInstalled()) return;
+
   switch (action) {
     case "daemon":
-      return hooks.runDaemon(genre, volume, { reactive });
+      return hooks.runDaemon(genre, volume, { reactive, volumeSource: followVolume ? volumeNow : null });
 
     case "hook-start":
       // The payload names the session (so SessionEnd can tell this session's
       // music from another's) and the transcript (so an interrupt, which
       // fires no hook, can still stop it).
-      hooks.readPayload((raw) => hooks.hookStart(genre, volume, { reactive, turn: hooks.newTurn(raw) }));
+      hooks.readPayload((raw) => hooks.hookStart(genre, volume, { reactive, follow: typed.volume === undefined, turn: hooks.newTurn(raw) }));
       return;
 
     case "hook-stop":
@@ -1297,7 +1354,7 @@ function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive,
       return;
 
     case "hook-resume":
-      hooks.readPayload((raw) => hooks.hookResume(raw, genre, volume, { reactive }));
+      hooks.readPayload((raw) => hooks.hookResume(raw, genre, volume, { reactive, follow: typed.volume === undefined }));
       return;
 
     case "hook-end":
@@ -1474,6 +1531,8 @@ async function run() {
     render,
     clearCache: shouldClear,
     status: showStatus,
+    state: showState,
+    events: followEvents,
     doctor: showDoctor,
     notify: notifyChange,
     report: reportDays,
@@ -1483,6 +1542,8 @@ async function run() {
     hookAction,
     mcp,
     reactive,
+    followVolume,
+    plugin,
     dryRun,
     tools,
     typed,
@@ -1500,7 +1561,7 @@ async function run() {
 
   if (hookAction) {
     try {
-      return runHookAction(hookAction, { genre, volume, chimeVolume, noChime, reactive, tools, dryRun, typed });
+      return runHookAction(hookAction, { genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, tools, dryRun, typed });
     } catch (e) {
       // Settings problems are the user's to fix — report them, don't stack-trace.
       console.error(`\x1b[31m[vibeaudio] ${e.message}\x1b[0m`);
@@ -1564,6 +1625,18 @@ async function run() {
     return printDoctor();
   }
 
+  // Machine-readable, for lights, menu bars and status lines: see "Build on it" in the README.
+  if (showState) {
+    console.log(JSON.stringify(require("./hooks").agentState()));
+    return;
+  }
+
+  if (followEvents) {
+    process.stdout.on("error", () => process.exit(0)); // `vibe --events | head` closing the pipe is not an error.
+    require("./hooks").followEvents();
+    return;
+  }
+
   if (reportDays !== null) {
     return printReport(reportDays);
   }

package/src/history.js

@@ -1,8 +1,9 @@
 /**
  * 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.
+ * how long it took, how much of that the agent spent blocked on you, how it
+ * ended, which session it was and whether a chime announced it. It never
+ * leaves the machine; VIBE_NO_HISTORY=1 turns it off.
  */
 
 const fs = require("fs");
@@ -14,12 +15,12 @@ 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) {
+function recordTurn({ project, ms, blockedMs = 0, outcome = "success", session, chimed, 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`);
+    fs.appendFileSync(file, `${JSON.stringify({ at, project, ms, blockedMs: Math.min(Math.max(blockedMs, 0), ms), outcome, session, chimed })}\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) {
@@ -54,4 +55,34 @@ function readTurns(days, now = Date.now(), file = HISTORY_FILE) {
   return turns;
 }
 
-module.exports = { HISTORY_FILE, recordTurn, readTurns };
+// A gap longer than this is a break - lunch, a meeting, the end of the day -
+// not someone coming back to a finished turn, and would swamp the median.
+const RETURN_WINDOW_MS = 30 * 60 * 1000;
+
+/**
+ * How long each finished turn sat before the next prompt in the same session:
+ * the time it took you to come back. A turn's start is `at - ms`. Sessions,
+ * not projects, are what pair up - two agents in one repo interleave - so a
+ * line from before sessions were logged (or an `anon` one) falls back to its
+ * project. `chimed` is the finished turn's, since that is the chime you were
+ * answering.
+ */
+function returnTimes(turns) {
+  const groups = new Map();
+  for (const t of turns) {
+    const key = t.session && t.session !== "anon" ? `s:${t.session}` : `p:${t.project}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(t);
+  }
+  const gaps = [];
+  for (const list of groups.values()) {
+    list.sort((a, b) => a.at - b.at);
+    for (let i = 1; i < list.length; i++) {
+      const ms = list[i].at - list[i].ms - list[i - 1].at;
+      if (ms >= 0 && ms <= RETURN_WINDOW_MS) gaps.push({ ms, chimed: list[i - 1].chimed });
+    }
+  }
+  return gaps;
+}
+
+module.exports = { HISTORY_FILE, RETURN_WINDOW_MS, recordTurn, readTurns, returnTimes };

package/src/hooks.js

@@ -25,6 +25,7 @@ const INTENSITY_FILE = path.join(STATE_DIR, "intensity");
 // them is working; each holds where its transcript began and, while paused for
 // the user, what will resume it.
 const SESSIONS_DIR = path.join(STATE_DIR, "sessions");
+const EVENTS_FILE = path.join(STATE_DIR, "events.jsonl");
 // Payloads that name no session share this one slot.
 const ANON_SESSION = "anon";
 const CLI_ENTRY = path.join(__dirname, "..", "bin", "vibeaudio.js");
@@ -410,7 +411,8 @@ function daemonPlaying() {
     pid,
     genre: genre ? genre[1] : null,
     volume: volume ? Number(volume[1]) : null,
-    reactive: /--reactive/.test(argv)
+    reactive: /--reactive/.test(argv),
+    follows: /--follow-volume/.test(argv)
   };
 }
 
@@ -451,7 +453,7 @@ function newTurn(raw) {
   const payload = parsePayload(raw);
   const transcript = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
   const offset = transcript ? fileSize(transcript) : 0;
-  return { session: String(payloadSession(payload) || ""), transcript, offset, blocked: blockedJustBefore(transcript, offset) };
+  return { session: String(payloadSession(payload) || ""), project: payload.cwd || process.cwd(), transcript, offset, blocked: blockedJustBefore(transcript, offset) };
 }
 
 const BLOCK_LOOKBACK_MS = 3000;
@@ -544,6 +546,102 @@ function listSessions() {
 // Working, as opposed to paused for the user.
 const working = (sessions) => sessions.filter((s) => s.waiting == null);
 
+// "Stuck": STUCK_FAILURES of a session's last STUCK_WINDOW tool calls failed.
+// Measured on 4,497 real Claude Code turns (46,032 tool calls, 3.8% failing):
+// this fires in 0.9% of turns, at minute 3 by the median, and those turns ran
+// a median 3.3 minutes more - time someone could have stepped in. "3 of 8"
+// fired in 2.4%, and "3 in a row" misses the usual loop, where an edit that
+// succeeds sits between every failing test run. Rare is the point: a signal
+// that fires often is one people learn to tune out.
+const STUCK_WINDOW = 8;
+const STUCK_FAILURES = 4;
+const isStuck = (session) => (session.recent || []).filter(Boolean).length >= STUCK_FAILURES;
+
+/**
+ * The public face of the session files: what every agent on the machine is
+ * doing, in five words that mean the same thing whichever agent it is. The
+ * hard part of this project is mapping eight agents' hook events onto those
+ * states; the music is one consumer of them, and `vibe --state` / `--events`
+ * let anything else be another - a light, a menu bar, a tmux status line.
+ * `status` is the machine's: the most urgent of its sessions, since one
+ * session waiting on you matters more than three working.
+ */
+const STATE_RANK = ["idle", "working", "stuck", "waiting"];
+const sessionState = (s) => (s.waiting != null ? "waiting" : isStuck(s) ? "stuck" : "working");
+
+function agentState(sessions = listSessions()) {
+  const list = sessions.map((s) => ({
+    session: s.id,
+    project: s.project || null,
+    state: sessionState(s),
+    since: s.started || null,
+    ...(s.waiting ? { tool: s.waiting } : {})
+  }));
+  const status = list.reduce((a, s) => (STATE_RANK.indexOf(s.state) > STATE_RANK.indexOf(a) ? s.state : a), "idle");
+  return { v: 1, status, sessions: list };
+}
+
+const EVENTS_MAX_BYTES = 256 * 1024;
+
+/**
+ * Appends one transition to ~/.vibeaudio/events.jsonl, after the session file
+ * already reflects it, so `status` is the state the event left behind. Not
+ * gated by a mute: a mute silences sound, and a light watching this is not
+ * sound. Rotated to `.1` rather than trimmed in place, so a follower sees a
+ * fresh file instead of re-reading the lines a trim kept. Never throws.
+ */
+function emitEvent(event, session, project, extra = {}) {
+  try {
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+    try {
+      if (fs.statSync(EVENTS_FILE).size > EVENTS_MAX_BYTES) fs.renameSync(EVENTS_FILE, `${EVENTS_FILE}.1`);
+    } catch (e) { /* no file yet */ }
+    const line = { v: 1, at: Date.now(), event, session, project: project || null, ...extra, status: agentState().status };
+    fs.appendFileSync(EVENTS_FILE, `${JSON.stringify(line)}\n`); // One write under PIPE_BUF: appends do not interleave.
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * `vibe --events`: the current state as one line, then every event as it is
+ * written, until killed. Polled rather than fs.watch'd, which is unreliable on
+ * the platforms this runs on; a quarter second is well inside a turn.
+ */
+function followEvents(write = (s) => process.stdout.write(s), pollMs = 250) {
+  write(`${JSON.stringify({ event: "state", at: Date.now(), ...agentState() })}\n`);
+  const stat = () => {
+    try {
+      const st = fs.statSync(EVENTS_FILE);
+      return { size: st.size, ino: st.ino };
+    } catch (e) {
+      return { size: 0, ino: null };
+    }
+  };
+  let { size: pos, ino } = stat();
+  let partial = "";
+  return setInterval(() => {
+    const now = stat();
+    if (now.ino !== ino || now.size < pos) {
+      ino = now.ino; // Rotated: the new file holds only what came after.
+      pos = 0;
+      partial = "";
+    }
+    if (now.size <= pos) return;
+    try {
+      const fd = fs.openSync(EVENTS_FILE, "r");
+      const buf = Buffer.alloc(now.size - pos);
+      fs.readSync(fd, buf, 0, buf.length, pos);
+      fs.closeSync(fd);
+      pos = now.size;
+      const lines = (partial + buf.toString("utf8")).split("\n");
+      partial = lines.pop();
+      for (const l of lines) if (l) write(`${l}\n`);
+    } catch (e) { /* removed between stat and open: next poll */ }
+  }, pollMs);
+}
+
 // 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";
@@ -610,7 +708,7 @@ const INTERRUPT_POLL_MS = 500;
  * Internal mode: plays while any session is working. The player's own loop
  * timer keeps the event loop alive.
  */
-function runDaemon(genre, volume, { reactive = false } = {}) {
+function runDaemon(genre, volume, { reactive = false, volumeSource = null } = {}) {
   const watchers = new Map(); // session id -> its transcript poll
 
   // Drops sessions whose transcript shows an interrupt (Esc fires no hook, so
@@ -626,6 +724,7 @@ function runDaemon(genre, volume, { reactive = false } = {}) {
       if (watchers.get(s.id)()) {
         fs.rmSync(sessionFile(s.id), { force: true });
         watchers.delete(s.id);
+        emitEvent("interrupted", s.id, s.project);
       }
     }
     return working(listSessions()).length > 0;
@@ -647,7 +746,9 @@ function runDaemon(genre, volume, { reactive = false } = {}) {
     // The same piece with more of it, as time escalation already does: two
     // sessions working is tier 2 at least, three or more is tier 3. Read at
     // each loop boundary, so it lands cleanly and eases off as they finish.
-    minTier: () => Math.min(3, working(listSessions()).length)
+    minTier: () => Math.min(3, working(listSessions()).length),
+    // A heartbeat under the music while any working session looks stuck.
+    tension: () => working(listSessions()).some(isStuck)
   });
   if (!started) process.exit(0);
 
@@ -661,6 +762,8 @@ function runDaemon(genre, volume, { reactive = false } = {}) {
   setTimeout(shutdown, MAX_DAEMON_MS);
 
   setInterval(() => {
+    // A volume saved while this plays reaches it now, not at the next prompt.
+    if (volumeSource) player.setVolume(volumeSource());
     if (sweep()) return;
     player.stop({ playChime: false });
     endIdle();
@@ -672,9 +775,10 @@ function daemonRunning() {
   return pid !== null && isOurDaemon(pid);
 }
 
-function spawnDaemon(genre, volume, reactive) {
+function spawnDaemon(genre, volume, reactive, follow = false) {
   const args = [CLI_ENTRY, "--daemon", "--genre", genre, "--volume", String(Math.round(volume * 100))];
   if (reactive) args.push("--reactive");
+  if (follow) args.push("--follow-volume");
 
   const child = spawn(process.execPath, args, { detached: true, stdio: "ignore" });
   child.unref();
@@ -689,16 +793,18 @@ function spawnDaemon(genre, volume, reactive) {
  * always did, so a genre change lands on the next prompt. With one working the
  * music carries on: restarting it would cut every other session's stream.
  */
-function hookStart(genre, volume, { reactive = false, turn = null } = {}) {
+function hookStart(genre, volume, { reactive = false, turn = null, follow = false } = {}) {
   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 });
+  const project = (turn && turn.project) || process.cwd();
+  writeSession(id, { project, transcript: (turn && turn.transcript) || "", offset: (turn && turn.offset) || 0, waiting: null, started: Date.now(), blockedMs: 0 });
+  emitEvent("started", id, project);
   if (working(listSessions()).some((s) => s.id !== id) && daemonRunning()) return readPid();
 
   stopDaemon({ keepSessions: true });
   fs.rmSync(INTENSITY_FILE, { force: true }); // Don't inherit the last prompt's activity
-  return spawnDaemon(genre, volume, reactive);
+  return spawnDaemon(genre, volume, reactive, follow);
 }
 
 /**
@@ -805,11 +911,14 @@ function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChi
   const session = readSession(id);
   const tracked = session !== null;
   fs.rmSync(sessionFile(id), { force: true });
+  if (tracked) emitEvent("finished", id, parsePayload(raw).cwd || session.project, { outcome });
   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 });
+    // ponytail: assumes a playback backend exists; a machine with none hears no music either.
+    const chimed = !noChime && !playbackDisabled();
+    recordTurn({ project: parsePayload(raw).cwd || process.cwd(), ms: now - session.started, blockedMs, outcome, session: id, chimed, at: now });
   }
 
   // The music is every working session's, so it ends with the last of them.
@@ -869,6 +978,7 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
   if (!session || session.waiting != null) return false;
 
   writeSession(id, { ...session, waiting: waitKey(raw), waitStart: Date.now() });
+  emitEvent("waiting", id, session.project, waitKey(raw) ? { tool: waitKey(raw) } : {});
   if (working(listSessions()).length === 0) stopDaemon({ keepSessions: true });
   const tool = payloadToolName(raw);
   notify(raw, tool ? `needs you (${tool})` : "needs you");
@@ -889,17 +999,36 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
  * one needing approval, can resume early - after the chime already did its
  * job. Match on tool_input as well if that ever shows up in practice.
  */
-function hookResume(raw, genre, volume, { reactive = false } = {}) {
-  const id = sessionId(payloadSession(parsePayload(raw)));
+function hookResume(raw, genre, volume, { reactive = false, follow = false } = {}) {
+  const payload = parsePayload(raw);
+  const id = sessionId(payloadSession(payload));
   const session = readSession(id);
-  if (!session || session.waiting == null) return false; // Not waiting - the common case, on every tool call.
+  if (!session) return false;
+
+  // Every tool call lands here, so this is where the stuck signal is kept.
+  // An interrupt is the user stopping a tool, not the tool failing.
+  // ponytail: two parallel tool calls in one session can each read, then write,
+  // and one result is lost. A heuristic over eight calls survives that.
+  const failed = payload.hook_event_name === "PostToolUseFailure" && !payload.is_interrupt;
+  const recent = [...(session.recent || []), failed ? 1 : 0].slice(-STUCK_WINDOW);
+  const next = { ...session, recent };
+  const crossing = isStuck(next) === isStuck(session) ? null : isStuck(next) ? "stuck" : "recovered";
+  if (crossing === "stuck") notify(raw, `looks stuck - ${STUCK_FAILURES} of its last ${STUCK_WINDOW} tool calls failed`);
+
   // An empty key is a wait that named nothing (a Notification): the next tool
   // to finish is the first sign of work carrying on.
-  if (session.waiting !== "" && session.waiting !== waitKey(raw)) return false;
+  const resumes = session.waiting != null && (session.waiting === "" || session.waiting === waitKey(raw));
+  if (!resumes) {
+    writeSession(id, next);
+    if (crossing) emitEvent(crossing, id, session.project);
+    return false; // Not waiting - the common case, on every tool call.
+  }
 
   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);
+  writeSession(id, { ...next, waiting: null, waitStart: null, blockedMs });
+  emitEvent("resumed", id, session.project);
+  if (crossing) emitEvent(crossing, id, session.project);
+  if (!daemonRunning()) spawnDaemon(genre, volume, reactive, follow);
   return true;
 }
 
@@ -914,9 +1043,11 @@ function hookResume(raw, genre, volume, { reactive = false } = {}) {
  */
 function hookEnd(raw) {
   const id = sessionId(payloadSession(parsePayload(raw)));
-  if (!readSession(id)) return false;
+  const session = readSession(id);
+  if (!session) return false;
 
   fs.rmSync(sessionFile(id), { force: true });
+  emitEvent("ended", id, session.project);
   if (working(listSessions()).length === 0) {
     stopDaemon({ keepSessions: true });
     fs.rmSync(INTENSITY_FILE, { force: true });
@@ -998,6 +1129,11 @@ function readVibeEntryCount(file, id) {
   }
 }
 
+/** True when --install-hooks has already written our entries for Claude Code. */
+function userHooksInstalled(file = null) {
+  return readVibeEntryCount(file || TARGETS.claude.file(), "claude") > 0;
+}
+
 function loadSettings(file, t = null) {
   if (!fs.existsSync(file)) return { settings: t ? t.seed() : {}, raw: null };
   const raw = fs.readFileSync(file, "utf8");
@@ -1210,6 +1346,11 @@ module.exports = {
   hookTool,
   hookWait,
   hookResume,
+  isStuck,
+  STUCK_WINDOW,
+  agentState,
+  followEvents,
+  EVENTS_FILE,
   hookEnd,
   newTurn,
   outcomeFromPayload,
@@ -1227,6 +1368,7 @@ module.exports = {
   uninstallHooks,
   settingsPath,
   isVibeHook,
+  userHooksInstalled,
   hookEntries,
   installSlashCommand,
   uninstallSlashCommand,

package/src/mac-player.jxa

@@ -1,6 +1,7 @@
 // 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>
+//   volume <volume 0-1> <ramp seconds>      (everything sounding now)
 // 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");
@@ -26,6 +27,11 @@ function play(volume, fadeIn, path) {
 }
 
 function handle(line) {
+  const v = /^volume (\S+) (\S+)$/.exec(line);
+  if (v) {
+    for (const p of players) if (p.playing) p.setVolumeFadeDuration(parseFloat(v[1]), parseFloat(v[2]));
+    return;
+  }
   const m = /^play (\S+) (\S+) (.+)$/.exec(line);
   if (m) play(parseFloat(m[1]), parseFloat(m[2]), m[3]);
 }

package/src/player.js

@@ -20,6 +20,7 @@ const { generatePianoLoop } = require("./synth/piano");
 const { generateJazzLoop } = require("./synth/jazz");
 const { generateSuccessChime, generateFailureChime, generateAttentionChime, DEFAULT_CHIME_KEY, SUCCESS_CHIME_NOTES } = require("./synth/chime");
 const { hashString } = require("./synth/generator");
+const { addTension } = require("./synth/tension");
 const pkg = require("../package.json");
 
 const CACHE_ROOT = path.join(os.homedir(), ".vibeaudio", "cache");
@@ -116,6 +117,7 @@ let warnedNoPlayer = false;
 // 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;
+const VOLUME_RAMP_S = 0.3;
 let helperFailed = false;
 
 function helperUsable(backend) {
@@ -616,7 +618,7 @@ function writeCacheFileAtomic(filePath, buffer) {
   }
 }
 
-function getAudioPath(genre, tier = 2, seed = projectSeed(), gain = 1, bar = 0) {
+function getAudioPath(genre, tier = 2, seed = projectSeed(), gain = 1, bar = 0, tension = false) {
   ensureCacheDir();
   const normalizedGenre = resolveGenre(genre);
   const safeTier = Math.max(1, Math.min(3, tier));
@@ -628,11 +630,14 @@ function getAudioPath(genre, tier = 2, seed = projectSeed(), gain = 1, bar = 0)
   // into this opens on exactly the bar it has always opened on.
   const barSuffix = safeBar === 0 ? "" : `_b${safeBar}`;
   const dir = seedDir(seed);
-  const filePath = path.join(dir, `loop_${normalizedGenre}_t${safeTier}${barSuffix}${gainSuffix(gain)}.wav`);
+  // The stuck heartbeat is its own file, rendered only once an agent is stuck.
+  const tensionSuffix = tension ? "_x" : "";
+  const filePath = path.join(dir, `loop_${normalizedGenre}_t${safeTier}${barSuffix}${tensionSuffix}${gainSuffix(gain)}.wav`);
 
   if (!fs.existsSync(filePath)) {
     fs.mkdirSync(dir, { recursive: true });
-    writeCacheFileAtomic(filePath, applyGain(generateLoop(normalizedGenre, safeTier, seed >>> 0, safeBar), gain));
+    const loop = generateLoop(normalizedGenre, safeTier, seed >>> 0, safeBar);
+    writeCacheFileAtomic(filePath, applyGain(tension ? addTension(loop, GENRE_KEYS[normalizedGenre]) : loop, gain));
     pruneSeedDirs();
   }
 
@@ -727,6 +732,7 @@ class AudioPlayer {
     this.seed = projectSeed();
     this.intensity = null;
     this.minTier = null;
+    this.tension = null;
     this.currentTier = 1;
     this.bar = 0;
     this.nextTimer = null;
@@ -737,7 +743,7 @@ class AudioPlayer {
    * Returns true if playback actually started. Restarts when called with
    * different settings while playing, so a genre switch is not silently dropped.
    */
-  start(genre = "lofi", volume = 0.42, { maxDurationMs = null, intensity = null, minTier = null } = {}) {
+  start(genre = "lofi", volume = 0.42, { maxDurationMs = null, intensity = null, minTier = null, tension = null } = {}) {
     const resolved = resolveGenre(genre);
     const targetVolume = Math.max(0.05, Math.min(1.0, volume));
 
@@ -761,6 +767,7 @@ class AudioPlayer {
     this.bar = 0; // Every run opens on the project's own bar.
     this.intensity = intensity;
     this.minTier = minTier;
+    this.tension = tension;
 
     installExitHook();
     activePlayers.add(this);
@@ -799,7 +806,8 @@ class AudioPlayer {
     // never both, or the volume would be applied twice.
     const backend = detectPlayer();
     const gain = bakedGain(backend, this.volume);
-    const audioFile = getAudioPath(this.genre, this.currentTier, this.seed, gain, this.bar);
+    // An agent that looks stuck adds a heartbeat, landing at this loop boundary.
+    const audioFile = getAudioPath(this.genre, this.currentTier, this.seed, gain, this.bar, Boolean(this.tension && this.tension()));
     // 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);
@@ -808,6 +816,22 @@ class AudioPlayer {
     this.nextTimer = setTimeout(() => this.playLoop(), Math.max(250, durationMs - LOOP_OVERLAP_MS));
   }
 
+  /**
+   * Changes the volume of music already playing. The helper eases the loops
+   * that are sounding to it; any other backend takes it at the next loop, which
+   * is as live as a player that reads its volume once at spawn can be.
+   */
+  setVolume(volume) {
+    const target = Math.max(0.05, Math.min(1.0, Number(volume))); // Already a fraction, unlike normalizeVolume's percent.
+    if (!this.isPlaying || !Number.isFinite(target) || target === this.volume) return;
+    this.volume = target;
+    try {
+      if (this.helper) this.helper.stdin.write(`volume ${this.volume} ${VOLUME_RAMP_S}\n`);
+    } catch (e) {
+      // The helper's own exit handler deals with a dead pipe.
+    }
+  }
+
   spawnLoop(audioFile, backend) {
     const proc = spawn(backend.cmd, backend.args(audioFile, this.volume), { stdio: "ignore" });
 

package/src/synth/tension.js

@@ -0,0 +1,67 @@
+/**
+ * The "stuck" layer: a soft heartbeat under the loop, played while an agent's
+ * recent tool calls keep failing. More of the same music would say "working
+ * hard", which is not the news; a pulse that was not there before changes the
+ * music's character, and a heartbeat is the most widely read tension cue there
+ * is. Pitched on the genre's tonic so it sits in the key rather than against it.
+ *
+ * Pure like every other synth module: a WAV buffer in, a new one out.
+ */
+
+const { noteToFreq, SAMPLE_RATE } = require("./generator");
+
+const BEAT_S = 1.1; // About 55 bpm: a resting heart, not a racing one.
+const DUB_DELAY_S = 0.24;
+const EDGE_S = 0.15; // Clear of the loop's boundary fades, so seams stay clean.
+const LEVEL = 0.22;
+
+// Laptop speakers roll off below ~120 Hz, and a pulse nobody hears is no
+// signal, so the tonic sits between 110 and 220 Hz with a second harmonic.
+function pulseFreq(key) {
+  const tonic = String(key || "A minor").split(" ")[0];
+  let f = noteToFreq(`${tonic}3`);
+  while (f > 220) f /= 2;
+  while (f < 110) f *= 2;
+  return f;
+}
+
+// One thump: a short pitch drop, like a soft kick, decaying in ~0.2s.
+function thump(t, f) {
+  if (t < 0 || t > 0.35) return 0;
+  const phase = f * t + (f * 0.5 * 0.04) * (1 - Math.exp(-t / 0.04)); // f*1.5 falling to f
+  const env = Math.min(1, t / 0.004) * Math.exp(-t / 0.075);
+  return env * (Math.sin(2 * Math.PI * phase) + 0.45 * Math.sin(4 * Math.PI * phase));
+}
+
+/** Mixes the heartbeat into a canonical 16-bit WAV (mono or stereo) and returns a new buffer. */
+function addTension(wav, key) {
+  if (wav.length < 44 || wav.toString("ascii", 0, 4) !== "RIFF") {
+    throw new Error("addTension expects a canonical 44-byte-header WAV");
+  }
+  const channels = wav.readUInt16LE(22);
+  const rate = wav.readUInt32LE(24) || SAMPLE_RATE;
+  const frames = Math.floor((wav.length - 44) / (2 * channels));
+  const duration = frames / rate;
+  const f = pulseFreq(key);
+
+  // A whole number of beats per loop, so the pulse keeps time across loops.
+  const beats = Math.max(1, Math.round((duration - 2 * EDGE_S) / BEAT_S));
+  const period = (duration - 2 * EDGE_S) / beats;
+  const out = Buffer.from(wav);
+
+  for (let i = 0; i < frames; i++) {
+    const t = i / rate - EDGE_S;
+    if (t < 0 || t > duration - 2 * EDGE_S) continue;
+    const local = t % period;
+    const s = LEVEL * (thump(local, f) + 0.7 * thump(local - DUB_DELAY_S, f));
+    if (s === 0) continue;
+    for (let c = 0; c < channels; c++) {
+      const offset = 44 + (i * channels + c) * 2;
+      const mixed = Math.round(out.readInt16LE(offset) + s * 32767);
+      out.writeInt16LE(Math.max(-32768, Math.min(32767, mixed)), offset);
+    }
+  }
+  return out;
+}
+
+module.exports = { addTension, pulseFreq };