tracegist-mcp-bridge 0.4.0 → 1.0.0

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 All notable changes to `tracegist-mcp-bridge`.
 
+## 1.0.0
+
+> ⚠️ **Breaking Remote Live Session protocol change** (`FRAME_VERSION` → 3):
+> a 1.0.0 bridge will NOT interoperate with an older extension, and vice
+> versa. It ships **in lockstep** with the TraceGist extension v1.0.0 release —
+> update both together. Includes everything from the (unpublished) 0.5.0 below.
+
+Hardens the E2E encryption per the security audit (findings F1–F3) plus a
+per-connection ephemeral-key handshake:
+
+- **Per-connection handshake (fixes the CRITICAL reconnect/replay flaw).** Data
+  frames are now encrypted under a _connection key_, not the code key. On every
+  (re)connection the tester sends a fresh nonce (tagged with a monotonic
+  wall-clock epoch); the agent replies with its own nonce; both HKDF a connection
+  key from the code secret + both nonces + epoch and reset their counter. Because
+  each connection derives a distinct key: (a) a routine single-sided reconnect
+  re-handshakes and resynchronizes both sides (no more "post-reconnect frames
+  rejected as replays" brick), and (b) a malicious relay replaying a previous
+  connection's frames fails to decrypt under the new key. The agent is idempotent
+  per epoch and the tester retransmits until it gets a reply (with a bounded
+  timeout that ends the session), so a dropped handshake nonce recovers.
+- **Anti-replay / anti-reflection (F1).** Every data frame authenticates a
+  per-direction monotonic counter + sender role via AES-GCM AAD; a `ReplayGuard`
+  rejects non-increasing counters (in-connection replay/reorder), and the
+  per-connection key rejects cross-connection replay.
+- **Slow KDF (F2).** The code secret is PBKDF2-SHA256 (210k iterations); the
+  handshake and connection keys are HKDF'd from it. The relay-visible room ID
+  stays a fast, domain-separated hash.
+- **Chunk-count cap (F3).** `FrameChunkAssembler` rejects a part count above
+  `MAX_CHUNK_TOTAL` (1024).
+
+Not included (deferred): **forward secrecy (F5)** — the nonce-mixed key does NOT
+provide it (a compromised code + logged nonces still derives the key); true FS
+needs ephemeral ECDH. Also deferred: raising session-code entropy above 75 bits.
+
+## 0.5.0
+
+_Never published to npm — these changes first shipped as part of 1.0.0._
+
+Remote Live Session agent-experience improvements (all additive — no breaking
+tool-signature changes), from real agent-session feedback.
+
+- `watch_live_session` gains an optional `wait_seconds` long-poll parameter (max
+  30). The call now blocks until the next event arrives (or the session ends),
+  so agents react instantly instead of sleeping-and-re-polling every few seconds.
+- **Tester reconnect grace window.** A transient tester disconnect (service-worker
+  suspend, network blip) no longer ends the session immediately; the bridge waits
+  `TRACEGIST_PEER_GRACE_MS` (default 15s) for the extension to reconnect and
+  re-announce, preserving buffered events and in-flight replies. An explicit
+  `session-end` (recording stopped / consent revoked) still ends at once.
+- **Actionable, differentiated errors** for `ask_tester_question` /
+  `get_live_screenshot`: distinguishes "tester hasn't joined / left", "connected
+  but not recording yet", and "momentarily disconnected, retry" instead of one
+  opaque message.
+- **Silent-recording detection.** A voice answer that transcribes to whisper's
+  `[BLANK_AUDIO]` (or empty) is now surfaced as an explicit "no speech detected —
+  consider re-asking" signal rather than a bogus transcript.
+- Every live event now carries `tsEpoch` (bridge wall-clock at ingestion) — a
+  single uniformly-comparable absolute timestamp, since `ts` is source-relative
+  for tester events but epoch for bridge control events.
+- `ask_tester_question` message limit raised 200 → 500 chars and reframed to allow
+  statements/replies, not only questions.
+
 ## 0.4.0
 
 **Remote Live Sessions** — the live shadowing loop now works across machines.

package/bin/lib.mjs

@@ -212,6 +212,44 @@ export function audioFormatFromMime(mimeType, fallback = "webm") {
   return m ? m[1] : fallback;
 }
 
+/**
+ * Interpret a raw transcription string from Whisper/OpenRouter. whisper.cpp
+ * emits the literal "[BLANK_AUDIO]" marker (and models can return near-empty
+ * text) when a recording has no speech — a silent mic. Strips those markers and
+ * reports silence explicitly so the caller can tell the agent to re-ask instead
+ * of forwarding a bogus "answer".
+ * @param {string | null | undefined} rawText
+ * @returns {{ transcription: string } | { silent: true }}
+ */
+export function interpretTranscription(rawText) {
+  const cleaned = String(rawText || "")
+    .replace(/\[BLANK_?AUDIO\]/gi, "")
+    .trim();
+  if (!cleaned) return { silent: true };
+  return { transcription: cleaned };
+}
+
+/**
+ * Validate a Whisper language code before it is handed to nodejs-whisper.
+ *
+ * nodejs-whisper interpolates this value UNescaped into a shell command string
+ * (`-l <language>`) executed via shelljs.exec, so an unvalidated value is a
+ * command-injection sink. Whisper language codes are ISO 639-1/639-2 (2-3
+ * ASCII letters) or the literal "auto". Returns the trimmed code, or `undefined`
+ * for an empty/absent value. Throws on anything else.
+ */
+export function sanitizeWhisperLanguage(language) {
+  const trimmed = typeof language === "string" ? language.trim() : "";
+  if (!trimmed) return undefined;
+  if (!/^(auto|[a-z]{2,3})$/i.test(trimmed)) {
+    throw new Error(
+      `Invalid language code: ${JSON.stringify(language)}. ` +
+        `Expected an ISO 639 code (e.g. "en", "de", "ja") or "auto".`,
+    );
+  }
+  return trimmed;
+}
+
 /**
  * Parse a boolean-ish env-var value. Treats "0", "false", "no", "off"
  * (case-insensitive) and empty/undefined as falsy; everything else as truthy.

package/bin/live-crypto.mjs

@@ -18,14 +18,57 @@ 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;
+/**
+ * Key derivation: PBKDF2-SHA256, high iteration count, into an HKDF base key.
+ * v3 adds the per-connection ephemeral-key handshake (see HandshakeManager).
+ * MUST match lib/remote-session.ts.
+ */
+const PBKDF2_SALT = "tracegist-live-v2";
+const PBKDF2_ITERATIONS = 210_000;
+
+export const FRAME_VERSION = 3;
+
+const HKDF_HANDSHAKE_INFO = "tracegist-hs-key-v3";
+const HKDF_CONNECTION_INFO = "tracegist-conn-v3";
+const HKDF_SALT_CONST = "tracegist-live-v3";
+const HANDSHAKE_NONCE_BYTES = 16;
 
 /** AES-GCM IV length in bytes (protocol constant, see docs/live-protocol.md) */
 const GCM_IV_BYTES = 12;
 
+/**
+ * AAD bound into every DATA frame's AES-GCM tag: version + sender role +
+ * per-direction counter. Blocks reflection and replay/reorder. MUST match
+ * lib/remote-session.ts byte-for-byte.
+ * @param {"tester" | "agent"} senderRole
+ * @param {number} counter
+ */
+function frameAad(senderRole, counter) {
+  return new TextEncoder().encode(`tracegist-frame-v3|${senderRole}|${counter}`);
+}
+
+/** AAD for a handshake frame: binds protocol tag + sender role. */
+function handshakeAad(senderRole) {
+  return new TextEncoder().encode(`tracegist-hs-v3|${senderRole}`);
+}
+
+/**
+ * Rejects frames whose per-direction counter is not strictly increasing (anti
+ * replay/reorder). One instance per receive direction; reset per connection.
+ */
+export class ReplayGuard {
+  constructor() {
+    this.last = -1;
+  }
+  /** @param {number} counter */
+  accept(counter) {
+    if (!Number.isInteger(counter) || counter <= this.last) return false;
+    this.last = counter;
+    return true;
+  }
+}
+
 /**
  * Normalize a user-entered session code: trim, uppercase.
  * @param {string} raw
@@ -50,21 +93,44 @@ export async function deriveRoomId(code) {
 }
 
 /**
- * Derive the AES-256-GCM session key from a normalized session code.
+ * Derive the long-term "code secret" (HKDF base key) from the session code via
+ * PBKDF2. Everything else is HKDF'd from this. MUST match lib/remote-session.ts.
  * @param {string} code
  * @returns {Promise<CryptoKey>}
  */
-export async function deriveSessionKey(code) {
+export async function deriveCodeSecret(code) {
+  const encoder = new TextEncoder();
+  const pbkdf2Key = await subtle.importKey("raw", encoder.encode(code), "PBKDF2", false, [
+    "deriveBits",
+  ]);
+  const bits = await subtle.deriveBits(
+    {
+      name: "PBKDF2",
+      hash: "SHA-256",
+      salt: encoder.encode(PBKDF2_SALT),
+      iterations: PBKDF2_ITERATIONS,
+    },
+    pbkdf2Key,
+    256,
+  );
+  return subtle.importKey("raw", bits, "HKDF", false, ["deriveKey"]);
+}
+
+/**
+ * Derive the handshake key (encrypts the nonce-exchange frames).
+ * @param {CryptoKey} codeSecret
+ * @returns {Promise<CryptoKey>}
+ */
+export async function deriveHandshakeKey(codeSecret) {
   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),
+      salt: encoder.encode(HKDF_SALT_CONST),
+      info: encoder.encode(HKDF_HANDSHAKE_INFO),
     },
-    ikm,
+    codeSecret,
     { name: "AES-GCM", length: 256 },
     false,
     ["encrypt", "decrypt"],
@@ -72,42 +138,294 @@ export async function deriveSessionKey(code) {
 }
 
 /**
- * Encrypt a live-shadow message object into a frame payload.
+ * Derive the per-connection DATA key from the code secret + both handshake
+ * nonces + epoch (nonces concatenated tester-then-agent). MUST match
+ * lib/remote-session.ts.
+ * @param {CryptoKey} codeSecret
+ * @param {Uint8Array} testerNonce
+ * @param {Uint8Array} agentNonce
+ * @param {number} epoch
+ * @returns {Promise<CryptoKey>}
+ */
+export async function deriveConnectionKey(codeSecret, testerNonce, agentNonce, epoch) {
+  const salt = new Uint8Array(testerNonce.length + agentNonce.length);
+  salt.set(testerNonce, 0);
+  salt.set(agentNonce, testerNonce.length);
+  return subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt,
+      info: new TextEncoder().encode(`${HKDF_CONNECTION_INFO}|${epoch}`),
+    },
+    codeSecret,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+/** Generate a fresh handshake nonce (raw bytes). */
+export function generateHandshakeNonce() {
+  return webcrypto.getRandomValues(new Uint8Array(HANDSHAKE_NONCE_BYTES));
+}
+
+/**
+ * Encrypt a live-shadow message into a frame payload. `senderRole` is this
+ * endpoint's own role, `counter` its per-direction monotonic sequence; both are
+ * authenticated via AAD.
  * @param {CryptoKey} key
  * @param {object} message
- * @returns {Promise<{v: number, iv: string, ct: string}>}
+ * @param {"tester" | "agent"} senderRole
+ * @param {number} counter
+ * @returns {Promise<{v: number, iv: string, ct: string, c: number}>}
  */
-export async function encryptFrame(key, message) {
+export async function encryptFrame(key, message, senderRole, counter) {
+  // Counter must be a non-negative safe integer (see lib/remote-session.ts).
+  if (!Number.isSafeInteger(counter) || counter < 0) {
+    throw new Error("Frame counter exhausted — a new session/key is required");
+  }
   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);
+  const additionalData = frameAad(senderRole, counter);
+  const ct = await subtle.encrypt({ name: "AES-GCM", iv, additionalData }, key, plaintext);
   return {
     v: FRAME_VERSION,
     iv: Buffer.from(iv).toString("base64"),
     ct: Buffer.from(ct).toString("base64"),
+    c: counter,
   };
 }
 
 /**
- * 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.
+ * Decrypt a frame payload back into a message object. `senderRole` is the role
+ * the receiver EXPECTS (the peer's role); the AAD is rebuilt from it and the
+ * frame counter, so a reflected or counter-tampered frame fails to authenticate.
+ * Returns null for unknown versions, malformed payloads, or failed auth.
+ * Anti-replay is enforced separately by ReplayGuard.
  * @param {CryptoKey} key
- * @param {{v: number, iv: string, ct: string}} payload
+ * @param {{v: number, iv: string, ct: string, c: number}} payload
+ * @param {"tester" | "agent"} senderRole
  * @returns {Promise<object | null>}
  */
-export async function decryptFrame(key, payload) {
-  if (!payload || payload.v !== FRAME_VERSION) return null;
+export async function decryptFrame(key, payload, senderRole) {
+  // Counters are non-negative safe integers by construction; reject anything
+  // else before it reaches AAD building or the ReplayGuard.
+  if (!payload || payload.v !== FRAME_VERSION || !Number.isSafeInteger(payload.c) || payload.c < 0)
+    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);
+    const additionalData = frameAad(senderRole, payload.c);
+    const plaintext = await subtle.decrypt({ name: "AES-GCM", iv, additionalData }, key, ct);
     return JSON.parse(new TextDecoder().decode(plaintext));
   } catch {
     return null;
   }
 }
 
+/**
+ * Encrypt a handshake message under the handshake key (authenticated by role).
+ * @param {CryptoKey} handshakeKey
+ * @param {"tester" | "agent"} senderRole
+ * @param {{epoch: number, nonce: string, role: string}} message
+ * @returns {Promise<{hs: 1, iv: string, ct: string}>}
+ */
+export async function encryptHandshake(handshakeKey, senderRole, message) {
+  const iv = webcrypto.getRandomValues(new Uint8Array(GCM_IV_BYTES));
+  const plaintext = new TextEncoder().encode(JSON.stringify(message));
+  const additionalData = handshakeAad(senderRole);
+  const ct = await subtle.encrypt({ name: "AES-GCM", iv, additionalData }, handshakeKey, plaintext);
+  return {
+    hs: 1,
+    iv: Buffer.from(iv).toString("base64"),
+    ct: Buffer.from(ct).toString("base64"),
+  };
+}
+
+/**
+ * Decrypt a handshake frame. `senderRole` is the expected sender (peer) role.
+ * @param {CryptoKey} handshakeKey
+ * @param {"tester" | "agent"} senderRole
+ * @param {{hs: 1, iv: string, ct: string}} payload
+ * @returns {Promise<{epoch: number, nonce: string, role: string} | null>}
+ */
+export async function decryptHandshake(handshakeKey, senderRole, payload) {
+  if (!payload || payload.hs !== 1) return null;
+  try {
+    const iv = Buffer.from(payload.iv, "base64");
+    const ct = Buffer.from(payload.ct, "base64");
+    const additionalData = handshakeAad(senderRole);
+    const plaintext = await subtle.decrypt(
+      { name: "AES-GCM", iv, additionalData },
+      handshakeKey,
+      ct,
+    );
+    const msg = JSON.parse(new TextDecoder().decode(plaintext));
+    if (
+      !Number.isSafeInteger(msg.epoch) ||
+      msg.epoch < 0 ||
+      typeof msg.nonce !== "string" ||
+      (msg.role !== "tester" && msg.role !== "agent")
+    ) {
+      return null;
+    }
+    return msg;
+  } catch {
+    return null;
+  }
+}
+
+/** True if a relay payload is a handshake frame (vs a data frame). */
+export function isHandshakeFrame(payload) {
+  return typeof payload === "object" && payload !== null && payload.hs === 1;
+}
+
+/**
+ * Per-connection ephemeral-key handshake state machine — mirror of
+ * lib/remote-session.ts (see that file for the protocol description).
+ */
+export class HandshakeManager {
+  /**
+   * @param {"tester" | "agent"} role
+   * @param {CryptoKey} codeSecret
+   * @param {CryptoKey} handshakeKey
+   */
+  constructor(role, codeSecret, handshakeKey) {
+    this.role = role;
+    this.peerRole = role === "tester" ? "agent" : "tester";
+    this.codeSecret = codeSecret;
+    this.handshakeKey = handshakeKey;
+    this.connectionKey = null;
+    this.sendCounter = 0;
+    this.guard = new ReplayGuard();
+    this.pendingEpoch = -1;
+    this.pendingNonce = null;
+    this.lastEpoch = -1;
+    // Highest epoch the tester has established (idempotency guard; see
+    // lib/remote-session.ts).
+    this.establishedEpoch = -1;
+    this.respondedEpoch = -1;
+    this.respondedNonce = null;
+  }
+
+  /**
+   * @param {"tester" | "agent"} role
+   * @param {string} code
+   */
+  static async create(role, code) {
+    const codeSecret = await deriveCodeSecret(code);
+    const handshakeKey = await deriveHandshakeKey(codeSecret);
+    return new HandshakeManager(role, codeSecret, handshakeKey);
+  }
+
+  get ready() {
+    return this.connectionKey !== null;
+  }
+
+  /** @param {number} now */
+  nextEpoch(now) {
+    const e = Math.max(this.lastEpoch + 1, Math.floor(now));
+    this.lastEpoch = e;
+    return e;
+  }
+
+  /** TESTER: begin a fresh handshake. @param {number} now */
+  async startHandshake(now) {
+    if (this.role !== "tester") throw new Error("only the tester initiates the handshake");
+    this.connectionKey = null;
+    this.pendingEpoch = this.nextEpoch(now);
+    this.pendingNonce = generateHandshakeNonce();
+    return this.encryptPendingHandshake();
+  }
+
+  encryptPendingHandshake() {
+    return encryptHandshake(this.handshakeKey, "tester", {
+      epoch: this.pendingEpoch,
+      nonce: Buffer.from(this.pendingNonce).toString("base64"),
+      role: "tester",
+    });
+  }
+
+  /** TESTER: re-encrypt the in-flight handshake for retransmit (or null). */
+  async retransmit() {
+    if (this.role !== "tester" || this.connectionKey !== null || !this.pendingNonce) return null;
+    return this.encryptPendingHandshake();
+  }
+
+  /** Feed an incoming handshake frame. */
+  async onHandshakeFrame(payload) {
+    const msg = await decryptHandshake(this.handshakeKey, this.peerRole, payload);
+    if (!msg || msg.role !== this.peerRole) return { kind: "ignored" };
+
+    if (this.role === "agent") {
+      if (msg.epoch < this.respondedEpoch) return { kind: "ignored" };
+      if (msg.epoch === this.respondedEpoch && this.respondedNonce) {
+        const resend = await encryptHandshake(this.handshakeKey, "agent", {
+          epoch: msg.epoch,
+          nonce: Buffer.from(this.respondedNonce).toString("base64"),
+          role: "agent",
+        });
+        return { kind: "response", payload: resend, keyReady: this.connectionKey !== null };
+      }
+      const testerNonce = Buffer.from(msg.nonce, "base64");
+      // A wrong-size nonce would silently derive a mismatched key — fail loud.
+      if (testerNonce.length !== HANDSHAKE_NONCE_BYTES) return { kind: "ignored" };
+      const agentNonce = generateHandshakeNonce();
+      this.connectionKey = await deriveConnectionKey(
+        this.codeSecret,
+        testerNonce,
+        agentNonce,
+        msg.epoch,
+      );
+      this.sendCounter = 0;
+      this.guard = new ReplayGuard();
+      this.respondedEpoch = msg.epoch;
+      this.respondedNonce = agentNonce;
+      const response = await encryptHandshake(this.handshakeKey, "agent", {
+        epoch: msg.epoch,
+        nonce: Buffer.from(agentNonce).toString("base64"),
+        role: "agent",
+      });
+      return { kind: "response", payload: response, keyReady: true };
+    }
+
+    if (msg.epoch !== this.pendingEpoch || !this.pendingNonce) return { kind: "ignored" };
+    // Idempotent: a re-delivered/replayed response for an already-established
+    // epoch must not re-derive or reset (would rewind the counter + reopen the
+    // replay hole). A legitimate reconnect uses a strictly higher epoch.
+    if (this.establishedEpoch >= msg.epoch) return { kind: "ignored" };
+    const agentNonce = Buffer.from(msg.nonce, "base64");
+    // A wrong-size nonce would silently derive a mismatched key — fail loud.
+    if (agentNonce.length !== HANDSHAKE_NONCE_BYTES) return { kind: "ignored" };
+    this.connectionKey = await deriveConnectionKey(
+      this.codeSecret,
+      this.pendingNonce,
+      agentNonce,
+      msg.epoch,
+    );
+    this.sendCounter = 0;
+    this.guard = new ReplayGuard();
+    this.establishedEpoch = msg.epoch;
+    return { kind: "established" };
+  }
+
+  /** Encrypt a data message under the connection key. Throws if not ready. */
+  async encryptData(message) {
+    if (!this.connectionKey) throw new Error("handshake not complete");
+    return encryptFrame(this.connectionKey, message, this.role, this.sendCounter++);
+  }
+
+  /** Decrypt + replay-check a data frame. Null if not ready / invalid. */
+  async decryptData(payload) {
+    if (!this.connectionKey) return null;
+    const inner = await decryptFrame(this.connectionKey, payload, this.peerRole);
+    if (inner === null) return null;
+    if (!this.guard.accept(payload.c)) return null;
+    return inner;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Frame chunking — mirror of lib/remote-session.ts (see that file for the
 // size rationale). Hosted relays cap WebSocket messages (Cloudflare: 1 MiB);
@@ -119,6 +437,8 @@ export async function decryptFrame(key, payload) {
 export const FRAME_CHUNK_THRESHOLD_BYTES = 700_000;
 /** UTF-8 bytes per chunk. */
 export const FRAME_CHUNK_BYTES = 500_000;
+/** Hard cap on part count — bounds new Array(total) from a peer-supplied total. */
+export const MAX_CHUNK_TOTAL = 1024;
 
 /**
  * Split an oversized inner message into `frame-chunk` parts. Returns null
@@ -174,6 +494,7 @@ export class FrameChunkAssembler {
       !Number.isInteger(seq) ||
       !Number.isInteger(total) ||
       total < 1 ||
+      total > MAX_CHUNK_TOTAL ||
       seq < 0 ||
       seq >= total
     ) {

package/bin/tracegist-mcp-bridge.mjs

@@ -25,13 +25,14 @@ import {
   audioFormatFromMime,
   isAllowedLiveShadowOrigin,
   envFlagEnabled,
+  interpretTranscription,
+  sanitizeWhisperLanguage,
 } from "./lib.mjs";
 import {
   normalizeSessionCode,
   deriveRoomId,
-  deriveSessionKey,
-  encryptFrame,
-  decryptFrame,
+  HandshakeManager,
+  isHandshakeFrame,
   chunkInnerMessage,
   FrameChunkAssembler,
 } from "./live-crypto.mjs";
@@ -175,7 +176,9 @@ const WHISPER_CONCURRENCY = 2;
  * accepts the file directly without any ffmpeg hop.
  */
 async function transcribeWithLocalWhisper(audioPath, model, language) {
-  const trimmedLang = language && language.trim() ? language.trim() : undefined;
+  // Reject anything that is not a plain language code before it reaches the
+  // shell — nodejs-whisper interpolates this value unescaped into `-l <lang>`.
+  const trimmedLang = sanitizeWhisperLanguage(language);
   const transcript = await nodewhisper(audioPath, {
     modelName: model,
     autoDownloadModelName: model,
@@ -1095,6 +1098,20 @@ const RELAY_MAX_RECONNECT_ATTEMPTS = 10;
 const PENDING_QUESTIONS_MAX = 50;
 const WATCH_LIVE_DEFAULT_LIMIT = 100;
 const WATCH_LIVE_MAX_LIMIT = 500;
+/** Max seconds watch_live_session will block waiting for a new event (long-poll). */
+const WATCH_LIVE_MAX_WAIT_SECONDS = 30;
+/**
+ * How long the bridge keeps a relay session "active" after the tester's peer
+ * drops, giving the tester's extension time to reconnect (it retries for ~30s)
+ * before the session is declared ended. Covers transient service-worker
+ * suspensions / network blips so an in-flight agent reply is not lost to a
+ * momentary disconnect. An explicit `session-end` still ends immediately.
+ * Override via TRACEGIST_PEER_GRACE_MS (0 disables the grace window).
+ */
+const PEER_ABSENT_GRACE_MS = (() => {
+  const raw = Number(process.env.TRACEGIST_PEER_GRACE_MS);
+  return Number.isFinite(raw) && raw >= 0 ? raw : 15000;
+})();
 
 /** @type {Array<{seq: number, ts: number, eventType: string, data: object}>} */
 const liveEvents = [];
@@ -1122,6 +1139,20 @@ const liveInteractions = [];
 /** @type {Array<{resolve: Function, reject: Function, timeout: ReturnType<typeof setTimeout>}>} */
 const screenshotWaiters = [];
 
+/**
+ * Resolvers for watch_live_session long-poll: each waits for the next event to
+ * be pushed (or a timeout). Notified by pushLiveEvent.
+ * @type {Array<() => void>}
+ */
+const eventWaiters = [];
+
+/**
+ * Timer that ends the relay session after the tester's peer has been absent for
+ * PEER_ABSENT_GRACE_MS. Cleared if the tester reconnects. See peer-left handler.
+ * @type {ReturnType<typeof setTimeout> | null}
+ */
+let peerAbsentGraceTimer = null;
+
 /**
  * Transcribe a voice data URL via the shared transcribeAudio path.
  * @param {string} voiceBlobDataUrl - data:audio/...;base64,... URL
@@ -1133,7 +1164,17 @@ async function transcribeLiveVoice(voiceBlobDataUrl) {
   const mimeType = match[1];
   const audioBuffer = Buffer.from(match[2], "base64");
   const result = await transcribeAudio({ audioBuffer, mimeType });
-  return result.transcription ? { transcription: result.transcription } : { error: result.error };
+  if (!result.transcription) return { error: result.error };
+  // Detect silent recordings (whisper's "[BLANK_AUDIO]" / empty) and surface them
+  // as an explicit signal instead of handing the agent a bogus "answer".
+  const interpreted = interpretTranscription(result.transcription);
+  if (interpreted.silent) {
+    return {
+      error: "No speech detected — the tester's recording was silent. Consider re-asking.",
+      silent: true,
+    };
+  }
+  return { transcription: interpreted.transcription };
 }
 
 /** Push a live event into the ring buffer with auto-incrementing seq.
@@ -1144,11 +1185,62 @@ 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, eventType, data });
+  // `ts` is the source event time: session-relative ms for extension/tester
+  // events, epoch ms for bridge-originated control events — so it is NOT
+  // consistent across sources. `tsEpoch` is always the bridge's wall-clock at
+  // ingestion, giving agents one uniformly-comparable absolute timestamp.
+  liveEvents.push({ seq: liveEventSeq, ts, tsEpoch: Date.now(), 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);
   }
+  // Wake any long-poll waiters now that a new event is available.
+  for (const wake of eventWaiters.splice(0)) wake();
+}
+
+/** Cancel a pending "tester absent" grace timer (tester reconnected or session ended). */
+function clearPeerAbsentGrace() {
+  if (peerAbsentGraceTimer !== null) {
+    clearTimeout(peerAbsentGraceTimer);
+    peerAbsentGraceTimer = null;
+  }
+}
+
+/**
+ * Why a tester-directed action (ask_tester_question / get_live_screenshot) can't
+ * run right now, or null if it can. Distinguishes the states that previously all
+ * returned one opaque error, so the agent can tell the tester what to do.
+ */
+function liveSessionUnavailableReason() {
+  if (liveSessionActive && isExtensionLinked()) return null;
+  if (relayRoomId) {
+    if (peerAbsentGraceTimer !== null || (relayPeerPresent === false && liveSessionActive)) {
+      return "The tester momentarily disconnected and may be reconnecting. Retry in a few seconds.";
+    }
+    if (!relayPeerPresent) {
+      return "The tester has not joined the session (or has left). Ask them to start their remote session in the TraceGist extension.";
+    }
+    if (!liveSessionActive) {
+      return "The tester is connected but hasn't started recording yet. Ask them to press record; keep polling watch_live_session for the 'session-start' event.";
+    }
+  }
+  return "No active live shadowing session, or the extension is not connected. Ensure the tester is recording with Live Shadowing / a remote session enabled.";
+}
+
+/** End the active relay session and notify polling agents. Idempotent. */
+function endRelaySession(reason) {
+  clearPeerAbsentGrace();
+  // Only end a RELAY-owned session. A local session that started (e.g. during the
+  // grace window after a relay drop) must not be torn down by relay teardown.
+  if (!liveSessionActive || liveSessionTransport !== "relay") return;
+  liveSessionActive = false;
+  console.error(`[${BRIDGE_NAME}] Relay: session ended (${reason})`);
+  pushLiveEvent("session-ended", { reason });
+  try {
+    server.sendResourceListChanged();
+  } catch {
+    // Not all transports support notifications
+  }
 }
 
 function startLiveShadowServer() {
@@ -1238,6 +1330,9 @@ function startLiveShadowServer() {
 function handleExtensionMessage(msg, source = "local") {
   switch (msg.type) {
     case "session-start": {
+      // A session is (re)starting — cancel any pending grace-end so it can't
+      // fire against this fresh session.
+      clearPeerAbsentGrace();
       // 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.
@@ -1402,6 +1497,8 @@ function handleExtensionMessage(msg, source = "local") {
       // 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;
+      // Explicit end (recording stopped / consent revoked) — end now, no grace.
+      clearPeerAbsentGrace();
       liveSessionActive = false;
       console.error(`[${BRIDGE_NAME}] Live shadow: session ended`);
       try {
@@ -1424,8 +1521,16 @@ function handleExtensionMessage(msg, source = "local") {
 
 /** @type {WebSocket | null} */
 let relayWs = null;
-/** @type {CryptoKey | null} */
-let relaySessionKey = null;
+/**
+ * Per-connection ephemeral-key handshake (agent side). Owns the connection key,
+ * send counter, and replay guard. Created on join_live_session.
+ * @type {HandshakeManager | null}
+ */
+let relayHandshake = null;
+/** Cap on messages buffered while the relay handshake is in flight (drop-oldest). */
+const RELAY_PENDING_SENDS_MAX = 2000;
+/** Inner messages awaiting the handshake before they can be encrypted + sent. */
+let relayPendingSends = [];
 let relayRoomId = null;
 let relayUrl = null;
 let relayPeerPresent = false;
@@ -1459,20 +1564,31 @@ let relaySendChain = Promise.resolve();
  * @param {object} msg
  */
 async function sendToExtension(msg) {
-  const canRelay = isRelayConnected() && relaySessionKey !== null;
+  const canRelay = isRelayConnected() && relayHandshake !== 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 parts = chunkInnerMessage(msg) ?? [msg];
+    // If the handshake hasn't completed yet, buffer the parts; they are flushed
+    // once the connection key is established. Bounded (drop-oldest) so a relay
+    // that never delivers the tester handshake can't grow this unboundedly —
+    // matches the extension's buffer cap (the agent has no handshake timeout).
+    if (!relayHandshake.ready) {
+      for (const part of parts) {
+        if (relayPendingSends.length >= RELAY_PENDING_SENDS_MAX) relayPendingSends.shift();
+        relayPendingSends.push(part);
+      }
+      return;
+    }
     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) {
+      if (!isRelayConnected() || relayHandshake === null || !relayHandshake.ready) {
         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);
+        const payload = await relayHandshake.encryptData(part);
         relayWs.send(JSON.stringify({ type: "frame", payload }));
       }
     });
@@ -1487,8 +1603,26 @@ async function sendToExtension(msg) {
   throw new Error("Extension not connected (no local or relay transport)");
 }
 
+/** Encrypt + send inner messages buffered while the relay handshake was in flight. */
+function flushRelayPendingSends() {
+  const hs = relayHandshake;
+  if (!hs || !hs.ready || relayPendingSends.length === 0) return;
+  const queued = relayPendingSends;
+  relayPendingSends = [];
+  const send = relaySendChain.then(async () => {
+    for (const part of queued) {
+      if (!isRelayConnected() || relayHandshake !== hs || !hs.ready) return;
+      relayWs.send(JSON.stringify({ type: "frame", payload: await hs.encryptData(part) }));
+    }
+  });
+  relaySendChain = send.catch(() => {});
+}
+
 function disconnectRelay() {
   relayIntentionalClose = true;
+  // Cancel any pending grace timer — otherwise it can fire after a new session
+  // (e.g. a rejoin with a different code) has taken over and end it spuriously.
+  clearPeerAbsentGrace();
   if (relayReconnectTimer) {
     clearTimeout(relayReconnectTimer);
     relayReconnectTimer = undefined;
@@ -1501,7 +1635,8 @@ function disconnectRelay() {
     }
   }
   relayWs = null;
-  relaySessionKey = null;
+  relayHandshake = null;
+  relayPendingSends = [];
   relayRoomId = null;
   relayPeerPresent = false;
   relayReconnectAttempts = 0;
@@ -1546,7 +1681,8 @@ function connectRelay() {
     // 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.
+    // Per-connection: a new socket can never continue a previous reassembly. The
+    // handshake manager owns the connection key + counter + replay guard.
     const chunkAssembler = new FrameChunkAssembler();
 
     ws.on("message", (raw) => {
@@ -1570,6 +1706,8 @@ function connectRelay() {
 
         case "peer-joined":
           relayPeerPresent = true;
+          // Tester is back within the grace window — cancel the pending end.
+          clearPeerAbsentGrace();
           pushLiveEvent("tester-connected", {
             hint: "The tester's extension joined the remote session.",
           });
@@ -1577,17 +1715,28 @@ function connectRelay() {
 
         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
+          // Do NOT end the session immediately: the tester's extension retries
+          // for ~30s and re-announces on reconnect, so a transient drop (service
+          // worker suspend, network blip) should not kill the session and lose an
+          // in-flight reply. Start a grace timer; an explicit `session-end` frame
+          // still ends the session at once via handleExtensionMessage.
+          if (liveSessionActive && peerAbsentGraceTimer === null) {
+            if (PEER_ABSENT_GRACE_MS === 0) {
+              endRelaySession("tester disconnected");
+            } else {
+              peerAbsentGraceTimer = setTimeout(() => {
+                peerAbsentGraceTimer = null;
+                if (!relayPeerPresent) endRelaySession("tester did not reconnect");
+              }, PEER_ABSENT_GRACE_MS);
+              if (typeof peerAbsentGraceTimer.unref === "function") peerAbsentGraceTimer.unref();
             }
           }
           pushLiveEvent("tester-disconnected", {
-            hint: "The tester's extension left the remote session.",
+            reconnectGraceMs: PEER_ABSENT_GRACE_MS,
+            hint:
+              PEER_ABSENT_GRACE_MS > 0
+                ? `The tester's extension dropped. Waiting up to ${Math.round(PEER_ABSENT_GRACE_MS / 1000)}s for it to reconnect before ending the session — keep polling.`
+                : "The tester's extension left the remote session.",
           });
           break;
 
@@ -1595,9 +1744,23 @@ function connectRelay() {
           const payload = msg.payload;
           frameChain = frameChain
             .then(async () => {
-              const inner = await decryptFrame(relaySessionKey, payload);
+              const hs = relayHandshake;
+              if (!hs || relayWs !== ws) return;
+              if (isHandshakeFrame(payload)) {
+                // The tester initiated (or retransmitted) a handshake. Reply with
+                // our nonce and, once the key is ready, flush any buffered sends.
+                const result = await hs.onHandshakeFrame(payload);
+                if (result.kind === "response") {
+                  relayWs.send(JSON.stringify({ type: "frame", payload: result.payload }));
+                  if (result.keyReady) flushRelayPendingSends();
+                }
+                return;
+              }
+              // Data frame from the tester: decrypt + replay-check under the
+              // connection key (rejects reflected/replayed/previous-connection).
+              const inner = await hs.decryptData(payload);
               if (inner === null) {
-                console.error(`[${BRIDGE_NAME}] Relay: dropped undecryptable frame`);
+                console.error(`[${BRIDGE_NAME}] Relay: dropped undecryptable/replayed frame`);
                 return;
               }
               // Chunk parts return null until the final part completes.
@@ -1648,6 +1811,7 @@ function scheduleRelayReconnect() {
     // 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") {
+      clearPeerAbsentGrace();
       liveSessionActive = false;
       pushLiveEvent("relay-connection-lost", {
         hint: "Relay connection lost and reconnection failed; the remote session has ended. Use join_live_session to reconnect.",
@@ -1709,8 +1873,10 @@ server.registerTool(
     description:
       "Watch a live TraceGist shadowing session in real-time. Returns buffered events since the given sequence number.\n\n" +
       "IMPORTANT POLLING BEHAVIOR:\n" +
-      "- You MUST keep calling this tool every 2-4 seconds in a loop until sessionActive becomes false.\n" +
-      "- Do NOT stop polling just because there are no new events — the tester is still active.\n" +
+      "- PREFER long-polling: pass `wait_seconds` (e.g. 25) with `since_seq = nextSeq`. The call blocks until a\n" +
+      "  new event arrives or the session ends, so you react instantly without a fixed sleep-and-poll loop.\n" +
+      "- Keep calling in a loop until sessionActive becomes false; with wait_seconds you can loop back immediately.\n" +
+      "- Do NOT stop just because a call returned no new events — the tester is still active.\n" +
       "- When you see 'voice-transcription' events, the tester recorded a voice marker — read the transcription and react to it.\n" +
       "- When you see 'question-response-received' events, use get_tester_response to retrieve the full answer with images.\n" +
       "- When you see 'question-response-transcribed' events, the tester's voice response has been transcribed — read it for context.\n" +
@@ -1742,9 +1908,47 @@ server.registerTool(
           `Maximum events to return per call (default: ${WATCH_LIVE_DEFAULT_LIMIT}, max: ${WATCH_LIVE_MAX_LIMIT}). ` +
             "Use the returned `nextSeq` as `since_seq` on the next call when `hasMore` is true.",
         ),
+      wait_seconds: z
+        .number()
+        .min(0)
+        .max(WATCH_LIVE_MAX_WAIT_SECONDS)
+        .optional()
+        .describe(
+          `Long-poll: block up to this many seconds (max ${WATCH_LIVE_MAX_WAIT_SECONDS}) waiting for a new ` +
+            "event after `since_seq`, returning immediately when one arrives (or the session ends). " +
+            "STRONGLY PREFERRED over fixed-interval polling — pass e.g. 25 with `since_seq = nextSeq` to " +
+            "react the instant the tester acts, instead of sleeping and re-polling. Omit or 0 to return at once.",
+        ),
     }),
   },
-  async ({ since_seq, limit = WATCH_LIVE_DEFAULT_LIMIT }) => {
+  async ({ since_seq, limit = WATCH_LIVE_DEFAULT_LIMIT, wait_seconds = 0 }) => {
+    // Long-poll: block until there's a new event after since_seq, the session
+    // ends, or the wait budget elapses. Only waits while a session is live or a
+    // relay room is joined — otherwise falls straight through to the error below.
+    const waitMs = Math.min(Math.max(wait_seconds, 0), WATCH_LIVE_MAX_WAIT_SECONDS) * 1000;
+    if (waitMs > 0) {
+      const deadline = Date.now() + waitMs;
+      while ((liveSessionActive || relayRoomId) && Date.now() < deadline) {
+        const hasNew =
+          since_seq != null ? liveEvents.some((e) => e.seq > since_seq) : liveEvents.length > 0;
+        if (hasNew) break;
+        // Wait for the next pushLiveEvent, capped at 1s slices so we re-check
+        // session/deadline state (e.g. the session ending) even without an event.
+        await new Promise((resolve) => {
+          let settled = false;
+          const wake = () => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            const i = eventWaiters.indexOf(wake);
+            if (i >= 0) eventWaiters.splice(i, 1);
+            resolve();
+          };
+          const timer = setTimeout(wake, Math.min(deadline - Date.now(), 1000));
+          eventWaiters.push(wake);
+        });
+      }
+    }
     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.
@@ -1822,14 +2026,15 @@ server.registerTool(
 
     if (liveSessionActive) {
       responseData.pollingGuidance =
-        "KEEP POLLING every 2-4 seconds. Do NOT stop — the tester is still active. " +
+        "KEEP WATCHING — the tester is still active. Prefer calling again with wait_seconds (e.g. 25) and " +
+        "since_seq = nextSeq to block until the next event instead of fixed-interval polling. " +
         "Watch for 'voice-transcription' events (tester voice markers) and 'question-response-received' events. " +
         "React to voice markers by acknowledging them or asking follow-up questions.";
       responseData.availableActions = [
         {
           tool: "ask_tester_question",
           description:
-            "Ask the tester a short question (max 200 chars). They respond with voice + highlights.",
+            "Send the tester a question or short message (max 500 chars). They respond with voice + highlights.",
         },
         {
           tool: "get_live_screenshot",
@@ -1900,17 +2105,17 @@ server.registerTool(
     inputSchema: z.object({
       question: z
         .string()
-        .max(200)
+        .max(500)
         .describe(
-          "Short, concise question for the tester (max 200 chars). " +
-            "Example: 'Can you click the Save button again?' or 'Does the error appear with a different email?'",
+          "Message for the tester — a question OR a statement/reply (max 500 chars). " +
+            "Examples: 'Can you click Save again?' · 'Thanks — I see the 500 now, fixing it.' · " +
+            "'In my opinion the layout bug is the CSS grid gap.'",
         ),
     }),
   },
   async ({ question }) => {
-    if (!liveSessionActive || !isExtensionLinked()) {
-      return toolError("No active live shadowing session or extension not connected.");
-    }
+    const unavailable = liveSessionUnavailableReason();
+    if (unavailable) return toolError(unavailable);
 
     const questionId = crypto.randomUUID();
     try {
@@ -2113,9 +2318,8 @@ server.registerTool(
     inputSchema: z.object({}),
   },
   async () => {
-    if (!liveSessionActive || !isExtensionLinked()) {
-      return toolError("No active live shadowing session or extension not connected.");
-    }
+    const unavailable = liveSessionUnavailableReason();
+    if (unavailable) return toolError(unavailable);
 
     // Request screenshot from extension and wait for response
     const screenshotPromise = new Promise((resolve, reject) => {
@@ -2204,15 +2408,24 @@ server.registerTool(
       );
     }
 
-    // Replace any previous remote session
+    // Replace any previous remote session. disconnectRelay() clears the grace
+    // timer; also reset the owning session state (as leave_live_session does) so
+    // a still-"active" session held open by the grace window doesn't carry its
+    // stale sessionId/meta into the new room until a session-start corrects it.
     if (relayWs || relayRoomId) {
       disconnectRelay();
+      if (liveSessionActive && liveSessionTransport === "relay") {
+        liveSessionActive = false;
+        liveSessionTransport = null;
+        liveSessionMeta = null;
+      }
     }
 
     relayIntentionalClose = false;
     relayUrl = process.env.TRACEGIST_RELAY_URL || DEFAULT_RELAY_URL;
     relayRoomId = await deriveRoomId(normalized);
-    relaySessionKey = await deriveSessionKey(normalized);
+    relayPendingSends = [];
+    relayHandshake = await HandshakeManager.create("agent", normalized);
 
     try {
       const { peerPresent } = await connectRelay();

package/package.json

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