@fanboynz/network-scanner 2.0.66 → 3.0.1

package/lib/browserhealth.js

@@ -4,6 +4,9 @@
  */
 
 const { formatLogMessage, messageColors } = require('./colorize');
+const IS_PAGE_FROM_PREVIOUS_SCAN_TAG = messageColors.processing('[isPageFromPreviousScan]');
+const REALTIME_CLEANUP_TAG = messageColors.processing('[realtime_cleanup]');
+const GROUP_WINDOW_CLEANUP_TAG = messageColors.processing('[group_window_cleanup]');
 const { execSync, execFile } = require('child_process');
 
 // Window cleanup delay constant
@@ -13,11 +16,28 @@ const REALTIME_CLEANUP_BUFFER_MS = 25000; // Additional buffer time after site d
 const REALTIME_CLEANUP_THRESHOLD = 12; // Default number of pages to keep
 const REALTIME_CLEANUP_MIN_PAGES = 6; // Minimum pages before cleanup kicks in
 
-// Track page creation order for realtime cleanup
-const pageCreationTracker = new Map(); // Maps page -> creation timestamp
+// Page-count thresholds — soft warn vs hard restart trigger. The two used to
+// live as bare 30/40 literals in different functions with no visible link.
+const PAGE_COUNT_WARN_THRESHOLD = 30;     // checkBrowserHealth: warn-only recommendation
+const PAGE_COUNT_RESTART_THRESHOLD = 40;  // monitorBrowserHealth: trigger restart
 
-// Track page usage for realtime cleanup safety
-const pageUsageTracker = new Map(); // Maps page -> { lastActivity: timestamp, isProcessing: boolean }
+// Browser response-time threshold above which monitorBrowserHealth triggers a restart.
+const SLOW_RESPONSE_RESTART_MS = 6000;
+
+// Heuristics for isPageFromPreviousScan: pages older than CREATION_AGE_MS or
+// idle longer than IDLE_AGE_MS are treated as leftover from a prior scan.
+const PREVIOUS_SCAN_CREATION_AGE_MS = 120000; // 2 minutes
+const PREVIOUS_SCAN_IDLE_AGE_MS = 60000;      // 60 seconds
+
+// Track page creation order for realtime cleanup. WeakMap so closed pages
+// drop out of tracking automatically when Puppeteer releases its internal
+// references — no manual purge needed to prevent the leak class that
+// purgeStaleTrackers() used to mitigate. The only API loss from Map ->
+// WeakMap is iteration (for...of), which only purgeStaleTrackers used.
+const pageCreationTracker = new WeakMap(); // Page -> creation timestamp
+
+// Track page usage for realtime cleanup safety. Same WeakMap rationale.
+const pageUsageTracker = new WeakMap(); // Page -> { lastActivity, isProcessing }
 const PAGE_IDLE_THRESHOLD = 25000; // 25 seconds of inactivity before considering page safe to clean
 
 /**
@@ -78,7 +98,7 @@ async function performGroupWindowCleanup(browserInstance, groupDescription, forc
     };
     const modeText = cleanupMode === "all" ? "aggressive cleanup of old windows" : "conservative cleanup of extra windows"
     if (forceDebug) {
-      console.log(formatLogMessage('debug', `[group_window_cleanup] Waiting ${WINDOW_CLEANUP_DELAY_MS}ms before ${modeText} for group: ${groupDescription}`));
+      console.log(formatLogMessage('debug', `${GROUP_WINDOW_CLEANUP_TAG} Waiting ${WINDOW_CLEANUP_DELAY_MS}ms before ${modeText} for group: ${groupDescription}`));
 
     }
     await new Promise(resolve => setTimeout(resolve, WINDOW_CLEANUP_DELAY_MS));
@@ -121,13 +141,13 @@ async function performGroupWindowCleanup(browserInstance, groupDescription, forc
       if (forceDebug) {
         // Cache URL call for logging
         const mainPageUrl = mainPuppeteerPage.url();
-        console.log(formatLogMessage('debug', `[group_window_cleanup] No blank page found, using first page as main: ${mainPageUrl}`));
+        console.log(formatLogMessage('debug', `${GROUP_WINDOW_CLEANUP_TAG} No blank page found, using first page as main: ${mainPageUrl}`));
       }
     }
     
     if (pagesToClose.length === 0) {
       if (forceDebug) {
-        console.log(formatLogMessage('debug', `[group_window_cleanup] No windows to close for group: ${groupDescription}`));
+        console.log(formatLogMessage('debug', `${GROUP_WINDOW_CLEANUP_TAG} No windows to close for group: ${groupDescription}`));
       }
       result.success = true;
       result.totalPages = allPages.length;
@@ -170,7 +190,7 @@ async function performGroupWindowCleanup(browserInstance, groupDescription, forc
         const pageUrl = page.url();
         if (!isPageClosed) {
           if (forceDebug) {
-            console.log(formatLogMessage('debug', `[group_window_cleanup] Closing page: ${pageUrl}`));
+            console.log(formatLogMessage('debug', `${GROUP_WINDOW_CLEANUP_TAG} Closing page: ${pageUrl}`));
           }
           pageCreationTracker.delete(page);
           pageUsageTracker.delete(page);
@@ -180,7 +200,7 @@ async function performGroupWindowCleanup(browserInstance, groupDescription, forc
         return { success: false, reason: 'already_closed', estimatedMemory: 0 };
       } catch (closeErr) {
         if (forceDebug) {
-          console.log(formatLogMessage('debug', `[group_window_cleanup] Failed to close old page ${index + 1}: ${closeErr.message}`));
+          console.log(formatLogMessage('debug', `${GROUP_WINDOW_CLEANUP_TAG} Failed to close old page ${index + 1}: ${closeErr.message}`));
         }
         return { success: false, error: closeErr.message, estimatedMemory: 0 };
       }
@@ -198,12 +218,12 @@ async function performGroupWindowCleanup(browserInstance, groupDescription, forc
     }
     
     if (forceDebug) {
-      console.log(formatLogMessage('debug', `[group_window_cleanup] Closed ${successfulCloses}/${pagesToClose.length} old windows for completed group: ${groupDescription} after ${WINDOW_CLEANUP_DELAY_MS}ms delay`));
-      console.log(formatLogMessage('debug', `[group_window_cleanup] Estimated memory freed: ${formatMemory(actualMemoryFreed)}`));
+      console.log(formatLogMessage('debug', `${GROUP_WINDOW_CLEANUP_TAG} Closed ${successfulCloses}/${pagesToClose.length} old windows for completed group: ${groupDescription} after ${WINDOW_CLEANUP_DELAY_MS}ms delay`));
+      console.log(formatLogMessage('debug', `${GROUP_WINDOW_CLEANUP_TAG} Estimated memory freed: ${formatMemory(actualMemoryFreed)}`));
       if (mainPuppeteerPage) {
         // Cache URL for final logging
         const mainPageUrl = mainPuppeteerPage.url();
-        console.log(formatLogMessage('debug', `[group_window_cleanup] Main Puppeteer window preserved: ${mainPageUrl}`));
+        console.log(formatLogMessage('debug', `${GROUP_WINDOW_CLEANUP_TAG} Main Puppeteer window preserved: ${mainPageUrl}`));
       }
     }
     
@@ -219,7 +239,7 @@ async function performGroupWindowCleanup(browserInstance, groupDescription, forc
     return result;
   } catch (cleanupErr) {
     if (forceDebug) {
-      console.log(formatLogMessage('debug', `[group_window_cleanup] Group cleanup failed for ${groupDescription}: ${cleanupErr.message}`));
+      console.log(formatLogMessage('debug', `${GROUP_WINDOW_CLEANUP_TAG} Group cleanup failed for ${groupDescription}: ${cleanupErr.message}`));
     }
     // Initialize result object with consistent shape for error case
     const result = {
@@ -266,7 +286,7 @@ async function isPageSafeToClose(page, forceDebug) {
     if (usage.isProcessing) {
       if (forceDebug) {
         const pageUrl = page.url();
-        console.log(formatLogMessage('debug', `[realtime_cleanup] Page still processing: ${pageUrl.substring(0, 50)}...`));
+        console.log(formatLogMessage('debug', `${REALTIME_CLEANUP_TAG} Page still processing: ${pageUrl.substring(0, 50)}...`));
       }
       return false;
     }
@@ -275,13 +295,13 @@ async function isPageSafeToClose(page, forceDebug) {
     const isSafe = idleTime >= PAGE_IDLE_THRESHOLD;
     
     if (!isSafe && forceDebug) {
-      console.log(formatLogMessage('debug', `[realtime_cleanup] Page not idle long enough: ${Math.round(idleTime/1000)}s < ${PAGE_IDLE_THRESHOLD/1000}s`));
+      console.log(formatLogMessage('debug', `${REALTIME_CLEANUP_TAG} Page not idle long enough: ${Math.round(idleTime/1000)}s < ${PAGE_IDLE_THRESHOLD/1000}s`));
     }
 
     return isSafe;
   } catch (err) {
     if (forceDebug) {
-      console.log(formatLogMessage('debug', `[realtime_cleanup] Error checking page safety: ${err.message}`));
+      console.log(formatLogMessage('debug', `${REALTIME_CLEANUP_TAG} Error checking page safety: ${err.message}`));
     }
     return true; // Assume safe if we can't check
   }
@@ -344,7 +364,7 @@ async function performRealtimeWindowCleanup(browserInstance, threshold = REALTIM
     // Skip cleanup if we don't have enough pages to warrant it
     if (quickPages.length <= Math.max(threshold, REALTIME_CLEANUP_MIN_PAGES)) {
       if (forceDebug) {
-        console.log(formatLogMessage('debug', `[realtime_cleanup] Only ${quickPages.length} pages open, threshold is ${threshold} - no cleanup needed`));
+        console.log(formatLogMessage('debug', `${REALTIME_CLEANUP_TAG} Only ${quickPages.length} pages open, threshold is ${threshold} - no cleanup needed`));
       }
       result.success = true;
       result.totalPages = quickPages.length;
@@ -356,7 +376,7 @@ async function performRealtimeWindowCleanup(browserInstance, threshold = REALTIM
     const cleanupDelay = totalDelay;
     
     if (forceDebug) {
-      console.log(formatLogMessage('debug', `[realtime_cleanup] Waiting ${cleanupDelay}ms before cleanup (threshold: ${threshold})`));
+      console.log(formatLogMessage('debug', `${REALTIME_CLEANUP_TAG} Waiting ${cleanupDelay}ms before cleanup (threshold: ${threshold})`));
     }
     await new Promise(resolve => setTimeout(resolve, cleanupDelay));
     
@@ -369,7 +389,7 @@ async function performRealtimeWindowCleanup(browserInstance, threshold = REALTIM
         if (context.isIncognito && context !== browserInstance.defaultBrowserContext()) {
           const contextPages = await context.pages();
           if (forceDebug) {
-            console.log(formatLogMessage('debug', `[realtime_cleanup] Found ${contextPages.length} pages in popup context`));
+            console.log(formatLogMessage('debug', `${REALTIME_CLEANUP_TAG} Found ${contextPages.length} pages in popup context`));
           }
           // Close popup context pages
           for (const page of contextPages) {
@@ -381,7 +401,7 @@ async function performRealtimeWindowCleanup(browserInstance, threshold = REALTIM
       }
     } catch (contextErr) {
       if (forceDebug) {
-        console.log(formatLogMessage('debug', `[realtime_cleanup] Context cleanup error: ${contextErr.message}`));
+        console.log(formatLogMessage('debug', `${REALTIME_CLEANUP_TAG} Context cleanup error: ${contextErr.message}`));
       }
     }
     
@@ -418,7 +438,7 @@ async function performRealtimeWindowCleanup(browserInstance, threshold = REALTIM
     const unsafePagesCount = pagesToClose.length - safePagesToClose.length;
     
     if (unsafePagesCount > 0 && forceDebug) {
-      console.log(formatLogMessage('debug', `[realtime_cleanup] Skipping ${unsafePagesCount} active pages for safety`));
+      console.log(formatLogMessage('debug', `${REALTIME_CLEANUP_TAG} Skipping ${unsafePagesCount} active pages for safety`));
     }
 
     if (safePagesToClose.length === 0) {
@@ -426,7 +446,7 @@ async function performRealtimeWindowCleanup(browserInstance, threshold = REALTIM
         const reason = pagesToClose.length === 0 ? 
           `${sortedPages.length} content pages, keeping ${pagesToKeep}` :
           `${pagesToClose.length} pages still active`;
-        console.log(formatLogMessage('debug', `[realtime_cleanup] No pages need closing (${reason})`));
+        console.log(formatLogMessage('debug', `${REALTIME_CLEANUP_TAG} No pages need closing (${reason})`));
       }
       result.success = true;
       result.totalPages = allPagesAfterDelay.length;
@@ -450,12 +470,12 @@ async function performRealtimeWindowCleanup(browserInstance, threshold = REALTIM
           closedCount++;
           
           if (forceDebug) {
-            console.log(formatLogMessage('debug', `[realtime_cleanup] Closed old page: ${pageUrl.substring(0, 50)}...`));
+            console.log(formatLogMessage('debug', `${REALTIME_CLEANUP_TAG} Closed old page: ${pageUrl.substring(0, 50)}...`));
           }
         }
       } catch (closeErr) {
         if (forceDebug) {
-          console.log(formatLogMessage('debug', `[realtime_cleanup] Failed to close page: ${closeErr.message}`));
+          console.log(formatLogMessage('debug', `${REALTIME_CLEANUP_TAG} Failed to close page: ${closeErr.message}`));
         }
       }
     }
@@ -463,7 +483,7 @@ async function performRealtimeWindowCleanup(browserInstance, threshold = REALTIM
     const remainingPages = allPagesAfterDelay.length - closedCount;
     
     if (forceDebug) {
-      console.log(formatLogMessage('debug', `[realtime_cleanup] Closed ${closedCount}/${pagesToClose.length} oldest pages (${unsafePagesCount} skipped for safety), ${remainingPages} pages remaining`));
+      console.log(formatLogMessage('debug', `${REALTIME_CLEANUP_TAG} Closed ${closedCount}/${pagesToClose.length} oldest pages (${unsafePagesCount} skipped for safety), ${remainingPages} pages remaining`));
     }
 
     result.success = true;
@@ -476,7 +496,7 @@ async function performRealtimeWindowCleanup(browserInstance, threshold = REALTIM
     return result;
   } catch (cleanupErr) {
     if (forceDebug) {
-      console.log(formatLogMessage('debug', `[realtime_cleanup] Cleanup failed: ${cleanupErr.message}`));
+      console.log(formatLogMessage('debug', `${REALTIME_CLEANUP_TAG} Cleanup failed: ${cleanupErr.message}`));
     }
     // Initialize result object with consistent shape for error case
     const result = {
@@ -520,15 +540,15 @@ async function isPageFromPreviousScan(page, forceDebug) {
     // Use tracker timestamp instead of expensive page.title() CDP call
     const now = Date.now();
     const createdAt = pageCreationTracker.get(page);
-    if (createdAt && now - createdAt > 120000) {
-      // Page is older than 2 minutes -- likely from a previous scan
+    if (createdAt && now - createdAt > PREVIOUS_SCAN_CREATION_AGE_MS) {
+      // Page older than the creation-age threshold — likely from a previous scan
       return true;
     }
-    
+
     // Check usage tracker -- idle pages are likely old
     const usage = pageUsageTracker.get(page);
-    if (usage && !usage.isProcessing && now - usage.lastActivity > 60000) {
-      return true; // Idle for over 60 seconds
+    if (usage && !usage.isProcessing && now - usage.lastActivity > PREVIOUS_SCAN_IDLE_AGE_MS) {
+      return true; // Idle beyond the idle-age threshold
     }
     
     // Fallback: only use page.title() if trackers have no data
@@ -552,9 +572,9 @@ async function isPageFromPreviousScan(page, forceDebug) {
       try {
         // Cache URL for error logging - wrap in try-catch as page might be closed
         const pageUrl = page.url();
-        console.log(formatLogMessage('debug', `[isPageFromPreviousScan] Error evaluating page ${pageUrl}: ${err.message}`));
+        console.log(formatLogMessage('debug', `${IS_PAGE_FROM_PREVIOUS_SCAN_TAG} Error evaluating page ${pageUrl}: ${err.message}`));
       } catch (urlErr) {
-        console.log(formatLogMessage('debug', `[isPageFromPreviousScan] Error evaluating page: ${err.message}`));
+        console.log(formatLogMessage('debug', `${IS_PAGE_FROM_PREVIOUS_SCAN_TAG} Error evaluating page: ${err.message}`));
       }
     }
     return false; // Conservative - don't close if we can't evaluate
@@ -581,22 +601,13 @@ function untrackPage(page) {
 }
 
 /**
- * Purges stale entries from tracking Maps (pages that were closed without cleanup)
- * Should be called periodically to prevent memory leaks
+ * No-op since the trackers were migrated to WeakMap — GC reclaims dead-page
+ * entries automatically when Puppeteer drops its internal references. Kept
+ * exported so the ~7 callers in nwss.js continue to compile; safe to delete
+ * entirely once those callsites are scrubbed.
  */
 function purgeStaleTrackers() {
-  for (const [page] of pageCreationTracker) {
-    try {
-      if (page.isClosed()) {
-        pageCreationTracker.delete(page);
-        pageUsageTracker.delete(page);
-      }
-    } catch (e) {
-      // Page reference is invalid, remove it
-      pageCreationTracker.delete(page);
-      pageUsageTracker.delete(page);
-    }
-  }
+  // intentionally empty
 }
 
 /**
@@ -651,8 +662,13 @@ async function testNetworkCapability(browserInstance, timeout = 10000) {
       'Network.enable test timeout'
     );
 
-    // Turn off interception and close
-    await testPage.setRequestInterception(false);
+    // Turn off interception. Symmetric to the enable above — Network.disable
+    // can hang for the same CDP reasons, so it needs the same watchdog.
+    await raceWithTimeout(
+      testPage.setRequestInterception(false),
+      timeout,
+      'Network.disable test timeout'
+    );
     result.capable = true;
     result.responseTime = Date.now() - startTime;
 
@@ -718,7 +734,7 @@ async function checkBrowserHealth(browserInstance, timeout = 8000) {
     healthResult.responseTime = Date.now() - startTime;
 
     // Test 3: Check for excessive pages (memory leak indicator)
-    if (pages.length > 30) {
+    if (pages.length > PAGE_COUNT_WARN_THRESHOLD) {
       healthResult.recommendations.push('Too many open pages - consider browser restart');
     }
 
@@ -740,12 +756,18 @@ async function checkBrowserHealth(browserInstance, timeout = 8000) {
 
       // Test 5: Network capability test on the same page (avoids creating a second test page)
       try {
+        const netTimeout = Math.min(timeout, 5000);
         await raceWithTimeout(
           testPage.setRequestInterception(true),
-          Math.min(timeout, 5000),
+          netTimeout,
           'Network.enable test timeout'
         );
-        await testPage.setRequestInterception(false);
+        // Disable can hang for the same CDP reasons enable can; mirror the watchdog.
+        await raceWithTimeout(
+          testPage.setRequestInterception(false),
+          netTimeout,
+          'Network.disable test timeout'
+        );
         healthResult.networkCapable = true;
       } catch (networkErr) {
         healthResult.networkCapable = false;
@@ -837,9 +859,9 @@ async function checkBrowserMemory(browserInstance) {
           else resolve(stdout);
         });
       });
-      const memoryKB = parseInt(memInfo.trim());
-      
-      if (!isNaN(memoryKB)) {
+      const memoryKB = parseInt(memInfo.trim(), 10);
+
+      if (!Number.isNaN(memoryKB)) {
         const memoryMB = Math.round(memoryKB / 1024);
         memoryResult.available = true;
         memoryResult.usage = {
@@ -897,7 +919,7 @@ async function testBrowserConnectivity(browserInstance, timeout = 2500) {
 
   try {
     // Test 1: Basic browser connection
-    const isConnected = browserInstance.isConnected();
+    const isConnected = browserInstance.connected;
     connectivityResult.connected = isConnected;
     
     if (!isConnected) {
@@ -994,7 +1016,9 @@ async function performHealthAssessment(browserInstance, options = {}) {
     assessment.needsRestart = true;
   } else if (assessment.recommendations.length > 0) {
     assessment.overall = 'degraded';
-    assessment.needsRestart = RESTART_RECOMMENDATION_REGEX.test(assessment.recommendations.join('|'));
+    // Test each recommendation independently — avoids allocating a joined
+    // string just to feed one regex test against it.
+    assessment.needsRestart = assessment.recommendations.some(r => RESTART_RECOMMENDATION_REGEX.test(r));
   } else {
     assessment.overall = 'healthy';
     assessment.needsRestart = false;
@@ -1058,10 +1082,10 @@ async function monitorBrowserHealth(browserInstance, context = {}, options = {})
     } else if (urlsSinceCleanup >= cleanupInterval) {
       result.shouldRestart = true;
       result.reason = `Scheduled cleanup after ${urlsSinceCleanup} URLs`;
-    } else if (assessment.browser.responseTime > 6000) {
+    } else if (assessment.browser.responseTime > SLOW_RESPONSE_RESTART_MS) {
       result.shouldRestart = true;
-      result.reason = `Slow browser response: ${assessment.browser.responseTime}ms (threshold: 6000ms)`;
-    } else if (assessment.browser.pageCount > 40) {
+      result.reason = `Slow browser response: ${assessment.browser.responseTime}ms (threshold: ${SLOW_RESPONSE_RESTART_MS}ms)`;
+    } else if (assessment.browser.pageCount > PAGE_COUNT_RESTART_THRESHOLD) {
       // More aggressive page count monitoring for Puppeteer 23.x
       result.shouldRestart = true;
       result.reason = `Too many open pages: ${assessment.browser.pageCount} (memory leak protection)`;
@@ -1070,7 +1094,7 @@ async function monitorBrowserHealth(browserInstance, context = {}, options = {})
     // Logging
     if (!silentMode && result.shouldRestart) {
       const progress = totalSites > 0 ? ` (${siteIndex + 1}/${totalSites})` : '';
-      console.log(`\n${messageColors.fileOp('?? Browser restart needed')} before site${progress}: ${result.reason}`);
+      console.log(`\n${messageColors.fileOp('Browser restart needed')} before site${progress}: ${result.reason}`);
     }
 
     if (forceDebug && !result.shouldRestart) {

package/lib/cdp.js

@@ -25,7 +25,11 @@
 //   - Compatible with headless and headful modes
 //   - Tested with Puppeteer 13+ but should work with older versions
 
-const { formatLogMessage } = require('./colorize');
+const { formatLogMessage, messageColors } = require('./colorize');
+
+// Precomputed colored '[cdp]' subsystem prefix. formatLogMessage only colors
+// the [severity] tag; '[cdp]' was sitting plain inside the message string.
+const CDP_TAG = messageColors.processing('[cdp]');
 
 /**
  * Race a promise against a timeout, clearing the timer when the promise settles.
@@ -43,6 +47,33 @@ function raceWithTimeout(promise, ms, message) {
   return Promise.race([promise, timeoutPromise]).finally(() => clearTimeout(timeoutId));
 }
 
+// Shared no-op cleanup used by every no-CDP / CDP-failed return path. Hoisted
+// so createSessionResult() doesn't allocate a fresh `async () => {}` per call.
+const NOOP_CLEANUP = async () => {};
+
+/**
+ * Safely extract a hostname from a URL string with a fallback for malformed URLs.
+ * Used in logs where 'unknown' or a truncated URL is acceptable on parse failure.
+ */
+function safeHostname(url, fallback = 'unknown') {
+  try { return new URL(url).hostname; } catch { return fallback; }
+}
+
+/**
+ * Recognize CDP errors that mean the browser is broken and needs restarting.
+ * Centralized so setRequestInterceptionWithTimeout and createCDPSession's catch
+ * stay in sync — previously each had its own slightly-different pattern list.
+ */
+function isCriticalCDPError(message) {
+  if (!message) return false;
+  return message.includes('Network.enable timed out') ||
+         message.includes('Protocol error') ||
+         message.includes('ProtocolError') ||
+         message.includes('Session closed') ||
+         message.includes('Target closed') ||
+         message.includes('Browser has been closed');
+}
+
 /**
  * Creates a standardized session result object for consistent V8 optimization
  * @param {object|null} session - CDP session or null
@@ -50,7 +81,7 @@ function raceWithTimeout(promise, ms, message) {
  * @param {boolean} isEnhanced - Whether enhanced features are active
  * @returns {object} Standardized session object
  */
-const createSessionResult = (session = null, cleanup = async () => {}, isEnhanced = false) => ({
+const createSessionResult = (session = null, cleanup = NOOP_CLEANUP, isEnhanced = false) => ({
   session,
   cleanup,
   isEnhanced
@@ -76,10 +107,8 @@ async function setRequestInterceptionWithTimeout(page, timeout = 15000) {
   try {
     await raceWithTimeout(page.setRequestInterception(true), timeout, 'Request interception timeout - first attempt');
   } catch (firstError) {
-    // Check for immediate critical failures
-    if (firstError.message.includes('Target closed') ||
-        firstError.message.includes('Session closed') ||
-        firstError.message.includes('Browser has been closed')) {
+    // Don't retry if the browser/session is already gone — escalate immediately.
+    if (isCriticalCDPError(firstError.message)) {
       throw new Error('CRITICAL_BROWSER_ERROR: ' + firstError.message);
     }
 
@@ -87,8 +116,7 @@ async function setRequestInterceptionWithTimeout(page, timeout = 15000) {
     try {
       await raceWithTimeout(page.setRequestInterception(true), timeout * 2, 'Request interception timeout - retry failed');
     } catch (retryError) {
-      if (retryError.message.includes('Network.enable timed out') || 
-          retryError.message.includes('ProtocolError')) {
+      if (isCriticalCDPError(retryError.message)) {
         throw new Error('CRITICAL_NETWORK_ERROR: ' + retryError.message);
       }
       throw retryError;
@@ -103,7 +131,7 @@ async function setRequestInterceptionWithTimeout(page, timeout = 15000) {
  *   const cdpManager = await createCDPSession(page, 'https://example.com', {
  *     enableCDP: true,        // Global CDP flag
  *     siteSpecificCDP: true,  // Site-specific CDP flag  
- *     forceDebug: false       // Enable debug logging
+ *     forceDebug: true        // When true, install the Network.requestWillBeSent log listener
  *   });
  *   
  *   // Your page automation code here...
@@ -130,32 +158,32 @@ async function setRequestInterceptionWithTimeout(page, timeout = 15000) {
  * @param {boolean} options.enableCDP - Global CDP flag (from --cdp command line)
  * @param {boolean} options.siteSpecificCDP - Site-specific CDP flag (from config)
  * @param {boolean} options.forceDebug - Debug logging flag
- * @param {string} options.currentUrl - Current URL for domain-specific CDP decisions
  * @returns {Promise<object>} CDP session object with cleanup method
  */
 async function createCDPSession(page, currentUrl, options = {}) {
   const { enableCDP, siteSpecificCDP, forceDebug } = options;
-  
-  // Determine if CDP logging is needed for this page
-  // You can customize this logic for your application's needs
-  const cdpLoggingNeeded = enableCDP || siteSpecificCDP === true;
-  
+
+  // The only thing this function's CDP session does is feed a debug-gated
+  // Network.requestWillBeSent listener. With !forceDebug the listener body is
+  // a no-op, so setting up CDP (and paying Network.enable's overhead) buys
+  // nothing. Skip entirely in that case — same observable behavior as before,
+  // minus the wasted protocol traffic.
+  const cdpLoggingNeeded = (enableCDP || siteSpecificCDP === true) && forceDebug;
+
   if (!cdpLoggingNeeded) {
-    // Return a null session with no-op cleanup for consistent API
     return createSessionResult();
   }
 
-  // Log which CDP mode is being used
-  if (forceDebug) {
-    const urlHostname = (() => {
-      try { return new URL(currentUrl).hostname; } catch { return 'unknown'; }
-    })();
+  // Parse the current URL hostname once and reuse it for the mode-log line,
+  // the per-request listener's first-vs-third-party comparison, and (with a
+  // different fallback) the catch-block error context.
+  const currentHostname = safeHostname(currentUrl);
 
-    if (enableCDP) {
-      console.log(formatLogMessage('debug', `[cdp] Global CDP enabled by --cdp flag for ${urlHostname}`));
-    } else if (siteSpecificCDP === true) {
-      console.log(formatLogMessage('debug', `[cdp] Site-specific CDP enabled for ${urlHostname} (via cdp: true or cdp_specific domain match)`));
-    }
+  // Log which CDP mode is being used
+  if (enableCDP) {
+    console.log(formatLogMessage('debug', `${CDP_TAG} Global CDP enabled by --cdp flag for ${currentHostname}`));
+  } else if (siteSpecificCDP === true) {
+    console.log(formatLogMessage('debug', `${CDP_TAG} Site-specific CDP enabled for ${currentHostname} (via cdp: true or cdp_specific domain match)`));
   }
 
   let cdpSession = null;
@@ -164,84 +192,78 @@ async function createCDPSession(page, currentUrl, options = {}) {
     // Create CDP session using modern Puppeteer 20+ API
     // Add timeout protection for CDP session creation
     cdpSession = await raceWithTimeout(page.createCDPSession(), 20000, 'CDP session creation timeout');
-    
-    // Enable network domain - required for network event monitoring  
-    await cdpSession.send('Network.enable');
 
-    // Parse current URL hostname once, reused across all request events
-    let currentHostname = 'unknown';
-    try { currentHostname = new URL(currentUrl).hostname; } catch (_) {}
+    // Enable network domain — required for network event monitoring. This is
+    // the operation the rest of the codebase has learned can hang under
+    // overload; race against a watchdog so we don't block the page load.
+    await raceWithTimeout(
+      cdpSession.send('Network.enable'),
+      15000,
+      'Network.enable timed out'
+    );
 
     // Set up network request monitoring
-    // This captures ALL network requests at the browser engine level
+    // This captures ALL network requests at the browser engine level.
+    // (We've already established forceDebug is true at this point — no inner
+    // check needed.)
     cdpSession.on('Network.requestWillBeSent', (params) => {
-      if (forceDebug) {
-        const { url: requestUrl, method } = params.request;
-        const initiator = params.initiator ? params.initiator.type : 'unknown';
-        let hostnameForLog = currentHostname;
-        try {
-          const requestHostname = new URL(requestUrl).hostname;
-          if (currentHostname !== requestHostname) {
-            hostnameForLog = `${currentHostname}?${requestHostname}`;
-          }
-        } catch (_) {}
-        console.log(formatLogMessage('debug', `[cdp][${hostnameForLog}] ${method} ${requestUrl} (initiator: ${initiator})`));
-      }
+      const { url: requestUrl, method } = params.request;
+      const initiator = params.initiator?.type ?? 'unknown';
+      let hostnameForLog = currentHostname;
+      try {
+        const requestHostname = new URL(requestUrl).hostname;
+        if (currentHostname !== requestHostname) {
+          hostnameForLog = `${currentHostname}?${requestHostname}`;
+        }
+      } catch (_) {}
+      console.log(formatLogMessage('debug', `${CDP_TAG}[${hostnameForLog}] ${method} ${requestUrl} (initiator: ${initiator})`));
     });
 
-    if (forceDebug) {
-      console.log(formatLogMessage('debug', `CDP session created successfully for ${currentUrl}`));
-    }
+    console.log(formatLogMessage('debug', `${CDP_TAG} CDP session created successfully for ${currentUrl}`));
 
-    return {
-      session: cdpSession,
-      cleanup: async () => {
+    return createSessionResult(
+      cdpSession,
+      async () => {
         // Safe cleanup that never throws errors
         if (cdpSession) {
           try {
             await cdpSession.detach();
-            if (forceDebug) {
-              console.log(formatLogMessage('debug', `CDP session detached for ${currentUrl}`));
-            }
+            console.log(formatLogMessage('debug', `${CDP_TAG} CDP session detached for ${currentUrl}`));
           } catch (cdpCleanupErr) {
             // Log cleanup errors but don't throw - cleanup should never fail the calling code
-            if (forceDebug) {
-              console.log(formatLogMessage('debug', `Failed to detach CDP session for ${currentUrl}: ${cdpCleanupErr.message}`));
-            }
+            console.log(formatLogMessage('debug', `${CDP_TAG} Failed to detach CDP session for ${currentUrl}: ${cdpCleanupErr.message}`));
           }
         }
       },
-      isEnhanced: false
-    };
+      false
+    );
 
   } catch (cdpErr) {
-    cdpSession = null; // Reset on failure
-    
-    // Enhanced error context for CDP domain-specific debugging
-    const urlContext = (() => {
-      try {
-        return new URL(currentUrl).hostname;
-      } catch {
-        return `${currentUrl.substring(0, 50)}...`;
+    // If the session was created but a subsequent send/wire-up failed, detach
+    // it so we don't leak a half-attached session. Previously the code just
+    // nulled the local and orphaned the session. We're already past the
+    // cdpLoggingNeeded gate here so forceDebug is true — log a failed detach
+    // instead of swallowing it, so partial-cleanup failures aren't invisible.
+    if (cdpSession) {
+      try { await cdpSession.detach(); }
+      catch (partialDetachErr) {
+        console.log(formatLogMessage('debug', `${CDP_TAG} Partial-session detach failed for ${currentUrl}: ${partialDetachErr.message}`));
       }
-    })();
+      cdpSession = null;
+    }
+
+    // Enhanced error context for CDP domain-specific debugging
+    const urlContext = safeHostname(currentUrl, `${currentUrl.substring(0, 50)}...`);
 
-    // Categorize CDP errors for proper handling
-    // Enhanced error handling for Puppeteer 20+ error patterns
-    if (cdpErr.message.includes('Network.enable timed out') || 
-        cdpErr.message.includes('Protocol error') ||
-        cdpErr.message.includes('Session closed') ||
-        cdpErr.message.includes('Target closed') ||
-        cdpErr.message.includes('Browser has been closed')) {
-      // CRITICAL ERROR: Browser is broken and needs restart
-      // Re-throw these errors so calling code can handle browser restart
-      throw new Error(`Browser protocol broken: ${cdpErr.message}`);
+    // Critical errors: browser is broken, propagate so the caller can restart.
+    if (isCriticalCDPError(cdpErr.message)) {
+      throw new Error(`Browser protocol broken (${urlContext}): ${cdpErr.message}`);
     }
-    
+
     // NON-CRITICAL ERROR: CDP failed but browser is still usable
     // Log warning but return working session object
-    console.warn(formatLogMessage('warn', `[cdp] Failed to attach CDP session for ${currentUrl}: ${cdpErr.message}`));
-    
+    console.warn(formatLogMessage('warn', `${CDP_TAG} Failed to attach CDP session for ${urlContext}: ${cdpErr.message}`));
+
     // Return null session with no-op cleanup for consistent API
     return createSessionResult();
   }