vibecheck-ai 2.0.2 → 5.0.0

package/bin/runners/runReality.js

@@ -0,0 +1,2260 @@
+/**
+ * Reality Mode v2 - Two-Pass Auth Verification + Dead UI Crawler + Fake Data Detection
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * ENTERPRISE EDITION - World-Class Terminal Experience
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * TIER ENFORCEMENT:
+ * - FREE: Preview mode (5 pages, 20 clicks, no auth boundary)
+ * - STARTER: Full budgets + basic auth verification
+ * - PRO: Advanced auth boundary (multi-role, 2-pass) + fake data detection
+ *
+ * Pass A (anon): crawl + click, record which routes look protected
+ * Pass B (auth): crawl same routes using storageState, verify protected routes accessible
+ *
+ * Findings:
+ * - Dead UI (clicks that do nothing)
+ * - HTTP errors (4xx/5xx)
+ * - Auth coverage (protected route reachable anonymously = BLOCK)
+ * - Fake domain detection (localhost, jsonplaceholder, ngrok, mockapi.io)
+ * - Fake response detection (demo IDs, test keys, placeholder data)
+ * - Mock status codes (418, 999, etc.)
+ * - Route coverage stats
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { parseGlobalFlags, shouldShowBanner } = require("./lib/global-flags");
+
+// Entitlements enforcement
+const entitlements = require("./lib/entitlements-v2");
+const upsell = require("./lib/upsell");
+
+let chromium;
+let playwrightError = null;
+try {
+  chromium = require("playwright").chromium;
+} catch (e) {
+  chromium = null;
+  playwrightError = e.message;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ADVANCED TERMINAL - ANSI CODES & UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  italic: '\x1b[3m',
+  underline: '\x1b[4m',
+  blink: '\x1b[5m',
+  inverse: '\x1b[7m',
+  hidden: '\x1b[8m',
+  strike: '\x1b[9m',
+  // Colors
+  black: '\x1b[30m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  // Bright colors
+  gray: '\x1b[90m',
+  brightRed: '\x1b[91m',
+  brightGreen: '\x1b[92m',
+  brightYellow: '\x1b[93m',
+  brightBlue: '\x1b[94m',
+  brightMagenta: '\x1b[95m',
+  brightCyan: '\x1b[96m',
+  brightWhite: '\x1b[97m',
+  // Background
+  bgBlack: '\x1b[40m',
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+  bgBlue: '\x1b[44m',
+  bgMagenta: '\x1b[45m',
+  bgCyan: '\x1b[46m',
+  bgWhite: '\x1b[47m',
+  // Cursor control
+  cursorUp: (n = 1) => `\x1b[${n}A`,
+  cursorDown: (n = 1) => `\x1b[${n}B`,
+  cursorRight: (n = 1) => `\x1b[${n}C`,
+  cursorLeft: (n = 1) => `\x1b[${n}D`,
+  clearLine: '\x1b[2K',
+  clearScreen: '\x1b[2J',
+  saveCursor: '\x1b[s',
+  restoreCursor: '\x1b[u',
+  hideCursor: '\x1b[?25l',
+  showCursor: '\x1b[?25h',
+};
+
+// True color support
+const rgb = (r, g, b) => `\x1b[38;2;${r};${g};${b}m`;
+const bgRgb = (r, g, b) => `\x1b[48;2;${r};${g};${b}m`;
+
+// Premium color palette (orange/coral theme for "reality" - testing/verification)
+const colors = {
+  // Gradient for banner
+  gradient1: rgb(255, 150, 100),   // Light coral
+  gradient2: rgb(255, 130, 80),    // Coral
+  gradient3: rgb(255, 110, 60),    // Orange-coral
+  gradient4: rgb(255, 90, 50),     // Orange
+  gradient5: rgb(255, 70, 40),     // Deep orange
+  gradient6: rgb(255, 50, 30),     // Red-orange
+  
+  // Pass colors
+  anon: rgb(150, 200, 255),        // Blue for anonymous
+  auth: rgb(100, 255, 180),        // Green for authenticated
+  
+  // Category colors
+  deadUI: rgb(255, 100, 100),      // Red for dead UI
+  authCoverage: rgb(255, 180, 100), // Orange for auth issues
+  httpError: rgb(255, 150, 50),    // Amber for HTTP errors
+  coverage: rgb(100, 200, 255),    // Blue for coverage
+  
+  // Status colors
+  success: rgb(0, 255, 150),
+  warning: rgb(255, 200, 0),
+  error: rgb(255, 80, 80),
+  info: rgb(100, 200, 255),
+  
+  // UI colors
+  accent: rgb(255, 150, 100),
+  muted: rgb(140, 120, 100),
+  subtle: rgb(100, 80, 60),
+  highlight: rgb(255, 255, 255),
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// PREMIUM BANNER
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const REALITY_BANNER = `
+${rgb(255, 160, 120)}  ██████╗ ███████╗ █████╗ ██╗     ██╗████████╗██╗   ██╗${c.reset}
+${rgb(255, 140, 100)}  ██╔══██╗██╔════╝██╔══██╗██║     ██║╚══██╔══╝╚██╗ ██╔╝${c.reset}
+${rgb(255, 120, 80)}  ██████╔╝█████╗  ███████║██║     ██║   ██║    ╚████╔╝ ${c.reset}
+${rgb(255, 100, 60)}  ██╔══██╗██╔══╝  ██╔══██║██║     ██║   ██║     ╚██╔╝  ${c.reset}
+${rgb(255, 80, 40)}  ██║  ██║███████╗██║  ██║███████╗██║   ██║      ██║   ${c.reset}
+${rgb(255, 60, 20)}  ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚══════╝╚═╝   ╚═╝      ╚═╝   ${c.reset}
+`;
+
+const BANNER_FULL = `
+${rgb(255, 160, 120)}  ██╗   ██╗██╗██████╗ ███████╗ ██████╗██╗  ██╗███████╗ ██████╗██╗  ██╗${c.reset}
+${rgb(255, 140, 100)}  ██║   ██║██║██╔══██╗██╔════╝██╔════╝██║  ██║██╔════╝██╔════╝██║ ██╔╝${c.reset}
+${rgb(255, 120, 80)}  ██║   ██║██║██████╔╝█████╗  ██║     ███████║█████╗  ██║     █████╔╝ ${c.reset}
+${rgb(255, 100, 60)}  ╚██╗ ██╔╝██║██╔══██╗██╔══╝  ██║     ██╔══██║██╔══╝  ██║     ██╔═██╗ ${c.reset}
+${rgb(255, 80, 40)}   ╚████╔╝ ██║██████╔╝███████╗╚██████╗██║  ██║███████╗╚██████╗██║  ██╗${c.reset}
+${rgb(255, 60, 20)}    ╚═══╝  ╚═╝╚═════╝ ╚══════╝ ╚═════╝╚═╝  ╚═╝╚══════╝ ╚═════╝╚═╝  ╚═╝${c.reset}
+
+${c.dim}  ┌─────────────────────────────────────────────────────────────────────┐${c.reset}
+${c.dim}  │${c.reset}  ${rgb(255, 150, 100)}🎭${c.reset} ${c.bold}REALITY${c.reset} ${c.dim}•${c.reset} ${rgb(200, 200, 200)}Dead UI${c.reset} ${c.dim}•${c.reset} ${rgb(150, 150, 150)}Fake Data${c.reset} ${c.dim}•${c.reset} ${rgb(100, 200, 255)}Auth Coverage${c.reset}     ${c.dim}│${c.reset}
+${c.dim}  └─────────────────────────────────────────────────────────────────────┘${c.reset}
+`;
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// FAKE DATA DETECTION PATTERNS (from reality-mode/reality-scanner.ts)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// FAKE DETECTION PATTERNS WITH CONFIDENCE SCORING
+// Each pattern has a confidence level to reduce false positives
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const FAKE_DOMAIN_PATTERNS = [
+  // CRITICAL: These are almost certainly fake backends (confidence: 0.95+)
+  { pattern: /jsonplaceholder\.typicode\.com/i, name: "JSONPlaceholder mock API", confidence: 0.99, severity: 'BLOCK' },
+  { pattern: /reqres\.in/i, name: "ReqRes mock API", confidence: 0.99, severity: 'BLOCK' },
+  { pattern: /mockapi\.io/i, name: "MockAPI.io", confidence: 0.99, severity: 'BLOCK' },
+  { pattern: /mocky\.io/i, name: "Mocky.io", confidence: 0.99, severity: 'BLOCK' },
+  { pattern: /httpbin\.org/i, name: "HTTPBin testing API", confidence: 0.95, severity: 'BLOCK' },
+  { pattern: /api\.example\.com/i, name: "Example.com API", confidence: 0.95, severity: 'BLOCK' },
+  { pattern: /fake\.api/i, name: "Fake API pattern", confidence: 0.95, severity: 'BLOCK' },
+  { pattern: /demo\.api/i, name: "Demo API pattern", confidence: 0.90, severity: 'BLOCK' },
+  
+  // HIGH: Likely development/testing (confidence: 0.7-0.9)
+  // NOTE: These could be legitimate in dev/CI contexts
+  { pattern: /localhost:\d+/i, name: "Localhost API", confidence: 0.75, severity: 'WARN', devContextOk: true },
+  { pattern: /127\.0\.0\.1:\d+/i, name: "Loopback API", confidence: 0.75, severity: 'WARN', devContextOk: true },
+  { pattern: /\.ngrok\.io/i, name: "Ngrok tunnel", confidence: 0.80, severity: 'WARN', devContextOk: true },
+  { pattern: /\.ngrok-free\.app/i, name: "Ngrok free tunnel", confidence: 0.80, severity: 'WARN', devContextOk: true },
+  
+  // MEDIUM: Could be legitimate staging (confidence: 0.5-0.7)
+  // NOTE: Many organizations have legitimate staging environments
+  { pattern: /staging\.[^/]+\/api/i, name: "Staging API endpoint", confidence: 0.60, severity: 'WARN', stagingContextOk: true },
+  { pattern: /\.local\//i, name: "Local domain", confidence: 0.50, severity: 'WARN', devContextOk: true },
+  { pattern: /\.test\//i, name: "Test domain", confidence: 0.50, severity: 'WARN', devContextOk: true },
+];
+
+const FAKE_RESPONSE_PATTERNS = [
+  // CRITICAL: Test API keys exposed (security issue)
+  { pattern: /sk_test_[a-zA-Z0-9]{20,}/i, name: "Test Stripe secret key", confidence: 0.99, severity: 'BLOCK' },
+  { pattern: /pk_test_[a-zA-Z0-9]{20,}/i, name: "Test Stripe public key", confidence: 0.95, severity: 'WARN' },
+  
+  // HIGH: Clearly fake IDs/data
+  { pattern: /inv_demo_[a-zA-Z0-9]+/i, name: "Demo invoice ID", confidence: 0.95, severity: 'BLOCK' },
+  { pattern: /user_demo_[a-zA-Z0-9]+/i, name: "Demo user ID", confidence: 0.95, severity: 'BLOCK' },
+  { pattern: /cus_demo_[a-zA-Z0-9]+/i, name: "Demo customer ID", confidence: 0.95, severity: 'BLOCK' },
+  { pattern: /sub_demo_[a-zA-Z0-9]+/i, name: "Demo subscription ID", confidence: 0.95, severity: 'BLOCK' },
+  { pattern: /"mock":\s*true/i, name: "Mock flag enabled", confidence: 0.95, severity: 'BLOCK' },
+  { pattern: /"isDemo":\s*true/i, name: "Demo mode flag", confidence: 0.95, severity: 'BLOCK' },
+  { pattern: /"status":\s*"simulated"/i, name: "Simulated status", confidence: 0.90, severity: 'BLOCK' },
+  
+  // MEDIUM: Placeholder content (could be legitimate in docs/examples)
+  // NOTE: Need context awareness - these are fine in documentation/help pages
+  { pattern: /lorem\s+ipsum\s+dolor/i, name: "Lorem ipsum placeholder", confidence: 0.70, severity: 'WARN', docsContextOk: true },
+  { pattern: /john\.doe@/i, name: "John Doe placeholder email", confidence: 0.65, severity: 'WARN', docsContextOk: true },
+  { pattern: /jane\.doe@/i, name: "Jane Doe placeholder email", confidence: 0.65, severity: 'WARN', docsContextOk: true },
+  { pattern: /user@example\.com/i, name: "Example.com email", confidence: 0.50, severity: 'WARN', docsContextOk: true },
+  { pattern: /placeholder\.(com|jpg|png)/i, name: "Placeholder domain/image", confidence: 0.60, severity: 'WARN', docsContextOk: true },
+  
+  // LOWER: Could have many false positives
+  { pattern: /"id":\s*"demo"/i, name: "Demo ID value", confidence: 0.70, severity: 'WARN' },
+  { pattern: /"id":\s*"test"/i, name: "Test ID value", confidence: 0.60, severity: 'WARN' },
+  { pattern: /"success":\s*true[^}]*"demo"/i, name: "Demo success response", confidence: 0.75, severity: 'WARN' },
+];
+
+// URLs that are allowed and should skip detection
+const FAKE_DETECTION_ALLOWLIST = [
+  /\/docs?\//i,          // Documentation pages
+  /\/help\//i,           // Help pages  
+  /\/examples?\//i,      // Example pages
+  /\/demo\//i,           // Demo pages (intentional)
+  /\/playground\//i,     // Playground/sandbox
+  /\/api-docs?\//i,      // API documentation
+  /\/swagger/i,          // Swagger docs
+  /\/openapi/i,          // OpenAPI docs
+  /readme/i,             // README content
+  /changelog/i,          // Changelog
+];
+
+/**
+ * Classify a network request/response for fake data patterns
+ * Returns null if clean, or an object with detection details
+ * 
+ * Enhanced with:
+ * - Confidence scoring to reduce false positives
+ * - Context awareness (dev, staging, docs)
+ * - Allowlist for legitimate use cases
+ */
+function classifyNetworkTraffic(url, responseBody, status, context = {}) {
+  // Skip static assets (images, fonts, stylesheets, scripts)
+  if (/\.(js|css|png|jpg|jpeg|svg|ico|woff|woff2|ttf|eot|gif|webp|mp4|webm|pdf)(\?|$)/i.test(url)) {
+    return null;
+  }
+  
+  // Check allowlist - skip detection for documentation/example URLs
+  for (const allowPattern of FAKE_DETECTION_ALLOWLIST) {
+    if (allowPattern.test(url)) {
+      return null;
+    }
+  }
+  
+  const detections = [];
+  const isDev = context.isDev || process.env.NODE_ENV === 'development';
+  const isStaging = context.isStaging || /staging|stg|preprod/i.test(url);
+  const isDocsPage = context.isDocsPage || /docs?|help|example|readme/i.test(url);
+  
+  // Check for fake domain patterns
+  for (const { pattern, name, confidence, severity, devContextOk, stagingContextOk } of FAKE_DOMAIN_PATTERNS) {
+    if (pattern.test(url)) {
+      // Skip if this pattern is OK in current context
+      if (devContextOk && isDev) continue;
+      if (stagingContextOk && isStaging) continue;
+      
+      detections.push({
+        type: 'fake-domain',
+        severity,
+        evidence: `URL matches fake domain pattern: ${name}`,
+        url,
+        confidence,
+        pattern: pattern.source
+      });
+      break; // One domain match is enough
+    }
+  }
+  
+  // Check response body for fake data patterns
+  if (responseBody && typeof responseBody === 'string') {
+    // Skip very short responses (likely not meaningful data)
+    if (responseBody.length < 20) {
+      return detections.length > 0 ? detections : null;
+    }
+    
+    for (const { pattern, name, confidence, severity, docsContextOk } of FAKE_RESPONSE_PATTERNS) {
+      // Skip patterns that are OK in docs context
+      if (docsContextOk && isDocsPage) continue;
+      
+      if (pattern.test(responseBody)) {
+        detections.push({
+          type: 'fake-response',
+          severity,
+          evidence: `Response contains ${name}`,
+          url,
+          confidence,
+          pattern: pattern.source
+        });
+      }
+    }
+  }
+  
+  // Check for suspicious status codes (with lower confidence)
+  if (status === 418 || status === 999 || status === 0) {
+    detections.push({
+      type: 'mock-status',
+      severity: 'WARN',
+      evidence: `Suspicious HTTP status code: ${status}`,
+      url,
+      confidence: 0.60 // Lower confidence - could be legitimate
+    });
+  }
+  
+  // Filter out low-confidence detections if we have high-confidence ones
+  const highConfidence = detections.filter(d => d.confidence >= 0.80);
+  if (highConfidence.length > 0 && detections.length > highConfidence.length) {
+    // Return only high-confidence detections to reduce noise
+    return highConfidence;
+  }
+  
+  return detections.length > 0 ? detections : null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ICONS & SYMBOLS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const ICONS = {
+  // Main
+  reality: '🎭',
+  browser: '🌐',
+  crawl: '🕷️',
+  
+  // Status
+  check: '✓',
+  cross: '✗',
+  warning: '⚠',
+  info: 'ℹ',
+  arrow: '→',
+  bullet: '•',
+  
+  // Passes
+  anon: '👤',
+  auth: '🔑',
+  pass: '✅',
+  fail: '❌',
+  
+  // Categories
+  deadUI: '💀',
+  click: '👆',
+  link: '🔗',
+  http: '📡',
+  coverage: '📊',
+  shield: '🛡️',
+  
+  // Actions
+  running: '▶',
+  complete: '●',
+  pending: '○',
+  skip: '◌',
+  
+  // Objects
+  page: '📄',
+  screenshot: '📸',
+  clock: '⏱',
+  lightning: '⚡',
+  sparkle: '✨',
+  target: '🎯',
+  eye: '👁️',
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// BOX DRAWING
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const BOX = {
+  topLeft: '╭', topRight: '╮', bottomLeft: '╰', bottomRight: '╯',
+  horizontal: '─', vertical: '│',
+  teeRight: '├', teeLeft: '┤', teeDown: '┬', teeUp: '┴',
+  cross: '┼',
+  // Double line
+  dTopLeft: '╔', dTopRight: '╗', dBottomLeft: '╚', dBottomRight: '╝',
+  dHorizontal: '═', dVertical: '║',
+  // Heavy
+  hTopLeft: '┏', hTopRight: '┓', hBottomLeft: '┗', hBottomRight: '┛',
+  hHorizontal: '━', hVertical: '┃',
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SPINNER & PROGRESS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const SPINNER_DOTS = ['⣾', '⣽', '⣻', '⢿', '⡿', '⣟', '⣯', '⣷'];
+const SPINNER_CRAWL = ['🕷️ ', ' 🕷️', '  🕷️', '   🕷️', '  🕷️', ' 🕷️'];
+
+let spinnerIndex = 0;
+let spinnerInterval = null;
+let spinnerStartTime = null;
+
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  const mins = Math.floor(ms / 60000);
+  const secs = Math.floor((ms % 60000) / 1000);
+  return `${mins}m ${secs}s`;
+}
+
+function formatNumber(num) {
+  return num.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+
+function truncate(str, len) {
+  if (!str) return '';
+  if (str.length <= len) return str;
+  return str.slice(0, len - 3) + '...';
+}
+
+function padCenter(str, width) {
+  const padding = Math.max(0, width - str.length);
+  const left = Math.floor(padding / 2);
+  const right = padding - left;
+  return ' '.repeat(left) + str + ' '.repeat(right);
+}
+
+function progressBar(percent, width = 30, opts = {}) {
+  const filled = Math.round((percent / 100) * width);
+  const empty = width - filled;
+  
+  let filledColor = opts.color || colors.accent;
+  if (!opts.color) {
+    if (percent >= 80) filledColor = colors.success;
+    else if (percent >= 50) filledColor = colors.warning;
+    else filledColor = colors.error;
+  }
+  
+  const filledChar = opts.filled || '█';
+  const emptyChar = opts.empty || '░';
+  
+  return `${filledColor}${filledChar.repeat(filled)}${c.dim}${emptyChar.repeat(empty)}${c.reset}`;
+}
+
+function startSpinner(message, color = colors.accent) {
+  spinnerStartTime = Date.now();
+  process.stdout.write(c.hideCursor);
+  
+  spinnerInterval = setInterval(() => {
+    const elapsed = formatDuration(Date.now() - spinnerStartTime);
+    process.stdout.write(`\r${c.clearLine}  ${color}${SPINNER_DOTS[spinnerIndex]}${c.reset} ${message} ${c.dim}${elapsed}${c.reset}`);
+    spinnerIndex = (spinnerIndex + 1) % SPINNER_DOTS.length;
+  }, 80);
+}
+
+function stopSpinner(message, success = true) {
+  if (spinnerInterval) {
+    clearInterval(spinnerInterval);
+    spinnerInterval = null;
+  }
+  const elapsed = spinnerStartTime ? formatDuration(Date.now() - spinnerStartTime) : '';
+  const icon = success ? `${colors.success}${ICONS.check}${c.reset}` : `${colors.error}${ICONS.cross}${c.reset}`;
+  process.stdout.write(`\r${c.clearLine}  ${icon} ${message} ${c.dim}${elapsed}${c.reset}\n`);
+  process.stdout.write(c.showCursor);
+  spinnerStartTime = null;
+}
+
+function updateSpinnerMessage(message) {
+  // Update message while spinner keeps running
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SECTION HEADERS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function printBanner() {
+  console.log(BANNER_FULL);
+}
+
+function printCompactBanner() {
+  console.log(REALITY_BANNER);
+}
+
+function printDivider(char = '─', width = 69, color = c.dim) {
+  console.log(`${color}  ${char.repeat(width)}${c.reset}`);
+}
+
+function printSection(title, icon = '◆') {
+  console.log();
+  console.log(`  ${colors.accent}${icon}${c.reset} ${c.bold}${title}${c.reset}`);
+  printDivider();
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// PASS DISPLAY - Two-Pass Visualization
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function printPassHeader(passType, url = null) {
+  const isAnon = passType === 'anon' || passType === 'ANON';
+  const config = isAnon 
+    ? { icon: ICONS.anon, name: 'PASS A: ANONYMOUS', color: colors.anon, desc: 'Crawling without authentication' }
+    : { icon: ICONS.auth, name: 'PASS B: AUTHENTICATED', color: colors.auth, desc: 'Crawling with session state' };
+  
+  console.log();
+  console.log(`  ${config.color}${BOX.hTopLeft}${BOX.hHorizontal.repeat(3)}${c.reset} ${config.icon} ${c.bold}${config.name}${c.reset}`);
+  console.log(`  ${config.color}${BOX.hVertical}${c.reset}   ${c.dim}${config.desc}${c.reset}`);
+  if (url) {
+    console.log(`  ${config.color}${BOX.hVertical}${c.reset}   ${colors.accent}${url}${c.reset}`);
+  }
+  console.log(`  ${config.color}${BOX.hBottomLeft}${BOX.hHorizontal.repeat(60)}${c.reset}`);
+}
+
+function printPassResult(passType, result) {
+  const isAnon = passType === 'anon' || passType === 'ANON';
+  const config = isAnon 
+    ? { icon: ICONS.anon, color: colors.anon }
+    : { icon: ICONS.auth, color: colors.auth };
+  
+  const pages = result.pagesVisited?.length || 0;
+  const findings = result.findings?.length || 0;
+  const blocks = result.findings?.filter(f => f.severity === 'BLOCK').length || 0;
+  const warns = result.findings?.filter(f => f.severity === 'WARN').length || 0;
+  
+  console.log();
+  console.log(`  ${config.color}${config.icon}${c.reset} ${c.bold}${isAnon ? 'Anonymous' : 'Authenticated'} Pass Complete${c.reset}`);
+  console.log(`     ${c.dim}Pages visited:${c.reset} ${colors.info}${pages}${c.reset}`);
+  console.log(`     ${c.dim}Findings:${c.reset} ${findings} ${c.dim}(${c.reset}${blocks > 0 ? colors.error : colors.success}${blocks} blockers${c.reset}${c.dim},${c.reset} ${warns > 0 ? colors.warning : colors.success}${warns} warnings${c.reset}${c.dim})${c.reset}`);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// COVERAGE DISPLAY
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function printCoverageCard(coverage, anonPages, authPages, maxPages) {
+  if (!coverage) return;
+  
+  printSection('COVERAGE', ICONS.coverage);
+  console.log();
+  
+  // UI Path Coverage
+  const pct = coverage.percent || 0;
+  const pctColor = pct >= 80 ? colors.success : pct >= 50 ? colors.warning : colors.error;
+  
+  console.log(`  ${c.bold}UI Path Coverage${c.reset}`);
+  console.log(`  ${progressBar(pct, 40)} ${pctColor}${c.bold}${pct}%${c.reset}`);
+  console.log(`  ${c.dim}${coverage.hit}/${coverage.total} paths visited${c.reset}`);
+  
+  // Pages visited breakdown
+  console.log();
+  console.log(`  ${c.bold}Pages Crawled${c.reset}`);
+  
+  const anonPct = Math.round((anonPages / maxPages) * 100);
+  console.log(`  ${ICONS.anon} ${c.dim}Anonymous:${c.reset}    ${progressBar(anonPct, 25, { color: colors.anon })} ${anonPages}/${maxPages}`);
+  
+  if (authPages !== null && authPages !== undefined) {
+    const authPct = Math.round((authPages / maxPages) * 100);
+    console.log(`  ${ICONS.auth} ${c.dim}Authenticated:${c.reset} ${progressBar(authPct, 25, { color: colors.auth })} ${authPages}/${maxPages}`);
+  }
+  
+  // Missed paths
+  if (coverage.missed && coverage.missed.length > 0) {
+    console.log();
+    console.log(`  ${c.dim}Missed paths (${coverage.missed.length}):${c.reset}`);
+    for (const missed of coverage.missed.slice(0, 5)) {
+      console.log(`    ${colors.warning}${ICONS.warning}${c.reset} ${c.dim}${truncate(missed, 50)}${c.reset}`);
+    }
+    if (coverage.missed.length > 5) {
+      console.log(`    ${c.dim}... and ${coverage.missed.length - 5} more${c.reset}`);
+    }
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// FINDINGS DISPLAY
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function getSeverityStyle(severity) {
+  const styles = {
+    BLOCK: { color: colors.error, bg: bgRgb(80, 20, 20), icon: '●', label: 'BLOCKER' },
+    WARN: { color: colors.warning, bg: bgRgb(80, 60, 0), icon: '◐', label: 'WARNING' },
+    INFO: { color: colors.info, bg: bgRgb(20, 40, 60), icon: '○', label: 'INFO' },
+  };
+  return styles[severity] || styles.INFO;
+}
+
+function getCategoryIcon(category) {
+  const icons = {
+    'DeadUI': ICONS.deadUI,
+    'AuthCoverage': ICONS.shield,
+    'HTTPError': ICONS.http,
+    // Fake data detection categories
+    'FakeDomain': '🔗',
+    'FakeResponse': '🎭',
+    'MockStatus': '📡',
+  };
+  return icons[category] || ICONS.bullet;
+}
+
+function getCategoryColor(category) {
+  const categoryColors = {
+    'DeadUI': colors.deadUI,
+    'AuthCoverage': colors.authCoverage,
+    'HTTPError': colors.httpError,
+    // Fake data detection categories - all critical (red/orange)
+    'FakeDomain': rgb(255, 80, 80),    // Red - critical
+    'FakeResponse': rgb(255, 100, 60), // Orange-red
+    'MockStatus': rgb(255, 150, 50),   // Amber
+  };
+  return categoryColors[category] || colors.accent;
+}
+
+function printFindingsBreakdown(findings) {
+  if (!findings || findings.length === 0) {
+    printSection('FINDINGS', ICONS.check);
+    console.log();
+    console.log(`  ${colors.success}${c.bold}${ICONS.sparkle} No issues found! UI is responsive.${c.reset}`);
+    return;
+  }
+  
+  // Group by category
+  const byCategory = {};
+  for (const f of findings) {
+    const cat = f.category || 'Other';
+    if (!byCategory[cat]) byCategory[cat] = [];
+    byCategory[cat].push(f);
+  }
+  
+  const blocks = findings.filter(f => f.severity === 'BLOCK');
+  const warns = findings.filter(f => f.severity === 'WARN');
+  
+  printSection(`FINDINGS (${blocks.length} blockers, ${warns.length} warnings)`, ICONS.target);
+  console.log();
+  
+  // Summary by category
+  for (const [category, catFindings] of Object.entries(byCategory)) {
+    const catBlocks = catFindings.filter(f => f.severity === 'BLOCK').length;
+    const catWarns = catFindings.filter(f => f.severity === 'WARN').length;
+    const icon = getCategoryIcon(category);
+    const catColor = getCategoryColor(category);
+    
+    const statusIcon = catBlocks > 0 ? ICONS.cross : catWarns > 0 ? ICONS.warning : ICONS.check;
+    const statusColor = catBlocks > 0 ? colors.error : catWarns > 0 ? colors.warning : colors.success;
+    
+    console.log(`  ${statusColor}${statusIcon}${c.reset} ${icon} ${c.bold}${category.padEnd(18)}${c.reset} ${catBlocks > 0 ? `${colors.error}${catBlocks} blockers${c.reset} ` : ''}${catWarns > 0 ? `${colors.warning}${catWarns} warnings${c.reset}` : ''}`);
+  }
+}
+
+function printBlockerDetails(findings, maxShow = 6) {
+  const blockers = findings.filter(f => f.severity === 'BLOCK');
+  
+  if (blockers.length === 0) return;
+  
+  printSection(`BLOCKERS (${blockers.length})`, '🚨');
+  console.log();
+  
+  for (const blocker of blockers.slice(0, maxShow)) {
+    const style = getSeverityStyle(blocker.severity);
+    const icon = getCategoryIcon(blocker.category);
+    
+    // Severity badge
+    console.log(`  ${style.bg}${c.bold} ${style.label} ${c.reset} ${icon} ${c.bold}${truncate(blocker.title, 45)}${c.reset}`);
+    
+    // Page URL
+    if (blocker.page) {
+      console.log(`  ${' '.repeat(10)} ${colors.info}${ICONS.page} ${truncate(blocker.page, 50)}${c.reset}`);
+    }
+    
+    // Reason
+    if (blocker.reason) {
+      console.log(`  ${' '.repeat(10)} ${c.dim}${truncate(blocker.reason, 50)}${c.reset}`);
+    }
+    
+    // Screenshot
+    if (blocker.screenshot) {
+      console.log(`  ${' '.repeat(10)} ${colors.accent}${ICONS.screenshot} ${truncate(blocker.screenshot, 45)}${c.reset}`);
+    }
+    
+    console.log();
+  }
+  
+  if (blockers.length > maxShow) {
+    console.log(`  ${c.dim}... and ${blockers.length - maxShow} more blockers (see full report)${c.reset}`);
+    console.log();
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// VERDICT DISPLAY
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function getVerdictConfig(blocks, warns) {
+  if (blocks === 0 && warns === 0) {
+    return {
+      verdict: 'CLEAN',
+      icon: '✅',
+      headline: 'REALITY VERIFIED',
+      tagline: 'All UI elements are responsive and functional!',
+      color: colors.success,
+      bgColor: bgRgb(0, 80, 50),
+      borderColor: rgb(0, 200, 120),
+    };
+  }
+  
+  if (blocks === 0) {
+    return {
+      verdict: 'WARN',
+      icon: '⚠️',
+      headline: 'MINOR ISSUES',
+      tagline: `${warns} warning${warns !== 1 ? 's' : ''} found - review recommended`,
+      color: colors.warning,
+      bgColor: bgRgb(80, 60, 0),
+      borderColor: rgb(200, 160, 0),
+    };
+  }
+  
+  return {
+    verdict: 'BLOCK',
+    icon: '🛑',
+    headline: 'DEAD UI DETECTED',
+    tagline: `${blocks} blocker${blocks !== 1 ? 's' : ''} must be fixed`,
+    color: colors.error,
+    bgColor: bgRgb(80, 20, 20),
+    borderColor: rgb(200, 60, 60),
+  };
+}
+
+function printVerdictCard(blocks, warns, duration) {
+  const config = getVerdictConfig(blocks, warns);
+  const w = 68;
+  
+  console.log();
+  console.log();
+  
+  // Top border
+  console.log(`  ${config.borderColor}${BOX.dTopLeft}${BOX.dHorizontal.repeat(w)}${BOX.dTopRight}${c.reset}`);
+  
+  // Empty line
+  console.log(`  ${config.borderColor}${BOX.dVertical}${c.reset}${' '.repeat(w)}${config.borderColor}${BOX.dVertical}${c.reset}`);
+  
+  // Icon and headline
+  const headlineText = `${config.icon}  ${config.headline}`;
+  const headlinePadded = padCenter(headlineText, w);
+  console.log(`  ${config.borderColor}${BOX.dVertical}${c.reset}${config.color}${c.bold}${headlinePadded}${c.reset}${config.borderColor}${BOX.dVertical}${c.reset}`);
+  
+  // Tagline
+  const taglinePadded = padCenter(config.tagline, w);
+  console.log(`  ${config.borderColor}${BOX.dVertical}${c.reset}${c.dim}${taglinePadded}${c.reset}${config.borderColor}${BOX.dVertical}${c.reset}`);
+  
+  // Empty line
+  console.log(`  ${config.borderColor}${BOX.dVertical}${c.reset}${' '.repeat(w)}${config.borderColor}${BOX.dVertical}${c.reset}`);
+  
+  // Stats row
+  const stats = `Blockers: ${blocks}  •  Warnings: ${warns}  •  Duration: ${formatDuration(duration)}`;
+  const statsPadded = padCenter(stats, w);
+  console.log(`  ${config.borderColor}${BOX.dVertical}${c.reset}${c.dim}${statsPadded}${c.reset}${config.borderColor}${BOX.dVertical}${c.reset}`);
+  
+  // Empty line
+  console.log(`  ${config.borderColor}${BOX.dVertical}${c.reset}${' '.repeat(w)}${config.borderColor}${BOX.dVertical}${c.reset}`);
+  
+  // Bottom border
+  console.log(`  ${config.borderColor}${BOX.dBottomLeft}${BOX.dHorizontal.repeat(w)}${BOX.dBottomRight}${c.reset}`);
+  
+  console.log();
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TIER WARNING DISPLAY
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function printTierWarning(tier, limits, originalMaxPages, appliedMaxPages, verifyAuthRequested, verifyAuthApplied) {
+  if (tier !== 'free') return;
+  
+  console.log();
+  console.log(`  ${colors.warning}${ICONS.warning}${c.reset} ${c.bold}FREE TIER: Preview Mode${c.reset}`);
+  
+  if (originalMaxPages > appliedMaxPages) {
+    console.log(`     ${c.dim}Pages capped:${c.reset} ${appliedMaxPages} ${c.dim}(requested ${originalMaxPages})${c.reset}`);
+  }
+  
+  if (verifyAuthRequested && !verifyAuthApplied) {
+    console.log(`     ${c.dim}Auth boundary:${c.reset} ${colors.error}disabled${c.reset} ${c.dim}(requires STARTER+)${c.reset}`);
+  }
+  
+  console.log(`     ${colors.accent}Upgrade:${c.reset} ${c.dim}https://vibecheckai.dev/pricing${c.reset}`);
+  console.log();
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELP DISPLAY
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function printHelp(opts = {}) {
+  if (shouldShowBanner(opts)) {
+    console.log(BANNER_FULL);
+  }
+  console.log(`
+  ${c.bold}Usage:${c.reset} vibecheck reality --url <url> [options]
+
+  ${c.bold}Runtime UI Verification${c.reset} — Prove your UI actually works.
+
+  ${c.bold}Two-Pass Architecture:${c.reset}
+    ${colors.anon}${ICONS.anon} Pass A (Anon)${c.reset}    Crawl without auth, record protected routes
+    ${colors.auth}${ICONS.auth} Pass B (Auth)${c.reset}    Re-crawl with session, verify access
+
+  ${c.bold}What It Detects:${c.reset}
+    ${colors.deadUI}${ICONS.deadUI} Dead UI${c.reset}        Clicks that do nothing
+    ${colors.authCoverage}${ICONS.shield} Auth Gaps${c.reset}      Protected routes accessible anonymously
+    ${colors.httpError}${ICONS.http} HTTP Errors${c.reset}   4xx/5xx responses
+
+  ${c.bold}Options:${c.reset}
+    ${colors.accent}--url, -u <url>${c.reset}           Base URL for testing ${c.dim}(required)${c.reset}
+    ${colors.accent}--auth <email:pass>${c.reset}      Login credentials for auth verification
+    ${colors.accent}--storage-state <path>${c.reset}   Playwright session state file
+    ${colors.accent}--save-storage-state <p>${c.reset} Save session after login
+    ${colors.accent}--truthpack <path>${c.reset}       Custom truthpack path
+    ${colors.accent}--verify-auth${c.reset}            Enable two-pass auth verification
+    ${colors.accent}--headed${c.reset}                 Run browser visible ${c.dim}(for debugging)${c.reset}
+    ${colors.accent}--danger${c.reset}                 Allow clicking destructive elements
+    ${colors.accent}--max-pages <n>${c.reset}          Max pages to crawl ${c.dim}(default: 18)${c.reset}
+    ${colors.accent}--max-depth <n>${c.reset}          Max crawl depth ${c.dim}(default: 2)${c.reset}
+    ${colors.accent}--timeout <ms>${c.reset}           Page timeout ${c.dim}(default: 15000)${c.reset}
+    ${colors.accent}--help, -h${c.reset}               Show this help
+
+  ${c.bold}Visual Artifacts:${c.reset}
+    ${colors.accent}--video, --record-video${c.reset}  Record video of browser sessions
+    ${colors.accent}--trace, --record-trace${c.reset}  Record Playwright trace (viewable in trace.playwright.dev)
+    ${colors.accent}--har, --record-har${c.reset}      Record HAR network traffic
+
+  ${c.bold}Flakiness Reduction:${c.reset}
+    ${colors.accent}--retries <n>${c.reset}            Retry failed nav/clicks ${c.dim}(default: 2)${c.reset}
+    ${colors.accent}--stable-wait <ms>${c.reset}       Wait after actions ${c.dim}(default: 500ms)${c.reset}
+    ${colors.accent}--stability-runs <n>${c.reset}     Run N times for stability check ${c.dim}(default: 1)${c.reset}
+    ${colors.accent}--flaky-threshold <f>${c.reset}    Min occurrence rate to report ${c.dim}(default: 0.66)${c.reset}
+
+  ${c.bold}Tier Limits:${c.reset}
+    ${c.dim}FREE${c.reset}      5 pages, no auth boundary
+    ${c.dim}STARTER${c.reset}   Full budgets + basic auth
+    ${c.dim}PRO${c.reset}       Advanced auth (multi-role)
+
+  ${c.bold}Exit Codes:${c.reset}
+    ${colors.success}0${c.reset}  CLEAN — No issues found
+    ${colors.warning}1${c.reset}  WARN  — Warnings found
+    ${colors.error}2${c.reset}  BLOCK — Blockers found (dead UI, auth gaps)
+
+  ${c.bold}Examples:${c.reset}
+    ${c.dim}# Basic crawl${c.reset}
+    vibecheck reality --url http://localhost:3000
+
+    ${c.dim}# With auth verification${c.reset}
+    vibecheck reality --url http://localhost:3000 --verify-auth --auth user@test.com:pass
+
+    ${c.dim}# Debug mode (visible browser)${c.reset}
+    vibecheck reality --url http://localhost:3000 --headed
+
+    ${c.dim}# Allow destructive actions${c.reset}
+    vibecheck reality --url http://localhost:3000 --danger
+  `);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// UTILITY FUNCTIONS (preserved from original)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function stamp() {
+  const d = new Date();
+  const z = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${z(d.getMonth() + 1)}${z(d.getDate())}_${z(d.getHours())}${z(d.getMinutes())}${z(d.getSeconds())}`;
+}
+
+function sha1(s) {
+  return crypto.createHash("sha1").update(String(s)).digest("hex");
+}
+
+function normalizeUrl(u) {
+  try {
+    const url = new URL(u);
+    url.hash = "";
+    return url.toString();
+  } catch {
+    return u;
+  }
+}
+
+function sameOrigin(a, b) {
+  try {
+    return new URL(a).origin === new URL(b).origin;
+  } catch {
+    return false;
+  }
+}
+
+function pathFromUrl(u) {
+  try {
+    return new URL(u).pathname || "/";
+  } catch {
+    return "/";
+  }
+}
+
+function looksRisky(text) {
+  const t = String(text || "").toLowerCase();
+  return /\b(delete|remove|destroy|wipe|purge|drop|cancel\s+plan|unsubscribe|terminate)\b/.test(t);
+}
+
+function looksAuthAction(text) {
+  const t = String(text || "").toLowerCase();
+  return /\b(logout|sign\s*out)\b/.test(t);
+}
+
+function loadTruthpack(repoRoot, truthpackRel) {
+  const rel = truthpackRel || path.join(".vibecheck", "truth", "truthpack.json");
+  const abs = path.isAbsolute(rel) ? rel : path.join(repoRoot, rel);
+  if (!fs.existsSync(abs)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(abs, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function compileNextMatcher(pattern) {
+  const p = String(pattern || "").trim();
+  if (!p) return null;
+  const norm = p.startsWith("/") ? p : `/${p}`;
+  const esc = norm.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  if (norm.includes(":path*")) {
+    const base = esc.replace(/\\:path\\\*/g, "");
+    return new RegExp(`^${base}(\\/.*)?$`, "i");
+  }
+  return new RegExp(`^${esc}$`, "i");
+}
+
+function getProtectedMatchersFromTruthpack(truthpack) {
+  const patterns = truthpack?.auth?.nextMatcherPatterns || [];
+  const out = [];
+  for (const p of patterns) {
+    const rx = compileNextMatcher(p);
+    if (rx) out.push({ pattern: p, rx });
+  }
+  return out;
+}
+
+async function isLoginPage(page) {
+  try {
+    return await page.evaluate(() => {
+      const hasPass = !!document.querySelector("input[type='password']");
+      const txt = (document.body?.innerText || "").toLowerCase();
+      const signInWords = /(sign in|log in|login|welcome back|forgot password)/.test(txt);
+      const urlLooks = /(login|signin|auth)/.test(location.pathname.toLowerCase());
+      return hasPass || signInWords || urlLooks;
+    });
+  } catch {
+    return false;
+  }
+}
+
+async function pageSignature(page) {
+  return page.evaluate(() => {
+    const c = document.querySelectorAll("a,button,input,select,textarea,[role='button']").length;
+    const t = document.body?.innerText?.length || 0;
+    return `${location.href}|${c}|${t}`;
+  });
+}
+
+async function clickOutcome(page, locator, opts = {}) {
+  const beforeSig = await pageSignature(page);
+  const beforeUrl = page.url();
+  const beforeReq = opts.reqCounter.value;
+
+  // Enhanced mutation observer that detects more changes including:
+  // - DOM structure changes (childList, subtree)
+  // - Attribute changes (class, style, aria-*, data-*)
+  // - CSS visibility/display changes
+  const domPromise = page.evaluate(() => {
+    return new Promise((resolve) => {
+      let changeCount = 0;
+      let attributeChanges = [];
+      
+      const obs = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          changeCount++;
+          if (mutation.type === 'attributes') {
+            attributeChanges.push({
+              attr: mutation.attributeName,
+              target: mutation.target.tagName
+            });
+          }
+        }
+      });
+      
+      obs.observe(document.documentElement, { 
+        childList: true, 
+        subtree: true, 
+        attributes: true,
+        attributeFilter: ['class', 'style', 'aria-expanded', 'aria-hidden', 'aria-selected', 
+                          'data-state', 'hidden', 'open', 'data-open', 'data-closed']
+      });
+      
+      setTimeout(() => { 
+        try { obs.disconnect(); } catch {} 
+        resolve({ 
+          changed: changeCount > 0, 
+          changeCount,
+          attributeChanges: attributeChanges.slice(0, 10) // Limit for performance
+        }); 
+      }, 900);
+    });
+  });
+
+  // Also track CSS visibility changes via computed styles
+  const beforeVisibility = await page.evaluate(() => {
+    const modals = document.querySelectorAll('[role="dialog"], .modal, .dropdown, .popover, [data-state]');
+    return Array.from(modals).slice(0, 20).map(el => ({
+      visible: getComputedStyle(el).display !== 'none' && getComputedStyle(el).visibility !== 'hidden',
+      state: el.getAttribute('data-state')
+    }));
+  }).catch(() => []);
+
+  const navPromise = page.waitForNavigation({ timeout: 1200 }).then(() => true).catch(() => false);
+  const clickRes = await locator.click({ timeout: 1200 }).then(() => ({ ok: true })).catch((e) => ({ ok: false, error: String(e?.message || e) }));
+
+  const navRes = await navPromise;
+  const domRes = await domPromise;
+  await page.waitForTimeout(300); // Slightly longer wait for CSS transitions
+
+  const afterSig = await pageSignature(page);
+  const afterUrl = page.url();
+  
+  // Check CSS visibility changes
+  const afterVisibility = await page.evaluate(() => {
+    const modals = document.querySelectorAll('[role="dialog"], .modal, .dropdown, .popover, [data-state]');
+    return Array.from(modals).slice(0, 20).map(el => ({
+      visible: getComputedStyle(el).display !== 'none' && getComputedStyle(el).visibility !== 'hidden',
+      state: el.getAttribute('data-state')
+    }));
+  }).catch(() => []);
+  
+  // Detect visibility state changes (modal open/close, dropdown toggle, etc.)
+  const visibilityChanged = JSON.stringify(beforeVisibility) !== JSON.stringify(afterVisibility);
+
+  return {
+    clickOk: clickRes.ok,
+    clickError: clickRes.error || null,
+    navHappened: !!navRes,
+    urlChanged: normalizeUrl(afterUrl) !== normalizeUrl(beforeUrl),
+    domChanged: !!domRes?.changed || afterSig !== beforeSig,
+    visibilityChanged, // NEW: Tracks CSS visibility/state changes
+    changeCount: domRes?.changeCount || 0, // NEW: Number of mutations detected
+    reqDelta: Math.max(0, opts.reqCounter.value - beforeReq),
+    beforeUrl,
+    afterUrl
+  };
+}
+
+async function collectLinks(page, baseUrl) {
+  const links = await page.evaluate(() => Array.from(document.querySelectorAll("a[href]")).map(a => a.getAttribute("href")).filter(Boolean));
+  return links.map(href => { try { return new URL(href, baseUrl).toString(); } catch { return null; } }).filter(Boolean);
+}
+
+async function collectInteractives(page) {
+  return page.evaluate(() => {
+    const nodes = Array.from(document.querySelectorAll("button, a[href], input[type='submit'], [role='button'], [onclick]"));
+    return nodes.slice(0, 80).map((el, idx) => {
+      const text = (el.getAttribute("aria-label") || el.innerText || "").trim().slice(0, 80).toLowerCase();
+      const classList = Array.from(el.classList).join(' ').toLowerCase();
+      const id = (el.id || "").toLowerCase();
+      const dataTestId = el.getAttribute("data-testid") || "";
+      
+      // Detect element context for false positive reduction
+      const isInsideModal = !!el.closest('[role="dialog"], [role="alertdialog"], .modal, .dialog, [data-radix-dialog-content]');
+      const isInsideDropdown = !!el.closest('[role="menu"], [role="listbox"], .dropdown, .popover, [data-radix-menu-content]');
+      const isInsideAccordion = !!el.closest('[role="region"], .accordion, [data-state], [data-radix-accordion-content]');
+      const isInsideTooltip = !!el.closest('[role="tooltip"], .tooltip');
+      
+      // Detect button intent for false positive reduction
+      const looksLikeClose = /close|dismiss|cancel|x|×|✕|✖/i.test(text) || /close|dismiss/i.test(classList);
+      const looksLikeToggle = /toggle|expand|collapse|show|hide|menu|hamburger|more/i.test(text) || /toggle|accordion|collaps/i.test(classList);
+      const looksLikeCopy = /copy|clipboard/i.test(text) || /copy/i.test(classList);
+      const looksLikeTheme = /theme|dark|light|mode/i.test(text) || /theme/i.test(classList);
+      const looksLikeTab = el.getAttribute("role") === "tab" || /tab/i.test(classList);
+      const looksLikeSort = /sort|order|filter/i.test(text);
+      
+      // Elements that legitimately may not trigger detectable changes
+      const isLikelyFalsePositive = looksLikeClose || looksLikeToggle || looksLikeCopy || 
+                                     looksLikeTheme || looksLikeTab || looksLikeSort ||
+                                     isInsideModal || isInsideDropdown || isInsideTooltip;
+      
+      return {
+        idx,
+        tag: el.tagName.toLowerCase(),
+        role: el.getAttribute("role") || "",
+        href: el.tagName === "A" ? el.getAttribute("href") || "" : "",
+        text: (el.getAttribute("aria-label") || el.innerText || "").trim().slice(0, 80),
+        id: el.id || "",
+        disabled: !!(el.disabled || el.getAttribute("aria-disabled") === "true"),
+        key: `${el.tagName}|${el.id}|${idx}`,
+        // Context for false positive reduction
+        context: {
+          isInsideModal,
+          isInsideDropdown,
+          isInsideAccordion,
+          isInsideTooltip,
+          looksLikeClose,
+          looksLikeToggle,
+          looksLikeCopy,
+          looksLikeTheme,
+          looksLikeTab,
+          isLikelyFalsePositive
+        }
+      };
+    });
+  });
+}
+
+async function attemptLogin(page, { auth }) {
+  if (!auth) return { did: false, ok: false };
+  const [email, pass] = String(auth).split(":");
+  if (!email || !pass) return { did: false, ok: false };
+
+  try {
+    const emailLoc = page.locator("input[type='email'], input[name*='email' i], input[placeholder*='email' i]").first();
+    const passLoc = page.locator("input[type='password']").first();
+    if ((await emailLoc.count()) === 0 || (await passLoc.count()) === 0) return { did: false, ok: false };
+
+    await emailLoc.fill(email, { timeout: 1200 });
+    await passLoc.fill(pass, { timeout: 1200 });
+
+    const submit = page.locator("button[type='submit'], input[type='submit']").first();
+    const fallback = page.locator("button:has-text('Log in'), button:has-text('Sign in')").first();
+    const before = page.url();
+
+    if ((await submit.count()) > 0) await submit.click({ timeout: 1200 });
+    else if ((await fallback.count()) > 0) await fallback.click({ timeout: 1200 });
+    else return { did: true, ok: false };
+
+    await page.waitForLoadState("networkidle", { timeout: 6000 }).catch(() => {});
+    const stillLogin = await isLoginPage(page);
+    return { did: true, ok: normalizeUrl(page.url()) !== normalizeUrl(before) || !stillLogin };
+  } catch {
+    return { did: true, ok: false };
+  }
+}
+
+async function runSinglePass({ label, baseUrl, context, shotsDir, danger, maxPages, maxDepth, timeoutMs, root, onProgress, retries = 2, stableWait = 500 }) {
+  const page = await context.newPage();
+  page.setDefaultTimeout(timeoutMs);
+  
+  // Helper for flaky-resistant navigation with retries
+  async function safeGoto(targetUrl, opts = {}) {
+    for (let attempt = 1; attempt <= retries; attempt++) {
+      try {
+        const res = await page.goto(targetUrl, { waitUntil: "domcontentloaded", ...opts });
+        // Wait for stability to reduce flakiness
+        if (stableWait > 0) {
+          await page.waitForTimeout(stableWait);
+        }
+        await page.waitForLoadState("networkidle", { timeout: 6000 }).catch(() => {});
+        return res;
+      } catch (err) {
+        if (attempt === retries) throw err;
+        await page.waitForTimeout(500 * attempt); // Exponential backoff
+      }
+    }
+    return null;
+  }
+  
+  // Helper for flaky-resistant clicks with retries
+  async function safeClick(locator, opts = {}) {
+    for (let attempt = 1; attempt <= retries; attempt++) {
+      try {
+        await locator.click({ timeout: timeoutMs / 2, ...opts });
+        if (stableWait > 0) {
+          await page.waitForTimeout(stableWait);
+        }
+        return { success: true };
+      } catch (err) {
+        if (attempt === retries) return { success: false, error: err.message };
+        await page.waitForTimeout(300 * attempt);
+      }
+    }
+    return { success: false, error: 'Max retries exceeded' };
+  }
+
+  const reqCounter = { value: 0 };
+  const netErrors = [];
+  const consoleErrors = [];
+  const findings = [];
+  const pagesVisited = [];
+  const fakeDataDetections = []; // Track fake data detections
+  const processedUrls = new Set(); // Avoid duplicate detections
+
+  page.on("requestfinished", () => { reqCounter.value += 1; });
+  page.on("requestfailed", (req) => { netErrors.push({ url: req.url(), failure: req.failure()?.errorText || "unknown" }); });
+  page.on("console", (msg) => { if (msg.type() === "error") consoleErrors.push({ text: msg.text().slice(0, 500) }); });
+  page.on("pageerror", (err) => { consoleErrors.push({ text: String(err?.message || err).slice(0, 500) }); });
+  
+  // Intercept responses for fake data detection
+  page.on("response", async (response) => {
+    try {
+      const url = response.url();
+      const status = response.status();
+      
+      // Skip already processed URLs and static assets
+      if (processedUrls.has(url)) return;
+      if (/\.(js|css|png|jpg|svg|ico|woff|woff2|ttf|gif|webp)(\?|$)/i.test(url)) return;
+      
+      // Only check API-like endpoints
+      if (!url.includes('/api/') && !url.includes('/graphql') && !url.includes('/trpc') && 
+          !response.headers()['content-type']?.includes('application/json')) {
+        return;
+      }
+      
+      processedUrls.add(url);
+      
+      let body = '';
+      try {
+        body = await response.text();
+      } catch {
+        // Some responses can't be read
+      }
+      
+      const detections = classifyNetworkTraffic(url, body, status);
+      if (detections && detections.length > 0) {
+        fakeDataDetections.push(...detections);
+      }
+    } catch {
+      // Ignore errors in response processing
+    }
+  });
+
+  const visited = new Set();
+  const queue = [{ url: baseUrl, depth: 0 }];
+
+  while (queue.length && pagesVisited.length < maxPages) {
+    const item = queue.shift();
+    if (!item) break;
+
+    const targetUrl = normalizeUrl(item.url);
+    if (!sameOrigin(baseUrl, targetUrl) || visited.has(targetUrl)) continue;
+    if (!danger && looksAuthAction(targetUrl)) continue;
+
+    visited.add(targetUrl);
+
+    // Progress callback
+    if (onProgress) {
+      onProgress({ page: pagesVisited.length + 1, maxPages, url: targetUrl });
+    }
+
+    const res = await safeGoto(targetUrl).catch(() => null);
+
+    const status = res ? res.status() : null;
+    const loginLike = await isLoginPage(page);
+    pagesVisited.push({ url: page.url(), depth: item.depth, status, loginLike });
+
+    if (status && status >= 400) {
+      const shot = path.join(shotsDir, `${label}_http_${status}_${sha1(targetUrl)}.png`);
+      await page.screenshot({ path: shot, fullPage: true }).catch(() => {});
+      findings.push({
+        id: `R_${label}_HTTP_${status}_${sha1(targetUrl).slice(0, 8)}`,
+        severity: status >= 500 ? "BLOCK" : "WARN",
+        category: "DeadUI",
+        title: `[${label}] HTTP ${status} at ${targetUrl}`,
+        page: targetUrl,
+        reason: "Navigation reached an error status",
+        screenshot: path.relative(root, shot).replace(/\\/g, "/")
+      });
+    }
+
+    if (item.depth < maxDepth) {
+      for (const l of await collectLinks(page, baseUrl)) {
+        const abs = normalizeUrl(l);
+        if (sameOrigin(baseUrl, abs) && !visited.has(abs) && (danger || !looksAuthAction(abs))) {
+          queue.push({ url: abs, depth: item.depth + 1 });
+        }
+      }
+    }
+
+    for (const el of await collectInteractives(page)) {
+      if (el.disabled || (looksRisky(el.text) && !danger)) continue;
+
+      let locator;
+      try {
+        if (el.tag === "a") locator = page.locator("a[href]").nth(el.idx);
+        else if (el.tag === "button") locator = page.locator("button").nth(el.idx);
+        else if (el.role === "button") locator = page.locator("[role='button']").nth(el.idx);
+        else continue;
+      } catch { continue; }
+
+      const out = await clickOutcome(page, locator, { reqCounter });
+
+      if (!out.clickOk) {
+        // Skip click failures for elements that are likely intentionally not clickable
+        // (e.g., visually hidden close buttons, buttons behind overlays)
+        if (el.context?.isLikelyFalsePositive) continue;
+        
+        const shot = path.join(shotsDir, `${label}_click_fail_${sha1(el.key)}.png`);
+        await page.screenshot({ path: shot }).catch(() => {});
+        findings.push({
+          id: `R_${label}_CLICK_FAIL_${sha1(el.key).slice(0, 8)}`,
+          severity: "WARN",
+          category: "DeadUI",
+          title: `[${label}] Click failed: ${el.text || el.tag}`,
+          page: page.url(),
+          reason: out.clickError || "click failed",
+          screenshot: path.relative(root, shot).replace(/\\/g, "/")
+        });
+        continue;
+      }
+
+      // Enhanced Dead UI detection with false positive reduction
+      // An element is considered "dead" if clicking produced NO observable effect:
+      // - No navigation
+      // - No URL change  
+      // - No DOM mutations
+      // - No CSS visibility/state changes
+      // - No network requests
+      const noEffect = !out.navHappened && !out.urlChanged && !out.domChanged && 
+                       !out.visibilityChanged && out.reqDelta === 0;
+      
+      if (noEffect) {
+        // Apply false positive reduction based on element context
+        const ctx = el.context || {};
+        
+        // Skip elements that are KNOWN to not produce observable changes
+        // These are legitimate UI patterns that don't need fixes
+        if (ctx.looksLikeClose && ctx.isInsideModal) {
+          // Close button inside a modal - the modal itself may have closed
+          continue;
+        }
+        if (ctx.looksLikeCopy) {
+          // Copy buttons work via clipboard API, no DOM change expected
+          continue;
+        }
+        if (ctx.looksLikeTheme) {
+          // Theme toggles may only change CSS custom properties
+          continue;
+        }
+        
+        // Downgrade severity for likely false positives
+        // Instead of BLOCK, use WARN for elements in contexts that commonly have no-op behavior
+        let severity = "BLOCK";
+        let reason = "Click produced no navigation, no network activity, and no DOM change";
+        
+        if (ctx.isLikelyFalsePositive) {
+          severity = "WARN";
+          reason = `Click produced no observable change (possible false positive: ${
+            ctx.looksLikeToggle ? 'toggle button' : 
+            ctx.looksLikeTab ? 'tab element' : 
+            ctx.looksLikeSort ? 'sort control' :
+            ctx.isInsideDropdown ? 'inside dropdown' :
+            ctx.isInsideAccordion ? 'inside accordion' :
+            'contextual element'
+          })`;
+        }
+        
+        // Always skip tooltip-related elements as they are purely visual
+        if (ctx.isInsideTooltip) continue;
+        
+        const shot = path.join(shotsDir, `${label}_dead_${sha1(el.key)}.png`);
+        await page.screenshot({ path: shot }).catch(() => {});
+        findings.push({
+          id: `R_${label}_DEAD_${sha1(el.key).slice(0, 8)}`,
+          severity,
+          category: "DeadUI",
+          title: `[${label}] Dead UI: ${el.text || el.tag}`,
+          page: page.url(),
+          reason,
+          screenshot: path.relative(root, shot).replace(/\\/g, "/"),
+          confidence: ctx.isLikelyFalsePositive ? 0.5 : 0.9, // Add confidence score
+          context: ctx // Include context for debugging
+        });
+      }
+    }
+  }
+
+  await page.close();
+  
+  // Convert fake data detections to findings with confidence-based filtering
+  const seenFakeUrls = new Set();
+  
+  // Sort by confidence (highest first) to prioritize most reliable detections
+  const sortedDetections = [...fakeDataDetections].sort((a, b) => 
+    (b.confidence || 0.5) - (a.confidence || 0.5)
+  );
+  
+  for (const detection of sortedDetections) {
+    // Dedupe by URL + type + pattern to avoid near-duplicates
+    const key = `${detection.url}:${detection.type}:${detection.pattern || ''}`;
+    if (seenFakeUrls.has(key)) continue;
+    seenFakeUrls.add(key);
+    
+    // Skip very low confidence detections (likely false positives)
+    const confidence = detection.confidence || 0.5;
+    if (confidence < 0.50) continue;
+    
+    // Downgrade severity for medium confidence detections
+    let severity = detection.severity;
+    if (confidence < 0.70 && severity === 'BLOCK') {
+      severity = 'WARN';
+    }
+    
+    findings.push({
+      id: `R_${label}_FAKE_${sha1(key).slice(0, 8)}`,
+      severity,
+      category: detection.type === 'fake-domain' ? 'FakeDomain' : 
+                detection.type === 'fake-response' ? 'FakeResponse' : 'MockStatus',
+      title: `[${label}] Fake Data: ${detection.evidence}`,
+      page: detection.url,
+      reason: detection.evidence,
+      confidence, // Include confidence score for transparency
+      pattern: detection.pattern // Include pattern for debugging
+    });
+  }
+  
+  return { 
+    label, 
+    pagesVisited, 
+    findings, 
+    consoleErrors: consoleErrors.slice(0, 50), 
+    networkErrors: netErrors.slice(0, 50),
+    fakeDataDetections: fakeDataDetections.slice(0, 100)
+  };
+}
+
+function buildAuthCoverageFindings({ baseUrl, matchers, anonPass, authPass }) {
+  const findings = [];
+  const anonByPath = new Map((anonPass.pagesVisited || []).map(p => [pathFromUrl(p.url), p]));
+  const authByPath = new Map((authPass?.pagesVisited || []).map(p => [pathFromUrl(p.url), p]));
+
+  for (const [pathKey, anon] of anonByPath) {
+    const isProtected = matchers.some(m => m.rx.test(pathKey));
+    if (!isProtected) continue;
+
+    const anonLooksBlocked = anon.loginLike || anon.status === 401 || anon.status === 403;
+    const authed = authByPath.get(pathKey);
+    const authedLooksBlocked = authed?.loginLike || authed?.status === 401 || authed?.status === 403;
+
+    if (!anonLooksBlocked) {
+      findings.push({
+        id: `R_AUTH_ANON_ACCESS_${sha1(pathKey).slice(0, 8)}`,
+        severity: "BLOCK",
+        category: "AuthCoverage",
+        title: `Protected route reachable anonymously: ${pathKey}`,
+        page: new URL(pathKey, baseUrl).toString(),
+        reason: "Matcher marks route protected, but anon session did not redirect or deny."
+      });
+    }
+
+    if (authed && authedLooksBlocked) {
+      findings.push({
+        id: `R_AUTH_BLOCKED_${sha1(pathKey).slice(0, 8)}`,
+        severity: "BLOCK",
+        category: "AuthCoverage",
+        title: `Protected route blocked after login: ${pathKey}`,
+        page: new URL(pathKey, baseUrl).toString(),
+        reason: "Authed session still looks like login/401/403 on a protected route."
+      });
+    }
+  }
+
+  return findings;
+}
+
+function coverageFromTruthpack({ truthpack, visitedUrls }) {
+  if (!truthpack) return null;
+  const refs = truthpack?.routes?.clientRefs || [];
+  const uiPaths = new Set(refs.map(r => r?.path || pathFromUrl(r?.url || r)).filter(Boolean));
+  const visitedPaths = new Set(visitedUrls.map(pathFromUrl));
+  const total = uiPaths.size;
+  const hit = Array.from(uiPaths).filter(p => visitedPaths.has(p)).length;
+  return { total, hit, percent: total ? Math.round((hit / total) * 100) : 0, missed: Array.from(uiPaths).filter(p => !visitedPaths.has(p)).slice(0, 50) };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// REPLAY DATA BUILDERS (for API/dashboard)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Build timeline events from pass results for replay
+ */
+function buildTimeline(anonPass, authPass) {
+  const timeline = [];
+  const baseTimestamp = Date.now();
+  
+  // Add anon pass pages as timeline events
+  if (anonPass?.pagesVisited) {
+    for (let i = 0; i < anonPass.pagesVisited.length; i++) {
+      const page = anonPass.pagesVisited[i];
+      timeline.push({
+        action: 'navigate',
+        url: page.url,
+        selector: null,
+        timestamp: new Date(baseTimestamp + (i * 1000)).toISOString(),
+        screenshot: null,
+        pass: 'anon',
+        status: page.status,
+      });
+    }
+  }
+  
+  // Add auth pass pages
+  if (authPass?.pagesVisited) {
+    const offset = (anonPass?.pagesVisited?.length || 0) * 1000;
+    for (let i = 0; i < authPass.pagesVisited.length; i++) {
+      const page = authPass.pagesVisited[i];
+      timeline.push({
+        action: 'navigate',
+        url: page.url,
+        selector: null,
+        timestamp: new Date(baseTimestamp + offset + (i * 1000)).toISOString(),
+        screenshot: null,
+        pass: 'auth',
+        status: page.status,
+      });
+    }
+  }
+  
+  return timeline;
+}
+
+/**
+ * Build network timeline from pass results
+ */
+function buildNetworkTimeline(anonPass, authPass) {
+  const network = [];
+  const baseTimestamp = Date.now();
+  let idx = 0;
+  
+  // Extract network requests from page visits
+  if (anonPass?.pagesVisited) {
+    for (const page of anonPass.pagesVisited) {
+      network.push({
+        method: 'GET',
+        url: page.url,
+        status: page.status || 200,
+        timestamp: new Date(baseTimestamp + (idx++ * 500)).toISOString(),
+      });
+    }
+  }
+  
+  // Add network errors as requests
+  if (anonPass?.networkErrors) {
+    for (const err of anonPass.networkErrors) {
+      network.push({
+        method: 'GET',
+        url: err.url,
+        status: 0,
+        timestamp: new Date(baseTimestamp + (idx++ * 500)).toISOString(),
+        error: err.failure,
+      });
+    }
+  }
+  
+  if (authPass?.networkErrors) {
+    for (const err of authPass.networkErrors) {
+      network.push({
+        method: 'GET',
+        url: err.url,
+        status: 0,
+        timestamp: new Date(baseTimestamp + (idx++ * 500)).toISOString(),
+        error: err.failure,
+      });
+    }
+  }
+  
+  return network;
+}
+
+/**
+ * Build screenshots list from findings
+ */
+function buildScreenshotsList(anonPass, authPass, root) {
+  const screenshots = [];
+  const allFindings = [...(anonPass?.findings || []), ...(authPass?.findings || [])];
+  
+  for (const finding of allFindings) {
+    if (finding.screenshot) {
+      screenshots.push({
+        url: finding.page || '',
+        timestamp: new Date().toISOString(),
+        path: finding.screenshot,
+      });
+    }
+  }
+  
+  return screenshots;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// FLAKINESS & STABILITY VERIFICATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Aggregate findings from multiple stability runs
+ * Only returns findings that appear in at least `threshold` of runs
+ * @param {Array<Array<Object>>} runFindings - Array of findings arrays from each run
+ * @param {number} threshold - Minimum occurrence rate (0-1) to include a finding
+ * @returns {Array<Object>} Deduplicated findings with flakiness scores
+ */
+function aggregateStabilityFindings(runFindings, threshold = 0.66) {
+  const totalRuns = runFindings.length;
+  if (totalRuns === 0) return [];
+  if (totalRuns === 1) return runFindings[0] || [];
+  
+  // Group findings by their unique key (category + normalized title/reason)
+  const findingCounts = new Map();
+  
+  for (const findings of runFindings) {
+    for (const finding of findings) {
+      // Create a stable key for deduplication
+      const key = `${finding.category}|${finding.title?.replace(/\[ANON\]|\[AUTH\]/g, '').trim()}|${finding.page || ''}`;
+      
+      if (!findingCounts.has(key)) {
+        findingCounts.set(key, {
+          finding: { ...finding },
+          count: 0,
+          occurrences: []
+        });
+      }
+      
+      const entry = findingCounts.get(key);
+      entry.count++;
+      entry.occurrences.push(finding);
+    }
+  }
+  
+  // Filter to findings that meet the threshold and add flakiness score
+  const aggregated = [];
+  
+  for (const [key, data] of findingCounts) {
+    const occurrenceRate = data.count / totalRuns;
+    
+    if (occurrenceRate >= threshold) {
+      // Calculate flakiness score (1 = always occurs, 0 = never)
+      const flakinessScore = 1 - occurrenceRate;
+      
+      // Merge the finding with flakiness metadata
+      const aggregatedFinding = {
+        ...data.finding,
+        stability: {
+          occurrenceRate: Math.round(occurrenceRate * 100) / 100,
+          appearedInRuns: data.count,
+          totalRuns,
+          flakinessScore: Math.round(flakinessScore * 100) / 100,
+          isFlaky: flakinessScore > 0.1, // More than 10% variance = flaky
+        }
+      };
+      
+      // If finding appeared in all runs, it's stable
+      // If it appeared in some runs, mark as potentially flaky
+      if (data.count < totalRuns) {
+        aggregatedFinding.reason = `${aggregatedFinding.reason || ''} (appeared ${data.count}/${totalRuns} runs)`.trim();
+      }
+      
+      aggregated.push(aggregatedFinding);
+    }
+  }
+  
+  return aggregated;
+}
+
+/**
+ * Print stability verification results
+ */
+function printStabilityResults(totalRuns, stableFindings, filteredCount) {
+  if (totalRuns <= 1) return;
+  
+  console.log();
+  console.log(`  ${colors.info}${ICONS.target}${c.reset} ${c.bold}Stability Verification${c.reset}`);
+  console.log(`     ${c.dim}Total runs:${c.reset}       ${totalRuns}`);
+  console.log(`     ${c.dim}Stable findings:${c.reset}  ${stableFindings} ${c.dim}(appeared in majority of runs)${c.reset}`);
+  
+  if (filteredCount > 0) {
+    console.log(`     ${c.dim}Filtered (flaky):${c.reset} ${colors.success}${filteredCount}${c.reset} ${c.dim}(inconsistent across runs)${c.reset}`);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MAIN REALITY FUNCTION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+async function runReality(argsOrOpts = {}) {
+  // Handle array args from CLI
+  let globalOpts = { noBanner: false, json: false, quiet: false, ci: false };
+  if (Array.isArray(argsOrOpts)) {
+    const { flags } = parseGlobalFlags(argsOrOpts);
+    globalOpts = { ...globalOpts, ...flags };
+    if (globalOpts.help) {
+      printHelp(globalOpts);
+      return 0;
+    }
+    // Parse args to options
+    const getArg = (flags) => {
+      for (const f of flags) {
+        const idx = argsOrOpts.indexOf(f);
+        if (idx !== -1 && idx < argsOrOpts.length - 1) return argsOrOpts[idx + 1];
+      }
+      return undefined;
+    };
+    argsOrOpts = {
+      url: getArg(["--url", "-u"]),
+      auth: getArg(["--auth"]),
+      storageState: getArg(["--storage-state"]),
+      saveStorageState: getArg(["--save-storage-state"]),
+      truthpack: getArg(["--truthpack"]),
+      verifyAuth: argsOrOpts.includes("--verify-auth"),
+      headed: argsOrOpts.includes("--headed"),
+      danger: argsOrOpts.includes("--danger"),
+      // Visual artifacts options
+      recordVideo: argsOrOpts.includes("--record-video") || argsOrOpts.includes("--video"),
+      recordTrace: argsOrOpts.includes("--record-trace") || argsOrOpts.includes("--trace"),
+      recordHar: argsOrOpts.includes("--record-har") || argsOrOpts.includes("--har"),
+      // Flakiness reduction options
+      retries: parseInt(getArg(["--retries"]) || "2", 10),
+      stableWait: parseInt(getArg(["--stable-wait"]) || "500", 10),
+      maxPages: parseInt(getArg(["--max-pages"]) || "18", 10),
+      maxDepth: parseInt(getArg(["--max-depth"]) || "2", 10),
+      timeoutMs: parseInt(getArg(["--timeout"]) || "15000", 10),
+      ...globalOpts,
+    };
+  }
+
+  let {
+    repoRoot,
+    url,
+    auth,
+    storageState,
+    saveStorageState,
+    truthpack,
+    verifyAuth = false,
+    headed = false,
+    maxPages = 18,
+    maxDepth = 2,
+    danger = false,
+    timeoutMs = 15000,
+    // Visual artifacts (videos, traces, HAR)
+    recordVideo = false,
+    recordTrace = false,
+    recordHar = false,
+    // Flakiness reduction
+    retries = 2,
+    stableWait = 500,
+    stabilityRuns = 1,
+    flakyThreshold = 0.66
+  } = argsOrOpts;
+
+  if (!url) {
+    printHelp(argsOrOpts);
+    console.log(`\n  ${colors.error}${ICONS.cross}${c.reset} ${c.bold}Error:${c.reset} --url is required\n`);
+    return 1;
+  }
+  
+  const root = repoRoot || process.cwd();
+  const projectName = path.basename(root);
+  const startTime = Date.now();
+  const originalMaxPages = maxPages;
+  const originalVerifyAuth = verifyAuth;
+  
+  // TIER ENFORCEMENT
+  let tierInfo = { tier: 'free', limits: {} };
+  try {
+    const access = await entitlements.enforce("reality", {
+      projectPath: root,
+      silent: true,
+    });
+    
+    tierInfo = access;
+    const limits = access.limits || entitlements.getLimits(access.tier);
+    
+    // Apply tier-based caps
+    if (access.downgrade === "reality.preview" || access.tier === "free") {
+      const previewMax = limits.realityMaxPages || 5;
+      if (maxPages > previewMax) {
+        maxPages = previewMax;
+      }
+      
+      if (verifyAuth && !limits.realityAuthBoundary) {
+        verifyAuth = false;
+      }
+    }
+  } catch (e) {
+    // Continue with defaults if entitlements unavailable
+  }
+
+  // Print banner
+  if (shouldShowBanner(argsOrOpts)) {
+    printBanner();
+  }
+  
+  console.log(`  ${c.dim}Project:${c.reset}  ${c.bold}${projectName}${c.reset}`);
+  console.log(`  ${c.dim}URL:${c.reset}      ${colors.accent}${url}${c.reset}`);
+  console.log(`  ${c.dim}Mode:${c.reset}     ${verifyAuth ? `${colors.auth}Two-Pass (Auth)${c.reset}` : `${colors.anon}Single-Pass (Anon)${c.reset}`}`);
+  console.log(`  ${c.dim}Budget:${c.reset}   ${maxPages} pages, depth ${maxDepth}`);
+  if (stabilityRuns > 1) {
+    console.log(`  ${c.dim}Stability:${c.reset} ${colors.info}${stabilityRuns} runs${c.reset}, threshold ${Math.round(flakyThreshold * 100)}%`);
+  }
+  
+  // Tier warning if applicable
+  if (tierInfo.tier === 'free' && (originalMaxPages > maxPages || (originalVerifyAuth && !verifyAuth))) {
+    printTierWarning(tierInfo.tier, tierInfo.limits, originalMaxPages, maxPages, originalVerifyAuth, verifyAuth);
+  }
+
+  // Playwright check
+  if (!chromium) {
+    const hint = playwrightError?.includes("Cannot find module") 
+      ? "Run: npm i -D playwright && npx playwright install chromium"
+      : `Playwright error: ${playwrightError || "unknown"}`;
+    console.log();
+    console.log(`  ${colors.error}${ICONS.cross}${c.reset} ${c.bold}Playwright not available${c.reset}`);
+    console.log(`  ${c.dim}${hint}${c.reset}`);
+    console.log();
+    return 1;
+  }
+
+  const baseUrl = normalizeUrl(url);
+  const outBase = path.join(root, ".vibecheck", "reality", stamp());
+  const shotsDir = path.join(outBase, "screenshots");
+  const videosDir = path.join(outBase, "videos");
+  const tracesDir = path.join(outBase, "traces");
+  const harDir = path.join(outBase, "har");
+  ensureDir(shotsDir);
+  if (recordVideo) ensureDir(videosDir);
+  if (recordTrace) ensureDir(tracesDir);
+  if (recordHar) ensureDir(harDir);
+
+  const tp = loadTruthpack(root, truthpack);
+  const matchers = getProtectedMatchersFromTruthpack(tp);
+  
+  if (tp) {
+    console.log(`  ${c.dim}Truthpack:${c.reset} ${colors.success}${ICONS.check}${c.reset} loaded (${matchers.length} protected patterns)`);
+  }
+
+  // Launch browser
+  console.log();
+  startSpinner('Launching browser...', colors.accent);
+  const browser = await chromium.launch({ headless: !headed });
+  stopSpinner('Browser launched', true);
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // STABILITY RUNS (multiple passes for flakiness detection)
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  const allRunFindings = [];
+  let lastAnonPass = null;
+  let lastAuthPass = null;
+  let anonVideoPath = null;
+  let authVideoPath = null;
+  let anonTracePath = null;
+  let authTracePath = null;
+  let savedStatePath = null;
+  
+  for (let runNum = 1; runNum <= stabilityRuns; runNum++) {
+    const isFirstRun = runNum === 1;
+    const isLastRun = runNum === stabilityRuns;
+    
+    if (stabilityRuns > 1) {
+      console.log();
+      console.log(`  ${colors.info}${BOX.hHorizontal.repeat(3)}${c.reset} ${c.bold}Stability Run ${runNum}/${stabilityRuns}${c.reset}`);
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // PASS A: ANONYMOUS
+    // ═══════════════════════════════════════════════════════════════════════════
+    printPassHeader('anon', baseUrl);
+    
+    startSpinner('Crawling anonymously...', colors.anon);
+    
+    // Build context options for video/HAR recording (only on last run to save resources)
+    const anonContextOpts = {};
+    if (recordVideo && isLastRun) {
+      anonContextOpts.recordVideo = {
+        dir: videosDir,
+        size: { width: 1280, height: 720 }
+      };
+    }
+    if (recordHar && isLastRun) {
+      anonContextOpts.recordHar = {
+        path: path.join(harDir, 'anon-traffic.har'),
+        mode: 'full'
+      };
+    }
+    
+    const anonContext = await browser.newContext(anonContextOpts);
+    
+    // Start trace recording if enabled (only on last run)
+    if (recordTrace && isLastRun) {
+      await anonContext.tracing.start({
+        screenshots: true,
+        snapshots: true,
+        sources: false
+      });
+    }
+    
+    const anonPass = await runSinglePass({ 
+      label: "ANON", 
+      baseUrl, 
+      context: anonContext, 
+      shotsDir: isLastRun ? shotsDir : path.join(outBase, `run${runNum}`, 'screenshots'),
+      danger, 
+      maxPages, 
+      maxDepth, 
+      timeoutMs, 
+      root,
+      retries,
+      stableWait,
+      onProgress: ({ page, maxPages: mp, url: currentUrl }) => {
+        // Could update spinner here if desired
+      }
+    });
+    
+    // Ensure shot dir exists for intermediate runs
+    if (!isLastRun) {
+      ensureDir(path.join(outBase, `run${runNum}`, 'screenshots'));
+    }
+    
+    // Save trace if enabled (only last run)
+    if (recordTrace && isLastRun) {
+      anonTracePath = path.join(tracesDir, 'anon-trace.zip');
+      await anonContext.tracing.stop({ path: anonTracePath });
+    }
+    
+    // Get video path before closing context (only last run)
+    if (recordVideo && isLastRun && anonPass.pagesVisited.length > 0) {
+      const pages = anonContext.pages();
+      if (pages.length > 0) {
+        const video = pages[0].video();
+        if (video) {
+          try {
+            anonVideoPath = await video.path();
+          } catch {}
+        }
+      }
+    }
+    
+    await anonContext.close();
+    stopSpinner(`Crawled ${anonPass.pagesVisited.length} pages`, true);
+    
+    printPassResult('anon', anonPass);
+    lastAnonPass = anonPass;
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // PASS B: AUTHENTICATED (optional)
+    // ═══════════════════════════════════════════════════════════════════════════
+    let authPass = null;
+    let authFindings = [];
+
+    if (verifyAuth) {
+      printPassHeader('auth', baseUrl);
+      
+      startSpinner('Setting up authenticated session...', colors.auth);
+      const ctxOpts = storageState ? { storageState } : {};
+      
+      // Add video/HAR recording options (only last run)
+      if (recordVideo && isLastRun) {
+        ctxOpts.recordVideo = {
+          dir: videosDir,
+          size: { width: 1280, height: 720 }
+        };
+      }
+      if (recordHar && isLastRun) {
+        ctxOpts.recordHar = {
+          path: path.join(harDir, 'auth-traffic.har'),
+          mode: 'full'
+        };
+      }
+      
+      const authContext = await browser.newContext(ctxOpts);
+      
+      // Start trace recording if enabled (only last run)
+      if (recordTrace && isLastRun) {
+        await authContext.tracing.start({
+          screenshots: true,
+          snapshots: true,
+          sources: false
+        });
+      }
+      const authPage = await authContext.newPage();
+      await authPage.goto(baseUrl, { waitUntil: "domcontentloaded" }).catch(() => {});
+      await authPage.waitForLoadState("networkidle", { timeout: 6000 }).catch(() => {});
+
+      if (!storageState && auth && isFirstRun) {
+        stopSpinner('Attempting login...', true);
+        startSpinner('Logging in...', colors.auth);
+        
+        const loginRes = await attemptLogin(authPage, { auth });
+        
+        if (loginRes.ok) {
+          stopSpinner('Login successful', true);
+          if (saveStorageState) {
+            const dest = path.isAbsolute(saveStorageState) ? saveStorageState : path.join(root, saveStorageState);
+            ensureDir(path.dirname(dest));
+            await authContext.storageState({ path: dest }).catch(() => {});
+            savedStatePath = dest;
+            console.log(`    ${colors.success}${ICONS.check}${c.reset} Session saved: ${c.dim}${path.relative(root, dest)}${c.reset}`);
+          }
+        } else {
+          stopSpinner('Login failed - continuing without auth', false);
+        }
+      } else {
+        stopSpinner('Using existing session', true);
+      }
+      
+      await authPage.close();
+
+      startSpinner('Crawling with authentication...', colors.auth);
+      authPass = await runSinglePass({ 
+        label: "AUTH", 
+        baseUrl, 
+        context: authContext, 
+        shotsDir: isLastRun ? shotsDir : path.join(outBase, `run${runNum}`, 'screenshots'),
+        danger, 
+        maxPages, 
+        maxDepth, 
+        timeoutMs, 
+        root,
+        retries,
+        stableWait
+      });
+      
+      // Save trace if enabled (only last run)
+      if (recordTrace && isLastRun) {
+        authTracePath = path.join(tracesDir, 'auth-trace.zip');
+        await authContext.tracing.stop({ path: authTracePath });
+      }
+      
+      // Get video path before closing context (only last run)
+      if (recordVideo && isLastRun && authPass.pagesVisited.length > 0) {
+        const pages = authContext.pages();
+        if (pages.length > 0) {
+          const video = pages[0].video();
+          if (video) {
+            try {
+              authVideoPath = await video.path();
+            } catch {}
+          }
+        }
+      }
+      
+      await authContext.close();
+      stopSpinner(`Crawled ${authPass.pagesVisited.length} pages`, true);
+      
+      printPassResult('auth', authPass);
+      lastAuthPass = authPass;
+
+      // Build auth coverage findings
+      if (matchers.length) {
+        startSpinner('Analyzing auth coverage...', colors.authCoverage);
+        authFindings = buildAuthCoverageFindings({ baseUrl, matchers, anonPass, authPass });
+        stopSpinner(`Found ${authFindings.length} auth issues`, authFindings.length === 0);
+      }
+    }
+    
+    // Collect findings from this run
+    const runFindings = [...anonPass.findings, ...(authPass?.findings || []), ...authFindings];
+    allRunFindings.push(runFindings);
+  }
+
+  await browser.close();
+  
+  // Use last pass results for page/coverage data
+  const anonPass = lastAnonPass;
+  const authPass = lastAuthPass;
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // ANALYSIS & RESULTS
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  const allVisited = [...anonPass.pagesVisited.map(p => p.url), ...(authPass?.pagesVisited || []).map(p => p.url)];
+  const coverage = coverageFromTruthpack({ truthpack: tp, visitedUrls: allVisited });
+
+  // Aggregate findings from stability runs (filters out flaky findings)
+  let findings;
+  let filteredFlakyCount = 0;
+  
+  if (stabilityRuns > 1) {
+    // Count total unique findings across all runs before filtering
+    const allFindingsFlat = allRunFindings.flat();
+    const uniqueBeforeFilter = new Set(allFindingsFlat.map(f => 
+      `${f.category}|${f.title?.replace(/\[ANON\]|\[AUTH\]/g, '').trim()}|${f.page || ''}`
+    )).size;
+    
+    findings = aggregateStabilityFindings(allRunFindings, flakyThreshold);
+    filteredFlakyCount = uniqueBeforeFilter - findings.length;
+    
+    printStabilityResults(stabilityRuns, findings.length, filteredFlakyCount);
+  } else {
+    // Single run - use findings directly
+    findings = allRunFindings[0] || [];
+  }
+  
+  const blocks = findings.filter(f => f.severity === "BLOCK").length;
+  const warns = findings.filter(f => f.severity === "WARN").length;
+
+  // Build artifact manifest
+  const artifacts = {
+    screenshots: shotsDir ? path.relative(root, shotsDir).replace(/\\/g, "/") : null,
+    videos: recordVideo ? {
+      directory: path.relative(root, videosDir).replace(/\\/g, "/"),
+      anon: anonVideoPath ? path.relative(root, anonVideoPath).replace(/\\/g, "/") : null,
+      auth: authVideoPath ? path.relative(root, authVideoPath).replace(/\\/g, "/") : null
+    } : null,
+    traces: recordTrace ? {
+      directory: path.relative(root, tracesDir).replace(/\\/g, "/"),
+      anon: anonTracePath ? path.relative(root, anonTracePath).replace(/\\/g, "/") : null,
+      auth: authTracePath ? path.relative(root, authTracePath).replace(/\\/g, "/") : null
+    } : null,
+    har: recordHar ? {
+      directory: path.relative(root, harDir).replace(/\\/g, "/"),
+      anon: path.join(harDir, 'anon-traffic.har'),
+      auth: path.join(harDir, 'auth-traffic.har')
+    } : null
+  };
+
+  // Build report
+  const report = {
+    meta: {
+      startedAt: new Date(startTime).toISOString(),
+      finishedAt: new Date().toISOString(),
+      durationMs: Date.now() - startTime,
+      baseUrl,
+      verifyAuth,
+      maxPages,
+      maxDepth,
+      truthpackLoaded: !!tp,
+      protectedMatcherCount: matchers.length,
+      savedStorageState: savedStatePath ? path.relative(root, savedStatePath).replace(/\\/g, "/") : null,
+      recordVideo,
+      recordTrace,
+      recordHar,
+      // Flakiness/stability metadata
+      stabilityRuns,
+      flakyThreshold,
+      filteredFlakyCount: stabilityRuns > 1 ? filteredFlakyCount : 0
+    },
+    artifacts,
+    coverage,
+    passes: { anon: anonPass, auth: authPass },
+    findings,
+    consoleErrors: [...anonPass.consoleErrors, ...(authPass?.consoleErrors || [])].slice(0, 50),
+    networkErrors: [...anonPass.networkErrors, ...(authPass?.networkErrors || [])].slice(0, 50)
+  };
+
+  // Write reports
+  fs.writeFileSync(path.join(outBase, "reality_report.json"), JSON.stringify(report, null, 2), "utf8");
+
+  const latestDir = path.join(root, ".vibecheck", "reality");
+  ensureDir(latestDir);
+  fs.writeFileSync(path.join(latestDir, "latest.json"), JSON.stringify({ latest: path.relative(root, outBase).replace(/\\/g, "/") }, null, 2));
+  fs.writeFileSync(path.join(latestDir, "last_reality.json"), JSON.stringify(report, null, 2), "utf8");
+
+  const duration = Date.now() - startTime;
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SEND TO API (for dashboard replay)
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  // Build reality result for API (timeline, network, screenshots, deadUI, fakeSuccess)
+  const realityResult = {
+    timeline: buildTimeline(anonPass, authPass),
+    network: buildNetworkTimeline(anonPass, authPass),
+    screenshots: buildScreenshotsList(anonPass, authPass, root),
+    deadUI: findings.filter(f => f.category === 'DeadUI').map((f, idx) => ({
+      stepIndex: idx,
+      selector: f.title || '',
+      reason: f.reason || '',
+    })),
+    fakeSuccess: findings.filter(f => f.category === 'FakeResponse' || f.category === 'FakeDomain').map((f, idx) => ({
+      stepIndex: idx,
+      message: f.title || f.reason || '',
+      actualStatus: 0, // Could be extracted from evidence
+    })),
+  };
+  
+  // Try to send to API (non-blocking, doesn't fail the run)
+  try {
+    const { sendRunToApi, extractFindings, calculateScore } = require('../../packages/cli/dist/runtime/api-run-sender.js');
+    
+    const runId = crypto.randomUUID ? crypto.randomUUID() : `reality-${Date.now()}`;
+    const apiFindings = extractFindings ? extractFindings({ findings }) : findings.map(f => ({
+      severity: f.severity?.toLowerCase() || 'medium',
+      category: f.category || 'general',
+      message: f.title || f.reason || 'Unknown issue',
+      file: f.page,
+    }));
+    
+    const score = calculateScore ? calculateScore(verdict, apiFindings) : (verdict === 'SHIP' ? 100 : verdict === 'WARN' ? 50 : 0);
+    
+    sendRunToApi({
+      runId,
+      command: 'reality',
+      status: 'completed',
+      verdict,
+      score,
+      exitCode: blocks ? 2 : warns ? 1 : 0,
+      startTime: new Date(startTime).toISOString(),
+      endTime: new Date().toISOString(),
+      duration,
+      projectPath: root,
+      findings: apiFindings,
+      metadata: {
+        baseUrl,
+        pagesVisited: anonPass.pagesVisited.length + (authPass?.pagesVisited?.length || 0),
+        coverage: coverage?.percent,
+      },
+      realityResult,
+      videoUrl: anonVideoPath ? path.relative(root, anonVideoPath).replace(/\\/g, "/") : undefined,
+      traceUrl: anonTracePath ? path.relative(root, anonTracePath).replace(/\\/g, "/") : undefined,
+    }).catch(() => {
+      // Silently ignore API errors - CLI works offline
+    });
+  } catch (e) {
+    // Module not available or other error - continue without API sync
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // OUTPUT
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  // Determine verdict
+  const verdict = blocks > 0 ? 'BLOCK' : warns > 0 ? 'WARN' : 'SHIP';
+  
+  // Use Mission Control format
+  if (!argsOrOpts.json && !argsOrOpts.quiet) {
+    const { formatRealityOutput } = require('./lib/reality-output');
+    
+    // Build test results from findings
+    const tests = findings.map(f => ({
+      name: f.title || f.category || 'Test',
+      route: f.page || f.url || '',
+      passed: f.severity !== 'BLOCK',
+    }));
+    
+    console.log(formatRealityOutput({
+      verdict,
+      tests,
+      passed: tests.filter(t => t.passed).length,
+      failed: tests.filter(t => !t.passed).length,
+      warnings: warns,
+      coverage: coverage.percent || 0,
+      duration,
+      url: baseUrl,
+      success: verdict === 'SHIP',
+    }, { projectPath: root, version: 'v3.5.5' }));
+    
+    // Show report path
+    console.log(`\n  ${colors.accent}Report:${c.reset} ${path.relative(root, outBase)}/reality_report.json`);
+  }
+
+  process.exitCode = blocks ? 2 : warns ? 1 : 0;
+  return process.exitCode;
+}
+
+module.exports = { runReality };