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

package/dist/services/ngrok/ngrokAgentInspector.js

@@ -0,0 +1,210 @@
+/**
+ * Local ngrok agent inspector (bead lc62).
+ *
+ * Every ngrok agent process serves a local inspection API on 127.0.0.1:4040,
+ * incrementing to 4041, 4042, ... when the port is taken. `GET /api/tunnels`
+ * answers with the tunnels THAT AGENT currently has open:
+ *
+ *   {"tunnels":[{"public_url":"https://x.ngrok.debugg.ai",
+ *                "config":{"addr":"http://127.0.0.1:3011"}}],"uri":"/api/tunnels"}
+ *
+ * This is the only free, honest source of tunnel liveness we have. It is
+ * loopback: no DNS, no TLS, no ngrok edge, no undici, and — critically — no
+ * request to the tunnel's PUBLIC url. Probing the public url for a reuse
+ * decision is the k6yq / z15n / kmzb failure class: the edge answers undici
+ * over HTTP/2 and the response is lost to a concurrent GOAWAY, so a live tunnel
+ * reads as dead and gets replaced for two billed hours.
+ *
+ * ── The safety property, and why it is structural rather than a policy ──
+ *
+ * A tunnel MISSING from this API is not proof it is gone: the agent that owns
+ * it may be on a port we did not scan, or may not be answering. Only a
+ * REACHABLE agent that does not list a tunnel is evidence, and even that is
+ * scoped to that one agent.
+ *
+ * Rather than encode that asymmetry as a tri-state ("live" / "gone" /
+ * "unknown") that some future caller could mishandle, the inspector returns
+ * only what it POSITIVELY OBSERVED, and TunnelManager uses it in an
+ * ADD-ONLY way: reconciliation can create or refresh a registry entry, never
+ * delete one. An unreachable agent therefore contributes an empty list and
+ * changes nothing versus today's behaviour, and no failure of this module can
+ * ever cost a re-provision. That is a guarantee about the shape of the data
+ * flow, not a rule someone has to remember.
+ *
+ * Adoption is filtered to `*.ngrok.debugg.ai`. A developer's own unrelated
+ * ngrok tunnels share this agent API and must never be touched by us.
+ */
+import { request as httpRequest } from 'node:http';
+import { Logger } from '../../utils/logger.js';
+import { getFaultModeFromEnv } from './tunnelFaultInjection.js';
+const logger = new Logger({ module: 'ngrokAgentInspector' });
+/** Only tunnels on this suffix are ours to adopt. */
+const OWNED_TUNNEL_SUFFIX = '.ngrok.debugg.ai';
+/** ngrok's web-inspector base port, and how far it walks when 4040 is busy. */
+const FIRST_INSPECTOR_PORT = 4040;
+const INSPECTOR_PORT_COUNT = 10;
+/**
+ * Parse one agent's `/api/tunnels` body into the tunnels we are allowed to own.
+ *
+ * Tolerant by construction — every unexpected shape drops the entry rather than
+ * throwing, because a parse failure must degrade to "learned nothing".
+ *
+ * ngrok reports the same tunnel more than once when it exposes several protos,
+ * so results are de-duplicated by tunnelId; first hostname wins.
+ */
+export function parseAgentTunnels(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return [];
+    }
+    const raw = parsed?.tunnels;
+    if (!Array.isArray(raw))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const item of raw) {
+        const publicUrl = item?.public_url;
+        const addr = item?.config?.addr;
+        if (typeof publicUrl !== 'string' || typeof addr !== 'string')
+            continue;
+        const tunnelId = tunnelIdFromPublicUrl(publicUrl);
+        if (!tunnelId || seen.has(tunnelId))
+            continue;
+        const port = portFromAgentAddr(addr);
+        if (port === undefined)
+            continue;
+        seen.add(tunnelId);
+        out.push({ tunnelId, publicUrl, port });
+    }
+    return out;
+}
+/**
+ * Subdomain of a `*.ngrok.debugg.ai` public url, or undefined for anything
+ * else — including a developer's personal ngrok tunnels, which share this
+ * agent API and are none of our business.
+ */
+function tunnelIdFromPublicUrl(publicUrl) {
+    let host;
+    try {
+        host = new URL(publicUrl).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+    if (!host.endsWith(OWNED_TUNNEL_SUFFIX))
+        return undefined;
+    const sub = host.slice(0, -OWNED_TUNNEL_SUFFIX.length);
+    // A bare or multi-label subdomain is not a tunnelId we minted.
+    return sub && !sub.includes('.') ? sub : undefined;
+}
+/**
+ * Local port out of an agent `config.addr`, which ngrok reports in several
+ * shapes depending on how connect() was called: `http://127.0.0.1:3011`,
+ * `https://localhost:3443`, or a bare `localhost:3011`.
+ */
+export function portFromAgentAddr(addr) {
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(addr) ? addr : `tcp://${addr}`;
+    try {
+        const port = new URL(withScheme).port;
+        if (port) {
+            const n = Number(port);
+            return Number.isInteger(n) && n > 0 && n <= 65535 ? n : undefined;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return undefined;
+}
+/**
+ * GET one agent's /api/tunnels over loopback HTTP/1.1.
+ *
+ * `agent: false` so the socket is closed rather than pooled — this runs once
+ * per process and must not leave a keep-alive handle behind.
+ */
+function fetchAgentTunnelsOverHttp(port, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        const req = httpRequest({ host: '127.0.0.1', port, path: '/api/tunnels', method: 'GET', agent: false, timeout: timeoutMs }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                return done(undefined);
+            }
+            let body = '';
+            res.setEncoding('utf8');
+            // 256KB ceiling: something answering on 4040 that is not an ngrok agent
+            // must not be able to stream us out of memory.
+            res.on('data', (chunk) => {
+                if (body.length < 262144)
+                    body += chunk;
+            });
+            res.on('end', () => done(body));
+            res.on('error', () => done(undefined));
+        });
+        req.on('timeout', () => { req.destroy(); done(undefined); });
+        // Nothing is listening on most of these ports; ECONNREFUSED is the norm.
+        req.on('error', () => done(undefined));
+        req.end();
+    });
+}
+/**
+ * Scans the local agents. Ports are probed in parallel — nearly all of them
+ * refuse instantly, so the wall cost is one timeout at worst.
+ */
+export function createLocalAgentInspector(opts = {}) {
+    const ports = opts.ports ?? Array.from({ length: INSPECTOR_PORT_COUNT }, (_, i) => FIRST_INSPECTOR_PORT + i);
+    const timeoutMs = opts.timeoutMs ?? 500;
+    const fetchOne = opts.fetchAgentTunnels ?? fetchAgentTunnelsOverHttp;
+    return {
+        async listLiveTunnels() {
+            const faults = opts.faultMode !== undefined ? opts.faultMode : getFaultModeFromEnv();
+            if (faults?.inspectorUnreachable) {
+                logger.debug('[fault-inject] ngrok agent inspector forced unreachable');
+                return [];
+            }
+            if (faults?.inspectorAdoptPort !== undefined) {
+                const port = faults.inspectorAdoptPort;
+                logger.debug(`[fault-inject] ngrok agent inspector reporting a synthetic tunnel on port ${port}`);
+                return [{
+                        tunnelId: `fault-adopt-${port}`,
+                        publicUrl: `https://fault-adopt-${port}${OWNED_TUNNEL_SUFFIX}`,
+                        port,
+                    }];
+            }
+            const bodies = await Promise.all(ports.map((port) => fetchOne(port, timeoutMs).catch(() => undefined)));
+            const seen = new Set();
+            const found = [];
+            for (const body of bodies) {
+                if (!body)
+                    continue;
+                for (const tunnel of parseAgentTunnels(body)) {
+                    if (seen.has(tunnel.tunnelId))
+                        continue;
+                    seen.add(tunnel.tunnelId);
+                    found.push(tunnel);
+                }
+            }
+            return found;
+        },
+    };
+}
+/** Learns nothing, ever. The default under NODE_ENV=test. */
+export const noopInspector = {
+    listLiveTunnels: async () => [],
+};
+/**
+ * Mirrors getDefaultRegistry(): tests get the inert inspector so no unit test
+ * can reach the network, production gets the real loopback scan.
+ */
+export function getDefaultInspector() {
+    return process.env.NODE_ENV === 'test' ? noopInspector : createLocalAgentInspector();
+}

package/dist/services/ngrok/tunnelFaultInjection.js

@@ -6,20 +6,27 @@
  *   - DEBUGG_TUNNEL_FAULT_MODE env var explicitly set
  *
  * Modes (comma-separated, parseable by parseFaultMode):
- *   fail-connect-N:<count>     — fail the first <count> ngrok.connect() attempts
+ *   fail-connect-N:<count>      — fail the first <count> ngrok.connect() attempts
  *   empty-url-N:<count>         — return empty URL from first <count> connect() attempts
  *   delay-connect:<ms>          — sleep <ms> before each connect() call
+ *   inspector-unreachable:1     — the local ngrok agent inspector observes nothing
+ *                                 (bead lc62: proves reconciliation is add-only, i.e.
+ *                                 a blind inspector cannot cost a re-provision)
+ *   inspector-adopt:<port>      — the inspector reports one synthetic live tunnel on
+ *                                 <port>, exercising re-adoption end to end without
+ *                                 provisioning a real, billable tunnel
  *
  * Examples:
  *   DEBUGG_TUNNEL_FAULT_MODE=fail-connect-N:2
  *   DEBUGG_TUNNEL_FAULT_MODE=delay-connect:2000,fail-connect-N:1
+ *   DEBUGG_TUNNEL_FAULT_MODE=inspector-adopt:3000
  */
 export function parseFaultMode(raw) {
     if (!raw)
         return null;
     const mode = {};
     for (const token of raw.split(',').map((s) => s.trim()).filter(Boolean)) {
-        const m = token.match(/^(fail-connect-N|empty-url-N|delay-connect):(\d+)$/);
+        const m = token.match(/^(fail-connect-N|empty-url-N|delay-connect|inspector-unreachable|inspector-adopt):(\d+)$/);
         if (!m)
             continue;
         const [, name, valStr] = m;
@@ -30,6 +37,12 @@ export function parseFaultMode(raw) {
             mode.emptyUrlN = val;
         else if (name === 'delay-connect')
             mode.delayConnectMs = val;
+        // Value-less switch, but kept in the `name:<digits>` grammar so one regex
+        // covers every mode. Any non-zero value turns it on.
+        else if (name === 'inspector-unreachable')
+            mode.inspectorUnreachable = val !== 0;
+        else if (name === 'inspector-adopt')
+            mode.inspectorAdoptPort = val;
     }
     return Object.keys(mode).length > 0 ? mode : null;
 }

package/dist/services/ngrok/tunnelManager.js

@@ -23,6 +23,7 @@ import { v4 as uuidv4 } from 'uuid';
 import { FaultInjector, TunnelTrace, getFaultModeFromEnv } from './tunnelFaultInjection.js';
 import { getDefaultRegistry, } from './tunnelRegistry.js';
 import { startAgentSession } from './ngrokAgentSession.js';
+import { getDefaultInspector } from './ngrokAgentInspector.js';
 let ngrokModule = null;
 async function getNgrok() {
     if (!ngrokModule) {
@@ -49,18 +50,51 @@ class TunnelManager {
     activeTunnels = new Map();
     pendingTunnels = new Map();
     initialized = false;
-    TUNNEL_TIMEOUT_MS = 55 * 60 * 1000;
+    /**
+     * Idle window before an owned tunnel auto-shuts-off. THE constant of this
+     * class: every other lifetime below is derived from it, because they are all
+     * answering the same question — "could this tunnel still be alive?" — and
+     * when they answered it differently they cost real money (bead y7x6).
+     *
+     * Public so timer tests can run in milliseconds instead of 55 minutes,
+     * matching the `connectBackoffMs` / `agentSessionStarter` precedent.
+     */
+    idleTimeoutMs = 55 * 60 * 1000;
     /**
      * Bead `3th`: registry-entry freshness window. An entry not touched within
      * this many ms is treated as stale even if its owner PID is alive — defends
      * against PID-reuse (OS reassigns dead-owner's PID to a different process).
+     *
+     * Bead `y7x6`: this was a hard-coded 30 minutes while tunnels lived for 55,
+     * so between T+30 and T+55 an entry was judged unusable while the tunnel it
+     * named was alive and billing. The next request provisioned a duplicate and
+     * OVERWROTE the entry, orphaning the original: a systematic double-bill on a
+     * 25-minute-wide window. Deriving it from the idle timeout is the fix, and
+     * it is the derivation — not the number — that matters, because it makes the
+     * two impossible to drift apart again.
+     *
+     * No guard band is subtracted. A band would just re-open a narrower version
+     * of the same window, and the T+55 boundary is already handled: a borrower
+     * writes `lastAccessedAt` before the owner's timer fires, and the owner then
+     * extends rather than shutting down.
      */
-    REGISTRY_FRESHNESS_TTL_MS = 30 * 60 * 1000;
+    get registryFreshnessTtlMs() {
+        return this.idleTimeoutMs;
+    }
     /**
      * Bead `mdp`: prune-on-startup eviction window. Entries older than this OR
      * with dead owner PID get swept out when TunnelManager initializes.
+     *
+     * Also derived, for the same reason: an entry older than the idle timeout
+     * names a tunnel that has already auto-shut-off, and one that has NOT is
+     * recovered by re-adoption (bead lc62) rather than by keeping a longer
+     * threshold here. Pruning something `isEntryUsable` already rejects costs
+     * nothing; the danger was never prune's window, it was that nothing put a
+     * live tunnel back.
      */
-    REGISTRY_PRUNE_THRESHOLD_MS = 60 * 60 * 1000;
+    get registryPruneThresholdMs() {
+        return this.idleTimeoutMs;
+    }
     /**
      * Backoff schedule (ms) between ngrok.connect() retry attempts. Bead ixh.
      * Exposed on the class so tests can override with short delays without
@@ -80,17 +114,31 @@ class TunnelManager {
      * a hang.
      */
     agentSessionTimeoutMs = 5000;
+    /**
+     * Bead lc62: where we learn which tunnels are actually alive on this machine.
+     * Overridable so tests drive a fake agent API instead of loopback HTTP.
+     */
+    tunnelInspector = getDefaultInspector();
     /** 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;
+    /** Memoized one-shot reconcile against the local ngrok agents (bead lc62). */
+    reconcilePromise = null;
     constructor(reg = getDefaultRegistry()) {
         this.reg = reg;
         // Bead `mdp`: sweep stale entries on startup so the registry doesn't grow
         // unboundedly across MCP processes that exited without stopAllTunnels
         // (SIGKILL / crash). Best-effort — no-op registries don't actually prune.
+        //
+        // Bead lc62: this sweep deletes map keys, which cannot stop a tunnel, so a
+        // pruned-but-live tunnel becomes an invisible billing line. Making prune
+        // tear tunnels down would be far worse — two billed hours for every idle
+        // gap, on exactly the days-long sessions this design exists to serve — so
+        // recovery is handled the other way round, by reconcileWithLocalAgents()
+        // putting live tunnels BACK. Prune stays cheap, synchronous, and harmless.
         try {
-            const result = this.reg.prune({ staleAfterMs: this.REGISTRY_PRUNE_THRESHOLD_MS });
+            const result = this.reg.prune({ staleAfterMs: this.registryPruneThresholdMs });
             if (result.pruned > 0) {
                 logger.info(`Pruned ${result.pruned} stale registry entries on startup (${result.remaining} remaining)`);
             }
@@ -105,7 +153,7 @@ class TunnelManager {
      */
     isEntryUsable(entry, nowMs = Date.now()) {
         return (this.reg.isPidAlive(entry.ownerPid) &&
-            (nowMs - entry.lastAccessedAt) <= this.REGISTRY_FRESHNESS_TTL_MS);
+            (nowMs - entry.lastAccessedAt) <= this.registryFreshnessTtlMs);
     }
     // ── Public API ──────────────────────────────────────────────────────────────
     async processUrl(url, authToken, specificTunnelId, keyId, revokeKey) {
@@ -132,7 +180,7 @@ class TunnelManager {
             return undefined;
         if (!existing.isOwned) {
             // Verify the owning process is still alive AND the entry is fresh
-            // (lastAccessedAt within REGISTRY_FRESHNESS_TTL_MS — defends against
+            // (lastAccessedAt within registryFreshnessTtlMs — defends against
             // PID-reuse per bead 3th).
             const entry = this.reg.read()[String(port)];
             if (!entry || !this.isEntryUsable(entry)) {
@@ -184,25 +232,61 @@ class TunnelManager {
             // best-effort — a failed eviction just means the next call re-probes and re-evicts
         }
     }
+    /**
+     * Mark a tunnel as in-use: refresh the shared registry entry so the owner
+     * does not auto-shut-off underneath us, and reset the local idle timer.
+     *
+     * Bead lc62 — two changes here, both about the registry telling the truth:
+     *
+     * 1. The refresh is now scoped to OUR tunnelId. It used to refresh whatever
+     *    entry held our port, so using tunnel A kept tunnel B's entry alive after
+     *    B had replaced A on that port.
+     * 2. If we OWN the tunnel and the entry has gone missing, we put it back.
+     *    Nothing did this before: prune (or a registry the process could not see,
+     *    bead fcbm) deleted the entry, and since the in-process reuse path never
+     *    wrote to the registry, the tunnel stayed live, stayed billing, and
+     *    stayed permanently invisible to every other MCP on the machine. One file
+     *    write makes that self-heal, and it cannot churn a tunnel because it only
+     *    ever ADDS the entry for a tunnel this process is holding open.
+     *
+     * A foreign entry — same port, different tunnelId — is left completely alone.
+     * That is another process's live tunnel; overwriting it would displace it.
+     */
     touchTunnel(tunnelId) {
         const tunnelInfo = this.activeTunnels.get(tunnelId);
         if (!tunnelInfo)
             return;
-        // Refresh the shared registry entry so the owning process won't auto-shutoff
-        // while we're actively using the tunnel (even if we're borrowing it).
         try {
             const registry = this.reg.read();
-            const entry = registry[String(tunnelInfo.port)];
-            if (entry) {
+            const key = String(tunnelInfo.port);
+            const entry = registry[key];
+            if (entry?.tunnelId === tunnelInfo.tunnelId) {
                 entry.lastAccessedAt = Date.now();
                 this.reg.write(registry);
             }
+            else if (!entry && tunnelInfo.isOwned) {
+                registry[key] = this.registryEntryFor(tunnelInfo);
+                this.reg.write(registry);
+                logger.info(`Re-registered owned tunnel ${tunnelInfo.tunnelId} for port ${tunnelInfo.port} — ` +
+                    'its registry entry had gone missing while the tunnel was still live (bead lc62).');
+            }
         }
         catch {
             // best-effort
         }
         this.resetTunnelTimer(tunnelInfo);
     }
+    /** The shared-registry view of a tunnel this process owns. */
+    registryEntryFor(tunnelInfo) {
+        return {
+            tunnelId: tunnelInfo.tunnelId,
+            publicUrl: tunnelInfo.publicUrl,
+            tunnelUrl: tunnelInfo.tunnelUrl,
+            port: tunnelInfo.port,
+            ownerPid: process.pid,
+            lastAccessedAt: Date.now(),
+        };
+    }
     touchTunnelByUrl(url) {
         const tunnelId = this.extractTunnelId(url);
         if (tunnelId) {
@@ -238,11 +322,19 @@ class TunnelManager {
             Telemetry.capture(TelemetryEvents.TUNNEL_STOPPED, { port: tunnelInfo.port, reason: 'released', isOwned: false });
             return;
         }
-        // Owned — remove from shared registry, then disconnect + revoke
+        // Owned — remove from shared registry, then disconnect + revoke.
+        // Guarded by tunnelId (bead lc62, same reasoning as the auto-shutoff check
+        // and markTunnelDead): if a replacement already holds this port's entry,
+        // deleting it would strand ITS live tunnel and buy the next caller a
+        // duplicate. Only ever remove the entry that names the tunnel we are
+        // actually stopping.
         try {
             const registry = this.reg.read();
-            delete registry[String(tunnelInfo.port)];
-            this.reg.write(registry);
+            const key = String(tunnelInfo.port);
+            if (registry[key]?.tunnelId === tunnelInfo.tunnelId) {
+                delete registry[key];
+                this.reg.write(registry);
+            }
         }
         catch {
             // best-effort
@@ -281,7 +373,7 @@ class TunnelManager {
             tunnel,
             age: now - tunnel.createdAt,
             timeSinceLastAccess: now - tunnel.lastAccessedAt,
-            timeUntilAutoShutoff: Math.max(0, tunnel.lastAccessedAt + this.TUNNEL_TIMEOUT_MS - now),
+            timeUntilAutoShutoff: Math.max(0, tunnel.lastAccessedAt + this.idleTimeoutMs - now),
         };
     }
     getAllTunnelStatuses() {
@@ -300,6 +392,12 @@ class TunnelManager {
         if (existing) {
             // Bead zmc9: retarget to THIS caller's path; publicUrl carries the creator's.
             const url_ = retargetTunnelUrl(existing.tunnelUrl, url);
+            // Bead lc62: reuse used to return straight from the in-process map without
+            // touching the registry at all, so a tunnel could be in constant use and
+            // still look abandoned to every other MCP — and its own idle timer kept
+            // counting down. touchTunnel refreshes (or restores) the shared entry and
+            // resets that timer, which is what "this tunnel is in use" should mean.
+            this.touchTunnel(existing.tunnelId);
             logger.info(`Reusing existing tunnel for port ${port}: ${url_}`);
             Telemetry.capture(TelemetryEvents.TUNNEL_PROVISIONED, { port, how: 'reused' });
             return { url: url_, tunnelId: existing.tunnelId, isLocalhost: true };
@@ -320,34 +418,20 @@ class TunnelManager {
         }
         // 3. Check cross-process registry — another MCP instance may own a tunnel.
         //    Borrow only if the entry is fresh (PID alive AND touched within
-        //    REGISTRY_FRESHNESS_TTL_MS — defends against PID-reuse, bead 3th).
+        //    registryFreshnessTtlMs — defends against PID-reuse, bead 3th).
         const registry = this.reg.read();
         const regEntry = registry[String(port)];
         if (regEntry && this.isEntryUsable(regEntry)) {
-            logger.info(`Borrowing tunnel from PID ${regEntry.ownerPid} for port ${port}: ${regEntry.publicUrl}`);
-            const now = Date.now();
-            const borrowed = {
-                tunnelId: regEntry.tunnelId,
-                originalUrl: url,
-                tunnelUrl: regEntry.tunnelUrl,
-                publicUrl: regEntry.publicUrl,
-                port,
-                createdAt: now,
-                lastAccessedAt: now,
-                isOwned: false,
-            };
-            this.activeTunnels.set(regEntry.tunnelId, borrowed);
-            // Touch registry so the owner knows not to auto-shutoff
-            regEntry.lastAccessedAt = now;
-            this.reg.write(registry);
-            this.resetTunnelTimer(borrowed);
-            Telemetry.capture(TelemetryEvents.TUNNEL_PROVISIONED, { port, how: 'borrowed' });
+            const borrowed = this.borrowRegistryEntry(regEntry, url, registry);
             // Bead zmc9: retarget to THIS caller's path; regEntry.publicUrl carries the
             // owning PID's creating-call path — replaying it is the cross-session poison.
-            return { url: retargetTunnelUrl(regEntry.tunnelUrl, url), tunnelId: regEntry.tunnelId, isLocalhost: true };
+            return { url: retargetTunnelUrl(borrowed.tunnelUrl, url), tunnelId: borrowed.tunnelId, isLocalhost: true };
         }
-        // 4. Create a new tunnel (this process becomes the owner)
-        const creationPromise = this.createTunnel(url, port, tunnelId, authToken, keyId, revokeKey);
+        // 4. Nothing to reuse. Publish the pending promise SYNCHRONOUSLY — every
+        //    check above is synchronous precisely so a second caller arriving in
+        //    this same tick joins us rather than buying a second hour — and do the
+        //    slow work (agent reconcile, then connect) inside it.
+        const creationPromise = this.adoptOrCreateTunnel(url, port, tunnelId, authToken, keyId, revokeKey);
         this.pendingTunnels.set(port, creationPromise);
         let tunnelInfo;
         try {
@@ -356,7 +440,123 @@ class TunnelManager {
         finally {
             this.pendingTunnels.delete(port);
         }
-        return { url: tunnelInfo.publicUrl, tunnelId: tunnelInfo.tunnelId, isLocalhost: true };
+        // A tunnel we just created carries this caller's path in publicUrl; an
+        // ADOPTED one carries someone else's, so retarget (bead zmc9).
+        const resolvedUrl = tunnelInfo.isOwned
+            ? tunnelInfo.publicUrl
+            : retargetTunnelUrl(tunnelInfo.tunnelUrl, url);
+        return { url: resolvedUrl, tunnelId: tunnelInfo.tunnelId, isLocalhost: true };
+    }
+    /**
+     * Take a live registry entry into this process as a BORROWED tunnel, and
+     * stamp it as touched so its owner does not auto-shut-off underneath us.
+     */
+    borrowRegistryEntry(entry, url, registry) {
+        logger.info(`Borrowing tunnel from PID ${entry.ownerPid} for port ${entry.port}: ${entry.publicUrl}`);
+        const now = Date.now();
+        const borrowed = {
+            tunnelId: entry.tunnelId,
+            originalUrl: url,
+            tunnelUrl: entry.tunnelUrl,
+            publicUrl: entry.publicUrl,
+            port: entry.port,
+            createdAt: now,
+            lastAccessedAt: now,
+            isOwned: false,
+        };
+        this.activeTunnels.set(entry.tunnelId, borrowed);
+        entry.lastAccessedAt = now;
+        try {
+            this.reg.write(registry);
+        }
+        catch {
+            // best-effort
+        }
+        this.resetTunnelTimer(borrowed);
+        Telemetry.capture(TelemetryEvents.TUNNEL_PROVISIONED, { port: entry.port, how: 'borrowed' });
+        return borrowed;
+    }
+    /**
+     * Last stop before spending a billed hour (bead lc62).
+     *
+     * The registry says there is nothing to reuse for this port. Before believing
+     * it, ask the local ngrok agents what is ACTUALLY running: a tunnel whose
+     * owner was SIGKILLed, or whose entry got pruned or written to a registry
+     * this process could not see, is still open and still billing, and the
+     * registry is simply wrong about it. Re-adopting one costs a loopback GET;
+     * not adopting it costs an hour for the replacement plus the remaining hour
+     * of the orphan nobody is using.
+     *
+     * Reaping orphans is deliberately NOT done here. Once they can be re-adopted
+     * an orphan pointing at a live port is an asset, and killing it only
+     * guarantees we buy that hour again later.
+     */
+    async adoptOrCreateTunnel(url, port, tunnelId, authToken, keyId, revokeKey) {
+        await this.reconcileWithLocalAgents();
+        const registry = this.reg.read();
+        const entry = registry[String(port)];
+        if (entry && this.isEntryUsable(entry)) {
+            logger.info(`Adopted live tunnel ${entry.tunnelId} for port ${port} instead of provisioning a new one`);
+            return this.borrowRegistryEntry(entry, url, registry);
+        }
+        return this.createTunnel(url, port, tunnelId, authToken, keyId, revokeKey);
+    }
+    /**
+     * Reconcile the shared registry against the tunnels the local ngrok agents
+     * report (bead lc62). Runs at most once per process, lazily — on the first
+     * request that would otherwise provision — so importing this module never
+     * touches the network and a process that only ever borrows never pays for it.
+     *
+     * ADD-ONLY, and that is the whole safety argument. This can create an entry
+     * or refresh an unusable one; it can never delete or invalidate anything. So
+     * an agent that is down, a scan that misses the right port, or a parse that
+     * fails all degrade to "learned nothing" and leave behaviour exactly as it is
+     * today. Nothing this function can get wrong is able to cost a re-provision.
+     *
+     * A usable entry is never disturbed, even by a live tunnel claiming the same
+     * port: that entry is somebody's working tunnel and displacing it would
+     * strand a paid-for session.
+     */
+    reconcileWithLocalAgents() {
+        if (!this.reconcilePromise) {
+            this.reconcilePromise = (async () => {
+                const live = await this.tunnelInspector.listLiveTunnels();
+                if (live.length === 0)
+                    return;
+                const registry = this.reg.read();
+                const adopted = [];
+                for (const tunnel of live) {
+                    const key = String(tunnel.port);
+                    const entry = registry[key];
+                    // Somebody's working entry — never touch it, even to "correct" it.
+                    if (entry && this.isEntryUsable(entry))
+                        continue;
+                    registry[key] = {
+                        tunnelId: tunnel.tunnelId,
+                        publicUrl: tunnel.publicUrl,
+                        tunnelUrl: tunnel.publicUrl,
+                        port: tunnel.port,
+                        // We are not the ngrok owner and never claim to be — TunnelInfo for
+                        // this entry is always built with isOwned:false. ownerPid is the
+                        // registry's liveness proxy, and pointing it at a live process is
+                        // what makes the entry borrowable at all.
+                        ownerPid: process.pid,
+                        lastAccessedAt: Date.now(),
+                    };
+                    adopted.push(`${tunnel.tunnelId}→${tunnel.port}`);
+                }
+                if (adopted.length > 0) {
+                    this.reg.write(registry);
+                    logger.info(`Re-adopted ${adopted.length} live ngrok tunnel(s) the registry had lost: ${adopted.join(', ')}. ` +
+                        'Each one saves provisioning a duplicate for a port that is already served.');
+                }
+            })().catch((err) => {
+                // An inspector failure must never block tunnelling — it only ever had
+                // the power to save us money, never to authorise anything.
+                logger.debug(`ngrok agent reconcile unavailable (non-fatal): ${err}`);
+            });
+        }
+        return this.reconcilePromise;
     }
     findTunnelByPort(port) {
         for (const tunnel of this.activeTunnels.values()) {
@@ -619,10 +819,21 @@ class TunnelManager {
         tunnelInfo.autoShutoffTimer = setTimeout(async () => {
             // For owned tunnels: if another process recently touched the registry entry,
             // reset the timer rather than disconnecting — that process is still using it.
+            //
+            // Bead lc62: the entry has to be OURS. This lookup is keyed by port, and
+            // the check used to stop at the timestamp, so once a replacement tunnel
+            // took over the port the displaced tunnel read the replacement's activity
+            // as its own and extended itself — forever, since every extension found
+            // the entry fresh again. That is what turned a 55-minute mistake into a
+            // multi-day one: an orphan nobody could reach, billing indefinitely.
+            // Comparing tunnelId makes an orphan simply time out, 55 idle minutes
+            // after the last time anyone actually used IT.
             if (tunnelInfo.isOwned) {
                 try {
                     const entry = this.reg.read()[String(tunnelInfo.port)];
-                    if (entry && Date.now() - entry.lastAccessedAt < this.TUNNEL_TIMEOUT_MS) {
+                    if (entry &&
+                        entry.tunnelId === tunnelInfo.tunnelId &&
+                        Date.now() - entry.lastAccessedAt < this.idleTimeoutMs) {
                         logger.info(`Tunnel ${tunnelInfo.tunnelId} accessed by another process — extending lifetime`);
                         this.resetTunnelTimer(tunnelInfo);
                         return;
@@ -635,7 +846,7 @@ class TunnelManager {
             logger.info(`Auto-shutting down tunnel ${tunnelInfo.tunnelId} after inactivity`);
             Telemetry.capture(TelemetryEvents.TUNNEL_STOPPED, { port: tunnelInfo.port, reason: 'auto-shutoff', isOwned: tunnelInfo.isOwned });
             await this.stopTunnel(tunnelInfo.tunnelId).catch((err) => logger.error(`Failed to auto-shutdown tunnel ${tunnelInfo.tunnelId}:`, err));
-        }, this.TUNNEL_TIMEOUT_MS);
+        }, this.idleTimeoutMs);
     }
 }
 const tunnelManager = new TunnelManager();

package/dist/services/ngrok/tunnelRegistry.js

@@ -7,29 +7,109 @@
  * The file registry uses an atomic rename-write so concurrent processes never
  * see a partial JSON file.  All operations are best-effort — errors are
  * swallowed so a broken registry never blocks tunnel creation.
+ *
+ * Bead `fcbm` — WHERE the file lives is load-bearing. It used to be
+ * `join(tmpdir(), 'debugg-ai-tunnels.json')`, and `os.tmpdir()` honours
+ * `$TMPDIR`, which is not a property of the machine — it is a property of how
+ * the process was LAUNCHED. Under launchd it is a per-user
+ * `/var/folders/<...>/T`; a shell with a scrubbed environment gets `/tmp`; the
+ * Docker image gets `/tmp`. Two MCPs started differently therefore kept two
+ * SEPARATE registries, never saw each other's tunnels, and provisioned a
+ * duplicate per port — silently and permanently. At a 1-hour minimum charge per
+ * tunnel that is a guaranteed double-bill, not an edge case.
+ *
+ * So the path is pinned to `~/.debugg-ai/tunnels.json`, which is the same file
+ * for the same user no matter how the process was started, with a
+ * `DEBUGG_AI_TUNNEL_REGISTRY` override for containers that mount a shared
+ * volume elsewhere. Anything found at the legacy tmpdir() path is merged in
+ * once, so tunnels already paid for on the old path stay discoverable.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'fs';
+import { homedir, tmpdir } from 'os';
+import { dirname, join } from 'path';
+// ── File location ─────────────────────────────────────────────────────────────
+/**
+ * The pre-fcbm location. Still READ (and merged from) so tunnels provisioned by
+ * an older build, or by a build whose $TMPDIR differed, are not stranded.
+ *
+ * Never written to, and never deleted: a still-running older MCP is reading it,
+ * and removing its entries would make it re-provision — the exact double-bill
+ * this bead exists to stop.
+ */
+export function getLegacyRegistryFilePath() {
+    return join(tmpdir(), 'debugg-ai-tunnels.json');
+}
+/**
+ * The registry path for this machine+user. Resolved per call (not cached at
+ * module load) so an override can be set before the registry is constructed.
+ */
+export function getRegistryFilePath() {
+    const override = process.env.DEBUGG_AI_TUNNEL_REGISTRY?.trim();
+    if (override)
+        return override;
+    return join(homedir(), '.debugg-ai', 'tunnels.json');
+}
+/** Paths already merged in this process — the legacy merge is a one-shot. */
+const migratedPaths = new Set();
+/**
+ * Per-path watermark: when we last wrote a complete view of this registry.
+ *
+ * The read-side legacy overlay needs to tell two cases apart that look identical
+ * in the file: an entry we have ALREADY considered and deliberately swept, and
+ * one an old-build MCP wrote after we swept. Resurrecting the first hands a dead
+ * tunnel to the next borrower (bead k34o); missing the second buys a duplicate.
+ * An entry's `lastAccessedAt` relative to our last write separates them.
+ *
+ * Ties and clock skew resolve toward NOT resurrecting, because the two mistakes
+ * are not equal: a dead entry breaks a run, a missed one costs an hour we were
+ * already spending before this path moved.
  */
-import { existsSync, readFileSync, writeFileSync, renameSync } from 'fs';
-import { tmpdir } from 'os';
-import { join } from 'path';
+const sweptAt = new Map();
 // ── File-backed implementation (production) ───────────────────────────────────
-const REGISTRY_FILE = join(tmpdir(), 'debugg-ai-tunnels.json');
-export function createFileRegistry() {
+/**
+ * Both paths are parameters rather than module constants so tests can point at
+ * a throwaway directory. That matters more than it looks: the legacy path is a
+ * real machine-wide file that a running MCP may depend on, and `os.tmpdir()`
+ * does not observe a `TMPDIR` set inside a Jest realm — so a test that tried to
+ * redirect it by environment would silently read and REWRITE the developer's
+ * actual registry.
+ */
+export function createFileRegistry(registryFile = getRegistryFilePath(), legacyFile = getLegacyRegistryFilePath()) {
     const store = {
         read() {
-            try {
-                if (!existsSync(REGISTRY_FILE))
-                    return {};
-                return JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));
-            }
-            catch {
-                return {};
-            }
+            // Overlay the legacy registry on EVERY read, not just once at startup.
+            //
+            // Moving the path partitions us against every MCP still running the old
+            // build, which keeps writing to tmpdir() — i.e. for the length of the
+            // rollout this change would REINTRODUCE the split-registry double-billing
+            // it exists to fix. That window is not short: long-lived sessions here run
+            // for days, so a one-shot merge at process start would miss every tunnel
+            // an old build provisions afterwards.
+            //
+            // Reading both and preferring the fresher record closes the direction that
+            // matters — new builds see old builds' tunnels and borrow them instead of
+            // buying duplicates. The reverse (old builds seeing ours) cannot be fixed
+            // from this side without dual-writing, which would hand the old code a file
+            // it may prune on our behalf; it resolves as old sessions exit.
+            //
+            // Cost is one extra existsSync + small JSON read per lookup, against a
+            // 1-hour minimum charge for getting it wrong.
+            return overlayLegacy(readRegistryFile(registryFile), legacyFile, registryFile);
         },
         write(data) {
-            const tmp = `${REGISTRY_FILE}.${process.pid}.tmp`;
+            const tmp = `${registryFile}.${process.pid}.tmp`;
             try {
+                // 0o700: the registry names every local port this user is exposing.
+                // Also covers a first run where ~/.debugg-ai does not exist yet, and a
+                // later run where someone removed it.
+                mkdirSync(dirname(registryFile), { recursive: true, mode: 0o700 });
                 writeFileSync(tmp, JSON.stringify(data));
-                renameSync(tmp, REGISTRY_FILE);
+                // Same directory as the target, so the rename is same-filesystem and
+                // therefore actually atomic.
+                renameSync(tmp, registryFile);
+                // We have just published a complete view; anything older in the legacy
+                // file has already been considered (and possibly swept) by us.
+                sweptAt.set(registryFile, Date.now());
             }
             catch {
                 // best-effort
@@ -42,8 +122,87 @@ export function createFileRegistry() {
             return pruneRegistryData(store, opts);
         },
     };
+    mergeLegacyRegistry(store, registryFile, legacyFile);
     return store;
 }
+/**
+ * One-shot merge of the legacy tmpdir() registry into the stable one.
+ *
+ * Merge, not move: an entry only wins if this path has nothing for that port or
+ * has something older. A tunnel that both files know about keeps whichever
+ * record was touched most recently, which is the one whose `lastAccessedAt`
+ * actually reflects use.
+ */
+function mergeLegacyRegistry(store, registryFile, legacyFile) {
+    if (legacyFile === registryFile || migratedPaths.has(registryFile))
+        return;
+    migratedPaths.add(registryFile);
+    const legacy = readRegistryFile(legacyFile);
+    const ports = Object.keys(legacy);
+    if (ports.length === 0)
+        return;
+    const current = store.read();
+    let merged = 0;
+    for (const port of ports) {
+        const entry = legacy[port];
+        if (!isRegistryEntry(entry))
+            continue;
+        const mine = current[port];
+        if (!mine || entry.lastAccessedAt > mine.lastAccessedAt) {
+            current[port] = entry;
+            merged++;
+        }
+    }
+    if (merged > 0)
+        store.write(current);
+}
+/**
+ * Merge the legacy registry over `current` in memory, fresher record winning.
+ *
+ * Read-side only — never writes. An old-build MCP that provisions a tunnel after
+ * our one-shot migration ran is otherwise invisible to us, and we would buy a
+ * duplicate for a port it already has covered.
+ */
+function overlayLegacy(current, legacyFile, registryFile) {
+    if (legacyFile === registryFile)
+        return current;
+    const watermark = sweptAt.get(registryFile) ?? 0;
+    const legacy = readRegistryFile(legacyFile);
+    for (const [port, entry] of Object.entries(legacy)) {
+        if (!isRegistryEntry(entry))
+            continue;
+        // Older than our last complete write => we already saw it and chose not to
+        // keep it. Bringing it back would undo a prune and re-borrow a dead tunnel.
+        if (entry.lastAccessedAt <= watermark)
+            continue;
+        const mine = current[port];
+        if (!mine || entry.lastAccessedAt > mine.lastAccessedAt)
+            current[port] = entry;
+    }
+    return current;
+}
+function readRegistryFile(file) {
+    try {
+        if (!existsSync(file))
+            return {};
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+function isRegistryEntry(value) {
+    const e = value;
+    return (!!e &&
+        typeof e === 'object' &&
+        typeof e.tunnelId === 'string' &&
+        typeof e.port === 'number' &&
+        typeof e.ownerPid === 'number' &&
+        typeof e.lastAccessedAt === 'number');
+}
 // ── In-memory implementation (tests / injectable) ─────────────────────────────
 export function createInMemoryRegistry(isPidAliveImpl) {
     let data = {};

package/dist/utils/localReachability.js

@@ -14,6 +14,9 @@
  *     misconfigured ngrok, etc.)
  */
 import { createConnection } from 'node:net';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { Readable } from 'node:stream';
 export async function probeLocalPort(port, opts = {}) {
     const host = opts.host ?? '127.0.0.1';
     const timeoutMs = opts.timeoutMs ?? 1500;
@@ -72,9 +75,134 @@ const TRANSIENT_CAUSE_CODES = new Set([
     '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
+    // undici codes. Since bead kmzb the default probe transport is node:https,
+    // which reports the OS codes above instead — these stay for an injected
+    // fetchFn, and as the record of what the HTTP/2 path used to produce.
+    'UND_ERR_SOCKET',
     'UND_ERR_CONNECT_TIMEOUT',
 ]);
+/**
+ * ngrok codes meaning "the edge does not route this hostname".
+ *
+ * Kept here deliberately separate from tunnelDisposition's ENDPOINT_GONE
+ * allowlist even though they currently hold the same code: that list decides
+ * whether a verdict may DESTROY a tunnel, this one decides whether a verdict is
+ * worth double-checking first. A code could reasonably be on one and not the
+ * other, and coupling them would make this module depend on policy it has no
+ * business knowing.
+ */
+const ENDPOINT_NOT_FOUND_CODES = new Set(['ERR_NGROK_3200']);
+// ─ HTTP/1.1 probe transport (bead kmzb) ──────────────────────────────────────
+/**
+ * `fetch`-shaped GET that speaks HTTP/1.1, because the global fetch cannot.
+ *
+ * Measured against the ngrok edge on 2026-07-27, Node v26:
+ *
+ *   ALPN offer [h2, http/1.1] → edge selects h2
+ *   raw HTTP/2 GET of a hostname ngrok no longer routes
+ *       → 404 with ERR_NGROK_3200 in the body, AND a GOAWAY (code 0, NO_ERROR)
+ *         on the same connection
+ *   undici (global fetch) over that h2 connection
+ *       → TypeError: fetch failed / UND_ERR_SOCKET, 3/3 — the response is lost
+ *         to the concurrent GOAWAY and never surfaces
+ *   node:https (HTTP/1.1)
+ *       → 404 + ERR_NGROK_3200, 3/3
+ *
+ * So the edge was answering us the whole time and undici was dropping the
+ * answer. That is why `ngrokErrorCode` had never once been populated in
+ * production, which in turn made tunnelDisposition's ENDPOINT_GONE allowlist
+ * unreachable: every probe failure looked like a transient network error, and
+ * a genuinely dead endpoint could never be told apart from a flake. Speaking
+ * HTTP/1.1 makes the distinction observable again and re-activates that
+ * allowlist — so ERR_NGROK_3200 can once more evict a tunnel that is provably
+ * gone, while everything short of proof still keeps the tunnel we are paying
+ * for. It also removes the h2 GOAWAY that bead k6yq's retry ladder existed to
+ * paper over, leaving the ladder as a genuine safety net rather than a
+ * load-bearing workaround.
+ *
+ * Node's fetch offers no way to disable h2, hence a transport rather than an
+ * option. `http.ClientRequest` — which `https.request` returns — implements
+ * HTTP/1.x only, so this cannot regress into h2 no matter what a future Node
+ * negotiates by default. The seam is deliberately `typeof fetch` so every
+ * caller and test that injects `fetchFn` is unaffected.
+ */
+export const http1Fetch = async (input, init) => {
+    const url = new URL(typeof input === 'string' ? input : input.url ?? String(input));
+    const isPlainHttp = url.protocol === 'http:';
+    const signal = init?.signal ?? undefined;
+    const options = {
+        protocol: url.protocol,
+        host: url.hostname,
+        port: url.port || (isPlainHttp ? 80 : 443),
+        path: `${url.pathname}${url.search}`,
+        method: (init?.method ?? 'GET').toUpperCase(),
+        headers: init?.headers ?? {},
+        // One-shot probe — do not leave a pooled keep-alive socket behind.
+        agent: false,
+    };
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const fail = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(err);
+        };
+        const onResponse = (res) => {
+            if (settled)
+                return;
+            settled = true;
+            const status = res.statusCode ?? 0;
+            // Response rejects a body on these statuses; they have none anyway.
+            const bodyless = status === 101 || status === 204 || status === 205 || status === 304;
+            if (bodyless)
+                res.resume();
+            resolve(new Response(bodyless ? null : Readable.toWeb(res), {
+                status,
+                headers: headersFrom(res.headers),
+            }));
+        };
+        const req = isPlainHttp
+            ? httpRequest(options, onResponse)
+            : httpsRequest(options, onResponse);
+        if (signal) {
+            if (signal.aborted) {
+                req.destroy();
+                return fail(abortError());
+            }
+            signal.addEventListener('abort', () => {
+                req.destroy();
+                fail(abortError());
+            }, { once: true });
+        }
+        req.on('error', fail);
+        req.end();
+    });
+};
+/** Matches what an aborted fetch throws, so probeOnce's TIMEOUT arm still fires. */
+function abortError() {
+    const err = new Error('The operation was aborted.');
+    err.name = 'AbortError';
+    return err;
+}
+/** node:http header bag → Headers, skipping the pseudo/array oddities. */
+function headersFrom(raw) {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(raw)) {
+        if (value === undefined)
+            continue;
+        for (const v of Array.isArray(value) ? value : [value]) {
+            try {
+                headers.append(key, v);
+            }
+            catch {
+                // A header Headers refuses (invalid name from a hostile server) is not
+                // worth failing a health probe over.
+            }
+        }
+    }
+    return headers;
+}
 /** undici hides the real error behind `TypeError: fetch failed` — dig it out. */
 function errorCodeOf(err) {
     return err?.cause?.code ?? err?.code;
@@ -113,7 +241,8 @@ export async function probeTunnelHealth(tunnelUrl, opts = {}) {
 }
 async function probeOnce(tunnelUrl, opts, started) {
     const timeoutMs = opts.timeoutMs ?? 5000;
-    const fetchImpl = opts.fetchFn ?? fetch;
+    // Bead kmzb: HTTP/1.1, not the global fetch — see http1Fetch.
+    const fetchImpl = opts.fetchFn ?? http1Fetch;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -129,18 +258,31 @@ async function probeOnce(tunnelUrl, opts, started) {
         // 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.
-        // A RESPONSE is proof the edge is up: never retried, so bead 4bui's
+        // An ngrok error page. A RESPONSE is proof the edge is up, so these are
+        // returned as-is rather than retried into a false pass, and bead 4bui's
         // marker-driven reclassification keeps seeing the real verdict.
+        //
+        // One exception, and it exists only because bead kmzb made these codes
+        // reachable at all: ENDPOINT_NOT_FOUND is the single verdict that
+        // AUTHORISES A TEARDOWN (tunnelDisposition's allowlist), and the ngrok
+        // agent passes through a short window where it is briefly true — while a
+        // dropped session reconnects and re-announces the same hostname. Acting on
+        // one sample would kill a tunnel that was about to come back, at a cost of
+        // two billed hours. So this code alone is confirmed across the retry
+        // ladder: a reconnect resolves inside it, a genuinely deleted endpoint
+        // answers the same way every time and is still reported as gone.
         if (ngrokErr) {
+            const notFound = ENDPOINT_NOT_FOUND_CODES.has(ngrokErr);
             return {
-                retryable: false,
+                retryable: notFound,
                 result: {
                     healthy: false,
                     status: res.status,
                     code: 'NGROK_ERROR',
                     ngrokErrorCode: ngrokErr,
-                    detail: `ngrok returned ${ngrokErr} — tunnel established but traffic could not reach dev server`,
+                    detail: notFound
+                        ? `ngrok returned ${ngrokErr} — the edge no longer routes this tunnel hostname`
+                        : `ngrok returned ${ngrokErr} — tunnel established but traffic could not reach dev server`,
                     elapsedMs: Date.now() - started,
                 },
             };

package/package.json

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