@matware/e2e-runner 1.3.0 → 1.3.1

package/src/mcp-tools.js

@@ -15,18 +15,48 @@ import http from 'http';
 import { loadConfig } from './config.js';
 import { connectToPool } from './pool.js';
 import { waitForAnyPool, getPoolUrls, getAggregatedPoolStatus, selectPool } from './pool-manager.js';
-import { runTestsParallel, loadTestFile, loadTestSuite, loadAllSuites, listSuites } from './runner.js';
+import { runTestsParallel, loadTestFile, loadTestSuite, loadAllSuites, listSuites, fetchAuthToken } from './runner.js';
 import { generateReport, saveReport, persistRun } from './reporter.js';
 import { narrateTest } from './narrate.js';
 import { startDashboard, stopDashboard } from './dashboard.js';
 import { lookupScreenshotHash, ensureProject, computeScreenshotHash, registerScreenshotHash, getNetworkLogs, setVariable, getVariables, deleteVariable, listVariables } from './db.js';
 import { fetchIssue, checkCliAuth, detectProvider } from './issues.js';
-import { buildPrompt, hasApiKey } from './ai-generate.js';
+import { buildPrompt, hasApiKey, generateHindsightHint } from './ai-generate.js';
 import { verifyIssue } from './verify.js';
 import { listModules } from './module-resolver.js';
-import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends, getRunInsights, getTestHistory, getPageHistory, getSelectorHistory, getHealthSnapshot, getTestCreationContext, generateImprovements } from './learner-sqlite.js';
+import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends, getRunInsights, getTestHistory, getPageHistory, getSelectorHistory, getHealthSnapshot, getTestCreationContext, generateImprovements, getActionHealthScores } from './learner-sqlite.js';
 import { queryGraph } from './learner-neo4j.js';
 import { startNeo4j, stopNeo4j, getNeo4jStatus } from './neo4j-pool.js';
+import { getAppPoolStatus, isAppPoolEnabled } from './app-pool.js';
+
+/**
+ * Resolves auth token from config: uses static authToken if set,
+ * otherwise auto-logs in via authLoginEndpoint + authCredentials.
+ * If the endpoint is a Docker-internal hostname (e.g. "nginx", "api")
+ * and fails with ENOTFOUND, retries with localhost.
+ * Returns the token string or null if no auth is configured.
+ */
+async function resolveAuthToken(config) {
+  if (config.authToken) return config.authToken;
+  if (config.authLoginEndpoint && config.authCredentials) {
+    const tokenPath = config.authTokenPath || 'token';
+    try {
+      return await fetchAuthToken(config.authLoginEndpoint, config.authCredentials, tokenPath);
+    } catch (err) {
+      // Docker-internal hostname? Retry with localhost from host machine
+      if (err.message && err.message.includes('ENOTFOUND')) {
+        const url = new URL(config.authLoginEndpoint);
+        if (!url.hostname.includes('.')) {
+          // Simple hostname (nginx, api, etc.) → likely Docker service name
+          const localhostUrl = `http://localhost${url.port && url.port !== '80' ? ':' + url.port : ''}${url.pathname}${url.search}`;
+          return await fetchAuthToken(localhostUrl, config.authCredentials, tokenPath);
+        }
+      }
+      throw err;
+    }
+  }
+  return null;
+}
 
 // ── Tool definitions ──────────────────────────────────────────────────────────
 
@@ -223,6 +253,20 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
       },
     },
   },
+  {
+    name: 'e2e_app_pool_status',
+    description:
+      'Get the status of the app environment pool. Shows active forks, allocated ports, per-fork details (driver, baseUrl, test name, fork time). Only relevant when appPool is enabled in config.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: {
+          type: 'string',
+          description: 'Absolute path to the project root directory.',
+        },
+      },
+    },
+  },
   {
     name: 'e2e_screenshot',
     description:
@@ -264,6 +308,24 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
       properties: {},
     },
   },
+  {
+    name: 'e2e_dashboard_restart',
+    description:
+      'Restart the E2E Runner web dashboard. Stops the current instance and starts a new one, optionally with a new cwd or port. Useful when switching projects or when the dashboard was started from another session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        port: {
+          type: 'number',
+          description: 'Dashboard port (default: same port or 8484)',
+        },
+        cwd: {
+          type: 'string',
+          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+        },
+      },
+    },
+  },
   {
     name: 'e2e_issue',
     description:
@@ -337,6 +399,11 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
           type: 'string',
           description: 'localStorage key name for the auth token (default: "accessToken")',
         },
+        waitUntil: {
+          type: 'string',
+          enum: ['networkidle2', 'domcontentloaded', 'load', 'auto'],
+          description: 'Navigation wait strategy. "auto" (default) tries networkidle2 first with a short timeout, then falls back to domcontentloaded + delay for SPA/WebSocket apps. Use "domcontentloaded" for apps with persistent connections (WebSocket, SSE).',
+        },
         cwd: {
           type: 'string',
           description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
@@ -384,6 +451,11 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
           type: 'string',
           description: 'localStorage key name for the auth token (default: "accessToken")',
         },
+        waitUntil: {
+          type: 'string',
+          enum: ['networkidle2', 'domcontentloaded', 'load', 'auto'],
+          description: 'Navigation wait strategy. "auto" (default) tries networkidle2 first with a short timeout, then falls back to domcontentloaded + delay for SPA/WebSocket apps. Use "domcontentloaded" for apps with persistent connections (WebSocket, SSE).',
+        },
         cwd: {
           type: 'string',
           description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
@@ -568,9 +640,9 @@ Good module candidates: auth setup, page navigation, tab clicking, opening sideb
   },
 ];
 
-/** Tools exposed on the dashboard — excludes dashboard start/stop (already running). */
+/** Tools exposed on the dashboard — excludes dashboard start/stop/restart (already running). */
 export const DASHBOARD_TOOLS = TOOLS.filter(
-  t => t.name !== 'e2e_dashboard_start' && t.name !== 'e2e_dashboard_stop'
+  t => t.name !== 'e2e_dashboard_start' && t.name !== 'e2e_dashboard_stop' && t.name !== 'e2e_dashboard_restart'
 );
 
 // ── Dashboard broadcast helper ────────────────────────────────────────────────
@@ -620,7 +692,8 @@ async function handleRun(args) {
   const config = await loadConfig(configOverrides, args.cwd);
   config.triggeredBy = 'mcp';
 
-  await waitForAnyPool(getPoolUrls(config));
+  const driverOpts = { poolDriver: config.poolDriver, maxSessions: config.maxSessions };
+  await waitForAnyPool(getPoolUrls(config), 30000, driverOpts);
 
   let tests, hooks;
 
@@ -669,8 +742,13 @@ async function handleRun(args) {
     }));
 
   const flaky = report.results
-    .filter(r => r.success && r.attempt > 1)
-    .map(r => ({ name: r.name, attempts: r.attempt }));
+    .filter(r => r.success && (r.attempt > 1 || r.flaky))
+    .map(r => {
+      const entry = { name: r.name };
+      if (r.voting) entry.voting = r.voting;
+      else entry.attempts = r.attempt;
+      return entry;
+    });
 
   const summary = {
     ...report.summary,
@@ -799,6 +877,19 @@ async function handleRun(args) {
     } catch { /* never fail the run response */ }
   }
 
+  // Hindsight hints — LLM-powered fix suggestions for failures (async, never blocks)
+  if (hasApiKey(config) && failures.length > 0) {
+    try {
+      const maxHints = config.hintsMaxFailures ?? 3;
+      const hintTargets = failures.slice(0, maxHints);
+      const failedResults = hintTargets.map(f => report.results.find(r => r.name === f.name)).filter(Boolean);
+      const hints = (await Promise.all(failedResults.map(r => generateHindsightHint(r, config)))).filter(Boolean);
+      if (hints.length > 0) {
+        summary.hindsightHints = hints;
+      }
+    } catch { /* never fail the run response */ }
+  }
+
   return textResult(JSON.stringify(summary, null, 2));
 }
 
@@ -1039,24 +1130,46 @@ function analyzeEvaluateUsage(actions) {
       suggestions.push('No-op evaluate (returns static string) → remove entirely');
     }
 
-    // 🚨 Pattern: evaluate returns template string interpolating booleans but never throws/fails
-    // e.g. return `Foo: ${hasFoo}, Bar: ${hasBar}` — always truthy, never fails
-    if (!(/throw\s+new\s+Error/s.test(code) || /\bFAIL[:\s]/s.test(code) || /\bERROR[:\s]/s.test(code)
-      || /return\s+false\b/s.test(code) || /return\s+'FAIL/s.test(code) || /return\s+`FAIL/s.test(code))) {
-      // Check for template returns with ${var} interpolation (informational, never fails)
+    // 🚨 Pattern: evaluate that NEVER fails — no throw, no FAIL:/ERROR:, no return false
+    const canFail = /throw\s+new\s+Error/s.test(code) || /\bFAIL[:\s]/s.test(code) || /\bERROR[:\s]/s.test(code)
+      || /return\s+false\b/s.test(code) || /return\s+'FAIL/s.test(code) || /return\s+`FAIL/s.test(code);
+
+    if (!canFail) {
+      // Any template string return → always truthy, test always passes
       if (/return\s+`[^`]*\$\{[^}]+\}[^`]*`/s.test(code)) {
-        // Heuristic: does the template interpolate boolean-like variables?
-        const hasConditionInterpolation = /\$\{(has\w+|is\w+|no\w+|found|exists|present|visible|loaded)\}/i.test(code);
-        const hasComparisonInterpolation = /\$\{[^}]*(===|!==|>|<|&&|\|\|)[^}]*\}/s.test(code);
-        if (hasConditionInterpolation || hasComparisonInterpolation) {
-          suggestions.push(
-            '🚨 Evaluate returns informational template string with boolean/condition values but NEVER throws or returns false — ' +
-            'this test will ALWAYS PASS. Either throw new Error("FAIL: ...") when conditions are not met, or replace with built-in assert actions'
-          );
-        }
+        suggestions.push(
+          '🚨 Evaluate returns template string but NEVER throws or returns false — ' +
+          'this action will ALWAYS PASS regardless of results. Either throw new Error("FAIL: ...") when conditions fail, or use built-in assert actions'
+        );
+      }
+      // Returns a plain string (not template) that isn't FAIL/ERROR
+      else if (/return\s+['"][^'"]*['"]/s.test(code) && code.length > 60) {
+        suggestions.push(
+          '⚠️ Evaluate returns a plain string but never fails — informational-only. Add failure conditions or replace with assert actions'
+        );
       }
     }
 
+    // 🚨 Pattern: .click() inside evaluate — should use built-in click action
+    if (/\.click\(\)/s.test(code) && !(/\.textContent[^]*\.click\(\)/s.test(code))) {
+      // Only flag if not already caught by the textContent click pattern above
+      if (/\.filter\([^)]*text/s.test(code) || /querySelectorAll[^)]*\)[^]*\.click/s.test(code) || /querySelector[^)]*\)[^]*\.click/s.test(code)) {
+        suggestions.push(
+          '🚨 Element click via evaluate → use { type: "click", text: "..." } or { type: "click", selector: "..." }. ' +
+          'Built-in click has retries, waits, and better error reporting'
+        );
+      }
+    }
+
+    // 🚨 Pattern: MUI/framework selectors inside evaluate — fragile
+    const muiMatches = code.match(/\.Mui[\w-]+/g) || [];
+    if (muiMatches.length > 0) {
+      suggestions.push(
+        `⚠️ MUI class selectors (${muiMatches.slice(0, 3).join(', ')}) are auto-generated and change between versions. ` +
+        `Prefer [data-testid="..."], [role="..."], or text-based selectors`
+      );
+    }
+
     // 🚨 Pattern: sets window.__e2e_* globals for cross-test state sharing
     if (/window\.__e2e_\w+\s*=/.test(code) && !/window\.__e2e\./.test(code.replace(/window\.__e2e_\w+\s*=/g, ''))) {
       suggestions.push(
@@ -1093,6 +1206,23 @@ function analyzeActionPatterns(tests) {
     }
   }
 
+  // Detect MUI/framework selectors in action selectors
+  for (const test of tests) {
+    if (!test.actions) continue;
+    for (const action of test.actions) {
+      const sel = action.selector || '';
+      if (/\.Mui[\w-]+/.test(sel) || /\.ant-[\w-]+/.test(sel) || /\.v-[\w-]+/.test(sel)) {
+        const match = sel.match(/\.(Mui[\w-]+|ant-[\w-]+|v-[\w-]+)/);
+        warnings.push(
+          `⚠️ Framework selector ".${match[1]}" in "${test.name}" (${action.type}) — ` +
+          `these class names are auto-generated and break on version upgrades. ` +
+          `Prefer [data-testid="..."], [role="..."], or text-based actions`
+        );
+        break;
+      }
+    }
+  }
+
   // Detect cross-test state: test N writes window.__e2e_*, test M reads it
   const writers = new Map(); // varName → test name
   const readers = new Map(); // varName → [test names]
@@ -1132,7 +1262,7 @@ function analyzeActionPatterns(tests) {
 async function handlePoolStatus(args) {
   const config = await loadConfig({}, args.cwd);
   const poolUrls = getPoolUrls(config);
-  const aggregated = await getAggregatedPoolStatus(poolUrls);
+  const aggregated = await getAggregatedPoolStatus(poolUrls, { poolDriver: config.poolDriver, maxSessions: config.maxSessions });
 
   const lines = [];
 
@@ -1159,6 +1289,30 @@ async function handlePoolStatus(args) {
   return textResult(lines.join('\n'));
 }
 
+async function handleAppPoolStatus(args) {
+  const config = await loadConfig({}, args.cwd);
+  if (!isAppPoolEnabled(config)) {
+    return textResult('App pool is not enabled. Set appPool.enabled = true in e2e.config.js to use isolated app environments per test.');
+  }
+
+  const status = getAppPoolStatus();
+  const lines = [
+    `Driver:        ${config.appPool.driver}`,
+    `Active forks:  ${status.activeForks}/${config.appPool.maxForks}`,
+    `Port range:    ${config.appPool.forkBasePort}-${config.appPool.forkBasePort + config.appPool.maxForks - 1}`,
+    `Allocated:     ${status.allocatedPorts.length ? status.allocatedPorts.join(', ') : 'none'}`,
+  ];
+
+  if (status.forks.length > 0) {
+    lines.push('');
+    for (const fork of status.forks) {
+      lines.push(`  ${fork.forkId}: port ${fork.port}, ${fork.baseUrl} (${fork.testName || 'unnamed'}, ${fork.forkTimeMs}ms)`);
+    }
+  }
+
+  return textResult(lines.join('\n'));
+}
+
 async function handleScreenshot(args) {
   if (!args.hash) return errorResult('Missing required parameter: hash');
 
@@ -1695,12 +1849,42 @@ function buildSuggestedTests(structure, pageUrl) {
   return tests;
 }
 
+/**
+ * Smart page navigation with fallback for SPA/WebSocket apps.
+ * - "auto" (default): tries networkidle2 with 10s timeout, falls back to domcontentloaded + 2s delay
+ * - "networkidle2"/"load"/"domcontentloaded": uses that strategy directly with 30s timeout
+ */
+async function smartNavigate(page, url, waitUntil) {
+  const strategy = waitUntil || 'auto';
+
+  if (strategy === 'auto') {
+    try {
+      await page.goto(url, { waitUntil: 'networkidle2', timeout: 10000 });
+    } catch (err) {
+      if (err.name === 'TimeoutError' || (err.message && err.message.includes('timeout'))) {
+        // networkidle2 timed out — likely a SPA with WebSocket/SSE/polling
+        // Fall back to domcontentloaded + wait for hydration
+        await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 20000 });
+        await new Promise(r => setTimeout(r, 2000));
+      } else {
+        throw err;
+      }
+    }
+  } else {
+    await page.goto(url, { waitUntil: strategy, timeout: 30000 });
+    // For domcontentloaded, add a small hydration delay for SPAs
+    if (strategy === 'domcontentloaded') {
+      await new Promise(r => setTimeout(r, 1500));
+    }
+  }
+}
+
 async function handleAnalyze(args) {
   if (!args.url) return errorResult('Missing required parameter: url');
 
   const config = await loadConfig({}, args.cwd);
   const poolUrls = getPoolUrls(config);
-  const chosenPool = await selectPool(poolUrls);
+  const chosenPool = await selectPool(poolUrls, 2000, 60000, { poolDriver: config.poolDriver, maxSessions: config.maxSessions });
 
   let browser;
   try {
@@ -1708,8 +1892,8 @@ async function handleAnalyze(args) {
     const page = await browser.newPage();
     await page.setViewport(config.viewport);
 
-    // Inject auth token into localStorage before navigation
-    const authToken = args.authToken || config.authToken;
+    // Resolve auth token: explicit arg > config static > auto-login
+    const authToken = args.authToken || await resolveAuthToken(config);
     if (authToken) {
       const storageKey = args.authStorageKey || config.authStorageKey || 'accessToken';
       const origin = new URL(args.url).origin;
@@ -1717,7 +1901,7 @@ async function handleAnalyze(args) {
       await page.evaluate((key, token) => { localStorage.setItem(key, token); }, storageKey, authToken);
     }
 
-    await page.goto(args.url, { waitUntil: 'networkidle2', timeout: 30000 });
+    await smartNavigate(page, args.url, args.waitUntil);
 
     if (args.selector) {
       await page.waitForSelector(args.selector, { timeout: 10000 });
@@ -1789,7 +1973,7 @@ async function handleCapture(args) {
 
   const config = await loadConfig({}, args.cwd);
   const capturePoolUrls = getPoolUrls(config);
-  const capturePool = await selectPool(capturePoolUrls);
+  const capturePool = await selectPool(capturePoolUrls, 2000, 60000, { poolDriver: config.poolDriver, maxSessions: config.maxSessions });
 
   let browser;
   try {
@@ -1797,8 +1981,8 @@ async function handleCapture(args) {
     const page = await browser.newPage();
     await page.setViewport(config.viewport);
 
-    // Inject auth token into localStorage before navigation
-    const authToken = args.authToken || config.authToken;
+    // Resolve auth token: explicit arg > config static > auto-login
+    const authToken = args.authToken || await resolveAuthToken(config);
     if (authToken) {
       const storageKey = args.authStorageKey || config.authStorageKey || 'accessToken';
       // Navigate to origin first so localStorage is accessible
@@ -1807,7 +1991,7 @@ async function handleCapture(args) {
       await page.evaluate((key, token) => { localStorage.setItem(key, token); }, storageKey, authToken);
     }
 
-    await page.goto(args.url, { waitUntil: 'networkidle2', timeout: 30000 });
+    await smartNavigate(page, args.url, args.waitUntil);
 
     if (args.selector) {
       await page.waitForSelector(args.selector, { timeout: 10000 });
@@ -1874,6 +2058,35 @@ async function handleDashboardStop() {
   return textResult('Dashboard stopped');
 }
 
+async function handleDashboardRestart(args) {
+  const port = args.port || (dashboardHandle ? dashboardHandle.port : 8484);
+
+  // Stop current instance if we own it
+  if (dashboardHandle) {
+    stopDashboard(dashboardHandle);
+    dashboardHandle = null;
+  }
+
+  // Kill any process occupying the target port (e.g. from another session)
+  try {
+    const { execFileSync } = await import('child_process');
+    const lsof = execFileSync('lsof', ['-ti', `:${port}`], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    if (lsof) {
+      for (const pid of lsof.split('\n').filter(Boolean)) {
+        try { process.kill(Number(pid), 'SIGTERM'); } catch {}
+      }
+      // Brief wait for port to free up
+      await new Promise(r => setTimeout(r, 500));
+    }
+  } catch {}
+
+  // Start fresh
+  const overrides = { dashboardPort: port };
+  const config = await loadConfig(overrides, args.cwd);
+  dashboardHandle = await startDashboard(config);
+  return textResult(`Dashboard restarted at http://localhost:${dashboardHandle.port}`);
+}
+
 async function handleNeo4j(args) {
   if (!args.action) return errorResult('Missing required parameter: action');
 
@@ -1965,8 +2178,10 @@ async function handleLearnings(args) {
       return textResult(JSON.stringify(getErrorPatterns(projectId), null, 2));
     case 'trends':
       return textResult(JSON.stringify(getTestTrends(projectId, days), null, 2));
+    case 'actions':
+      return textResult(JSON.stringify(getActionHealthScores(projectId, days), null, 2));
     default:
-      return errorResult(`Unknown query: "${args.query}". Use: summary, flaky, selectors, pages, apis, errors, trends, test:<name>, page:<path>, selector:<value>`);
+      return errorResult(`Unknown query: "${args.query}". Use: summary, flaky, selectors, pages, apis, errors, trends, actions, test:<name>, page:<path>, selector:<value>`);
   }
 }
 
@@ -2136,12 +2351,16 @@ export async function dispatchTool(name, args = {}) {
       return await handleCreateTest(args);
     case 'e2e_pool_status':
       return await handlePoolStatus(args);
+    case 'e2e_app_pool_status':
+      return await handleAppPoolStatus(args);
     case 'e2e_screenshot':
       return await handleScreenshot(args);
     case 'e2e_dashboard_start':
       return await handleDashboardStart(args);
     case 'e2e_dashboard_stop':
       return await handleDashboardStop();
+    case 'e2e_dashboard_restart':
+      return await handleDashboardRestart(args);
     case 'e2e_issue':
       return await handleIssue(args);
     case 'e2e_create_module':

package/src/narrate.js

@@ -167,6 +167,28 @@ export function narrateAction(action, result) {
       return `Executed JS: ${snippet}${time}`;
     }
 
+    case 'assert_visual': {
+      const vr = result.result;
+      if (vr?.goldenCreated) return `Saved golden reference: ${value}${time}`;
+      const pct = vr?.diffPercentage != null ? (vr.diffPercentage * 100).toFixed(2) + '% diff' : '';
+      return `Visual comparison against "${value}": ${pct}${time}`;
+    }
+
+    case 'open_tab':
+      return `Opened new tab${text ? ` "${text}"` : ''} → ${value}${time}`;
+
+    case 'switch_tab':
+      return `Switched to tab "${value}"${time}`;
+
+    case 'close_tab':
+      return `Closed tab${value ? ` "${value}"` : ''}${time}`;
+
+    case 'assert_tab_count':
+      return `Verified ${value} tab(s) open${time}`;
+
+    case 'wait_for_tab':
+      return `Waited for new tab to open${text ? ` (labeled "${text}")` : ''}${time}`;
+
     default:
       return `Unknown action "${type}"${time}`;
   }
@@ -223,6 +245,12 @@ function describeIntent(action) {
     case 'click_menu_item':        return `Click menu item "${text}"`;
     case 'click_in_context':       return `Click "${selector}" in context of "${text}"`;
     case 'evaluate':   return 'Execute JS';
+    case 'assert_visual':           return `Visual compare against "${value}"`;
+    case 'open_tab':               return `Open new tab → ${value}`;
+    case 'switch_tab':             return `Switch to tab "${value}"`;
+    case 'close_tab':              return `Close tab${value ? ` "${value}"` : ''}`;
+    case 'assert_tab_count':       return `Assert ${value} tab(s) open`;
+    case 'wait_for_tab':           return 'Wait for new tab';
     default:           return `Action "${type}"`;
   }
 }

package/src/pool-manager.js

@@ -42,16 +42,22 @@ function getPending(poolUrl) {
   return pendingConnections.get(poolUrl) || 0;
 }
 
+/** Extracts pool driver options from config for passing to getPoolStatus. */
+function driverOpts(config) {
+  if (!config) return {};
+  return { poolDriver: config.poolDriver || 'auto', maxSessions: config.maxSessions || 10 };
+}
+
 /** Returns the normalized pool URL array from config. Always an array, even for single pool. */
 export function getPoolUrls(config) {
   return config._poolUrls || [config.poolUrl];
 }
 
-/** Fetches /pressure from all pools in parallel. Returns [{ url, status, error }]. */
-export async function getAllPoolStatuses(poolUrls) {
+/** Fetches status from all pools in parallel. Returns [{ url, status, error }]. */
+export async function getAllPoolStatuses(poolUrls, options = {}) {
   return Promise.all(poolUrls.map(async (url) => {
     try {
-      const status = await getPoolStatus(url);
+      const status = await getPoolStatus(url, options);
       return { url, status, error: null };
     } catch (error) {
       return { url, status: null, error: error.message };
@@ -60,8 +66,8 @@ export async function getAllPoolStatuses(poolUrls) {
 }
 
 /** Combined view across all pools: totalRunning, totalMaxConcurrent, per-pool details. */
-export async function getAggregatedPoolStatus(poolUrls) {
-  const results = await getAllPoolStatuses(poolUrls);
+export async function getAggregatedPoolStatus(poolUrls, options = {}) {
+  const results = await getAllPoolStatuses(poolUrls, options);
 
   let totalRunning = 0;
   let totalMaxConcurrent = 0;
@@ -90,11 +96,11 @@ export async function getAggregatedPoolStatus(poolUrls) {
 }
 
 /** Blocks until at least one pool is reachable and available. */
-export async function waitForAnyPool(poolUrls, maxWaitMs = 30000) {
+export async function waitForAnyPool(poolUrls, maxWaitMs = 30000, options = {}) {
   const start = Date.now();
 
   while (Date.now() - start < maxWaitMs) {
-    const results = await getAllPoolStatuses(poolUrls);
+    const results = await getAllPoolStatuses(poolUrls, options);
     const available = results.find(r => r.status?.available);
     if (available) return available.status;
 
@@ -115,17 +121,17 @@ export async function waitForAnyPool(poolUrls, maxWaitMs = 30000) {
  * Picks the pool with the lowest pressure ratio.
  *
  * Algorithm:
- * 1. Query all pools' /pressure in parallel
+ * 1. Query all pools' status in parallel (driver-aware)
  * 2. Add local pending count to each pool's running total
  * 3. Filter to reachable pools with (running + pending) < maxConcurrent
  * 4. Sort by: lowest effective pressure → fewest queued → most free slots
  * 5. Track selection in pending counter, return best candidate URL
  * 6. If all full, poll every 2s up to 60s, then pick least-pressured anyway
  */
-export async function selectPool(poolUrls, pollIntervalMs = 2000, maxWaitMs = 60000) {
+export async function selectPool(poolUrls, pollIntervalMs = 2000, maxWaitMs = 60000, options = {}) {
   // Fast path: single pool
   if (poolUrls.length === 1) {
-    await waitForSlotOnPool(poolUrls[0], pollIntervalMs, maxWaitMs);
+    await waitForSlotOnPool(poolUrls[0], pollIntervalMs, maxWaitMs, options);
     trackPending(poolUrls[0]);
     return poolUrls[0];
   }
@@ -133,7 +139,7 @@ export async function selectPool(poolUrls, pollIntervalMs = 2000, maxWaitMs = 60
   const start = Date.now();
 
   while (Date.now() - start < maxWaitMs) {
-    const results = await getAllPoolStatuses(poolUrls);
+    const results = await getAllPoolStatuses(poolUrls, options);
     const candidates = results
       .filter(r => r.status && !r.error && r.status.available)
       .map(r => {
@@ -173,7 +179,7 @@ export async function selectPool(poolUrls, pollIntervalMs = 2000, maxWaitMs = 60
   }
 
   // Timeout — pick the least-pressured pool anyway (let connectToPool deal with it)
-  const results = await getAllPoolStatuses(poolUrls);
+  const results = await getAllPoolStatuses(poolUrls, options);
   const reachable = results
     .filter(r => r.status && !r.error)
     .sort((a, b) => {
@@ -198,16 +204,16 @@ export async function selectPool(poolUrls, pollIntervalMs = 2000, maxWaitMs = 60
 /** Convenience: selectPool + connectToPool in one call. */
 export async function selectAndConnect(config) {
   const poolUrls = getPoolUrls(config);
-  const chosenUrl = await selectPool(poolUrls);
+  const chosenUrl = await selectPool(poolUrls, 2000, 60000, driverOpts(config));
   return connectToPool(chosenUrl, config.connectRetries, config.connectRetryDelay);
 }
 
-/** Waits until a single pool has capacity (replaces the old waitForSlot from runner.js). */
-async function waitForSlotOnPool(poolUrl, pollIntervalMs = 2000, maxWaitMs = 60000) {
+/** Waits until a single pool has capacity. */
+async function waitForSlotOnPool(poolUrl, pollIntervalMs = 2000, maxWaitMs = 60000, options = {}) {
   const start = Date.now();
   while (Date.now() - start < maxWaitMs) {
     try {
-      const status = await getPoolStatus(poolUrl);
+      const status = await getPoolStatus(poolUrl, options);
       if (status.available && status.running < status.maxConcurrent) {
         return;
       }