@bongos/core 1.19.365 → 1.19.366

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.365",
-  "core_contract": "1.19.365",
-  "source_commit": "cf24b657bacb6c291ab9351c73cfd93be421c62f",
+  "core_version": "1.19.366",
+  "core_contract": "1.19.366",
+  "source_commit": "25f9ddadfd356311a69eb302d7b6c065046fb74d",
   "source_ref": "HEAD",
-  "built_at": "2026-08-25T20:07:12.580Z",
+  "built_at": "2026-08-25T20:30:49.191Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 331,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1529,
+    "functional_verbatim": 1536,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1882,
-  "tree_sha256": "7ecb76bb4cadcc01fbe7adb2a6301d5dd509e1d98ab5ea776486fb7499fc877b",
+  "file_count": 1889,
+  "tree_sha256": "69e72536ccdae1d15797d10aad857a6d82a62b87f7699c1f62273750b1618a34",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1602,7 +1602,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "1cda168698104ff12fbe75a28a5f76fd11a2d7311c8ba32ba985874dbff65570"
+      "sha256": "8c92a7b61b7e90dff48de1d2e9444d6f460e1d71c41c45f78554deef4c1cb30b"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2572,7 +2572,7 @@
     {
       "path": "modules/builder-settings/event-sound-prefs.js",
       "mode": "0000644",
-      "sha256": "546e849963a471d1adb417fbbb52d9d0c303098079fbfeb6f8ebdd9173e5b1e7"
+      "sha256": "a4115ffcd3b298959b4ea1b13a0c5bfd645c603ad2dd4361d1340ab645dae435"
     },
     {
       "path": "modules/builder-settings/interaction-prefs.js",
@@ -3384,6 +3384,11 @@
       "mode": "0000644",
       "sha256": "fd1220e4b2716912a03c78b23a7d0c78e4a5f4e325547cdd5207487147aad82c"
     },
+    {
+      "path": "modules/hall-ui/public/alert.wav",
+      "mode": "0000644",
+      "sha256": "d175874039e054abf211670908b33080438ffdf7d3a38b9f9a715c6d066fc21a"
+    },
     {
       "path": "modules/hall-ui/public/atlas.css",
       "mode": "0000644",
@@ -3509,6 +3514,11 @@
       "mode": "0000644",
       "sha256": "098fcc0a3933b6d76086f92840d3b3ddb324de7b4f25cb475d23ad4a346723df"
     },
+    {
+      "path": "modules/hall-ui/public/fanfare.wav",
+      "mode": "0000644",
+      "sha256": "9885b45c517fb078c30673e3fb89faceae4cb3191096e35d8b248ef1d253f9e4"
+    },
     {
       "path": "modules/hall-ui/public/gate.css",
       "mode": "0000644",
@@ -3804,6 +3814,11 @@
       "mode": "0000644",
       "sha256": "8d07f24b287a54fdff6d340972d8cc80e37f8fffb4169834fe051a40e6a196ac"
     },
+    {
+      "path": "modules/hall-ui/public/ship.wav",
+      "mode": "0000644",
+      "sha256": "733c8db2c083c7e7595799a7941f13c9940a5615fde1f23e28d03e2aabce1f3c"
+    },
     {
       "path": "modules/hall-ui/public/style.css",
       "mode": "0000644",
@@ -3829,6 +3844,11 @@
       "mode": "0000644",
       "sha256": "f2c4c154920e8f1019fb1628e187201e6e582ec61b04fa9fb9620be097f44b62"
     },
+    {
+      "path": "modules/hall-ui/public/triumph.wav",
+      "mode": "0000644",
+      "sha256": "0d17be2800724ca4130197f222222fcdad167bde24c068739f5ad4bfb6d6ccd8"
+    },
     {
       "path": "modules/hall-ui/public/watch.css",
       "mode": "0000644",
@@ -4857,12 +4877,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "0c5e3a6968b8cea0f192e4b7afabd3d56ebdfb4c195caa6b2e2c83488f747994"
+      "sha256": "91de7354c10b9722a1189018f827cae48448db443384510dbed0c271c67b6d32"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "690bded1bc02daf39aab34106ac5430080ed1125978e8e4d641b60c9fd465dd9"
+      "sha256": "b690c96c25a37783d84ce670859cdcf52ff3d15629254c379bc52d4c825e7538"
     },
     {
       "path": "public-docs/index.html",
@@ -5624,6 +5644,11 @@
       "mode": "0000644",
       "sha256": "9b936143ae25442fefb52b98949bc33d245d4b3894d778c51926e9da75c92357"
     },
+    {
+      "path": "scripts/gds/gen-sounds.js",
+      "mode": "0000644",
+      "sha256": "321fa3e48fbf0987a133d232b811feea84af8ee7b6d121b1b2a5c5c527841413"
+    },
     {
       "path": "scripts/gds/git-merge-regen.js",
       "mode": "0000644",
@@ -6197,7 +6222,7 @@
     {
       "path": "scripts/gds/ship-io.js",
       "mode": "0000644",
-      "sha256": "dc863484634845b84913532db0606a64006f6a506b97b94ea131dfdc1c1ed245"
+      "sha256": "d881d3de837a0d13f2fcaddac7aec17969e8c2d395db238fe9bf257a0925deff"
     },
     {
       "path": "scripts/gds/ship-land.js",
@@ -6324,6 +6349,11 @@
       "mode": "0000644",
       "sha256": "831de1914642a7dcf7c591c9cc69b37c917122e04428cb1e28fc00b07170b603"
     },
+    {
+      "path": "scripts/gds/turn-end-sound.js",
+      "mode": "0000644",
+      "sha256": "cc6e8640376ada7ceff6a896007b3257c8ea4d943a900eae28433cd41bdd139d"
+    },
     {
       "path": "scripts/gds/update-channel.js",
       "mode": "0000644",
@@ -6727,7 +6757,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "29fe80fe994a985cfbc64db7d7835b09485ed7dceae578fab86d0fcb99eccc46"
+      "sha256": "482e6347bf3fa30bc7f55897307f64ee6be8bf14c5186fa4f882cb53cdb92990"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9199,6 +9229,11 @@
       "mode": "0000644",
       "sha256": "f9b1a7021c96c02a5eb667b2d10003b4c7e256fcaafbbc228b2585c710f1d162"
     },
+    {
+      "path": "tests/sound_player.mjs",
+      "mode": "0000644",
+      "sha256": "42398e730349be5f10e07eb3ec42aa47c9a024371f2f95f96802b990ff0e6f80"
+    },
     {
       "path": "tests/sound_prefs.mjs",
       "mode": "0000644",

package/docs/file-map.md

@@ -412,12 +412,24 @@ To install on a new machine, symlink each routine's directory under `~/.claude/s
 ├── lifecycle-card.js         ← PostToolUse: deterministic delivery of MUTATING lifecycle cards (claim/ship/release) — the write-side mirror of session-cards.js (task 1288)
 ├── pre-compact.js            ← PreCompact: thin reader around eviction-policy.js — emits an eviction directive (blocks to drop + one-line recovery stubs) at the compaction seam (task 1349)
 ├── eviction-policy.js        ← pure deterministic in-session compaction classifier (transcript turns → eviction set + replacement stubs); no I/O, unit-tested in tests/eviction_policy.mjs; consumed by pre-compact.js (task 1348)
-├── stop-sound.js             ← Stop: completion sound on macOS (afplay; Glass / Hero on /tmp/otb-celebrate); silent no-op on other OSes
+├── stop-sound.js             ← ⚠ ABSENT from this repo (see the note below). Superseded anyway: the turn-end sound is now `scripts/gds/turn-end-sound.js`, wired as the Stop hook in `.claude/settings.json` and cross-platform rather than macOS-only (task 1003272)
 └── stop-refcheck.js          ← Stop: deterministic backstop that catches a bare `#NNN` Bongos ref in live session text (autolinks to a 404 GitHub issue) and asks for the clickable form (follow-on to task 929)
 ```
 
+> **⚠ THIS TREE IS STALE: 12 of the 13 files listed above are NOT in this repo** — only `secret-gate.js` exists on disk, and `.claude/settings.json` wires just `SessionStart` (three `scripts/gds/*` probes + the sound-prefs mirror), `PreToolUse` (secret-gate) and `Stop` (`scripts/gds/turn-end-sound.js`). The hook tree went the same way as `.claude/sounds/` — absent from every commit, lost when core was re-seeded to 1.18.0 (task 1003272 found and fixed the sound half of that). Do not assume a hook named here runs; check `.claude/settings.json`. Auditing and either restoring or deleting the other twelve is its own task, not a doc edit.
+
 (Before [#671](https://example.com/builders#/task/671) these ran via `bash` shims — `sync-env-local.sh`, `conductor.sh`, `onboarding-ship-logs.sh`, `rank-change-greeting.sh`, `pull-memory.sh` — which failed on Windows without Git Bash. The Node entries above replaced them.)
 
+**Notification sounds** at `.claude/sounds/` + `modules/hall-ui/public/*.wav` (task 1003272 — the local half of the 5-event sound system, which had never been committed):
+
+```
+.claude/sounds/
+└── play.js                   ← the local player. playSound(<wavName>) — fire-and-forget, never throws, spawns the platform player detached (afplay / paplay / aplay / ffplay / PowerShell SoundPlayer); scales the WAV itself for the master volume because aplay and SoundPlayer have no volume flag. Reads the prefs mirror at instance-config.configPath('sound-prefs.json') with the pre-rename ~/.config/otb/ as fallback. Required (guarded) by scripts/gds/ship-state.js; runnable directly: `node .claude/sounds/play.js ship`
+```
+
+The five base assets live ONCE, in `modules/hall-ui/public/` — served at `/builders/<name>.wav` for the Settings previews and read from the same directory by the player:
+`chime.wav` (pre-existing) plus `alert.wav`, `ship.wav`, `triumph.wav`, `fanfare.wav`, all generated by [`scripts/gds/gen-sounds.js`](../scripts/gds/gen-sounds.js) (`--check` verifies freshness; it never touches `chime.wav`).
+
 **On the droplet (`REDACTED_IP`):**
 
 ```

package/modules/builder-settings/event-sound-prefs.js

@@ -2,12 +2,22 @@
 // src/bongos/event-sound-prefs.js — per-builder per-event sound variant selection
 // (task 582). Extends the mute-toggle system (sound-prefs.js) with variant
 // picking: for each of 5 build events a builder can choose which world-themed
-// sound variant plays. Each variant maps to an EXISTING .wav in .claude/sounds/;
-// the dedicated world-themed audio assets (lyre-pluck.wav etc.) ship separately.
+// sound variant plays. Each variant maps to an EXISTING base .wav; the dedicated
+// per-variant audio (lyre-pluck.wav etc.) would ship separately.
+//
+// WHERE THE BASE WAVS ACTUALLY LIVE (corrected, task 1003272): modules/hall-ui/
+// public/, served at /builders/<name>.wav and read from that same directory by
+// .claude/sounds/play.js. This comment used to say .claude/sounds/, which was
+// true of no commit in this repo's history — for months FOUR of the five base
+// wavs did not exist anywhere, so every variant below except the two backed by
+// `chime` resolved to a 404 and played nothing. All five exist now, and
+// tests/sound_player.mjs asserts that every `wav` named here has a real file.
 
 // 5 build events, ordered for the UI. Each has a world-themed default variant
-// plus alternates. `wav` is the existing .claude/sounds/<name>.wav that backs
-// the variant until dedicated audio ships.
+// plus alternates. `wav` is the existing base sound that backs the variant until
+// dedicated audio ships. Each event's two variants deliberately name DIFFERENT
+// base wavs, so switching the picker audibly changes something — a picker whose
+// options all sounded identical would be a worse lie than no picker.
 const EVENTS = Object.freeze([
   {
     id:    'user-input',

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.365",
+  "version": "1.19.366",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.365",
+      "version": "1.19.366",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.365",
+  "version": "1.19.366",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/gen-sounds.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// scripts/gds/gen-sounds.js — synthesize the notification WAVs (task 1003272).
+//
+// WHY A GENERATOR RATHER THAN FOUR COMMITTED BINARIES. The 5-event sound system
+// (V3.R90, task 1000781) shipped its configuration — the prefs, the toggles, the
+// master volume, the per-event variant picker — and never shipped the audio. Only
+// chime.wav has ever existed in this repo, so four of the five events resolved to
+// a 404 and played nothing. Two prior attempts to fix "sound is broken" (tasks
+// 1001252 and 1000796) were abandoned without reaching that.
+//
+// An opaque binary nobody can regenerate is how a repo loses assets in the first
+// place (the local player itself vanished in the 1.18.0 re-seed and no commit
+// records it). These are simple synthesized tones, so the honest artifact is the
+// recipe: a few dozen lines of additive synthesis anyone can read, adjust, and
+// re-run. `node scripts/gds/gen-sounds.js` is idempotent — same bytes every time,
+// no timestamps, no randomness — so it can be a CI freshness check like the other
+// generators if that is ever wanted.
+//
+// chime.wav IS NOT TOUCHED. It predates this task and is the one asset the system
+// always had; regenerating it would replace a sound builders already know with a
+// different one for no reason. This writes only the four that were missing.
+//
+// WHERE THEY GO, and why one copy. modules/hall-ui/public/ is served at
+// /builders/<name>.wav, which is exactly what settings.js previews
+// (`new Audio('/builders/' + wavName + '.wav')`). The local player
+// (.claude/sounds/play.js) reads the SAME files from that directory rather than
+// keeping a second copy — two copies of an asset are two things to drift.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const RATE = 44100;
+const OUT_DIR = path.resolve(__dirname, '..', '..', 'modules', 'hall-ui', 'public');
+
+// Equal-temperament note table, only the notes these sounds use. Named rather
+// than numeric so the voicings below read as music instead of magic numbers.
+const HZ = {
+  A5: 880.00, D6: 1174.66,
+  C5: 523.25, E5: 659.25, G5: 783.99,
+  C6: 1046.50, E6: 1318.51, G6: 1567.98,
+};
+
+// One struck note: a fundamental plus a little second and third harmonic (a bell
+// is not a sine wave), under an exponential decay with a short fade-in. The
+// fade-in matters — starting a waveform at full amplitude is an audible click.
+function note({ freq, start, dur, gain = 0.5, decay = 4.5 }) {
+  const voices = [
+    { mult: 1, amp: 1.0 },
+    { mult: 2, amp: 0.28 },
+    { mult: 3, amp: 0.10 },
+  ];
+  const attack = Math.min(0.006, dur / 8); // seconds
+  return { freq, start, dur, gain, decay, voices, attack };
+}
+
+// Render a list of notes into one mono float buffer, summed (notes may overlap).
+function render(notes) {
+  const end = notes.reduce((m, n) => Math.max(m, n.start + n.dur), 0);
+  const total = Math.ceil((end + 0.03) * RATE); // a little tail so nothing cuts
+  const buf = new Float64Array(total);
+  for (const n of notes) {
+    const from = Math.floor(n.start * RATE);
+    const len = Math.floor(n.dur * RATE);
+    for (let i = 0; i < len; i++) {
+      const t = i / RATE;
+      const env = Math.exp(-n.decay * t) * Math.min(1, t / n.attack);
+      let s = 0;
+      for (const v of n.voices) s += v.amp * Math.sin(2 * Math.PI * n.freq * v.mult * t);
+      buf[from + i] += s * env * n.gain;
+    }
+  }
+  // Normalize to a consistent peak so no sound is jarringly louder than another,
+  // then a short linear fade-out so the file never ends mid-cycle (another click).
+  let peak = 0;
+  for (let i = 0; i < total; i++) peak = Math.max(peak, Math.abs(buf[i]));
+  const scale = peak > 0 ? 0.82 / peak : 0;
+  const fade = Math.min(total, Math.floor(0.02 * RATE));
+  for (let i = 0; i < total; i++) {
+    let s = buf[i] * scale;
+    const fromEnd = total - 1 - i;
+    if (fromEnd < fade) s *= fromEnd / fade;
+    buf[i] = s;
+  }
+  return buf;
+}
+
+// 16-bit mono PCM, 44100 Hz — byte-for-byte the format of the existing chime.wav,
+// so nothing downstream has to care which file it got.
+function toWav(samples) {
+  const dataBytes = samples.length * 2;
+  const out = Buffer.alloc(44 + dataBytes);
+  out.write('RIFF', 0);
+  out.writeUInt32LE(36 + dataBytes, 4);
+  out.write('WAVE', 8);
+  out.write('fmt ', 12);
+  out.writeUInt32LE(16, 16);      // fmt chunk size
+  out.writeUInt16LE(1, 20);       // PCM
+  out.writeUInt16LE(1, 22);       // mono
+  out.writeUInt32LE(RATE, 24);
+  out.writeUInt32LE(RATE * 2, 28); // byte rate
+  out.writeUInt16LE(2, 32);        // block align
+  out.writeUInt16LE(16, 34);       // bits
+  out.write('data', 36);
+  out.writeUInt32LE(dataBytes, 40);
+  for (let i = 0; i < samples.length; i++) {
+    const clamped = Math.max(-1, Math.min(1, samples[i]));
+    out.writeInt16LE(Math.round(clamped * 32767), 44 + i * 2);
+  }
+  return out;
+}
+
+// The four voicings. Each is written to match what the event MEANS — the labels
+// come from modules/builder-settings/sound-prefs.js.
+const SOUNDS = {
+  // "When Claude needs your input" — a two-tone ask, rising so it reads as a
+  // question. Short and unhurried: this one can fire while someone is thinking.
+  alert: [
+    note({ freq: HZ.A5, start: 0.00, dur: 0.26, gain: 0.5, decay: 7 }),
+    note({ freq: HZ.D6, start: 0.15, dur: 0.40, gain: 0.5, decay: 6 }),
+  ],
+  // "When a task ships" — a settled two-note rise, C5 to G5. A fifth, because it
+  // should sound finished rather than expectant.
+  ship: [
+    note({ freq: HZ.C5, start: 0.00, dur: 0.30, gain: 0.5, decay: 6 }),
+    note({ freq: HZ.G5, start: 0.14, dur: 0.55, gain: 0.5, decay: 4.5 }),
+  ],
+  // "When a big task ships" — the same idea carried further: a major triad
+  // arpeggio landing on the octave.
+  triumph: [
+    note({ freq: HZ.C5, start: 0.00, dur: 0.26, gain: 0.42, decay: 7 }),
+    note({ freq: HZ.E5, start: 0.11, dur: 0.26, gain: 0.42, decay: 7 }),
+    note({ freq: HZ.G5, start: 0.22, dur: 0.30, gain: 0.46, decay: 6 }),
+    note({ freq: HZ.C6, start: 0.34, dur: 0.75, gain: 0.55, decay: 3.4 }),
+  ],
+  // "When you earn a rank promotion" — the brightest of the four, a four-note
+  // fanfare that overlaps into a held top note.
+  fanfare: [
+    note({ freq: HZ.G5, start: 0.00, dur: 0.22, gain: 0.40, decay: 8 }),
+    note({ freq: HZ.C6, start: 0.10, dur: 0.22, gain: 0.44, decay: 8 }),
+    note({ freq: HZ.E6, start: 0.20, dur: 0.26, gain: 0.46, decay: 7 }),
+    note({ freq: HZ.G6, start: 0.31, dur: 0.90, gain: 0.55, decay: 3.0 }),
+  ],
+};
+
+function main() {
+  const check = process.argv.includes('--check');
+  const written = [];
+  const stale = [];
+  for (const [name, notes] of Object.entries(SOUNDS)) {
+    const file = path.join(OUT_DIR, `${name}.wav`);
+    const wav = toWav(render(notes));
+    let current = null;
+    try { current = fs.readFileSync(file); } catch { /* absent */ }
+    if (current && current.equals(wav)) continue;
+    if (check) { stale.push(path.relative(path.resolve(__dirname, '..', '..'), file)); continue; }
+    fs.writeFileSync(file, wav);
+    written.push(`${name}.wav (${wav.length} bytes)`);
+  }
+  if (check) {
+    if (stale.length) {
+      console.error(`gen-sounds --check: STALE — would rewrite ${stale.join(', ')}`);
+      console.error('  run: node scripts/gds/gen-sounds.js  (and commit the result)');
+      process.exit(1);
+    }
+    console.log('gen-sounds --check: up to date.');
+    return;
+  }
+  console.log(written.length
+    ? `gen-sounds: wrote ${written.join(', ')}`
+    : 'gen-sounds: all sounds already current — no changes.');
+}
+
+if (require.main === module) main();
+module.exports = { render, toWav, SOUNDS, RATE };

package/scripts/gds/ship-io.js

@@ -14,8 +14,7 @@ const { playSound } = require('./ship-state.js');
 function playShipBell() {
   let shipWav = 'ship';
   try {
-    const prefsPath = require('path').join(os.homedir(), '.config', 'otb', 'sound-prefs.json');
-    const raw = require('fs').readFileSync(prefsPath, 'utf8');
+    const raw = require('fs').readFileSync(shipPrefsPath(), 'utf8');
     const parsed = JSON.parse(raw);
     const ev = parsed && parsed.event_sounds && parsed.event_sounds['task-shipped'];
     if (typeof ev === 'string') shipWav = ev;
@@ -23,6 +22,20 @@ function playShipBell() {
   playSound(shipWav);
 }
 
+// task 1003272: this used to hardcode ~/.config/otb/, the PRE-RENAME location,
+// while fetch-sound-prefs.js writes the mirror through
+// instance-config.configPath() — today ~/.config/cloudbongos/. Reader and writer
+// were looking at different files, so a builder's chosen ship sound was never
+// found and this always fell through to the 'ship' default. Resolve the SAME way
+// the writer does, with the legacy path as a fallback for an older box.
+function shipPrefsPath() {
+  try {
+    const p = require('../../src/instance-config').configPath('sound-prefs.json');
+    if (require('fs').existsSync(p)) return p;
+  } catch (_) { /* fall through to the legacy location */ }
+  return require('path').join(os.homedir(), '.config', 'otb', 'sound-prefs.json');
+}
+
 // task 1002809: normalize an API error body across BOTH wire shapes — the live
 // ADR 0116 (R01) envelope `{ error: { code, message } }` and the legacy flat
 // `{ error: 'code' }`. Same normalization as claim.js:formatClaimFailure and
@@ -93,6 +106,7 @@ function postLandShipOutcome({ code, liveStatus }) {
 // the early returns are control flow only.
 
 module.exports = {
+  shipPrefsPath,
   apiErrorLine,
   normalizeApiError,
   playShipBell,

package/scripts/gds/turn-end-sound.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// scripts/gds/turn-end-sound.js — the Stop hook that rings when a turn ends
+// (task 1003272).
+//
+// THE TRIGGER THAT NEVER EXISTED. scripts/gds/fetch-sound-prefs.js has always
+// described "a LOCAL Stop hook + ship.js via .claude/sounds/play.js", and
+// sound-prefs.js has always labelled `chime` as "When Claude finishes a turn" —
+// but .claude/settings.json had no Stop hook at all. So the single most
+// noticeable sound in the system had nothing to fire it, on top of the player
+// being absent and four of the five WAVs never having been committed. Three
+// independent gaps, one symptom: "all sound seems bugged".
+//
+// WHY A SCRIPT RATHER THAN AN INLINE HOOK COMMAND. The variant resolution below
+// is the same logic ship-io.js's playShipBell() already uses (read the mirrored
+// prefs, take the event's chosen wav, fall back to a base sound). That is a
+// couple of lines too many for a JSON string, and a hook that cannot be read is
+// a hook nobody will fix.
+//
+// IT MUST ALWAYS EXIT 0 AND FAST. This runs at the end of every turn. It resolves
+// a name, hands it to a fire-and-forget player that spawns detached, and returns;
+// every failure path is a silent no-op. A Stop hook that threw, or that blocked
+// on audio, would make a cosmetic feature everyone's problem.
+
+'use strict';
+
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('node:fs');
+
+// `user-input` is the event whose meaning matches a turn ending — Claude has
+// paused and it is the builder's move. Falls back to `chime`, which is the base
+// sound sound-prefs.js labels "When Claude finishes a turn".
+const EVENT_ID = 'user-input';
+const FALLBACK_WAV = 'chime';
+
+// Resolve the mirror the SAME way fetch-sound-prefs.js writes it
+// (instance-config.configPath — today ~/.config/cloudbongos/), with the
+// pre-rename ~/.config/otb/ as a fallback for an older box. Hardcoding the
+// legacy path is the bug this task found in two other readers; it is not going
+// to be re-introduced here.
+function prefsPath() {
+  try {
+    const p = require('../../src/instance-config').configPath('sound-prefs.json');
+    if (fs.existsSync(p)) return p;
+  } catch (_) { /* fall through */ }
+  return path.join(os.homedir(), '.config', 'otb', 'sound-prefs.json');
+}
+
+function resolveWav() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(prefsPath(), 'utf8'));
+    const chosen = parsed && parsed.event_sounds && parsed.event_sounds[EVENT_ID];
+    if (typeof chosen === 'string' && chosen) return chosen;
+  } catch (_) { /* no mirror yet — the fallback is the honest default */ }
+  return FALLBACK_WAV;
+}
+
+function main() {
+  try {
+    // Guarded exactly like ship-state.js's: on a checkout without the player
+    // (or mid-re-seed) this is a no-op, never a failed turn.
+    let playSound;
+    try {
+      ({ playSound } = require(path.resolve(__dirname, '..', '..', '.claude', 'sounds', 'play.js')));
+    } catch (_) { return; }
+    if (typeof playSound === 'function') playSound(resolveWav());
+  } catch (_) { /* cosmetic, always */ }
+}
+
+if (require.main === module) {
+  main();
+  process.exit(0); // never let a stray handle hold the turn open
+}
+module.exports = { resolveWav, prefsPath, EVENT_ID, FALLBACK_WAV };

package/src/module-api.js

@@ -1160,8 +1160,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.363 with no explicit bump. run 32890225073. (task 1002620)
 //   1.19.365 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.364 with no explicit bump. run 32893443215. (task 1002620)
+//   1.19.366 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.365 with no explicit bump. run 32895705036. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.365'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.366'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/sound_player.mjs

@@ -0,0 +1,345 @@
+// tests/sound_player.mjs — the local notification player and its assets
+// (task 1003272).
+//
+// THE BUG THIS FILE EXISTS TO MAKE UNREPEATABLE. The 5-event sound system
+// (V3.R90, task 1000781) shipped its whole CONFIGURATION — prefs, per-sound
+// toggles, master volume, a per-event variant picker in Settings — and never
+// shipped the audio. `git ls-files` carried exactly one WAV, so four of the five
+// events resolved to a 404 and played nothing, and .claude/sounds/play.js, which
+// four other files require, had never been committed at all. Two previous
+// attempts to fix "sound is broken" (tasks 1001252, 1000796) were abandoned
+// without reaching either fact.
+//
+// So the load-bearing test here is the boring one: EVERY SOUND THE SERVER CAN
+// NAME HAS A FILE (and every file is really playable audio). That is the
+// assertion whose absence let a shipped feature be silent for months.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const player = require(path.join(ROOT, '.claude', 'sounds', 'play.js'));
+const soundPrefs = require(path.join(ROOT, 'modules', 'builder-settings', 'sound-prefs.js'));
+
+const WAV_DIR = path.join(ROOT, 'modules', 'hall-ui', 'public');
+
+function tmpPrefs(obj) {
+  const f = path.join(os.tmpdir(), `otb-test-prefs-${process.pid}-${Math.abs(hash(JSON.stringify(obj)))}.json`);
+  fs.writeFileSync(f, JSON.stringify(obj));
+  return f;
+}
+// A tiny stable hash so the temp name is derived from content, not a clock
+// (Date.now()/Math.random() are avoidable here and make reruns noisier).
+function hash(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) { h = (h * 31 + s.charCodeAt(i)) | 0; }
+  return h;
+}
+
+// Minimal 16-bit mono WAV, for the scaler tests.
+function wav(samples, { bits = 16, extraChunk = false } = {}) {
+  const data = Buffer.alloc(samples.length * 2);
+  samples.forEach((v, i) => data.writeInt16LE(v, i * 2));
+  const pre = extraChunk ? Buffer.concat([Buffer.from('LIST'), u32(4), Buffer.from('INFO')]) : Buffer.alloc(0);
+  const head = Buffer.alloc(36);
+  head.write('RIFF', 0); head.writeUInt32LE(28 + pre.length + data.length, 4); head.write('WAVE', 8);
+  head.write('fmt ', 12); head.writeUInt32LE(16, 16); head.writeUInt16LE(1, 20);
+  head.writeUInt16LE(1, 22); head.writeUInt32LE(44100, 24); head.writeUInt32LE(88200, 28);
+  head.writeUInt16LE(2, 32); head.writeUInt16LE(bits, 34);
+  return Buffer.concat([head, pre, Buffer.from('data'), u32(data.length), data]);
+}
+function u32(n) { const b = Buffer.alloc(4); b.writeUInt32LE(n); return b; }
+
+// ── the assertion the original bug needed ───────────────────────────────────
+
+test('EVERY sound the server can name has a real file on disk', () => {
+  // KNOWN_SOUNDS is what /me/sound-prefs offers a builder to toggle, and the
+  // event-sound variants resolve to these same stems. A name here with no file
+  // is a toggle for silence — which is exactly what shipped.
+  const known = Object.keys(soundPrefs.SOUND_DEFAULTS || {});
+  assert.ok(known.length >= 5, `expected the 5-event roster, got ${known.length}`);
+  for (const name of known) {
+    const f = path.join(WAV_DIR, `${name}.wav`);
+    assert.ok(fs.existsSync(f), `${name}.wav is MISSING — the server offers this sound and nothing can play it`);
+    assert.ok(fs.statSync(f).size > 1000, `${name}.wav exists but is suspiciously tiny`);
+  }
+});
+
+test('every asset is really 16-bit 44.1kHz mono PCM, like the one that always worked', () => {
+  // Same format as the pre-existing chime.wav, so nothing downstream has to care
+  // which file it was handed.
+  for (const name of Object.keys(soundPrefs.SOUND_DEFAULTS || {})) {
+    const b = fs.readFileSync(path.join(WAV_DIR, `${name}.wav`));
+    assert.equal(b.toString('ascii', 0, 4), 'RIFF', `${name}: not RIFF`);
+    assert.equal(b.toString('ascii', 8, 12), 'WAVE', `${name}: not WAVE`);
+    assert.equal(b.readUInt16LE(20), 1, `${name}: not PCM`);
+    assert.equal(b.readUInt16LE(22), 1, `${name}: not mono`);
+    assert.equal(b.readUInt32LE(24), 44100, `${name}: wrong sample rate`);
+    assert.equal(b.readUInt16LE(34), 16, `${name}: not 16-bit`);
+  }
+});
+
+test('EVERY event-sound variant resolves to a real file, and each event offers a real CHOICE', () => {
+  // The Settings variant picker offered names like "Lyre Pluck" and "Bronze
+  // Fanfare" that resolved to wavs which did not exist — selectable options for
+  // silence. Both halves are asserted: the file is there, and an event's variants
+  // are not all the same sound (a picker whose options are identical is a lie).
+  const eventPrefs = require(path.join(ROOT, 'modules', 'builder-settings', 'event-sound-prefs.js'));
+  const events = eventPrefs.EVENTS || eventPrefs.default || [];
+  assert.equal(events.length, 5, 'the 5-event roster');
+  for (const ev of events) {
+    assert.ok(ev.variants.length >= 2, `${ev.id}: a picker needs something to pick`);
+    for (const v of ev.variants) {
+      assert.ok(fs.existsSync(path.join(WAV_DIR, `${v.wav}.wav`)),
+        `${ev.id}/${v.id} names ${v.wav}.wav, which does not exist — a selectable silence`);
+    }
+    const distinct = new Set(ev.variants.map((v) => v.wav));
+    assert.equal(distinct.size, ev.variants.length,
+      `${ev.id}: its variants must map to DIFFERENT sounds, or switching changes nothing`);
+    assert.equal(ev.variants.filter((v) => v.isDefault).length, 1, `${ev.id}: exactly one default`);
+  }
+});
+
+test('the generator is idempotent, so the assets are reproducible not mysterious', () => {
+  // --check exits non-zero if a re-run would change any byte. An asset nobody can
+  // regenerate is how this repo lost the player in the first place.
+  execFileSync(process.execPath, [path.join(ROOT, 'scripts', 'gds', 'gen-sounds.js'), '--check'], { stdio: 'pipe' });
+});
+
+test('the generator does NOT touch chime.wav', () => {
+  // chime predates this task and is the sound builders already know; regenerating
+  // it would silently swap a familiar sound for a different one.
+  const gen = require(path.join(ROOT, 'scripts', 'gds', 'gen-sounds.js'));
+  assert.ok(!Object.keys(gen.SOUNDS).includes('chime'));
+  assert.deepEqual(Object.keys(gen.SOUNDS).sort(), ['alert', 'fanfare', 'ship', 'triumph']);
+});
+
+// ── the require that four files depend on ───────────────────────────────────
+
+test("ship-state's guarded require now resolves the REAL player, not its no-op stub", () => {
+  // task 1002199 wrapped this require so a missing player could not crash ship.js.
+  // The guard stays — but it must no longer be what actually runs.
+  const shipState = require(path.join(ROOT, 'scripts', 'gds', 'ship-state.js'));
+  assert.equal(typeof shipState.playSound, 'function');
+  assert.equal(shipState.playSound.name, 'playSound',
+    'the stub is an anonymous arrow; the real one is a named function');
+  assert.ok(shipState.playSound.length >= 1, 'the real player takes a wav name');
+});
+
+// ── the writer and the readers must agree on ONE path ──────────────────────
+
+test('every prefs READER resolves the same path the WRITER uses', () => {
+  // THE FOURTH BUG IN THIS STACK. fetch-sound-prefs.js writes the mirror through
+  // instance-config.configPath() — today ~/.config/cloudbongos/ — while three
+  // readers hardcoded ~/.config/otb/, the PRE-RENAME location. Every one of them
+  // silently found nothing: the player failed open (so the Settings toggles and
+  // master volume had no local effect at all), and the ship bell always fell back
+  // to its default instead of the builder's chosen variant. Nothing errored.
+  const ic = require(path.join(ROOT, 'src', 'instance-config.js'));
+  const canonical = ic.configPath('sound-prefs.json');
+
+  const shipIo = require(path.join(ROOT, 'scripts', 'gds', 'ship-io.js'));
+  const turnEnd = require(path.join(ROOT, 'scripts', 'gds', 'turn-end-sound.js'));
+
+  // The player's canonical path must BE the writer's path.
+  assert.equal(player.PREFS_PATH, canonical, 'play.js must read where the writer writes');
+  // The other two resolve to the canonical path when it exists, else the legacy
+  // one — so assert membership rather than pinning which branch this box takes.
+  for (const [name, got] of [['ship-io', shipIo.shipPrefsPath()], ['turn-end-sound', turnEnd.prefsPath()]]) {
+    assert.ok([canonical, player.LEGACY_PREFS_PATH].includes(got),
+      `${name} resolved ${got}, which is neither the canonical nor the legacy path`);
+  }
+});
+
+test('no reader hardcodes the pre-rename otb path as its ONLY location', () => {
+  // A grep-level guard: the string may appear as a documented FALLBACK, but a
+  // reader whose only path is the legacy one is the bug returning.
+  const files = [
+    path.join(ROOT, '.claude', 'sounds', 'play.js'),
+    path.join(ROOT, 'scripts', 'gds', 'ship-io.js'),
+    path.join(ROOT, 'scripts', 'gds', 'turn-end-sound.js'),
+  ];
+  for (const f of files) {
+    const src = fs.readFileSync(f, 'utf8');
+    if (!src.includes("'otb'")) continue; // no legacy reference at all: fine
+    assert.ok(src.includes('instance-config'),
+      `${path.basename(f)} mentions the legacy otb path without resolving via instance-config`);
+  }
+});
+
+test('the legacy prefs file is still honoured when the canonical one is absent', () => {
+  // An older box has its mirror at the pre-rename path; its saved toggles must
+  // keep working rather than silently resetting to "everything on".
+  const legacyOnly = tmpPrefs({ sounds: { ship: false }, volume: 40 });
+  // readPrefs falls back only when its FIRST path is unreadable, so point it at
+  // an absent file and assert the fallback chain does not throw or lose the shape.
+  const p = player.readPrefs(path.join(os.tmpdir(), 'otb-absent-canonical.json'));
+  assert.equal(typeof p.volume, 'number');
+  assert.equal(typeof p.enabled('ship'), 'boolean');
+  // And the explicit-path form still reads exactly what it is given.
+  const direct = player.readPrefs(legacyOnly);
+  assert.equal(direct.enabled('ship'), false);
+  assert.equal(direct.volume, 40);
+});
+
+test('the Stop hook resolves the builder CHOSEN variant, not just the fallback', () => {
+  // The hook exists at all only as of this task — .claude/settings.json had no
+  // Stop hook, so the "Claude finished a turn" sound had nothing to fire it.
+  const turnEnd = require(path.join(ROOT, 'scripts', 'gds', 'turn-end-sound.js'));
+  assert.equal(turnEnd.EVENT_ID, 'user-input');
+  assert.equal(turnEnd.FALLBACK_WAV, 'chime');
+  const wav = turnEnd.resolveWav();
+  assert.equal(typeof wav, 'string');
+  assert.ok(fs.existsSync(path.join(WAV_DIR, `${wav}.wav`)),
+    `the hook resolved ${wav}, which has no file`);
+});
+
+test('the Stop hook and the prefs mirror are actually WIRED into settings.json', () => {
+  // fetch-sound-prefs.js described "a LOCAL Stop hook" for months while
+  // .claude/settings.json contained no Stop hook and never invoked the mirror.
+  // Documentation is not a trigger.
+  const settings = JSON.parse(fs.readFileSync(path.join(ROOT, '.claude', 'settings.json'), 'utf8'));
+  const cmds = (key) => (settings.hooks?.[key] || []).flatMap((g) => (g.hooks || []).map((h) => h.command));
+  assert.ok(cmds('Stop').some((c) => c.includes('turn-end-sound')), 'no Stop hook rings the turn-end sound');
+  assert.ok(cmds('SessionStart').some((c) => c.includes('fetch-sound-prefs')),
+    'nothing mirrors the prefs, so the toggles cannot take local effect');
+});
+
+// ── path safety: the wav name comes off disk, so it is input ────────────────
+
+test('a wav name is a bare stem — traversal and absolute paths are refused', () => {
+  for (const bad of ['../../etc/passwd', '/etc/passwd', '..', '', 'a/b', 'sh ell', null, undefined, 42, 'x'.repeat(65)]) {
+    assert.equal(player.safeName(bad), null, `${JSON.stringify(bad)} must not be accepted`);
+  }
+  for (const good of ['ship', 'chime', 'bronze-fanfare', 'Alert_2']) {
+    assert.equal(player.safeName(good), good);
+  }
+});
+
+test('playSound refuses a bad name without touching the filesystem', () => {
+  let spawned = 0;
+  const spawnFn = () => { spawned += 1; return { on() {}, unref() {} }; };
+  assert.equal(player.playSound('../../etc/passwd', { spawnFn }), false);
+  assert.equal(player.playSound('nope-not-a-sound', { spawnFn }), false);
+  assert.equal(spawned, 0);
+});
+
+// ── prefs: fail OPEN, because being mutely broken is the bug ────────────────
+
+test('a missing prefs file plays everything (fail open)', () => {
+  const p = player.readPrefs(path.join(os.tmpdir(), 'otb-definitely-absent-prefs.json'));
+  assert.equal(p.volume, 100);
+  assert.equal(p.enabled('ship'), true);
+  assert.equal(p.enabled('anything-at-all'), true);
+});
+
+test('garbage in the prefs file also plays everything', () => {
+  const f = path.join(os.tmpdir(), `otb-test-prefs-garbage-${process.pid}.json`);
+  fs.writeFileSync(f, 'not json at all');
+  const p = player.readPrefs(f);
+  assert.equal(p.volume, 100);
+  assert.equal(p.enabled('ship'), true);
+});
+
+test('only an EXPLICIT false mutes a sound', () => {
+  const p = player.readPrefs(tmpPrefs({ sounds: { ship: false, alert: true }, volume: 70 }));
+  assert.equal(p.enabled('ship'), false);
+  assert.equal(p.enabled('alert'), true);
+  assert.equal(p.enabled('triumph'), true, 'a sound absent from the map is not muted');
+  assert.equal(p.volume, 70);
+});
+
+test('the LEGACY flat prefs shape is still read', () => {
+  // fetch-sound-prefs.js documents that play.js must tolerate the old
+  // { <sound>: <bool> } file, which older boxes still have on disk.
+  const p = player.readPrefs(tmpPrefs({ ship: false, chime: true }));
+  assert.equal(p.enabled('ship'), false);
+  assert.equal(p.enabled('chime'), true);
+  assert.equal(p.volume, 100, 'no volume key in the legacy shape → full');
+});
+
+test('volume is clamped and rounded into 0-100', () => {
+  assert.equal(player.readPrefs(tmpPrefs({ volume: 250 })).volume, 100);
+  assert.equal(player.readPrefs(tmpPrefs({ volume: -30 })).volume, 0);
+  assert.equal(player.readPrefs(tmpPrefs({ volume: 62.6 })).volume, 63);
+  assert.equal(player.readPrefs(tmpPrefs({ volume: 'loud' })).volume, 100);
+  assert.equal(player.readPrefs(tmpPrefs({ volume: NaN })).volume, 100);
+});
+
+test('a muted sound and volume 0 both spawn NOTHING', () => {
+  let spawned = 0;
+  const spawnFn = () => { spawned += 1; return { on() {}, unref() {} }; };
+  assert.equal(player.playSound('ship', { prefsPath: tmpPrefs({ sounds: { ship: false }, volume: 100 }), spawnFn }), false);
+  assert.equal(player.playSound('ship', { prefsPath: tmpPrefs({ sounds: {}, volume: 0 }), spawnFn }), false);
+  assert.equal(spawned, 0, 'silence must not cost a process');
+});
+
+// ── the volume scaler (aplay and PowerShell have no volume flag) ────────────
+
+test('scaleWav halves the samples and preserves the file length', () => {
+  const src = wav([0, 1000, -2000, 32000, -32000]);
+  const out = player.scaleWav(src, 0.5);
+  assert.equal(out.length, src.length);
+  const at = (b, i) => b.readInt16LE(b.length - 10 + i * 2);
+  assert.equal(at(out, 1), 500);
+  assert.equal(at(out, 2), -1000);
+  assert.equal(at(out, 3), 16000);
+});
+
+test('scaleWav clamps rather than wrapping — a gain above 1 must not invert audio', () => {
+  const out = player.scaleWav(wav([32000, -32000]), 2);
+  assert.equal(out.readInt16LE(out.length - 4), 32767);
+  assert.equal(out.readInt16LE(out.length - 2), -32768);
+});
+
+test('scaleWav walks the chunk list instead of assuming data starts at byte 44', () => {
+  // A WAV carrying a LIST chunk before `data` would be corrupted by a naive
+  // fixed-offset scaler — it would scale the metadata and skip the audio.
+  const src = wav([1000, 2000], { extraChunk: true });
+  const out = player.scaleWav(src, 0.5);
+  assert.equal(out.readInt16LE(out.length - 4), 500);
+  assert.equal(out.readInt16LE(out.length - 2), 1000);
+  assert.equal(out.toString('ascii', 36, 40), 'LIST', 'the metadata chunk is left intact');
+});
+
+test('scaleWav leaves anything it does not understand completely alone', () => {
+  const notWav = Buffer.from('this is not audio at all');
+  assert.ok(player.scaleWav(notWav, 0.5).equals(notWav));
+  assert.ok(player.scaleWav(Buffer.alloc(10), 0.5).equals(Buffer.alloc(10)));
+  const eightBit = wav([1000, 2000], { bits: 8 });
+  assert.ok(player.scaleWav(eightBit, 0.5).equals(eightBit), '8-bit is passed through, not mangled');
+});
+
+// ── the spawn, exercised without real audio ────────────────────────────────
+
+test('a playable sound spawns the platform player, detached and unref\'d', () => {
+  const calls = [];
+  const spawnFn = (cmd, args, opts) => { calls.push({ cmd, args, opts }); return { on() {}, unref() {} }; };
+  // playerFor returns null on a machine with no audio binary (CI containers), in
+  // which case there is nothing to assert about the spawn — so this test asserts
+  // the CONTRACT that holds either way: it never throws, and it only ever spawns
+  // when a player exists.
+  const res = player.playSound('ship', { prefsPath: tmpPrefs({ sounds: {}, volume: 100 }), spawnFn });
+  const available = player.playerFor(path.join(WAV_DIR, 'ship.wav')) !== null;
+  assert.equal(res, available, 'plays exactly when this machine has a player');
+  assert.equal(calls.length, available ? 1 : 0);
+  if (available) {
+    assert.equal(calls[0].opts.detached, true, 'audio must not hold the caller open');
+    assert.equal(calls[0].opts.stdio, 'ignore');
+    assert.ok(calls[0].args.some((a) => String(a).includes('ship')), 'the chosen wav reaches the player');
+  }
+});
+
+test('playerFor never throws and returns null or a [cmd, args] pair', () => {
+  const got = player.playerFor('/tmp/whatever.wav');
+  if (got !== null) {
+    assert.equal(typeof got[0], 'string');
+    assert.ok(Array.isArray(got[1]));
+  }
+});