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

package/dist/services/ngrok/tunnelRegistry.js

@@ -1,8 +1,26 @@
 /**
- * Cross-process tunnel registry.
+ * Cross-process tunnel registry — WRITE-MOSTLY OBSERVABILITY ONLY.
  *
- * Lets multiple MCP server instances on the same machine discover and share
- * ngrok tunnels instead of each provisioning a duplicate for the same port.
+ * Under the old per-port model this registry was load-bearing for
+ * correctness: it was how a second MCP instance on the same machine
+ * discovered and BORROWED an existing tunnel instead of provisioning a
+ * duplicate for the same port. That borrowing mechanism (and everything that
+ * existed only to make it safe — freshness TTLs, PID-reuse defenses,
+ * adopt/reconcile against the local ngrok agent) is retired outright by
+ * docs/local-tunnel-multiplexer-architecture-2026-07-31.md §4: "No sharing,
+ * ever, at any granularity. Each session key gets its own Caddy instance and
+ * its own ngrok tunnel."
+ *
+ * What remains is a diagnostic view: `RegistryEntry` rows, keyed by
+ * `tunnelId` (not port — a port no longer identifies anything unique once
+ * one Caddy instance can be repointed across many ports, and one HTTP-mode
+ * process can host many session keys sharing one port namespace). Nothing in
+ * `TunnelManager` reads this registry to make a reuse/borrow decision
+ * anymore; it only writes to it (best-effort) so `~/.debugg-ai/tunnels.json`
+ * stays useful for a human debugging "what tunnels does this machine have
+ * open." An over-eager prune or a `$TMPDIR`-split process (bead `fcbm`) can
+ * therefore only corrupt the diagnostic view now, never correctness — a
+ * deliberate, accepted downgrade in what this file is trusted for (§6).
  *
  * The file registry uses an atomic rename-write so concurrent processes never
  * see a partial JSON file.  All operations are best-effort — errors are
@@ -14,27 +32,24 @@
  * 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.
+ * SEPARATE registries and never saw each other's diagnostic rows.
  *
  * 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.
+ * once, so rows already written on the old path stay visible.
  */
 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.
+ * The pre-fcbm location. Still READ (and merged from) so rows written 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.
+ * Never written to, and never deleted: a still-running older MCP may be
+ * reading it.
  */
 export function getLegacyRegistryFilePath() {
     return join(tmpdir(), 'debugg-ai-tunnels.json');
@@ -55,14 +70,9 @@ 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.
+ * in the file: a row we have ALREADY considered and deliberately swept, and
+ * one an old-build MCP wrote after we swept. A `lastAccessedAt` relative to
+ * our last write separates them.
  */
 const sweptAt = new Map();
 // ── File-backed implementation (production) ───────────────────────────────────
@@ -77,31 +87,15 @@ const sweptAt = new Map();
 export function createFileRegistry(registryFile = getRegistryFilePath(), legacyFile = getLegacyRegistryFilePath()) {
     const store = {
         read() {
-            // 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.
+            // Overlay the legacy registry on EVERY read, not just once at startup —
+            // see mergeLegacyRegistry()'s doc comment for why a one-shot merge at
+            // process start is not enough during a rollout.
             return overlayLegacy(readRegistryFile(registryFile), legacyFile, registryFile);
         },
         write(data) {
             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.
+                // 0o700: the registry names every local tunnel this user has open.
                 mkdirSync(dirname(registryFile), { recursive: true, mode: 0o700 });
                 writeFileSync(tmp, JSON.stringify(data));
                 // Same directory as the target, so the rename is same-filesystem and
@@ -128,28 +122,27 @@ export function createFileRegistry(registryFile = getRegistryFilePath(), legacyF
 /**
  * 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.
+ * Merge, not move: a row only wins if this path has nothing for that
+ * tunnelId or has something older. A tunnel both files know about keeps
+ * whichever record was touched most recently.
  */
 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)
+    const ids = Object.keys(legacy);
+    if (ids.length === 0)
         return;
     const current = store.read();
     let merged = 0;
-    for (const port of ports) {
-        const entry = legacy[port];
+    for (const id of ids) {
+        const entry = legacy[id];
         if (!isRegistryEntry(entry))
             continue;
-        const mine = current[port];
+        const mine = current[id];
         if (!mine || entry.lastAccessedAt > mine.lastAccessedAt) {
-            current[port] = entry;
+            current[id] = entry;
             merged++;
         }
     }
@@ -158,26 +151,23 @@ function mergeLegacyRegistry(store, registryFile, legacyFile) {
 }
 /**
  * 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.
+ * Read-side only — never writes.
  */
 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)) {
+    for (const [id, 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.
+        // Older than our last complete write => we already saw it and chose not
+        // to keep it (or it belongs to a tunnel that no longer exists).
         if (entry.lastAccessedAt <= watermark)
             continue;
-        const mine = current[port];
+        const mine = current[id];
         if (!mine || entry.lastAccessedAt > mine.lastAccessedAt)
-            current[port] = entry;
+            current[id] = entry;
     }
     return current;
 }
@@ -199,7 +189,7 @@ function isRegistryEntry(value) {
     return (!!e &&
         typeof e === 'object' &&
         typeof e.tunnelId === 'string' &&
-        typeof e.port === 'number' &&
+        typeof e.sessionKey === 'string' &&
         typeof e.ownerPid === 'number' &&
         typeof e.lastAccessedAt === 'number');
 }
@@ -243,20 +233,17 @@ function checkPid(pid) {
  * Shared prune logic — read, filter, write back. Used by both the file-backed
  * and in-memory implementations so the eviction policy lives in one place.
  *
- * Eviction rule: drop entries where EITHER the owner PID is dead OR the entry
- * hasn't been touched within `staleAfterMs`. The freshness check is what
- * defends against PID-reuse (bead 3th).
+ * Eviction rule: drop entries whose owner PID is dead. That's the whole
+ * rule now — see the `prune()` doc comment on `RegistryStore` for why the
+ * old freshness window is gone.
  */
-function pruneRegistryData(store, opts) {
-    const now = opts.nowMs ?? Date.now();
+function pruneRegistryData(store, _opts) {
     const data = store.read();
     const next = {};
     let pruned = 0;
-    for (const [port, entry] of Object.entries(data)) {
-        const aliveAndFresh = store.isPidAlive(entry.ownerPid) &&
-            (now - entry.lastAccessedAt) <= opts.staleAfterMs;
-        if (aliveAndFresh) {
-            next[port] = entry;
+    for (const [id, entry] of Object.entries(data)) {
+        if (store.isPidAlive(entry.ownerPid)) {
+            next[id] = entry;
         }
         else {
             pruned++;

package/dist/services/verdictAdapter.js

@@ -80,5 +80,7 @@ export function adaptVerdict(execution, opts = {}) {
     if (evidence?.loginError && typeof evidence.loginError === 'object') {
         relay.loginError = evidence.loginError;
     }
+    if (typeof evidence?.report === 'string' && evidence.report)
+        relay.report = evidence.report;
     return relay;
 }

package/dist/utils/telemetry.js

@@ -56,6 +56,22 @@ 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
+    // crash-respawned onto a DIFFERENT local proxy port (sticky-port reclaim
+    // failed). The existing ngrok 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
+    // contract (§2.3): map state is always removed before cleanup I/O runs, so
+    // a partial failure here (ngrok 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',
     PROJECT_LOOKUP: 'project.lookup',
+    // services/caddy/portLock.ts — maxHoldMs is an OBSERVABILITY-ONLY watchdog
+    // (see docs/local-tunnel-multiplexer-architecture-2026-07-31.md §2.4/§4):
+    // it never force-releases the lock, it only surfaces that a generation has
+    // been held unusually long.
+    PORT_LOCK_MAX_HOLD_EXCEEDED: 'port_lock.max_hold_exceeded',
 };

package/dist/utils/tunnelContext.js

@@ -4,10 +4,11 @@
  * Centralizes:
  *  - resolving user input url to a concrete URL
  *  - creating / reusing ngrok 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 } from '../services/ngrok/tunnelManager.js';
-import { isLocalhostUrl, replaceTunnelUrls, extractLocalhostPort, retargetTunnelUrl } from './urlParser.js';
+import { tunnelManager, getSessionKey } from '../services/ngrok/tunnelManager.js';
+import { isLocalhostUrl, replaceTunnelUrls, retargetTunnelUrl, extractLocalhostPort } from './urlParser.js';
 // ─── URL resolution ──────────────────────────────────────────────────────────
 /**
  * Resolve tool input to a concrete URL string.
@@ -27,24 +28,22 @@ export function buildContext(originalUrl) {
 }
 // ─── Tunnel creation ─────────────────────────────────────────────────────────
 /**
- * Check whether an active tunnel already exists for the same local port.
- * If found, touches its timer and returns an enriched context pointing at it.
- * Returns null for public URLs or when no tunnel is active for that port.
+ * Check whether this SESSION already has a tunnel (§2.1 — one ngrok 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.
  *
  * Call this BEFORE provisioning a new key — if it returns a context, skip the provision.
  */
 export function findExistingTunnel(ctx) {
     if (!ctx.isLocalhost)
         return null;
-    const port = extractLocalhostPort(ctx.originalUrl);
-    if (!port)
-        return null;
-    const existing = tunnelManager.getTunnelForPort(port);
+    const existing = tunnelManager.getSessionTunnelInfo(getSessionKey());
     if (!existing)
         return null;
     tunnelManager.touchTunnel(existing.tunnelId);
-    // Bead zmc9: retarget to THIS caller's path — never replay existing.publicUrl,
-    // which carries the path of whichever call created the (port-keyed) tunnel.
+    // Bead zmc9: retarget to THIS caller's path — never replay another call's
+    // path baked into a previously-returned URL for this same session tunnel.
     return {
         ...ctx,
         tunnelId: existing.tunnelId,
@@ -52,22 +51,60 @@ export function findExistingTunnel(ctx) {
     };
 }
 /**
- * Create (or reuse) a tunnel for a localhost URL.
+ * Create (or reuse) this session's tunnel (§2.1) for a localhost URL.
  *
  * Call this AFTER the backend returns a `tunnelKey` and `tunnelId`.
  * 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
+ * @param tunnelId  - ID to use as the ngrok subdomain (only takes effect the
+ *                    first time this session creates a tunnel)
  * @param keyId     - Backend key ID; stored on the tunnel so it is revoked on stop
  * @param revokeKey - Callback that revokes the backend key (called when tunnel stops)
  */
 export async function ensureTunnel(ctx, tunnelKey, tunnelId, keyId, revokeKey) {
     if (!ctx.isLocalhost)
         return ctx;
-    const result = await tunnelManager.processUrl(ctx.originalUrl, tunnelKey, tunnelId, keyId, revokeKey);
-    return { ...ctx, tunnelId: result.tunnelId, targetUrl: result.url };
+    const info = await tunnelManager.ensureSessionTunnel(getSessionKey(), tunnelKey, tunnelId, keyId, revokeKey);
+    return { ...ctx, tunnelId: info.tunnelId, targetUrl: retargetTunnelUrl(info.tunnelUrl, ctx.originalUrl) };
+}
+// ─── Port route lock (§2.4) ──────────────────────────────────────────────────
+/**
+ * Acquire this session's shared Caddy route for `ctx`'s port, blocking until
+ * Caddy is CONFIRMED pointed at it (§2.4/§3.1 of the architecture doc). Every
+ * localhost-targeting handler must call this immediately after
+ * `findExistingTunnel`/`ensureTunnel` and BEFORE `probeTunnelHealth` — probing
+ * before the repoint is confirmed would probe whatever port happened to be
+ * active a moment ago, not the port this call actually wants.
+ *
+ * No-op (returns `ctx` unchanged) for public URLs and for any ctx that never
+ * got a `tunnelId` (dev mode, or a public URL that never provisioned a
+ * tunnel) — there is no shared route to serialize in either case.
+ */
+export async function acquirePortRoute(ctx, opts) {
+    if (!ctx.isLocalhost || !ctx.tunnelId)
+        return ctx;
+    const info = tunnelManager.getTunnelInfo(ctx.tunnelId);
+    if (!info) {
+        throw new Error(`acquirePortRoute: no TunnelInfo for tunnel ${ctx.tunnelId} (session tunnel vanished?)`);
+    }
+    const port = extractLocalhostPort(ctx.originalUrl);
+    if (port === undefined) {
+        throw new Error(`acquirePortRoute: could not extract a port from localhost URL: ${ctx.originalUrl}`);
+    }
+    const isHttpsLocal = ctx.originalUrl.startsWith('https:');
+    const routeLock = await info.portLock.acquire({ port, isHttpsLocal }, opts);
+    return { ...ctx, routeLock };
+}
+/**
+ * Release this request's claim on the session's shared Caddy route, if it
+ * holds one. Call from the handler's existing `finally` block — safe/no-op
+ * when `ctx.routeLock` was never set (public URL, dev mode, or the call never
+ * reached `acquirePortRoute`).
+ */
+export function releasePortRoute(ctx) {
+    ctx.routeLock?.release();
 }
 /**
  * Stop the tunnel associated with a context (fire-and-forget safe).

package/dist/utils/tunnelDisposition.js

@@ -36,7 +36,6 @@
  * run's own evidence (bead 4bui, the one live-confirmed source of ERR_NGROK_*).
  */
 import { tunnelManager } from '../services/ngrok/tunnelManager.js';
-import { extractLocalhostPort } from './urlParser.js';
 import { Logger } from './logger.js';
 const logger = new Logger({ module: 'tunnelDisposition' });
 /**
@@ -91,10 +90,13 @@ export function isEndpointGone(ngrokErrorCode) {
  * them (run_test_suite had already drifted: it evicted on every failure and never
  * got bead k34o's shared-registry eviction at all).
  *
- * Endpoint proven gone  → markTunnelDead: for an owned tunnel that disconnects and
- *                         revokes the key; for a BORROWED one it also evicts the
- *                         shared registry entry, which plain stopTunnel leaves
- *                         behind for every other session to re-borrow (bead k34o).
+ * Endpoint proven gone  → markTunnelDead: disconnects the tunnel and revokes its
+ *                         key. Under the per-session-tunnel model (§4 of
+ *                         docs/local-tunnel-multiplexer-architecture-2026-07-31.md)
+ *                         every tunnel is created — never borrowed — by this
+ *                         process, so there is no separate shared-registry
+ *                         adoption record left to evict; bead k34o's borrowed-
+ *                         tunnel half retired along with cross-process borrowing.
  * Anything else         → nothing at all. The caller still returns
  *                         TunnelTrafficBlocked, so the user is told; we simply do
  *                         not spend two billed hours acting on a verdict this
@@ -113,16 +115,6 @@ export function disposeUnhealthyTunnel(args) {
             '(1-hour minimum down, another up) and the next call reuses this one for free.');
         return;
     }
-    const port = extractLocalhostPort(originalUrl);
-    if (typeof port !== 'number') {
-        // markTunnelDead is keyed by port. Without one we cannot evict the shared
-        // entry safely, and a blind stopTunnel is exactly the teardown this module
-        // exists to prevent — so keep the tunnel and say why.
-        logger.warn(`Tunnel ${tunnelId} reported ${health.ngrokErrorCode} but no port could be parsed from ${originalUrl} — ` +
-            'leaving it in place rather than risking a teardown of a live tunnel.');
-        return;
-    }
-    logger.warn(`Tunnel ${tunnelId} on port ${port} reported ${health.ngrokErrorCode} — the endpoint is gone, evicting it ` +
-        'so no session re-borrows the corpse (bead k34o).');
-    tunnelManager.markTunnelDead(port, tunnelId).catch((err) => logger.warn(`Failed to evict dead tunnel ${tunnelId}: ${err}`));
+    logger.warn(`Tunnel ${tunnelId} (${originalUrl}) reported ${health.ngrokErrorCode} — the endpoint is gone, evicting it.`);
+    tunnelManager.markTunnelDead(tunnelId).catch((err) => logger.warn(`Failed to evict dead tunnel ${tunnelId}: ${err}`));
 }

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "3.9.3",
+  "version": "4.0.0",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
+  "caddy": "2.11.3",
   "bin": {
     "debugg-ai-mcp": "dist/index.js"
   },
@@ -57,6 +58,7 @@
   "changelog": "https://github.com/debugg-ai/debugg-ai-mcp/CHANGELOG.md",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0",
+    "@radically-straightforward/caddy": "^2.0.12",
     "axios": "^1.9.0",
     "mkdirp": "^3.0.1",
     "ngrok": "^5.0.0-beta.2",