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

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 = {};