tracegist-mcp-bridge 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to `tracegist-mcp-bridge`.
 
+## 0.4.0
+
+**Remote Live Sessions** — the live shadowing loop now works across machines.
+A tester anywhere starts a remote session in the TraceGist extension and
+shares a code; this bridge joins through a relay and every live tool works
+exactly as it does locally.
+
+- New tool `join_live_session({ code })`: joins the tester's session via a
+  relay (`TRACEGIST_RELAY_URL` env var overrides the default). All live-shadow
+  traffic is end-to-end encrypted with AES-256-GCM using a key derived from
+  the session code — the relay only ever sees ciphertext, and the room ID is
+  a hash of the code, so the relay cannot derive the key.
+- New tool `leave_live_session()`: disconnects from the remote session.
+- `live-session://status` now reports the active transport (`local` / `relay`
+  / `none`) and remote connection state.
+- The local localhost WebSocket transport is unchanged and remains the
+  default; remote mode is purely additive (semver minor).
+- `TRACEGIST_DISABLE_LIVE` now also disables `join_live_session`.
+- Relay reconnects use the same backoff strategy as the extension; a
+  `tester-connected` / `tester-disconnected` live event is pushed when the
+  tester's extension joins or drops.
+
+The relay itself ships separately as the `tracegist-relay` package
+(self-hostable; plain Node + ws).
+
 ## 0.3.0
 
 **Breaking changes:**

package/bin/live-crypto.mjs

@@ -0,0 +1,214 @@
+/**
+ * Remote Live Sessions — session-code derivation and E2E frame crypto.
+ *
+ * Node-side mirror of the extension's lib/remote-session.ts. The two modules
+ * must stay byte-compatible: same code normalization, same room-ID and key
+ * derivation, same AES-256-GCM frame format (see docs/live-protocol.md in the
+ * TraceGist repo). This package is published standalone, so the primitives
+ * are duplicated here rather than imported from the extension codebase.
+ */
+
+import { webcrypto } from "node:crypto";
+
+const subtle = webcrypto.subtle;
+
+/** Crockford base32 alphabet — no I, L, O, U to avoid ambiguity. */
+const CODE_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const CODE_GROUP_LENGTH = 5;
+const CODE_GROUPS = 3;
+
+const ROOM_ID_CONTEXT = "tracegist-room-v1:";
+const HKDF_SALT = "tracegist-live-v1";
+const HKDF_INFO = "aes-256-gcm";
+
+export const FRAME_VERSION = 1;
+
+/** AES-GCM IV length in bytes (protocol constant, see docs/live-protocol.md) */
+const GCM_IV_BYTES = 12;
+
+/**
+ * Normalize a user-entered session code: trim, uppercase.
+ * @param {string} raw
+ * @returns {string | null} normalized code, or null if malformed
+ */
+export function normalizeSessionCode(raw) {
+  const code = String(raw).trim().toUpperCase();
+  const groupPattern = `[${CODE_ALPHABET}]{${CODE_GROUP_LENGTH}}`;
+  const pattern = new RegExp(`^TG(-${groupPattern}){${CODE_GROUPS}}$`);
+  return pattern.test(code) ? code : null;
+}
+
+/**
+ * Derive the relay room ID (hex SHA-256) from a normalized session code.
+ * @param {string} code
+ * @returns {Promise<string>}
+ */
+export async function deriveRoomId(code) {
+  const data = new TextEncoder().encode(ROOM_ID_CONTEXT + code);
+  const digest = await subtle.digest("SHA-256", data);
+  return Buffer.from(digest).toString("hex");
+}
+
+/**
+ * Derive the AES-256-GCM session key from a normalized session code.
+ * @param {string} code
+ * @returns {Promise<CryptoKey>}
+ */
+export async function deriveSessionKey(code) {
+  const encoder = new TextEncoder();
+  const ikm = await subtle.importKey("raw", encoder.encode(code), "HKDF", false, ["deriveKey"]);
+  return subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: encoder.encode(HKDF_SALT),
+      info: encoder.encode(HKDF_INFO),
+    },
+    ikm,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+/**
+ * Encrypt a live-shadow message object into a frame payload.
+ * @param {CryptoKey} key
+ * @param {object} message
+ * @returns {Promise<{v: number, iv: string, ct: string}>}
+ */
+export async function encryptFrame(key, message) {
+  const iv = webcrypto.getRandomValues(new Uint8Array(GCM_IV_BYTES));
+  const plaintext = new TextEncoder().encode(JSON.stringify(message));
+  const ct = await subtle.encrypt({ name: "AES-GCM", iv }, key, plaintext);
+  return {
+    v: FRAME_VERSION,
+    iv: Buffer.from(iv).toString("base64"),
+    ct: Buffer.from(ct).toString("base64"),
+  };
+}
+
+/**
+ * Decrypt a frame payload back into a message object.
+ * Returns null for unknown versions, malformed payloads, or failed
+ * authentication — a tampered or foreign frame must not crash the session.
+ * @param {CryptoKey} key
+ * @param {{v: number, iv: string, ct: string}} payload
+ * @returns {Promise<object | null>}
+ */
+export async function decryptFrame(key, payload) {
+  if (!payload || payload.v !== FRAME_VERSION) return null;
+  try {
+    const iv = Buffer.from(payload.iv, "base64");
+    const ct = Buffer.from(payload.ct, "base64");
+    const plaintext = await subtle.decrypt({ name: "AES-GCM", iv }, key, ct);
+    return JSON.parse(new TextDecoder().decode(plaintext));
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Frame chunking — mirror of lib/remote-session.ts (see that file for the
+// size rationale). Hosted relays cap WebSocket messages (Cloudflare: 1 MiB);
+// oversized inner messages are split into `frame-chunk` parts BEFORE
+// encryption so relays only ever see ordinary frames.
+// ---------------------------------------------------------------------------
+
+/** Inner messages whose UTF-8 size exceeds this are chunked. */
+export const FRAME_CHUNK_THRESHOLD_BYTES = 700_000;
+/** UTF-8 bytes per chunk. */
+export const FRAME_CHUNK_BYTES = 500_000;
+
+/**
+ * Split an oversized inner message into `frame-chunk` parts. Returns null
+ * when the message fits in a single frame. Operates on UTF-8 bytes so
+ * multi-byte characters and surrogate pairs can never be split.
+ * @param {object} message
+ * @returns {Array<{type: "frame-chunk", id: string, seq: number, total: number, data: string}> | null}
+ */
+export function chunkInnerMessage(message) {
+  const bytes = new TextEncoder().encode(JSON.stringify(message));
+  if (bytes.length <= FRAME_CHUNK_THRESHOLD_BYTES) return null;
+  const total = Math.ceil(bytes.length / FRAME_CHUNK_BYTES);
+  const id = webcrypto.randomUUID();
+  const parts = [];
+  for (let seq = 0; seq < total; seq++) {
+    parts.push({
+      type: "frame-chunk",
+      id,
+      seq,
+      total,
+      data: Buffer.from(
+        bytes.subarray(seq * FRAME_CHUNK_BYTES, (seq + 1) * FRAME_CHUNK_BYTES),
+      ).toString("base64"),
+    });
+  }
+  return parts;
+}
+
+/**
+ * Reassembles decrypted `frame-chunk` parts back into the original message.
+ * Non-chunk messages pass through unchanged; chunk parts return null until
+ * the final part completes the message. A part for a new id discards any
+ * incomplete assembly (peer reconnect mid-message).
+ */
+export class FrameChunkAssembler {
+  constructor() {
+    this.id = null;
+    this.parts = [];
+    this.received = 0;
+  }
+
+  /**
+   * @param {object} inner - a decrypted inner message
+   * @returns {object | null} pass-through message, completed reassembly, or null
+   */
+  push(inner) {
+    if (inner.type !== "frame-chunk") return inner;
+
+    const { id, seq, total, data } = inner;
+    if (
+      typeof id !== "string" ||
+      typeof data !== "string" ||
+      !Number.isInteger(seq) ||
+      !Number.isInteger(total) ||
+      total < 1 ||
+      seq < 0 ||
+      seq >= total
+    ) {
+      return null;
+    }
+
+    if (this.id !== id) {
+      this.id = id;
+      this.parts = new Array(total);
+      this.received = 0;
+    }
+
+    if (this.parts.length !== total || this.parts[seq] !== undefined) {
+      this.reset();
+      return null;
+    }
+
+    this.parts[seq] = data;
+    this.received++;
+    if (this.received < total) return null;
+
+    const assembled = this.parts;
+    this.reset();
+    try {
+      const bytes = Buffer.concat(assembled.map((p) => Buffer.from(p, "base64")));
+      return JSON.parse(new TextDecoder().decode(bytes));
+    } catch {
+      // Corrupt part payload — same posture as decryptFrame: drop, don't crash
+      return null;
+    }
+  }
+
+  reset() {
+    this.id = null;
+    this.parts = [];
+    this.received = 0;
+  }
+}

package/bin/tracegist-mcp-bridge.mjs

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
 import { createServer } from "node:http";
-import { WebSocketServer } from "ws";
+import { WebSocketServer, WebSocket } from "ws";
 import JSZip from "jszip";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -26,6 +26,15 @@ import {
   isAllowedLiveShadowOrigin,
   envFlagEnabled,
 } from "./lib.mjs";
+import {
+  normalizeSessionCode,
+  deriveRoomId,
+  deriveSessionKey,
+  encryptFrame,
+  decryptFrame,
+  chunkInnerMessage,
+  FrameChunkAssembler,
+} from "./live-crypto.mjs";
 
 const BRIDGE_NAME = "tracegist-mcp-bridge";
 const { version: BRIDGE_VERSION } = JSON.parse(
@@ -1073,9 +1082,16 @@ server.registerTool(
 // Live Shadowing — WebSocket server + state
 // ---------------------------------------------------------------------------
 
+const liveShadowDisabled = envFlagEnabled(process.env.TRACEGIST_DISABLE_LIVE);
+
 const LIVE_SHADOW_PORT = 19384;
 const LIVE_SHADOW_PORT_RANGE = 5;
 const LIVE_SHADOW_EVENT_BUFFER_SIZE = 2000;
+
+/** Default relay for Remote Live Sessions. Override via TRACEGIST_RELAY_URL. */
+const DEFAULT_RELAY_URL = "wss://relay.tracegist.com";
+const RELAY_RECONNECT_INTERVAL_MS = 3000;
+const RELAY_MAX_RECONNECT_ATTEMPTS = 10;
 const PENDING_QUESTIONS_MAX = 50;
 const WATCH_LIVE_DEFAULT_LIMIT = 100;
 const WATCH_LIVE_MAX_LIMIT = 500;
@@ -1084,6 +1100,8 @@ const WATCH_LIVE_MAX_LIMIT = 500;
 const liveEvents = [];
 let liveEventSeq = 0;
 let liveSessionActive = false;
+/** Which transport owns the current session: "local" | "relay" | null. */
+let liveSessionTransport = null;
 /** @type {{sessionId: string, url: string, title: string, startedAt: number} | null} */
 let liveSessionMeta = null;
 /** @type {import("ws").WebSocket | null} */
@@ -1119,12 +1137,14 @@ async function transcribeLiveVoice(voiceBlobDataUrl) {
 }
 
 /** Push a live event into the ring buffer with auto-incrementing seq.
- *  Seq is always higher than any existing event (including extension-originated ones). */
-function pushLiveEvent(eventType, data) {
+ *  All events are re-sequenced with the bridge's own monotonic counter —
+ *  extension-provided seq numbers restart per session and would collide with
+ *  bridge-originated events, breaking the watch_live_session since_seq cursor. */
+function pushLiveEvent(eventType, data, ts = Date.now()) {
   // Ensure our seq is always higher than the max seq in the buffer
   const maxExistingSeq = liveEvents.length > 0 ? liveEvents[liveEvents.length - 1].seq : 0;
   liveEventSeq = Math.max(liveEventSeq, maxExistingSeq) + 1;
-  liveEvents.push({ seq: liveEventSeq, ts: Date.now(), eventType, data });
+  liveEvents.push({ seq: liveEventSeq, ts, eventType, data });
   if (liveEvents.length > LIVE_SHADOW_EVENT_BUFFER_SIZE) {
     const evictCount = Math.floor(LIVE_SHADOW_EVENT_BUFFER_SIZE * 0.25);
     liveEvents.splice(0, evictCount);
@@ -1170,7 +1190,7 @@ function startLiveShadowServer() {
       ws.on("message", (raw) => {
         try {
           const msg = JSON.parse(String(raw));
-          handleExtensionMessage(msg);
+          handleExtensionMessage(msg, "local");
         } catch (err) {
           console.error(`[${BRIDGE_NAME}] Live shadow: invalid message:`, err);
         }
@@ -1179,7 +1199,7 @@ function startLiveShadowServer() {
       ws.on("close", () => {
         if (activeConnection === ws) {
           activeConnection = null;
-          if (liveSessionActive) {
+          if (liveSessionActive && liveSessionTransport === "local") {
             liveSessionActive = false;
             console.error(`[${BRIDGE_NAME}] Live shadow: session ended (extension disconnected)`);
             try {
@@ -1215,22 +1235,33 @@ function startLiveShadowServer() {
   tryPort(LIVE_SHADOW_PORT);
 }
 
-function handleExtensionMessage(msg) {
+function handleExtensionMessage(msg, source = "local") {
   switch (msg.type) {
-    case "session-start":
+    case "session-start": {
+      // The extension re-announces the session whenever the relay peer
+      // (re)connects. A re-announce of the SAME session must not wipe
+      // buffered events or un-retrieved question responses.
+      const isReannounce = liveSessionActive && liveSessionMeta?.sessionId === msg.sessionId;
       liveSessionActive = true;
+      liveSessionTransport = source;
       liveSessionMeta = {
         sessionId: msg.sessionId,
         url: msg.url,
         title: msg.title,
-        startedAt: Date.now(),
+        startedAt: isReannounce ? liveSessionMeta.startedAt : Date.now(),
       };
-      liveEvents.length = 0;
-      liveEventSeq = 0;
-      pendingQuestions.length = 0;
-      questionResponses.clear();
-      liveInteractions.length = 0;
-      console.error(`[${BRIDGE_NAME}] Live shadow: session started (${msg.sessionId})`);
+      if (!isReannounce) {
+        liveEvents.length = 0;
+        // liveEventSeq intentionally NOT reset: the watch_live_session cursor
+        // stays monotonic across sessions, so a stale since_seq from a previous
+        // session can never silently filter out new events.
+        pendingQuestions.length = 0;
+        questionResponses.clear();
+        liveInteractions.length = 0;
+      }
+      console.error(
+        `[${BRIDGE_NAME}] Live shadow: session ${isReannounce ? "re-announced" : "started"} (${msg.sessionId}, ${source})`,
+      );
       // Notify MCP clients that resources changed
       try {
         server.sendResourceListChanged();
@@ -1238,19 +1269,13 @@ function handleExtensionMessage(msg) {
         // Not all transports support notifications
       }
       break;
+    }
 
     case "event":
-      liveEvents.push({
-        seq: msg.seq,
-        ts: msg.ts,
-        eventType: msg.eventType,
-        data: msg.data,
-      });
-      if (liveEvents.length > LIVE_SHADOW_EVENT_BUFFER_SIZE) {
-        // Batch-evict oldest 25% to amortize the O(n) splice cost
-        const evictCount = Math.floor(LIVE_SHADOW_EVENT_BUFFER_SIZE * 0.25);
-        liveEvents.splice(0, evictCount);
-      }
+      // Re-sequence with the bridge's monotonic counter (see pushLiveEvent);
+      // the extension's own seq restarts per session and would collide with
+      // bridge-originated events.
+      pushLiveEvent(msg.eventType, msg.data, msg.ts);
       break;
 
     case "question-response": {
@@ -1374,6 +1399,9 @@ function handleExtensionMessage(msg) {
     }
 
     case "session-end":
+      // A session-end from the transport that doesn't own the session must
+      // not tear down the owning transport's session.
+      if (liveSessionTransport && source !== liveSessionTransport) break;
       liveSessionActive = false;
       console.error(`[${BRIDGE_NAME}] Live shadow: session ended`);
       try {
@@ -1385,6 +1413,265 @@ function handleExtensionMessage(msg) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Remote Live Sessions (relay transport)
+//
+// The extension and this bridge meet at a relay and exchange the same
+// live-shadow messages as the local transport, AES-256-GCM encrypted with a
+// key derived from the session code (see docs/live-protocol.md). The relay
+// only ever sees ciphertext.
+// ---------------------------------------------------------------------------
+
+/** @type {WebSocket | null} */
+let relayWs = null;
+/** @type {CryptoKey | null} */
+let relaySessionKey = null;
+let relayRoomId = null;
+let relayUrl = null;
+let relayPeerPresent = false;
+let relayIntentionalClose = false;
+let relayReconnectAttempts = 0;
+/** @type {ReturnType<typeof setTimeout> | undefined} */
+let relayReconnectTimer;
+
+function isRelayConnected() {
+  return relayWs !== null && relayWs.readyState === WebSocket.OPEN;
+}
+
+/** True when the extension that owns the current session is reachable. */
+function isExtensionLinked() {
+  // Route by session owner so a locally-connected extension can never hijack
+  // a remote session (or vice versa).
+  if (liveSessionTransport === "relay") return isRelayConnected() && relayPeerPresent;
+  if (liveSessionTransport === "local") return activeConnection !== null;
+  return activeConnection !== null || (isRelayConnected() && relayPeerPresent);
+}
+
+/** Serializes relay sends so chunk ids can never interleave on the wire —
+ * the receiver's single-slot reassembler relies on it (mirrors the
+ * extension's sendChain in lib/live-shadow.ts). */
+let relaySendChain = Promise.resolve();
+
+/**
+ * Send a live-shadow message to the extension that owns the current session:
+ * the local WebSocket (plaintext, localhost-only) or the relay (E2E
+ * encrypted). Throws if the owning transport is unavailable.
+ * @param {object} msg
+ */
+async function sendToExtension(msg) {
+  const canRelay = isRelayConnected() && relaySessionKey !== null;
+  const useRelay = canRelay && (liveSessionTransport === "relay" || activeConnection === null);
+  if (useRelay) {
+    // Hosted relays cap WebSocket messages (Cloudflare: 1 MiB); oversized
+    // messages travel as encrypted frame-chunk parts (see live-crypto.mjs).
+    const send = relaySendChain.then(async () => {
+      // Re-check at execution time: the socket may have closed while an
+      // earlier message in the chain was encrypting.
+      if (!isRelayConnected() || relaySessionKey === null) {
+        throw new Error("Extension not connected (relay closed while sending)");
+      }
+      const parts = chunkInnerMessage(msg) ?? [msg];
+      for (const part of parts) {
+        const payload = await encryptFrame(relaySessionKey, part);
+        relayWs.send(JSON.stringify({ type: "frame", payload }));
+      }
+    });
+    // One failed send must not poison the chain for later messages.
+    relaySendChain = send.catch(() => {});
+    return send;
+  }
+  if (activeConnection && liveSessionTransport !== "relay") {
+    activeConnection.send(JSON.stringify(msg));
+    return;
+  }
+  throw new Error("Extension not connected (no local or relay transport)");
+}
+
+function disconnectRelay() {
+  relayIntentionalClose = true;
+  if (relayReconnectTimer) {
+    clearTimeout(relayReconnectTimer);
+    relayReconnectTimer = undefined;
+  }
+  if (relayWs && relayWs.readyState <= WebSocket.OPEN) {
+    try {
+      relayWs.close();
+    } catch {
+      // ignore
+    }
+  }
+  relayWs = null;
+  relaySessionKey = null;
+  relayRoomId = null;
+  relayPeerPresent = false;
+  relayReconnectAttempts = 0;
+}
+
+/**
+ * Connect to the relay and join the session's room as the agent.
+ * Resolves once the join is acknowledged.
+ * @returns {Promise<{peerPresent: boolean}>}
+ */
+function connectRelay() {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    // Hosted relays (Cloudflare Worker) route the upgrade to a per-room
+    // Durable Object, so the room ID must ride on the URL; the npm relay
+    // ignores the query string. The room ID is a hash — not the secret.
+    let wsUrl;
+    try {
+      const parsed = new URL(relayUrl);
+      parsed.searchParams.set("room", relayRoomId);
+      wsUrl = parsed.toString();
+    } catch {
+      reject(new Error(`Invalid relay URL: ${relayUrl}`));
+      return;
+    }
+    const ws = new WebSocket(wsUrl);
+    relayWs = ws;
+
+    const settle = (fn, arg) => {
+      if (!settled) {
+        settled = true;
+        fn(arg);
+      }
+    };
+
+    ws.on("open", () => {
+      relayReconnectAttempts = 0;
+      ws.send(JSON.stringify({ type: "join", room: relayRoomId, role: "agent" }));
+    });
+
+    // Frames are decrypted asynchronously; chain them so slow decryption of
+    // one frame can never reorder events behind a faster later frame (the
+    // live event buffer assumes ascending seq).
+    let frameChain = Promise.resolve();
+    // Per-connection: a new socket can never continue a previous reassembly.
+    const chunkAssembler = new FrameChunkAssembler();
+
+    ws.on("message", (raw) => {
+      // A superseded socket must not mutate current-connection state.
+      if (relayWs !== ws) return;
+      let msg;
+      try {
+        msg = JSON.parse(String(raw));
+      } catch {
+        return;
+      }
+
+      switch (msg.type) {
+        case "joined":
+          relayPeerPresent = !!msg.peerPresent;
+          console.error(
+            `[${BRIDGE_NAME}] Relay: joined room (tester ${relayPeerPresent ? "present" : "not connected yet"})`,
+          );
+          settle(resolve, { peerPresent: relayPeerPresent });
+          break;
+
+        case "peer-joined":
+          relayPeerPresent = true;
+          pushLiveEvent("tester-connected", {
+            hint: "The tester's extension joined the remote session.",
+          });
+          break;
+
+        case "peer-left":
+          relayPeerPresent = false;
+          if (liveSessionActive) {
+            liveSessionActive = false;
+            console.error(`[${BRIDGE_NAME}] Relay: session ended (tester disconnected)`);
+            try {
+              server.sendResourceListChanged();
+            } catch {
+              // Not all transports support notifications
+            }
+          }
+          pushLiveEvent("tester-disconnected", {
+            hint: "The tester's extension left the remote session.",
+          });
+          break;
+
+        case "frame": {
+          const payload = msg.payload;
+          frameChain = frameChain
+            .then(async () => {
+              const inner = await decryptFrame(relaySessionKey, payload);
+              if (inner === null) {
+                console.error(`[${BRIDGE_NAME}] Relay: dropped undecryptable frame`);
+                return;
+              }
+              // Chunk parts return null until the final part completes.
+              const complete = chunkAssembler.push(inner);
+              if (complete !== null) {
+                handleExtensionMessage(complete, "relay");
+              }
+            })
+            .catch((err) => {
+              // One bad frame must not poison the chain and freeze the session
+              console.error(`[${BRIDGE_NAME}] Relay: frame handling failed:`, err);
+            });
+          break;
+        }
+
+        case "error":
+          console.error(`[${BRIDGE_NAME}] Relay error: ${msg.code} — ${msg.message}`);
+          settle(reject, new Error(`Relay error: ${msg.code}`));
+          break;
+      }
+    });
+
+    ws.on("close", () => {
+      settle(reject, new Error("Relay connection closed before join completed"));
+      // A superseded socket's late close event must not clobber the state of
+      // the current connection or arm a spurious reconnect for the new room.
+      if (relayWs !== ws) return;
+      relayWs = null;
+      relayPeerPresent = false;
+      if (!relayIntentionalClose && relayRoomId) {
+        scheduleRelayReconnect();
+      }
+    });
+
+    ws.on("error", (err) => {
+      console.error(`[${BRIDGE_NAME}] Relay connection error: ${err.message}`);
+      settle(reject, err);
+      // close fires after error; reconnect handled there
+    });
+  });
+}
+
+function scheduleRelayReconnect() {
+  if (relayReconnectAttempts >= RELAY_MAX_RECONNECT_ATTEMPTS) {
+    console.error(
+      `[${BRIDGE_NAME}] Relay: giving up after ${RELAY_MAX_RECONNECT_ATTEMPTS} reconnect attempts`,
+    );
+    // The relay-owned session is unreachable for good — end it so polling
+    // agents see sessionActive:false instead of a permanently dead session.
+    if (liveSessionActive && liveSessionTransport === "relay") {
+      liveSessionActive = false;
+      pushLiveEvent("relay-connection-lost", {
+        hint: "Relay connection lost and reconnection failed; the remote session has ended. Use join_live_session to reconnect.",
+      });
+      try {
+        server.sendResourceListChanged();
+      } catch {
+        // Not all transports support notifications
+      }
+    }
+    return;
+  }
+  relayReconnectAttempts++;
+  const delay = RELAY_RECONNECT_INTERVAL_MS * Math.min(relayReconnectAttempts, 4);
+  relayReconnectTimer = setTimeout(() => {
+    relayReconnectTimer = undefined;
+    if (!relayIntentionalClose && relayRoomId) {
+      connectRelay().catch(() => {
+        // scheduleRelayReconnect is re-armed by the close handler
+      });
+    }
+  }, delay);
+}
+
 // Register live shadowing MCP resource
 server.resource(
   "live-session-status",
@@ -1400,6 +1687,10 @@ server.resource(
             session: liveSessionMeta,
             eventCount: liveEvents.length,
             pendingQuestions: pendingQuestions.length,
+            transport: activeConnection ? "local" : isRelayConnected() ? "relay" : "none",
+            remote: relayRoomId
+              ? { relayUrl, connected: isRelayConnected(), testerPresent: relayPeerPresent }
+              : null,
           },
           null,
           2,
@@ -1455,6 +1746,31 @@ server.registerTool(
   },
   async ({ since_seq, limit = WATCH_LIVE_DEFAULT_LIMIT }) => {
     if (!liveSessionActive && liveEvents.length === 0) {
+      // Joined a remote room but the tester hasn't started yet — this is the
+      // documented flow after join_live_session, not an error.
+      if (relayRoomId) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  sessionActive: false,
+                  waitingForTester: !relayPeerPresent,
+                  events: [],
+                  nextSeq: since_seq ?? 0,
+                  hasMore: false,
+                  note: relayPeerPresent
+                    ? "Tester is connected but has not started recording. Keep polling — a 'session-start' will arrive when they do."
+                    : "Joined the remote session room; waiting for the tester to connect. Keep polling — a 'tester-connected' event will appear when they join.",
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      }
       return toolError(
         "No active live shadowing session. Ensure the TraceGist extension has Live Shadowing enabled and is recording.",
       );
@@ -1592,19 +1908,17 @@ server.registerTool(
     }),
   },
   async ({ question }) => {
-    if (!liveSessionActive || !activeConnection) {
+    if (!liveSessionActive || !isExtensionLinked()) {
       return toolError("No active live shadowing session or extension not connected.");
     }
 
     const questionId = crypto.randomUUID();
     try {
-      activeConnection.send(
-        JSON.stringify({
-          type: "agent-question",
-          questionId,
-          question,
-        }),
-      );
+      await sendToExtension({
+        type: "agent-question",
+        questionId,
+        question,
+      });
     } catch (err) {
       return toolError(`Failed to send question to extension: ${err}`);
     }
@@ -1799,7 +2113,7 @@ server.registerTool(
     inputSchema: z.object({}),
   },
   async () => {
-    if (!liveSessionActive || !activeConnection) {
+    if (!liveSessionActive || !isExtensionLinked()) {
       return toolError("No active live shadowing session or extension not connected.");
     }
 
@@ -1812,12 +2126,17 @@ server.registerTool(
       }, 5000);
       screenshotWaiters.push({ resolve, reject, timeout });
     });
+    // If the send below fails, the abandoned promise's timeout would reject
+    // with nobody awaiting — an unhandled rejection that kills the process.
+    screenshotPromise.catch(() => {});
 
     try {
-      activeConnection.send(JSON.stringify({ type: "request-screenshot" }));
+      await sendToExtension({ type: "request-screenshot" });
     } catch (err) {
-      // Clean up waiter
-      screenshotWaiters.splice(0);
+      // Clean up waiters, including their timeout rejections
+      for (const waiter of screenshotWaiters.splice(0)) {
+        clearTimeout(waiter.timeout);
+      }
       return toolError(`Failed to request screenshot: ${err}`);
     }
 
@@ -1847,6 +2166,118 @@ server.registerTool(
   },
 );
 
+// Tool: join_live_session
+server.registerTool(
+  "join_live_session",
+  {
+    title: "Join Remote Live Session",
+    description:
+      "Join a Remote Live Session using the session code shown in the tester's TraceGist " +
+      "extension (format: TG-XXXXX-XXXXX-XXXXX). Connects to the relay and links this bridge " +
+      "to the tester's browser — all live tools (watch_live_session, ask_tester_question, " +
+      "get_tester_response, get_live_screenshot) then work exactly as they do locally. " +
+      "Traffic is end-to-end encrypted with a key derived from the code; the relay never " +
+      "sees session data.",
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
+    inputSchema: z.object({
+      code: z
+        .string()
+        .describe(
+          "The session code from the tester, e.g. TG-7K3MP-9XWQA-2BCDE (case-insensitive).",
+        ),
+    }),
+  },
+  async ({ code }) => {
+    if (liveShadowDisabled) {
+      return toolError("Live shadowing is disabled via TRACEGIST_DISABLE_LIVE.");
+    }
+
+    const normalized = normalizeSessionCode(code);
+    if (!normalized) {
+      return toolError(
+        "Invalid session code. Expected format: TG-XXXXX-XXXXX-XXXXX (letters/digits, no I/L/O/U).",
+      );
+    }
+
+    // Replace any previous remote session
+    if (relayWs || relayRoomId) {
+      disconnectRelay();
+    }
+
+    relayIntentionalClose = false;
+    relayUrl = process.env.TRACEGIST_RELAY_URL || DEFAULT_RELAY_URL;
+    relayRoomId = await deriveRoomId(normalized);
+    relaySessionKey = await deriveSessionKey(normalized);
+
+    try {
+      const { peerPresent } = await connectRelay();
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `Joined remote live session via ${relayUrl}.`,
+              peerPresent
+                ? "The tester is connected. Once they start recording you will see a session-start; poll watch_live_session for events."
+                : "Waiting for the tester to connect — ask them to start their remote session in the TraceGist extension. Poll watch_live_session; a 'tester-connected' event will appear when they join.",
+              "",
+              "All live tools now work over this connection: watch_live_session, ask_tester_question, get_tester_response, get_live_screenshot, get_live_session_summary.",
+              "Use leave_live_session to disconnect when done.",
+            ].join("\n"),
+          },
+        ],
+      };
+    } catch (err) {
+      disconnectRelay();
+      return toolError(
+        `Could not join the remote session: ${err instanceof Error ? err.message : err}. ` +
+          `Check the relay URL (${relayUrl}) and that the code is current.`,
+      );
+    }
+  },
+);
+
+// Tool: leave_live_session
+server.registerTool(
+  "leave_live_session",
+  {
+    title: "Leave Remote Live Session",
+    description:
+      "Disconnect from the current Remote Live Session (relay connection). " +
+      "Local live shadowing on this machine is unaffected.",
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    inputSchema: z.object({}),
+  },
+  async () => {
+    const wasConnected = relayRoomId !== null;
+    disconnectRelay();
+    if (liveSessionActive && liveSessionTransport === "relay") {
+      liveSessionActive = false;
+      liveSessionTransport = null;
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: wasConnected
+            ? "Left the remote live session."
+            : "No remote live session was active.",
+        },
+      ],
+    };
+  },
+);
+
 // Tool: get_live_session_summary
 server.registerTool(
   "get_live_session_summary",
@@ -1921,10 +2352,10 @@ console.error(
 // Inspector) and live shadowing is not needed for the current task.
 // Accepts the conventional boolean-ish values: 1/true/yes/on disable;
 // 0/false/no/off (and empty/unset) leave it enabled.
-if (envFlagEnabled(process.env.TRACEGIST_DISABLE_LIVE)) {
+if (liveShadowDisabled) {
   console.error(
     `[${BRIDGE_NAME}] Live shadow disabled via TRACEGIST_DISABLE_LIVE — ` +
-      "watch_live_session / ask_tester_question / get_tester_response / get_live_screenshot will be unavailable.",
+      "watch_live_session / ask_tester_question / get_tester_response / get_live_screenshot / join_live_session will be unavailable.",
   );
 } else {
   startLiveShadowServer();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracegist-mcp-bridge",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Local-first MCP bridge for reading and transcribing TraceGist package zips.",
   "type": "module",
   "bin": {