@debugg-ai/debugg-ai-mcp 3.9.1 → 3.9.2

package/dist/handlers/probePageHandler.js

@@ -18,7 +18,7 @@ import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { TunnelProvisionError } from '../services/tunnels.js';
-import { tunnelManager } from '../services/ngrok/tunnelManager.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';
@@ -148,18 +148,12 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                                         elapsedMs: health.elapsedMs,
                                     },
                                 };
-                                if (tunneled.tunnelId) {
-                                    const deadPort = extractLocalhostPort(tunneled.originalUrl);
-                                    if (health.ngrokErrorCode && typeof deadPort === 'number') {
-                                        // Tunnel-level dead (ERR_NGROK_*): evict the SHARED registry entry
-                                        // so the next call re-provisions instead of re-borrowing the corpse
-                                        // (bead k34o) — plain stopTunnel leaves a borrowed entry to re-poison.
-                                        tunnelManager.markTunnelDead(deadPort, tunneled.tunnelId).catch((err) => logger.warn(`Failed to evict dead tunnel ${tunneled.tunnelId}: ${err}`));
-                                    }
-                                    else {
-                                        tunnelManager.stopTunnel(tunneled.tunnelId).catch((err) => logger.warn(`Failed to stop broken tunnel ${tunneled.tunnelId}: ${err}`));
-                                    }
-                                }
+                                // 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 };
                             }
                         }

package/dist/handlers/runTestSuiteHandler.js

@@ -2,7 +2,7 @@ import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { TunnelProvisionError } from '../services/tunnels.js';
-import { tunnelManager } from '../services/ngrok/tunnelManager.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';
@@ -82,9 +82,17 @@ export async function runTestSuiteHandler(input, _context) {
                         if (tunneled.targetUrl) {
                             const health = await probeTunnelHealth(tunneled.targetUrl);
                             if (!health.healthy) {
-                                if (tunneled.tunnelId) {
-                                    tunnelManager.stopTunnel(tunneled.tunnelId).catch((err) => logger.warn(`Failed to stop broken tunnel ${tunneled.tunnelId}: ${err}`));
-                                }
+                                // 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 });
                             }
                         }

package/dist/handlers/testPageChangesHandler.js

@@ -13,7 +13,7 @@ import { adaptVerdict, isEnvironmentDefault } from '../services/verdictAdapter.j
 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 { disposeUnhealthyTunnel } from '../utils/tunnelDisposition.js';
 import { probeLocalPort, probeTunnelHealth, extractNgrokErrorCode } from '../utils/localReachability.js';
 import { extractLocalhostPort } from '../utils/urlParser.js';
 import { getCachedTemplateUuid, getCachedProjectUuid, invalidateTemplateCache, invalidateProjectCache, } from '../utils/handlerCaches.js';
@@ -276,21 +276,16 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                             },
                         };
                         logger.warn(`Tunnel health probe failed for ${ctx.targetUrl}: ${health.code} ${health.ngrokErrorCode ?? ''} in ${health.elapsedMs}ms`);
-                        // Tear down the broken tunnel so a subsequent call doesn't reuse it.
-                        if (ctx.tunnelId) {
-                            const deadPort = extractLocalhostPort(ctx.originalUrl);
-                            if (health.ngrokErrorCode && typeof deadPort === 'number') {
-                                // Tunnel-level dead (ERR_NGROK_*): evict the SHARED registry entry
-                                // so the next call re-provisions instead of re-borrowing the corpse.
-                                // Plain stopTunnel leaves a borrowed entry to re-poison (bead k34o).
-                                tunnelManager.markTunnelDead(deadPort, ctx.tunnelId).catch((err) => logger.warn(`Failed to evict dead tunnel ${ctx.tunnelId}: ${err}`));
-                            }
-                            else {
-                                tunnelManager.stopTunnel(ctx.tunnelId).catch((err) => logger.warn(`Failed to stop broken tunnel ${ctx.tunnelId}: ${err}`));
-                            }
-                        }
-                        // keyId is consumed by stopTunnel's revoke path; clear so the
-                        // outer finally block doesn't double-revoke.
+                        // Evict ONLY on a code proving the endpoint is gone; every other
+                        // failure keeps the tunnel we are already paying for, because 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: ctx.tunnelId, originalUrl: ctx.originalUrl });
+                        // Don't revoke the key on either branch: if we evicted, markTunnelDead's
+                        // owned path already revokes it; if we kept the tunnel, the key is that
+                        // live tunnel's own credential and revoking it would kill what we just
+                        // decided to preserve.
                         keyId = undefined;
                         return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
                     }

package/dist/handlers/triggerCrawlHandler.js

@@ -15,7 +15,7 @@ import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { TunnelProvisionError } from '../services/tunnels.js';
-import { tunnelManager } from '../services/ngrok/tunnelManager.js';
+import { disposeUnhealthyTunnel } from '../utils/tunnelDisposition.js';
 import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js';
 import { extractLocalhostPort } from '../utils/urlParser.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
@@ -138,18 +138,15 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
                             },
                         };
                         logger.warn(`Tunnel health probe failed for ${ctx.targetUrl}: ${health.code} ${health.ngrokErrorCode ?? ''} in ${health.elapsedMs}ms`);
-                        if (ctx.tunnelId) {
-                            const deadPort = extractLocalhostPort(ctx.originalUrl);
-                            if (health.ngrokErrorCode && typeof deadPort === 'number') {
-                                // Tunnel-level dead (ERR_NGROK_*): evict the SHARED registry entry so
-                                // the next call re-provisions instead of re-borrowing the corpse — plain
-                                // stopTunnel leaves a borrowed entry to re-poison (bead k34o).
-                                tunnelManager.markTunnelDead(deadPort, ctx.tunnelId).catch((err) => logger.warn(`Failed to evict dead tunnel ${ctx.tunnelId}: ${err}`));
-                            }
-                            else {
-                                tunnelManager.stopTunnel(ctx.tunnelId).catch((err) => logger.warn(`Failed to stop broken tunnel ${ctx.tunnelId}: ${err}`));
-                            }
-                        }
+                        // Evict ONLY on a code proving the endpoint is gone; every other failure
+                        // keeps the tunnel we are already paying for, because 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.
+                        disposeUnhealthyTunnel({ health, tunnelId: ctx.tunnelId, originalUrl: ctx.originalUrl });
+                        // Don't revoke the key on either branch: if we evicted, markTunnelDead's
+                        // owned path already revokes it; if we kept the tunnel, the key is that
+                        // live tunnel's own credential and revoking it would kill what we just
+                        // decided to preserve.
                         keyId = undefined;
                         return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
                     }

package/dist/utils/tunnelDisposition.js

@@ -0,0 +1,128 @@
+/**
+ * What to do with a tunnel whose health probe just failed.
+ *
+ * ngrok bills a MINIMUM OF ONE HOUR PER TUNNEL, so tearing one down and standing
+ * a replacement up costs TWO billed hours. A teardown therefore has to be backed
+ * by proof that the tunnel is already gone — not by a probe result that a
+ * transient edge flake produces just as readily as a real death.
+ *
+ * All four tool handlers probe tunnel health before handing the URL to the remote
+ * browser, and all four used to gate eviction on `health.ngrokErrorCode` being
+ * set AT ALL, falling back to stopTunnel() otherwise. Both halves were wrong:
+ *
+ *   - `ngrokErrorCode` is not a verdict. ERR_NGROK_8012 means the tunnel is ALIVE
+ *     and its upstream refused the connection — the tunnel is literally what
+ *     served us that error. Evicting on it orphans a live, billing tunnel and
+ *     makes the next call provision a replacement: two billed hours spent on a
+ *     dev server that was the actual problem.
+ *   - the stopTunnel() fallback tore down an OWNED tunnel on ANY probe failure,
+ *     including the transient HTTP/2 GOAWAY the ngrok edge sends to undici
+ *     (bead k6yq — measured at roughly 1 run in 5 before the retry ladder landed,
+ *     and still reachable whenever that ladder exhausts).
+ *
+ * Hence an explicit allowlist of codes that prove the ENDPOINT ITSELF is gone.
+ * Everything else leaves both the tunnel and the shared registry entry completely
+ * untouched and just reports TunnelTrafficBlocked: the user fixes their dev
+ * server and the next call reuses the same tunnel for free.
+ *
+ * Bead kmzb, confirmed live on 2026-07-27: probeTunnelHealth cannot currently
+ * produce ANY ngrokErrorCode against this edge. `curl` and a raw node:https
+ * request both get `404 + ERR_NGROK_3200` from a hostname ngrok no longer routes,
+ * but undici's fetch negotiates HTTP/2 and the edge answers with a GOAWAY, which
+ * surfaces as UND_ERR_SOCKET / NETWORK_ERROR with no code at all. So in practice
+ * every probe failure takes the leave-it-alone branch today. The allowlist is the
+ * policy that governs the moment a code CAN be produced — whether that is kmzb
+ * forcing HTTP/1.1 for the probe, or a caller passing the marker recorded by a
+ * run's own evidence (bead 4bui, the one live-confirmed source of ERR_NGROK_*).
+ */
+import { tunnelManager } from '../services/ngrok/tunnelManager.js';
+import { extractLocalhostPort } from './urlParser.js';
+import { Logger } from './logger.js';
+const logger = new Logger({ module: 'tunnelDisposition' });
+/**
+ * ngrok error codes that PROVE the endpoint no longer exists, so evicting it
+ * costs nothing and re-borrowing it costs everyone a failed run (bead k34o).
+ *
+ * Inclusion criterion — the code must be served BY THE EDGE ABOUT A HOSTNAME IT
+ * NO LONGER ROUTES, i.e. it is impossible to receive it from a tunnel that is
+ * still up. Anything describing the upstream, the agent, or the connection is a
+ * live tunnel reporting on something else, and must NOT be here.
+ *
+ * Verify a candidate before adding it — the check is free and creates no tunnel:
+ *   curl -s https://<random-uuid>.ngrok.debugg.ai/ | grep -o 'ERR_NGROK_[0-9]*'
+ * (use curl or node:https, NOT fetch — see the kmzb note above).
+ *
+ *   ERR_NGROK_3200 — "not found". Verified live 2026-07-27: a GET to a
+ *   nonexistent *.ngrok.debugg.ai host returns 404 with this code in the body.
+ *   The endpoint is definitively gone; nothing is billing for it.
+ *
+ * Deliberately EXCLUDED, and the sharpest case of all:
+ *
+ *   ERR_NGROK_8012 — the agent could not dial the upstream (connection refused).
+ *   The TUNNEL IS ALIVE; it is the thing that generated the error page. Evicting
+ *   on 8012 orphans a paid-for tunnel and buys a duplicate — two billed hours —
+ *   to work around a dev server that is down, bound to the wrong interface, or
+ *   still starting up. Leave it be; it will serve the very next request once the
+ *   user's server is back.
+ *
+ * This set is pinned by a test. Adding a code has to be a deliberate act with
+ * evidence behind it, not a silent default to teardown.
+ *
+ * The frozen ARRAY is the source of truth, not a frozen Set: Object.freeze does
+ * not make a Set immutable — its entries live in internal slots, so `.add()` on
+ * a "frozen" Set still succeeds silently. Freezing the array is a real runtime
+ * guarantee; the lookup Set is derived from it and kept private.
+ */
+const ENDPOINT_GONE_CODES = Object.freeze(['ERR_NGROK_3200']);
+const ENDPOINT_GONE_LOOKUP = new Set(ENDPOINT_GONE_CODES);
+/** The allowlist, as an immutable list. Read-only by construction. */
+export const ENDPOINT_GONE_NGROK_CODES = ENDPOINT_GONE_CODES;
+/**
+ * True only when the code proves the endpoint is gone. Unset / unknown codes are
+ * NOT proof of anything, so they answer false: the default is always to keep the
+ * tunnel we are already paying for.
+ */
+export function isEndpointGone(ngrokErrorCode) {
+    return !!ngrokErrorCode && ENDPOINT_GONE_LOOKUP.has(ngrokErrorCode);
+}
+/**
+ * Decide — once, in one place — what an unhealthy tunnel health probe does to the
+ * tunnel. Called by every handler that probes, so the policy cannot drift between
+ * them (run_test_suite had already drifted: it evicted on every failure and never
+ * got bead k34o's shared-registry eviction at all).
+ *
+ * Endpoint proven gone  → markTunnelDead: for an owned tunnel that disconnects and
+ *                         revokes the key; for a BORROWED one it also evicts the
+ *                         shared registry entry, which plain stopTunnel leaves
+ *                         behind for every other session to re-borrow (bead k34o).
+ * Anything else         → nothing at all. The caller still returns
+ *                         TunnelTrafficBlocked, so the user is told; we simply do
+ *                         not spend two billed hours acting on a verdict this
+ *                         probe cannot actually deliver.
+ *
+ * Never throws and never awaits the eviction: a cleanup decision must not be able
+ * to fail or slow down the error response the caller is about to return.
+ */
+export function disposeUnhealthyTunnel(args) {
+    const { health, tunnelId, originalUrl } = args;
+    if (!tunnelId)
+        return;
+    if (!isEndpointGone(health.ngrokErrorCode)) {
+        logger.info(`Tunnel ${tunnelId} failed its health probe (${health.code}${health.ngrokErrorCode ? ` ${health.ngrokErrorCode}` : ''}) ` +
+            'but nothing proves the endpoint is gone — keeping it. Tearing down a live tunnel costs two billed hours ' +
+            '(1-hour minimum down, another up) and the next call reuses this one for free.');
+        return;
+    }
+    const port = extractLocalhostPort(originalUrl);
+    if (typeof port !== 'number') {
+        // markTunnelDead is keyed by port. Without one we cannot evict the shared
+        // entry safely, and a blind stopTunnel is exactly the teardown this module
+        // exists to prevent — so keep the tunnel and say why.
+        logger.warn(`Tunnel ${tunnelId} reported ${health.ngrokErrorCode} but no port could be parsed from ${originalUrl} — ` +
+            'leaving it in place rather than risking a teardown of a live tunnel.');
+        return;
+    }
+    logger.warn(`Tunnel ${tunnelId} on port ${port} reported ${health.ngrokErrorCode} — the endpoint is gone, evicting it ` +
+        'so no session re-borrows the corpse (bead k34o).');
+    tunnelManager.markTunnelDead(port, tunnelId).catch((err) => logger.warn(`Failed to evict dead tunnel ${tunnelId}: ${err}`));
+}

package/package.json

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