music: officer-music sidecar + /api/music streaming proxy

Adds an officer-music sidecar that owns an audio-streaming HTTP server, and a
thin authenticating proxy on the platform. All processing (path resolution,
byte-range streaming, ffprobe duration) is in the sidecar; the platform only
authenticates and forwards.

App-facing contract (handoff):
  GET /api/music/stream?path=<home-relative path>&token=<jwt>
    - auth via userMiddleware (Bearer or ?token= for media elements)
    - 200 full / 206 on Range, with Accept-Ranges, Content-Length,
      Content-Range, Content-Type, and X-Audio-Duration (seconds, ffprobe)
    - path resolved within HOME_DIR, traversal-guarded (400); 404 if missing
  Purpose: stream + seek without pre-downloading the whole file — the app can
  read X-Audio-Duration instead of scanning for VBR duration.

Pieces:
- sidecar/music/{index.ts,stream-audio.ts}: Bun.serve on a random port, /stream
  + /health, duration cached by path+mtime; reports its port via a new
  music:server sidecar event on connect.
- api/music/{sidecar-server.ts,router.ts}: capture the port; reverse-proxy
  /api/music/* → sidecar, streaming status + headers through.
- protocol.ts music:server event; hono.ts mounts /api/music; ecosystem adds
  officer-music.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/servers/sidecar/music/index.ts

@@ -0,0 +1,92 @@
+import type { SidecarCommand, SidecarEvent } from '../protocol';
+import { createSidecarConnector } from '../connect';
+import { streamAudioFile } from './stream-audio';
+
+// The music sidecar (officer-music). Same philosophy as the other officer-* sidecars: a singleton
+// process that registers with the API server. It OWNS an audio-streaming HTTP server (all path
+// resolution + streaming + ffprobe duration happens here); the platform API is just a thin proxy that
+// authenticates and forwards to us. The server listens on a random loopback port, reported to the API
+// on connect so it can route `/api/music/*` here.
+
+const API_URL = process.env.API_URL ?? `ws://127.0.0.1:${process.env.PORT ?? '5000'}`;
+
+// ── Audio-streaming HTTP server ──
+
+/** Grab an ephemeral free port by briefly binding one and releasing it. */
+function getFreePort(): number {
+  const probe = Bun.serve({ port: 0, hostname: '127.0.0.1', fetch: () => new Response('') });
+  const port = probe.port;
+  probe.stop(true);
+  if (port == null) throw new Error('failed to acquire a free port');
+  return port;
+}
+
+const port = getFreePort();
+
+const server = Bun.serve({
+  port,
+  hostname: '127.0.0.1',
+  async fetch(req) {
+    const url = new URL(req.url);
+    if (url.pathname === '/health') return new Response('ok');
+    if (url.pathname === '/stream') {
+      const path = url.searchParams.get('path');
+      if (!path) return new Response('path is required', { status: 400 });
+      return streamAudioFile(path, req.headers.get('range'));
+    }
+    return new Response('Not found', { status: 404 });
+  },
+});
+
+console.log(`[music] audio server listening on http://127.0.0.1:${port}`);
+
+// ── Command handlers ──
+
+type ReplyFn = (msg: SidecarEvent) => void;
+
+function handleCommand(cmd: SidecarCommand, reply: ReplyFn) {
+  switch (cmd.type) {
+    case 'ping':
+      reply({ type: 'pong', id: cmd.id });
+      break;
+
+    default:
+      reply({
+        type: 'error',
+        id: (cmd as SidecarCommand).id,
+        error: `Unknown command type: ${(cmd as Record<string, unknown>).type}`,
+      });
+  }
+}
+
+// ── Connect to API server ──
+
+const connection = createSidecarConnector({
+  apiUrl: `${API_URL}/api/sidecar/register`,
+  name: 'music',
+  capabilities: ['music'],
+  onCommand(cmd, reply) {
+    handleCommand(cmd as SidecarCommand, reply as ReplyFn);
+  },
+  onConnected() {
+    // Tell the API where our audio server is listening, so it can proxy /api/music/* here.
+    connection.send({ type: 'music:server', port });
+    console.log(`[music] reported audio server port ${port} to API`);
+  },
+});
+
+// ── Graceful shutdown ──
+
+function shutdown(signal: string) {
+  console.log(`[music] ${signal} received, shutting down...`);
+  try {
+    server.stop(true);
+  } catch {
+    /* already stopped */
+  }
+  connection.destroy();
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));