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

package/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to the DebuggAI MCP project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased] — BREAKING
+
+### Changed — one ngrok tunnel per session instead of one per local port
+
+`check_app_in_browser`, `probe_page`, and `trigger_crawl` now share a **single**
+ngrok tunnel per session (keyed per-caller on HTTP transport, so different
+callers never share state), backed by a local Caddy reverse proxy that gets
+repointed at whichever local port a call targets immediately before dispatch.
+Previously every distinct local port tested in a session opened its own ngrok
+tunnel — N ports meant N billed tunnels. Full design:
+`docs/local-tunnel-multiplexer-architecture-2026-07-31.md`.
+
+This replaces (not extends) a Feb 2026 attempt at the same goal that used
+path-prefix routing (`/p/{port}/*`) and broke on any root-absolute asset/API
+path (`/api/...`, `/_next/...` — the default in most modern frameworks). The
+new design routes through a single dynamic upstream with zero path/host
+rewriting, so that failure mode is structurally impossible rather than patched.
+A live-browser regression test for exactly this case now exists and passes
+(`__tests__/integration/caddyProxy.test.ts`).
+
+**New runtime dependency, auto-installed:** `check_app_in_browser`/`probe_page`/`trigger_crawl`
+now need the `caddy` binary for any `http://localhost:...` call. It installs itself — the
+`@radically-straightforward/caddy` npm dependency downloads a pinned Caddy release (`2.11.3`) for
+your platform during `npm install`/`npx`, the same pattern this project already uses for the
+`ngrok` binary. Falls back to `CADDY_BIN` (or a system `caddy` on `PATH`) if that download never
+ran (`npm install --ignore-scripts`, offline install) — fails fast with a clear
+`CaddyBinaryNotFoundError` rather than a silent hang if none of those resolve.
+`test_suite {action:"run"}` is unaffected either way (dedicated per-run tunnel, bypasses Caddy).
+
+**Deployment precondition for HTTP transport:** multi-replica deployments that
+want the one-tunnel-per-session guarantee need session-affine load-balancer
+routing (consistent hash / sticky on the caller's bearer token). Without it,
+tunnel count degrades to bounded, cost-only over-provisioning (never a
+correctness issue) — see architecture doc §2.1.
+
+### Fixed — two latent response-sanitization bugs surfaced by the above
+
+- `probe_page` multi-target batches could cross-attribute a tunnel-hostname
+  rewrite from one target's result onto another's once targets started sharing
+  a session hostname (they didn't, before this change).
+- `run_test_suite` had no defensive URL-sanitization call at all.
+
 ## [3.5.1]
 
 ### Fixed — default OAuth issuer points at the Django AS

package/README.md

@@ -10,6 +10,18 @@ AI-powered browser testing via the [Model Context Protocol](https://modelcontext
 
 **Requires Node.js 20.20.0 or later** (transitive requirement from `posthog-node@^5.26.0`).
 
+**Testing `http://localhost:...` URLs requires the `caddy` binary** — `check_app_in_browser`,
+`probe_page`, and `trigger_crawl` tunnel localhost targets through a local Caddy reverse proxy.
+This installs automatically: the `@radically-straightforward/caddy` npm dependency downloads a
+pinned Caddy release for your platform during `npm install`/`npx`, same as this project already
+does for the `ngrok` binary — nothing to install yourself in the normal case. If that download
+never ran (`npm install --ignore-scripts`, an offline/air-gapped install), point `CADDY_BIN` at
+your own install (`brew install caddy` / `apt install caddy` / see
+[caddyserver.com/docs/install](https://caddyserver.com/docs/install)) — missing it surfaces as a
+clear error on the first localhost-URL call, not a silent hang. Public-URL calls, every
+non-browser tool, and `test_suite {action:"run"}` (which uses its own dedicated tunnel and
+bypasses Caddy entirely) don't need it either way.
+
 Get an API key at [debugg.ai](https://debugg.ai), then add to your MCP client config:
 
 ```json
@@ -32,6 +44,17 @@ Or with Docker:
 docker run -i --rm --init -e DEBUGGAI_API_KEY=your_api_key quinnosha/debugg-ai-mcp
 ```
 
+The `Dockerfile`'s `npm install` step would pick up `caddy` the same automatic way local installs
+do, in principle — but as of this writing the `Dockerfile` doesn't `COPY` several directories the
+build now needs (`handlers`, `tools`, `types`, `config`) and still references a `tunnels/`
+directory that no longer exists, so a fresh build likely fails before that matters. That's a
+pre-existing gap, unrelated to Caddy. The **currently published** `quinnosha/debugg-ai-mcp` image
+predates the Caddy dependency regardless — localhost-URL calls to
+`check_app_in_browser`/`probe_page`/`trigger_crawl` will fail with `CaddyBinaryNotFoundError`
+inside that image until it's rebuilt (Dockerfile fixed) and republished, or `CADDY_BIN` points at
+one baked in separately. Public-URL calls, the non-browser tools, and `test_suite {action:"run"}`
+are unaffected either way.
+
 ## Tools
 
 The server exposes **8** tools: three **Browser** tools plus one **action-based** tool per managed entity. The headline tools are `check_app_in_browser` (full AI agent) and `probe_page` (lightweight no-LLM page probe). The rest — `project`, `environment`, `test_suite`, `test_case`, `executions` — each take an `action` discriminator (e.g. `{"action":"list"}`) that selects the operation. Destructive `delete` actions require confirmation (an elicitation prompt where supported, otherwise `confirm: true`).
@@ -117,7 +140,7 @@ Fires a server-side browser-agent crawl to populate the project's knowledge grap
 | `includeHtml` | boolean | Return raw HTML in each result (default false) |
 | `captureScreenshots` | boolean | Return one PNG per target (default true) |
 
-The whole batch shares a single backend execution + browser session + tunnel — 5 URLs in one call is dramatically faster than 5 parallel single-URL calls. Per-URL `error` field preserves batch resilience: a single failed target doesn't fail the others.
+All targets in a batch share one session tunnel, but only same-port (or all-public) batches share a **single** backend execution — 5 URLs on one port in one call is dramatically faster than 5 parallel single-URL calls. A batch that mixes multiple **local** ports decomposes into one sequential backend execution per port group (still one call, still one merged `results[]` in your original order, but N backend round-trips instead of one — slower, not rejected). Per-URL `error` field preserves batch resilience: a single failed target doesn't fail the others.
 
 **`networkSummary` aggregation key is `origin + pathname`** — refetch loops (`?n=0..4` repeatedly hitting the same endpoint) collapse into a single entry with the count, so `/api/poll` showing up with `count: 47` is the actionable "infinite refetch loop" signal users originally asked for.
 
@@ -294,6 +317,19 @@ flow against the advertised authorization server. The bearer is request-scoped
 
 stdio installs need none of these.
 
+**Multi-replica deployments (go/no-go before rollout):** tunnel state (the ngrok session tunnel,
+its Caddy instance, and its port-route lock) is in-process, keyed per caller by a hash of the
+bearer token — there is no cross-process coordination. Running several replicas behind a plain
+round-robin load balancer means one caller's calls can land on different replicas and mint one
+tunnel **per replica they hit** instead of one for the whole session (extra ngrok cost, bounded by
+replica count, self-healing via the existing 55-minute idle auto-shutoff — never a cross-session
+correctness bug, since any single tool call stays on one replica for its whole duration). To get
+the intended "one tunnel per session" behavior on a multi-replica HTTP deployment, configure
+**session-affine routing** at the load balancer (sticky/consistent-hash keyed on the same identity
+`getSessionKey()` derives — in practice, the caller's `Authorization` bearer token). See
+`docs/local-tunnel-multiplexer-architecture-2026-07-31.md` §2.1 for the full reasoning and the
+honest degrade path if this isn't configured.
+
 ## Telemetry
 
 The MCP server ships with telemetry enabled by default — an embedded write-only PostHog project key (`phc_*`) so the team can observe cache hit rates, poll cadence, tunnel reliability, and other operational metrics across the install base. Captured events:

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'));
                 }