@debugg-ai/debugg-ai-mcp 4.4.1 → 5.0.0

package/dist/utils/localReachability.js

@@ -3,21 +3,18 @@
  *
  * MCP owns the tunnel lifecycle. It must validate that the user's claimed
  * localhost URL is actually reachable BEFORE calling the backend provision
- * API and BEFORE committing to the slow ngrok/browser-agent path. Without
- * these probes, unreachable apps result in a 5-minute false-positive pass
- * as the browser agent burns its step budget on ERR_NGROK_8012.
+ * API and BEFORE committing to the slow tunnel/browser-agent path. Without
+ * these probes, unreachable apps result in a 5-minute false-positive pass as
+ * the browser agent burns its step budget on our upstream-refused error page.
  *
  * Two probes:
  *   - probeLocalPort(port): pre-flight TCP connect to 127.0.0.1:<port>
- *   - probeTunnelHealth(url): HTTP check that traffic actually flows through
- *     the tunnel to our local server (catches IPv4/IPv6 bind mismatches,
- *     misconfigured ngrok, etc.)
+ *   - probeTunnelHealth(url): asks the tunnel server to fetch the tunnel's own
+ *     public URL and report what it got — proof that traffic actually flows
+ *     end to end (catches IPv4/IPv6 bind mismatches, a dev server that died
+ *     after the port probe, a tunnel that never came up).
  */
 import { createConnection } from 'node:net';
-import { request as httpRequest } from 'node:http';
-import { request as httpsRequest } from 'node:https';
-import { Readable } from 'node:stream';
-import { tunnelDomainFor } from './tunnelDomains.js';
 import { getControlProbe } from '../services/tunnel/probeRegistry.js';
 export async function probeLocalPort(port, opts = {}) {
     const host = opts.host ?? '127.0.0.1';
@@ -58,187 +55,54 @@ export async function probeLocalPort(port, opts = {}) {
     });
 }
 /**
- * Bead k6yq: connection-level failures that mean "the edge isn't ready yet",
- * NOT "the tunnel is broken".
+ * Markers meaning "the edge does not route this hostname".
  *
- * Measured live on freshly created tunnels against a server serving 200: the
- * ngrok edge sends an HTTP/2 GOAWAY with code 0 (NO_ERROR) — a graceful
- * "reconnect on a fresh connection" signal — which undici raises as
- * UND_ERR_SOCKET behind an opaque "fetch failed". DNS resolved in 1ms, and a
- * retry 250ms later returned 200. Treating that as a fault reported a healthy
- * dev server as unreachable roughly 1 run in 5-14.
- *
- * Deliberately EXCLUDED (these resolve and answer — they are real faults):
- *   ECONNREFUSED / EHOSTUNREACH / ENETUNREACH, TLS errors, any HTTP response
- *   (incl. 502 + ERR_NGROK_*), and timeouts.
- */
-const TRANSIENT_CAUSE_CODES = new Set([
-    'ENOTFOUND', // DNS: name not resolvable yet
-    'EAI_AGAIN', // DNS: temporary resolver failure
-    'ECONNRESET', // edge dropped the connection mid-handshake
-    'EPIPE',
-    // 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.
+ * Kept deliberately separate from tunnelDisposition's ENDPOINT_GONE allowlist
+ * even though the codes overlap: 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',
-    // The debugg analogue. The server already holds a browser request for
-    // RECONNECT_GRACE_MS (5s) while a client reconnects before rendering this,
-    // but a reconnect that outlasts the grace window would otherwise evict a
-    // tunnel that is about to come back, so confirm it across the ladder too.
+    // The server already holds a browser request for RECONNECT_GRACE_MS (5s)
+    // while a client reconnects before rendering this, but a reconnect that
+    // outlasts the grace window would otherwise evict a tunnel that is about to
+    // come back, so confirm it across the ladder too.
+    //
     // DEBUGG_TUNNEL_UNKNOWN is deliberately NOT here: the id is gone, and
     // re-probing cannot change that answer.
     'DEBUGG_TUNNEL_OFFLINE',
 ]);
-// ─ 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;
-}
-function isTransientConnectionError(err) {
-    const code = errorCodeOf(err);
-    return code !== undefined && TRANSIENT_CAUSE_CODES.has(code);
-}
 /**
  * Probe that traffic actually flows through the tunnel.
  *
- * Bead k6yq: a freshly created ngrok tunnel can bounce the first connection
- * (HTTP/2 GOAWAY, DNS not yet resolvable) while being perfectly healthy, so
- * transient connection-level failures are retried with a short backoff. Every
- * other outcome — any HTTP response, connection refused, timeout — is returned
- * on the first attempt, so a real fault is never retried into a false pass.
+ * ONE transport, ONE mechanism: a tunnel hostname resolves only inside our
+ * VPC, so it cannot be fetched from the user's machine at all. The health
+ * question goes over the tunnel's own control websocket (PROBE /
+ * PROBE_RESULT), and the server answers it by making a REAL request back
+ * through the public ingress path — same ALB, same nginx, same routing a
+ * browser takes. That is strictly better evidence than the client-side HTTP
+ * GET this used to do while tunnel URLs were public ngrok hostnames, which is
+ * why the HTTP transport (and its `fetchFn` seam, its HTTP/1.1-forcing
+ * `http1Fetch`, and the undici-flake retry codes that went with it) went away
+ * with ngrok rather than being kept as a fallback: there is nothing left it
+ * could reach.
+ *
+ * Bead k6yq: a freshly created tunnel can bounce the first probe while being
+ * perfectly healthy (a session mid-reconnect), so connection-level failures
+ * are retried with a short backoff. Every other outcome — any status the app
+ * answered with, a timeout, an unknown id — is returned on the first attempt,
+ * so a real fault is never retried into a false pass.
  */
 export async function probeTunnelHealth(tunnelUrl, opts = {}) {
     const maxAttempts = Math.max(1, opts.maxAttempts ?? 3);
     const backoff = opts.retryBackoffMs ?? [150, 350];
     const sleep = opts.sleepFn ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const timeoutMs = opts.timeoutMs ?? 5000;
     const started = Date.now();
     let last;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        const { result, retryable } = await probeOnce(tunnelUrl, opts, started);
+        const { result, retryable } = await probeOverControlChannel(tunnelUrl, timeoutMs, started);
         if (!retryable)
             return result;
         last = result;
@@ -246,132 +110,15 @@ export async function probeTunnelHealth(tunnelUrl, opts = {}) {
             await sleep(backoff[attempt - 1] ?? backoff[backoff.length - 1] ?? 150);
         }
     }
-    // Ladder exhausted on a transient error — the edge never came up. Report it:
-    // "not ready" that never becomes ready IS unhealthy.
+    // Ladder exhausted on a transient error — the tunnel never came up. Report
+    // it: "not ready" that never becomes ready IS unhealthy.
     return last;
 }
-async function probeOnce(tunnelUrl, opts, started) {
-    const timeoutMs = opts.timeoutMs ?? 5000;
-    // A debugg tunnel hostname resolves only inside our VPC, so it cannot be
-    // fetched from the user's machine at all. Its health question goes over the
-    // tunnel's own control websocket instead, and the server answers it by
-    // making a REAL request through the public ingress path — same ALB, same
-    // nginx, same routing a browser takes. Everything below this branch (the
-    // retry ladder, the confirm-across-retries rule, the result shape the
-    // handlers render) is shared by both transports.
-    if (tunnelDomainFor(tunnelUrl)?.transport === 'debugg') {
-        return probeOverControlChannel(tunnelUrl, timeoutMs, started);
-    }
-    // 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 {
-        const res = await fetchImpl(tunnelUrl, {
-            method: 'GET',
-            redirect: 'manual',
-            signal: controller.signal,
-            // Many user apps reject HEAD; stick to GET for broader compatibility.
-            headers: { 'User-Agent': 'debugg-ai-mcp/tunnel-health-probe' },
-        });
-        clearTimeout(timer);
-        // Read body so we can inspect for ngrok error markers. Cap at 4KB —
-        // ngrok error pages are small; a full user app body is a waste.
-        const bodyText = await readCapped(res, 4096);
-        const ngrokErr = extractNgrokErrorCode(bodyText);
-        // 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: notFound,
-                result: {
-                    healthy: false,
-                    status: res.status,
-                    code: 'NGROK_ERROR',
-                    ngrokErrorCode: ngrokErr,
-                    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,
-                },
-            };
-        }
-        if (res.status === 502 || res.status === 504) {
-            return {
-                retryable: false,
-                result: {
-                    healthy: false,
-                    status: res.status,
-                    code: 'BAD_GATEWAY',
-                    detail: `tunnel returned ${res.status} without an ngrok error marker — gateway is rejecting upstream`,
-                    elapsedMs: Date.now() - started,
-                },
-            };
-        }
-        // Any other response (incl. 4xx from user's app) means traffic reached
-        // the dev server — that's healthy from the TUNNEL's perspective. The
-        // user's 404 is a user concern, not a tunnel concern.
-        return {
-            retryable: false,
-            result: {
-                healthy: true,
-                status: res.status,
-                elapsedMs: Date.now() - started,
-            },
-        };
-    }
-    catch (err) {
-        clearTimeout(timer);
-        const e = err;
-        if (e?.name === 'AbortError' || /abort|timeout/i.test(e?.message ?? '')) {
-            // Not retried: a hanging tunnel must not cost 3x the timeout budget.
-            return {
-                retryable: false,
-                result: {
-                    healthy: false,
-                    code: 'TIMEOUT',
-                    detail: `tunnel health probe timed out after ${timeoutMs}ms`,
-                    elapsedMs: Date.now() - started,
-                },
-            };
-        }
-        // Surface the cause code: undici reports every network failure as the
-        // undiagnosable "fetch failed" and hides the truth in err.cause.
-        const causeCode = errorCodeOf(e);
-        const baseMsg = e?.message ?? String(err);
-        const causeMsg = e?.cause?.message;
-        const detail = causeCode
-            ? `${baseMsg} (${causeCode}${causeMsg && causeMsg !== baseMsg ? `: ${causeMsg}` : ''})`
-            : baseMsg;
-        return {
-            retryable: isTransientConnectionError(e),
-            result: {
-                healthy: false,
-                code: 'NETWORK_ERROR',
-                detail,
-                elapsedMs: Date.now() - started,
-            },
-        };
-    }
-}
-// ─ Control-channel probe (debugg transport) ──────────────────────────────────
+// ─ Control-channel probe ─────────────────────────────────────────────────────
 /**
  * Ask the tunnel server to fetch `path` back through this tunnel and report
- * what it got. Maps PROBE_RESULT onto the same TunnelHealthProbeResult the
- * HTTP path produces — the mapping is pinned on bead debugg_ai_mcp-xkoh.1.2 §9
- * and must not be re-derived here.
+ * what it got. The PROBE_RESULT → TunnelHealthProbeResult mapping is pinned on
+ * bead debugg_ai_mcp-xkoh.1.2 §9 and must not be re-derived here.
  */
 async function probeOverControlChannel(tunnelUrl, timeoutMs, started) {
     const elapsed = () => Date.now() - started;
@@ -384,8 +131,8 @@ async function probeOverControlChannel(tunnelUrl, timeoutMs, started) {
             retryable: false,
             result: {
                 healthy: false,
-                code: 'NGROK_ERROR',
-                ngrokErrorCode: 'DEBUGG_TUNNEL_UNKNOWN',
+                code: 'TUNNEL_ERROR',
+                tunnelErrorCode: 'DEBUGG_TUNNEL_UNKNOWN',
                 detail: 'no live debugg tunnel session in this process for this hostname',
                 elapsedMs: elapsed(),
             },
@@ -416,8 +163,8 @@ async function probeOverControlChannel(tunnelUrl, timeoutMs, started) {
             result: {
                 healthy: false,
                 status,
-                code: 'NGROK_ERROR',
-                ngrokErrorCode: marker,
+                code: 'TUNNEL_ERROR',
+                tunnelErrorCode: marker,
                 detail: notFound
                     ? `the tunnel server returned ${marker} — no client is connected for this tunnel`
                     : `the tunnel server returned ${marker} — tunnel established but traffic could not reach the dev server`,
@@ -443,8 +190,8 @@ async function probeOverControlChannel(tunnelUrl, timeoutMs, started) {
         return { retryable: false, result: { healthy: true, status, elapsedMs: elapsed() } };
     }
     if (error === 'TIMEOUT') {
-        // Not retried, for the same reason the HTTP path does not: a hanging
-        // tunnel must not cost three times the timeout budget.
+        // Not retried: a hanging tunnel must not cost three times the timeout
+        // budget.
         return {
             retryable: false,
             result: {
@@ -478,62 +225,36 @@ function probePathOf(tunnelUrl) {
         return '/';
     }
 }
-// ─ helpers ───────────────────────────────────────────────────────────────────
-async function readCapped(res, maxBytes) {
-    if (!res.body)
-        return '';
-    const reader = res.body.getReader();
-    const decoder = new TextDecoder();
-    let total = 0;
-    let out = '';
-    try {
-        while (total < maxBytes) {
-            const { value, done } = await reader.read();
-            if (done)
-                break;
-            const remaining = maxBytes - total;
-            const chunk = value.length > remaining ? value.slice(0, remaining) : value;
-            out += decoder.decode(chunk, { stream: true });
-            total += chunk.length;
-            if (value.length > remaining) {
-                // Got enough; cancel the rest.
-                await reader.cancel().catch(() => { });
-                break;
-            }
-        }
-        out += decoder.decode();
-    }
-    catch {
-        /* ignore read errors — we return what we have */
-    }
-    return out;
-}
+// ─ Error markers ─────────────────────────────────────────────────────────────
 /**
  * The debugg tunnel server's error markers, spelled out rather than matched by
  * a `DEBUGG_TUNNEL_[A-Z_]+` pattern.
  *
  * A pattern would also match this repo's own `DEBUGG_TUNNEL_FAULT_MODE` env var
- * (services/ngrok/tunnelFaultInjection.ts). This function is used on RUN
+ * (services/tunnel/tunnelFaultInjection.ts). This function is used on RUN
  * EVIDENCE as well as on response bodies (testPageChangesHandler's
- * findNgrokErrorMarker), so a log line mentioning that variable would otherwise
+ * findTunnelErrorMarker), so a log line mentioning that variable would otherwise
  * be read as proof that the browser hit our error page, and a genuine UI
  * failure would be reclassified as an infrastructure fault.
+ *
+ * ngrok's own error codes used to be matched here too. They went with the
+ * ngrok transport: no tunnel this client can create is served by ngrok, so
+ * matching them would be dead logic that reads as live — and worse, it would
+ * reclassify a genuine app failure as an infrastructure fault if a user's own
+ * page ever mentioned one.
  */
 const DEBUGG_TUNNEL_MARKERS = Object.freeze([
     'DEBUGG_TUNNEL_OFFLINE',
     'DEBUGG_TUNNEL_UNKNOWN',
     'DEBUGG_TUNNEL_UPSTREAM_REFUSED',
 ]);
-const MARKER_PATTERN = new RegExp(`ERR_NGROK_\\d+|${DEBUGG_TUNNEL_MARKERS.join('|')}`);
+const MARKER_PATTERN = new RegExp(DEBUGG_TUNNEL_MARKERS.join('|'));
 /**
- * The stable error marker a tunnel put in front of the user's app, from either
- * transport: ngrok's `ERR_NGROK_*` or the debugg server's `DEBUGG_TUNNEL_*`.
- *
- * Name kept (and with it `TunnelHealthProbeResult.ngrokErrorCode` and
- * `code: 'NGROK_ERROR'`) because handlers echo these into tool output;
- * renaming them is part of deleting ngrok, not of adding a transport.
+ * The stable error marker the tunnel server put in front of the user's app,
+ * if any. Handlers echo it into tool output, so it is the one piece of
+ * evidence that distinguishes "our tunnel broke" from "the app failed".
  */
-export function extractNgrokErrorCode(body) {
+export function extractTunnelErrorCode(body) {
     const match = body.match(MARKER_PATTERN);
     return match ? match[0] : undefined;
 }

package/dist/utils/telemetry.js

@@ -56,15 +56,15 @@ export const TelemetryEvents = {
     TUNNEL_PROVISIONED: 'tunnel.provisioned',
     TUNNEL_PROVISION_RETRY: 'tunnel.provision_retry',
     TUNNEL_STOPPED: 'tunnel.stopped',
-    // services/ngrok/tunnelManager.ts — the session tunnel's Caddy instance
+    // services/tunnel/tunnelManager.ts — the session tunnel's Caddy instance
     // crash-respawned onto a DIFFERENT local proxy port (sticky-port reclaim
-    // failed). The existing ngrok tunnel is now dialing a dead port, so the
+    // failed). The existing tunnel is now dialing a dead port, so the
     // whole session tunnel is evicted and must be recreated on the next call
     // (see docs/local-tunnel-multiplexer-architecture-2026-07-31.md §2.3).
     TUNNEL_EVICTED_PORT_CHANGED: 'tunnel.evicted_port_changed',
-    // services/ngrok/tunnelManager.ts — stopTunnel()'s unconditional-removal
+    // services/tunnel/tunnelManager.ts — stopTunnel()'s unconditional-removal
     // contract (§2.3): map state is always removed before cleanup I/O runs, so
-    // a partial failure here (ngrok disconnect / caddy.stop() / key revoke)
+    // a partial failure here (tunnel disconnect / caddy.stop() / key revoke)
     // never leaves stale-but-discoverable state. Fired once per failed step.
     TUNNEL_TEARDOWN_PARTIAL_FAILURE: 'tunnel.teardown_partial_failure',
     TEMPLATE_LOOKUP: 'template.lookup',

package/dist/utils/tunnelContext.js

@@ -3,11 +3,11 @@
  *
  * Centralizes:
  *  - resolving user input url to a concrete URL
- *  - creating / reusing ngrok tunnels after the backend returns a tunnelKey
+ *  - creating / reusing tunnels after the backend returns a tunnelKey
  *  - acquiring/releasing this session's shared Caddy port route (§2.4)
  *  - sanitizing backend responses so callers only ever see the original URL
  */
-import { tunnelManager, getSessionKey } from '../services/ngrok/tunnelManager.js';
+import { tunnelManager, getSessionKey } from '../services/tunnel/tunnelManager.js';
 import { isLocalhostUrl, replaceTunnelUrls, retargetTunnelUrl, extractLocalhostPort } from './urlParser.js';
 // ─── URL resolution ──────────────────────────────────────────────────────────
 /**
@@ -28,7 +28,7 @@ export function buildContext(originalUrl) {
 }
 // ─── Tunnel creation ─────────────────────────────────────────────────────────
 /**
- * Check whether this SESSION already has a tunnel (§2.1 — one ngrok tunnel
+ * Check whether this SESSION already has a tunnel (§2.1 — one tunnel
  * per session key, not per local port). If found, touches its timer and
  * returns an enriched context retargeted at this caller's own path. Returns
  * null for public URLs or when this session has no tunnel yet.
@@ -57,14 +57,16 @@ export function findExistingTunnel(ctx) {
  * No-op for public URLs.
  *
  * @param ctx       - Context built from `buildContext()`
- * @param tunnelKey - Auth token from the backend (short-lived ngrok key)
- * @param tunnelId  - ID to use as the ngrok subdomain (only takes effect the
- *                    first time this session creates a tunnel)
+ * @param tunnelKey - Auth token from the backend (short-lived tunnel token)
+ * @param tunnelId  - ID to use as the tunnel hostname's label (only takes
+ *                    effect the first time this session creates a tunnel).
+ *                    The token is bound to it, so it must be the backend's.
  * @param keyId     - Backend key ID; stored on the tunnel so it is revoked on stop
  * @param revokeKey - Callback that revokes the backend tunnel (called when tunnel stops)
- * @param selection - The provision response's transport fields. Omitted means
- *                    ngrok, which is what an old backend implies, so every
- *                    existing caller keeps its meaning.
+ * @param selection - The provision response's relayUrl / tunnelDomain /
+ *                    tunnelId. Omitting it leaves the transport with nowhere
+ *                    to connect, so every handler must pass the provision
+ *                    (locked by __tests__/handlers/tunnelSelectionWiring.test.ts).
  */
 export async function ensureTunnel(ctx, tunnelKey, tunnelId, keyId, revokeKey, selection) {
     if (!ctx.isLocalhost)