@debugg-ai/debugg-ai-mcp 4.2.2 → 4.4.0

package/dist/services/ngrok/tunnelManager.js

@@ -30,6 +30,7 @@
  * bypasses Caddy/PortLock entirely — see §2.3.
  */
 import { Logger } from '../../utils/logger.js';
+import { config } from '../../config/index.js';
 import { Telemetry, TelemetryEvents } from '../../utils/telemetry.js';
 import { extractLocalhostPort, generateTunnelUrl } from '../../utils/urlParser.js';
 import { currentApiKey } from '../../utils/requestContext.js';
@@ -37,28 +38,17 @@ import { createHash } from 'node:crypto';
 import { v4 as uuidv4 } from 'uuid';
 import { FaultInjector, TunnelTrace, getFaultModeFromEnv } from './tunnelFaultInjection.js';
 import { getDefaultRegistry, } from './tunnelRegistry.js';
-import { startAgentSession } from './ngrokAgentSession.js';
 import { createCaddyProxy, isDockerEnv, } from '../caddy/caddyProxy.js';
 import { PortLock } from '../caddy/portLock.js';
-let ngrokModule = null;
-async function getNgrok() {
-    if (!ngrokModule) {
-        try {
-            ngrokModule = await import('ngrok');
-        }
-        catch (error) {
-            throw new Error(`Failed to load ngrok module: ${error}`);
-        }
-    }
-    return ngrokModule;
-}
+import { createNgrokTransport, } from '../tunnel/ngrokTransport.js';
+import { createDebuggTransport } from '../tunnel/debuggTransport.js';
+import { extractTunnelIdFromHost, isTunnelHost, } from '../../utils/tunnelDomains.js';
 /**
- * Reset the cached ngrok module so the next connect() bootstraps a fresh agent.
- * Called when the last tunnel is disconnected and the agent process may have died.
+ * The hostname suffix a tunnel gets when the provision response does not name
+ * one — i.e. the ngrok path, which is every tunnel until the backend starts
+ * selecting the debugg transport.
  */
-function resetNgrokModule() {
-    ngrokModule = null;
-}
+const DEFAULT_TUNNEL_DOMAIN = 'ngrok.debugg.ai';
 const logger = new Logger({ module: 'tunnelManager' });
 // ── Session identity (§2.1) ────────────────────────────────────────────────────
 /**
@@ -112,7 +102,6 @@ class TunnelManager {
      *  session key join one creation instead of each minting their own (§2.3's
      *  cold-start TOCTOU fix — see ensureSessionTunnel()). */
     pendingSessionTunnels = new Map();
-    initialized = false;
     /**
      * Idle window before a tunnel auto-shuts-off. Public so timer tests can run
      * in milliseconds instead of 55 minutes, matching the `connectBackoffMs` /
@@ -125,29 +114,51 @@ class TunnelManager {
      * changing the public API or depending on jest fake timers.
      */
     connectBackoffMs = [500, 1500];
+    /**
+     * The transport implementations, keyed by the kind a provision response can
+     * select. Public and mutable in the same spirit as `caddyFactory`: a test
+     * drives a fake transport instead of a real agent or websocket.
+     *
+     * A provision response with no `transport` means ngrok, so an old backend
+     * and a new client keep working together.
+     */
+    transports = {
+        ngrok: createNgrokTransport(),
+        debugg: createDebuggTransport({ clientVersion: `debugg-ai-mcp/${config.server.version}` }),
+    };
     /**
      * 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.
+     *
+     * The pre-warm itself moved into ngrokTransport (it is ngrok-only, and the
+     * debugg path must never touch the `ngrok` package), but the seam stays here
+     * because it is public API the existing suites drive.
      */
-    agentSessionStarter = startAgentSession;
+    get agentSessionStarter() {
+        return this.transports.ngrok.agentSessionStarter;
+    }
+    set agentSessionStarter(starter) {
+        this.transports.ngrok.agentSessionStarter = starter;
+    }
     /**
      * 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;
+    get agentSessionTimeoutMs() {
+        return this.transports.ngrok.agentSessionTimeoutMs;
+    }
+    set agentSessionTimeoutMs(ms) {
+        this.transports.ngrok.agentSessionTimeoutMs = ms;
+    }
     /**
      * §2.2/§2.3: one fresh `CaddyProxy` instance PER SESSION KEY, never a
      * process-wide singleton. Overridable so tests drive a fake proxy instead
      * of spawning a real `caddy` process.
      */
     caddyFactory = createCaddyProxy;
-    /** 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 dead-owner entries on startup so the (now purely
@@ -182,7 +193,7 @@ class TunnelManager {
      * so whichever call runs its synchronous prefix first wins the map slot,
      * and the other necessarily observes it on its own synchronous prefix.
      */
-    async ensureSessionTunnel(sessionKey, authToken, specificTunnelId, keyId, revokeKey) {
+    async ensureSessionTunnel(sessionKey, authToken, specificTunnelId, keyId, revokeKey, selection) {
         // 1. Fast path: a fully-created tunnel already exists for this session key.
         const existingId = this.sessionTunnels.get(sessionKey);
         if (existingId) {
@@ -198,7 +209,7 @@ class TunnelManager {
         if (inFlight)
             return inFlight;
         // 3. First caller for this session key: claim the slot BEFORE any await.
-        const creation = this.createSessionTunnel(sessionKey, authToken, specificTunnelId, keyId, revokeKey)
+        const creation = this.createSessionTunnel(sessionKey, authToken, specificTunnelId, keyId, revokeKey, selection)
             .finally(() => { this.pendingSessionTunnels.delete(sessionKey); });
         this.pendingSessionTunnels.set(sessionKey, creation);
         return creation;
@@ -234,14 +245,19 @@ class TunnelManager {
      * A session that calls both a Caddy-routed tool AND run_test_suite pays for
      * 2 tunnels for that session — honest and bounded, flagged in §6.
      */
-    async acquireDedicatedTunnel(url, authToken, keyId, revokeKey) {
-        await this.ensureInitialized();
+    async acquireDedicatedTunnel(url, authToken, keyId, revokeKey, selection) {
         const port = extractLocalhostPort(url);
         if (!port) {
             throw new Error(`acquireDedicatedTunnel: could not extract port from localhost URL: ${url}`);
         }
-        const tunnelId = uuidv4();
-        const tunnelDomain = `${tunnelId}.ngrok.debugg.ai`;
+        const transportKind = selection?.transport ?? 'ngrok';
+        // The ngrok path mints its own id, as it always has — an ngrok key is not
+        // bound to a hostname. A debugg token IS bound to its Tunnel record, so a
+        // client-minted uuid would be rejected with 401 and the id the backend
+        // issued must be used instead.
+        const tunnelId = selection?.tunnelId ?? uuidv4();
+        const domain = selection?.tunnelDomain ?? DEFAULT_TUNNEL_DOMAIN;
+        const tunnelDomain = `${tunnelId}.${domain}`;
         const isHttpsLocal = url.startsWith('https:');
         const inDocker = isDockerEnv();
         // NOTE: this intentionally does NOT reuse caddyProxy.ts's
@@ -270,18 +286,28 @@ class TunnelManager {
         const trace = new TunnelTrace();
         trace.emit('acquireDedicatedTunnel.start', { port, tunnelId, hasFaultMode: !!faultMode });
         try {
-            const tunnelUrl = await this.connectWithRetry(localAddr, tunnelDomain, authToken, trace, faults);
+            const tunnelUrl = await this.connectWithRetry(localAddr, tunnelDomain, authToken, trace, faults, {
+                transport: transportKind,
+                tunnelId,
+                relayUrl: selection?.relayUrl,
+                onDead: (reason) => {
+                    logger.error(`Dedicated tunnel ${tunnelId} reported dead by its transport (${reason}) — evicting`);
+                    void this.stopTunnel(tunnelId);
+                },
+            });
             const now = Date.now();
             const info = {
-                tunnelId, tunnelUrl, createdAt: now, lastAccessedAt: now, keyId, revokeKey,
+                tunnelId, transport: transportKind, tunnelUrl, createdAt: now, lastAccessedAt: now, keyId, revokeKey,
             };
             this.directTunnels.set(tunnelId, info);
             this.writeRegistryEntry(tunnelId, `dedicated:${tunnelId}`, tunnelUrl, -1);
             this.armIdleTimer(info);
             trace.emit('acquireDedicatedTunnel.success', { tunnelId, tunnelUrl });
             logger.info(`Dedicated tunnel created: ${tunnelUrl} -> localhost:${port}`);
-            Telemetry.capture(TelemetryEvents.TUNNEL_PROVISIONED, { tunnelId, how: 'created-dedicated' });
-            return { url: generateTunnelUrl(url, tunnelId), tunnelId };
+            Telemetry.capture(TelemetryEvents.TUNNEL_PROVISIONED, {
+                tunnelId, how: 'created-dedicated', transport: transportKind,
+            });
+            return { url: generateTunnelUrl(url, tunnelId, domain), tunnelId };
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : 'Unknown error';
@@ -356,12 +382,12 @@ class TunnelManager {
             this.touchTunnel(tunnelId);
         }
     }
+    /** True for a hostname on ANY known tunnel domain (utils/tunnelDomains.ts). */
     isTunnelUrl(url) {
-        return url.includes('.ngrok.debugg.ai');
+        return isTunnelHost(url);
     }
     extractTunnelId(url) {
-        const match = url.match(/https?:\/\/([^.]+)\.ngrok\.debugg\.ai/);
-        return match ? match[1] : null;
+        return extractTunnelIdFromHost(url);
     }
     getTunnelStatus(tunnelId) {
         const tunnel = this.activeTunnels.get(tunnelId);
@@ -385,10 +411,12 @@ class TunnelManager {
         return statuses;
     }
     // ── Session tunnel creation ─────────────────────────────────────────────────
-    async createSessionTunnel(sessionKey, authToken, specificTunnelId, keyId, revokeKey) {
-        await this.ensureInitialized();
+    async createSessionTunnel(sessionKey, authToken, specificTunnelId, keyId, revokeKey, selection) {
+        const transportKind = selection?.transport ?? 'ngrok';
         const tunnelId = specificTunnelId ?? uuidv4();
-        const tunnelDomain = `${tunnelId}.ngrok.debugg.ai`; // UNCHANGED scheme, minted ONCE per session now
+        // The hostname comes from the provision response for a debugg tunnel, and
+        // is ngrok's for everything else — minted ONCE per session either way.
+        const tunnelDomain = `${tunnelId}.${selection?.tunnelDomain ?? DEFAULT_TUNNEL_DOMAIN}`;
         const caddy = this.caddyFactory(); // NEW instance per session key — never a process-wide singleton
         const { localOrigin, adminPort } = await caddy.ensureStarted();
         logger.info(`Creating session tunnel (domain: ${tunnelDomain}, session: ${sessionKey})`);
@@ -403,7 +431,18 @@ class TunnelManager {
             // no HTTPS/Docker complexity on this leg at all (Caddy runs in the same
             // host/container as the MCP server). That matrix moved entirely into
             // caddyProxy.setUpstream(), invoked per-dispatch, not per-tunnel-creation.
-            const tunnelUrl = await this.connectWithRetry(localOrigin, tunnelDomain, authToken, trace, faults);
+            const tunnelUrl = await this.connectWithRetry(localOrigin, tunnelDomain, authToken, trace, faults, {
+                transport: transportKind,
+                tunnelId,
+                relayUrl: selection?.relayUrl,
+                // A transport that reports the tunnel permanently gone (revoked, or
+                // auth refused on reconnect) must not leave a corpse behind for the
+                // next call to reuse: evict it exactly like a port change does.
+                onDead: (reason) => {
+                    logger.error(`Tunnel ${tunnelId} reported dead by its transport (${reason}) — evicting`);
+                    void this.stopTunnel(tunnelId);
+                },
+            });
             const now = Date.now();
             const portLock = new PortLock((t) => caddy.setUpstream(t));
             caddy.onPortChanged(() => {
@@ -414,11 +453,13 @@ class TunnelManager {
                 // call. stopTunnel() never throws (its unconditional-removal
                 // contract, above), so this needs no defensive .catch() of its own.
                 logger.error(`Caddy proxy port changed under session ${sessionKey} — evicting tunnel ${tunnelId}`);
-                Telemetry.capture(TelemetryEvents.TUNNEL_EVICTED_PORT_CHANGED, { tunnelId, sessionKey });
+                Telemetry.capture(TelemetryEvents.TUNNEL_EVICTED_PORT_CHANGED, {
+                    tunnelId, sessionKey, transport: transportKind,
+                });
                 void this.stopTunnel(tunnelId);
             });
             const info = {
-                tunnelId, sessionKey, tunnelUrl, createdAt: now, lastAccessedAt: now,
+                tunnelId, sessionKey, transport: transportKind, tunnelUrl, createdAt: now, lastAccessedAt: now,
                 keyId, revokeKey, caddy, portLock,
             };
             this.activeTunnels.set(tunnelId, info);
@@ -427,7 +468,7 @@ class TunnelManager {
             this.armIdleTimer(info);
             trace.emit('createSessionTunnel.success', { tunnelId, tunnelUrl });
             logger.info(`Session tunnel created: ${tunnelUrl} (session ${sessionKey})`);
-            Telemetry.capture(TelemetryEvents.TUNNEL_PROVISIONED, { tunnelId, how: 'created' });
+            Telemetry.capture(TelemetryEvents.TUNNEL_PROVISIONED, { tunnelId, how: 'created', transport: transportKind });
             return info;
         }
         catch (error) {
@@ -462,21 +503,29 @@ class TunnelManager {
      * IDENTICAL retry/backoff/fault-injection/agent-prewarm behavior, so it
      * lives here once.
      */
-    async connectWithRetry(localAddr, tunnelDomain, authToken, trace, faults) {
+    async connectWithRetry(localAddr, tunnelDomain, authToken, trace, faults, connectSpec) {
         const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
         const BACKOFF_MS = this.connectBackoffMs; // bead ixh: test-overridable
         const MAX_ATTEMPTS = BACKOFF_MS.length + 1; // N sleeps between N+1 attempts
+        const transport = this.transports[connectSpec.transport];
+        if (!transport) {
+            throw new Error(`No tunnel transport registered for "${connectSpec.transport}"`);
+        }
+        // Telemetry stage: the ngrok path keeps its existing value so dashboards
+        // built on it stay continuous.
+        const connectStage = transport.kind === 'ngrok' ? 'ngrok_connect' : 'debugg_connect';
         const connectOpts = {
-            proto: 'http',
-            addr: localAddr,
-            hostname: tunnelDomain,
-            authtoken: authToken,
+            tunnelId: connectSpec.tunnelId,
+            relayUrl: connectSpec.relayUrl,
+            onDead: connectSpec.onDead,
         };
-        // Bead pqgj: pre-warm the agent session so attempt 1 doesn't race the
+        // Bead pqgj: pre-warm the agent session so attempt 1 doesn't race the ngrok
         // 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);
+        // "invalid tunnel configuration"). Transport-specific and a no-op for
+        // debugg, which has no agent to warm.
+        await transport.prepare?.(authToken);
+        trace.emit('transport.prepared', { transport: transport.kind });
         let lastError;
         for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
             trace.emit('connect.attempt.start', { attempt });
@@ -487,24 +536,26 @@ class TunnelManager {
                 await sleep(delayMs);
             }
             try {
-                const ngrok = await getNgrok();
-                // Fault-inject a synthetic failure BEFORE ngrok.connect runs so we
-                // can simulate connect-layer failures without hitting the real API.
+                // Fault-inject a synthetic failure BEFORE the transport runs so we can
+                // simulate connect-layer failures without hitting a real API.
                 if (faults.shouldFailConnect()) {
                     trace.emit('connect.fault.inject', { attempt, mode: 'fail-connect-N' });
                     throw new Error(`[fault-inject] synthetic connect failure (attempt ${attempt})`);
                 }
-                const url = faults.shouldReturnEmptyUrl() ? '' : await ngrok.connect(connectOpts);
+                const url = faults.shouldReturnEmptyUrl()
+                    ? ''
+                    : await transport.connect(localAddr, tunnelDomain, authToken, connectOpts);
                 if (!url) {
                     trace.emit('connect.attempt.empty-url', { attempt });
-                    throw new Error(`ngrok.connect() returned empty URL (attempt ${attempt})`);
+                    throw new Error(`${transport.kind} transport returned empty URL (attempt ${attempt})`);
                 }
                 trace.emit('connect.attempt.success', { attempt });
                 if (attempt > 1) {
                     Telemetry.capture(TelemetryEvents.TUNNEL_PROVISION_RETRY, {
                         attempt,
                         outcome: 'success',
-                        stage: 'ngrok_connect',
+                        stage: connectStage,
+                        transport: transport.kind,
                     });
                 }
                 return url;
@@ -513,15 +564,21 @@ class TunnelManager {
                 lastError = err;
                 const msg = err instanceof Error ? err.message : String(err);
                 trace.emit('connect.attempt.fail', { attempt, message: msg.slice(0, 200) });
-                // Auth-class errors are non-retryable — retrying with the same token
-                // would loop. Let the outer catch classify the message.
-                if (/authtoken|unauthorized|\b401\b|\b403\b/i.test(msg)) {
-                    trace.emit('connect.giving-up', { reason: 'auth-error' });
+                // Non-retryable by construction: a transport says so for the cases
+                // where looping cannot help (401 bad/expired key, 400 bad id, 426 this
+                // build is too old). Retrying those sends the identical request.
+                const declaredTerminal = err?.retryable === false;
+                // Auth-class errors are non-retryable for the same reason. Kept as a
+                // message test as well, because ngrok only ever reports them that way.
+                if (declaredTerminal || /authtoken|unauthorized|\b401\b|\b403\b/i.test(msg)) {
+                    const reason = declaredTerminal ? 'transport-terminal' : 'auth-error';
+                    trace.emit('connect.giving-up', { reason });
                     Telemetry.capture(TelemetryEvents.TUNNEL_PROVISION_RETRY, {
                         attempt,
                         outcome: 'giving-up',
-                        stage: 'ngrok_connect',
-                        reason: 'auth-error',
+                        stage: connectStage,
+                        transport: transport.kind,
+                        reason,
                     });
                     throw err;
                 }
@@ -529,24 +586,24 @@ class TunnelManager {
                 Telemetry.capture(TelemetryEvents.TUNNEL_PROVISION_RETRY, {
                     attempt,
                     outcome: isLastAttempt ? 'giving-up' : 'will-retry',
-                    stage: 'ngrok_connect',
+                    stage: connectStage,
+                    transport: transport.kind,
                 });
                 if (isLastAttempt) {
                     trace.emit('connect.giving-up', { reason: 'max-attempts' });
                     throw err;
                 }
-                // Between attempt 1→2, do an agent-reset (covers the "agent died"
-                // failure mode that used to be the only retried case). Between 2→3,
-                // just wait — the reset already happened.
+                // Between attempt 1→2, let the transport reset itself — for ngrok that
+                // is the agent reset that covers the "agent died" failure mode, which
+                // used to be the only retried case. Between 2→3, just wait: the reset
+                // already happened. A transport with nothing to reset does nothing.
                 if (attempt === 1) {
-                    logger.warn(`ngrok.connect() failed (attempt 1/${MAX_ATTEMPTS}), resetting agent: ${msg}`);
+                    logger.warn(`${transport.kind} connect failed (attempt 1/${MAX_ATTEMPTS}), resetting transport: ${msg}`);
                     trace.emit('agent.reset');
-                    resetNgrokModule();
-                    this.initialized = false;
-                    await this.ensureInitialized();
+                    await transport.resetAfterFailedAttempt?.();
                 }
                 else {
-                    logger.warn(`ngrok.connect() failed (attempt ${attempt}/${MAX_ATTEMPTS}), will retry: ${msg}`);
+                    logger.warn(`${transport.kind} connect failed (attempt ${attempt}/${MAX_ATTEMPTS}), will retry: ${msg}`);
                 }
                 const backoffMs = BACKOFF_MS[attempt - 1] ?? BACKOFF_MS[BACKOFF_MS.length - 1];
                 trace.emit('connect.backoff', { attempt, backoffMs });
@@ -569,7 +626,7 @@ class TunnelManager {
             clearTimeout(info.autoShutoffTimer);
         this.removeRegistryEntry(info.tunnelId);
         const results = await Promise.allSettled([
-            this.disconnectNgrok(info.tunnelUrl),
+            this.transports[info.transport].disconnect(info.tunnelUrl),
             info.caddy.stop(),
             info.revokeKey ? info.revokeKey() : Promise.resolve(),
         ]);
@@ -581,9 +638,11 @@ class TunnelManager {
                 Telemetry.capture(TelemetryEvents.TUNNEL_TEARDOWN_PARTIAL_FAILURE, { tunnelId: info.tunnelId, step: i });
             }
         });
-        this.maybeResetNgrokModule();
+        this.notifyIfNoTunnelsRemain(info.transport);
         logger.info(`Cleaned up session tunnel: ${info.tunnelUrl}`);
-        Telemetry.capture(TelemetryEvents.TUNNEL_STOPPED, { tunnelId: info.tunnelId, reason: 'stopped' });
+        Telemetry.capture(TelemetryEvents.TUNNEL_STOPPED, {
+            tunnelId: info.tunnelId, reason: 'stopped', transport: info.transport,
+        });
     }
     async stopDirectTunnel(info) {
         // Same unconditional-removal contract as stopSessionTunnel, above.
@@ -592,7 +651,7 @@ class TunnelManager {
             clearTimeout(info.autoShutoffTimer);
         this.removeRegistryEntry(info.tunnelId);
         const results = await Promise.allSettled([
-            this.disconnectNgrok(info.tunnelUrl),
+            this.transports[info.transport].disconnect(info.tunnelUrl),
             info.revokeKey ? info.revokeKey() : Promise.resolve(),
         ]);
         results.forEach((r, i) => {
@@ -601,23 +660,28 @@ class TunnelManager {
                 Telemetry.capture(TelemetryEvents.TUNNEL_TEARDOWN_PARTIAL_FAILURE, { tunnelId: info.tunnelId, step: i });
             }
         });
-        this.maybeResetNgrokModule();
+        this.notifyIfNoTunnelsRemain(info.transport);
         logger.info(`Cleaned up dedicated tunnel: ${info.tunnelUrl}`);
-        Telemetry.capture(TelemetryEvents.TUNNEL_STOPPED, { tunnelId: info.tunnelId, reason: 'stopped' });
-    }
-    async disconnectNgrok(tunnelUrl) {
-        const ngrok = await getNgrok();
-        await ngrok.disconnect(tunnelUrl);
+        Telemetry.capture(TelemetryEvents.TUNNEL_STOPPED, {
+            tunnelId: info.tunnelId, reason: 'stopped', transport: info.transport,
+        });
     }
-    /** If no tunnels of any kind remain, the ngrok agent process may have
-     *  exited. Reset module + init state so the next connect() bootstraps a
-     *  fresh agent. */
-    maybeResetNgrokModule() {
-        if (this.activeTunnels.size === 0 && this.directTunnels.size === 0) {
-            logger.info('No tunnels remain — resetting ngrok module for fresh init on next request');
-            resetNgrokModule();
-            this.initialized = false;
-        }
+    /**
+     * Tell a transport when the last tunnel OF ITS KIND is gone. ngrok uses it to
+     * reset its module and init state, because the agent process may have exited
+     * with it; debugg has nothing process-wide to reset.
+     *
+     * Counted per transport, not globally: while both are in play, a debugg
+     * tunnel shutting down must not make the ngrok transport throw away a live
+     * agent that another tunnel is still using.
+     */
+    notifyIfNoTunnelsRemain(transport) {
+        const remaining = [...this.activeTunnels.values(), ...this.directTunnels.values()]
+            .some((t) => t.transport === transport);
+        if (remaining)
+            return;
+        logger.info(`No ${transport} tunnels remain — notifying its transport`);
+        this.transports[transport].onAllTunnelsStopped?.();
     }
     // ── Idle timer (KEPT — minus the retired cross-process extension branch) ───
     /**
@@ -681,74 +745,6 @@ class TunnelManager {
             // best-effort
         }
     }
-    // ── 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 {
-                const ngrok = await getNgrok();
-                ngrok.getApi();
-            }
-            catch {
-                // ignore — let connect surface real errors
-            }
-            this.initialized = true;
-        }
-    }
 }
 const tunnelManager = new TunnelManager();
 export { tunnelManager };