@debugg-ai/debugg-ai-mcp 3.7.1 → 3.7.2

package/dist/handlers/testPageChangesHandler.js

@@ -14,7 +14,7 @@ import { TunnelProvisionError } from '../services/tunnels.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 import { detectRepoName } from '../utils/gitContext.js';
 import { tunnelManager } from '../services/ngrok/tunnelManager.js';
-import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js';
+import { probeLocalPort, probeTunnelHealth, extractNgrokErrorCode } from '../utils/localReachability.js';
 import { extractLocalhostPort } from '../utils/urlParser.js';
 import { getCachedTemplateUuid, getCachedProjectUuid, invalidateTemplateCache, invalidateProjectCache, } from '../utils/handlerCaches.js';
 import { isTransientWorkflowError, transientReasonTag } from '../utils/transientErrors.js';
@@ -33,6 +33,28 @@ function getMaxTransientRetries() {
         return 1;
     return Math.min(n, 3);
 }
+// Bug z15n: scan run evidence for ngrok's interstitial marker. The marker is a
+// stable, recognizable string the REMOTE BROWSER saw — positive evidence that it
+// hit our tunnel's error page rather than the user's app. Non-string parts are
+// serialized (the action trace is the usual carrier); a part we can't serialize
+// is simply skipped — it is not evidence either way.
+function findNgrokErrorMarker(parts) {
+    for (const part of parts) {
+        if (part === undefined || part === null || part === '')
+            continue;
+        let text;
+        try {
+            text = typeof part === 'string' ? part : JSON.stringify(part) ?? '';
+        }
+        catch {
+            continue;
+        }
+        const code = extractNgrokErrorCode(text);
+        if (code)
+            return code;
+    }
+    return undefined;
+}
 // Concurrency control — max 2 simultaneous browser checks.
 // Additional requests queue and run when a slot opens.
 const MAX_CONCURRENT = 2;
@@ -99,10 +121,45 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
     // dropped client kept polling for up to ~10 min, holding one of just
     // MAX_CONCURRENT=2 slots. Wiring to context.signal cancels the poll and frees
     // the slot immediately.
+    //
+    // Bead 5er7: aborting the poll frees our slot but does NOT stop the BACKEND
+    // execution — it runs on to its own contextData.timeoutSeconds (720), driving
+    // a real browser session and burning quota with nobody reading the result.
+    // cancelExecution() existed for exactly this and had zero callers. Cancel the
+    // in-flight execution best-effort on abort.
+    //
+    // Contract for the cancel path: NEVER throw and NEVER await. The client is
+    // already gone, so a failed cancel is not worth surfacing, and the abort path
+    // must not delay slot release. Strictly fire-and-forget, rejection swallowed.
+    let clientAborted = false;
+    let currentExecutionUuid = '';
+    const cancelCurrentExecution = () => {
+        // HELD OFF BY DEFAULT (bead 5er7 / sentinal-wmzdf). Cancelling the backend
+        // execution skips its browser teardown, so the BrowserSession row leaks
+        // ACTIVE and permanently burns one of the company's 50 concurrency slots —
+        // a net-negative trade vs. the pre-fix behaviour (poll aborts, backend runs
+        // to its own 720s budget, then teardown runs and the slot is returned:
+        // bounded and self-healing). Read at call time so the flag can be flipped
+        // to 'true' the moment the backend runs teardown on cancel (sentinal-wmzdf).
+        if (process.env.DEBUGGAI_CANCEL_ABANDONED_EXECUTIONS !== 'true')
+            return;
+        const uuid = currentExecutionUuid;
+        if (!uuid)
+            return; // nothing queued yet — never POST cancel/<empty>/
+        currentExecutionUuid = ''; // cancel any given execution at most once
+        try {
+            client.workflows?.cancelExecution(uuid).then(() => logger.info(`Cancelled abandoned execution ${uuid}`), (err) => logger.warn(`Best-effort cancel of abandoned execution ${uuid} failed: ${err}`));
+        }
+        catch (err) {
+            logger.warn(`Best-effort cancel of abandoned execution ${uuid} threw synchronously: ${err}`);
+        }
+    };
     const abortController = new AbortController();
     const onAbort = () => {
+        clientAborted = true;
         abortController.abort();
         progressDisabled = true; // client is gone — stop emitting
+        cancelCurrentExecution();
     };
     const requestSignal = context.signal;
     if (requestSignal) {
@@ -336,7 +393,17 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             }
             executeResponse = await client.workflows.executeWorkflow(templateUuid, contextData, Object.keys(env).length > 0 ? env : undefined);
             executionUuid = executeResponse.executionUuid;
+            // Bead 5er7: this is now the execution an abort must cancel (a retry moves
+            // the target forward; the previous attempt already reached a terminal
+            // state, so there is nothing to cancel there).
+            currentExecutionUuid = executionUuid;
             logger.info(`Execution queued: ${executionUuid}${attempt > 1 ? ` (retry ${attempt - 1}/${MAX_RETRIES})` : ''}`);
+            // The abort can fire BEFORE anything is queued — while provisioning the
+            // tunnel or resolving the template — and there is no abort check between
+            // there and here. Without this, a client that dropped during setup still
+            // gets a ~12-minute browser run queued on its behalf and abandoned.
+            if (clientAborted)
+                cancelCurrentExecution();
             // Closure state — reset PER ATTEMPT so progress numbers don't double-count
             // across retries.
             let lastStepsTaken = 0;
@@ -410,6 +477,13 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                 }
                 await progressCallback({ progress: execProgress, total: TOTAL_STEPS, message });
             }, abortController.signal);
+            // Bead 5er7: pollExecution returned, so the execution reached a terminal
+            // state — there is nothing left to cancel and a late abort (while we shape
+            // the response) must not POST a cancel for finished work. EXCEPTION: on a
+            // poll-deadline timeout the execution may still be running backend-side,
+            // so keep it cancellable.
+            if (!finalExecution.timedOut)
+                currentExecutionUuid = '';
             // Decide retry vs exit: only retry on documented transient signatures
             // AND while we still have budget. Otherwise break and surface whatever
             // result the agent reached.
@@ -496,6 +570,68 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         // Evidence: prefer the backend's contract evidence.actionTrace; fall back to
         // the legacy node-extracted trace while the backend contract deploys.
         const relayActionTrace = verdict.actionTrace ?? actionTrace;
+        // --- Post-hoc tunnel reclassification (bugs z15n, 4bui) ---
+        // The pre-flight probe above proves the tunnel was alive when we handed it to
+        // the remote browser — it can still die mid-run. When it does, the browser
+        // lands on ngrok's ERR_NGROK_* interstitial and the backend, which only sees
+        // "the page didn't contain what I was asked about", returns a normal 'fail'
+        // whose reason blames the USER'S page for OUR dead tunnel (execution
+        // a8f07747: 217s, 7 steps, failureCategory 'fail').
+        //
+        // THE MARKER IS REQUIRED (bug 4bui). Reclassifying overrides the backend's
+        // verdict, so it demands positive evidence of the claim we are actually
+        // making: that the remote browser hit OUR error page DURING THE RUN. Only
+        // the ERR_NGROK_* marker recorded BY the run is evidence of that.
+        //
+        // The re-probe is NOT such evidence and can no longer trigger this on its
+        // own. It answers a different question — "is the tunnel healthy NOW?" —
+        // and we were using its answer to assert something about the run window.
+        // That laundered a genuine UI failure into an infrastructure excuse:
+        // execution 2aa14b0b completed 2.78s BEFORE its upstream was killed (tunnel
+        // alive for 100% of the run, no marker, an honest evidence-strictness
+        // verdict) and we still stamped it TunnelOfflineDuringRun. Worse, the probe
+        // independently returned a FALSE NETWORK_ERROR on healthy servers ~1 in 5
+        // runs (bug k6yq), so the false positive was reachable with nothing
+        // whatsoever wrong. (k6yq is now fixed: the cause was not the suspected DNS
+        // race but an HTTP/2 GOAWAY from the ngrok edge on a freshly created
+        // tunnel, which probeTunnelHealth now retries. The marker requirement
+        // stands on its own regardless — the probe never decides this.)
+        //
+        // Requiring the marker loses no coverage: a real mid-run death fires BOTH
+        // arms (live-confirmed — re-probe NETWORK_ERROR *and* marker ERR_NGROK_3200),
+        // so the marker alone still catches it. The probe is kept purely as
+        // CORROBORATION in `detail` — it tells the caller whether the tunnel is
+        // still down now or has since recovered. Per epic 56kd ("relay honestly,
+        // invent nothing"), asserting an infrastructure fault we did not observe
+        // during the run is the relay inventing a cause.
+        let tunnelFault;
+        if (verdict.outcome === 'fail' && ctx.isLocalhost && ctx.tunnelId && ctx.targetUrl) {
+            const marker = findNgrokErrorMarker([
+                verdict.reason,
+                finalExecution.state?.error,
+                finalExecution.errorMessage,
+                relayActionTrace,
+            ]);
+            // probeTunnelHealth never throws by contract; guard anyway — a probe we
+            // couldn't run is NOT evidence of a fault. Corroboration only: its result
+            // never decides whether we reclassify, only what we report alongside it.
+            const probe = await probeTunnelHealth(ctx.targetUrl).catch(() => undefined);
+            if (marker) {
+                tunnelFault = { probe, ngrokErrorCode: marker };
+                logger.warn(`Reclassifying backend 'fail' as an infrastructure fault for ${executionUuid}: ` +
+                    `the run recorded ${marker} (re-probe now: ` +
+                    `${probe ? (probe.healthy ? 'healthy — tunnel has since recovered' : probe.code) : 'unavailable'})`);
+            }
+            else if (probe && !probe.healthy) {
+                // Deliberately NOT reclassifying. The tunnel looks unhealthy now, but
+                // the run recorded no ngrok interstitial, so we have no evidence the
+                // browser ever saw one — the tunnel most likely died after the run (or
+                // the probe flaked). Relay the backend's verdict and log the tension.
+                logger.info(`Post-run tunnel re-probe for ${executionUuid} was unhealthy (${probe.code}) but the run ` +
+                    'recorded no ERR_NGROK_* marker, so the browser reached the app during the run. Relaying ' +
+                    "the backend's verdict verbatim rather than blaming the tunnel.");
+            }
+        }
         const responsePayload = {
             outcome: verdict.outcome,
             success: verdict.success,
@@ -513,6 +649,44 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             responsePayload.failureCategory = verdict.failureCategory;
         if (verdict.reason)
             responsePayload.reason = verdict.reason;
+        // Bug z15n: OUR tunnel died mid-run, so this 'fail' describes our error page,
+        // not the user's app. Relay it as a distinct, retryable infrastructure class
+        // so an automated caller doesn't record a UI regression that never happened.
+        // The backend's original verdict is preserved verbatim, never swallowed.
+        //
+        // Bug 4bui: the stated cause leads with the MARKER, because the marker is the
+        // evidence that justified getting here — the run itself recorded ngrok's
+        // interstitial. The probe only corroborates (and may legitimately say the
+        // tunnel has recovered by now), so it rides in `detail`, never as the cause.
+        if (tunnelFault) {
+            const { probe, ngrokErrorCode } = tunnelFault;
+            responsePayload.backendVerdict = { outcome: verdict.outcome, reason: verdict.reason };
+            responsePayload.outcome = 'error';
+            responsePayload.success = false;
+            responsePayload.failureCategory = 'infrastructure';
+            responsePayload.error = 'TunnelOfflineDuringRun';
+            responsePayload.message =
+                'During this run the remote browser landed on our tunnel\'s ngrok error page instead of your ' +
+                    'app, so the check evaluated our error page rather than your UI. This is an infrastructure ' +
+                    'fault on our side, not a failed check — retry it. The backend\'s original verdict is ' +
+                    'preserved under `backendVerdict`.';
+            responsePayload.reason =
+                `The run recorded ngrok's ${ngrokErrorCode} interstitial, so the remote browser reached ` +
+                    'our tunnel error page instead of your app.' +
+                    (probe
+                        ? probe.healthy
+                            ? ' (Our re-probe after the run found the tunnel reachable again, so it has since recovered.)'
+                            : ` (Our re-probe after the run also failed: ${probe.code}` +
+                                `${probe.status ? ` (HTTP ${probe.status})` : ''}.)`
+                        : '');
+            responsePayload.detail = {
+                ngrokErrorCode,
+                probeCode: probe?.code,
+                probeStatus: probe?.status,
+                probeHealthy: probe?.healthy,
+                probeElapsedMs: probe?.elapsedMs,
+            };
+        }
         if (Array.isArray(relayActionTrace) && relayActionTrace.length > 0)
             responsePayload.actionTrace = relayActionTrace;
         if (evaluation)
@@ -626,7 +800,10 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                 content.push(link);
             }
         }
-        return { content };
+        // Bug z15n: an infrastructure fault is an error, not a check result — same
+        // posture as the LocalServerUnreachable / TunnelTrafficBlocked pre-checks.
+        // The evidence (screenshot, trace, artifacts) still rides along in `content`.
+        return tunnelFault ? { content, isError: true } : { content };
     }
     catch (error) {
         const duration = Date.now() - startTime;

package/dist/services/ngrok/ngrokAgentSession.js

@@ -0,0 +1,49 @@
+/**
+ * ngrok agent session bootstrap (bead pqgj).
+ *
+ * ngrok's connect() calls its internal getProcess() and then IMMEDIATELY asks
+ * the agent to open a tunnel. But getProcess() resolves as soon as the agent
+ * prints its local API address, which — measured live against agent v3.38.0 —
+ * is ~293ms BEFORE the client session is established:
+ *
+ *   [ 110ms] msg="starting web service" addr=127.0.0.1:4043   <- getProcess resolves
+ *   [ 403ms] msg="client session established"                 <- ~293ms later
+ *
+ * Tunnelling inside that window returns 503 "a successful ngrok tunnel session
+ * has not yet been established". That 503 is retriable and ngrok retries it
+ * internally — but connectRetry() pins opts.name on the first call and reuses
+ * it, so its own retry collides with the tunnel record the 503 left behind:
+ * 400 "invalid tunnel configuration — tunnel already exists". 400 is not
+ * retriable, so it surfaces to us. That is bead pqgj's 100% attempt-1 failure.
+ *
+ * Fix: start the agent and wait for its session BEFORE anyone tunnels.
+ * getProcess() memoizes on a module-level promise, so ngrok's own connect()
+ * then reuses the very agent we started and never re-spawns it.
+ *
+ * getProcess is not in ngrok's package export map ({".": "./index.js"}), hence
+ * the resolved deep require. It is isolated in this module so the reach into
+ * another package's internals is explicit, greppable, and mockable — and so a
+ * version bump that moves it fails HERE, loudly, instead of silently spawning
+ * something unexpected. Callers treat a throw as "no pre-warm available" and
+ * fall back to their connect retry ladder.
+ */
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+/**
+ * Spawn (or reuse) the ngrok agent, wiring the session callbacks.
+ *
+ * Resolves once the agent's local API is up — NOT once the session is live.
+ * Callers await the session via `onStatusChange('connected')`.
+ *
+ * @throws if ngrok's internals cannot be reached (version bump, stubbed module).
+ */
+export const startAgentSession = async (opts) => {
+    const require = createRequire(import.meta.url);
+    const ngrokEntry = require.resolve('ngrok');
+    const processModulePath = join(dirname(ngrokEntry), 'src', 'process.js');
+    const { getProcess } = require(processModulePath);
+    if (typeof getProcess !== 'function') {
+        throw new Error(`ngrok getProcess() not found at ${processModulePath}`);
+    }
+    await getProcess(opts);
+};

package/dist/services/ngrok/tunnelManager.js

@@ -22,6 +22,7 @@ import { isLocalhostUrl, extractLocalhostPort, generateTunnelUrl } from '../../u
 import { v4 as uuidv4 } from 'uuid';
 import { FaultInjector, TunnelTrace, getFaultModeFromEnv } from './tunnelFaultInjection.js';
 import { getDefaultRegistry, } from './tunnelRegistry.js';
+import { startAgentSession } from './ngrokAgentSession.js';
 let ngrokModule = null;
 async function getNgrok() {
     if (!ngrokModule) {
@@ -66,6 +67,23 @@ class TunnelManager {
      * changing the public API or depending on jest fake timers.
      */
     connectBackoffMs = [500, 1500];
+    /**
+     * Bead pqgj: how the ngrok agent gets started + how we learn its client
+     * session is live. Overridable so tests can drive a fake agent instead of
+     * spawning a real ngrok process.
+     */
+    agentSessionStarter = startAgentSession;
+    /**
+     * Cap on waiting for "client session established". Measured live at ~293ms;
+     * this is a generous ceiling, not an expected wait. On expiry we tunnel
+     * anyway and let the retry ladder handle it — a slow session must not become
+     * a hang.
+     */
+    agentSessionTimeoutMs = 5000;
+    /** Whether the ngrok agent's client session is established (bead pqgj). */
+    agentSessionReady = false;
+    /** In-flight session bootstrap, so concurrent tunnels wait on one spawn. */
+    agentSessionPromise = null;
     constructor(reg = getDefaultRegistry()) {
         this.reg = reg;
         // Bead `mdp`: sweep stale entries on startup so the registry doesn't grow
@@ -349,6 +367,11 @@ class TunnelManager {
                 hostname: tunnelDomain,
                 authtoken: authToken,
             };
+            // Bead pqgj: pre-warm the agent session so attempt 1 doesn't race the
+            // agent's ~293ms not-ready window (which poisons the tunnel name via
+            // ngrok's own name-reusing internal retry and surfaces as
+            // "invalid tunnel configuration").
+            await this.ensureAgentSession(authToken, trace);
             let lastError;
             for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
                 trace.emit('connect.attempt.start', { attempt });
@@ -481,6 +504,61 @@ class TunnelManager {
         }
     }
     // ── Helpers ─────────────────────────────────────────────────────────────────
+    /**
+     * Bead pqgj: make sure the ngrok agent's client session is established before
+     * we ask it for a tunnel, so attempt 1 lands on a ready agent instead of the
+     * ~293ms not-ready window that made every single run fail its first connect.
+     *
+     * Never throws: if the agent can't be pre-warmed (ngrok internals moved, slow
+     * session, dead token) we fall through and let connectWithRetry's ladder do
+     * what it did before this fix. The ladder stays a genuine safety net.
+     */
+    async ensureAgentSession(authtoken, trace) {
+        if (this.agentSessionReady)
+            return;
+        if (!this.agentSessionPromise) {
+            this.agentSessionPromise = (async () => {
+                let markEstablished;
+                const established = new Promise((resolve) => { markEstablished = resolve; });
+                await this.agentSessionStarter({
+                    authtoken,
+                    onStatusChange: (status) => {
+                        if (status === 'connected') {
+                            this.agentSessionReady = true;
+                            markEstablished();
+                        }
+                        else if (status === 'closed') {
+                            this.agentSessionReady = false;
+                        }
+                    },
+                    onTerminated: () => {
+                        // Agent process died — next tunnel must re-warm.
+                        this.agentSessionReady = false;
+                        this.agentSessionPromise = null;
+                    },
+                });
+                let capTimer;
+                const cap = new Promise((resolve) => {
+                    capTimer = setTimeout(resolve, this.agentSessionTimeoutMs);
+                });
+                try {
+                    await Promise.race([established, cap]);
+                }
+                finally {
+                    if (capTimer)
+                        clearTimeout(capTimer);
+                }
+            })().catch((err) => {
+                // Pre-warm unavailable — not fatal, the ladder covers it.
+                this.agentSessionPromise = null;
+                const msg = err instanceof Error ? err.message : String(err);
+                trace?.emit('agent.session.prewarm-failed', { message: msg.slice(0, 200) });
+                logger.debug(`ngrok agent pre-warm unavailable, relying on connect retry ladder: ${msg}`);
+            });
+        }
+        await this.agentSessionPromise;
+        trace?.emit('agent.session.ready', { ready: this.agentSessionReady });
+    }
     async ensureInitialized() {
         if (!this.initialized) {
             try {

package/dist/utils/localReachability.js

@@ -52,10 +52,68 @@ export async function probeLocalPort(port, opts = {}) {
         });
     });
 }
+/**
+ * Bead k6yq: connection-level failures that mean "the edge isn't ready yet",
+ * NOT "the tunnel is broken".
+ *
+ * Measured live on freshly created tunnels against a server serving 200: the
+ * ngrok edge sends an HTTP/2 GOAWAY with code 0 (NO_ERROR) — a graceful
+ * "reconnect on a fresh connection" signal — which undici raises as
+ * UND_ERR_SOCKET behind an opaque "fetch failed". DNS resolved in 1ms, and a
+ * retry 250ms later returned 200. Treating that as a fault reported a healthy
+ * dev server as unreachable roughly 1 run in 5-14.
+ *
+ * Deliberately EXCLUDED (these resolve and answer — they are real faults):
+ *   ECONNREFUSED / EHOSTUNREACH / ENETUNREACH, TLS errors, any HTTP response
+ *   (incl. 502 + ERR_NGROK_*), and timeouts.
+ */
+const TRANSIENT_CAUSE_CODES = new Set([
+    'ENOTFOUND', // DNS: name not resolvable yet
+    'EAI_AGAIN', // DNS: temporary resolver failure
+    'ECONNRESET', // edge dropped the connection mid-handshake
+    'EPIPE',
+    'UND_ERR_SOCKET', // undici socket error — this is the GOAWAY case
+    'UND_ERR_CONNECT_TIMEOUT',
+]);
+/** undici hides the real error behind `TypeError: fetch failed` — dig it out. */
+function errorCodeOf(err) {
+    return err?.cause?.code ?? err?.code;
+}
+function isTransientConnectionError(err) {
+    const code = errorCodeOf(err);
+    return code !== undefined && TRANSIENT_CAUSE_CODES.has(code);
+}
+/**
+ * Probe that traffic actually flows through the tunnel.
+ *
+ * Bead k6yq: a freshly created ngrok tunnel can bounce the first connection
+ * (HTTP/2 GOAWAY, DNS not yet resolvable) while being perfectly healthy, so
+ * transient connection-level failures are retried with a short backoff. Every
+ * other outcome — any HTTP response, connection refused, timeout — is returned
+ * on the first attempt, so a real fault is never retried into a false pass.
+ */
 export async function probeTunnelHealth(tunnelUrl, opts = {}) {
+    const maxAttempts = Math.max(1, opts.maxAttempts ?? 3);
+    const backoff = opts.retryBackoffMs ?? [150, 350];
+    const sleep = opts.sleepFn ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const started = Date.now();
+    let last;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const { result, retryable } = await probeOnce(tunnelUrl, opts, started);
+        if (!retryable)
+            return result;
+        last = result;
+        if (attempt < maxAttempts) {
+            await sleep(backoff[attempt - 1] ?? backoff[backoff.length - 1] ?? 150);
+        }
+    }
+    // Ladder exhausted on a transient error — the edge never came up. Report it:
+    // "not ready" that never becomes ready IS unhealthy.
+    return last;
+}
+async function probeOnce(tunnelUrl, opts, started) {
     const timeoutMs = opts.timeoutMs ?? 5000;
     const fetchImpl = opts.fetchFn ?? fetch;
-    const started = Date.now();
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -71,51 +129,77 @@ export async function probeTunnelHealth(tunnelUrl, opts = {}) {
         // ngrok error pages are small; a full user app body is a waste.
         const bodyText = await readCapped(res, 4096);
         const ngrokErr = extractNgrokErrorCode(bodyText);
-        // 502/504 + ngrok error marker → ngrok couldn't reach our server
+        // 502/504 + ngrok error marker → ngrok couldn't reach our server.
+        // A RESPONSE is proof the edge is up: never retried, so bead 4bui's
+        // marker-driven reclassification keeps seeing the real verdict.
         if (ngrokErr) {
             return {
-                healthy: false,
-                status: res.status,
-                code: 'NGROK_ERROR',
-                ngrokErrorCode: ngrokErr,
-                detail: `ngrok returned ${ngrokErr} — tunnel established but traffic could not reach dev server`,
-                elapsedMs: Date.now() - started,
+                retryable: false,
+                result: {
+                    healthy: false,
+                    status: res.status,
+                    code: 'NGROK_ERROR',
+                    ngrokErrorCode: ngrokErr,
+                    detail: `ngrok returned ${ngrokErr} — tunnel established but traffic could not reach dev server`,
+                    elapsedMs: Date.now() - started,
+                },
             };
         }
         if (res.status === 502 || res.status === 504) {
             return {
-                healthy: false,
-                status: res.status,
-                code: 'BAD_GATEWAY',
-                detail: `tunnel returned ${res.status} without an ngrok error marker — gateway is rejecting upstream`,
-                elapsedMs: Date.now() - started,
+                retryable: false,
+                result: {
+                    healthy: false,
+                    status: res.status,
+                    code: 'BAD_GATEWAY',
+                    detail: `tunnel returned ${res.status} without an ngrok error marker — gateway is rejecting upstream`,
+                    elapsedMs: Date.now() - started,
+                },
             };
         }
         // Any other response (incl. 4xx from user's app) means traffic reached
         // the dev server — that's healthy from the TUNNEL's perspective. The
         // user's 404 is a user concern, not a tunnel concern.
         return {
-            healthy: true,
-            status: res.status,
-            elapsedMs: Date.now() - started,
+            retryable: false,
+            result: {
+                healthy: true,
+                status: res.status,
+                elapsedMs: Date.now() - started,
+            },
         };
     }
     catch (err) {
         clearTimeout(timer);
         const e = err;
         if (e?.name === 'AbortError' || /abort|timeout/i.test(e?.message ?? '')) {
+            // Not retried: a hanging tunnel must not cost 3x the timeout budget.
             return {
-                healthy: false,
-                code: 'TIMEOUT',
-                detail: `tunnel health probe timed out after ${timeoutMs}ms`,
-                elapsedMs: Date.now() - started,
+                retryable: false,
+                result: {
+                    healthy: false,
+                    code: 'TIMEOUT',
+                    detail: `tunnel health probe timed out after ${timeoutMs}ms`,
+                    elapsedMs: Date.now() - started,
+                },
             };
         }
+        // Surface the cause code: undici reports every network failure as the
+        // undiagnosable "fetch failed" and hides the truth in err.cause.
+        const causeCode = errorCodeOf(e);
+        const baseMsg = e?.message ?? String(err);
+        const causeMsg = e?.cause?.message;
+        const detail = causeCode
+            ? `${baseMsg} (${causeCode}${causeMsg && causeMsg !== baseMsg ? `: ${causeMsg}` : ''})`
+            : baseMsg;
         return {
-            healthy: false,
-            code: 'NETWORK_ERROR',
-            detail: e?.message ?? String(err),
-            elapsedMs: Date.now() - started,
+            retryable: isTransientConnectionError(e),
+            result: {
+                healthy: false,
+                code: 'NETWORK_ERROR',
+                detail,
+                elapsedMs: Date.now() - started,
+            },
         };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "3.7.1",
+  "version": "3.7.2",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "bin": {