@debugg-ai/debugg-ai-mcp 3.10.0 → 4.1.0

package/dist/handlers/probePageHandler.js

@@ -21,12 +21,41 @@ import { TunnelProvisionError } from '../services/tunnels.js';
 import { disposeUnhealthyTunnel } from '../utils/tunnelDisposition.js';
 import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js';
 import { extractLocalhostPort } from '../utils/urlParser.js';
-import { buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
+import { buildContext, findExistingTunnel, ensureTunnel, acquirePortRoute, releasePortRoute, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
+import { randomUUID } from 'node:crypto';
 import { getCachedTemplateUuid, invalidateTemplateCache } from '../utils/handlerCaches.js';
 import { getPageProbeTemplateSlug } from '../services/workflows.js';
 import { reaggregateByOriginPath, mapConsoleSlice } from '../utils/harSummarizer.js';
 import { fetchImageAsBase64, imageContentBlock } from '../utils/imageUtils.js';
 const logger = new Logger({ module: 'probePageHandler' });
+function groupTargetsByRoute(targetContexts) {
+    const groups = [];
+    const byKey = new Map();
+    for (let i = 0; i < targetContexts.length; i++) {
+        const tc = targetContexts[i];
+        let key;
+        let needsRoute = false;
+        if (tc.isLocalhost && tc.tunnelId) {
+            const port = extractLocalhostPort(tc.originalUrl);
+            const isHttpsLocal = tc.originalUrl.startsWith('https:');
+            key = `local:${port}:${isHttpsLocal}`;
+            needsRoute = true;
+        }
+        else {
+            // Public URLs (and dev-mode localhost, which never gets a tunnelId)
+            // share ONE group — no route to serialize, no reason to split them.
+            key = 'public';
+        }
+        let group = byKey.get(key);
+        if (!group) {
+            group = { key, indices: [], needsRoute };
+            byKey.set(key, group);
+            groups.push(group);
+        }
+        group.indices.push(i);
+    }
+    return groups;
+}
 export async function probePageHandler(input, context, rawProgressCallback) {
     const startTime = Date.now();
     logger.toolStart('probe_page', input);
@@ -68,6 +97,10 @@ export async function probePageHandler(input, context, rawProgressCallback) {
         else
             requestSignal.addEventListener('abort', onAbort, { once: true });
     }
+    // Base id for the shared port-route lock's holder bookkeeping (§2.4) — one
+    // per target GROUP, suffixed below, since a multi-port batch acquires the
+    // route once per group, sequentially.
+    const callId = randomUUID();
     // Per-target tunnel contexts. Index aligns with input.targets[].
     const targetContexts = [];
     // Tunnel keys we provisioned this call (for cleanup if creation fails after key acquired).
@@ -133,30 +166,15 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                             const msg = tunnelError instanceof Error ? tunnelError.message : String(tunnelError);
                             throw new Error(`Tunnel creation failed for ${ctx.originalUrl}. (Detail: ${msg})`);
                         }
-                        // Tunnel health probe: catch the IPv4/IPv6 bind / dead-server case
-                        // before committing to a full backend execution.
-                        if (tunneled.targetUrl) {
-                            const health = await probeTunnelHealth(tunneled.targetUrl);
-                            if (!health.healthy) {
-                                const payload = {
-                                    error: 'TunnelTrafficBlocked',
-                                    message: `Tunnel established but traffic isn't reaching the dev server. ${health.detail ?? ''}`,
-                                    detail: {
-                                        code: health.code,
-                                        status: health.status,
-                                        ngrokErrorCode: health.ngrokErrorCode,
-                                        elapsedMs: health.elapsedMs,
-                                    },
-                                };
-                                // Evict ONLY on a code proving the endpoint is gone; every other
-                                // failure keeps the tunnel we are already paying for, since a
-                                // teardown+re-provision costs two billed hours and this probe
-                                // cannot tell a dead endpoint from a transient edge flake. See
-                                // utils/tunnelDisposition.ts for the allowlist and the evidence.
-                                disposeUnhealthyTunnel({ health, tunnelId: tunneled.tunnelId, originalUrl: tunneled.originalUrl });
-                                return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
-                            }
-                        }
+                        // NOTE: the tunnel health probe used to run right here, immediately
+                        // after ensureTunnel. Under the session-tunnel + Caddy model that is
+                        // WRONG — ensureTunnel only confirms the tunnel reaches Caddy, not
+                        // that Caddy is pointed at THIS target's port yet (that's
+                        // acquirePortRoute's job, per-group, below). Probing here would
+                        // probe whatever port Caddy happened to be pointed at a moment ago
+                        // (often the placeholder, on a session's first call), not this
+                        // target's port — see utils/tunnelContext.ts's acquirePortRoute
+                        // doc comment. Moved to right after acquirePortRoute succeeds.
                         targetContexts.push(tunneled);
                     }
                 }
@@ -181,140 +199,235 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                 `Ensure the backend has that template seeded and accessible ` +
                 `(GET /api/v1/workflows/?slug=${templateSlug}).`);
         }
-        // ── Build contextData (camelCase; axiosTransport snake_cases on the wire) ──
-        // Backend's browser.setup node (shared with App Evaluation + Raw Crawl
-        // templates) requires `target_url` (singular). The Page Probe template
-        // currently uses that node as-is — the per-target loop primitive is
-        // pending. Send BOTH:
-        //   - targetUrl: first target's tunneled URL (satisfies browser.setup
-        //     today; will keep working when the loop wraps it later)
-        //   - targets[]: the full per-URL config for when the loop primitive
-        //     ships and iterates over them
-        const firstTargetUrl = targetContexts[0]?.targetUrl ?? input.targets[0].url;
-        const contextData = {
-            targetUrl: firstTargetUrl,
-            targets: input.targets.map((t, i) => ({
-                url: targetContexts[i].targetUrl ?? t.url,
-                // Send null (not undefined) for optional fields so the field exists
-                // in the target object even when the caller didn't pass one. Backend
-                // placeholder resolver was fixed in commit 154e1e69 to type-preserve
-                // null in single-placeholder substitutions, so null flows through.
-                waitForSelector: t.waitForSelector ?? null,
-                waitForLoadState: t.waitForLoadState,
-                timeoutMs: t.timeoutMs,
-            })),
-            // Backend's browser.capture template binds {{include_dom}} and
-            // {{include_screenshot}} from contextData (verified 2026-04-29).
-            // The MCP-facing schema keeps `includeHtml` / `captureScreenshots`
-            // for caller ergonomics; we just map them to what the template wants.
-            includeDom: input.includeHtml,
-            includeScreenshot: input.captureScreenshots,
-            // Keep the original keys too for any downstream node that reads them
-            // (cheap to send, future-proof against template field-name churn).
-            includeHtml: input.includeHtml,
-            captureScreenshots: input.captureScreenshots,
-        };
-        // ── Execute ────────────────────────────────────────────────────────────
+        // ── Group targets by shared Caddy route (§4 multi-port batch decision) ──
+        // Single-group batches (the common case — one port, or all-public) behave
+        // EXACTLY as before: one repoint (if localhost), one backend execution.
+        // Multi-group batches decompose into one sequential
+        // acquirePortRoute → executeWorkflow(subset) → poll → releasePortRoute
+        // cycle per group — slower (N backend round-trips) but correct, rather
+        // than hard-rejecting a batch shape that worked when it was single-port.
+        const groups = groupTargetsByRoute(targetContexts);
+        // ── Execute (queuing progress step, once — shared across all groups) ───
         if (progressCallback) {
             await progressCallback({ progress: ++progressStep, total: TOTAL_STEPS, message: 'Queuing workflow execution...' });
         }
-        const executeResponse = await client.workflows.executeWorkflow(templateUuid, contextData);
-        const executionUuid = executeResponse.executionUuid;
-        logger.info(`Probe execution queued: ${executionUuid}`);
-        // ── Poll ───────────────────────────────────────────────────────────────
-        let lastCompleted = -1;
-        const finalExecution = await client.workflows.pollExecution(executionUuid, async (exec) => {
-            // Keep all active tunnels alive during polling.
-            for (const tc of targetContexts) {
-                if (tc.tunnelId)
-                    touchTunnelById(tc.tunnelId);
-            }
-            if (!progressCallback)
-                return;
-            const completedNodes = (exec.nodeExecutions ?? []).filter(n => n.nodeType === 'browser.capture' && n.status === 'success').length;
-            if (completedNodes !== lastCompleted) {
-                lastCompleted = completedNodes;
-                await progressCallback({
-                    progress: Math.min(progressStep + completedNodes, TOTAL_STEPS - 1),
-                    total: TOTAL_STEPS,
-                    message: `Probed ${completedNodes}/${input.targets.length} target${input.targets.length === 1 ? '' : 's'}...`,
+        const results = new Array(input.targets.length);
+        const captureDataByIndex = new Array(input.targets.length);
+        const executionIds = [];
+        const browserSessions = [];
+        let lastExecutionDurationMs;
+        let completedOffset = 0;
+        for (const group of groups) {
+            // §2.4: acquire this session's shared Caddy route for the group's port
+            // BEFORE dispatching — held for the group's whole execute+poll cycle,
+            // not just the repoint. No-op (undefined) for the 'public' group.
+            let groupCtx;
+            if (group.needsRoute) {
+                const representative = targetContexts[group.indices[0]];
+                groupCtx = await acquirePortRoute(representative, {
+                    callId: `${callId}:${group.key}`,
+                    signal: abortController.signal,
+                    onWaitProgress: progressCallback
+                        ? async (info) => {
+                            await progressCallback({
+                                progress: Math.min(progressStep + completedOffset, TOTAL_STEPS - 1),
+                                total: TOTAL_STEPS,
+                                message: `Waiting for shared tunnel — port ${info.blockingPort} is in use (waited ${Math.round(info.waitedMs / 1000)}s)...`,
+                            });
+                        }
+                        : undefined,
                 });
             }
-        }, abortController.signal);
-        // ── Format response ────────────────────────────────────────────────────
-        const duration = Date.now() - startTime;
-        const captureNodes = (finalExecution.nodeExecutions ?? [])
-            .filter(n => n.nodeType === 'browser.capture')
-            .sort((a, b) => a.executionOrder - b.executionOrder);
-        const results = [];
-        for (let i = 0; i < input.targets.length; i++) {
-            const target = input.targets[i];
-            const node = captureNodes[i];
-            const data = node?.outputData ?? {};
-            // Backend (post-154e1e69) emits browser.capture output_data with:
-            //   captured_url, status_code, title, load_time_ms,
-            //   console_slice (already per-capture, in {text, level, location, timestamp} shape),
-            //   network_summary (already pre-aggregated by FULL URL,
-            //                    in {url, count, methods[], statuses{}, resource_types[]} shape),
-            //   surfer_page_uuid (reference to SurferPage row for screenshot/title/visible_text),
-            //   error
-            // axiosTransport snake→camel'd at the wire, so JS-side these are
-            // capturedUrl / consoleSlice / networkSummary / surferPageUuid / etc.
-            // Re-aggregate networkSummary by origin+pathname so refetch loops
-            // collapse (preserves the original client-feedback contract).
-            const result = {
-                url: target.url, // ORIGINAL caller URL — not the tunneled rewrite
-                finalUrl: typeof data.capturedUrl === 'string' ? data.capturedUrl
-                    : typeof data.finalUrl === 'string' ? data.finalUrl
-                        : typeof data.url === 'string' ? data.url
-                            : target.url,
-                statusCode: typeof data.statusCode === 'number' ? data.statusCode : 0,
-                title: typeof data.title === 'string' ? data.title : null,
-                loadTimeMs: typeof data.loadTimeMs === 'number' ? data.loadTimeMs : 0,
-                consoleErrors: mapConsoleSlice(Array.isArray(data.consoleSlice) ? data.consoleSlice : []),
-                networkSummary: reaggregateByOriginPath(Array.isArray(data.networkSummary) ? data.networkSummary : []),
-            };
-            if (input.includeHtml && typeof data.html === 'string') {
-                result.html = data.html;
-            }
-            if (typeof data.error === 'string' && data.error) {
-                result.error = data.error;
+            try {
+                // Tunnel health probe: catch the IPv4/IPv6 bind / dead-server case
+                // before committing to a full backend execution. Must run AFTER
+                // acquirePortRoute (above) confirms Caddy is actually pointed at this
+                // group's port — probing any earlier would probe whatever port Caddy
+                // happened to be pointed at a moment ago, not this one (see
+                // utils/tunnelContext.ts's acquirePortRoute doc comment).
+                if (groupCtx?.targetUrl) {
+                    const health = await probeTunnelHealth(groupCtx.targetUrl);
+                    if (!health.healthy) {
+                        const payload = {
+                            error: 'TunnelTrafficBlocked',
+                            message: `Tunnel established but traffic isn't reaching the dev server. ${health.detail ?? ''}`,
+                            detail: {
+                                code: health.code,
+                                status: health.status,
+                                ngrokErrorCode: health.ngrokErrorCode,
+                                elapsedMs: health.elapsedMs,
+                            },
+                        };
+                        // Evict ONLY on a code proving the endpoint is gone; every other
+                        // failure keeps the tunnel we are already paying for, since a
+                        // teardown+re-provision costs two billed hours and this probe
+                        // cannot tell a dead endpoint from a transient edge flake. See
+                        // utils/tunnelDisposition.ts for the allowlist and the evidence.
+                        disposeUnhealthyTunnel({ health, tunnelId: groupCtx.tunnelId, originalUrl: groupCtx.originalUrl });
+                        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
+                    }
+                }
+                // ── Build contextData for THIS group's subset (camelCase; axiosTransport
+                // snake_cases on the wire) ──────────────────────────────────────────
+                // Backend's browser.setup node (shared with App Evaluation + Raw Crawl
+                // templates) requires `target_url` (singular). Send BOTH:
+                //   - targetUrl: this group's first target's tunneled URL (satisfies
+                //     browser.setup today; will keep working when the loop wraps it later)
+                //   - targets[]: the full per-URL config for when the loop primitive
+                //     ships and iterates over them
+                const groupTargets = group.indices.map(i => input.targets[i]);
+                const firstTargetUrl = targetContexts[group.indices[0]]?.targetUrl ?? groupTargets[0].url;
+                const contextData = {
+                    targetUrl: firstTargetUrl,
+                    targets: group.indices.map(i => ({
+                        url: targetContexts[i].targetUrl ?? input.targets[i].url,
+                        // Send null (not undefined) for optional fields so the field exists
+                        // in the target object even when the caller didn't pass one. Backend
+                        // placeholder resolver was fixed in commit 154e1e69 to type-preserve
+                        // null in single-placeholder substitutions, so null flows through.
+                        waitForSelector: input.targets[i].waitForSelector ?? null,
+                        waitForLoadState: input.targets[i].waitForLoadState,
+                        timeoutMs: input.targets[i].timeoutMs,
+                    })),
+                    // Backend's browser.capture template binds {{include_dom}} and
+                    // {{include_screenshot}} from contextData (verified 2026-04-29).
+                    // The MCP-facing schema keeps `includeHtml` / `captureScreenshots`
+                    // for caller ergonomics; we just map them to what the template wants.
+                    includeDom: input.includeHtml,
+                    includeScreenshot: input.captureScreenshots,
+                    // Keep the original keys too for any downstream node that reads them
+                    // (cheap to send, future-proof against template field-name churn).
+                    includeHtml: input.includeHtml,
+                    captureScreenshots: input.captureScreenshots,
+                };
+                const executeResponse = await client.workflows.executeWorkflow(templateUuid, contextData);
+                const executionUuid = executeResponse.executionUuid;
+                executionIds.push(executionUuid);
+                logger.info(`Probe execution queued: ${executionUuid} (group ${group.key}, ${group.indices.length} target(s))`);
+                // ── Poll ───────────────────────────────────────────────────────────
+                let lastCompletedInGroup = -1;
+                const finalExecution = await client.workflows.pollExecution(executionUuid, async (exec) => {
+                    // Keep this group's active tunnels alive during polling.
+                    for (const i of group.indices) {
+                        const tunnelId = targetContexts[i].tunnelId;
+                        if (tunnelId)
+                            touchTunnelById(tunnelId);
+                    }
+                    if (!progressCallback)
+                        return;
+                    const completedNodes = (exec.nodeExecutions ?? []).filter(n => n.nodeType === 'browser.capture' && n.status === 'success').length;
+                    if (completedNodes !== lastCompletedInGroup) {
+                        lastCompletedInGroup = completedNodes;
+                        const totalCompleted = completedOffset + completedNodes;
+                        await progressCallback({
+                            progress: Math.min(progressStep + totalCompleted, TOTAL_STEPS - 1),
+                            total: TOTAL_STEPS,
+                            message: `Probed ${totalCompleted}/${input.targets.length} target${input.targets.length === 1 ? '' : 's'}...`,
+                        });
+                    }
+                }, abortController.signal);
+                lastExecutionDurationMs = finalExecution.durationMs ?? undefined;
+                if (finalExecution.browserSession)
+                    browserSessions.push(finalExecution.browserSession);
+                // ── Format this group's results into the shared, ORIGINAL-order arrays ──
+                const captureNodes = (finalExecution.nodeExecutions ?? [])
+                    .filter(n => n.nodeType === 'browser.capture')
+                    .sort((a, b) => a.executionOrder - b.executionOrder);
+                for (let gi = 0; gi < group.indices.length; gi++) {
+                    const originalIndex = group.indices[gi];
+                    const target = input.targets[originalIndex];
+                    const node = captureNodes[gi];
+                    const data = node?.outputData ?? {};
+                    captureDataByIndex[originalIndex] = data;
+                    // Backend (post-154e1e69) emits browser.capture output_data with:
+                    //   captured_url, status_code, title, load_time_ms,
+                    //   console_slice (already per-capture, in {text, level, location, timestamp} shape),
+                    //   network_summary (already pre-aggregated by FULL URL,
+                    //                    in {url, count, methods[], statuses{}, resource_types[]} shape),
+                    //   surfer_page_uuid (reference to SurferPage row for screenshot/title/visible_text),
+                    //   error
+                    // axiosTransport snake→camel'd at the wire, so JS-side these are
+                    // capturedUrl / consoleSlice / networkSummary / surferPageUuid / etc.
+                    // Re-aggregate networkSummary by origin+pathname so refetch loops
+                    // collapse (preserves the original client-feedback contract).
+                    const result = {
+                        url: target.url, // ORIGINAL caller URL — not the tunneled rewrite
+                        finalUrl: typeof data.capturedUrl === 'string' ? data.capturedUrl
+                            : typeof data.finalUrl === 'string' ? data.finalUrl
+                                : typeof data.url === 'string' ? data.url
+                                    : target.url,
+                        statusCode: typeof data.statusCode === 'number' ? data.statusCode : 0,
+                        title: typeof data.title === 'string' ? data.title : null,
+                        loadTimeMs: typeof data.loadTimeMs === 'number' ? data.loadTimeMs : 0,
+                        consoleErrors: mapConsoleSlice(Array.isArray(data.consoleSlice) ? data.consoleSlice : []),
+                        networkSummary: reaggregateByOriginPath(Array.isArray(data.networkSummary) ? data.networkSummary : []),
+                    };
+                    if (input.includeHtml && typeof data.html === 'string') {
+                        result.html = data.html;
+                    }
+                    if (typeof data.error === 'string' && data.error) {
+                        result.error = data.error;
+                    }
+                    if (typeof data.surferPageUuid === 'string' && data.surferPageUuid) {
+                        result.surferPageUuid = data.surferPageUuid;
+                    }
+                    // Bead debugg_ai_mcp-6cfv.6 fix: sanitize each result against ITS
+                    // OWN target's tunnel context, never the whole accumulated payload.
+                    // Under the old per-port-tunnel model every target had a distinct
+                    // hostname, so rewriting the whole payload on each pass was safe by
+                    // accident. Under the new session-tunnel model every localhost
+                    // target in a batch can share ONE hostname — sanitizing the whole
+                    // payload with target A's context would also rewrite target B's own
+                    // (correct) occurrences, a cross-target data leak. Scoping the
+                    // sanitize call to `result`'s own subtree, keyed by `targetContexts[originalIndex]`,
+                    // makes that leak structurally impossible regardless of how many
+                    // targets share a hostname.
+                    const tc = targetContexts[originalIndex];
+                    results[originalIndex] = tc.isLocalhost ? sanitizeResponseUrls(result, tc) : result;
+                }
+                completedOffset += group.indices.length;
             }
-            if (typeof data.surferPageUuid === 'string' && data.surferPageUuid) {
-                result.surferPageUuid = data.surferPageUuid;
+            finally {
+                if (groupCtx)
+                    releasePortRoute(groupCtx);
             }
-            results.push(result);
         }
+        // ── Format response ────────────────────────────────────────────────────
+        const duration = Date.now() - startTime;
         const responsePayload = {
-            executionId: executionUuid,
-            durationMs: typeof finalExecution.durationMs === 'number' ? finalExecution.durationMs : duration,
+            executionId: executionIds[0],
+            // Single-group batches (every existing caller) keep the exact prior
+            // semantics: the backend's own reported durationMs when present, wall
+            // clock otherwise. Multi-group batches use wall clock — summing/picking
+            // among several backend-reported per-execution durations would be
+            // misleading, since the executions ran sequentially, not concurrently.
+            durationMs: groups.length === 1 && typeof lastExecutionDurationMs === 'number'
+                ? lastExecutionDurationMs
+                : duration,
             results,
         };
-        if (finalExecution.browserSession) {
-            responsePayload.browserSession = finalExecution.browserSession;
+        // Multi-group batches ran more than one backend execution — surface all
+        // of their ids/sessions additively, without changing the single-group
+        // (single-execution) response shape any existing caller already parses.
+        if (executionIds.length > 1)
+            responsePayload.executionIds = executionIds;
+        if (browserSessions.length === 1) {
+            responsePayload.browserSession = browserSessions[0];
         }
-        // Sanitize ngrok URLs from the entire payload — agent-authored strings in
-        // node outputData (titles, HTML, console messages from the page itself)
-        // can occasionally contain the tunnel URL; rewrite to the original
-        // localhost origin per tunnel context. For multi-localhost batches we
-        // run sanitize once per localhost target since each may have its own
-        // tunnel↔origin mapping.
-        let sanitizedPayload = responsePayload;
-        for (const tc of targetContexts) {
-            if (tc.isLocalhost) {
-                sanitizedPayload = sanitizeResponseUrls(sanitizedPayload, tc);
-            }
+        else if (browserSessions.length > 1) {
+            responsePayload.browserSessions = browserSessions;
         }
         logger.toolComplete('probe_page', duration);
         const responseContent = [
-            { type: 'text', text: JSON.stringify(sanitizedPayload, null, 2) },
+            { type: 'text', text: JSON.stringify(responsePayload, null, 2) },
         ];
         // Embed screenshots when captureScreenshots is true. The backend may return
         // screenshotB64 or a URL-keyed field on browser.capture outputData.
         if (input.captureScreenshots) {
             const SCREENSHOT_URL_KEYS = ['screenshotB64', 'screenshot', 'screenshotUrl', 'screenshotUri', 'finalScreenshot'];
-            for (const node of captureNodes) {
-                const data = node?.outputData ?? {};
+            for (const data of captureDataByIndex) {
+                if (!data)
+                    continue;
                 if (typeof data.screenshotB64 === 'string' && data.screenshotB64) {
                     responseContent.push(imageContentBlock(data.screenshotB64, 'image/png'));
                 }

package/dist/handlers/runTestSuiteHandler.js

@@ -5,7 +5,8 @@ import { TunnelProvisionError } from '../services/tunnels.js';
 import { disposeUnhealthyTunnel } from '../utils/tunnelDisposition.js';
 import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js';
 import { extractLocalhostPort } from '../utils/urlParser.js';
-import { buildContext, findExistingTunnel, ensureTunnel } from '../utils/tunnelContext.js';
+import { buildContext, sanitizeResponseUrls } from '../utils/tunnelContext.js';
+import { tunnelManager } from '../services/ngrok/tunnelManager.js';
 import { config } from '../config/index.js';
 import { resolveProject, resolveTestSuite } from '../utils/resolveProject.js';
 const logger = new Logger({ module: 'runTestSuiteHandler' });
@@ -19,6 +20,13 @@ export async function runTestSuiteHandler(input, _context) {
     await client.init();
     let acquiredKeyId = null;
     let tunnelId;
+    // Used ONLY to scope the defensive sanitizeResponseUrls call below (bead
+    // debugg_ai_mcp-6cfv.7) — never fed into acquirePortRoute/PortLock. This
+    // handler is fire-and-forget (no poll loop, no bounded window to hold the
+    // shared session lock over — see the acquireDedicatedTunnel call below), so
+    // it deliberately does NOT go through findExistingTunnel/ensureTunnel/
+    // acquirePortRoute at all (§2.3's named, deliberate exception).
+    let sanitizeCtx;
     try {
         let suiteUuid = input.suiteUuid;
         if (!suiteUuid) {
@@ -51,68 +59,79 @@ export async function runTestSuiteHandler(input, _context) {
                     logger.info(`run_test_suite: dev mode — using localhost URL directly: ${input.targetUrl}`);
                 }
                 else {
-                    // Reuse an existing tunnel for this port if one is already active.
-                    const reused = findExistingTunnel(ctx);
-                    if (reused) {
-                        effectiveTargetUrl = reused.targetUrl ?? input.targetUrl;
-                        tunnelId = reused.tunnelId;
+                    // §2.3: run_test_suite is the ONE named, deliberate exception to
+                    // "one tunnel per session" — it is fire-and-forget (dispatches
+                    // client.runTestSuite() below and returns; the tests it triggers
+                    // keep using this tunnel on the BACKEND for possibly many more
+                    // minutes, entirely outside this process's poll loop, because
+                    // there IS no poll loop). Sharing the session's Caddy-routed tunnel
+                    // and its PortLock would give this handler no real protection —
+                    // the lock would release back to contention seconds after
+                    // triggering a suite that goes on to use the port for much longer.
+                    // So it gets its OWN tunnel, dialing ngrok directly, bypassing
+                    // Caddy/PortLock entirely (never deduped/reused — always fresh).
+                    let tunnel;
+                    try {
+                        tunnel = await client.tunnels.provisionWithRetry();
                     }
-                    else {
-                        // Provision a new tunnel.
-                        let tunnel;
-                        try {
-                            tunnel = await client.tunnels.provisionWithRetry();
-                        }
-                        catch (provisionError) {
-                            const msg = provisionError instanceof Error ? provisionError.message : String(provisionError);
-                            const diag = provisionError instanceof TunnelProvisionError ? ` ${provisionError.diagnosticSuffix()}` : '';
-                            return errorResp('TunnelProvisionFailed', `Failed to provision tunnel for ${input.targetUrl}. (Detail: ${msg})${diag}`);
-                        }
-                        acquiredKeyId = tunnel.keyId;
-                        let tunneled;
-                        try {
-                            tunneled = await ensureTunnel(ctx, tunnel.tunnelKey, tunnel.tunnelId, tunnel.keyId, () => client.revokeNgrokKey(tunnel.keyId));
-                        }
-                        catch (tunnelError) {
-                            const msg = tunnelError instanceof Error ? tunnelError.message : String(tunnelError);
-                            return errorResp('TunnelCreationFailed', `Tunnel creation failed for ${input.targetUrl}. (Detail: ${msg})`);
-                        }
-                        // Health probe — catches ERR_NGROK_8012 and bind mismatches before
-                        // the remote agent wastes steps trying to reach the server.
-                        if (tunneled.targetUrl) {
-                            const health = await probeTunnelHealth(tunneled.targetUrl);
-                            if (!health.healthy) {
-                                // Brought in line with the other three handlers, which this one never
-                                // was (it evicted on EVERY failure and never got bead k34o's shared-
-                                // registry eviction). Evict only on a code proving the endpoint is
-                                // gone: a transient edge flake must not cost two billed hours.
-                                // See utils/tunnelDisposition.ts.
-                                disposeUnhealthyTunnel({ health, tunnelId: tunneled.tunnelId, originalUrl: ctx.originalUrl });
-                                // Record the tunnel so the finally block's orphaned-key revoke can't
-                                // fire: the tunnel we just kept is authenticated with that key, and
-                                // revoking a live tunnel's credential would kill what we preserved.
-                                // (On the eviction branch markTunnelDead already revokes it.)
-                                tunnelId = tunneled.tunnelId;
-                                return errorResp('TunnelTrafficBlocked', `Tunnel established but traffic isn't reaching the dev server. ${health.detail ?? ''}`, { code: health.code, ngrokErrorCode: health.ngrokErrorCode, elapsedMs: health.elapsedMs });
-                            }
+                    catch (provisionError) {
+                        const msg = provisionError instanceof Error ? provisionError.message : String(provisionError);
+                        const diag = provisionError instanceof TunnelProvisionError ? ` ${provisionError.diagnosticSuffix()}` : '';
+                        return errorResp('TunnelProvisionFailed', `Failed to provision tunnel for ${input.targetUrl}. (Detail: ${msg})${diag}`);
+                    }
+                    acquiredKeyId = tunnel.keyId;
+                    let dedicated;
+                    try {
+                        dedicated = await tunnelManager.acquireDedicatedTunnel(ctx.originalUrl, tunnel.tunnelKey, tunnel.keyId, () => client.revokeNgrokKey(tunnel.keyId));
+                    }
+                    catch (tunnelError) {
+                        const msg = tunnelError instanceof Error ? tunnelError.message : String(tunnelError);
+                        return errorResp('TunnelCreationFailed', `Tunnel creation failed for ${input.targetUrl}. (Detail: ${msg})`);
+                    }
+                    // Health probe — catches ERR_NGROK_8012 and bind mismatches before
+                    // the remote agent wastes steps trying to reach the server.
+                    if (dedicated.url) {
+                        const health = await probeTunnelHealth(dedicated.url);
+                        if (!health.healthy) {
+                            // Brought in line with the other three handlers, which this one never
+                            // was (it evicted on EVERY failure and never got bead k34o's shared-
+                            // registry eviction). Evict only on a code proving the endpoint is
+                            // gone: a transient edge flake must not cost two billed hours.
+                            // See utils/tunnelDisposition.ts.
+                            disposeUnhealthyTunnel({ health, tunnelId: dedicated.tunnelId, originalUrl: ctx.originalUrl });
+                            // Record the tunnel so the finally block's orphaned-key revoke can't
+                            // fire: the tunnel we just kept is authenticated with that key, and
+                            // revoking a live tunnel's credential would kill what we preserved.
+                            // (On the eviction branch markTunnelDead already revokes it.)
+                            tunnelId = dedicated.tunnelId;
+                            return errorResp('TunnelTrafficBlocked', `Tunnel established but traffic isn't reaching the dev server. ${health.detail ?? ''}`, { code: health.code, ngrokErrorCode: health.ngrokErrorCode, elapsedMs: health.elapsedMs });
                         }
-                        effectiveTargetUrl = tunneled.targetUrl ?? input.targetUrl;
-                        tunnelId = tunneled.tunnelId;
                     }
+                    effectiveTargetUrl = dedicated.url;
+                    tunnelId = dedicated.tunnelId;
+                    sanitizeCtx = { ...ctx, tunnelId: dedicated.tunnelId, targetUrl: dedicated.url };
                     logger.info(`run_test_suite: localhost detected, tunneled ${input.targetUrl} → ${effectiveTargetUrl}`);
                 }
             }
         }
         const result = await client.runTestSuite(suiteUuid, { targetUrl: effectiveTargetUrl });
         logger.toolComplete('run_test_suite', Date.now() - start);
+        const responsePayload = {
+            ...result,
+            ...(tunnelId ? { tunnelActive: true, originalUrl: input.targetUrl } : {}),
+            note: 'Tests are running asynchronously. Use get_test_suite_results to check progress.',
+        };
+        // Bead debugg_ai_mcp-6cfv.7: this handler previously had NO sanitize call
+        // at all — safe only by accident of `result`'s narrow return type never
+        // having carried a tunnel hostname in practice. Add the same defensive
+        // pass every other handler already runs, so a future backend field that
+        // echoes back the (dedicated, ngrok-direct) tunnel URL can never leak it
+        // to a caller who only knows their own localhost address.
+        const sanitizedPayload = sanitizeCtx ? sanitizeResponseUrls(responsePayload, sanitizeCtx) : responsePayload;
         return {
             content: [{
                     type: 'text',
-                    text: JSON.stringify({
-                        ...result,
-                        ...(tunnelId ? { tunnelActive: true, originalUrl: input.targetUrl } : {}),
-                        note: 'Tests are running asynchronously. Use get_test_suite_results to check progress.',
-                    }, null, 2),
+                    text: JSON.stringify(sanitizedPayload, null, 2),
                 }],
         };
     }