roger-roger 0.1.3 → 0.1.8

package/README.md

@@ -57,6 +57,7 @@ A missing key is not fatal. Speech falls back to the computer's built-in voice (
 `roger-roger install` asks, in the terminal:
 
 - which agents should have the skill (every one it finds is ticked)
+- whether to tell your agents to always use it: a marked block in each agent's global instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.config/opencode/AGENTS.md`, `~/.gemini/GEMINI.md`), which uninstall takes out again
 - whether to register with Herdr, if it's installed
 - how to reach you: Slack, sound, speech, in any combination
 - Slack: it connects it for you (see above), and where messages go (your DMs, or a channel)
@@ -96,7 +97,7 @@ There is no always-on service. `ask` starts a small watcher process, and one wat
 - **Talk to an agent**: write "sage, rerun the tests" (or "hey sage rerun the tests", or "sage: ..."). With one agent running, a plain message goes to it. With several, but only one of them listening, it goes to that one and Slack says so, with a button to redirect it. With several, the bot asks which, with a button per agent — and remembers your answer for that thread.
 - **You can hear who it is**: a spoken line starts with the agent's name — "Amber here.", "This is Rose.", "Jade speaking." — so three agents sharing one pair of speakers stay tellable apart (`setup --say-who off`).
 - **Reachable while idle**: an agent that has finished can run `listen` in the background instead of going quiet. It costs nothing to wait, and when you write, it wakes up and answers. Slack shows 👀 when an agent is listening and 💤 when your message is saved for one that isn't, so you always know which.
-- **In the tray**: `tray install` puts an icon in the system tray, started with the daemon from then on (`tray start` starts it straight away; `setup --tray off` stops it starting by itself) — every agent at a glance, a translucent panel on click, snooze on right-click. It reads the same state the daemon already keeps and runs ordinary commands, so it can be closed, killed or never installed and nothing else changes.
+- **In the tray**: `tray install` puts an icon in the system tray, started with the daemon from then on (`tray start` starts it straight away; `setup --tray off` stops it starting by itself) — every agent at a glance, a translucent panel on click, snooze on right-click, a Stop button while a voice is speaking (`roger-roger hush` from a terminal), and a log of who said what lately: every notification and question from the agents, and every message and answer from you, per agent or all together. It reads the same state the daemon already keeps and runs ordinary commands, so it can be closed, killed or never installed and nothing else changes.
 - **Questions asked in the terminal**: when the agent asks you something with its own question tool (Claude Code's question dialog, OpenCode's question tool, Codex's `request_user_input`) or wants a plan approved, it's stuck until you answer and can't tell you itself. `hooks install` hooks into each of those agents it finds: once the question has gone unanswered for a little while, it arrives in Slack with its options, and when you answer in the terminal the message turns into your answer. Claude Code gets three hooks in `~/.claude/settings.json`; OpenCode a small plugin in `~/.config/opencode/plugins/`; Codex three hooks in `~/.codex/hooks.json`, which you trust once in Codex's `/hooks`. Claude Code knows when you've stopped typing; OpenCode and Codex don't, so they wait 20 seconds first (`setup --terminal-wait`). `setup --permission-pings on` does the same for ordinary permission prompts. `hooks uninstall` takes it all out again.
 - **Quiet hours**: `setup --quiet-hours 22:00-08:00` mutes sound and speech overnight. It's off by default.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roger-roger",
-  "version": "0.1.3",
+  "version": "0.1.8",
   "description": "Bring yourself back to the conversation: your coding agents reach you by Slack, a sound or a spoken line when they finish, get stuck, or need a decision, and you answer from your phone.",
   "type": "module",
   "bin": {

package/skills/roger-roger/SKILL.md

@@ -25,7 +25,7 @@ Every command prints a single JSON object.
 
 **Your name.** The daemon gives every agent session a short colour nickname — 🌿 sage, 🌹 rose, 🍇 plum — shown on all your Slack messages with a matching colour bar down their edge. That is how the user tells three agents apart and how they address you: "sage, rerun the tests". `sessions` lists who is running; `status` tells you your own name.
 
-**In Herdr, your pane is named after you — by the skill, not by you.** When the session runs inside a [Herdr](https://herdr.dev) pane (`HERDR_ENV=1`), the first command labels the pane's tab with your badge (`🍯 amber`) and its agent with your kind and your work (`claude-build-process-improvements`: Herdr allows only lowercase letters, digits, `-` and `_` there, 32 characters at most), so the Herdr sidebar reads `code-red 🍯 amber claude-build-process-improvements` and matches your Slack messages. The work part is your `--session` name, which is one more reason to pass it, and the labels follow a `sessions rename` or a new `--session` name by themselves. Don't run `herdr tab rename` or `herdr agent rename` yourself; `status` shows what was put on under `daemon.me.herdr`, and a label Herdr refused (a name another pane already has) is in `~/.roger-roger/daemon.log`.
+**In Herdr, your pane is named after you — by the skill, not by you.** When the session runs inside a [Herdr](https://herdr.dev) pane (`HERDR_ENV=1`), the first command labels the pane's tab with your badge (`🍯 amber`) and its agent with your kind and your work (`claude-build-process-improvements`: Herdr allows only lowercase letters, digits, `-` and `_` there, 32 characters at most), so the Herdr sidebar reads `code-red 🍯 amber claude-build-process-improvements` and matches your Slack messages. The work part is your `--session` name, which is one more reason to pass it (without one, the skill falls back to your terminal title, which may be vague or out of date), and the labels follow a `sessions rename` or a new `--session` name by themselves. Don't run `herdr tab rename` or `herdr agent rename` yourself; `status` shows what was put on under `daemon.me.herdr`, and a label Herdr refused (a name another pane already has) is in `~/.roger-roger/daemon.log`.
 
 **Always pass `--session`**, the same 3–6 word name on every call. It is not only a label: for agents that don't publish a session id of their own it is *how you are recognised* between commands, so leaving it off can make one piece of work look like two. Nothing here is specific to any agent — if your environment publishes a session id (anything like `*_SESSION_ID`) it is used automatically; otherwise `--session` plus the working directory identifies you, and the terminal is the last resort. If you know better than all of that, pass `--session-id ID` (and `--agent-pid PID`, so a crash is noticed straight away).
 
@@ -78,7 +78,7 @@ roger-roger notify --kind done --message "Refactor of the billing module is fini
 |---|---|
 | `--kind` | `done`, `blocked`, `input`, `milestone`, `error`, `info`. Sets the Slack emoji. |
 | `--message` | The written message for Slack. Make it self-contained, because the user may read it on their phone without context. Say what happened and what, if anything, you need from them. Slack mrkdwn works. |
-| `--say` | The spoken line (optional). Keep it short, one or two sentences, with no paths, code, or URLs. If you leave it out, the message is spoken. Ignored when the user's speech mode is `same`. With `brief`, always pass a one-sentence `--say`. |
+| `--say` | The spoken line. Keep it short, one or two sentences, and **never put code in it**: no commands, flags, paths, URLs, hostnames or JSON. Say what the thing is and why, the way you would to someone across the room: not "ssh -o BatchMode=yes … lsblk …" but "Can I run lsblk on the server, to see which disks it has?". The command itself goes in `--message` (in a code block), where it can be read. Pass `--say` whenever the message has anything technical in it, because without it the message is what gets spoken. Ignored when the user's speech mode is `same`. With `brief`, always pass a one-sentence `--say`. |
 | `--only` | Restrict this one call to some methods, e.g. `--only sound` when the user said "just ding me when done". |
 | `--project` | Label shown in Slack. Defaults to the current directory name. |
 | `--session` | **Always pass it.** A short name for this session, made up by you from what the session is about: 3–6 plain words, e.g. `"roger-roger skill slack integration"` or `"billing refactor tests"`. It's shown in the small `machine · agent · model · session` line under Slack messages, so the user can tell sessions apart. Decide it on your first call and reuse the exact same name for every later call in this session. Never use IDs or hashes. |
@@ -173,7 +173,9 @@ Examples:
 - `--say "[positive] Deployment finished. [short pause] Everything is green."`
 - `--say "[serious] I'm blocked. I need the production database password to continue."`
 
-Tags must be separated by words or punctuation, never placed back to back. The script strips tags from Slack text and from the local-voice fallback, so they are safe to include. Very short or odd lines (a single word) are sometimes refused by Gemini, so write a natural sentence.
+Tags must be separated by words or punctuation, never placed back to back. The script strips tags from Slack text and from the local-voice fallback, so they are safe to include.
+
+Code is never read aloud. As a safety net, anything that reaches the speakers still looking like code is replaced with what it is ("an ssh command", "a file", "a link", "the details are in Slack"), but that is a fallback, not a way of writing: a line the safety net had to fix still sounds clumsy. Write the spoken line as plain speech in the first place, and name commands by what they do. Very short or odd lines (a single word) are sometimes refused by Gemini, so write a natural sentence.
 
 ## 3. Asking the user to choose
 
@@ -261,7 +263,7 @@ Judge it by what happens if you are wrong, not by whether it feels routine. A fo
 ## Other commands
 
 - `install`: the interactive setup, for the user to run in a terminal (section 1). `install --yes` asks nothing: it links the skill for every agent on the machine and registers with Herdr, and prints what it did.
-- `uninstall`: takes it out again, for the user to run in a terminal (`npx roger-roger@latest uninstall`): hooks, skill links, the Herdr plugin, the daemon and the tray, settings and tokens, the global command. `--yes` removes all of that without asking (`--slack-cli` adds the Slack CLI). Never run it for the user unasked.
+- `uninstall`: takes it out again, for the user to run in a terminal (`npx roger-roger@latest uninstall`): the standing instruction `install` put in the agents' global files (a marked block in `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`), hooks, skill links, the Herdr plugin, the daemon and the tray, settings and tokens, the global command. `--yes` removes all of that without asking (`--slack-cli` adds the Slack CLI). Never run it for the user unasked.
 - `help [command]`: the commands, and one command's flags.
 - `status`: current config, whether the tokens are present, the daemon, running sessions, and every valid option value.
 - `slack-setup [status|install-cli|login|create]`: the Slack steps `install` runs, one at a time, for repairing a connection by hand. `create` again is safe: it updates the same app, which is what to do after the manifest changed or when a scope is missing.
@@ -269,6 +271,7 @@ Judge it by what happens if you are wrong, not by whether it feels routine. A fo
 - `end [name]`: this session is finished. Do this when your work is done, so messages meant for someone else don't come to you.
 - `tray status|start|stop|install`: an icon in the system tray showing every agent, with a translucent panel behind it and snooze on the right-click menu. The native part is a separate package installed on request into `~/.roger-roger` (about 4 MB, nothing compiled); everything here works without it. Once installed, the daemon starts it by itself whenever it starts (`setup --tray off` to stop that).
 - `snooze [1h|off]`: mute sound and speech for a while; Slack keeps working. For "not now" moments that quiet hours don't cover.
+- `hush`: stop the voice or sound playing right now (the user's Stop button in the tray does the same). Only that announcement; the next one plays, and the Slack message stays. If a notification comes back with `results.interrupted`, the user stopped it: don't send it again.
 - `hooks status|install|uninstall [claude|opencode|codex|all]`: the terminal-question hooks. When you use your own question tool (Claude Code's question dialog, OpenCode's question tool, Codex's `request_user_input`) or present a plan to approve, you are frozen until it's answered and can't send anything yourself; with the hooks, the agent itself runs roger-roger, and once the question has gone unanswered for a little while the user gets it in Slack with its options. `roger-roger install` offers them; without a name, `hooks install` covers the agents on this machine. What each gets: Claude Code, three entries in `~/.claude/settings.json`; OpenCode, a small plugin at `~/.config/opencode/plugins/roger-roger.js` (restart OpenCode to load it); Codex, three entries in `~/.codex/hooks.json`, to trust in `/hooks`. They follow the user's `when`, quiet hours and snooze like any notification, and log each run to `~/.roger-roger/hooks.log`. Claude Code pings once nobody has typed for a few seconds; OpenCode and Codex can't tell, so they wait `setup --terminal-wait` (default 20s) and ping only if it's still unanswered. Ordinary permission prompts (leave to run a command) don't ping unless the user asks: `setup --permission-pings on` (Claude Code and OpenCode; Codex gives no signal when one is answered). Run `hooks install` again after the skill moves, so they point at the new copy; `hooks status` says if they don't.
 - `daemon status|start|stop`: the always-on process behind everything. It starts on demand, so this is only for checking on it or restarting it after a change to the skill's code.
 - `play [sound]`: preview a sound (defaults to the configured one).

package/skills/roger-roger/herdr-plugin.toml

@@ -6,7 +6,7 @@
 
 id = "roger-roger"
 name = "roger-roger"
-version = "0.1.3"
+version = "0.1.8"
 min_herdr_version = "0.9.0"
 description = "Slack, a sound or a spoken line from the agents in your panes, and questions you answer from your phone"
 platforms = ["linux", "macos", "windows"]

package/skills/roger-roger/scripts/activity.mjs

@@ -0,0 +1,92 @@
+// Who said what, lately: every notification and question an agent sent, and every message and
+// answer the user sent back, newest last. The tray shows it as a log, so "what did amber say an
+// hour ago, and did I answer?" has an answer without scrolling Slack.
+//
+// Kept in ~/.roger-roger/activity.json, capped, and written through a temp file so the tray never
+// reads half of it. Recording never throws: a log that can't be written is not a reason for a
+// notification to fail.
+
+import fs from "node:fs";
+import path from "node:path";
+import { rogerRogerHome, stripTags } from "./lib.mjs";
+import { colourOf } from "./names.mjs";
+
+export const MAX_ENTRIES = 200;
+const MAX_TEXT = 600;
+
+export const activityPath = (env = process.env) => path.join(rogerRogerHome(env), "activity.json");
+
+export function read(env = process.env) {
+  try {
+    const entries = JSON.parse(fs.readFileSync(activityPath(env), "utf8"));
+    return Array.isArray(entries) ? entries : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Who an entry is about: the agent's name and colour, or nobody yet. */
+export function agentOf(session) {
+  if (!session?.nickname) return null;
+  const colour = colourOf(session.nickname);
+  return { nickname: session.nickname, swatch: session.swatch ?? colour.swatch, colour: session.colour ?? colour.hex, project: session.project ?? "" };
+}
+
+const clip = (text) => {
+  const s = stripTags(String(text ?? "")).replace(/\s+/g, " ").trim();
+  return s.length > MAX_TEXT ? `${s.slice(0, MAX_TEXT - 1)}…` : s;
+};
+
+/**
+ * Add one entry. `from` is "agent" or "user"; `agent` is who the agent was, or who the user wrote
+ * to (null when that isn't known yet); `kind` is what it was: notify's kind, "question", "answer",
+ * or "message".
+ */
+export function record({ from, agent = null, kind, text, detail = "", at = new Date().toISOString(), ref = "" }, env = process.env) {
+  try {
+    const entry = { at, from, kind, text: clip(text), ...(detail ? { detail: clip(detail) } : {}), ...(agent ? { agent } : {}), ...(ref ? { ref } : {}) };
+    write([...read(env), entry].slice(-MAX_ENTRIES), env);
+    return entry;
+  } catch {
+    return null;
+  }
+}
+
+/** The user picked who a message was for after it was logged: say so on its entry. */
+export function retarget(ref, agent, detail = "", env = process.env) {
+  try {
+    const entries = read(env);
+    const i = entries.findLastIndex((e) => e.ref === ref);
+    if (i < 0) return false;
+    const { detail: _old, agent: _was, ...rest } = entries[i];
+    entries[i] = { ...rest, ...(agent ? { agent } : {}), ...(detail ? { detail } : {}) };
+    write(entries, env);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function write(entries, env) {
+  const file = activityPath(env);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(entries, null, 1) + "\n", "utf8");
+  fs.renameSync(tmp, file);
+}
+
+/** The newest `n`, newest first, for the tray. */
+export function recent(n = 60, env = process.env) {
+  return read(env).slice(-n).reverse();
+}
+
+/** How an answer reads in one line: the button, the options ticked, the typed words, or what happened. */
+export function answerText(decision) {
+  const a = decision.answer ?? {};
+  if (decision.status === "cancelled") return "cancelled";
+  if (decision.status === "expired") return "expired, unanswered";
+  if (a.edited) return `edited the draft: ${a.text ?? ""}`;
+  if (Array.isArray(a.choices)) return a.choices.length ? a.choices.join(", ") : "none of them";
+  if (a.choice) return a.auto ? `${a.choice} (no answer, so the recommended one)` : a.choice;
+  return a.text ?? "";
+}

package/skills/roger-roger/scripts/audio.mjs

@@ -9,6 +9,71 @@ import { SOUNDS_DIR, duckFactor, rogerRogerHome, stripTags } from "./lib.mjs";
 import { providerOf, synthesize } from "./tts.mjs";
 import { withSpeaker } from "./speaker.mjs";
 
+// ---------------------------------------------------------------- what is playing, and stopping it
+//
+// Everything audible goes through onAir(), so the daemon knows who is speaking (the tray shows a
+// Stop button while someone is) and interruptPlayback() can cut it off: the players are killed,
+// the generation moves on, and anything that notices the generation changed under it stops
+// instead of carrying on to the next sound or falling back to the computer's voice.
+
+let generation = 0;
+const players = new Set();
+let onAirCount = 0;
+let playing = null;
+const listeners = new Set();
+
+/** Called with what is playing (or null) whenever that changes. Returns a function to stop listening. */
+export function onPlaybackChange(fn) {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+const emit = () => {
+  for (const fn of listeners) {
+    try {
+      fn(playing);
+    } catch {}
+  }
+};
+
+/** Who is speaking right now, `{ who, since }`, or null. */
+export const nowPlaying = () => playing;
+
+/** True once playback started at `gen` has been interrupted. */
+export const stoppedSince = (gen) => generation !== gen;
+
+/** Mark `fn` as audible for its duration, on behalf of `who`. `fn` gets the generation to check. */
+export async function onAir(who, fn) {
+  const gen = generation;
+  onAirCount++;
+  if (!playing) {
+    playing = { who: who || null, since: new Date().toISOString() };
+    emit();
+  }
+  try {
+    return await fn(gen);
+  } finally {
+    onAirCount--;
+    if (!onAirCount) {
+      playing = null;
+      emit();
+    }
+  }
+}
+
+/** Stop whatever is playing, now. Returns whether anything was. */
+export function interruptPlayback() {
+  const was = playing;
+  if (!was) return { stopped: false };
+  generation++;
+  for (const child of players) {
+    try {
+      child.kill();
+    } catch {}
+  }
+  session?.kill();
+  return { stopped: true, who: was.who };
+}
+
 /** Run a command to completion; resolves true only on a clean exit. Never rejects. */
 function run(cmd, args, opts = {}) {
   return new Promise((resolve) => {
@@ -18,14 +83,19 @@ function run(cmd, args, opts = {}) {
     } catch {
       return resolve(false);
     }
-    child.on("error", () => resolve(false));
-    child.on("exit", (code) => resolve(code === 0));
+    players.add(child);
+    child.on("error", () => (players.delete(child), resolve(false)));
+    child.on("exit", (code) => (players.delete(child), resolve(code === 0)));
   });
 }
 
-/** Try each [cmd, args] in order; true on the first that runs cleanly. */
-async function firstThatWorks(candidates, opts) {
-  for (const [cmd, args] of candidates) if (await run(cmd, args, opts)) return true;
+/** Try each in turn, but stop trying once playback was interrupted: that exit was ours, not a failure. */
+async function firstThatWorksUnlessStopped(candidates, opts) {
+  const gen = generation;
+  for (const [cmd, args] of candidates) {
+    if (await run(cmd, args, opts)) return true;
+    if (stoppedSince(gen)) return true;
+  }
   return false;
 }
 
@@ -195,6 +265,14 @@ function windowsSession() {
       if (session === self) session = null;
       child.stdin.end();
     },
+    // PlaySync and Speak block the player, so a stop can't be asked for: the player goes, and the
+    // next request starts a new one.
+    kill() {
+      fail("interrupted");
+      try {
+        child.kill();
+      } catch {}
+    },
   };
   session = self;
   return self;
@@ -210,15 +288,26 @@ export function closeAudio() {
   session?.close();
 }
 
+/** A Windows player request that, if the player was killed to stop it, just ends: stopping isn't failing. */
+async function windowsRequest(command, gen) {
+  try {
+    await windowsSession().request(command);
+  } catch (e) {
+    if (!stoppedSince(gen)) throw e;
+  }
+}
+
+// Interrupted playback returns as if it had finished: the caller checks stoppedSince() to know.
 export async function playWav(file) {
   if (!fs.existsSync(file)) throw new Error(`no such sound file: ${file}`);
+  const gen = generation;
   let ok;
   if (process.platform === "win32") {
-    return windowsSession().request(`PLAY\t${b64(file)}`);
+    return windowsRequest(`PLAY\t${b64(file)}`, gen);
   } else if (process.platform === "darwin") {
-    ok = await run("afplay", [file]);
+    ok = (await run("afplay", [file])) || stoppedSince(gen);
   } else {
-    ok = await firstThatWorks([
+    ok = await firstThatWorksUnlessStopped([
       ["paplay", [file]],
       ["pw-play", [file]],
       ["aplay", ["-q", file]],
@@ -241,13 +330,14 @@ export async function playWavBuffer(wav) {
 
 export async function speakLocally(text) {
   const plain = stripTags(text);
+  const gen = generation;
   let ok;
   if (process.platform === "win32") {
-    return windowsSession().request(`SAY\t${b64(plain)}`);
+    return windowsRequest(`SAY\t${b64(plain)}`, gen);
   } else if (process.platform === "darwin") {
-    ok = await run("say", [plain]);
+    ok = (await run("say", [plain])) || stoppedSince(gen);
   } else {
-    ok = await firstThatWorks([
+    ok = await firstThatWorksUnlessStopped([
       ["spd-say", ["-w", plain]],
       ["espeak-ng", [plain]],
       ["espeak", [plain]],
@@ -299,7 +389,13 @@ export async function withOthersQuieter(config, fn) {
   try {
     return await fn();
   } finally {
-    await player.request("UNDUCK").catch(() => {});
+    // Stopping the voice kills this player, and with it what it saved. A fresh player reads the
+    // saved levels back from the file and puts them back, so the music doesn't stay down.
+    try {
+      await player.request("UNDUCK");
+    } catch {
+      await duckPlayer().catch(() => {});
+    }
     fs.rmSync(duckFile(), { force: true });
   }
 }
@@ -330,14 +426,18 @@ export function prepareSpeech(text, config, { local = false } = {}) {
 }
 
 /** Play prepared audio; else the local synthesiser; else (if nothing else made a noise) the ding. */
-export async function deliverSpeech(prepared, text, config, { dingIfSilent = false } = {}) {
+export async function deliverSpeech(prepared, text, config, { dingIfSilent = false, gen = generation } = {}) {
   const engine = providerOf(config).id;
   const errors = prepared.error ? [`${engine}: ${prepared.error}`] : [];
+  // Stopped by the user: that is the end of it, not a reason to try the computer's voice instead.
+  const interrupted = () => ({ ok: true, engine, interrupted: true });
+  if (stoppedSince(gen)) return interrupted();
   if (prepared.wav) {
     try {
       await playWavBuffer(prepared.wav);
-      return { ok: true, engine, voice: config.voice };
+      return stoppedSince(gen) ? interrupted() : { ok: true, engine, voice: config.voice };
     } catch (e) {
+      if (stoppedSince(gen)) return interrupted();
       errors.push(`playback: ${e.message}`);
     }
   }
@@ -366,15 +466,16 @@ export async function deliverSpeech(prepared, text, config, { dingIfSilent = fal
  * the speaker is claimed, so a queued agent waits for playback, not for the network.
  * The ding and the voice after it are one turn: another agent cannot cut between them.
  */
-export async function playAlert({ methods, config, text, prepared }) {
+export async function playAlert({ methods, config, text, prepared, who = null }) {
   const results = {};
   const wantsSpeech = methods.includes("speech");
   if (wantsSpeech || methods.includes("sound")) warmUpAudio();
   const speech = wantsSpeech ? await (prepared ?? prepareSpeech(text, config)) : null;
   if (!wantsSpeech && !methods.includes("sound")) return results;
 
-  // The ding and the voice are one announcement, so everything else goes quiet for both of them.
-  return withSpeaker((turn) => withOthersQuieter(wantsSpeech ? config : null, async () => {
+  // The ding and the voice are one announcement, so everything else goes quiet for both of them,
+  // and stopping it stops both: a stop during the ding means no voice after it.
+  return withSpeaker((turn) => onAir(who, (gen) => withOthersQuieter(wantsSpeech ? config : null, async () => {
     if (methods.includes("sound")) {
       try {
         await playWav(soundFile(config.sound));
@@ -384,9 +485,12 @@ export async function playAlert({ methods, config, text, prepared }) {
       }
     }
     if (wantsSpeech) {
-      results.speech = await deliverSpeech(speech, text, config, { dingIfSilent: !methods.includes("sound") });
+      results.speech = stoppedSince(gen)
+        ? { ok: true, interrupted: true }
+        : await deliverSpeech(speech, text, config, { dingIfSilent: !methods.includes("sound"), gen });
     }
+    if (stoppedSince(gen)) results.interrupted = true;
     if (turn.waitedMs > 0) results.queued = { waitedMs: turn.waitedMs, ...(turn.tookOver ? { tookOver: true } : {}) };
     return results;
-  }));
+  })));
 }

package/skills/roger-roger/scripts/daemon.mjs

@@ -25,7 +25,7 @@ import {
 } from "./lib.mjs";
 import { lineReader, send, socketPath, PROTOCOL_VERSION } from "./protocol.mjs";
 import { connectSocket, openModal, permalink, postToChannel, updateMessage } from "./slack.mjs";
-import { closeAudio, playAlert, warmUpAudio } from "./audio.mjs";
+import { closeAudio, nowPlaying, onPlaybackChange, playAlert, warmUpAudio } from "./audio.mjs";
 import { FROM_HOOKS, HANDLERS, owedTo, startTray } from "./handlers.mjs";
 import * as progressStore from "./progress.mjs";
 import * as tray from "./tray.mjs";
@@ -99,7 +99,7 @@ function refreshTray({ ifStaleMs = 0 } = {}) {
     snapshotTimer = null;
     snapshotAt = Date.now();
     try {
-      tray.write(tray.snapshot({ config: loadConfig(), daemon: { pid: process.pid, slackConnected: state.slackConnected } }));
+      tray.write(tray.snapshot({ config: loadConfig(), daemon: { pid: process.pid, slackConnected: state.slackConnected, speaking: nowPlaying() } }));
     } catch (e) {
       log(`could not write the tray snapshot: ${e.message}`);
     }
@@ -408,7 +408,7 @@ async function remindIfDue(decision) {
         .catch((e) => log(`${decision.id}: reminder post failed: ${e.message}`))
     : null;
   try {
-    await playAlert({ methods, config, text: "[neutral] Quick reminder. I'm still waiting for your answer in Slack." });
+    await playAlert({ methods, config, text: "[neutral] Quick reminder. I'm still waiting for your answer in Slack.", who: decision.nickname ?? null });
   } catch (e) {
     log(`${decision.id}: reminder audio failed: ${e.message}`);
   }
@@ -563,6 +563,8 @@ async function main() {
   const stamp = codeStamp();
   log(`daemon started on ${socketPath()}`);
   warmUpAudio(); // so the first announcement of the day doesn't wait for a PowerShell to start
+  // The tray shows a Stop button while something plays, so it has to hear when that starts and ends.
+  onPlaybackChange(() => changed("speaking"));
   await stopLegacyDaemon().catch((e) => log(`could not stop the old daemon: ${e.message}`));
   autostartTray();
 

package/skills/roger-roger/scripts/decisions.mjs

@@ -6,6 +6,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { rogerRogerHome, outcomeText, resolvedBlocks, stripTags } from "./lib.mjs";
 import { updateMessage } from "./slack.mjs";
+import * as activity from "./activity.mjs";
 
 const KEEP_RESOLVED_MS = 7 * 24 * 3600 * 1000;
 
@@ -114,6 +115,14 @@ export async function settle(id, patch, log = () => {}, { waiting = false } = {}
   const owed = Boolean(current.sessionId) && patch.status === "answered";
   const settled = { ...current, ...patch, resolvedAt: now, ...(owed ? { deliveredAt: waiting ? now : null } : {}) };
   write(settled);
+  const byUser = settled.status === "answered" && !settled.answer?.auto;
+  activity.record({
+    from: byUser ? "user" : "agent",
+    kind: settled.status === "answered" ? "answer" : settled.status,
+    agent: activity.agentOf({ nickname: settled.nickname, swatch: settled.swatch, colour: settled.colour }),
+    text: activity.answerText(settled),
+    detail: settled.question,
+  });
 
   try {
     const outcome = outcomeText(settled);

package/skills/roger-roger/scripts/handlers.mjs

@@ -20,7 +20,7 @@ import {
 } from "./lib.mjs";
 import {
   deliverSpeech, mapPool, playAlert, playWav, playWavBuffer, prepareSpeech, soundFile,
-  speakLocally, speechAudio, warmUpAudio, withOthersQuieter,
+  interruptPlayback, nowPlaying, onAir, speakLocally, speechAudio, stoppedSince, warmUpAudio, withOthersQuieter,
 } from "./audio.mjs";
 import { withSpeaker } from "./speaker.mjs";
 import { catalog, findVoice, keyFor, missingKey, providerOf, refreshCatalog, testSample } from "./tts.mjs";
@@ -29,6 +29,7 @@ import * as progressStore from "./progress.mjs";
 import * as sessions from "./sessions.mjs";
 import * as inbox from "./inbox.mjs";
 import * as decisions from "./decisions.mjs";
+import * as activity from "./activity.mjs";
 import { labelPane } from "./herdr.mjs";
 import { answeredNotice, isQuestion, matchRequest, permissionNotice, rememberRequest } from "./hooks.mjs";
 
@@ -179,9 +180,10 @@ export async function notify(ctx, args) {
       })().catch((e) => (results.slack = { ok: Boolean(results.slack?.ok), error: e.message }))
     : null;
 
-  Object.assign(results, await playAlert({ methods, config, text, prepared }));
+  Object.assign(results, await playAlert({ methods, config, text, prepared, who: ctx.session?.nickname }));
   await slackJob;
   const succeeded = Object.values(results).some((r) => r.ok);
+  if (succeeded) activity.record({ from: "agent", kind, agent: activity.agentOf(ctx.session), text: message });
   const body = {
     ok: succeeded,
     kind,
@@ -679,6 +681,19 @@ export async function tray(ctx, args) {
  * Quiet for a while, on purpose. Quiet hours are a schedule and a meeting is not one, so this is
  * the ad-hoc version: sound and speech off until it runs out, Slack untouched.
  */
+/**
+ * Stop the voice (or sound) playing right now: the tray's Stop button, or `roger-roger hush`. Only
+ * this announcement; the next one plays as usual, and the Slack message was posted either way.
+ * It only means anything in the daemon, which is where playback happens.
+ */
+export function hush(ctx) {
+  if (!ctx.daemon) return ok({ ok: true, stopped: false, note: "no daemon, so nothing of roger-roger's is playing" });
+  const playing = nowPlaying();
+  const result = interruptPlayback();
+  if (result.stopped) ctx.log(`hush: stopped ${playing?.who ?? "playback"}`);
+  return ok({ ok: true, stopped: result.stopped, ...(result.stopped && playing?.who ? { who: playing.who } : {}) });
+}
+
 export function snooze(ctx, args) {
   const value = (args._ ?? [])[0] ?? args.for ?? "1h";
   // Snoozing is not setting up: saving here would write the defaults and call that the user's choice.
@@ -835,8 +850,9 @@ export async function ask(ctx, args) {
   });
   sessions.bindThread(ts, ctx.session?.id);
   setState(ctx, "waiting");
+  activity.record({ from: "agent", kind: "question", agent: activity.agentOf(ctx.session), text: question, detail: choices.join(" / ") });
 
-  const audio = await playAlert({ methods: audible, config, text, prepared });
+  const audio = await playAlert({ methods: audible, config, text, prepared, who: ctx.session?.nickname });
   const extra = { audio, ...(attached ? { attached } : {}), ...(muted.length ? { mutedByQuietHours: muted } : {}) };
   if (args.wait !== undefined) return waitFor(ctx, id, parseDuration(args.wait, Infinity), extra);
   // Waiting costs the agent nothing: run it in the background and carry on. It always comes back,
@@ -956,7 +972,7 @@ export async function play(ctx, args) {
   const name = (args._ ?? [])[0] ?? ctx.config?.sound ?? DEFAULTS.sound;
   const sounds = listSounds();
   if (!sounds.includes(name)) fail(`unknown sound "${name}"; available: ${sounds.join(", ")}`);
-  await withSpeaker(() => playWav(soundFile(name)));
+  await withSpeaker(() => onAir("preview", () => playWav(soundFile(name))));
   return ok({ ok: true, played: name });
 }
 
@@ -989,11 +1005,11 @@ export async function say(ctx, args) {
     } catch (e) {
       fail(`${provider.label} failed with the key from ${key.name}: ${e.message}`);
     }
-    await withSpeaker(() => withOthersQuieter(config, () => playWavBuffer(sample.wav)));
+    await withSpeaker(() => onAir("voice test", () => withOthersQuieter(config, () => playWavBuffer(sample.wav))));
     return ok({ ok: true, engine: provider.id, voice: config.voice, model: config.model, keyVar: key.name, cached: sample.cached });
   }
   const prepared = await prepareSpeech(text, config, { local: Boolean(args.local) });
-  const result = await withSpeaker(() => deliverSpeech(prepared, text, config));
+  const result = await withSpeaker(() => onAir("preview", (gen) => deliverSpeech(prepared, text, config, { gen })));
   return ok(result, result.ok ? 0 : 1);
 }
 
@@ -1059,9 +1075,10 @@ export async function previewSounds(ctx, args) {
   const audio = args.local ? sounds.map(() => ({ error: "--local" })) : await prefetch(sounds.map(soundAnnouncement), config);
 
   // The whole run-through is one turn at the speakers, so another agent can't cut in mid-list.
-  const played = await withSpeaker(async () => {
+  const played = await withSpeaker(() => onAir("preview", async (gen) => {
     const done = [];
     for (const [i, name] of sounds.entries()) {
+      if (stoppedSince(gen)) break;
       const entry = { sound: name };
       try {
         if (audio[i].wav) await playWavBuffer(audio[i].wav);
@@ -1078,7 +1095,7 @@ export async function previewSounds(ctx, args) {
       done.push(entry);
     }
     return done;
-  });
+  }));
   const succeeded = played.some((p) => p.ok);
   return ok({ ok: succeeded, order: sounds, played }, succeeded ? 0 : 1);
 }
@@ -1097,9 +1114,10 @@ export async function previewVoices(ctx, args) {
   const audio = await mapPool(voices, 4, (voice) =>
     speechAudio(text(voice), { ...config, voice }).then((wav) => ({ wav }), (e) => ({ error: e.message })));
 
-  const played = await withSpeaker(async () => {
+  const played = await withSpeaker(() => onAir("preview", async (gen) => {
     const done = [];
     for (const [i, voice] of voices.entries()) {
+      if (stoppedSince(gen)) break;
       const entry = { voice, name: byId[voice]?.name ?? voice, ...(byId[voice]?.description ? { character: byId[voice].description } : {}) };
       if (audio[i].error) {
         Object.assign(entry, { ok: false, error: audio[i].error });
@@ -1114,7 +1132,7 @@ export async function previewVoices(ctx, args) {
       done.push(entry);
     }
     return done;
-  });
+  }));
   const succeeded = played.some((p) => p.ok);
   return ok({ ok: succeeded, order: voices, played }, succeeded ? 0 : 1);
 }
@@ -1134,6 +1152,7 @@ export const HANDLERS = {
   messages,
   listen,
   snooze,
+  hush,
   tray,
   ask,
   wait,

package/skills/roger-roger/scripts/help.mjs

@@ -10,8 +10,8 @@ export const TAGLINE = "Bring yourself back to the conversation: your agents rea
 /** Every command: where it belongs, how it is called, what it does, and (for the busy ones) its flags. */
 export const COMMANDS = [
   // ---- setting up
-  { section: "Setting up", name: "install", usage: "[--yes]", summary: "Set everything up in the terminal: the command on your PATH, the skill for every agent, Herdr, Slack, the sound and the voice, hooks, tray. Run it again to change anything. --yes asks nothing and only links the skill.", flags: [["--yes", "no questions: link the skill for every agent on the machine and register with Herdr, then print what was done"]] },
-  { section: "Setting up", name: "uninstall", usage: "[--yes]", summary: "Take it out again: hooks, links, Herdr, the daemon and the tray, settings and tokens, the global command.", flags: [["--yes", "no questions: remove everything except the Slack CLI, then print what was done"]] },
+  { section: "Setting up", name: "install", usage: "[--yes]", summary: "Set everything up in the terminal: the command on your PATH, the skill for every agent and a standing instruction to use it, Herdr, Slack, the sound and the voice, hooks, tray. Run it again to change anything. --yes asks nothing and only links the skill.", flags: [["--yes", "no questions: link the skill for every agent on the machine and register with Herdr, then print what was done. Nothing is written to CLAUDE.md or AGENTS.md"]] },
+  { section: "Setting up", name: "uninstall", usage: "[--yes]", summary: "Take it out again: the standing instruction, hooks, links, Herdr, the daemon and the tray, settings and tokens, the global command.", flags: [["--yes", "no questions: remove everything except the Slack CLI, then print what was done"], ["--slack-cli", "with --yes, remove the Slack CLI and its login as well"]] },
   { section: "Setting up", name: "status", usage: "", summary: "Settings, whether the tokens are there, the daemon, who is running, and every valid option value." },
   {
     section: "Setting up", name: "setup", usage: "[flags]", summary: "Change any setting; the rest are kept.",
@@ -66,6 +66,7 @@ export const COMMANDS = [
   { section: "Reaching the user", name: "control", usage: "[--key NAME] [--wait DURATION]", summary: "Read Pause, Stop and new messages without posting. --wait blocks while paused." },
   { section: "Reaching the user", name: "listen", usage: "[--wait 25m]", summary: "Park until the user says something. Run it in the background as the last thing you do." },
   { section: "Reaching the user", name: "snooze", usage: "[1h|off]", summary: "Sound and speech off for a while; Slack keeps working." },
+  { section: "Reaching the user", name: "hush", usage: "", summary: "Stop the voice or sound playing right now. Only this announcement: the next plays as usual, and the Slack message stays. The tray's Stop button does the same." },
 
   // ---- asking
   {