@misaka-net/misakanet-setup 0.4.1 → 0.5.0

package/README.md

@@ -1,7 +1,7 @@
 # @misaka-net/misakanet-setup
 
-One command to teach your **Claude Code**, **Codex**, **Hermes** or **OpenClaw** to check
-MisakaNet's failure lessons before repeating a mistake — and to distil the session's reusable
+One command to teach your **Claude Code**, **Codex**, **Hermes**, **OpenClaw** or **codewhale** to
+check MisakaNet's failure lessons before repeating a mistake — and to distil the session's reusable
 lessons at a checkpoint.
 
 ```bash
@@ -18,6 +18,7 @@ knowledge base on its own instead of guessing.
 |---|---|---|
 | 1 | the agent **can** call it | MCP server `https://misakanet.org/mcp` (streamable HTTP) in `~/.claude.json`, `~/.codex/config.toml` and `~/.openclaw/openclaw.json` (`mcp.servers.misakanet`), with the Bearer token so reads are not metered by the anonymous 5/day/IP limit. Hermes is the same thing in its own files: `mcp_servers.misakanet` in `~/.hermes/config.yaml` plus the token in `~/.hermes/.env` under `MCP_MISAKANET_API_KEY`. All four are config files written file-to-file — no subprocess is spawned, so **no token ever appears in a command line** |
 | 2 | the agent **knows when** | rules block appended to `~/.claude/CLAUDE.md` / `~/.codex/AGENTS.md` / `~/.hermes/SOUL.md` / `~/.openclaw/workspace/AGENTS.md` (issue, retry, risky-operation triggers; desensitisation rules) |
+| 4 | *(opt-in)* you **hear** it | `--voice` adds a `PostToolUse` hook that plays the cue the server asked for (`lesson-found` / `failure-warning` / `connect-success` / `pair-success`). Off by default; mute with `MISAKANET_VOICE=0`; see `docs/integrations/mcp-voice-hooks.md` |
 | 3 | the checkpoint **fires** | a hook that counts user turns: turn 1 announces the install to the user, turn 20 (and every 10 after) injects the "distil and submit" reminder; a failed tool call injects a "search before you retry" reminder built from the error text. Claude Code only today — Codex's user-level hook shape is unconfirmed and OpenClaw's events are unverified, so those two work from the rules block, and `--verify` says so per target instead of implying otherwise |
 
 Without (3) a rule saying "summarise every 20 turns" never fires — agents do not keep
@@ -33,6 +34,8 @@ npx @misaka-net/misakanet-setup --no-register # read-only, no anonymous token
 npx @misaka-net/misakanet-setup --upgrade     # same as installing the latest (the command is idempotent)
                                              # re-running also *refreshes* an older hook (the previous copy
                                              # is kept as ~/.misakanet-agent/hook.mjs.misakanet.bak)
+npx @misaka-net/misakanet-setup --voice       # opt-in: a cue when a search hits, another when it misses
+                                             # (Claude Code: a PostToolUse hook; mute later with MISAKANET_VOICE=0)
 npx @misaka-net/misakanet-setup --uninstall   # remove exactly what it added
 ```
 

package/bin/misakanet-setup.mjs

@@ -23,13 +23,13 @@
  * Everything is idempotent, every rewritten file is backed up to *.misakanet.bak, and
  * --uninstall removes exactly what was added (same markers), leaving user config intact.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, rmSync, chmodSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFileSync, rmSync, chmodSync, statSync } from 'node:fs';
 // No child_process import on purpose: this installer must never hand a file-derived value to
 // another program (the plugin scanner's SHELL_INJECTION_PATTERN, alert #269, and argv secrets
 // are visible to every process on the box). Every target is configured by writing its own
 // config file; commands aimed at the user are printed, never executed.
 import { homedir } from 'node:os';
-import { join, dirname, resolve } from 'node:path';
+import { delimiter, join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -69,7 +69,7 @@ const valueOf = (flag, dflt) => {
 const only = valueOf('--only', '').split(',').map((s) => s.trim()).filter(Boolean);
 const DRY = has('--dry-run');
 const HOME = resolve(valueOf('--home', homedir()));
-const AGENTS = ['claude', 'codex', 'hermes', 'openclaw'];
+const AGENTS = ['claude', 'codex', 'hermes', 'openclaw', 'codewhale'];
 
 const done = [];
 const manual = [];
@@ -103,7 +103,7 @@ function readText(path) {
  * meant to prevent is now caught in CI instead, by a test that binds this literal to the
  * manifest — a failing test is a better place for that than a request header.
  */
-const VERSION = '0.4.1';
+const VERSION = '0.5.0';
 
 function backup(path) {
   if (DRY || !readText(path)) return;
@@ -236,6 +236,51 @@ const PROMPT_BLOCK = `遇到报错、要重试一个刚失败的修法、或要
  * on every prompt" is a supply-chain hole, and it buys nothing - `prepack` already puts the
  * canonical hook inside the package. If it is somehow missing, say so instead of fetching.
  */
+/** Is `cmd` on PATH? Presence, not a spawn: this installer deliberately has no
+ *  child_process import (a value derived from a file must never reach a shell — that was the
+ *  shape behind the plugin scanner's shell-injection report). */
+function onPath(cmd) {
+  for (const dir of String(process.env.PATH || '').split(delimiter)) {
+    if (!dir) continue;
+    try {
+      if (statSync(join(dir, cmd)).isFile()) return join(dir, cmd);
+    } catch { /* not here */ }
+  }
+  return '';
+}
+
+/** The first player the voice hook will actually use on this machine. */
+function detectPlayer() {
+  for (const cmd of ['afplay', 'paplay', 'ffplay', 'mpv', 'mpg123', 'cvlc', 'powershell.exe']) {
+    if (onPath(cmd)) return cmd;
+  }
+  return '';
+}
+
+/**
+ * Where the player and the cues come from. Two layouts, and they do **not** share a name:
+ * the shipped copy is `voice/voice-hook.mjs` with the MP3s beside it, while the canonical file
+ * in a repo checkout is `integrations/agent-autostart/voice_hook.mjs` (underscore, like
+ * `checkpoint_reminder.mjs`) with the cues under `docs/assets/voice/`.
+ *
+ * Getting this wrong is invisible locally — a pack step leaves the shipped copy behind — and
+ * only CI caught it: the repo layout was rejected, so `--voice` silently added nothing.
+ */
+function locateVoice() {
+  const shipped = join(PKG_ROOT, 'voice');
+  if (existsSync(join(shipped, 'voice-hook.mjs'))) {
+    return { player: join(shipped, 'voice-hook.mjs'), cues: shipped };
+  }
+  const repo = join(PKG_ROOT, '..', '..', 'integrations', 'agent-autostart');
+  if (existsSync(join(repo, 'voice_hook.mjs'))) {
+    return {
+      player: join(repo, 'voice_hook.mjs'),
+      cues: join(PKG_ROOT, '..', '..', 'docs', 'assets', 'voice'),
+    };
+  }
+  return null;
+}
+
 function locateHook() {
   const candidates = [
     join(PKG_ROOT, 'hook', 'checkpoint_reminder.mjs'),      // shipped in the tarball
@@ -352,6 +397,7 @@ function detect(agent) {
     codex: ['.codex'],
     hermes: ['.hermes'],
     openclaw: ['.openclaw'],
+    codewhale: ['.codewhale'],
   }[agent] || [];
   return paths.some((p) => existsSync(join(HOME, p)));
 }
@@ -399,6 +445,52 @@ async function installClaude(hookPath, bearer) {
     settings.hooks[event] = bucket;
     changed = true;
   }
+  // Voice cues are opt-in (`--voice`): the server answers with a `voice` field, and this
+  // turns it into a sound through a PostToolUse hook. Default off on purpose — an assistant
+  // that starts talking on its own is exactly the kind of surprise this installer exists to
+  // avoid. `MISAKANET_VOICE=0` mutes it later without uninstalling anything.
+  if (has('--voice')) {
+    const voice = locateVoice();
+    if (!voice) {
+      need('语音钩子：这个 npm 包里没有带播放器（安装不完整）→ 重新执行 npx 安装即可；其它功能不受影响');
+    } else {
+      const destDir = join(stateDir(), 'voice');
+      if (!DRY) {
+        mkdirSync(destDir, { recursive: true });
+        copyFileSync(voice.player, join(destDir, 'voice-hook.mjs'));
+        const cues = existsSync(voice.cues) ? readdirSync(voice.cues).filter((f) => f.endsWith('.mp3')) : [];
+        for (const cue of cues) {
+          copyFileSync(join(voice.cues, cue), join(destDir, cue));
+        }
+        if (!cues.length) {
+          need('语音钩子：找到了播放器但没有找到音频文件 → 重装一次 npx 包即可（其它功能不受影响）');
+        }
+      }
+      const post = settings.hooks.PostToolUse || [];
+      if (!JSON.stringify(post).includes('voice-hook')) {
+        // `matcher: '*'` is load-bearing, not cosmetic: measured on 2026-09-16, a PostToolUse
+        // entry **without** a matcher never fired in this host, while the same command with
+        // `matcher: '*'` fired on every tool call. The hook itself filters by the `voice`
+        // field, so matching everything costs nothing.
+        post.push({
+          matcher: '*',
+          hooks: [{ type: 'command', command: `"${node}" "${join(destDir, 'voice-hook.mjs')}"` }],
+        });
+        settings.hooks.PostToolUse = post;
+        changed = true;
+      }
+      const player = detectPlayer();
+      if (player) {
+        ok(`语音钩子：已开启（PostToolUse → ${player}）；想静音设 MISAKANET_VOICE=0`);
+      } else {
+        need('语音钩子：装上了，但这台机器上没有找到播放器 → 不会有声音'
+          + '（macOS 自带 afplay；Linux 装 paplay 或 ffplay；WSL 会走 Windows 的 PowerShell）');
+      }
+    }
+  } else {
+    ok('语音钩子：未开启（想让命中/未命中时出声：重跑安装器并加 --voice）');
+  }
+
   if (changed) {
     backup(settingsPath);
     writeText(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
@@ -673,6 +765,75 @@ async function installHermes(hookPath, bearer) {
  * The manual `openclaw mcp add …` line is still printed for the user to run themselves — as
  * text, never executed.
  */
+/**
+ * codewhale keeps MCP servers in its own JSON file, and reads workspace rules from a
+ * plain `AGENTS.md` — but only in a *trusted* project (`config.toml`'s
+ * `[projects."<dir>"] trust_level = "trusted"`). So the block goes into the trusted
+ * project directories, which are also where the user actually works, rather than into a
+ * guessed user-level path (checked on 0.9.7: no user-level AGENTS.md is read).
+ *
+ * The token is the one thing codewhale will not take inline: `bearer_token_env_var` names
+ * an environment variable, so "install once" for this agent ends with the user exporting
+ * `MISAKANET_TOKEN` once. That is stated rather than silently half-installed.
+ */
+function codewhaleProjects() {
+  const text = readText(join(HOME, '.codewhale', 'config.toml'));
+  if (!text) return [];
+  const out = [];
+  let current = null;
+  for (const line of text.split('\n')) {
+    const header = line.match(/^\s*\[projects\.(.+?)\]\s*$/);
+    if (header) { current = header[1].trim().replace(/^"|"$/g, ''); continue; }
+    if (/^\s*\[/.test(line)) { current = null; continue; }
+    if (current && /^\s*trust_level\s*=\s*"trusted"/.test(line)) out.push(current);
+  }
+  return out;
+}
+
+async function installCodewhale(bearer) {
+  const cfg = join(HOME, '.codewhale', 'mcp.json');
+  const data = readJson(cfg, null) || {
+    timeouts: { connect_timeout: 10, execute_timeout: 60, read_timeout: 120 },
+    servers: {},
+  };
+  const servers = { ...(data.servers || {}) };
+  const entry = {
+    command: null,
+    args: [],
+    env: {},
+    url: ENDPOINT,
+    connect_timeout: null,
+    execute_timeout: null,
+    read_timeout: null,
+    disabled: false,
+    enabled: true,
+    required: false,
+    enabled_tools: [],
+    disabled_tools: [],
+    bearer_token_env_var: 'MISAKANET_TOKEN',
+  };
+  if (JSON.stringify(servers.misakanet || null) !== JSON.stringify(entry)) {
+    servers.misakanet = entry;
+    backup(cfg);
+    writeText(cfg, `${JSON.stringify({ ...data, servers }, null, 2)}\n`);
+    ok(`codewhale：注册 MCP（streamable-http）→ ${cfg}`);
+  } else {
+    ok('codewhale：MCP 已注册（无改动）');
+  }
+
+  const projects = codewhaleProjects();
+  for (const project of projects) {
+    if (!existsSync(project)) continue;
+    ok(`codewhale：规则块 ${injectBlock(join(project, 'AGENTS.md'), PROMPT_BLOCK)} → ${join(project, 'AGENTS.md')}`);
+  }
+  if (!projects.length) {
+    need('codewhale：没有受信任的项目目录（config.toml 里没有 trust_level = "trusted"）→ '
+      + '先在 codewhale 里打开一次你的项目并信任它，再运行本命令，规则块才会写进去');
+  }
+  need('codewhale：token 只能通过环境变量给 → 在你的 shell 配置里加 `export MISAKANET_TOKEN=<你的 token>`'
+    + '（本机状态：npx @misaka-net/misakanet-setup --verify 会告诉你 token 在哪）');
+}
+
 async function installOpenclaw(bearer) {
   const workspace = openclawWorkspaces()[0];
   const rules = join(workspace, 'AGENTS.md');
@@ -850,6 +1011,20 @@ function uninstall() {
     const rules = join(workspace, 'AGENTS.md');
     if (stripBlock(rules)) ok(`移除规则块 → ${rules}`);
   }
+
+  // codewhale: same two surfaces as the install (its own mcp.json + trusted projects).
+  for (const project of codewhaleProjects()) {
+    const rules = join(project, 'AGENTS.md');
+    if (stripBlock(rules)) ok(`移除规则块 → ${rules}`);
+  }
+  const whaleCfg = join(HOME, '.codewhale', 'mcp.json');
+  const whale = readJson(whaleCfg, null);
+  if (whale?.servers?.misakanet) {
+    delete whale.servers.misakanet;
+    backup(whaleCfg);
+    writeText(whaleCfg, `${JSON.stringify(whale, null, 2)}\n`);
+    ok(`移除 MCP 注册 → ${whaleCfg}`);
+  }
   const cfg = join(HOME, '.claude.json');
   const data = readJson(cfg, null);
   if (data && data.mcpServers?.misakanet) {
@@ -858,12 +1033,20 @@ function uninstall() {
     writeText(cfg, `${JSON.stringify(data, null, 2)}\n`);
     ok(`移除 MCP 注册 → ${cfg}`);
   }
+  const voiceDir = join(stateDir(), 'voice');
+  if (existsSync(voiceDir)) {
+    try {
+      rmSync(voiceDir, { recursive: true, force: true });
+      ok(`移除语音钩子文件 → ${voiceDir}`);
+    } catch { /* best effort */ }
+  }
   const settingsPath = join(HOME, '.claude', 'settings.json');
   const settings = readJson(settingsPath, null);
   if (settings?.hooks) {
     let changed = false;
     for (const event of Object.keys(settings.hooks)) {
-      const kept = (settings.hooks[event] || []).filter((entry) => !JSON.stringify(entry).includes('hook.mjs'));
+      const kept = (settings.hooks[event] || []).filter((entry) =>
+        !JSON.stringify(entry).includes('hook.mjs') && !JSON.stringify(entry).includes('voice-hook'));
       if (kept.length !== settings.hooks[event].length) {
         changed = true;
         if (kept.length) settings.hooks[event] = kept; else delete settings.hooks[event];
@@ -974,6 +1157,7 @@ if (!targets.length) {
     else if (agent === 'codex') await installCodex(hookPath, bearer);
     else if (agent === 'hermes') await installHermes(hookPath, bearer);
     else if (agent === 'openclaw') await installOpenclaw(bearer);
+    else if (agent === 'codewhale') await installCodewhale(bearer);
   }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@misaka-net/misakanet-setup",
-  "version": "0.4.1",
-  "description": "One-command setup: teach your Claude Code / Codex / Hermes / OpenClaw to search MisakaNet failure lessons before repeating a mistake, and to distil the session at a checkpoint.",
+  "version": "0.5.0",
+  "description": "One-command setup: teach your Claude Code / Codex / Hermes / OpenClaw / codewhale to search MisakaNet failure lessons before repeating a mistake, and to distil the session at a checkpoint.",
   "bin": {
     "misakanet-setup": "bin/misakanet-setup.mjs"
   },
@@ -9,6 +9,7 @@
   "files": [
     "bin/misakanet-setup.mjs",
     "hook/checkpoint_reminder.mjs",
+    "voice/",
     "README.md"
   ],
   "scripts": {

package/voice/voice-hook.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * MisakaNet voice hook — play the cue a tool result asked for.
+ *
+ * The MCP server already answers with a `voice` field (`lesson-found` when a search hit,
+ * `failure-warning` when it did not, `connect-success` for a lesson, `pair-success` for a
+ * usage receipt). This hook turns that field into a sound. It is registered as a Claude Code
+ * `PostToolUse` hook by `npx @misaka-net/misakanet-setup --voice`, and it is *opt-in*: nobody
+ * wants an assistant that starts talking on its own.
+ *
+ * Why Node and not the older shell script: that one parses stdin with `python`, and `python`
+ * is not on PATH on many Linux/WSL boxes (`python3` is) — this repo has that exact bug on
+ * record. Node is guaranteed here: the installer itself runs on it.
+ *
+ * Rules it must never break:
+ * - **never block the agent**: the player is spawned detached and the process exits
+ *   immediately, with a hard timeout as a backstop;
+ * - **never fail loudly**: a missing player, a missing MP3 or unparsable stdin all end in
+ *   exit 0 with no output, because a hook that prints to stderr can show up as a tool error;
+ * - **be silent when asked**: `MISAKANET_VOICE=0` mutes it even after it is installed.
+ *
+ * Test/debug affordances:
+ * - `MISAKANET_VOICE_DRY_RUN=1` prints the cue name instead of playing it (that is what the
+ *   test suite uses, so CI never needs an audio device);
+ * - `MISAKANET_VOICE_DIR` overrides where the MP3s live.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CUES = ['connect-success', 'pair-success', 'lesson-found', 'failure-warning'];
+
+/**
+ * Find the first cue name anywhere in the payload.
+ *
+ * Two nests are real, not hypothetical (both observed on 2026-09-16 with Claude Code):
+ *  * `tool_response` is the MCP result, so the cue is one level down;
+ *  * for an MCP tool that value is a **JSON string**, not an object — the whole response is
+ *    escaped inside it. Descending only into objects therefore found nothing even when the
+ *    server had sent the cue.
+ */
+function findCue(value, depth = 0) {
+  if (depth > 8) return '';
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) return '';
+    try {
+      return findCue(JSON.parse(trimmed), depth + 1);
+    } catch {
+      return '';
+    }
+  }
+  if (value === null || typeof value !== 'object') return '';
+  if (typeof value.voice === 'string' && CUES.includes(value.voice)) return value.voice;
+  for (const child of Array.isArray(value) ? value : Object.values(value)) {
+    const found = findCue(child, depth + 1);
+    if (found) return found;
+  }
+  return '';
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function parseCue(raw) {
+  if (!raw) return '';
+  const trimmed = raw.trim();
+  // Claude Code writes one JSON object per line; the CLI sends the whole document.
+  for (const candidate of [trimmed, ...trimmed.split('\n')]) {
+    try {
+      const cue = findCue(JSON.parse(candidate));
+      if (cue) return cue;
+    } catch {
+      /* try the next shape */
+    }
+  }
+  // Last resort: a bare cue name on the line, so a hand-rolled hook still works.
+  const bare = trimmed.match(new RegExp(`\\b(${CUES.join('|')})\\b`));
+  return bare ? bare[1] : '';
+}
+
+/** The path Windows needs, for the WSL case. */
+function windowsPathFor(file) {
+  const drive = file.match(/^\/mnt\/([a-z])\/(.*)$/);
+  if (drive) return `${drive[1].toUpperCase()}:\\${drive[2].replace(/\//g, '\\')}`;
+  const distro = process.env.WSL_DISTRO_NAME;
+  if (distro && file.startsWith('/')) {
+    return `\\\\wsl.localhost\\${distro}${file.replace(/\//g, '\\')}`;
+  }
+  return '';
+}
+
+function isWsl() {
+  return Boolean(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP);
+}
+
+/**
+ * Players in preference order, with the reason each one is where it is.
+ *
+ * `aplay` is deliberately absent: the assets are MP3 and aplay only plays raw/WAV, so the
+ * older shell script's ALSA branch was silent on exactly the machines that reached it.
+ *
+ * On WSL the Windows side comes **first**, and that is not a detail: measured on this
+ * machine, `ffplay` cannot open an ALSA card at all in WSL ("cannot find card '0'"), so the
+ * local-player branch installs a hook that never makes a sound. PowerShell's
+ * presentationCore plays the same file by URI through Windows audio — verified by asking it
+ * for the duration it had loaded (4.2s for `lesson-found`).
+ */
+function players(file) {
+  const winPath = windowsPathFor(file);
+  const powershell = winPath
+    ? [
+        'powershell.exe',
+        [
+          '-NoProfile',
+          '-Command',
+          'Add-Type -AssemblyName presentationCore;'
+            + '$p = New-Object System.Windows.Media.MediaPlayer;'
+            + `$p.Open([uri]'${winPath}'); $p.Play(); Start-Sleep -Seconds 6`,
+        ],
+      ]
+    : null;
+  const local = [
+    ['afplay', [file]], // macOS
+    ['paplay', [file]], // Linux (PulseAudio)
+    ['ffplay', ['-nodisp', '-autoexit', '-loglevel', 'quiet', file]],
+    ['mpv', ['--no-video', '--really-quiet', file]],
+    ['mpg123', ['-q', file]],
+    ['cvlc', ['--play-and-exit', '--intf', 'dummy', file]],
+  ];
+  return powershell && isWsl() ? [powershell, ...local] : [...local, ...(powershell ? [powershell] : [])];
+}
+
+function play(file) {
+  for (const [cmd, args] of players(file)) {
+    try {
+      const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+      child.on('error', () => {});
+      child.unref();
+      return cmd;
+    } catch {
+      /* try the next player */
+    }
+  }
+  return '';
+}
+
+function main() {
+  if (process.env.MISAKANET_VOICE === '0') return;
+  const cue = parseCue(readStdin());
+  if (!cue) return;
+
+  if (process.env.MISAKANET_VOICE_DRY_RUN === '1') {
+    process.stdout.write(`${cue}\n`);
+    return;
+  }
+
+  // The cues sit next to the player when it is installed (…/voice/), next to the canonical
+  // copy in a repo checkout, or under docs/assets/voice/ there. Getting this wrong is silent
+  // by design — which is exactly how the first version of this file shipped mute.
+  const dirs = [
+    process.env.MISAKANET_VOICE_DIR,
+    HERE,
+    join(HERE, 'voice'),
+    join(HERE, '..', '..', 'docs', 'assets', 'voice'),
+  ].filter(Boolean);
+  const file = dirs.map((dir) => join(dir, `${cue}.mp3`)).find((candidate) => existsSync(candidate));
+  if (!file) return;
+  const used = play(file);
+  if (process.env.MISAKANET_VOICE_DEBUG === '1') {
+    // Synchronous write: process.exit(0) below would truncate an async stdout write, and a
+    // hook that prints on the normal path can look like a tool failure.
+    writeFileSync(1, `cue=${cue} player=${used || 'none'} file=${file}\n`);
+  }
+}
+
+try {
+  main();
+} catch {
+  /* a hook must never surface as a tool failure */
+} finally {
+  process.exit(0);
+}
+
+// Backstop: if a detached player leaves this process alive (some players keep a handle),
+// leave anyway. The sound is best-effort by design.
+setTimeout(() => process.exit(0), 3000).unref();