node-loop-detective 1.1.0 → 1.3.0

package/README.md

@@ -74,6 +74,9 @@ loop-detective -p 12345 -d 30 -t 100
 # Detect slow I/O with a 1-second threshold
 loop-detective -p 12345 --io-threshold 1000
 
+# Connect to a remote inspector (Docker, K8s, remote server)
+loop-detective --host 192.168.1.100 --port 9229
+
 # Continuous monitoring mode
 loop-detective -p 12345 --watch
 
@@ -86,6 +89,7 @@ loop-detective -p 12345 --json
 | Flag | Description | Default |
 |------|-------------|---------|
 | `-p, --pid <pid>` | Target Node.js process ID | — |
+| `-H, --host <host>` | Inspector host (remote connections) | 127.0.0.1 |
 | `-P, --port <port>` | Inspector port (skip SIGUSR1) | — |
 | `-d, --duration <sec>` | Profiling duration in seconds | 10 |
 | `-t, --threshold <ms>` | Event loop lag threshold | 50 |
@@ -124,6 +128,7 @@ const { Detective } = require('node-loop-detective');
 
 const detective = new Detective({
   pid: 12345,
+  inspectorHost: '127.0.0.1',  // or remote host
   duration: 10000,
   threshold: 50,
   interval: 100,

package/bin/cli.js

@@ -10,6 +10,7 @@ function parseCliArgs(argv) {
   const args = argv.slice(2);
   const values = {
     pid: null,
+    host: null,
     port: null,
     duration: '10',
     threshold: '50',
@@ -24,6 +25,7 @@ function parseCliArgs(argv) {
 
   const flagMap = {
     '-p': 'pid', '--pid': 'pid',
+    '-H': 'host', '--host': 'host',
     '-P': 'port', '--port': 'port',
     '-d': 'duration', '--duration': 'duration',
     '-t': 'threshold', '--threshold': 'threshold',
@@ -85,9 +87,11 @@ function printUsage() {
     loop-detective <pid>
     loop-detective --pid <pid>
     loop-detective --port <inspector-port>
+    loop-detective --host <remote-host> --port <inspector-port>
 
   OPTIONS
     -p, --pid <pid>          Target Node.js process ID
+    -H, --host <host>        Inspector host (default: 127.0.0.1)
     -P, --port <port>        Connect to an already-open inspector port
     -d, --duration <sec>     Profiling duration in seconds (default: 10)
     -t, --threshold <ms>     Event loop lag threshold in ms (default: 50)
@@ -102,6 +106,7 @@ function printUsage() {
     loop-detective 12345
     loop-detective --pid 12345 --duration 30 --threshold 100
     loop-detective --port 9229 --watch
+    loop-detective --host 192.168.1.100 --port 9229
     loop-detective -p 12345 -d 5 -j
 
   HOW IT WORKS
@@ -116,6 +121,7 @@ function printUsage() {
 async function main() {
   const config = {
     pid: pid ? parseInt(pid, 10) : null,
+    inspectorHost: values.host || '127.0.0.1',
     inspectorPort,
     duration: parseInt(values.duration, 10) * 1000,
     threshold: parseInt(values.threshold, 10),
@@ -128,6 +134,11 @@ async function main() {
   const reporter = new Reporter(config);
   const detective = new Detective(config);
 
+  // Security warning for remote connections
+  if (config.inspectorHost !== '127.0.0.1' && config.inspectorHost !== 'localhost') {
+    reporter.onInfo(`⚠ Warning: Connecting to remote host ${config.inspectorHost}. The CDP protocol has no authentication — ensure the network is trusted.`);
+  }
+
   detective.on('connected', () => reporter.onConnected());
   detective.on('lag', (data) => reporter.onLag(data));
   detective.on('slowIO', (data) => reporter.onSlowIO(data));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-loop-detective",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Detect event loop blocking & lag in running Node.js apps without code changes or restarts",
   "main": "src/index.js",
   "bin": {

package/src/analyzer.js

@@ -7,12 +7,6 @@ class Analyzer {
 
   /**
    * Analyze a V8 CPU profile to find blocking functions
-   *
-   * V8 CPU profile format:
-   * - nodes: array of { id, callFrame: { functionName, url, lineNumber, columnNumber }, hitCount, children }
-   * - startTime, endTime: microseconds
-   * - samples: array of node IDs (sampled at each tick)
-   * - timeDeltas: array of time deltas between samples (microseconds)
    */
   analyzeProfile(profile) {
     const { nodes, samples, timeDeltas, startTime, endTime } = profile;
@@ -22,7 +16,7 @@ class Analyzer {
       nodeMap.set(node.id, node);
     }
 
-    // Calculate total time per node
+    // Calculate total time per node (keyed by node ID)
     const timings = new Map();
     for (let i = 0; i < samples.length; i++) {
       const nodeId = samples[i];
@@ -30,7 +24,6 @@ class Analyzer {
       timings.set(nodeId, (timings.get(nodeId) || 0) + delta);
     }
 
-    // Build results: find heavy functions
     const totalDuration = endTime - startTime; // microseconds
     const heavyFunctions = [];
 
@@ -40,35 +33,30 @@ class Analyzer {
 
       const { functionName, url, lineNumber, columnNumber } = node.callFrame;
 
-      // Skip internal/idle nodes
       if (!url && !functionName) continue;
       if (functionName === '(idle)' || functionName === '(program)') continue;
-      if (functionName === '(garbage collector)') {
-        // GC is interesting — keep it
-      }
 
       const selfTimeMs = selfTime / 1000;
       const percentage = totalDuration > 0 ? (selfTime / totalDuration) * 100 : 0;
 
-      if (selfTimeMs < 1) continue; // skip trivial entries
+      if (selfTimeMs < 1) continue;
 
       heavyFunctions.push({
+        nodeId, // Fix #5: carry node ID for accurate call stack building
         functionName: functionName || '(anonymous)',
         url: url || '(native)',
-        lineNumber: lineNumber + 1, // V8 uses 0-based
+        lineNumber: lineNumber + 1,
         columnNumber: columnNumber + 1,
         selfTimeMs: Math.round(selfTimeMs * 100) / 100,
         percentage: Math.round(percentage * 100) / 100,
       });
     }
 
-    // Sort by self time descending
     heavyFunctions.sort((a, b) => b.selfTimeMs - a.selfTimeMs);
 
-    // Build call tree for the top blockers
-    const callStacks = this._buildCallStacks(nodeMap, timings, heavyFunctions.slice(0, 5));
+    // Fix #5: Pass node IDs to _buildCallStacks instead of matching by name
+    const callStacks = this._buildCallStacks(nodeMap, heavyFunctions.slice(0, 5));
 
-    // Detect event loop blocking patterns
     const blockingPatterns = this._detectPatterns(heavyFunctions, profile);
 
     return {
@@ -77,7 +65,8 @@ class Analyzer {
         samplesCount: samples.length,
         heavyFunctionCount: heavyFunctions.length,
       },
-      heavyFunctions: heavyFunctions.slice(0, 20),
+      // Strip nodeId from public output
+      heavyFunctions: heavyFunctions.slice(0, 20).map(({ nodeId, ...rest }) => rest),
       callStacks,
       blockingPatterns,
       timestamp: Date.now(),
@@ -85,9 +74,11 @@ class Analyzer {
   }
 
   /**
-   * Build call stacks for the heaviest functions
+   * Build call stacks for the heaviest functions.
+   * Fix for Issue #5: Uses node ID directly instead of matching by function name,
+   * which avoids incorrect matches for same-named functions or minified code.
    */
-  _buildCallStacks(nodeMap, timings, topFunctions) {
+  _buildCallStacks(nodeMap, topFunctions) {
     const stacks = [];
 
     // Build parent map
@@ -101,18 +92,7 @@ class Analyzer {
     }
 
     for (const fn of topFunctions) {
-      // Find the node matching this function
-      let targetNode = null;
-      for (const node of nodeMap.values()) {
-        const cf = node.callFrame;
-        if (cf.functionName === fn.functionName &&
-            cf.url === (fn.url === '(native)' ? '' : fn.url) &&
-            cf.lineNumber === fn.lineNumber - 1) {
-          targetNode = node;
-          break;
-        }
-      }
-
+      const targetNode = nodeMap.get(fn.nodeId);
       if (!targetNode) continue;
 
       // Walk up the call stack
@@ -149,7 +129,6 @@ class Analyzer {
     const patterns = [];
     const totalMs = (profile.endTime - profile.startTime) / 1000;
 
-    // Pattern: Single function dominating CPU
     const topFn = heavyFunctions[0];
     if (topFn && topFn.percentage > 50) {
       patterns.push({
@@ -161,7 +140,6 @@ class Analyzer {
       });
     }
 
-    // Pattern: JSON parsing / serialization
     const jsonFns = heavyFunctions.filter(
       (f) => f.functionName.includes('JSON') || f.functionName.includes('parse') || f.functionName.includes('stringify')
     );
@@ -175,7 +153,6 @@ class Analyzer {
       });
     }
 
-    // Pattern: RegExp heavy
     const regexFns = heavyFunctions.filter(
       (f) => f.functionName.includes('RegExp') || f.functionName.includes('exec') || f.functionName.includes('match')
     );
@@ -189,7 +166,6 @@ class Analyzer {
       });
     }
 
-    // Pattern: GC pressure
     const gcFns = heavyFunctions.filter((f) => f.functionName.includes('garbage collector'));
     const gcTime = gcFns.reduce((sum, f) => sum + f.selfTimeMs, 0);
     if (gcTime > totalMs * 0.05) {
@@ -201,7 +177,6 @@ class Analyzer {
       });
     }
 
-    // Pattern: Synchronous file I/O
     const syncFns = heavyFunctions.filter(
       (f) => f.functionName.includes('Sync') || f.url.includes('fs.js') || f.url.includes('node:fs')
     );
@@ -215,7 +190,6 @@ class Analyzer {
       });
     }
 
-    // Pattern: Crypto operations
     const cryptoFns = heavyFunctions.filter(
       (f) => f.url.includes('crypto') || f.functionName.includes('pbkdf') || f.functionName.includes('hash')
     );

package/src/detective.js

@@ -11,6 +11,7 @@ class Detective extends EventEmitter {
     this.inspector = null;
     this.analyzer = new Analyzer(config);
     this._running = false;
+    this._stopping = false;
     this._lagTimer = null;
     this._ioTimer = null;
   }
@@ -19,13 +20,13 @@ class Detective extends EventEmitter {
    * Activate the inspector on the target process via SIGUSR1
    */
   _activateInspector() {
-    if (this.config.inspectorPort) return; // already specified
+    if (this.config.inspectorPort) return;
 
     const pid = this.config.pid;
     if (!pid) throw new Error('No PID provided');
 
     try {
-      process.kill(pid, 0); // check process exists
+      process.kill(pid, 0);
     } catch (err) {
       throw new Error(`Process ${pid} not found or not accessible: ${err.message}`);
     }
@@ -45,19 +46,21 @@ class Detective extends EventEmitter {
    */
   async _findInspectorPort() {
     if (this.config.inspectorPort) return this.config.inspectorPort;
-
-    // After SIGUSR1, Node.js opens inspector on 9229 by default
-    // Give it a moment to start
     await this._sleep(1000);
     return 9229;
   }
 
   /**
    * Start event loop lag detection via CDP Runtime.evaluate
-   * We inject a tiny lag-measuring snippet into the target process
+   *
+   * Note on stack traces (Issue #6): The setInterval callback fires AFTER
+   * blocking code has finished, so captureStack() captures the timer's own
+   * stack, not the blocking code's stack. The lag event stacks are best-effort
+   * context. For accurate blocking code identification, use the CPU profile
+   * analysis (heavyFunctions + callStacks) which is based on V8 sampling and
+   * reliably identifies the actual blocking functions.
    */
   async _startLagDetection() {
-    // Inject a lag detector that also captures stack traces
     const script = `
       (function() {
         if (globalThis.__loopDetective) {
@@ -67,13 +70,11 @@ class Detective extends EventEmitter {
         let lastTime = Date.now();
         const threshold = ${this.config.threshold};
 
-        // Capture stack trace at the point of lag detection
         function captureStack() {
           const orig = Error.stackTraceLimit;
           Error.stackTraceLimit = 20;
           const err = new Error();
           Error.stackTraceLimit = orig;
-          // Parse the stack into structured frames
           const frames = (err.stack || '').split('\\n').slice(2).map(line => {
             const m = line.match(/at\\s+(?:(.+?)\\s+\\()?(.+?):(\\d+):(\\d+)\\)?/);
             if (m) return { fn: m[1] || '(anonymous)', file: m[2], line: +m[3], col: +m[4] };
@@ -99,7 +100,6 @@ class Detective extends EventEmitter {
           lastTime = now;
         }, ${this.config.interval});
 
-        // Make sure our timer doesn't keep the process alive
         if (timer.unref) timer.unref();
 
         globalThis.__loopDetective = {
@@ -127,7 +127,6 @@ class Detective extends EventEmitter {
       throw new Error(`Failed to inject lag detector: ${JSON.stringify(result.exceptionDetails)}`);
     }
 
-    // Poll for lag events
     this._lagTimer = setInterval(async () => {
       if (!this._running) return;
       try {
@@ -148,6 +147,10 @@ class Detective extends EventEmitter {
   /**
    * Start slow async I/O detection via CDP Runtime.evaluate
    * Monkey-patches http, https, net, dns to track slow operations
+   *
+   * Fix for Issue #1: Original functions are stored and restored on cleanup.
+   * Fix for Issue #7: http.get is wrapped around the original http.get,
+   * not reimplemented via mod.request + req.end().
    */
   async _startAsyncIOTracking() {
     const ioThreshold = this.config.ioThreshold || 500;
@@ -160,6 +163,20 @@ class Detective extends EventEmitter {
 
         const slowOps = [];
         const threshold = ${ioThreshold};
+        const originals = {};
+
+        function captureCallerStack() {
+          const origLimit = Error.stackTraceLimit;
+          Error.stackTraceLimit = 10;
+          const stackErr = new Error();
+          Error.stackTraceLimit = origLimit;
+          return (stackErr.stack || '').split('\\n').slice(2, 6).map(l => l.trim());
+        }
+
+        function recordSlowOp(op) {
+          slowOps.push(op);
+          if (slowOps.length > 200) slowOps.shift();
+        }
 
         // --- Track outgoing HTTP/HTTPS requests ---
         function patchHttp(modName) {
@@ -167,65 +184,78 @@ class Detective extends EventEmitter {
           try { mod = require(modName); } catch { return; }
           const origRequest = mod.request;
           const origGet = mod.get;
+          originals[modName + '.request'] = { mod, key: 'request', fn: origRequest };
+          originals[modName + '.get'] = { mod, key: 'get', fn: origGet };
 
           mod.request = function patchedRequest(...args) {
             const startTime = Date.now();
             const opts = typeof args[0] === 'string' ? { href: args[0] } : (args[0] || {});
             const target = opts.href || opts.hostname || opts.host || 'unknown';
             const method = (opts.method || 'GET').toUpperCase();
-            const label = modName + ' ' + method + ' ' + target;
-
-            // Capture caller stack
-            const origLimit = Error.stackTraceLimit;
-            Error.stackTraceLimit = 10;
-            const stackErr = new Error();
-            Error.stackTraceLimit = origLimit;
-            const callerStack = (stackErr.stack || '').split('\\n').slice(2, 6).map(l => l.trim());
+            const callerStack = captureCallerStack();
 
             const req = origRequest.apply(this, args);
 
             req.on('response', (res) => {
               const duration = Date.now() - startTime;
               if (duration >= threshold) {
-                slowOps.push({
-                  type: 'http',
-                  protocol: modName,
-                  method,
-                  target,
-                  statusCode: res.statusCode,
-                  duration,
-                  timestamp: Date.now(),
-                  stack: callerStack,
+                recordSlowOp({
+                  type: 'http', protocol: modName, method, target,
+                  statusCode: res.statusCode, duration, timestamp: Date.now(), stack: callerStack,
                 });
-                if (slowOps.length > 200) slowOps.shift();
               }
             });
 
             req.on('error', (err) => {
               const duration = Date.now() - startTime;
               if (duration >= threshold) {
-                slowOps.push({
-                  type: 'http',
-                  protocol: modName,
-                  method,
-                  target,
-                  error: err.message,
-                  duration,
-                  timestamp: Date.now(),
-                  stack: callerStack,
+                recordSlowOp({
+                  type: 'http', protocol: modName, method, target,
+                  error: err.message, duration, timestamp: Date.now(), stack: callerStack,
                 });
-                if (slowOps.length > 200) slowOps.shift();
               }
             });
 
             return req;
           };
 
+          // Fix #7: Wrap original http.get instead of reimplementing
           mod.get = function patchedGet(...args) {
-            const req = mod.request(...args);
-            req.end();
+            return origGet.apply(this, args);
+          };
+          // Add timing to get as well
+          const wrappedGet = mod.get;
+          mod.get = function patchedGetWithTiming(...args) {
+            const startTime = Date.now();
+            const opts = typeof args[0] === 'string' ? { href: args[0] } : (args[0] || {});
+            const target = opts.href || opts.hostname || opts.host || 'unknown';
+            const callerStack = captureCallerStack();
+
+            const req = origGet.apply(this, args);
+
+            req.on('response', (res) => {
+              const duration = Date.now() - startTime;
+              if (duration >= threshold) {
+                recordSlowOp({
+                  type: 'http', protocol: modName, method: 'GET', target,
+                  statusCode: res.statusCode, duration, timestamp: Date.now(), stack: callerStack,
+                });
+              }
+            });
+
+            req.on('error', (err) => {
+              const duration = Date.now() - startTime;
+              if (duration >= threshold) {
+                recordSlowOp({
+                  type: 'http', protocol: modName, method: 'GET', target,
+                  error: err.message, duration, timestamp: Date.now(), stack: callerStack,
+                });
+              }
+            });
+
             return req;
           };
+          originals[modName + '.get'].fn = origGet;
         }
 
         patchHttp('http');
@@ -236,6 +266,7 @@ class Detective extends EventEmitter {
           let dns;
           try { dns = require('dns'); } catch { return; }
           const origLookup = dns.lookup;
+          originals['dns.lookup'] = { mod: dns, key: 'lookup', fn: origLookup };
 
           dns.lookup = function patchedLookup(hostname, options, callback) {
             const startTime = Date.now();
@@ -243,25 +274,15 @@ class Detective extends EventEmitter {
               callback = options;
               options = {};
             }
-
-            const origLimit = Error.stackTraceLimit;
-            Error.stackTraceLimit = 10;
-            const stackErr = new Error();
-            Error.stackTraceLimit = origLimit;
-            const callerStack = (stackErr.stack || '').split('\\n').slice(2, 6).map(l => l.trim());
+            const callerStack = captureCallerStack();
 
             return origLookup.call(dns, hostname, options, function(err, address, family) {
               const duration = Date.now() - startTime;
               if (duration >= threshold) {
-                slowOps.push({
-                  type: 'dns',
-                  target: hostname,
-                  duration,
-                  error: err ? err.message : null,
-                  timestamp: Date.now(),
-                  stack: callerStack,
+                recordSlowOp({
+                  type: 'dns', target: hostname, duration,
+                  error: err ? err.message : null, timestamp: Date.now(), stack: callerStack,
                 });
-                if (slowOps.length > 200) slowOps.shift();
               }
               if (callback) callback(err, address, family);
             });
@@ -273,44 +294,25 @@ class Detective extends EventEmitter {
           let net;
           try { net = require('net'); } catch { return; }
           const origConnect = net.Socket.prototype.connect;
+          originals['net.Socket.connect'] = { mod: net.Socket.prototype, key: 'connect', fn: origConnect };
 
           net.Socket.prototype.connect = function patchedConnect(...args) {
             const startTime = Date.now();
             const opts = typeof args[0] === 'object' ? args[0] : { port: args[0], host: args[1] };
             const target = (opts.host || '127.0.0.1') + ':' + (opts.port || '?');
-
-            const origLimit = Error.stackTraceLimit;
-            Error.stackTraceLimit = 10;
-            const stackErr = new Error();
-            Error.stackTraceLimit = origLimit;
-            const callerStack = (stackErr.stack || '').split('\\n').slice(2, 6).map(l => l.trim());
+            const callerStack = captureCallerStack();
 
             this.once('connect', () => {
               const duration = Date.now() - startTime;
               if (duration >= threshold) {
-                slowOps.push({
-                  type: 'tcp',
-                  target,
-                  duration,
-                  timestamp: Date.now(),
-                  stack: callerStack,
-                });
-                if (slowOps.length > 200) slowOps.shift();
+                recordSlowOp({ type: 'tcp', target, duration, timestamp: Date.now(), stack: callerStack });
               }
             });
 
             this.once('error', (err) => {
               const duration = Date.now() - startTime;
               if (duration >= threshold) {
-                slowOps.push({
-                  type: 'tcp',
-                  target,
-                  error: err.message,
-                  duration,
-                  timestamp: Date.now(),
-                  stack: callerStack,
-                });
-                if (slowOps.length > 200) slowOps.shift();
+                recordSlowOp({ type: 'tcp', target, error: err.message, duration, timestamp: Date.now(), stack: callerStack });
               }
             });
 
@@ -319,13 +321,12 @@ class Detective extends EventEmitter {
         })();
 
         globalThis.__loopDetectiveIO = {
-          getSlowOps: () => {
-            const result = slowOps.splice(0);
-            return result;
-          },
+          getSlowOps: () => slowOps.splice(0),
           cleanup: () => {
-            // Note: we don't restore originals to avoid complexity.
-            // The patches become no-ops once threshold filtering removes them.
+            // Fix #1: Restore all original functions
+            for (const entry of Object.values(originals)) {
+              entry.mod[entry.key] = entry.fn;
+            }
             delete globalThis.__loopDetectiveIO;
           }
         };
@@ -340,12 +341,10 @@ class Detective extends EventEmitter {
     });
 
     if (result.exceptionDetails) {
-      // Non-fatal: IO tracking is optional
       this.emit('error', new Error(`Failed to inject I/O tracker (non-fatal): ${JSON.stringify(result.exceptionDetails)}`));
       return;
     }
 
-    // Poll for slow I/O events
     this._ioTimer = setInterval(async () => {
       if (!this._running) return;
       try {
@@ -382,23 +381,19 @@ class Detective extends EventEmitter {
   /**
    * Clean up the injected lag detector and I/O tracker
    */
-  async _cleanupLagDetector() {
+  async _cleanupInjectedCode() {
     try {
       await this.inspector.send('Runtime.evaluate', {
         expression: 'globalThis.__loopDetective && globalThis.__loopDetective.cleanup()',
         returnByValue: true,
       });
-    } catch {
-      // Best effort cleanup
-    }
+    } catch { /* best effort */ }
     try {
       await this.inspector.send('Runtime.evaluate', {
         expression: 'globalThis.__loopDetectiveIO && globalThis.__loopDetectiveIO.cleanup()',
         returnByValue: true,
       });
-    } catch {
-      // Best effort cleanup
-    }
+    } catch { /* best effort */ }
   }
 
   /**
@@ -406,13 +401,12 @@ class Detective extends EventEmitter {
    */
   async start() {
     this._running = true;
+    this._stopping = false;
 
-    // Step 1: Activate inspector
     this._activateInspector();
     const port = await this._findInspectorPort();
 
-    // Step 2: Connect
-    this.inspector = new Inspector({ port });
+    this.inspector = new Inspector({ host: this.config.inspectorHost, port });
     await this.inspector.connect();
     this.emit('connected');
 
@@ -425,14 +419,10 @@ class Detective extends EventEmitter {
 
   async _singleRun() {
     try {
-      // Step 3: Start lag detection + async I/O tracking
       await this._startLagDetection();
       await this._startAsyncIOTracking();
 
-      // Step 4: Capture CPU profile
       const profile = await this._captureProfile(this.config.duration);
-
-      // Step 5: Analyze
       const analysis = this.analyzer.analyzeProfile(profile);
       this.emit('profile', analysis);
     } finally {
@@ -440,6 +430,10 @@ class Detective extends EventEmitter {
     }
   }
 
+  /**
+   * Fix for Issue #2: Wrap runCycle in try/catch, emit errors,
+   * and continue the watch loop.
+   */
   async _watchMode() {
     await this._startLagDetection();
     await this._startAsyncIOTracking();
@@ -447,22 +441,30 @@ class Detective extends EventEmitter {
     const runCycle = async () => {
       if (!this._running) return;
 
-      const profile = await this._captureProfile(this.config.duration);
-      const analysis = this.analyzer.analyzeProfile(profile);
-      this.emit('profile', analysis);
+      try {
+        const profile = await this._captureProfile(this.config.duration);
+        const analysis = this.analyzer.analyzeProfile(profile);
+        this.emit('profile', analysis);
+      } catch (err) {
+        this.emit('error', err);
+      }
 
       if (this._running) {
         setTimeout(runCycle, 1000);
       }
     };
 
-    runCycle();
+    // Await the first cycle and catch its errors
+    await runCycle();
   }
 
   /**
-   * Stop the detective and clean up
+   * Stop the detective and clean up.
+   * Fix for Issue #3: Idempotent — safe to call multiple times.
    */
   async stop() {
+    if (this._stopping) return;
+    this._stopping = true;
     this._running = false;
 
     if (this._lagTimer) {
@@ -476,7 +478,7 @@ class Detective extends EventEmitter {
     }
 
     if (this.inspector) {
-      await this._cleanupLagDetector();
+      await this._cleanupInjectedCode();
       await this.inspector.disconnect();
       this.inspector = null;
     }

package/src/inspector.js

@@ -64,7 +64,8 @@ class Inspector extends EventEmitter {
       this.ws.on('message', (data) => {
         const msg = JSON.parse(data.toString());
         if (msg.id !== undefined && this._callbacks.has(msg.id)) {
-          const { resolve, reject } = this._callbacks.get(msg.id);
+          const { resolve, reject, timer } = this._callbacks.get(msg.id);
+          clearTimeout(timer);
           this._callbacks.delete(msg.id);
           if (msg.error) {
             reject(new Error(msg.error.message));
@@ -98,16 +99,15 @@ class Inspector extends EventEmitter {
     const id = ++this._id;
 
     return new Promise((resolve, reject) => {
-      this._callbacks.set(id, { resolve, reject });
-      this.ws.send(JSON.stringify({ id, method, params }));
-
-      // Timeout for individual commands
-      setTimeout(() => {
+      const timer = setTimeout(() => {
         if (this._callbacks.has(id)) {
           this._callbacks.delete(id);
           reject(new Error(`CDP command timeout: ${method}`));
         }
       }, 30000);
+
+      this._callbacks.set(id, { resolve, reject, timer });
+      this.ws.send(JSON.stringify({ id, method, params }));
     });
   }
 
@@ -116,6 +116,11 @@ class Inspector extends EventEmitter {
    */
   async disconnect() {
     if (this.ws) {
+      // Clear all pending timeouts and reject pending callbacks
+      for (const { reject, timer } of this._callbacks.values()) {
+        clearTimeout(timer);
+        try { reject(new Error('Inspector disconnected')); } catch {}
+      }
       this._callbacks.clear();
       this.ws.close();
       this.ws = null;