Update CLAUDE.md — reflects out-of-process architecture, current status, lessons learned

CLAUDE.md

@@ -2,118 +2,125 @@
 
 ## What This Is
 A JUCE-based VST3/AU plugin that:
-1. Hosts any third-party VST3/AU plugin inside itself (audio passes through)
+1. Hosts any third-party VST3/AU plugin in a **separate crash-safe process**
 2. Exposes ALL hosted plugin parameters via a local MCP server (port 16620)
-3. Provides real-time audio analysis (LUFS, FFT bands, stereo width)
+3. Audio routes through shared memory (zero added latency)
 4. Any AI that speaks MCP (Claude Code, Codex CLI, Gemini CLI) can control any plugin
 
 ## Current Status
-- **Sprint 1:** ✅ Done — plugin shell + MCP server responding
-- **Sprint 2:** ✅ Done — hosts Pro-Q 4 (737 params), routes audio, MCP tools wired
-- **Sprint 3:** Next — full MCP client integration test from Claude Code
-- **Sprint 4:** Pending — real-time audio analysis
+- **Sprint 1:** ✅ Done — plugin shell + MCP server
+- **Sprint 2:** ✅ Done — out-of-process plugin hosting, crash-safe, GUI working
+- **Sprint 3:** Next — full MCP client integration test (search/get/set params via curl)
+- **Sprint 4:** Pending — real-time audio analysis (LUFS, FFT)
 
-## Project Decisions (Confirmed)
-- **Platform:** macOS only (for now)
-- **License:** GPL (JUCE GPL mode — no commercial license needed, doesn't hamper project)
-- **VST3 install path:** `~/Library/Audio/Plug-Ins/VST3/`
-- **AU install path:** `~/Library/Audio/Plug-Ins/Components/`
-- **Test plugins:** FabFilter Pro-Q 4 (EQ, 737 params), LA-2A compressor (fewer params)
-- **Xcode:** CLI tools 2410+ (no full Xcode.app needed)
-- **CMake:** 3.28 via pip (system CMake 4.x incompatible with JUCE 8)
-- **DAW:** Ableton Live (primary), Logic Pro (secondary AU test)
-- **Build generator:** Unix Makefiles or Ninja (NOT Xcode generator — no Xcode.app)
+## Architecture: OUT-OF-PROCESS (Crash-Safe)
 
-## Architecture (Single Plugin Host, Not a Graph)
 ```
-PluginBridgeProcessor (AudioProcessor — the outer VST3/AU shell)
-  ├── HostedPluginManager     → loads ONE inner VST3/AU, enumerates params
-  ├── McpServer (httplib)     → JSON-RPC 2.0 on http://127.0.0.1:16620/mcp
-  ├── AudioAnalyser           → LUFS + 7-band FFT + stereo width in processBlock
-  └── processBlock():
-        buffer → hostManager.processBlock(buffer, midi)
-               → output (audio routed through hosted plugin)
+┌─ Ableton Process ─────────────────┐     ┌─ PluginBridgeHelper Process ─────┐
+│                                    │     │                                   │
+│  PluginBridge.vst3 (thin shell)    │     │  Standalone executable            │
+│  ├── McpServer (port 16620)        │     │  ├── Loads third-party plugin     │
+│  ├── HelperConnection              │     │  ├── processBlock via shared mem  │
+│  │   ├── Shared memory (audio)     │◄───►│  ├── Shows plugin GUI (floating)  │
+│  │   ├── Semaphores (sync)         │     │  └── Handles param get/set        │
+│  │   └── Unix socket (IPC/cmds)    │◄───►│                                   │
+│  └── processBlock():               │     │  If crash → only helper dies      │
+│       write shm → signal → wait    │     │  Ableton stays alive              │
+│       read output from shm         │     │                                   │
+└────────────────────────────────────┘     └───────────────────────────────────┘
 ```
 
+**Why out-of-process:** Some plugins (Ozone 12, Kickstart 2) call abort() or show NSAlert during loading, which crashes the entire host process. By running in a separate process, crashes are isolated — Ableton never dies.
+
 ## Build System
 - **JUCE 8** via CMake (git submodule at `/JUCE`)
-- **cpp-httplib** — single header `libs/httplib.h` (MIT)
-- **nlohmann/json** — single header `libs/json.hpp` (MIT)
-- **LUFSMeter** — 4 files in `Source/LufsMeter/` (MIT, from klangfreund/LUFSMeter) — Sprint 4
-- **Target formats:** VST3 + AU (macOS only)
+- **Two build targets:**
+  - `PluginBridge` — VST3/AU plugin (loaded in DAW)
+  - `PluginBridgeHelper` — standalone executable (bundled inside .vst3/Contents/Resources/)
+- **cpp-httplib** — `libs/httplib.h` (MIT, header-only)
+- **nlohmann/json** — `libs/json.hpp` (MIT, header-only)
 - **Build:** `cd build && cmake .. -DCMAKE_C_COMPILER=/usr/bin/cc -DCMAKE_CXX_COMPILER=/usr/bin/c++ && cmake --build . --config Release`
-- **Install:** `COPY_PLUGIN_AFTER_BUILD=TRUE` copies to `~/Library/Audio/Plug-Ins/VST3/`
+- **CMake 3.28** required (via pip — system CMake 4.x incompatible with JUCE 8)
+
+## Project Decisions (Confirmed)
+- **Platform:** macOS only
+- **License:** GPL (JUCE GPL mode)
+- **VST3 install:** `~/Library/Audio/Plug-Ins/VST3/`
+- **Test plugins:** Pro-Q 4, LA-2A, Kickstart 2 (crash test)
+- **Xcode CLI tools:** 2410+
+- **DAW:** Ableton Live 12 (primary)
+
+## IPC Between Plugin ↔ Helper
+- **Audio:** POSIX shared memory (`shm_open` + `mmap`) — zero-copy
+- **Sync:** Named semaphores (`sem_open`) — ~microsecond wakeup
+- **Commands:** Unix domain socket, newline-delimited JSON
+- **Protocol:** See `Source/Shared/IPCProtocol.h` for all message formats
 
 ## MCP Protocol
-- Transport: Streamable HTTP (NOT stdio — we're inside a DAW process)
 - Endpoint: `POST http://127.0.0.1:16620/mcp`
-- Health check: `GET http://127.0.0.1:16620/health`
+- Health: `GET http://127.0.0.1:16620/health`
 - Wire format: JSON-RPC 2.0
-- Handshake: `initialize` → `notifications/initialized` → then tools/list, tools/call
 - 5 tools: `list_plugins`, `search_param`, `get_params`, `set_params`, `get_analysis`
 
-## Key JUCE 8 APIs (Verified — these WORK)
+## Plugin GUI Behavior
+- GUI runs in Helper process as a **floating window** (always-on-top)
+- Uses `NSApplicationActivationPolicyAccessory` — no Dock icon, no focus steal
+- `orderFrontRegardless` — shows without switching away from Ableton
+- Toggle via "Open GUI" / "Close GUI" button in PluginBridge's panel
+- If plugin crashes → GUI disappears, PluginBridge shows "Plugin crashed - click Reload"
+
+## Key JUCE 8 APIs (Verified Working)
 - `formatManager.addFormat(new juce::VST3PluginFormat())` — explicit registration
 - `formatManager.addFormat(new juce::AudioUnitPluginFormat())` — explicit registration
 - `instance->enableAllBuses()` — MUST call before using
 - `plugin->getParameters()` → `Array<AudioProcessorParameter*>`
-- Cast to `juce::AudioPluginInstance::HostedParameter*` for `getParameterID()`
+- `dynamic_cast<juce::AudioPluginInstance::HostedParameter*>(param)` for stable ID
 - `param->beginChangeGesture()` / `setValueNotifyingHost(val)` / `endChangeGesture()`
-- `juce::dsp::FFT` for spectral analysis
-- `juce::PluginDirectoryScanner` for system plugin scan
-- `juce::KnownPluginList` for storing scan results
+- `juce_add_gui_app()` for Helper target in CMake
 
 ## Key JUCE 8 APIs (BROKEN — do NOT use)
-- ❌ `addDefaultFormats()` — deleted in JUCE 8, use explicit addFormat() calls
-- ❌ `addDefaultFormatsToManager()` — also deleted
+- ❌ `addDefaultFormats()` — deleted
+- ❌ `juce::Thread::setCurrentThreadPriority()` — removed, use native pthread
 - ❌ `getParameter(int)` / `setParameter(int, float)` — deprecated, asserts
 
-## Plugin Discovery UX
-- Click "Select Plugin..." button → first click triggers background scan
-- Button shows "Scanning..." while scanning (background thread, non-blocking)
-- After scan: popup menu grouped by manufacturer → plugin name
-- Subsequent clicks: instant menu (cached scan results)
-- NO file browser — clean DAW-style UX
-
-## Design Laws (Non-Negotiable)
-- Never return all parameters — search first, fetch by ID
-- Delta only after param changes
-- Single-line compact responses (numbers only)
-- Batch operations (set 10 params in one call)
-- Silence detection (no analysis if RMS < -60dB)
-- Target: <2,000 tokens per full mixing session
+## macOS-Specific Gotchas (Learned the Hard Way)
+- ❌ `MSG_NOSIGNAL` — doesn't exist on macOS. Use `signal(SIGPIPE, SIG_IGN)` + `SO_NOSIGPIPE`
+- ❌ Plugin scanning in background thread — some plugins show NSAlert → crash. Solution: don't scan at all, just list .vst3/.component files from disk
+- ❌ `NSApplicationActivationPolicyRegular` — steals focus from DAW. Use `Accessory` (policy 1)
+- ❌ `activateIgnoringOtherApps:YES` — switches away from Ableton. Use `orderFrontRegardless` instead
+- ✅ `posix_spawn` — works for launching helper from within a plugin process
 
-## Thread Safety Rules
-- HTTP handlers run on httplib's thread pool — NOT audio thread
-- Plugin scan runs in background thread — NOT message thread (crashes DAW otherwise)
-- Use `CriticalSection` / `ScopedLock` for plugin hot-swap in processBlock
-- Cap httplib thread pool to 2 threads
-- `httplib::Server` lifecycle: constructor starts thread, destructor calls stop()+join()
-
-## What NOT To Do
-- Don't use `AudioProcessorGraph` — we host ONE plugin, not a graph
-- Don't scan plugins on editor open — scan only on button click, in background thread
-- Don't use `addDefaultFormats()` — deleted in JUCE 8
-- Don't use stdio MCP transport — plugin is inside DAW, not a subprocess
-- Don't target Windows yet — macOS only for now
-
-## Repo Structure
+## File Structure
 ```
 pluginbridge/
-├── CLAUDE.md              ← this file
-├── ROADMAP.md             ← full technical roadmap
-├── SYNC.md               ← coordination between HF Claude and Claude Code
-├── CMakeLists.txt         ← JUCE 8 CMake (LANGUAGES C CXX)
-├── .gitignore
-├── JUCE/                  ← git submodule
+├── CMakeLists.txt              (builds PluginBridge + PluginBridgeHelper)
+├── JUCE/                       (git submodule)
 ├── libs/
-│   ├── README.md          ← download instructions
-│   ├── httplib.h          ← cpp-httplib
-│   └── json.hpp           ← nlohmann/json
-└── Source/
-    ├── PluginBridgeProcessor.h/.cpp  ← main AudioProcessor, owns HostedPluginManager + McpServer
-    ├── PluginBridgeEditor.h/.cpp     ← GUI: status + plugin selector popup menu
-    ├── HostedPluginManager.h/.cpp    ← loads VST3/AU, enumerates params, routes audio
-    ├── McpServer.h/.cpp              ← HTTP server, JSON-RPC dispatch, 5 tools
-    └── AudioAnalyser.h/.cpp          ← stub (Sprint 4)
+│   ├── httplib.h
+│   └── json.hpp
+├── Source/
+│   ├── Plugin/                 ← VST3/AU (runs inside Ableton)
+│   │   ├── PluginBridgeProcessor.h/.cpp
+│   │   ├── PluginBridgeEditor.h/.cpp
+│   │   ├── HelperConnection.h/.cpp
+│   │   └── McpServer.h/.cpp
+│   ├── Helper/                 ← Standalone exe (separate process)
+│   │   ├── main.cpp
+│   │   ├── HelperPluginHost.h/.cpp
+│   │   └── HelperIPC.h/.cpp
+│   └── Shared/                 ← Used by both targets
+│       ├── SharedAudioBuffer.h
+│       ├── IPCProtocol.h
+│       └── Constants.h
+├── CLAUDE.md
+├── ROADMAP.md
+└── SYNC.md
 ```
+
+## What NOT To Do
+- Don't load plugins in-process — crashes DAW with misbehaving plugins
+- Don't use `PluginDirectoryScanner` — triggers plugin code execution → crash
+- Don't use `addDefaultFormats()` — deleted in JUCE 8
+- Don't steal focus when showing GUI — use Accessory policy
+- Don't use `MSG_NOSIGNAL` — macOS doesn't have it
+- Don't use `juce::Thread::setCurrentThreadPriority()` — removed in JUCE 8