ofw-mcp 2.0.19 → 2.2.0

package/dist/bundle.js

@@ -3112,6 +3112,9 @@ var require_utils = __commonJS({
     "use strict";
     var isUUID = RegExp.prototype.test.bind(/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iu);
     var isIPv4 = RegExp.prototype.test.bind(/^(?:(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)$/u);
+    var isHexPair = RegExp.prototype.test.bind(/^[\da-f]{2}$/iu);
+    var isUnreserved = RegExp.prototype.test.bind(/^[\da-z\-._~]$/iu);
+    var isPathCharacter = RegExp.prototype.test.bind(/^[\da-z\-._~!$&'()*+,;=:@/]$/iu);
     function stringArrayToHexStripped(input) {
       let acc = "";
       let code = 0;
@@ -3304,27 +3307,77 @@ var require_utils = __commonJS({
       }
       return output.join("");
     }
-    function normalizeComponentEncoding(component, esc2) {
-      const func = esc2 !== true ? escape : unescape;
-      if (component.scheme !== void 0) {
-        component.scheme = func(component.scheme);
-      }
-      if (component.userinfo !== void 0) {
-        component.userinfo = func(component.userinfo);
-      }
-      if (component.host !== void 0) {
-        component.host = func(component.host);
+    var HOST_DELIMS = { "@": "%40", "/": "%2F", "?": "%3F", "#": "%23", ":": "%3A" };
+    var HOST_DELIM_RE = /[@/?#:]/g;
+    var HOST_DELIM_NO_COLON_RE = /[@/?#]/g;
+    function reescapeHostDelimiters(host, isIP) {
+      const re = isIP ? HOST_DELIM_NO_COLON_RE : HOST_DELIM_RE;
+      re.lastIndex = 0;
+      return host.replace(re, (ch) => HOST_DELIMS[ch]);
+    }
+    function normalizePercentEncoding(input, decodeUnreserved = false) {
+      if (input.indexOf("%") === -1) {
+        return input;
       }
-      if (component.path !== void 0) {
-        component.path = func(component.path);
+      let output = "";
+      for (let i = 0; i < input.length; i++) {
+        if (input[i] === "%" && i + 2 < input.length) {
+          const hex3 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex3)) {
+            const normalizedHex = hex3.toUpperCase();
+            const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
+            if (decodeUnreserved && isUnreserved(decoded)) {
+              output += decoded;
+            } else {
+              output += "%" + normalizedHex;
+            }
+            i += 2;
+            continue;
+          }
+        }
+        output += input[i];
       }
-      if (component.query !== void 0) {
-        component.query = func(component.query);
+      return output;
+    }
+    function normalizePathEncoding(input) {
+      let output = "";
+      for (let i = 0; i < input.length; i++) {
+        if (input[i] === "%" && i + 2 < input.length) {
+          const hex3 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex3)) {
+            const normalizedHex = hex3.toUpperCase();
+            const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
+            if (decoded !== "." && isUnreserved(decoded)) {
+              output += decoded;
+            } else {
+              output += "%" + normalizedHex;
+            }
+            i += 2;
+            continue;
+          }
+        }
+        if (isPathCharacter(input[i])) {
+          output += input[i];
+        } else {
+          output += escape(input[i]);
+        }
       }
-      if (component.fragment !== void 0) {
-        component.fragment = func(component.fragment);
+      return output;
+    }
+    function escapePreservingEscapes(input) {
+      let output = "";
+      for (let i = 0; i < input.length; i++) {
+        if (input[i] === "%" && i + 2 < input.length) {
+          const hex3 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex3)) {
+            output += "%" + hex3.toUpperCase();
+            i += 2;
+            continue;
+          }
+        }
+        output += escape(input[i]);
       }
-      return component;
+      return output;
     }
     function recomposeAuthority(component) {
       const uriTokens = [];
@@ -3339,7 +3392,7 @@ var require_utils = __commonJS({
           if (ipV6res.isIPV6 === true) {
             host = `[${ipV6res.escapedHost}]`;
           } else {
-            host = component.host;
+            host = reescapeHostDelimiters(host, false);
           }
         }
         uriTokens.push(host);
@@ -3353,7 +3406,10 @@ var require_utils = __commonJS({
     module.exports = {
       nonSimpleDomain,
       recomposeAuthority,
-      normalizeComponentEncoding,
+      reescapeHostDelimiters,
+      normalizePercentEncoding,
+      normalizePathEncoding,
+      escapePreservingEscapes,
       removeDotSegments,
       isIPv4,
       isUUID,
@@ -3577,12 +3633,12 @@ var require_schemes = __commonJS({
 var require_fast_uri = __commonJS({
   "node_modules/fast-uri/index.js"(exports, module) {
     "use strict";
-    var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizeComponentEncoding, isIPv4, nonSimpleDomain } = require_utils();
+    var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, escapePreservingEscapes, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
     var { SCHEMES, getSchemeHandler } = require_schemes();
     function normalize(uri, options) {
       if (typeof uri === "string") {
         uri = /** @type {T} */
-        serialize(parse3(uri, options), options);
+        normalizeString(uri, options);
       } else if (typeof uri === "object") {
         uri = /** @type {T} */
         parse3(serialize(uri, options), options);
@@ -3649,19 +3705,9 @@ var require_fast_uri = __commonJS({
       return target;
     }
     function equal(uriA, uriB, options) {
-      if (typeof uriA === "string") {
-        uriA = unescape(uriA);
-        uriA = serialize(normalizeComponentEncoding(parse3(uriA, options), true), { ...options, skipEscape: true });
-      } else if (typeof uriA === "object") {
-        uriA = serialize(normalizeComponentEncoding(uriA, true), { ...options, skipEscape: true });
-      }
-      if (typeof uriB === "string") {
-        uriB = unescape(uriB);
-        uriB = serialize(normalizeComponentEncoding(parse3(uriB, options), true), { ...options, skipEscape: true });
-      } else if (typeof uriB === "object") {
-        uriB = serialize(normalizeComponentEncoding(uriB, true), { ...options, skipEscape: true });
-      }
-      return uriA.toLowerCase() === uriB.toLowerCase();
+      const normalizedA = normalizeComparableURI(uriA, options);
+      const normalizedB = normalizeComparableURI(uriB, options);
+      return normalizedA !== void 0 && normalizedB !== void 0 && normalizedA.toLowerCase() === normalizedB.toLowerCase();
     }
     function serialize(cmpts, opts) {
       const component = {
@@ -3686,12 +3732,12 @@ var require_fast_uri = __commonJS({
       if (schemeHandler && schemeHandler.serialize) schemeHandler.serialize(component, options);
       if (component.path !== void 0) {
         if (!options.skipEscape) {
-          component.path = escape(component.path);
+          component.path = escapePreservingEscapes(component.path);
           if (component.scheme !== void 0) {
             component.path = component.path.split("%3A").join(":");
           }
         } else {
-          component.path = unescape(component.path);
+          component.path = normalizePercentEncoding(component.path);
         }
       }
       if (options.reference !== "suffix" && component.scheme) {
@@ -3726,7 +3772,16 @@ var require_fast_uri = __commonJS({
       return uriTokens.join("");
     }
     var URI_PARSE = /^(?:([^#/:?]+):)?(?:\/\/((?:([^#/?@]*)@)?(\[[^#/?\]]+\]|[^#/:?]*)(?::(\d*))?))?([^#?]*)(?:\?([^#]*))?(?:#((?:.|[\n\r])*))?/u;
-    function parse3(uri, opts) {
+    function getParseError(parsed, matches) {
+      if (matches[2] !== void 0 && parsed.path && parsed.path[0] !== "/") {
+        return 'URI path must start with "/" when authority is present.';
+      }
+      if (typeof parsed.port === "number" && (parsed.port < 0 || parsed.port > 65535)) {
+        return "URI port is malformed.";
+      }
+      return void 0;
+    }
+    function parseWithStatus(uri, opts) {
       const options = Object.assign({}, opts);
       const parsed = {
         scheme: void 0,
@@ -3737,6 +3792,7 @@ var require_fast_uri = __commonJS({
         query: void 0,
         fragment: void 0
       };
+      let malformedAuthorityOrPort = false;
       let isIP = false;
       if (options.reference === "suffix") {
         if (options.scheme) {
@@ -3757,6 +3813,11 @@ var require_fast_uri = __commonJS({
         if (isNaN(parsed.port)) {
           parsed.port = matches[5];
         }
+        const parseError = getParseError(parsed, matches);
+        if (parseError !== void 0) {
+          parsed.error = parsed.error || parseError;
+          malformedAuthorityOrPort = true;
+        }
         if (parsed.host) {
           const ipv4result = isIPv4(parsed.host);
           if (ipv4result === false) {
@@ -3795,14 +3856,18 @@ var require_fast_uri = __commonJS({
               parsed.scheme = unescape(parsed.scheme);
             }
             if (parsed.host !== void 0) {
-              parsed.host = unescape(parsed.host);
+              parsed.host = reescapeHostDelimiters(unescape(parsed.host), isIP);
             }
           }
           if (parsed.path) {
-            parsed.path = escape(unescape(parsed.path));
+            parsed.path = normalizePathEncoding(parsed.path);
           }
           if (parsed.fragment) {
-            parsed.fragment = encodeURI(decodeURIComponent(parsed.fragment));
+            try {
+              parsed.fragment = encodeURI(decodeURIComponent(parsed.fragment));
+            } catch {
+              parsed.error = parsed.error || "URI malformed";
+            }
           }
         }
         if (schemeHandler && schemeHandler.parse) {
@@ -3811,7 +3876,29 @@ var require_fast_uri = __commonJS({
       } else {
         parsed.error = parsed.error || "URI can not be parsed.";
       }
-      return parsed;
+      return { parsed, malformedAuthorityOrPort };
+    }
+    function parse3(uri, opts) {
+      return parseWithStatus(uri, opts).parsed;
+    }
+    function normalizeString(uri, opts) {
+      return normalizeStringWithStatus(uri, opts).normalized;
+    }
+    function normalizeStringWithStatus(uri, opts) {
+      const { parsed, malformedAuthorityOrPort } = parseWithStatus(uri, opts);
+      return {
+        normalized: malformedAuthorityOrPort ? uri : serialize(parsed, opts),
+        malformedAuthorityOrPort
+      };
+    }
+    function normalizeComparableURI(uri, opts) {
+      if (typeof uri === "string") {
+        const { normalized, malformedAuthorityOrPort } = normalizeStringWithStatus(uri, opts);
+        return malformedAuthorityOrPort ? void 0 : normalized;
+      }
+      if (typeof uri === "object") {
+        return serialize(uri, opts);
+      }
     }
     var fastUri = {
       SCHEMES,
@@ -34856,6 +34943,8 @@ function validateFrame(raw) {
     return validateReady(raw);
   if (t === "frame")
     return validateEncrypted(raw);
+  if (t === "pair-pending")
+    return validatePairPending(raw);
   throw new ProtocolError(`unknown frame type: ${String(t)}`);
 }
 function validateHello(raw) {
@@ -34957,6 +35046,17 @@ function validateEncrypted(raw) {
   assertBase64(raw.ciphertext, "frame.ciphertext");
   return raw;
 }
+var PAIR_CODE_RE = /^\d{3}-\d{3}$/;
+function validatePairPending(raw) {
+  assertString(raw.mcpId, "pair-pending.mcpId");
+  if (!isValidMcpId(raw.mcpId))
+    throw new ProtocolError("pair-pending.mcpId: invalid format");
+  assertString(raw.pairCode, "pair-pending.pairCode");
+  if (!PAIR_CODE_RE.test(raw.pairCode)) {
+    throw new ProtocolError(`pair-pending.pairCode: must match XXX-XXX, got ${String(raw.pairCode)}`);
+  }
+  return { type: "pair-pending", mcpId: raw.mcpId, pairCode: raw.pairCode };
+}
 function validateInnerFrame(raw) {
   assertObject(raw, "inner");
   const t = raw.type;
@@ -35540,7 +35640,9 @@ async function startHost(opts) {
   const peers = /* @__PURE__ */ new Map();
   const ownInnerListeners = [];
   const disconnectListeners = [];
+  const pendingPairListeners = [];
   let ownSession = null;
+  let ownPendingPairCode = null;
   let resolveOwnSession;
   let rejectOwnSession;
   let ownSessionReady;
@@ -35625,6 +35727,7 @@ async function startHost(opts) {
             if (extensionWs !== ws)
               return;
             ownSession = new SessionState(key);
+            ownPendingPairCode = null;
             resolveOwnSession(ownSession);
           } else {
             const slot = peers.get(frame.mcpId);
@@ -35652,6 +35755,16 @@ async function startHost(opts) {
               extensionWs.send(JSON.stringify(frame));
           }
         }
+        if (frame.type === "pair-pending" && identified === "extension") {
+          if (frame.mcpId === opts.ownMcpId) {
+            ownPendingPairCode = frame.pairCode;
+            pendingPairListeners.forEach((cb) => cb(frame.pairCode));
+          } else {
+            const slot = peers.get(frame.mcpId);
+            if (slot)
+              slot.ws.send(JSON.stringify(frame));
+          }
+        }
       } catch (e) {
         console.error("[fetchproxy] host: message handler error:", e);
         try {
@@ -35697,7 +35810,11 @@ async function startHost(opts) {
     },
     onExtensionDisconnect: (cb) => {
       disconnectListeners.push(cb);
-    }
+    },
+    onPendingPair: (cb) => {
+      pendingPairListeners.push(cb);
+    },
+    pendingPairCode: () => ownPendingPairCode
   };
 }
 
@@ -35727,36 +35844,57 @@ async function startPeer(opts) {
   const sessionNonce = fromB64(hello.sessionNonce);
   ws.send(JSON.stringify(hello));
   const innerListeners = [];
+  const renegotiateListeners = [];
+  const pendingPairListeners = [];
   let session = null;
+  let pendingPairCode = null;
+  let resolveFirstReady;
+  let rejectFirstReady;
   const sessionPromise = new Promise((resolve2, reject) => {
-    const onMessage = async (data) => {
-      try {
-        const raw = JSON.parse(data.toString());
-        const frame = validateFrame(raw);
-        if (frame.type === "ready" && frame.mcpId === opts.mcpId) {
-          const extPub = fromB64(frame.extensionSessionPub);
-          const shared = await ecdhX25519(opts.identity.x25519Priv, extPub);
-          const sessionKey = await hkdfSha256(shared, sessionNonce, enc3.encode(HKDF_SESSION_INFO), 32);
-          session = new SessionState(sessionKey);
-          resolve2(session);
-          return;
+    resolveFirstReady = resolve2;
+    rejectFirstReady = reject;
+  });
+  const onMessage = async (data) => {
+    try {
+      const raw = JSON.parse(data.toString());
+      const frame = validateFrame(raw);
+      if (frame.type === "ready" && frame.mcpId === opts.mcpId) {
+        const extPub = fromB64(frame.extensionSessionPub);
+        const shared = await ecdhX25519(opts.identity.x25519Priv, extPub);
+        const sessionKey = await hkdfSha256(shared, sessionNonce, enc3.encode(HKDF_SESSION_INFO), 32);
+        const isRenegotiation = session !== null;
+        session = new SessionState(sessionKey);
+        pendingPairCode = null;
+        if (isRenegotiation) {
+          renegotiateListeners.forEach((cb) => cb());
+        } else {
+          resolveFirstReady(session);
         }
-        if (frame.type === "frame" && frame.mcpId === opts.mcpId) {
-          if (!session)
-            return;
-          if (!session.acceptInboundSeq(frame.seq))
-            return;
+        return;
+      }
+      if (frame.type === "pair-pending" && frame.mcpId === opts.mcpId) {
+        pendingPairCode = frame.pairCode;
+        pendingPairListeners.forEach((cb) => cb(frame.pairCode));
+        return;
+      }
+      if (frame.type === "frame" && frame.mcpId === opts.mcpId) {
+        if (!session)
+          return;
+        if (!session.acceptInboundSeq(frame.seq))
+          return;
+        try {
           const inner = await openEncryptedFrame(session.sessionKey, frame);
           innerListeners.forEach((cb) => cb(inner));
+        } catch {
         }
-      } catch (e) {
-        reject(e instanceof Error ? e : new Error(String(e)));
       }
-    };
-    ws.on("message", onMessage);
-    ws.once("close", () => {
-      reject(new Error("peer WS closed before ready"));
-    });
+    } catch (e) {
+      rejectFirstReady(e instanceof Error ? e : new Error(String(e)));
+    }
+  };
+  ws.on("message", onMessage);
+  ws.once("close", () => {
+    rejectFirstReady(new Error("peer WS closed before ready"));
   });
   sessionPromise.catch(() => {
   });
@@ -35764,13 +35902,21 @@ async function startPeer(opts) {
     ws,
     session: sessionPromise,
     sendInner: async (inner) => {
-      const s = await sessionPromise;
+      await sessionPromise;
+      const s = session;
       const sealed = await sealInnerFrame(s.sessionKey, opts.mcpId, s.nextOutboundSeq(), inner);
       ws.send(JSON.stringify(sealed));
     },
     onInner: (cb) => {
       innerListeners.push(cb);
     },
+    onRenegotiate: (cb) => {
+      renegotiateListeners.push(cb);
+    },
+    onPendingPair: (cb) => {
+      pendingPairListeners.push(cb);
+    },
+    pendingPairCode: () => pendingPairCode,
     close: () => ws.close()
   };
   return handle;
@@ -35868,6 +36014,52 @@ var FetchproxyHttpError = class extends Error {
     this.name = "FetchproxyHttpError";
   }
 };
+var FetchproxyBridgeDownError = class extends FetchproxyProtocolError {
+  originalError;
+  retryAttempted;
+  op;
+  url;
+  /** 0.8.0+: bridge role at throw time; `null` if listen() hadn't bound yet. */
+  role;
+  /** 0.8.0+: bridge port at throw time (the same port `listen()` bound to). */
+  port;
+  hint;
+  constructor(args) {
+    const retryAttempted = args.retryAttempted ?? false;
+    const op = args.op ?? "fetch";
+    const retryClause = retryAttempted ? `Server already burned a one-shot lazy-revive retry; SW is still down. ` : `Server lazy-revive retry was disabled (bridgeReviveDelayMs unset/0). `;
+    const hint = `the fetchproxy extension's service worker is not responding ("${args.originalError}"). Chrome evicts extension service workers after ~30s idle by default. ${retryClause}Wake it by clicking the fetchproxy extension toolbar icon, then retry. If it keeps happening, reload the extension from chrome://extensions.`;
+    super(`fetchproxy bridge down during ${op}${args.url ? ` (${args.url})` : ""}. ${hint}`);
+    this.name = "FetchproxyBridgeDownError";
+    this.originalError = args.originalError;
+    this.retryAttempted = retryAttempted;
+    this.op = op;
+    if (args.url !== void 0)
+      this.url = args.url;
+    this.role = args.role ?? null;
+    this.port = args.port ?? 0;
+    this.hint = hint;
+  }
+};
+var FetchproxyTimeoutError = class extends FetchproxyProtocolError {
+  url;
+  timeoutMs;
+  /** 0.8.0+: bridge role at throw time; `null` if listen() hadn't bound yet. */
+  role;
+  /** 0.8.0+: bridge port at throw time. */
+  port;
+  /** 0.8.0+: actual elapsed milliseconds when the timer won the race. */
+  elapsedMs;
+  constructor(args) {
+    super(`fetchproxy: ${args.url} did not respond within ${args.timeoutMs}ms`);
+    this.name = "FetchproxyTimeoutError";
+    this.url = args.url;
+    this.timeoutMs = args.timeoutMs;
+    this.role = args.role ?? null;
+    this.port = args.port ?? 0;
+    this.elapsedMs = args.elapsedMs ?? args.timeoutMs;
+  }
+};
 var SUBDOMAIN_LABEL_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/i;
 function assertSubdomainLabel(label) {
   if (!SUBDOMAIN_LABEL_RE.test(label)) {
@@ -35895,12 +36087,28 @@ function assertUrlInDomains(field, url2, domains) {
 }
 var DEFAULT_JSON_OK_STATUSES = [200, 201, 202, 204];
 var FetchproxyServer = class {
-  /** Set after `listen()` succeeds. Null while not listening. */
+  /**
+   * Bridge role. `null` until the first verb call (or an explicit
+   * `connect()`) — `listen()` no longer triggers the role election
+   * as of 0.5.3+. Reset to `null` on `close()`.
+   */
   role = null;
   opts;
   hostHandle = null;
   peerHandle = null;
   nextRequestId = 1;
+  // 0.8.0+: process-wide freshness counters surfaced via bridgeHealth().
+  // Replaces the local copies every downstream MCP was rolling on top
+  // of its own transport adapter — see realty-mcp cohort drift notes.
+  // Updated by recordSuccess / recordFailure from fetch + capture paths.
+  // `lastExtensionMessageAt` (#23 ask 4) is updated whenever any inner
+  // frame from the extension arrives — gives extension-side liveness
+  // distinct from per-call success/failure.
+  lastSuccessAt = null;
+  lastFailureAt = null;
+  lastFailureReason = null;
+  consecutiveFailures = 0;
+  lastExtensionMessageAt = null;
   pending = /* @__PURE__ */ new Map();
   // Separate pending map for read_cookies so the response shape (cookies
   // string vs status/body) doesn't have to share a union type with fetch.
@@ -35917,6 +36125,12 @@ var FetchproxyServer = class {
   pendingIdb = /* @__PURE__ */ new Map();
   mcpId = null;
   identity = null;
+  // 0.5.3+: in-flight role-election / handle-start promise. Set the
+  // first time a verb call runs `ensureConnected`, awaited by concurrent
+  // callers, cleared once the connection is up. Single source of truth
+  // for "we're connecting right now" so two parallel first-calls don't
+  // race the port bind.
+  connectingPromise = null;
   constructor(opts) {
     if (!Array.isArray(opts.domains) || opts.domains.length === 0) {
       throw new Error("FetchproxyServer: opts.domains must be a non-empty array of hostnames");
@@ -35963,28 +36177,98 @@ var FetchproxyServer = class {
         key: d.key,
         jsonPointer: d.jsonPointer
       })),
+      // 0.8.0+: timer + lazy-revive default to ON. Every realty MCP
+      // adapter was about to set these to the same numbers anyway; the
+      // back-door is `0` (explicit opt-out) if a caller genuinely wants
+      // the legacy hang-forever / fail-once-on-SW-eviction behavior.
+      fetchTimeoutMs: opts.fetchTimeoutMs ?? 3e4,
+      bridgeReviveDelayMs: opts.bridgeReviveDelayMs ?? 2e3,
       identityDir: opts.identityDir,
       onPairCode: opts.onPairCode
     };
   }
   /**
-   * Start the WebSocket bridge. Loads the long-term identity keypair
-   * from disk (creating it on first call), elects the host-vs-peer
-   * role by attempting to bind the configured port, and stands up the
-   * matching handshake machinery. Idempotent only insofar as it leaves
-   * `role` non-null on success; calling `listen()` twice without an
-   * intervening `close()` is a programming error.
+   * Prepare the bridge for use. Loads the long-term identity keypair
+   * from disk (creating it on first call) and computes this instance's
+   * `mcpId`. Does NOT bind the bridge port or dial any WebSocket — the
+   * connection is established lazily on the first verb call (see
+   * `ensureConnected` / `getOrConnect`).
+   *
+   * Pre-0.5.3 behavior: `listen()` also did role election and started
+   * the host/peer immediately, which meant every configured-but-unused
+   * MCP claimed bridge resources at MCP-client boot. Several MCPs
+   * starting in parallel under Claude Desktop also produced noisy
+   * `ERR_CONNECTION_REFUSED` errors in the extension if it raced ahead
+   * of the first MCP's port bind. Deferring keeps boot quiet and
+   * leaves the port unowned until something actually needs it.
+   *
+   * Calling `listen()` twice without an intervening `close()` is a
+   * no-op (the second call's identity load is idempotent).
    */
   async listen() {
-    this.identity = await loadOrCreateIdentity(this.opts.serverName, this.opts.identityDir);
-    this.mcpId = generateMcpId(this.opts.serverName, this.opts.version);
+    if (!this.identity) {
+      this.identity = await loadOrCreateIdentity(this.opts.serverName, this.opts.identityDir);
+    }
+    if (!this.mcpId) {
+      this.mcpId = generateMcpId(this.opts.serverName, this.opts.version);
+    }
+  }
+  /**
+   * Force an eager bridge connection (role-election + host/peer handle
+   * start + listener wiring) without waiting for the first verb call.
+   * Useful for callers that want to surface the role / connection
+   * outcome at boot, or for tests whose harness dials a mock extension
+   * immediately after server construction. Production MCPs that just
+   * answer tool calls should NOT call this — the lazy connect via
+   * `ensureConnected` will do the right thing on first use, keeping
+   * boot cheap and avoiding port-bind contention for MCPs that never
+   * actually get invoked.
+   *
+   * Idempotent: a second call after the first has resolved is a no-op
+   * (the existing handle is reused). Throws if `listen()` was never
+   * called.
+   */
+  async connect() {
+    await this.ensureConnected();
+  }
+  /**
+   * Establish the bridge connection (role-election + host/peer handle
+   * start + listener wiring) the first time a verb is invoked.
+   * Idempotent after the connection is up; concurrent first-callers
+   * share the same in-flight promise so only one election happens.
+   *
+   * Throws if `listen()` was never called — the contract is that the
+   * MCP author still must wire `transport.start()` at boot to load
+   * identity / set mcpId, even though the WS doesn't open until a
+   * verb runs.
+   */
+  async ensureConnected() {
+    if (this.hostHandle || this.peerHandle)
+      return;
+    if (this.connectingPromise) {
+      await this.connectingPromise;
+      return;
+    }
+    if (!this.identity || !this.mcpId) {
+      throw new Error("FetchproxyServer: ensureConnected called before listen() \u2014 call listen() at MCP boot to load identity");
+    }
+    this.connectingPromise = this.doConnect();
+    try {
+      await this.connectingPromise;
+    } finally {
+      this.connectingPromise = null;
+    }
+  }
+  async doConnect() {
+    const identity = this.identity;
+    const mcpId = this.mcpId;
     const el = await electRole({ host: this.opts.host, port: this.opts.port });
     if (el.role === "host") {
       this.role = "host";
       this.hostHandle = await startHost({
         httpServer: el.server,
-        ownIdentity: this.identity,
-        ownMcpId: this.mcpId,
+        ownIdentity: identity,
+        ownMcpId: mcpId,
         ownServerName: this.opts.serverName,
         ownVersion: this.opts.version,
         ownDomains: this.opts.domains,
@@ -36000,13 +36284,16 @@ var FetchproxyServer = class {
       });
       this.hostHandle.onOwnInner((inner) => this.onInner(inner));
       this.hostHandle.onExtensionDisconnect(() => this.rejectAllPending());
+      this.hostHandle.onPendingPair((code) => {
+        this.rejectAllPending(this.pairingErrorMessage(code));
+      });
     } else {
       this.role = "peer";
       this.peerHandle = await startPeer({
         host: this.opts.host,
         port: this.opts.port,
-        identity: this.identity,
-        mcpId: this.mcpId,
+        identity,
+        mcpId,
         serverName: this.opts.serverName,
         version: this.opts.version,
         domains: this.opts.domains,
@@ -36020,8 +36307,19 @@ var FetchproxyServer = class {
         sessionStoragePointers: this.opts.sessionStoragePointers
       });
       this.peerHandle.onInner((inner) => this.onInner(inner));
+      this.peerHandle.onRenegotiate(() => this.rejectAllPending());
+      this.peerHandle.onPendingPair((code) => {
+        this.rejectAllPending(this.pairingErrorMessage(code));
+      });
+      if (this.opts.onPairCode) {
+        const cb = this.opts.onPairCode;
+        this.peerHandle.onPendingPair((code) => cb(code));
+      }
     }
   }
+  pairingErrorMessage(code) {
+    return `fetchproxy transport error: pairing required for ${this.opts.serverName}. Tell the user to open the Transporter browser extension popup and approve the pair request. The pair code is: ${code} \u2014 display this code to the user so they can verify it matches.`;
+  }
   /**
    * Raw single-shot fetch through the bridge. Most callers should prefer
    * the verb shortcuts (`get` / `post` / `getJson` / `postJson` / `getHtml`)
@@ -36037,9 +36335,75 @@ var FetchproxyServer = class {
    * offline, etc.).
    */
   async fetch(init) {
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error("FetchproxyServer.fetch called before listen() \u2014 not listening");
+    await this.ensureConnected();
+    const pendingCode = this.currentPendingPairCode();
+    if (pendingCode !== null) {
+      const error51 = this.pairingErrorMessage(pendingCode);
+      return {
+        ok: false,
+        error: error51,
+        kind: classifyFetchError(error51),
+        retryAttempted: false
+      };
     }
+    const first = await this._fetchOnceWithTimeout(init);
+    const reviveMs = this.opts.bridgeReviveDelayMs;
+    let final = first;
+    if (!first.ok && first.kind === "content_script_unreachable" && reviveMs !== void 0 && reviveMs > 0) {
+      await new Promise((r) => setTimeout(r, reviveMs));
+      const second = await this._fetchOnceWithTimeout(init);
+      if (second.ok)
+        this.recordSuccess();
+      else
+        this.recordFailure(`${second.kind ?? "other"}: ${second.error}`);
+      return { ...second, retryAttempted: true };
+    }
+    if (first.ok)
+      this.recordSuccess();
+    else
+      this.recordFailure(`${first.kind ?? "other"}: ${first.error}`);
+    return { ...first, retryAttempted: false };
+  }
+  /**
+   * 0.8.0+: snapshot of the bridge's process-wide freshness counters,
+   * suitable for surfacing through a downstream MCP's healthcheck tool.
+   * Counters reset on a success (consecutiveFailures), accumulate
+   * across the process lifetime otherwise. Replaces the per-MCP
+   * duplication the realty cohort had been rolling in their adapters.
+   * `lastExtensionMessageAt` is updated whenever ANY inner frame
+   * arrives from the extension — gives extension-side liveness
+   * distinct from server-side success/failure of the user-visible
+   * call (addresses #23 ask 4).
+   */
+  bridgeHealth() {
+    return {
+      role: this.role,
+      port: this.opts.port,
+      serverVersion: this.opts.version,
+      fetchTimeoutMs: this.opts.fetchTimeoutMs ?? 0,
+      bridgeReviveDelayMs: this.opts.bridgeReviveDelayMs ?? 0,
+      lastSuccessAt: this.lastSuccessAt,
+      lastFailureAt: this.lastFailureAt,
+      lastFailureReason: this.lastFailureReason,
+      consecutiveFailures: this.consecutiveFailures,
+      lastExtensionMessageAt: this.lastExtensionMessageAt
+    };
+  }
+  recordSuccess() {
+    this.lastSuccessAt = Date.now();
+    this.consecutiveFailures = 0;
+  }
+  recordFailure(reason) {
+    this.lastFailureAt = Date.now();
+    this.lastFailureReason = reason;
+    this.consecutiveFailures += 1;
+  }
+  /**
+   * Single bridge round-trip, wrapped by `fetchTimeoutMs` when set.
+   * On timeout returns the `{ok:false, kind:'timeout'}` envelope —
+   * the throwing surface is the convenience methods.
+   */
+  async _fetchOnceWithTimeout(init) {
     const id = this.nextRequestId++;
     const inner = { type: "request", id, op: "fetch", init };
     const pending = new Promise((resolve2) => {
@@ -36050,7 +36414,61 @@ var FetchproxyServer = class {
     } else if (this.peerHandle) {
       await this.peerHandle.sendInner(inner);
     }
-    return pending;
+    const timeoutMs = this.opts.fetchTimeoutMs;
+    if (timeoutMs === void 0 || timeoutMs <= 0)
+      return pending;
+    let timer;
+    const start = Date.now();
+    try {
+      return await Promise.race([
+        pending,
+        new Promise((resolve2) => {
+          timer = setTimeout(() => {
+            this.pending.delete(id);
+            const elapsedMs = Date.now() - start;
+            const error51 = `fetchproxy: ${init.url} did not respond within ${timeoutMs}ms`;
+            resolve2({
+              ok: false,
+              error: error51,
+              kind: "timeout",
+              retryAttempted: false,
+              elapsedMs
+            });
+          }, timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timer)
+        clearTimeout(timer);
+    }
+  }
+  /**
+   * Map an `ok:false` fetch result to its typed throwable. Centralizes
+   * the kind-to-error-class switch so `request()` and (via the same
+   * logic re-implemented inline) `captureRequestHeader()` agree on what
+   * to throw.
+   */
+  _typedErrorFor(result, url2, op, retryAttempted) {
+    if (result.kind === "timeout") {
+      return new FetchproxyTimeoutError({
+        url: url2,
+        timeoutMs: this.opts.fetchTimeoutMs ?? 0,
+        role: this.role,
+        port: this.opts.port,
+        elapsedMs: result.elapsedMs
+      });
+    }
+    if (result.kind === "content_script_unreachable") {
+      return new FetchproxyBridgeDownError({
+        originalError: result.error,
+        retryAttempted,
+        op,
+        url: url2,
+        role: this.role,
+        port: this.opts.port
+      });
+    }
+    return new FetchproxyProtocolError(result.error);
   }
   /**
    * Convenience wrapper around `fetch()`. Builds the URL from a path
@@ -36073,8 +36491,18 @@ var FetchproxyServer = class {
     if (opts.subdomain !== void 0)
       assertSubdomainLabel(opts.subdomain);
     const baseDomain = this.resolveBaseDomain(opts.domain);
-    const host = opts.subdomain ? `${opts.subdomain}.${baseDomain}` : baseDomain;
-    const url2 = path.startsWith("http://") || path.startsWith("https://") ? path : `https://${host}${path}`;
+    const isAbsolute2 = path.startsWith("http://") || path.startsWith("https://");
+    let host;
+    if (isAbsolute2) {
+      try {
+        host = new URL(path).host;
+      } catch {
+        throw new Error(`FetchproxyServer.request: absolute path is not a valid URL: ${JSON.stringify(path)}`);
+      }
+    } else {
+      host = opts.subdomain ? `${opts.subdomain}.${baseDomain}` : baseDomain;
+    }
+    const url2 = isAbsolute2 ? path : `https://${host}${path}`;
     assertUrlInDomains("request url", url2, this.opts.domains);
     const init = {
       url: url2,
@@ -36085,7 +36513,7 @@ var FetchproxyServer = class {
     };
     const result = await this.fetch(init);
     if (!result.ok) {
-      throw new FetchproxyProtocolError(result.error);
+      throw this._typedErrorFor(result, init.url, "fetch", result.retryAttempted ?? false);
     }
     const response = {
       status: result.status,
@@ -36179,9 +36607,8 @@ var FetchproxyServer = class {
     if (!this.opts.capabilities.includes("read_cookies")) {
       throw new Error('FetchproxyServer.readCookies(): MCP did not declare "read_cookies" in capabilities \u2014 add it to FetchproxyServerOpts.capabilities to enable this verb');
     }
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error("FetchproxyServer.readCookies called before listen() \u2014 not listening");
-    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
     if (opts.subdomain !== void 0)
       assertSubdomainLabel(opts.subdomain);
     const baseDomain = this.resolveBaseDomain(opts.domain);
@@ -36238,9 +36665,8 @@ var FetchproxyServer = class {
     if (!this.opts.capabilities.includes(op)) {
       throw new Error(`FetchproxyServer.${op === "read_local_storage" ? "readLocalStorage" : "readSessionStorage"}(): MCP did not declare ${JSON.stringify(op)} in capabilities`);
     }
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error(`FetchproxyServer.${op} called before listen() \u2014 not listening`);
-    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
     if (!Array.isArray(opts.keys) || opts.keys.length === 0) {
       throw new Error(`FetchproxyServer.${op}: opts.keys must be a non-empty array`);
     }
@@ -36295,13 +36721,75 @@ var FetchproxyServer = class {
     if (!this.opts.capabilities.includes("capture_request_header")) {
       throw new Error('FetchproxyServer.captureRequestHeader(): MCP did not declare "capture_request_header" in capabilities');
     }
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error("FetchproxyServer.captureRequestHeader called before listen() \u2014 not listening");
+    await this.ensureConnected();
+    this.throwIfPendingPair();
+    const decls = this.opts.captureHeaders;
+    let resolved;
+    if (opts?.urlPattern !== void 0 && opts?.headerName !== void 0) {
+      const found = decls.find((d) => d.urlPattern === opts.urlPattern && d.headerName === opts.headerName);
+      if (!found) {
+        throw new Error(`FetchproxyServer.captureRequestHeader: (urlPattern=${JSON.stringify(opts.urlPattern)}, headerName=${JSON.stringify(opts.headerName)}) not declared in captureHeaders`);
+      }
+      resolved = found;
+    } else if (opts?.urlPattern === void 0 && opts?.headerName === void 0) {
+      if (decls.length === 0) {
+        throw new Error("FetchproxyServer.captureRequestHeader: no captureHeaders declared on this server \u2014 declare at least one entry in FetchproxyServerOpts.captureHeaders, or pass {urlPattern, headerName} explicitly");
+      }
+      if (decls.length > 1) {
+        const list = decls.map((d) => `${JSON.stringify(d.urlPattern)}/${JSON.stringify(d.headerName)}`).join(", ");
+        throw new Error(`FetchproxyServer.captureRequestHeader: multiple captureHeaders declared (${decls.length}: ${list}); pass {urlPattern, headerName} to disambiguate`);
+      }
+      resolved = decls[0];
+    } else {
+      throw new Error("FetchproxyServer.captureRequestHeader: pass both urlPattern AND headerName, or neither (which defaults to the single declared entry)");
     }
-    const declared = this.opts.captureHeaders.find((d) => d.urlPattern === opts.urlPattern && d.headerName === opts.headerName);
-    if (!declared) {
-      throw new Error(`FetchproxyServer.captureRequestHeader: (urlPattern=${JSON.stringify(opts.urlPattern)}, headerName=${JSON.stringify(opts.headerName)}) not declared in captureHeaders`);
+    const callOpts = { ...resolved, ...opts?.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {} };
+    try {
+      const result = await this._captureRequestHeaderOnce(callOpts);
+      this.recordSuccess();
+      return result;
+    } catch (err) {
+      const swDown = err instanceof FetchproxyProtocolError && classifyFetchError(err.message) === "content_script_unreachable";
+      if (!swDown) {
+        this.recordFailure(`capture_request_header: ${err.message ?? String(err)}`);
+        throw err;
+      }
+      const reviveMs = this.opts.bridgeReviveDelayMs ?? 0;
+      if (reviveMs > 0) {
+        await new Promise((r) => setTimeout(r, reviveMs));
+        try {
+          const result = await this._captureRequestHeaderOnce(callOpts);
+          this.recordSuccess();
+          return result;
+        } catch (retryErr) {
+          const stillDown = retryErr instanceof FetchproxyProtocolError && classifyFetchError(retryErr.message) === "content_script_unreachable";
+          if (!stillDown) {
+            this.recordFailure(`capture_request_header: ${retryErr.message ?? String(retryErr)}`);
+            throw retryErr;
+          }
+          this.recordFailure(`capture_request_header bridge-down: ${retryErr.message}`);
+          throw new FetchproxyBridgeDownError({
+            originalError: retryErr.message,
+            retryAttempted: true,
+            op: "capture_request_header",
+            url: resolved.urlPattern,
+            role: this.role,
+            port: this.opts.port
+          });
+        }
+      }
+      this.recordFailure(`capture_request_header bridge-down: ${err.message}`);
+      throw new FetchproxyBridgeDownError({
+        originalError: err.message,
+        retryAttempted: false,
+        op: "capture_request_header",
+        url: resolved.urlPattern,
+        role: this.role,
+        port: this.opts.port
+      });
     }
+  }
+  async _captureRequestHeaderOnce(opts) {
     const id = this.nextRequestId++;
     const inner = {
       type: "request",
@@ -36338,9 +36826,8 @@ var FetchproxyServer = class {
     if (!this.opts.capabilities.includes("read_indexed_db")) {
       throw new Error('FetchproxyServer.readIndexedDb(): MCP did not declare "read_indexed_db" in capabilities');
     }
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error("FetchproxyServer.readIndexedDb called before listen() \u2014 not listening");
-    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
     if (!Array.isArray(opts.keys) || opts.keys.length === 0) {
       throw new Error("FetchproxyServer.readIndexedDb: opts.keys must be a non-empty array");
     }
@@ -36411,18 +36898,35 @@ var FetchproxyServer = class {
   onInner(inner) {
     if (inner.type !== "response")
       return;
+    this.lastExtensionMessageAt = Date.now();
     const fetchCb = this.pending.get(inner.id);
     if (fetchCb) {
       this.pending.delete(inner.id);
       if (inner.ok) {
         if (inner.op === void 0 || inner.op === "fetch") {
-          fetchCb({ ok: true, status: inner.status, url: inner.url, body: inner.body });
+          fetchCb({
+            ok: true,
+            status: inner.status,
+            url: inner.url,
+            body: inner.body,
+            retryAttempted: false
+          });
         } else {
           const error51 = `unexpected ${inner.op} response on fetch awaiter`;
-          fetchCb({ ok: false, error: error51, kind: classifyFetchError(error51) });
+          fetchCb({
+            ok: false,
+            error: error51,
+            kind: classifyFetchError(error51),
+            retryAttempted: false
+          });
         }
       } else {
-        fetchCb({ ok: false, error: inner.error, kind: classifyFetchError(inner.error) });
+        fetchCb({
+          ok: false,
+          error: inner.error,
+          kind: classifyFetchError(inner.error),
+          retryAttempted: false
+        });
       }
       return;
     }
@@ -36489,10 +36993,15 @@ var FetchproxyServer = class {
       }
     }
   }
-  rejectAllPending() {
-    const err = new FetchproxyProtocolError("extension disconnected");
+  rejectAllPending(reason = "extension disconnected") {
+    const err = new FetchproxyProtocolError(reason);
     for (const cb of this.pending.values()) {
-      cb({ ok: false, error: err.message, kind: classifyFetchError(err.message) });
+      cb({
+        ok: false,
+        error: err.message,
+        kind: classifyFetchError(err.message),
+        retryAttempted: false
+      });
     }
     this.pending.clear();
     for (const cb of this.pendingReadCookies.values()) {
@@ -36509,6 +37018,32 @@ var FetchproxyServer = class {
       reject(err);
     this.pendingIdb.clear();
   }
+  /**
+   * 0.5.2+: read the current pair-pending pair code from whichever handle
+   * is active, returning null when none is pending. Public verbs call this
+   * at the top so that a tool invoked while the bridge is waiting on user
+   * approval fails fast with the actionable error rather than hanging on a
+   * sealed frame the extension will never process.
+   */
+  currentPendingPairCode() {
+    if (this.hostHandle)
+      return this.hostHandle.pendingPairCode();
+    if (this.peerHandle)
+      return this.peerHandle.pendingPairCode();
+    return null;
+  }
+  /**
+   * 0.5.2+: throw `FetchproxyProtocolError` with the actionable pair-code
+   * message if the bridge is waiting on user approval. Used by the verb
+   * methods (readCookies, readLocalStorage, etc.) that surface errors via
+   * thrown exceptions rather than `ok:false` discriminated unions.
+   */
+  throwIfPendingPair() {
+    const code = this.currentPendingPairCode();
+    if (code !== null) {
+      throw new FetchproxyProtocolError(this.pairingErrorMessage(code));
+    }
+  }
   /**
    * Shut down the bridge. Host: terminates the WebSocket server and any
    * still-attached extension/peer clients. Peer: closes the upstream
@@ -36517,6 +37052,9 @@ var FetchproxyServer = class {
    */
   async close() {
     this.rejectAllPending();
+    if (this.connectingPromise) {
+      await this.connectingPromise.catch(() => void 0);
+    }
     if (this.hostHandle)
       await this.hostHandle.close();
     if (this.peerHandle)
@@ -36524,9 +37062,23 @@ var FetchproxyServer = class {
     this.hostHandle = null;
     this.peerHandle = null;
     this.role = null;
+    this.connectingPromise = null;
   }
 };
 
+// node_modules/@fetchproxy/server/dist/classify-bridge-error.js
+function classifyBridgeError(err) {
+  if (err instanceof FetchproxyTimeoutError)
+    return "timeout";
+  if (err instanceof FetchproxyBridgeDownError)
+    return "bridge_down";
+  if (err instanceof FetchproxyHttpError)
+    return "http";
+  if (err instanceof FetchproxyProtocolError)
+    return "protocol";
+  return "other";
+}
+
 // node_modules/@fetchproxy/bootstrap/dist/index.js
 var defaultFactory = (opts) => new FetchproxyServer(opts);
 async function bootstrap(opts) {
@@ -36581,7 +37133,11 @@ async function bootstrap(opts) {
       key: p.storageKey,
       jsonPointer: p.jsonPointer
     })),
-    onPairCode: opts.onPairCode
+    onPairCode: opts.onPairCode,
+    // 0.8.0+ pass-through. Only forwarded when the caller set them;
+    // unset → server defaults apply (30000 / 2000 in 0.8.0).
+    ...opts.fetchTimeoutMs !== void 0 ? { fetchTimeoutMs: opts.fetchTimeoutMs } : {},
+    ...opts.bridgeReviveDelayMs !== void 0 ? { bridgeReviveDelayMs: opts.bridgeReviveDelayMs } : {}
   });
   const storageDomainOpts = {};
   if (opts.storageDomain !== void 0)
@@ -36766,7 +37322,7 @@ function getDefaultInlineAttachments() {
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.0.19",
+  version: "2.2.0",
   mcpName: "io.github.chrischall/ofw-mcp",
   description: "OurFamilyWizard MCP server for Claude \u2014 developed and maintained by AI (Claude Code)",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -36793,17 +37349,18 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@fetchproxy/bootstrap": "^0.5.1",
+    "@fetchproxy/bootstrap": "^0.8.0",
+    "@fetchproxy/server": "^0.8.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    dotenv: "^17.4.0",
-    zod: "^4.4.2"
+    dotenv: "^17.4.2",
+    zod: "^4.4.3"
   },
   devDependencies: {
-    "@types/node": "^25.8.0",
-    "@vitest/coverage-v8": "^4.1.6",
+    "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "^4.1.7",
     esbuild: "^0.28.0",
-    typescript: "^6.0.2",
-    vitest: "^4.1.6"
+    typescript: "^6.0.3",
+    vitest: "^4.1.7"
   }
 };
 
@@ -36860,6 +37417,12 @@ async function resolveAuth() {
         source: "fetchproxy"
       };
     } catch (e) {
+      if (classifyBridgeError(e) === "bridge_down") {
+        const downErr = e;
+        throw new Error(
+          `OFW auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`
+        );
+      }
       const msg = e instanceof Error ? e.message : String(e);
       throw new Error(
         `OFW auth: no OFW_USERNAME/OFW_PASSWORD set, and fetchproxy fallback failed: ${msg}`
@@ -36899,6 +37462,13 @@ function redactHeaders(h) {
   if (out.Authorization) out.Authorization = `Bearer ${out.Authorization.slice(7, 17)}\u2026`;
   return out;
 }
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+function getRequestTimeoutMs() {
+  const raw = process.env.OFW_REQUEST_TIMEOUT_MS;
+  if (typeof raw !== "string" || raw.trim().length === 0) return DEFAULT_REQUEST_TIMEOUT_MS;
+  const n = Number(raw.trim());
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_REQUEST_TIMEOUT_MS;
+}
 var OFWClient = class {
   token = null;
   tokenExpiry = null;
@@ -36939,13 +37509,37 @@ var OFWClient = class {
       console.error(`[ofw-debug]   headers: ${JSON.stringify(redactHeaders(headers))}`);
       console.error(`[ofw-debug]   body: ${bodyPreview}`);
     }
-    const response = await fetch(url2, {
-      method,
-      headers,
-      ...body !== void 0 ? { body: isFormData ? body : JSON.stringify(body) } : {}
-    });
+    const timeoutMs = getRequestTimeoutMs();
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    const startedAt = Date.now();
+    let response;
+    try {
+      response = await fetch(url2, {
+        method,
+        headers,
+        signal: ac.signal,
+        ...body !== void 0 ? { body: isFormData ? body : JSON.stringify(body) } : {}
+      });
+    } catch (err) {
+      const elapsed = Date.now() - startedAt;
+      if (ac.signal.aborted) {
+        if (debugLogEnabled()) {
+          console.error(`[ofw-debug] \u23F1 TIMEOUT after ${elapsed}ms: ${method} ${url2}`);
+        }
+        throw new Error(
+          `OFW API request timed out after ${timeoutMs}ms: ${method} ${path}`
+        );
+      }
+      if (debugLogEnabled()) {
+        console.error(`[ofw-debug] \u2717 ${err.message} after ${elapsed}ms: ${method} ${url2}`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
     if (debugLogEnabled()) {
-      console.error(`[ofw-debug] \u2190 ${response.status} ${response.statusText}`);
+      console.error(`[ofw-debug] \u2190 ${response.status} ${response.statusText} (${Date.now() - startedAt}ms)`);
     }
     if (response.status === 401 && !isRetry) {
       this.token = null;
@@ -37680,18 +38274,55 @@ function registerMessageTools(server2, client2) {
     return jsonResponse({ ...row, attachments });
   });
   server2.registerTool("ofw_send_message", {
-    description: "Send a message via OurFamilyWizard. If sending from a draft, pass draftId to delete the draft after sending. If replyToId is provided, the cache may rewrite it to the latest reply in the same thread (a note is included in the response when this happens). Attach files by passing their fileIds (from ofw_upload_attachment) in myFileIDs. After sending, the tool re-fetches the message from OFW to populate the local cache and link attachments to the new message id.",
+    description: "Send a message via OurFamilyWizard. To send an existing draft, pass messageId \u2014 subject/body/recipientIds become optional overrides (missing fields default to the draft's cached values) and the draft is deleted after sending. To send a fresh message, supply subject/body/recipientIds directly. draftId is the legacy spelling of messageId and works the same way. If replyToId is provided, the cache may rewrite it to the latest reply in the same thread (a note is included in the response when this happens). Attach files by passing their fileIds (from ofw_upload_attachment) in myFileIDs. After sending, the tool re-fetches the message from OFW to populate the local cache and link attachments to the new message id.",
     annotations: { destructiveHint: true },
     inputSchema: {
-      subject: external_exports.string().describe("Message subject"),
-      body: external_exports.string().describe("Message body text"),
-      recipientIds: external_exports.array(external_exports.number()).describe("Array of recipient user IDs (get from ofw_get_profile)"),
+      subject: external_exports.string().describe("Message subject. Required unless messageId/draftId references a cached draft.").optional(),
+      body: external_exports.string().describe("Message body text. Required unless messageId/draftId references a cached draft.").optional(),
+      recipientIds: external_exports.array(external_exports.number()).describe("Array of recipient user IDs (get from ofw_get_profile). Required unless messageId/draftId references a cached draft.").optional(),
       replyToId: external_exports.number().describe("ID of the message being replied to").optional(),
-      draftId: external_exports.number().describe("ID of the draft to delete after sending (omit if not sending from a draft)").optional(),
+      messageId: external_exports.number().describe("ID of an existing draft to send. When set, missing subject/body/recipientIds default to the draft's cached values, and the draft is deleted after sending.").optional(),
+      draftId: external_exports.number().describe("Legacy synonym for messageId. If both are passed they must be equal.").optional(),
       myFileIDs: external_exports.array(external_exports.number()).describe("Attachment file ids (from ofw_upload_attachment) to attach to the message").optional()
     }
   }, async (args) => {
-    const requestedReplyTo = args.replyToId ?? null;
+    if (args.messageId !== void 0 && args.draftId !== void 0 && args.messageId !== args.draftId) {
+      throw new Error(`messageId (${args.messageId}) and draftId (${args.draftId}) refer to different drafts; pass only one.`);
+    }
+    const draftRef = args.messageId ?? args.draftId;
+    let subject = args.subject;
+    let body = args.body;
+    let recipientIds = args.recipientIds;
+    let draftReplyToId = null;
+    let draftLookupAttempted = false;
+    let draftFound = false;
+    if (draftRef !== void 0) {
+      draftLookupAttempted = true;
+      const draft = getDraft(draftRef);
+      if (draft !== null) {
+        draftFound = true;
+        subject = subject ?? draft.subject;
+        body = body ?? draft.body;
+        recipientIds = recipientIds ?? draft.recipients.map((r) => r.userId);
+        draftReplyToId = draft.replyToId;
+      }
+    }
+    if (subject === void 0 || body === void 0 || recipientIds === void 0) {
+      if (draftLookupAttempted && !draftFound) {
+        throw new Error(
+          `draft ${draftRef} not found in local cache. Call ofw_sync_messages first, or supply subject/body/recipientIds explicitly.`
+        );
+      }
+      const missing = [
+        subject === void 0 ? "subject" : null,
+        body === void 0 ? "body" : null,
+        recipientIds === void 0 ? "recipientIds" : null
+      ].filter((n) => n !== null).join(", ");
+      throw new Error(
+        `ofw_send_message requires ${missing}. Pass it directly, or pass messageId to default missing fields from a cached draft.`
+      );
+    }
+    const requestedReplyTo = args.replyToId ?? draftReplyToId ?? null;
     let resolvedReplyTo = requestedReplyTo;
     let chainRootId = null;
     let rewriteNote = null;
@@ -37705,9 +38336,9 @@ function registerMessageTools(server2, client2) {
     }
     const myFileIDs = args.myFileIDs ?? [];
     const { id: newId, detail, raw } = await postMessageAndRefetch(client2, {
-      subject: args.subject,
-      body: args.body,
-      recipientIds: args.recipientIds,
+      subject,
+      body,
+      recipientIds,
       attachments: { myFileIDs },
       draft: false,
       includeOriginal: resolvedReplyTo !== null,
@@ -37718,11 +38349,11 @@ function registerMessageTools(server2, client2) {
       persisted = {
         id: newId,
         folder: "sent",
-        subject: detail.subject ?? args.subject,
+        subject: detail.subject ?? subject,
         fromUser: detail.from?.name ?? "",
         sentAt: detail.date?.dateTime ?? (/* @__PURE__ */ new Date()).toISOString(),
         recipients: mapRecipients(detail.recipients),
-        body: detail.body ?? args.body,
+        body: detail.body ?? body,
         fetchedBodyAt: (/* @__PURE__ */ new Date()).toISOString(),
         replyToId: resolvedReplyTo,
         chainRootId,
@@ -37742,9 +38373,9 @@ function registerMessageTools(server2, client2) {
         });
       }
     }
-    if (args.draftId !== void 0) {
-      await deleteOFWMessages(client2, [args.draftId]);
-      deleteDraft(args.draftId);
+    if (draftRef !== void 0) {
+      await deleteOFWMessages(client2, [draftRef]);
+      deleteDraft(draftRef);
     }
     const responseObj = persisted ?? raw;
     const text = responseObj ? JSON.stringify(responseObj, null, 2) : "Message sent successfully.";
@@ -38153,7 +38784,7 @@ process.emit = function(event, ...args) {
   }
   return originalEmit(event, ...args);
 };
-var server = new McpServer({ name: "ofw", version: "2.0.19" });
+var server = new McpServer({ name: "ofw", version: "2.2.0" });
 registerUserTools(server, client);
 registerMessageTools(server, client);
 registerCalendarTools(server, client);