@johnhenry/wsh 0.16.1 → 0.17.1

package/src/client.mjs

@@ -29,6 +29,7 @@ import {
   keyExchange as keyExchangeMsg,
   fileOp as fileOpMsg,
   fileChunk as fileChunkMsg,
+  authorizedKeyAdd as authorizedKeyAddMsg,
   policyEval as policyEvalMsg, policyUpdate as policyUpdateMsg,
   detach as detachMsg,
   sessionListRequest as sessionListRequestMsg,
@@ -52,7 +53,50 @@ const STATE_CLOSED        = 'closed';
 
 const DEFAULT_AUTH_TIMEOUT   = 10_000;  // ms
 const DEFAULT_OPEN_TIMEOUT   = 10_000;  // ms
+
+/**
+ * ServerHello feature advertising that McpResult echoes McpCall's call_id.
+ *
+ * Negotiated rather than assumed: McpCallPayload is `deny_unknown_fields` on
+ * the Rust side, so sending call_id to a server predating it does not
+ * degrade -- it makes the server reject the call.
+ */
+export const MCP_CALL_ID_FEATURE = 'mcp-call-id';
+
+/**
+ * Reject a missing argument that maps to a `required: true` wire field.
+ *
+ * JavaScript will happily let an omitted argument through, and
+ * `cborEncode` turns the resulting `undefined` into CBOR null rather
+ * than dropping the key -- so the message goes out looking well-formed,
+ * gets rejected by a spec-conformant server for a reason that has
+ * nothing to do with what the caller did wrong, and the local stack
+ * trace is long gone by then. This is exactly how `resumeSession()`
+ * shipped broken for two releases (CHANGELOG 0.14.0: `last_seq`
+ * "previously always sent as `undefined`, which the wire's
+ * `required: true` field never tolerated"). Failing here instead names
+ * the argument at the call site.
+ *
+ * @param {string} method - Method name, for the message.
+ * @param {Record<string, *>} args - Argument name -> value.
+ */
+function requireArgs(method, args) {
+  for (const [name, value] of Object.entries(args)) {
+    if (value === undefined || value === null) {
+      throw new TypeError(
+        `${method}: "${name}" is required -- the corresponding wire field is not optional, ` +
+        'and omitting it produces a message a conformant server will reject'
+      );
+    }
+  }
+}
 const DEFAULT_PING_INTERVAL  = 30_000;  // ms
+/*
+ * How long a peer may go without answering a ping before it is treated as
+ * gone. A multiple of the interval, so an ordinary missed pong is tolerated
+ * and a peer that has genuinely stopped answering is not.
+ */
+const DEFAULT_PONG_TIMEOUT   = 90_000;  // ms
 const DEFAULT_EXEC_TIMEOUT   = 60_000;  // ms
 const FILE_CHUNK_SIZE        = 65_536;
 
@@ -181,9 +225,27 @@ export class WshClient {
    */
   #acceptedRelayPeers = new Set();
 
+  /**
+   * Observers registered through addControlListener() — see that method
+   * and #dispatchControlListeners.
+   * @type {Set<function(object): void>}
+   */
+  #controlListeners = new Set();
+
   /** @type {number} Monotonically increasing channel ID counter. */
   #channelCounter = 0;
 
+  /** @type {number} Monotonically increasing MCP call counter for call_id. */
+  #mcpCallCounter = 0;
+
+  /**
+   * Tail of the serialised MCP call chain, used only against servers that do
+   * not advertise `mcp-call-id`. Never rejects: each link swallows so one
+   * failed call does not poison the queue.
+   * @type {Promise<void>}
+   */
+  #mcpQueue = Promise.resolve();
+
   /**
    * Pending message waiters: Map<messageType, Array<{resolve, reject, timer}>>
    * Multiple waiters can exist for the same message type.
@@ -201,12 +263,21 @@ export class WshClient {
 
   /** @type {number|null} Timestamp of last pong received. */
   #lastPong = null;
+  #pingIntervalMs = DEFAULT_PING_INTERVAL;
+  #pongTimeoutMs = DEFAULT_PONG_TIMEOUT;
 
-  constructor({ transportFactories } = {}) {
+  constructor({ transportFactories, pingIntervalMs, pongTimeoutMs } = {}) {
     this.#transportFactories = transportFactories || {
       wt: () => new WebTransportTransport(),
       ws: () => new WebSocketTransport(),
     };
+    /*
+     * Overridable so the keepalive is testable at all. Left as constants,
+     * the only way to observe a 90s timeout is to wait 90s or fake the
+     * clock -- which is why nothing observed it before.
+     */
+    this.#pingIntervalMs = pingIntervalMs ?? DEFAULT_PING_INTERVAL;
+    this.#pongTimeoutMs = pongTimeoutMs ?? DEFAULT_PONG_TIMEOUT;
   }
 
   // ── Callbacks ───────────────────────────────────────────────────────
@@ -342,10 +413,18 @@ export class WshClient {
    * @param {CryptoKeyPair} [opts.keyPair] - Ed25519 key pair for pubkey auth
    * @param {string} [opts.password] - Password for password auth
    * @param {'wt'|'ws'|'auto'} [opts.transport] - Force a specific transport
+   * @param {object} [opts.webTransport] - Options forwarded to the
+   *   `WebTransport` constructor when the WebTransport rung of the ladder
+   *   is tried. Most usefully `serverCertificateHashes`, which pins a
+   *   specific self-signed certificate by SHA-256 digest -- the one way
+   *   page JavaScript can reach a server whose certificate no certificate
+   *   authority signed. Values may be raw bytes, hex (colon-separated is
+   *   fine), or base64. Ignored by the WebSocket rung, which has no
+   *   equivalent mechanism.
    * @param {number} [opts.timeout] - Auth handshake timeout in ms
    * @returns {Promise<string>} The server-assigned session ID
    */
-  async connect(url, { username, keyPair, password, transport: transportHint, timeout = DEFAULT_AUTH_TIMEOUT } = {}) {
+  async connect(url, { username, keyPair, password, transport: transportHint, webTransport, timeout = DEFAULT_AUTH_TIMEOUT } = {}) {
     if (this.#state !== STATE_DISCONNECTED && this.#state !== STATE_CLOSED) {
       throw new Error(`Client already ${this.#state}`);
     }
@@ -365,7 +444,7 @@ export class WshClient {
 
     try {
       // ── Select and connect transport ──────────────────────────────
-      const transport = await this.#connectTransport(url, transportHint);
+      const transport = await this.#connectTransport(url, transportHint, webTransport);
       this.#transport = transport;
       this.#state = STATE_CONNECTED;
 
@@ -834,6 +913,7 @@ export class WshClient {
     username,
     keyPair,
     password,
+    webTransport,
     expose = {},
     peerType = 'browser-shell',
     shellBackend,
@@ -843,7 +923,7 @@ export class WshClient {
     supportsTermSync,
   } = {}) {
     // Authenticate normally first.
-    const sessionId = await this.connect(url, { username, keyPair, password });
+    const sessionId = await this.connect(url, { username, keyPair, password, webTransport });
 
     // Build capabilities list from expose options.
     const capabilities = [];
@@ -985,6 +1065,71 @@ export class WshClient {
     await this.#transport.sendControl(msg);
   }
 
+  // ── Raw control channel (used by WshMcpBridge / WshFileTransfer) ─────
+  //
+  // `WshMcpBridge` and `WshFileTransfer` both document their constructor
+  // argument as "a WshClient", and both drive the connection through
+  // `sendControl()` + `addControlListener()`/`removeControlListener()`
+  // (`WshFileTransfer.list()` also needs `openStream()`). None of those
+  // existed on this class, so every one of those code paths failed with
+  // `TypeError: this.#client.sendControl is not a function` the moment a
+  // real client was passed instead of a hand-written stand-in — the same
+  // shape as the 0.14.0 `attachSession()`/`resumeSession()` bug, where a
+  // whole method was unreachable while the suite stayed green because
+  // every test spoke to a mock that answered whatever it was asked.
+  //
+  // These four members are thin, deliberate delegations rather than a new
+  // subsystem: the transport already owns the socket and the framing, and
+  // `#handleControl` already sees every inbound control message.
+
+  /**
+   * Send a raw control message on the authenticated connection.
+   *
+   * Prefer the typed methods (`openSession`, `callTool`, `upload`, …).
+   * This exists for the helper classes that compose their own messages —
+   * see `WshMcpBridge` and `WshFileTransfer`.
+   *
+   * @param {object} msg
+   * @returns {Promise<void>}
+   */
+  async sendControl(msg) {
+    this.#assertAuthenticated('sendControl');
+    await this.#transport.sendControl(msg);
+  }
+
+  /**
+   * Open a raw bidirectional stream on the underlying transport.
+   *
+   * @returns {Promise<{ readable: ReadableStream, writable: WritableStream }>}
+   */
+  async openStream() {
+    this.#assertAuthenticated('openStream');
+    return this.#transport.openStream();
+  }
+
+  /**
+   * Observe every inbound control message this client handles.
+   *
+   * Listeners are called after the RelayForward trust gate, so a relayed
+   * message from an untrusted peer is never handed to one, and a trusted
+   * RelayForward is delivered as its unwrapped inner message. A listener
+   * that throws is logged and does not stop the client's own dispatch.
+   *
+   * @param {function(object): void} fn
+   */
+  addControlListener(fn) {
+    if (typeof fn !== 'function') throw new TypeError('addControlListener requires a function');
+    this.#controlListeners.add(fn);
+  }
+
+  /**
+   * Stop observing inbound control messages.
+   * @param {function(object): void} fn
+   */
+  removeControlListener(fn) {
+    this.#controlListeners.delete(fn);
+  }
+
   /**
    * Mark a peer fingerprint as an accepted reverse-connect bridge partner.
    *
@@ -1135,22 +1280,60 @@ export class WshClient {
   /**
    * Call an MCP tool on the remote server.
    *
+   * Safe to call concurrently. Against a server advertising the
+   * `mcp-call-id` feature each call carries a correlation id and takes only
+   * its own reply. Against an older server there is no id on the wire and
+   * replies are indistinguishable, so calls are queued one at a time on this
+   * connection -- slower, but never the wrong tool's result.
+   *
    * @param {string} name - Tool name
-   * @param {object} args - Tool arguments
+   * @param {object} [args={}] - Tool arguments. Defaults to `{}` rather
+   *   than being omitted: `McpCall.arguments` is a required wire field,
+   *   and a tool that takes no arguments is an ordinary thing to call.
    * @param {number} [timeout=30000]
    * @returns {Promise<*>} Tool result
    */
-  async callTool(name, args, timeout = 30_000) {
+  async callTool(name, args = {}, timeout = 30_000) {
     this.#assertAuthenticated('callTool');
+    requireArgs('callTool', { name });
+
+    if (this.hasFeature(MCP_CALL_ID_FEATURE)) {
+      return this.#callToolCorrelated(name, args, timeout);
+    }
+    // No correlation available: serialise so a concurrent caller cannot be
+    // handed someone else's result.
+    const run = this.#mcpQueue.then(
+      () => this.#callToolCorrelated(name, args, timeout),
+      () => this.#callToolCorrelated(name, args, timeout),
+    );
+    this.#mcpQueue = run.then(() => undefined, () => undefined);
+    return run;
+  }
+
+  /**
+   * Send one McpCall and wait for the McpResult that answers it.
+   * @private
+   */
+  async #callToolCorrelated(name, args, timeout) {
+    const correlate = this.hasFeature(MCP_CALL_ID_FEATURE);
+    // Only sent when the peer understands it: McpCallPayload is
+    // deny_unknown_fields on the Rust side, so an unsolicited call_id would
+    // make an older server reject the call outright rather than ignore it.
+    const callId = correlate ? `mcp-${++this.#mcpCallCounter}-${Date.now()}` : undefined;
 
     await this.#transport.sendControl(
-      mcpCallMsg({ tool: name, arguments: args })
+      mcpCallMsg({ tool: name, arguments: args, callId })
     );
 
     const response = await this.#waitForMessage(
       [MSG.MCP_RESULT],
       timeout,
-      `Timed out waiting for MCP tool result (${name})`
+      `Timed out waiting for MCP tool result (${name})`,
+      // A responder that echoes no call_id gets matched on type, which is
+      // the pre-correlation behaviour and all an older peer can offer.
+      callId === undefined
+        ? undefined
+        : (msg) => msg.call_id === undefined || msg.call_id === callId,
     );
 
     return response.result;
@@ -1207,6 +1390,7 @@ export class WshClient {
    */
   async inviteGuest(sessionId, ttl, permissions = ['read'], timeout = DEFAULT_OPEN_TIMEOUT) {
     this.#assertAuthenticated('inviteGuest');
+    requireArgs('inviteGuest', { sessionId, ttl });
     await this.#transport.sendControl(guestInviteMsg({ sessionId, ttl, permissions }));
     return this.#waitForMessage(
       [MSG.GUEST_INVITE],
@@ -1248,12 +1432,17 @@ export class WshClient {
    * Share a session for multi-attach.
    * @param {string} sessionId - Session to share
    * @param {string} [mode='read'] - Share mode
-   * @param {number} [ttl] - Share TTL in seconds
+   * @param {number} ttl - Share lifetime in seconds. Not optional,
+   *   despite its position after a defaulted parameter:
+   *   `ShareSession.ttl` is a required wire field, and there is no
+   *   sensible default lifetime for a share link to invent on the
+   *   caller's behalf.
    * @param {number} [timeout=10000]
    * @returns {Promise<object>} Share response with share_id
    */
   async shareSession(sessionId, mode = 'read', ttl, timeout = DEFAULT_OPEN_TIMEOUT) {
     this.#assertAuthenticated('shareSession');
+    requireArgs('shareSession', { sessionId, ttl });
     await this.#transport.sendControl(shareSessionMsg({ sessionId, mode, ttl }));
     return this.#waitForMessage(
       [MSG.SHARE_SESSION],
@@ -1301,6 +1490,7 @@ export class WshClient {
    */
   async setRateControl(sessionId, maxBytesPerSec, policy = 'pause') {
     this.#assertAuthenticated('setRateControl');
+    requireArgs('setRateControl', { sessionId, maxBytesPerSec });
     await this.#transport.sendControl(rateControlMsg({ sessionId, maxBytesPerSec, policy }));
   }
 
@@ -1340,6 +1530,7 @@ export class WshClient {
    */
   async copilotAttach(sessionId, model, contextWindow) {
     this.#assertAuthenticated('copilotAttach');
+    requireArgs('copilotAttach', { sessionId, model });
     await this.#transport.sendControl(
       copilotAttachMsg({ sessionId, model, contextWindow })
     );
@@ -1401,6 +1592,30 @@ export class WshClient {
     this.#assertAuthenticated('initiateE2E');
     const wantHybrid = algorithm === 'X25519+ML-KEM-768';
 
+    // Register the waiter before ANY await, key generation included.
+    //
+    // Two peers establishing E2E both call this at once, and #handleControl
+    // DROPS a KEY_EXCHANGE that no waiter is listening for. Whichever side
+    // finishes its local key generation first sends its round-1 message into
+    // the other's blind window -- the other is still inside generateKey /
+    // exportKey below and has nothing registered. That message is gone, and
+    // the side that lost it then waits the full timeout for something the
+    // peer has already sent and will not send again.
+    //
+    // Registering after the crypto, or merely before sendControl, leaves the
+    // window open: measured at ~10% of runs before, and still ~5% with the
+    // waiter registered after key generation. The only safe point is here,
+    // before this function yields for the first time.
+    const peerMsgPromise = this.#waitForMessage(
+      [MSG.KEY_EXCHANGE],
+      timeout,
+      'Timed out waiting for peer key exchange'
+    );
+    // Mark it handled so a failure in the key generation or send below does
+    // not surface as an unhandled rejection when this waiter later times
+    // out. Awaiting the promise still throws normally.
+    peerMsgPromise.catch(() => {});
+
     // Generate ephemeral X25519 key pair (and, for hybrid, a fresh
     // ML-KEM-768 key pair too).
     const ephemeral = await crypto.subtle.generateKey(
@@ -1417,11 +1632,30 @@ export class WshClient {
       keyExchangeMsg({ algorithm, publicKey: localPub, sessionId, kemPublicKey: localKem?.publicKey })
     );
 
-    const peerMsg = await this.#waitForMessage(
-      [MSG.KEY_EXCHANGE],
-      timeout,
-      'Timed out waiting for peer key exchange'
-    );
+    const peerMsg = await peerMsgPromise;
+
+    // Round 2 has the same shape as round 1, so it needs the same treatment.
+    // Whether we encapsulate or decapsulate is decided entirely by data
+    // already in hand, so decide it now and register the ciphertext waiter
+    // BEFORE the derive below. Registering it inside the `else` branch, after
+    // importKey and deriveBits, let the peer's ciphertext arrive while this
+    // side was still deriving -- dropped, then a full-timeout wait for a
+    // message already sent. That surfaced as "Timed out waiting for peer
+    // ML-KEM-768 ciphertext", which retryOnKnownFlake retries and the test
+    // file attributes to a Node provider stall.
+    const hybridActive = wantHybrid && !!localKem && !!peerMsg.kem_public_key;
+    const isEncapsulator = hybridActive
+      && compareBytes(localPub, new Uint8Array(peerMsg.public_key)) < 0;
+
+    let ctMsgPromise = null;
+    if (hybridActive && !isEncapsulator) {
+      ctMsgPromise = this.#waitForMessage(
+        [MSG.KEY_EXCHANGE],
+        timeout,
+        'Timed out waiting for peer ML-KEM-768 ciphertext'
+      );
+      ctMsgPromise.catch(() => {});
+    }
 
     // Import peer's public key and derive the classical shared secret.
     const peerKey = await crypto.subtle.importKey(
@@ -1437,12 +1671,10 @@ export class WshClient {
       256
     ));
 
-    const hybridActive = wantHybrid && !!localKem && !!peerMsg.kem_public_key;
     let combinedBits = sharedBits;
 
     if (hybridActive) {
       const peerKemPublicKey = new Uint8Array(peerMsg.kem_public_key);
-      const isEncapsulator = compareBytes(localPub, new Uint8Array(peerMsg.public_key)) < 0;
 
       let kemSharedSecret;
       if (isEncapsulator) {
@@ -1450,11 +1682,7 @@ export class WshClient {
         kemSharedSecret = sharedSecret;
         await this.#transport.sendControl(keyExchangeMsg({ algorithm, sessionId, kemCiphertext: ciphertext }));
       } else {
-        const ctMsg = await this.#waitForMessage(
-          [MSG.KEY_EXCHANGE],
-          timeout,
-          'Timed out waiting for peer ML-KEM-768 ciphertext'
-        );
+        const ctMsg = await ctMsgPromise;
         kemSharedSecret = await mlKemDecapsulate(localKem.secretKeySeed, new Uint8Array(ctMsg.kem_ciphertext));
       }
 
@@ -1511,6 +1739,45 @@ export class WshClient {
   /** Rename a remote file or directory. */
   async fileRename(oldPath, newPath, timeout) { return this.fileOperation('rename', oldPath, {}, timeout); }
 
+  // ── Authorized-key management (wsh #59) ───────────────────────────
+
+  /**
+   * Install a raw 32-byte Ed25519 public key into the remote host's
+   * ~/.wsh/authorized_keys via the AuthorizedKeyAdd protocol message.
+   *
+   * Replaces `wsh copy-id`'s CLI-only, shell-command-built approach
+   * (`crates/wsh-cli/src/commands/copy_id.rs`) with a real protocol
+   * message every implementation can call -- including this one, the
+   * browser SDK, which previously had no way to install a key at all
+   * (no shell channel to build a command string for). See copy_id.rs's
+   * doc comment for the full security reasoning: an authenticated
+   * connection already has unrestricted exec/file access to this exact
+   * file, so this adds no new privilege boundary.
+   *
+   * Idempotent: installing an already-present key resolves
+   * `{ added: false }` rather than duplicating the line or erroring.
+   *
+   * @param {Uint8Array} publicKeyRaw - Raw 32-byte Ed25519 public key
+   * @param {string} [comment] - Trailing comment for the authorized_keys line
+   * @param {number} [timeout=10000]
+   * @returns {Promise<{ added: boolean }>}
+   */
+  async addAuthorizedKey(publicKeyRaw, comment, timeout = DEFAULT_OPEN_TIMEOUT) {
+    this.#assertAuthenticated('addAuthorizedKey');
+    await this.#transport.sendControl(
+      authorizedKeyAddMsg({ publicKey: publicKeyRaw, comment })
+    );
+    const result = await this.#waitForMessage(
+      [MSG.AUTHORIZED_KEY_RESULT],
+      timeout,
+      'Timed out waiting for authorized-key-add result'
+    );
+    if (!result.success) {
+      throw new Error(result.error_message || 'key installation refused');
+    }
+    return { added: !!result.added };
+  }
+
   // ── Policy Engine ─────────────────────────────────────────────────
 
   /**
@@ -1542,6 +1809,7 @@ export class WshClient {
    */
   async updatePolicy(policyId, rules, version) {
     this.#assertAuthenticated('updatePolicy');
+    requireArgs('updatePolicy', { policyId, rules, version });
     await this.#transport.sendControl(
       policyUpdateMsg({ policyId, rules, version })
     );
@@ -1554,17 +1822,23 @@ export class WshClient {
    *
    * @param {string} url
    * @param {'wt'|'ws'|'auto'} [hint]
+   * @param {object} [webTransport] - Options for the `WebTransport`
+   *   constructor, applied only to a `wt` attempt (see
+   *   `WebTransportTransport`). The `ws` rung of the ladder ignores them:
+   *   a `serverCertificateHashes` pin has no WebSocket equivalent, so a
+   *   `wss:` fallback against that same self-signed certificate will
+   *   still fail the usual certificate-authority check.
    * @returns {Promise<import('./transport.mjs').WshTransport>}
    * @private
    */
-  async #connectTransport(url, hint) {
+  async #connectTransport(url, hint, webTransport) {
     const attempts = this.#buildTransportAttempts(url, hint);
     const errors = [];
 
     for (const attempt of attempts) {
       const transport = this.#createTransport(attempt.kind);
       try {
-        await transport.connect(attempt.url);
+        await transport.connect(attempt.url, attempt.kind === 'wt' ? webTransport : undefined);
         this.#attachTransportHandlers(transport);
         return transport;
       } catch (err) {
@@ -1606,6 +1880,16 @@ export class WshClient {
     if (hint === 'ws') {
       return [{ kind: 'ws', url }];
     }
+    if (hint !== undefined && hint !== null && hint !== 'auto') {
+      // Anything else is a typo, and silently treating it as 'auto' is
+      // the worst available answer: `transport: 'webtransport'` would
+      // quietly fall back to WebSocket, dropping any
+      // `webTransport.serverCertificateHashes` pin along with it and
+      // connecting over a transport the caller explicitly tried to avoid.
+      throw new Error(
+        `Unknown transport hint: ${JSON.stringify(hint)} (expected 'wt', 'ws', or 'auto')`
+      );
+    }
     if (/^wss?:\/\//i.test(url)) {
       return [{ kind: 'ws', url }];
     }
@@ -1804,6 +2088,13 @@ export class WshClient {
       return;
     }
 
+    // Observers registered via addControlListener() see the message here —
+    // past the RelayForward trust gate above (so an untrusted peer's
+    // message never reaches one, and a trusted one arrives unwrapped) and
+    // before this client's own dispatch, so a helper waiting on a reply
+    // cannot miss it to an ordering accident.
+    this.#dispatchControlListeners(msg);
+
     // OPEN_OK/OPEN_FAIL: handled as a dedicated case (not the generic
     // waiter mechanism below) so the WshSession gets constructed and
     // registered in #sessions synchronously, in the same dispatch step as
@@ -1864,10 +2155,13 @@ export class WshClient {
     }
 
     // First, check if any waiters are listening for this message type.
+    // A waiter carrying a `match` predicate only takes messages it claims,
+    // so the queue is scanned rather than shifted blindly.
     if (this.#waiters.has(type)) {
       const queue = this.#waiters.get(type);
-      if (queue.length > 0) {
-        const waiter = queue.shift();
+      for (let i = 0; i < queue.length; i++) {
+        if (queue[i].match && !queue[i].match(msg)) continue;
+        const waiter = queue.splice(i, 1)[0];
         if (queue.length === 0) this.#waiters.delete(type);
         clearTimeout(waiter.timer);
         waiter.resolve(msg);
@@ -1879,13 +2173,13 @@ export class WshClient {
     for (const [key, queue] of this.#waiters) {
       if (typeof key === 'string' && key.startsWith('multi:')) {
         for (let i = 0; i < queue.length; i++) {
-          if (queue[i].types?.includes(type)) {
-            const waiter = queue.splice(i, 1)[0];
-            if (queue.length === 0) this.#waiters.delete(key);
-            clearTimeout(waiter.timer);
-            waiter.resolve(msg);
-            return;
-          }
+          if (!queue[i].types?.includes(type)) continue;
+          if (queue[i].match && !queue[i].match(msg)) continue;
+          const waiter = queue.splice(i, 1)[0];
+          if (queue.length === 0) this.#waiters.delete(key);
+          clearTimeout(waiter.timer);
+          waiter.resolve(msg);
+          return;
         }
       }
     }
@@ -2063,7 +2357,7 @@ export class WshClient {
    * @returns {Promise<object>}
    * @private
    */
-  #waitForMessage(types, timeout, timeoutMessage) {
+  #waitForMessage(types, timeout, timeoutMessage, match) {
     const typeArr = Array.isArray(types) ? types : [types];
 
     return new Promise((resolve, reject) => {
@@ -2073,7 +2367,10 @@ export class WshClient {
         reject(new Error(timeoutMessage));
       }, timeout);
 
-      const waiter = { resolve, reject, timer, types: typeArr };
+      // `match` lets a waiter claim only the reply that belongs to it --
+      // correlation, rather than "first waiter of this type wins". Waiters
+      // without one match on type alone, as before.
+      const waiter = { resolve, reject, timer, types: typeArr, match };
 
       // For multi-type waiting, use a synthetic key.
       const key = typeArr.length === 1
@@ -2138,12 +2435,37 @@ export class WshClient {
         return;
       }
 
+      /*
+       * Act on the pong, rather than merely recording it.
+       *
+       * `#lastPong` was written on every PONG and read nowhere -- `grep -arn
+       * lastPong src/` returned the declaration and two assignments and no
+       * third line. So the keepalive proved the connection was alive when it
+       * was, and said nothing when it stopped being: pings went out forever
+       * at every peer, dead or not, and a caller waiting for data waited
+       * without a reason.
+       *
+       * Compared against a deadline rather than armed as a timer, which
+       * matters: a timer re-armed on each tick is cleared before it can fire
+       * whenever the interval is shorter than the timeout, and is then
+       * incapable of firing at all. (browsermesh#32 shipped exactly that.) A
+       * timestamp comparison has no such failure mode.
+       */
+      if (this.#lastPong !== null && Date.now() - this.#lastPong > this.#pongTimeoutMs) {
+        const silentFor = Date.now() - this.#lastPong;
+        this.#stopPing();
+        this.#emitError(
+          new Error(`wsh: peer stopped answering keepalive pings ${silentFor}ms ago`)
+        );
+        return;
+      }
+
       this.#transport?.sendControl(
         pingMsg({ id: ++this.#pingId })
       ).catch((err) => {
         console.warn('[wsh:client] Failed to send ping:', err.message);
       });
-    }, DEFAULT_PING_INTERVAL);
+    }, this.#pingIntervalMs);
 
     // Don't let the ping timer prevent Node.js/Deno from exiting.
     if (typeof this.#pingTimer === 'object' && this.#pingTimer.unref) {
@@ -2199,6 +2521,28 @@ export class WshClient {
     }
   }
 
+  /**
+   * Hand a control message to every addControlListener() observer.
+   *
+   * Iterates a copy, so a listener that deregisters itself (the normal
+   * case — a one-shot reply waiter) does not perturb the iteration, and
+   * isolates throws so one bad observer cannot break the client's own
+   * dispatch of the same message.
+   *
+   * @param {object} msg
+   * @private
+   */
+  #dispatchControlListeners(msg) {
+    if (this.#controlListeners.size === 0) return;
+    for (const fn of [...this.#controlListeners]) {
+      try {
+        fn(msg);
+      } catch (err) {
+        console.error('[wsh:client] control listener error:', err);
+      }
+    }
+  }
+
   /**
    * Emit an error through the callback.
    * @param {Error} err