@mthines/reaper-mcp 0.8.0 → 0.9.0

package/knowledge/workflows/session-prep.md

@@ -0,0 +1,205 @@
+---
+name: Session Preparation
+id: session-prep
+description: Organize and prepare a REAPER session for mixing — naming, coloring, routing, markers, bus structure
+---
+
+# Session Preparation
+
+## When to Use
+
+Before any mixing begins. Session preparation is the organizational groundwork that makes everything downstream faster and less error-prone. A well-prepared session prevents routing mistakes, makes navigation instant, and ensures no tracks are overlooked.
+
+Use this workflow when:
+- Opening a new session for the first time before mixing
+- A session has grown organically and needs reorganization
+- Tracks have generic names like "Audio_001" or "Track 14"
+- There is no bus/routing structure in place
+- The session has no markers for song sections
+
+## Prerequisites
+
+- REAPER session is open with all recorded tracks
+- You have a general idea of the song structure (verse, chorus, bridge, etc.)
+- No mixing has been done yet (or you are willing to reorganize before continuing)
+
+## Step-by-Step
+
+### Step 1: Save a safety snapshot
+
+```
+tool: snapshot_save
+params:
+  name: "pre-session-prep"
+  description: "State before session organization"
+```
+
+### Step 2: Inventory all tracks
+
+```
+tool: get_project_info
+tool: list_tracks
+```
+
+Note: track count, existing names, any folder/bus structure already present, sample rate, tempo.
+
+Identify each track's instrument/source by its name, audio content, or position. If names are unclear, read media items to check source filenames:
+
+```
+tool: list_media_items
+params:
+  trackIndex: [n]
+```
+
+### Step 3: Rename tracks with descriptive names
+
+Apply clear, consistent names. Standard naming conventions:
+
+| Category | Examples |
+|----------|---------|
+| Drums | Kick In, Kick Out, Snare Top, Snare Bot, Hi-Hat, Tom 1, Tom 2, OH L, OH R, Room L, Room R |
+| Bass | Bass DI, Bass Amp |
+| Guitars | Gtr Rhythm L, Gtr Rhythm R, Gtr Lead, Gtr Clean, Gtr Acoustic |
+| Keys | Piano, Organ, Synth Pad, Synth Lead |
+| Vocals | Lead Vox, BV 1, BV 2, BV Harmony, Dbl Vox |
+| Effects | FX Riser, FX Impact, FX Ambience |
+
+```
+tool: set_track_property
+params:
+  trackIndex: [n]
+  property: "name"
+  value: "Kick In"
+```
+
+### Step 4: Reorder and group tracks
+
+Standard track ordering (top to bottom):
+1. **Drums** — Kick, Snare, Toms, Hi-Hat, Overheads, Room
+2. **Bass** — DI, Amp
+3. **Guitars** — Rhythm (L/R pairs), Lead, Clean, Acoustic
+4. **Keys/Synths** — Piano, Organ, Pads, Leads
+5. **Vocals** — Lead, Doubles, Backing Vocals, Harmonies
+6. **Effects/Samples** — Risers, Impacts, Pads
+7. **Buses** — Drum Bus, Instrument Bus, Vocal Bus, Effects Bus
+8. **Returns** — Reverb, Delay
+9. **Master/Mix Bus** — Always last
+
+### Step 5: Color code by group
+
+Apply consistent colors across the session:
+
+| Group | Suggested Color |
+|-------|----------------|
+| Drums | Blue |
+| Bass | Dark Blue / Navy |
+| Guitars | Green |
+| Keys/Synths | Purple |
+| Vocals | Orange / Yellow |
+| Effects/Samples | Pink / Magenta |
+| Buses | Gray |
+| Returns | Teal |
+
+```
+tool: set_track_property
+params:
+  trackIndex: [n]
+  property: "color"
+  value: "0,100,200"
+```
+
+### Step 6: Set up bus/routing structure
+
+Create submix buses for each instrument group. Typical bus structure:
+
+| Bus | Routes From | Purpose |
+|-----|------------|---------|
+| Drum Bus | All drum tracks | Group processing, glue compression |
+| Bass Bus | Bass DI + Amp | Blend and control |
+| Guitar Bus | All guitar tracks | Group EQ, width control |
+| Vocal Bus | Lead + BVs | Unified vocal processing |
+| Instrument Bus | Guitar Bus + Keys | Non-rhythm instrument group |
+| Effects Bus | FX tracks | Level control for effects |
+| Reverb Return | Aux send destination | Shared reverb space |
+| Delay Return | Aux send destination | Shared delay effects |
+
+Check existing routing first:
+
+```
+tool: get_track_routing
+params:
+  trackIndex: [n]
+```
+
+### Step 7: Add markers for song sections
+
+Navigate through the session and identify song sections. Add markers at each section boundary:
+
+```
+tool: add_marker
+params:
+  position: [seconds]
+  name: "Intro"
+```
+
+Standard section markers:
+- Intro
+- Verse 1
+- Pre-Chorus 1
+- Chorus 1
+- Verse 2
+- Pre-Chorus 2
+- Chorus 2
+- Bridge
+- Chorus 3 / Final Chorus
+- Outro
+
+Optionally add regions for each section:
+
+```
+tool: add_region
+params:
+  startPosition: [seconds]
+  endPosition: [seconds]
+  name: "Chorus 1"
+```
+
+### Step 8: Verify session parameters
+
+```
+tool: get_project_info
+```
+
+Confirm:
+- Sample rate is consistent (44.1 kHz, 48 kHz, etc.)
+- Tempo is correct
+- Time signature is set
+
+### Step 9: Save post-prep snapshot
+
+```
+tool: snapshot_save
+params:
+  name: "post-session-prep"
+  description: "Session organized — tracks named, colored, routed, markers placed"
+```
+
+## Verification
+
+After completing session preparation:
+
+1. Every track has a descriptive name (no "Audio_001" or "Track 14")
+2. Tracks are ordered by instrument group
+3. Each group has a consistent color
+4. Bus structure is in place (at minimum: drum bus, vocal bus)
+5. Song section markers are placed at correct positions
+6. All tracks route to appropriate buses (no orphan tracks going directly to master)
+7. Session parameters are verified
+
+## Common Pitfalls
+
+- **Renaming without checking content**: Listen or check media items before naming — a track labeled "Guitar" might actually be a synth
+- **Over-complex routing**: Start simple. A drum bus, vocal bus, and instrument bus is sufficient for most sessions. Add complexity only when needed.
+- **Forgetting returns**: Reverb and delay sends need return tracks routed to the master bus
+- **Inconsistent naming**: Pick a convention and stick with it — "Lead Vox" or "Lead Vocal" but not both
+- **Not saving a snapshot**: Session prep involves many changes. Save before starting so you can revert if needed.

package/knowledge/workflows/stem-prep.md

@@ -0,0 +1,175 @@
+---
+name: Stem Preparation
+id: stem-prep
+description: Verify bus structure and routing for stem export readiness
+---
+
+# Stem Preparation
+
+## When to Use
+
+After mastering is complete and before final delivery. Stem preparation ensures the session's bus structure, routing, and naming conventions are correct so that exported stems will sum to match the full mix exactly.
+
+Use this workflow when:
+- The mix is complete and mastered, ready for stem export
+- Stems are needed for sync licensing, remix, or immersive audio
+- A mastering engineer has requested stems instead of a stereo mix
+- The session needs routing verification before export
+
+## Prerequisites
+
+- Mix is complete (all mixing and mastering decisions are finalized)
+- Bus structure exists (drum bus, vocal bus, instrument bus, etc.)
+- Session is playing back correctly (no muted tracks that should be active)
+- Genre and delivery specs are known
+
+## Step-by-Step
+
+### Step 1: Save a safety snapshot
+
+```
+tool: snapshot_save
+params:
+  name: "pre-stem-prep"
+  description: "State before stem preparation"
+```
+
+### Step 2: Document the current bus structure
+
+```
+tool: list_tracks
+tool: get_project_info
+```
+
+Map out the full routing hierarchy. For each track:
+
+```
+tool: get_track_routing
+params:
+  trackIndex: [n]
+```
+
+Identify:
+- Which tracks route to which buses
+- Which buses route to the master
+- Any orphan tracks routing directly to master (should go through a bus)
+- Any tracks with sends to multiple destinations
+
+### Step 3: Verify standard stem groups
+
+Typical stem groups for export:
+
+| Stem | Contains | Bus |
+|------|----------|-----|
+| Drums | Kick, Snare, Toms, OH, Room | Drum Bus |
+| Bass | Bass DI, Bass Amp | Bass Bus |
+| Guitars | All guitar tracks | Guitar Bus |
+| Keys/Synths | Piano, Organ, Pads, Leads | Keys Bus |
+| Vocals | Lead, BVs, Harmonies | Vocal Bus |
+| Effects | Reverbs, Delays (printed) | Effects Bus |
+
+Verify each group routes correctly:
+
+```
+tool: get_track_properties
+params:
+  trackIndex: [bus track index]
+```
+
+### Step 4: Check for routing problems
+
+Common issues to flag:
+
+1. **Orphan tracks**: Source tracks routing directly to master instead of through a bus
+2. **Double-routing**: A track routing to both a bus AND the master (will be in the stem AND the full mix twice)
+3. **Missing tracks**: Tracks that are muted or have no output
+4. **Send-only tracks**: Reverb returns that should be captured in a stem but are going to master instead of a bus
+5. **Master bus processing**: Note which FX are on the master bus — stems are typically exported pre-master-bus-processing
+
+For each bus, check that all expected source tracks are present:
+
+```
+tool: get_track_routing
+params:
+  trackIndex: [bus index]
+```
+
+### Step 5: Verify naming conventions
+
+Stems need clear, consistent names for delivery. Verify bus names follow a convention:
+
+```
+[Song Title]_[Stem Name]_[Bit Depth]-[Sample Rate]
+```
+
+Examples:
+- `MySong_Drums_24-48.wav`
+- `MySong_Vocals_24-48.wav`
+- `MySong_Bass_24-48.wav`
+
+Check that bus track names are clean and descriptive:
+
+```
+tool: get_track_properties
+params:
+  trackIndex: [bus index]
+```
+
+Rename if needed:
+```
+tool: set_track_property
+params:
+  trackIndex: [bus index]
+  property: "name"
+  value: "Drum Bus"
+```
+
+### Step 6: Verify technical specs
+
+```
+tool: get_project_info
+```
+
+Confirm:
+- **Sample rate**: Matches delivery requirements (typically 44.1 kHz or 48 kHz)
+- **Bit depth**: 24-bit or 32-bit float for stems
+- **All stems have same duration**: Check that all bus tracks span the full song (from before first note to after last decay)
+
+### Step 7: Document the stem map
+
+Create a clear report of:
+- Each stem name and what tracks it contains
+- Routing chain for each stem
+- Any processing on stem buses (baked into the stem)
+- Master bus processing that will NOT be in individual stems
+- Total stem count
+- Technical specs (sample rate, bit depth)
+
+### Step 8: Save post-prep snapshot
+
+```
+tool: snapshot_save
+params:
+  name: "post-stem-prep"
+  description: "Stems verified — routing correct, naming consistent, ready for export"
+```
+
+## Verification
+
+After completing stem preparation:
+
+1. Every source track routes to exactly one bus (no orphans, no double-routing)
+2. All buses route to the master
+3. Bus names are clear and follow a consistent convention
+4. No tracks are accidentally muted or disabled
+5. Stem groups make musical sense (all drums together, all vocals together, etc.)
+6. Technical specs are documented (sample rate, bit depth, duration)
+7. The user knows which master bus processing will NOT be included in individual stems
+
+## Common Pitfalls
+
+- **Forgetting reverb/delay returns**: Shared effects (reverb bus, delay bus) need to be assigned to a stem or exported as their own stem. If they route to master only, they'll be in the full mix but not in any stem.
+- **Double-counting sends**: If a track sends to both a bus and a reverb return, the dry signal is in one stem and the wet signal might be in another. This is usually correct, but document it.
+- **Master bus processing**: If the master bus has EQ/compression/limiting, individual stems will sound different than the full mix. This is normal — stems are typically pre-master-bus.
+- **Mismatched levels**: All stems should sum to equal the full mix at the master bus. If they don't, there's a routing or level issue.
+- **Not checking mute states**: A muted track won't export. Verify all intended tracks are unmuted and active.

package/main.js

@@ -134,12 +134,14 @@ function getTimeoutCounter() {
 
 // apps/reaper-mcp-server/src/bridge.ts
 import { randomUUID } from "node:crypto";
-import { readFile, writeFile, readdir, unlink, mkdir, stat } from "node:fs/promises";
+import { appendFile, readFile, writeFile, readdir, unlink, mkdir, stat } from "node:fs/promises";
 import { join as join2 } from "node:path";
 import { homedir, platform } from "node:os";
 import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
-var POLL_INTERVAL_MS = 50;
+var POLL_INTERVAL_MS = 10;
 var DEFAULT_TIMEOUT_MS = 1e4;
+var PROFILE_BRIDGE = process.env["BRIDGE_PROFILE"] === "1";
+var lastTimings = null;
 function getReaperResourcePath() {
   const env = process.env["REAPER_RESOURCE_PATH"];
   if (env) return env;
@@ -164,6 +166,10 @@ async function ensureBridgeDir() {
 async function sendCommand(type, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
   const tracer = getTracer();
   const startMs = Date.now();
+  const t = {};
+  const profiling = PROFILE_BRIDGE;
+  const now = profiling ? () => performance.now() : () => 0;
+  const t0 = now();
   return tracer.startActiveSpan(
     `mcp.bridge ${type}`,
     {
@@ -174,7 +180,10 @@ async function sendCommand(type, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
       }
     },
     async (span) => {
+      if (profiling) t["spanSetup"] = now() - t0;
+      const tDir = now();
       const dir = await ensureBridgeDir();
+      if (profiling) t["ensureDir"] = now() - tDir;
       const id = randomUUID();
       span.setAttribute("mcp.command.id", id);
       const command2 = {
@@ -183,8 +192,13 @@ async function sendCommand(type, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
         params,
         timestamp: Date.now()
       };
+      const tWrite = now();
       const commandPath = join2(dir, `command_${id}.json`);
       await writeFile(commandPath, JSON.stringify(command2, null, 2), "utf-8");
+      const notifyPath = join2(dir, "_notify");
+      await appendFile(notifyPath, id + "\n");
+      if (profiling) t["write"] = now() - tWrite;
+      const tLog = now();
       const traceCtx = getTraceContext();
       console.error(
         JSON.stringify({
@@ -194,13 +208,22 @@ async function sendCommand(type, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
           ...traceCtx
         })
       );
+      if (profiling) t["log"] = now() - tLog;
       const responsePath = join2(dir, `response_${id}.json`);
       const deadline = Date.now() + timeoutMs;
+      const tPoll = now();
+      let pollAttempts = 0;
       while (Date.now() < deadline) {
         try {
+          pollAttempts++;
+          const tRead = now();
           const data = await readFile(responsePath, "utf-8");
           const response = JSON.parse(data);
+          if (profiling) t["readParse"] = now() - tRead;
+          if (profiling) t["pollWait"] = now() - tPoll - (t["readParse"] ?? 0);
+          const tCleanup = now();
           await Promise.allSettled([unlink(commandPath), unlink(responsePath)]);
+          if (profiling) t["cleanup"] = now() - tCleanup;
           const durationMs2 = Date.now() - startMs;
           const succeeded = response.success;
           span.setAttribute("mcp.response.success", succeeded);
@@ -219,8 +242,24 @@ async function sendCommand(type, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
             );
           }
           span.end();
+          const tMetrics = now();
           getCommandDurationHistogram().record(durationMs2, { command_type: type });
           getCommandCounter().add(1, { command_type: type, success: String(succeeded) });
+          if (profiling) t["metrics"] = now() - tMetrics;
+          if (profiling) {
+            lastTimings = {
+              spanSetupMs: Math.round(t["spanSetup"] ?? 0),
+              ensureDirMs: Math.round(t["ensureDir"] ?? 0),
+              writeMs: Math.round(t["write"] ?? 0),
+              logMs: Math.round(t["log"] ?? 0),
+              pollWaitMs: Math.round(t["pollWait"] ?? 0),
+              pollAttempts,
+              readParseMs: Math.round(t["readParse"] ?? 0),
+              cleanupMs: Math.round(t["cleanup"] ?? 0),
+              metricsMs: Math.round(t["metrics"] ?? 0),
+              totalMs: Math.round(now() - t0)
+            };
+          }
           return response;
         } catch {
           await sleep(POLL_INTERVAL_MS);
@@ -1797,6 +1836,11 @@ function ensureClaudeSettings(settingsPath) {
   writeFileSync(settingsPath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
   return "updated";
 }
+function resolveAssetDirWithFallback(baseDir, buildName, sourceName) {
+  const resolved = resolveAssetDir(baseDir, buildName);
+  if (existsSync(resolved)) return resolved;
+  return resolveAssetDir(baseDir, sourceName);
+}
 
 // apps/reaper-mcp-server/src/main.ts
 var __dirname = dirname2(fileURLToPath2(import.meta.url));
@@ -1855,7 +1899,7 @@ async function installSkills(scope) {
   } else {
     console.log("Knowledge base not found in package. Skipping.");
   }
-  const rulesSrc = resolveAssetDir(__dirname, "claude-rules");
+  const rulesSrc = resolveAssetDirWithFallback(__dirname, "claude-rules", join4(".claude", "rules"));
   if (existsSync2(rulesSrc)) {
     const dest = join4(claudeDir, "rules");
     const count = copyDirSync(rulesSrc, dest);
@@ -1863,7 +1907,7 @@ async function installSkills(scope) {
   } else {
     console.log("Claude rules not found in package. Skipping.");
   }
-  const skillsSrc = resolveAssetDir(__dirname, "claude-skills");
+  const skillsSrc = resolveAssetDirWithFallback(__dirname, "claude-skills", join4(".claude", "skills"));
   if (existsSync2(skillsSrc)) {
     const dest = join4(claudeDir, "skills");
     const count = copyDirSync(skillsSrc, dest);
@@ -1871,7 +1915,7 @@ async function installSkills(scope) {
   } else {
     console.log("Claude skills not found in package. Skipping.");
   }
-  const agentsSrc = resolveAssetDir(__dirname, "claude-agents");
+  const agentsSrc = resolveAssetDirWithFallback(__dirname, "claude-agents", join4(".claude", "agents"));
   if (existsSync2(agentsSrc)) {
     const dest = join4(claudeDir, "agents");
     const count = copyDirSync(agentsSrc, dest);
@@ -1899,7 +1943,7 @@ Created: ${mcpJsonPath}`);
     }
   }
   console.log("\nDone! Claude Code now has mix engineer agents, knowledge, and REAPER MCP tools.");
-  console.log("All 48 REAPER tools are pre-approved \u2014 agents work autonomously.");
+  console.log(`All ${MCP_TOOL_NAMES.length} REAPER tools are pre-approved \u2014 agents work autonomously.`);
   console.log('\nTry: @mix-engineer "Please gain stage my tracks"');
   console.log('Or:  @mix-analyzer "Roast my mix"');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mthines/reaper-mcp",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "MCP server for controlling REAPER DAW — real-time mixing, FX control, and frequency analysis for AI agents",
   "license": "MIT",

package/reaper/mcp_bridge.lua

@@ -9,7 +9,7 @@
 -- The script will keep running in the background via defer().
 -- =============================================================================
 
-local POLL_INTERVAL = 0.030 -- 30ms between polls
+local POLL_INTERVAL = 0 -- scan every defer cycle; the notify file makes this cheap
 local HEARTBEAT_INTERVAL = 1.0 -- write heartbeat every 1s
 local MCP_ANALYZER_FX_NAME = "reaper-mcp/mcp_analyzer" -- JSFX analyzer name
 
@@ -21,6 +21,14 @@ reaper.RecursiveCreateDirectory(bridge_dir, 0)
 
 local last_poll = 0
 local last_heartbeat = 0
+local defer_count = 0
+local defer_intervals = {}  -- circular buffer of last 100 defer intervals
+local defer_idx = 0
+local defer_buf_size = 100
+local last_defer_time = 0
+local scan_count = 0
+local scan_durations = {}  -- last 100 scan durations
+local scan_idx = 0
 
 -- =============================================================================
 -- JSON Parser (minimal, sufficient for our command format)
@@ -243,6 +251,23 @@ local function list_files(dir, prefix)
   return files
 end
 
+-- Read pending command IDs from the notify file (avoids directory listing entirely).
+-- Returns a list of command filenames, or falls back to list_files if no notify file.
+local notify_path = bridge_dir .. "_notify"
+local function read_notify()
+  local f = io.open(notify_path, "r")
+  if not f then return nil end
+  local content = f:read("*a")
+  f:close()
+  os.remove(notify_path)
+  if not content or content == "" then return nil end
+  local files = {}
+  for id in content:gmatch("[^\n]+") do
+    files[#files + 1] = "command_" .. id .. ".json"
+  end
+  return files
+end
+
 -- =============================================================================
 -- dB conversion helpers
 -- =============================================================================
@@ -2442,7 +2467,12 @@ function handlers.create_track_envelope(params)
       if not chunk:find(chunk_key) then
         -- Insert a minimal envelope chunk before the closing >
         local env_chunk = "\n<" .. chunk_key .. "\nACT 1 -1\nVIS 1 1 1\nLANEHEIGHT 0 0\nARM 0\nDEFSHAPE 0 -1 -1\n>\n"
-        chunk = chunk:gsub("\n>$", env_chunk .. ">")
+        -- Use position capture to find the last ">" (closing the <TRACK block).
+        -- We cannot use "\n>$" because GetTrackStateChunk may include a trailing newline.
+        local last_gt = chunk:match(".*()>")
+        if last_gt then
+          chunk = chunk:sub(1, last_gt - 1) .. env_chunk .. chunk:sub(last_gt)
+        end
         reaper.SetTrackStateChunk(track, chunk, false)
       else
         -- Envelope exists in chunk but may be hidden; make it visible
@@ -2624,11 +2654,57 @@ function handlers.insert_envelope_points(params)
   }
 end
 
+-- =============================================================================
+-- Bridge diagnostics handler
+-- =============================================================================
+
+handlers["_bridge_diagnostics"] = function(params)
+  -- Compute defer interval stats from circular buffer
+  local intervals = {}
+  for i = 1, math.min(defer_count, defer_buf_size) do
+    intervals[#intervals + 1] = defer_intervals[i]
+  end
+  table.sort(intervals)
+  local n = #intervals
+  local sum = 0
+  for _, v in ipairs(intervals) do sum = sum + v end
+
+  local scan_times = {}
+  for i = 1, math.min(scan_count, defer_buf_size) do
+    scan_times[#scan_times + 1] = scan_durations[i]
+  end
+  table.sort(scan_times)
+  local sn = #scan_times
+  local ssum = 0
+  for _, v in ipairs(scan_times) do ssum = ssum + v end
+
+  return {
+    pollInterval = POLL_INTERVAL * 1000,
+    deferCount = defer_count,
+    scanCount = scan_count,
+    deferIntervals = n > 0 and {
+      count = n,
+      avgMs = math.floor(sum / n * 1000 + 0.5) / 1000,
+      minMs = math.floor(intervals[1] * 1000 * 1000 + 0.5) / 1000,
+      maxMs = math.floor(intervals[n] * 1000 * 1000 + 0.5) / 1000,
+      p50Ms = math.floor(intervals[math.floor(n * 0.5) + 1] * 1000 * 1000 + 0.5) / 1000,
+      p95Ms = math.floor(intervals[math.floor(n * 0.95) + 1] * 1000 * 1000 + 0.5) / 1000,
+    } or nil,
+    scanDurations = sn > 0 and {
+      count = sn,
+      avgMs = math.floor(ssum / sn * 1000 + 0.5) / 1000,
+      minMs = math.floor(scan_times[1] * 1000 * 1000 + 0.5) / 1000,
+      maxMs = math.floor(scan_times[sn] * 1000 * 1000 + 0.5) / 1000,
+    } or nil,
+  }
+end
+
 -- =============================================================================
 -- Command dispatcher
 -- =============================================================================
 
 local function process_command(filename)
+  local pickup_time = reaper.time_precise()
   local path = bridge_dir .. filename
   local content = read_file(path)
   if not content then return end
@@ -2660,6 +2736,13 @@ local function process_command(filename)
     }
   end
 
+  -- Add pickup timing to response for profiling
+  if cmd.timestamp then
+    response._pickupMs = math.floor((pickup_time - (cmd.timestamp / 1000)) * 1000 + 0.5)
+    response._deferCycle = defer_count
+    response._scanCycle = scan_count
+  end
+
   -- Write response
   local response_path = bridge_dir .. "response_" .. cmd.id .. ".json"
   write_file(response_path, json_encode(response))
@@ -2688,13 +2771,26 @@ end
 local function main_loop()
   local now = reaper.time_precise()
 
-  -- Poll for commands at interval
+  -- Track defer cadence
+  if last_defer_time > 0 then
+    defer_count = defer_count + 1
+    defer_idx = (defer_idx % defer_buf_size) + 1
+    defer_intervals[defer_idx] = now - last_defer_time
+  end
+  last_defer_time = now
+
+  -- Poll for commands: prefer notify file (instant), fall back to dir listing
   if now - last_poll >= POLL_INTERVAL then
     last_poll = now
-    local files = list_files(bridge_dir, "command_")
+    local scan_start = reaper.time_precise()
+    local files = read_notify() or list_files(bridge_dir, "command_")
     for _, filename in ipairs(files) do
       process_command(filename)
     end
+    local scan_dur = reaper.time_precise() - scan_start
+    scan_count = scan_count + 1
+    scan_idx = (scan_idx % defer_buf_size) + 1
+    scan_durations[scan_idx] = scan_dur
   end
 
   -- Write heartbeat at interval