ofw-mcp 2.0.19 → 2.1.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "OurFamilyWizard tools for Claude Code",
-    "version": "2.0.19"
+    "version": "2.1.0"
   },
   "plugins": [
     {
@@ -14,7 +14,7 @@
       "displayName": "OurFamilyWizard",
       "source": "./",
       "description": "OurFamilyWizard co-parenting tools for Claude — messages, calendar, expenses, and journal via MCP",
-      "version": "2.0.19",
+      "version": "2.1.0",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ofw",
   "displayName": "OurFamilyWizard",
-  "version": "2.0.19",
+  "version": "2.1.0",
   "description": "OurFamilyWizard co-parenting tools for Claude — messages, calendar, expenses, and journal via MCP",
   "author": {
     "name": "Chris Chall"

package/dist/auth.js

@@ -46,6 +46,7 @@
 //     specifically so it can be mocked here too. This keeps the
 //     selection logic independent of either implementation.
 import { bootstrap } from '@fetchproxy/bootstrap';
+import { classifyBridgeError } from '@fetchproxy/server';
 import { loginWithPassword } from './auth-password.js';
 import { parseBoolEnv } from './config.js';
 import pkg from '../package.json' with { type: 'json' };
@@ -121,6 +122,11 @@ export async function resolveAuth() {
             };
         }
         catch (e) {
+            // FetchproxyBridgeDownError only escapes bootstrap() after the lazy-revive retry fails — surface .hint verbatim (actionable "click toolbar icon" copy).
+            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}`);
         }

package/dist/bundle.js

@@ -34856,6 +34856,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 +34959,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 +35553,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 +35640,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 +35668,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 +35723,11 @@ async function startHost(opts) {
     },
     onExtensionDisconnect: (cb) => {
       disconnectListeners.push(cb);
-    }
+    },
+    onPendingPair: (cb) => {
+      pendingPairListeners.push(cb);
+    },
+    pendingPairCode: () => ownPendingPairCode
   };
 }
 
@@ -35727,36 +35757,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 +35815,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 +35927,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 +36000,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 +36038,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 +36090,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 +36197,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 +36220,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 +36248,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 +36327,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 +36404,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 +36426,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 +36520,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 +36578,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 +36634,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 +36739,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 +36811,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 +36906,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 +36931,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 +36965,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 +36975,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 +37046,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 +37235,7 @@ function getDefaultInlineAttachments() {
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.0.19",
+  version: "2.1.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 +37262,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 +37330,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}`
@@ -38153,7 +38629,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.1.0" });
 registerUserTools(server, client);
 registerMessageTools(server, client);
 registerCalendarTools(server, client);

package/dist/index.js

@@ -17,7 +17,7 @@ import { registerMessageTools } from './tools/messages.js';
 import { registerCalendarTools } from './tools/calendar.js';
 import { registerExpenseTools } from './tools/expenses.js';
 import { registerJournalTools } from './tools/journal.js';
-const server = new McpServer({ name: 'ofw', version: '2.0.19' }); // x-release-please-version
+const server = new McpServer({ name: 'ofw', version: '2.1.0' }); // x-release-please-version
 registerUserTools(server, client);
 registerMessageTools(server, client);
 registerCalendarTools(server, client);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.0.19",
+  "version": "2.1.0",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -27,16 +27,17 @@
     "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"
   }
 }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/ofw-mcp",
     "source": "github"
   },
-  "version": "2.0.19",
+  "version": "2.1.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.0.19",
+      "version": "2.1.0",
       "transport": {
         "type": "stdio"
       },