claude-music 1.0.0

package/README.md

@@ -0,0 +1,83 @@
+# claude-music
+
+Live AI background music for Claude Code, scored in real time by Claude itself.
+You type `/music`, music starts playing, and as Claude works it silently steers
+the soundtrack to match — calm and ambient while reading, driving and intense
+while grinding through a hard problem, a victory lap when the tests go green.
+
+Powered by Google's [Magenta RealTime 2](https://github.com/magenta/magenta-realtime)
+(`mrt2_small`, 230M params) running locally on Apple Silicon.
+
+## Install
+
+```bash
+npm install -g claude-music   # or: pnpm add -g claude-music
+claude-music install
+```
+
+`claude-music install` downloads the prebuilt audio daemon and the model, registers
+the MCP server with Claude Code, and installs the `/music` command. **Restart Claude
+Code** afterwards so it loads the MCP server, then:
+
+```
+/music          # start — Claude picks an opening vibe
+/music stop     # stop
+/music status   # what's currently playing
+```
+
+Once running you don't need to do anything — Claude re-vibes on its own as the work
+changes, and music stops when you end the session.
+
+### Requirements
+
+- **Apple-Silicon Mac** (M-series) — required by MLX/Metal.
+- **Node ≥ 18** and the **`claude`** CLI (Claude Code).
+- ~1.3 GB of disk for the model, downloaded on first install.
+
+No Xcode, CMake, or Python needed — the daemon ships as a prebuilt binary. (If a
+prebuilt binary can't be fetched, `install` falls back to building from source,
+which *does* require Xcode CLT + CMake.)
+
+## How it works
+
+```
+Claude Code ──set_music_vibe(prompt)──▶ mrt2-mcp (the `claude-music mcp` server)
+  ──JSON over ~/.mrt2d.sock──▶ mrt2d (C++ daemon, links magentart::core) ──CoreAudio──▶ ♪
+```
+
+- **`mrt2d`** — a C++ daemon wrapping `magentart::core::RealtimeRunner`, streaming
+  audio to CoreAudio and taking prompt commands over a Unix socket. Cached at
+  `~/.claude-music/bin/mrt2d`. Source lives in `daemon/`.
+- **MCP server** (`src/server.ts`, run via `claude-music mcp`) — exposes
+  `set_music_vibe` / `stop_music`. The vibe tool auto-spawns the daemon, so starting
+  music is a single silent tool call.
+- **`templates/music.md`** — the `/music` slash command, installed to
+  `~/.claude/commands/music.md`.
+- The model + resources download to `~/Documents/Magenta/magenta-rt-v2/`.
+
+## CLI
+
+```
+claude-music install        download daemon + model, register MCP, install /music
+claude-music uninstall      remove MCP registration + /music  (--purge: also delete cache + model)
+claude-music doctor         check that everything is installed
+claude-music start|stop|status
+claude-music mcp            run the MCP server (used internally by Claude Code)
+```
+
+Override the daemon binary with `MRT2D_BIN`, or its download URL with
+`CLAUDE_MUSIC_BINARY_URL`.
+
+## Maintainers — cutting a release
+
+The prebuilt daemon is produced by `scripts/build-release.sh`, which builds `mrt2d`
+against a fresh `magenta-realtime` checkout, bundles its non-system dylibs with
+`@loader_path` rewrites, and emits `dist-release/mrt2d-darwin-arm64.tar.gz`:
+
+```bash
+bash scripts/build-release.sh
+# test the artifact end-to-end before publishing:
+CLAUDE_MUSIC_BINARY_URL="file://$PWD/dist-release/mrt2d-darwin-arm64.tar.gz" claude-music install
+# publish to a public GitHub release:
+gh release upload vX.Y.Z dist-release/mrt2d-darwin-arm64.tar.gz --repo <owner>/claude-music
+```

package/daemon/CMakeLists.txt

@@ -0,0 +1,26 @@
+# Consumed by magenta-realtime/CMakeLists.txt via add_subdirectory.
+# All heavy deps (MLX, TFLite, SentencePiece, nlohmann_json, magentart::core)
+# are already configured by the parent project — just add targets here.
+
+add_executable(mrt2d
+    src/main.cpp
+    src/command.cpp
+    src/socket_server.cpp
+    src/audio_output.cpp
+)
+target_include_directories(mrt2d PRIVATE include)
+target_link_libraries(mrt2d PRIVATE
+    magentart::core
+    nlohmann_json::nlohmann_json
+    "-framework CoreAudio"
+    "-framework AudioUnit"
+    "-framework AudioToolbox"
+)
+
+# ---- unit test binaries (no model / audio deps) -----------------------------
+add_executable(test_command tests/test_command.cpp src/command.cpp)
+target_include_directories(test_command PRIVATE include)
+target_link_libraries(test_command PRIVATE nlohmann_json::nlohmann_json)
+
+add_executable(test_socket tests/test_socket.cpp src/socket_server.cpp)
+target_include_directories(test_socket PRIVATE include)

package/daemon/include/audio_output.h

@@ -0,0 +1,36 @@
+#pragma once
+
+#include <AudioUnit/AudioUnit.h>
+#include <cstddef>
+#include <functional>
+
+namespace mrt2d {
+
+// CoreAudio default output unit. Calls fill(L, R, count) from the I/O thread.
+// 48 kHz stereo float32 non-interleaved — matches RealtimeRunner output.
+class AudioOutput {
+public:
+    using FillCallback = std::function<void(float* L, float* R, std::size_t count)>;
+
+    AudioOutput();
+    ~AudioOutput();
+
+    AudioOutput(const AudioOutput&) = delete;
+    AudioOutput& operator=(const AudioOutput&) = delete;
+
+    void start(FillCallback fill);
+    void stop();
+
+private:
+    static OSStatus render_cb(void* refcon,
+                              AudioUnitRenderActionFlags* flags,
+                              const AudioTimeStamp* ts,
+                              UInt32 bus,
+                              UInt32 num_frames,
+                              AudioBufferList* data);
+
+    AudioUnit unit_{nullptr};
+    FillCallback fill_;
+};
+
+}  // namespace mrt2d

package/daemon/include/command.h

@@ -0,0 +1,24 @@
+#pragma once
+
+#include <nlohmann/json.hpp>
+#include <optional>
+#include <string>
+#include <variant>
+
+namespace mrt2d {
+
+struct VibeCommand {
+    std::string prompt;
+};
+
+struct StatusCommand {};
+
+using Command = std::variant<VibeCommand, StatusCommand>;
+
+std::optional<Command> parse_command(const std::string& line);
+
+std::string ack_ok(const std::string& prompt);
+std::string ack_status(bool running, const std::string& prompt);
+std::string ack_error(const std::string& message);
+
+}  // namespace mrt2d

package/daemon/include/socket_server.h

@@ -0,0 +1,30 @@
+#pragma once
+
+#include <atomic>
+#include <functional>
+#include <string>
+
+namespace mrt2d {
+
+class SocketServer {
+public:
+    explicit SocketServer(const std::string& path);
+    ~SocketServer();
+
+    SocketServer(const SocketServer&) = delete;
+    SocketServer& operator=(const SocketServer&) = delete;
+
+    // Block until stop(). Reads newline-delimited messages per client,
+    // writes handler(line) back.
+    void run(std::function<std::string(const std::string&)> handler);
+
+    // Thread-safe. Unblocks run().
+    void stop();
+
+private:
+    std::string path_;
+    int server_fd_{-1};
+    std::atomic<bool> running_{false};
+};
+
+}  // namespace mrt2d

package/daemon/src/audio_output.cpp

@@ -0,0 +1,68 @@
+#include "audio_output.h"
+
+#include <AudioToolbox/AudioToolbox.h>
+#include <stdexcept>
+
+namespace mrt2d {
+
+AudioOutput::AudioOutput() {
+    AudioComponentDescription desc{};
+    desc.componentType         = kAudioUnitType_Output;
+    desc.componentSubType      = kAudioUnitSubType_DefaultOutput;
+    desc.componentManufacturer = kAudioUnitManufacturer_Apple;
+
+    AudioComponent comp = AudioComponentFindNext(nullptr, &desc);
+    if (!comp) throw std::runtime_error("AudioComponentFindNext failed");
+
+    if (AudioComponentInstanceNew(comp, &unit_) != noErr)
+        throw std::runtime_error("AudioComponentInstanceNew failed");
+
+    AudioStreamBasicDescription fmt{};
+    fmt.mSampleRate       = 48000.0;
+    fmt.mFormatID         = kAudioFormatLinearPCM;
+    fmt.mFormatFlags      = kAudioFormatFlagIsFloat | kAudioFormatFlagIsNonInterleaved;
+    fmt.mBytesPerPacket   = 4;
+    fmt.mFramesPerPacket  = 1;
+    fmt.mBytesPerFrame    = 4;
+    fmt.mChannelsPerFrame = 2;
+    fmt.mBitsPerChannel   = 32;
+    AudioUnitSetProperty(unit_, kAudioUnitProperty_StreamFormat,
+                         kAudioUnitScope_Input, 0, &fmt, sizeof(fmt));
+
+    if (AudioUnitInitialize(unit_) != noErr)
+        throw std::runtime_error("AudioUnitInitialize failed");
+}
+
+AudioOutput::~AudioOutput() {
+    stop();
+    if (unit_) { AudioComponentInstanceDispose(unit_); unit_ = nullptr; }
+}
+
+void AudioOutput::start(FillCallback fill) {
+    fill_ = std::move(fill);
+    AURenderCallbackStruct cb{render_cb, this};
+    AudioUnitSetProperty(unit_, kAudioUnitProperty_SetRenderCallback,
+                         kAudioUnitScope_Input, 0, &cb, sizeof(cb));
+    if (AudioOutputUnitStart(unit_) != noErr)
+        throw std::runtime_error("AudioOutputUnitStart failed");
+}
+
+void AudioOutput::stop() {
+    if (unit_) AudioOutputUnitStop(unit_);
+    fill_ = nullptr;
+}
+
+OSStatus AudioOutput::render_cb(void* refcon,
+                                AudioUnitRenderActionFlags*,
+                                const AudioTimeStamp*,
+                                UInt32,
+                                UInt32 num_frames,
+                                AudioBufferList* data) {
+    auto* self = static_cast<AudioOutput*>(refcon);
+    auto* L = static_cast<float*>(data->mBuffers[0].mData);
+    auto* R = static_cast<float*>(data->mBuffers[1].mData);
+    if (self->fill_) self->fill_(L, R, num_frames);
+    return noErr;
+}
+
+}  // namespace mrt2d

package/daemon/src/command.cpp

@@ -0,0 +1,35 @@
+#include "command.h"
+
+namespace mrt2d {
+
+std::optional<Command> parse_command(const std::string& line) {
+    try {
+        auto j = nlohmann::json::parse(line);
+        if (j.contains("prompt")) {
+            return VibeCommand{j["prompt"].get<std::string>()};
+        }
+        if (j.contains("status")) {
+            return StatusCommand{};
+        }
+        return std::nullopt;
+    } catch (...) {
+        return std::nullopt;
+    }
+}
+
+std::string ack_ok(const std::string& prompt) {
+    return nlohmann::json{{"ok", true}, {"prompt", prompt}}.dump() + "\n";
+}
+
+std::string ack_status(bool running, const std::string& prompt) {
+    return nlohmann::json{
+        {"ok", true},
+        {"status", {{"running", running}, {"prompt", prompt}}}
+    }.dump() + "\n";
+}
+
+std::string ack_error(const std::string& message) {
+    return nlohmann::json{{"ok", false}, {"error", message}}.dump() + "\n";
+}
+
+}  // namespace mrt2d

package/daemon/src/main.cpp

@@ -0,0 +1,126 @@
+#include "audio_output.h"
+#include "command.h"
+#include "socket_server.h"
+
+#include <magentart/realtime_runner.h>
+
+#include <atomic>
+#include <csignal>
+#include <cstdio>
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+#include <string>
+#include <unistd.h>
+
+using namespace magentart::core;
+using namespace mrt2d;
+
+static std::atomic<bool> g_running{true};
+static SocketServer*     g_socket = nullptr;
+
+static void on_signal(int) {
+    g_running = false;
+    if (g_socket) g_socket->stop();
+}
+
+static std::string expand_home(const std::string& p) {
+    if (!p.empty() && p[0] == '~') {
+        const char* home = std::getenv("HOME");
+        if (home) return std::string(home) + p.substr(1);
+    }
+    return p;
+}
+
+int main(int argc, char** argv) {
+    std::string model_path   = expand_home("~/Documents/Magenta/magenta-rt-v2/models/mrt2_small/mrt2_small.mlxfn");
+    std::string resource_dir = expand_home("~/Documents/Magenta/magenta-rt-v2/resources");
+    std::string socket_path  = expand_home("~/.mrt2d.sock");
+    std::string pid_path     = expand_home("~/.mrt2d.pid");
+
+    for (int i = 1; i < argc; ++i) {
+        std::string a = argv[i];
+        if      (a == "--model"     && i + 1 < argc) model_path   = argv[++i];
+        else if (a == "--resources" && i + 1 < argc) resource_dir = argv[++i];
+        else if (a == "--socket"    && i + 1 < argc) socket_path  = argv[++i];
+    }
+
+    std::signal(SIGTERM, on_signal);
+    std::signal(SIGINT,  on_signal);
+
+    RealtimeRunner runner;
+
+    std::printf("Loading assets from %s ...\n", resource_dir.c_str());
+    if (!runner.init_assets(resource_dir.c_str())) {
+        std::fprintf(stderr, "init_assets failed\n"); return 1;
+    }
+    std::printf("Loading model %s ...\n", model_path.c_str());
+    if (!runner.load_model(model_path.c_str())) {
+        std::fprintf(stderr, "load_model failed\n"); return 1;
+    }
+    // load_model() starts the inference loop internally, generating from the
+    // model's baked-in initial conditioning state. We deliberately skip
+    // prefill_silence: this small model's SpectroStream encoder is compiled for
+    // a fixed 28s window that the silent-prefill path doesn't match, and
+    // prefill is only a first-second cleanliness optimisation anyway.
+
+    // Max out the output ring buffer (default 2048). Background coding music
+    // doesn't care about latency, so we trade it for the most underrun headroom
+    // the core's lock-free buffer allows — fewer audible glitches if inference
+    // momentarily stalls.
+    runner.set_buffer_size(RingBuffer::kCapacity);
+    std::printf("Ring buffer set to %zu samples (max).\n",
+                runner.get_buffer_size());
+    std::printf("Inference running.\n");
+
+    AudioOutput audio;
+    audio.start([&runner](float* L, float* R, std::size_t count) {
+        runner.read_audio_stereo(L, R, count);
+    });
+    std::printf("Audio output started.\n");
+
+    { std::ofstream pf(pid_path); pf << ::getpid() << "\n"; }
+
+    // Sampling / guidance knobs, matched to Google's shipped MRT2 apps so our
+    // output quality tracks their tuned defaults. Set ALL of them explicitly
+    // rather than relying on engine defaults — the stock cfg_notes default is
+    // 5.0, but Google ships 2.2. These are quality knobs, not musical energy
+    // (energy lives in the prompt text). Tune here to experiment.
+    constexpr float kTemperature  = 1.0f;   // best-sounding; also Google's value
+    constexpr int   kTopK         = 100;
+    constexpr float kCfgMusiccoca = 3.1f;   // "style" guidance
+    constexpr float kCfgNotes     = 2.2f;   // "notes" guidance
+    runner.set_temperature(kTemperature);
+    runner.set_top_k(kTopK);
+    runner.set_cfg_musiccoca(kCfgMusiccoca);
+    runner.set_cfg_notes(kCfgNotes);
+
+    std::string current_prompt = "ambient pads, slow, contemplative, coding session";
+    runner.set_text_prompt(current_prompt);
+
+    SocketServer server(socket_path);
+    g_socket = &server;
+    std::printf("Listening on %s\n", socket_path.c_str());
+
+    server.run([&](const std::string& line) -> std::string {
+        auto cmd = parse_command(line);
+        if (!cmd) return ack_error("parse error");
+
+        return std::visit([&](auto&& c) -> std::string {
+            using T = std::decay_t<decltype(c)>;
+            if constexpr (std::is_same_v<T, VibeCommand>) {
+                current_prompt = c.prompt;
+                runner.set_text_prompt(c.prompt);
+                return ack_ok(current_prompt);
+            } else {
+                return ack_status(true, current_prompt);
+            }
+        }, *cmd);
+    });
+
+    audio.stop();
+    runner.stop();
+    std::filesystem::remove(pid_path);
+    std::printf("Shutdown complete.\n");
+    return 0;
+}

package/daemon/src/socket_server.cpp

@@ -0,0 +1,78 @@
+#include "socket_server.h"
+
+#include <cstring>
+#include <poll.h>
+#include <stdexcept>
+#include <sys/socket.h>
+#include <sys/un.h>
+#include <thread>
+#include <unistd.h>
+
+namespace mrt2d {
+
+SocketServer::SocketServer(const std::string& path) : path_(path) {
+    server_fd_ = ::socket(AF_UNIX, SOCK_STREAM, 0);
+    if (server_fd_ < 0) throw std::runtime_error("socket() failed");
+
+    ::unlink(path_.c_str());
+
+    struct sockaddr_un addr{};
+    addr.sun_family = AF_UNIX;
+    std::strncpy(addr.sun_path, path_.c_str(), sizeof(addr.sun_path) - 1);
+
+    if (::bind(server_fd_, reinterpret_cast<struct sockaddr*>(&addr), sizeof(addr)) < 0)
+        throw std::runtime_error("bind() failed on: " + path_);
+    if (::listen(server_fd_, 8) < 0)
+        throw std::runtime_error("listen() failed");
+}
+
+SocketServer::~SocketServer() {
+    if (server_fd_ >= 0) ::close(server_fd_);
+    ::unlink(path_.c_str());
+}
+
+void SocketServer::run(std::function<std::string(const std::string&)> handler) {
+    running_.store(true, std::memory_order_relaxed);
+    while (running_.load(std::memory_order_relaxed)) {
+        // Poll with a timeout instead of a bare blocking accept() so stop()
+        // (which may be called from a signal handler) is observed within
+        // ~200ms regardless of SA_RESTART / shutdown()-on-listen-socket
+        // portability quirks.
+        struct pollfd pfd{server_fd_, POLLIN, 0};
+        int pr = ::poll(&pfd, 1, 200);
+        if (!running_.load(std::memory_order_relaxed)) break;
+        if (pr <= 0) continue;  // timeout or EINTR — re-check running_
+
+        int client_fd = ::accept(server_fd_, nullptr, nullptr);
+        if (client_fd < 0) continue;
+
+        std::thread([client_fd, handler]() {
+            char buf[4096];
+            std::string partial;
+            while (true) {
+                ssize_t n = ::recv(client_fd, buf, sizeof(buf) - 1, 0);
+                if (n <= 0) break;
+                buf[n] = '\0';
+                partial += buf;
+                size_t pos;
+                while ((pos = partial.find('\n')) != std::string::npos) {
+                    std::string line = partial.substr(0, pos);
+                    partial = partial.substr(pos + 1);
+                    if (!line.empty()) {
+                        std::string resp = handler(line);
+                        ::send(client_fd, resp.c_str(), resp.size(), 0);
+                    }
+                }
+            }
+            ::close(client_fd);
+        }).detach();
+    }
+}
+
+void SocketServer::stop() {
+    // Async-signal-safe: just an atomic store. The poll loop notices within
+    // the poll timeout and returns from run().
+    running_.store(false, std::memory_order_relaxed);
+}
+
+}  // namespace mrt2d

package/daemon/tests/test_command.cpp

@@ -0,0 +1,74 @@
+#include "command.h"
+#include <cassert>
+#include <iostream>
+#include <variant>
+
+int main() {
+    using namespace mrt2d;
+
+    // parse vibe command
+    {
+        auto cmd = parse_command(R"({"prompt":"jazz trio"})");
+        assert(cmd.has_value());
+        assert(std::get<VibeCommand>(*cmd).prompt == "jazz trio");
+        std::cout << "PASS: parse vibe\n";
+    }
+
+    // extra keys (e.g. a legacy intensity field) are ignored
+    {
+        auto cmd = parse_command(R"({"prompt":"x","intensity":0.7})");
+        assert(cmd.has_value());
+        assert(std::get<VibeCommand>(*cmd).prompt == "x");
+        std::cout << "PASS: ignore extra keys\n";
+    }
+
+    // parse status command
+    {
+        auto cmd = parse_command(R"({"status":true})");
+        assert(cmd.has_value());
+        assert(std::holds_alternative<StatusCommand>(*cmd));
+        std::cout << "PASS: parse status\n";
+    }
+
+    // reject malformed JSON
+    {
+        auto cmd = parse_command("not json {{");
+        assert(!cmd.has_value());
+        std::cout << "PASS: reject malformed\n";
+    }
+
+    // reject empty object (no known keys)
+    {
+        auto cmd = parse_command("{}");
+        assert(!cmd.has_value());
+        std::cout << "PASS: reject empty object\n";
+    }
+
+    // ack_ok serialises correctly
+    {
+        auto j = nlohmann::json::parse(ack_ok("jazz"));
+        assert(j["ok"] == true);
+        assert(j["prompt"] == "jazz");
+        std::cout << "PASS: ack_ok\n";
+    }
+
+    // ack_status serialises correctly
+    {
+        auto j = nlohmann::json::parse(ack_status(true, "jazz"));
+        assert(j["ok"] == true);
+        assert(j["status"]["running"] == true);
+        assert(j["status"]["prompt"] == "jazz");
+        std::cout << "PASS: ack_status\n";
+    }
+
+    // ack_error serialises correctly
+    {
+        auto j = nlohmann::json::parse(ack_error("parse error"));
+        assert(j["ok"] == false);
+        assert(j["error"] == "parse error");
+        std::cout << "PASS: ack_error\n";
+    }
+
+    std::cout << "\nAll command tests passed.\n";
+    return 0;
+}

package/daemon/tests/test_socket.cpp

@@ -0,0 +1,89 @@
+#include "socket_server.h"
+
+#include <cassert>
+#include <chrono>
+#include <cstring>
+#include <iostream>
+#include <string>
+#include <sys/socket.h>
+#include <sys/un.h>
+#include <thread>
+#include <unistd.h>
+
+static const char* SOCK = "/tmp/test_mrt2d_socket.sock";
+
+// Connect a Unix socket client, send msg, read one line response.
+static std::string roundtrip(const std::string& msg) {
+    int fd = ::socket(AF_UNIX, SOCK_STREAM, 0);
+    assert(fd >= 0);
+
+    struct sockaddr_un addr{};
+    addr.sun_family = AF_UNIX;
+    std::strncpy(addr.sun_path, SOCK, sizeof(addr.sun_path) - 1);
+    assert(::connect(fd, reinterpret_cast<struct sockaddr*>(&addr), sizeof(addr)) == 0);
+
+    std::string to_send = msg + "\n";
+    ::send(fd, to_send.c_str(), to_send.size(), 0);
+
+    char buf[1024] = {};
+    std::string result;
+    while (result.find('\n') == std::string::npos) {
+        ssize_t n = ::recv(fd, buf, sizeof(buf) - 1, 0);
+        if (n <= 0) break;
+        result.append(buf, n);
+    }
+    ::close(fd);
+    return result;
+}
+
+int main() {
+    mrt2d::SocketServer server(SOCK);
+
+    std::thread srv([&server]() {
+        server.run([](const std::string& line) -> std::string {
+            return "echo:" + line + "\n";
+        });
+    });
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(100));
+
+    // Single message round-trip.
+    {
+        std::string resp = roundtrip("hello");
+        assert(resp == "echo:hello\n");
+        std::cout << "PASS: single message roundtrip\n";
+    }
+
+    // Multiple messages on the same connection.
+    {
+        int fd = ::socket(AF_UNIX, SOCK_STREAM, 0);
+        assert(fd >= 0);
+        struct sockaddr_un addr{};
+        addr.sun_family = AF_UNIX;
+        std::strncpy(addr.sun_path, SOCK, sizeof(addr.sun_path) - 1);
+        assert(::connect(fd, reinterpret_cast<struct sockaddr*>(&addr), sizeof(addr)) == 0);
+
+        for (int i = 0; i < 3; ++i) {
+            std::string msg = "msg" + std::to_string(i) + "\n";
+            ::send(fd, msg.c_str(), msg.size(), 0);
+            char buf[256] = {};
+            std::string resp;
+            while (resp.find('\n') == std::string::npos) {
+                ssize_t n = ::recv(fd, buf, sizeof(buf) - 1, 0);
+                if (n <= 0) break;
+                resp.append(buf, n);
+            }
+            assert(resp == "echo:msg" + std::to_string(i) + "\n");
+        }
+        ::close(fd);
+        std::cout << "PASS: multiple messages same connection\n";
+    }
+
+    // stop() must unblock run() so the thread joins (the SIGTERM-path fix).
+    server.stop();
+    srv.join();
+    std::cout << "PASS: stop() unblocks run()\n";
+
+    std::cout << "\nAll socket tests passed.\n";
+    return 0;
+}