@misaka-net/misakanet-setup 0.4.2 → 0.5.1

package/README.md

@@ -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,11 @@ 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 --report      # this machine's state as YAML, safe to paste in public
+                                             # (token value never printed, home paths written as ~;
+                                             #  two blank fields are yours to fill — see the bounty)
+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));
@@ -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.2';
+const VERSION = '0.5.1';
 
 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
@@ -400,6 +445,62 @@ 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 包即可（其它功能不受影响）');
+        }
+      }
+      let post = settings.hooks.PostToolUse || [];
+      // Upgrade path: 0.4.2 shipped this entry *without* a matcher, which never fires. Treat a
+      // matcher-less entry of ours as stale rather than "already installed", or re-running the
+      // installer would leave a hook that stays silent forever (the exact failure this release
+      // is about).
+      const stale = post.filter((e) => JSON.stringify(e).includes('voice-hook') && e.matcher !== '*');
+      if (stale.length) {
+        post = post.filter((e) => !stale.includes(e));
+        settings.hooks.PostToolUse = post;
+        changed = true;
+      }
+      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`);
@@ -774,6 +875,9 @@ async function installOpenclaw(bearer) {
   ok(`OpenClaw：注册 MCP（streamable-http）→ ${cfg}`);
 }
 
+// The last endpoint probe, recorded so `--report` can print it without probing twice.
+let lastProbe = { reachable: false, tools: 0 };
+
 async function verify() {
   let allOk = true;
   // Handshake, not a search. `tools/list` proves the endpoint speaks MCP and answers, and it
@@ -784,6 +888,7 @@ async function verify() {
   // network was broken (found 2026-09-15 by running the agent chain test on this machine).
   const probe = await mcpRequest('tools/list', {}, 6000, probeEndpoint());
   const tools = Array.isArray(probe?.tools) ? probe.tools : [];
+  lastProbe = { reachable: tools.length > 0, tools: tools.length };
   if (tools.length) {
     ok(`端点可达：${ENDPOINT}（MCP 握手成功，${tools.length} 个工具）`);
   } else if (probe && (probe.error || probe.protocolVersion || probe.serverInfo)) {
@@ -942,12 +1047,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];
@@ -1014,6 +1127,88 @@ function uninstall() {
   }
 }
 
+/**
+ * `--report`: this machine's state as YAML, safe to paste into a public issue.
+ *
+ * Why it exists: the bounty that asks strangers' machines to run the installer also asks them to
+ * report back — and a report that a human has to assemble by hand is (a) rarely sent and (b)
+ * usually containing their token. So the tool prints its own evidence, redacted by construction,
+ * and leaves only the two things it cannot know (which tools the *agent* sees, and a line of
+ * live-call evidence) as empty fields for the reporter to fill.
+ *
+ * Invariants: the token value never appears (only present/absent); every home path is written as
+ * `~`; no hostname, no IP, no user name. `redact()` is deliberately blunt and applied to every
+ * string, including the messages assembled by the checks.
+ */
+function redact(value) {
+  return String(value)
+    .split(HOME).join('~')
+    .replace(/mcp_[A-Za-z0-9_-]{8,}/g, '<REDACTED>')
+    .replace(/sk-[A-Za-z0-9_-]{8,}/g, '<REDACTED>')
+    .replace(/Bearer [A-Za-z0-9_.-]{8,}/gi, 'Bearer <REDACTED>');
+}
+
+function voiceStatus() {
+  try {
+    const settings = readJson(join(HOME, '.claude', 'settings.json'), null);
+    const buckets = settings?.hooks?.PostToolUse;
+    if (!Array.isArray(buckets)) return 'absent';
+    const ours = buckets.filter((entry) => JSON.stringify(entry).includes('voice-hook'));
+    if (!ours.length) return 'absent';
+    return ours.some((entry) => entry.matcher === '*') ? 'on' : 'stale';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function platformName() {
+  if (process.platform === 'win32') return 'windows';
+  if (process.platform === 'darwin') return 'macos';
+  if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) return 'wsl2';
+  return process.platform; // linux
+}
+
+function distroName() {
+  try {
+    const release = readFileSync('/etc/os-release', 'utf8');
+    const id = release.match(/^ID="?([a-z0-9._-]+)"?$/m);
+    return id ? id[1] : 'unknown';
+  } catch {
+    return 'n/a';
+  }
+}
+
+async function report() {
+  const allOk = await verify();
+  const agents = AGENTS.filter((agent) => detect(agent));
+  const token = existsSync(join(stateDir(), 'token'));
+  const lines = [
+    '# MisakaNet setup report — safe to paste in public; the two empty fields at the end are',
+    '# for you to fill (they are the only parts this tool cannot know).',
+    'schema: misakanet-setup-report/1',
+    `setup-version: ${VERSION}`,
+    `os: ${platformName()}`,
+    `distro: ${distroName()}`,
+    `arch: ${process.arch}`,
+    `node: ${process.version}`,
+    `detected-agents: [${agents.join(', ')}]`,
+    `verify: ${allOk ? 'READY' : 'NOT READY'}`,
+    `endpoint-reachable: ${lastProbe.reachable}`,
+    `endpoint-tools: ${lastProbe.tools}`,
+    `token: ${token ? 'present' : 'absent'}`,
+    `hook: ${existsSync(join(stateDir(), 'hook.mjs')) ? 'present' : 'absent'}`,
+    `voice: ${voiceStatus()}`,
+    `open-items: ${manual.length}`,
+    ...(manual.length
+      ? ['open-items-detail:', ...manual.map((m) => `  - ${redact(m)}`)]
+      : []),
+    '# Fill these two in (see the bounty for how):',
+    'tools-visible: {}          # e.g. {codex: 7} — from `codex mcp list` / `codewhale mcp tools`',
+    'live-call-evidence: ""     # one line your agent printed when it called misakanet_search',
+  ];
+  console.log(lines.join('\n'));
+}
+
 // ── main ─────────────────────────────────────────────────────────────
 function render() {
   const out = [];
@@ -1023,9 +1218,15 @@ function render() {
   return out.join('\n');
 }
 
-const mode = has('--uninstall') ? 'uninstall' : (has('--verify') ? 'verify' : 'install');
-console.log(`MisakaNet 安装程序（npx 版）${DRY ? '（--dry-run，不会写任何文件）' : ''}${has('--upgrade') ? '（--upgrade：与安装等价，覆盖安装即升级）' : ''}`);
-console.log(`家目录：${HOME}\n`);
+const mode = has('--uninstall') ? 'uninstall'
+  : (has('--report') ? 'report'
+  : (has('--verify') ? 'verify' : 'install'));
+if (mode !== 'report') {
+  // The banner names the home directory, which is exactly the kind of thing that gets pasted
+  // along with a report — so `--report` prints only the report.
+  console.log(`MisakaNet 安装程序（npx 版）${DRY ? '（--dry-run，不会写任何文件）' : ''}${has('--upgrade') ? '（--upgrade：与安装等价，覆盖安装即升级）' : ''}`);
+  console.log(`家目录：${HOME}\n`);
+}
 
 if (mode === 'uninstall') {
   uninstall();
@@ -1034,6 +1235,14 @@ if (mode === 'uninstall') {
   process.exit(0);
 }
 
+if (mode === 'report') {
+  // Reporting must work before an install too: a bot's first useful data point is often "this
+  // machine has no agent config at all". Exit 0 even when NOT READY — the report is evidence,
+  // not a gate.
+  await report();
+  process.exit(0);
+}
+
 if (mode === 'verify') {
   const allOk = await verify();
   console.log(render());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misaka-net/misakanet-setup",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "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();