@unicitylabs/sphere-sdk 0.12.0-dev.1 → 0.13.0

package/dist/connect/index.js

@@ -340,7 +340,7 @@ var HOST_READY_TIMEOUT = 3e4;
 
 // connect/protocol.ts
 var SPHERE_CONNECT_NAMESPACE = "sphere-connect";
-var SPHERE_CONNECT_VERSION = "2.0";
+var SPHERE_CONNECT_VERSION = "2.1";
 var RPC_METHODS = {
   GET_IDENTITY: "sphere_getIdentity",
   GET_BALANCE: "sphere_getBalance",
@@ -394,19 +394,60 @@ var ERROR_CODES = {
   // Connect MAJOR mismatch (incompatible era)
   INCOMPATIBLE_NETWORK: 4008,
   // dApp targets a different network than the wallet
+  // Wallet locked; THE SESSION IS STILL ALIVE. A QUERY may be retried after wallet:unlocked.
+  // An INTENT already delegated to the wallet is NEVER answered with this code — it gets
+  // INTENT_OUTCOME_UNKNOWN (4201) instead, because a retry could double-spend.
+  WALLET_LOCKED: 4009,
   INSUFFICIENT_BALANCE: 4100,
   INVALID_RECIPIENT: 4101,
   TRANSFER_FAILED: 4102,
-  INTENT_CANCELLED: 4200
+  INTENT_CANCELLED: 4200,
+  /**
+   * The intent was DELEGATED to the wallet and the host lost track of the answer — a host
+   * deadline fired, or the wallet locked / logged out mid-flight. **The outcome is UNKNOWN:
+   * the money may or may not have moved.**
+   *
+   * A dApp MUST NOT retry on this code. Reconcile out of band (poll the recipient, the
+   * aggregator, or your own backend) and only then decide.
+   *
+   * This code exists because every other answer would be a lie. `INTENT_CANCELLED` (4200)
+   * asserts the user declined and nothing happened; `WALLET_LOCKED` (4009) invites a retry
+   * after the unlock. Sending either for an intent the wallet had already submitted is how a
+   * paid-but-not-credited order — and then a double spend on retry — happens.
+   */
+  INTENT_OUTCOME_UNKNOWN: 4201
 };
 var WALLET_EVENTS = {
-  /** Wallet locked or user logged out. dApp shows locked state and waits for unlock.
-   *  Pushed automatically by ConnectHost — no sphere_subscribe needed. */
+  /** Wallet is LOCKED — the session is STILL ALIVE. Requests are answered
+   *  WALLET_LOCKED (4009) until `wallet:unlocked`. The dApp must NOT disconnect,
+   *  must NOT clear its sessionId, and must NOT re-handshake.
+   *  Payload: {@link WalletLockedPayload}. Pushed by ConnectHost.setLocked() and
+   *  immediately after a handshake response carrying `locked: true`. */
   LOCKED: "wallet:locked",
+  /** Wallet was unlocked — the SAME session continues: no re-handshake, no re-approval,
+   *  no re-subscribe (the host re-arms the dApp's subscriptions before pushing this).
+   *  Payload: {@link WalletUnlockedPayload} — carries the CURRENT identity, which may
+   *  differ from the one the dApp connected with. Pushed by ConnectHost.updateSphere()
+   *  on the locked -> live edge only. */
+  UNLOCKED: "wallet:unlocked",
+  /** The session is GONE (logout, wallet deleted, dApp sphere_disconnect, expiry seen at
+   *  unlock, a different seed behind the lock screen, host destroy).
+   *  The dApp must clear its session and re-handshake to continue. Unlocking does not cure it.
+   *  Payload: {@link WalletDisconnectedPayload}. Pushed by ConnectHost.revokeSession(). */
+  DISCONNECTED: "wallet:disconnected",
   /** Active wallet address changed. dApp should update displayed identity.
    *  Pushed automatically by ConnectHost — no sphere_subscribe needed. */
   IDENTITY_CHANGED: "identity:changed"
 };
+var AUTO_PUSHED_EVENTS = [
+  WALLET_EVENTS.LOCKED,
+  WALLET_EVENTS.UNLOCKED,
+  WALLET_EVENTS.DISCONNECTED,
+  WALLET_EVENTS.IDENTITY_CHANGED
+];
+function isAutoPushedEvent(event) {
+  return AUTO_PUSHED_EVENTS.includes(event);
+}
 function isSphereConnectMessage(msg) {
   if (!msg || typeof msg !== "object") return false;
   const m = msg;
@@ -465,7 +506,7 @@ function checkCompatibility(input) {
 }
 
 // connect/version.ts
-var SDK_VERSION = "0.12.0-dev.1";
+var SDK_VERSION = "0.13.0";
 
 // connect/permissions.ts
 var PERMISSION_SCOPES = {
@@ -538,11 +579,188 @@ function validatePermissions(permissions) {
   return permissions.every((p) => validScopes.has(p));
 }
 
+// connect/host/host-state.ts
+var WALLET_LOCKED_MESSAGE = "Wallet is locked";
+var INTERNAL_ERROR_MESSAGE = "Internal wallet error";
+var INTENT_UNKNOWN_MESSAGE = "Intent outcome unknown \u2014 do not retry; reconcile before acting";
+var NOT_CONNECTED_MESSAGE = "Not connected";
+var VALID_WALLET_TRANSITIONS = {
+  live: ["locked", "unavailable"],
+  locked: ["live", "unavailable"],
+  unavailable: ["live", "locked"]
+};
+function isValidWalletTransition(from, to) {
+  return VALID_WALLET_TRANSITIONS[from].includes(to);
+}
+function assertWalletTransition(from, to) {
+  if (!isValidWalletTransition(from, to)) {
+    throw new SphereError(`Invalid wallet state transition: ${from} -> ${to}`, "VALIDATION_ERROR");
+  }
+}
+var LOCKED_ALLOWLIST = /* @__PURE__ */ new Set([
+  RPC_METHODS.GET_IDENTITY,
+  RPC_METHODS.SUBSCRIBE,
+  RPC_METHODS.UNSUBSCRIBE,
+  RPC_METHODS.DISCONNECT
+]);
+var REFUSE_NOT_CONNECTED = {
+  kind: "refuse",
+  error: { code: ERROR_CODES.NOT_CONNECTED, message: NOT_CONNECTED_MESSAGE }
+};
+var REFUSE_LOCKED = {
+  kind: "refuse",
+  error: {
+    code: ERROR_CODES.WALLET_LOCKED,
+    message: WALLET_LOCKED_MESSAGE,
+    data: { reason: "locked" }
+  }
+};
+function gate(walletState, hasActiveSession, requestKind, name) {
+  if (walletState === "unavailable") return REFUSE_NOT_CONNECTED;
+  if (requestKind === "handshake") {
+    return walletState === "locked" ? { kind: "serve-from-snapshot" } : { kind: "serve" };
+  }
+  if (!hasActiveSession) return REFUSE_NOT_CONNECTED;
+  if (walletState === "live") return { kind: "serve" };
+  if (requestKind === "query" && LOCKED_ALLOWLIST.has(name)) {
+    return name === RPC_METHODS.GET_IDENTITY ? { kind: "serve-from-snapshot" } : { kind: "serve" };
+  }
+  return REFUSE_LOCKED;
+}
+
+// connect/host/WalletSnapshot.ts
+var EMPTY_WALLET_SNAPSHOT = Object.freeze({ capturedAt: 0 });
+function buildWalletSnapshot(sphere) {
+  if (!sphere) return EMPTY_WALLET_SNAPSHOT;
+  const id = sphere.identity;
+  return Object.freeze({
+    ...typeof sphere.networkId === "number" ? { networkId: sphere.networkId } : {},
+    ...id ? {
+      identity: Object.freeze({
+        chainPubkey: id.chainPubkey,
+        directAddress: id.directAddress,
+        nametag: id.nametag
+      })
+    } : {},
+    capturedAt: Date.now()
+  });
+}
+
+// connect/host/InFlightRegistry.ts
+var InFlightRegistry = class {
+  slots = /* @__PURE__ */ new Map();
+  onExpire;
+  constructor(options) {
+    this.onExpire = options.onExpire;
+  }
+  get size() {
+    return this.slots.size;
+  }
+  has(id) {
+    return this.slots.has(id);
+  }
+  /** Register BEFORE the first await and arm the timer AT INSERTION TIME.
+   *  A duplicate id is a protocol violation: warn and reuse the existing entry, so a
+   *  hostile or buggy client cannot arm unbounded timers by replaying one id. */
+  add(id, kind, deadlineMs) {
+    const existing = this.slots.get(id);
+    if (existing) {
+      logger.warn("InFlightRegistry", `Duplicate request id, reusing entry: ${id}`);
+      return existing.entry;
+    }
+    const entry = {
+      id,
+      kind,
+      deadline: Date.now() + deadlineMs,
+      controller: new AbortController()
+    };
+    const timer = setTimeout(() => {
+      this.slots.delete(id);
+      entry.controller.abort();
+      this.onExpire(entry);
+    }, deadlineMs);
+    this.slots.set(id, { entry, timer });
+    return entry;
+  }
+  /** Remove + abort BEFORE the caller sends. Returns the entry, or null when it was
+   *  already settled — in which case the caller MUST send nothing. */
+  settle(id) {
+    const slot = this.slots.get(id);
+    if (!slot) {
+      logger.warn("InFlightRegistry", `Already settled, dropping second answer: ${id}`);
+      return null;
+    }
+    this.slots.delete(id);
+    clearTimeout(slot.timer);
+    slot.entry.controller.abort();
+    return slot.entry;
+  }
+  /** Settle every entry, in insertion order, aborting each. The caller sends one frame per
+   *  returned entry. Used by setLocked (4009), revokeSession (4001), destroy (4001). */
+  settleAll() {
+    const out = [];
+    for (const slot of this.slots.values()) {
+      clearTimeout(slot.timer);
+      slot.entry.controller.abort();
+      out.push(slot.entry);
+    }
+    this.slots.clear();
+    return out;
+  }
+  /** Clear all timers WITHOUT invoking onExpire. Host teardown only. */
+  destroy() {
+    for (const slot of this.slots.values()) clearTimeout(slot.timer);
+    this.slots.clear();
+  }
+};
+
 // connect/host/ConnectHost.ts
 var DEFAULT_SESSION_TTL_MS = 864e5;
 var DEFAULT_MAX_RPS = 20;
+var CHANNEL_ONLY_CODES = /* @__PURE__ */ new Set([
+  ERROR_CODES.WALLET_LOCKED,
+  ERROR_CODES.NOT_CONNECTED
+]);
+var DEFAULT_REQUEST_DEADLINE_MS = 25e3;
+var DEFAULT_INTENT_DEADLINE_MS = 18e4;
+var DEFAULT_HANDSHAKE_DEADLINE_MS = 12e4;
+function withDeadline(promise, ms, fallback) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => resolve(fallback()), ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
 var ConnectHost = class {
+  /** Null whenever _walletState is 'locked' or 'unavailable' (invariant B). */
   sphere;
+  /** The wallet-binding axis. Underscored because `walletState` is the public getter.
+   *  ORTHOGONAL to `session` — a locked wallet keeps its session, a live wallet may have
+   *  none. Written only by the WALLET (setLocked / setUnavailable / updateSphere / destroy);
+   *  `session` is written by the dApp handshake, sphere_disconnect and expiry. */
+  _walletState;
+  /** Immutable public facts about the current binding. Refreshed on every bind
+   *  (constructor, updateSphere); FROZEN by setLocked(); EMPTY after setUnavailable() and
+   *  destroy(). Never read from Sphere while locked — that is a property of the types
+   *  here, not of code review. */
+  snapshot;
+  /** Subscription KEYS captured by setLocked() BEFORE the unsub closures are detached.
+   *  Sphere.destroy() kills those closures, so the keys are the only recoverable
+   *  information. Excludes 'identity:changed' (autoSubscribeIdentityChanged re-arms it).
+   *  A Set, not an array: handleSubscribe may be called twice for the same key while
+   *  locked. */
+  suspendedSubscriptions = /* @__PURE__ */ new Set();
+  /** Every accepted id, with its own host-side timer. The single convergence point for
+   *  lock / revoke / unavailable / destroy / deadline. */
+  inFlight;
   transport;
   config;
   session = null;
@@ -557,11 +775,33 @@ var ConnectHost = class {
   rateLimitResetAt = 0;
   unsubscribeTransport = null;
   constructor(config) {
-    this.sphere = config.sphere;
     this.transport = config.transport;
     this.config = config;
+    this._walletState = config.initialWalletState ?? "live";
+    this.sphere = config.sphere ?? null;
+    if (this._walletState === "live" && !this.sphere) {
+      logger.warn(
+        "ConnectHost",
+        'Constructed live with sphere === null; coercing to unavailable. Pass initialWalletState: "locked" when the wallet is locked at construction time.'
+      );
+      this._walletState = "unavailable";
+    }
+    if (this._walletState !== "live") this.sphere = null;
+    this.snapshot = buildWalletSnapshot(this.sphere);
+    this.inFlight = new InFlightRegistry({ onExpire: (e) => this.settleExpired(e) });
     this.unsubscribeTransport = this.transport.onMessage(this.handleMessage.bind(this));
   }
+  /** The wallet-binding axis. Orthogonal to {@link getSession}. Read-only —
+   *  transitions go through setLocked() / setUnavailable() / updateSphere(). */
+  get walletState() {
+    return this._walletState;
+  }
+  /** Both axes in one read, for UI that must render "connected AND locked".
+   *  Required by the wallet's ConnectPage, which today renders a green pulsing
+   *  "Connected to {dapp}" with no regard for lock state. */
+  getState() {
+    return { walletState: this._walletState, session: this.session };
+  }
   /** Get current active session */
   getSession() {
     return this.session;
@@ -575,52 +815,212 @@ var ConnectHost = class {
     this.autoApprovedIntents.delete(action);
   }
   /**
-   * Update the Sphere instance (e.g. user switched address — new Sphere created).
-   * Re-subscribes auto-push events and notifies connected dApp of the new identity.
+   * Bind a (new) Sphere instance. This is BOTH the re-arm path after setLocked() /
+   * setUnavailable() AND the existing address-switch path in a live wallet.
+   *
+   * From 'live' (address switch): today's behaviour, unchanged — re-arm identity:changed,
+   *   push identity:changed. NO identity comparison: an address switch is legal.
+   *
+   * On the 'locked' -> 'live' edge, in this order:
+   *   1. compare snapshot.identity?.chainPubkey with the new Sphere's chainPubkey.
+   *      MISMATCH => revokeSession() (which pushes wallet:disconnected) and RETURN.
+   *      Never wallet:unlocked. This is the "Forgot password -> restore recovery phrase
+   *      installed a different seed behind an origin-keyed approval" guard.
+   *   2. session.expiresAt passed => revokeSession() and RETURN. A wallet:unlocked into a
+   *      dead session would make the dApp's next request answer SESSION_EXPIRED 4004.
+   *   3. rebind, refresh the snapshot, go live, re-arm identity:changed, replay every
+   *      suspended sphere_subscribe key, and ONLY THEN push wallet:unlocked with the
+   *      CURRENT identity. Re-arm BEFORE push, so a dApp reacting synchronously cannot
+   *      race its own event streams.
+   *
+   * From 'unavailable' -> 'live': rebind + refresh the snapshot, no identity check
+   *   (nothing was bound to compare against) and no event (the session is already null).
    */
   updateSphere(newSphere) {
-    this.sphere = newSphere;
-    const existing = this.eventSubscriptions.get(WALLET_EVENTS.IDENTITY_CHANGED);
-    if (existing) {
-      existing();
-      this.eventSubscriptions.delete(WALLET_EVENTS.IDENTITY_CHANGED);
+    const wasLocked = this._walletState === "locked";
+    const next = newSphere ?? null;
+    if (!next) {
+      if (this._walletState === "locked") {
+        logger.warn("ConnectHost", "updateSphere(null) while locked \u2014 staying locked");
+        return;
+      }
+      logger.warn("ConnectHost", "updateSphere(null) \u2014 treating as a non-lock loss of Sphere");
+      this.setUnavailable();
+      return;
     }
-    if (this.session?.active) {
-      this.autoSubscribeIdentityChanged();
-      const identity = this.getPublicIdentity();
-      if (identity) {
-        this.pushClientEvent(WALLET_EVENTS.IDENTITY_CHANGED, identity);
+    if (this._walletState === "live") {
+      this.sphere = next;
+      this.snapshot = buildWalletSnapshot(next);
+      const existing = this.eventSubscriptions.get(WALLET_EVENTS.IDENTITY_CHANGED);
+      if (existing) {
+        existing();
+        this.eventSubscriptions.delete(WALLET_EVENTS.IDENTITY_CHANGED);
+      }
+      if (this.session?.active) {
+        this.autoSubscribeIdentityChanged();
+        const identity2 = this.getPublicIdentity();
+        if (identity2) {
+          this.pushClientEvent(WALLET_EVENTS.IDENTITY_CHANGED, identity2);
+        }
+      }
+      return;
+    }
+    if (wasLocked && this.session?.active) {
+      const before = this.snapshot.identity?.chainPubkey ?? null;
+      const after = next.identity?.chainPubkey ?? null;
+      const netBefore = this.snapshot.networkId ?? null;
+      const netAfter = next.networkId ?? null;
+      if (before !== after || netBefore !== netAfter) {
+        logger.warn(
+          "ConnectHost",
+          `Wallet behind the lock screen is not the one this session was approved for \u2014 revoking instead of unlocking (origin=${this.config.origin ?? "unverified"})`
+        );
+        assertWalletTransition(this._walletState, "live");
+        this._walletState = "live";
+        this.sphere = next;
+        this.snapshot = buildWalletSnapshot(next);
+        this.revokeSession();
+        return;
+      }
+      if (this.session.expiresAt > 0 && Date.now() > this.session.expiresAt) {
+        logger.warn(
+          "ConnectHost",
+          `Session expired while locked \u2014 re-handshake required (origin=${this.config.origin ?? "unverified"})`
+        );
+        assertWalletTransition(this._walletState, "live");
+        this._walletState = "live";
+        this.sphere = next;
+        this.snapshot = buildWalletSnapshot(next);
+        this.revokeSession();
+        return;
+      }
+    }
+    assertWalletTransition(this._walletState, "live");
+    this.sphere = next;
+    this.snapshot = buildWalletSnapshot(next);
+    this._walletState = "live";
+    if (!this.session?.active) {
+      this.suspendedSubscriptions.clear();
+      return;
+    }
+    this.autoSubscribeIdentityChanged();
+    const suspended = [...this.suspendedSubscriptions];
+    this.suspendedSubscriptions.clear();
+    for (const eventName of suspended) {
+      try {
+        this.handleSubscribe(eventName);
+      } catch (err) {
+        logger.warn("ConnectHost", `Re-subscribe failed after unlock: ${eventName}`, err);
       }
     }
+    logger.debug(
+      "ConnectHost",
+      `Wallet unlocked \u2014 re-armed ${suspended.length} subscription(s) (origin=${this.config.origin ?? "unverified"})`
+    );
+    this.pushClientEvent(WALLET_EVENTS.UNLOCKED, {
+      identity: this.getPublicIdentity()
+    });
+    const identity = this.getPublicIdentity();
+    if (identity) this.pushClientEvent(WALLET_EVENTS.IDENTITY_CHANGED, identity);
   }
-  /** Revoke the current session */
+  /**
+   * The wallet locked (manual lock, idle auto-lock, cross-tab broadcast, cold start).
+   * The session is PRESERVED — a lock is a state, not a teardown. Every request outside
+   * the locked allow-list is answered WALLET_LOCKED (4009) until updateSphere().
+   *
+   * Idempotent: a second call is a no-op and pushes nothing. Required, because
+   * SphereProvider.lock(), ConnectPage's `sphere → null` effect and broadcastLock()'s
+   * same-tab loopback can all fire it for one user action.
+   *
+   * ORDERING CONTRACT: call this BEFORE sphere.destroy(). The host drops its Sphere
+   * reference here; destroying first leaves in-flight requests reading a dead instance
+   * (-32603, or `undefined` returned AS SUCCESS from sphere_getIdentity).
+   */
+  setLocked() {
+    if (this._walletState === "locked") return;
+    assertWalletTransition(this._walletState, "locked");
+    this.snapshot = buildWalletSnapshot(this.sphere);
+    this._walletState = "locked";
+    logger.debug(
+      "ConnectHost",
+      `Wallet locked \u2014 session preserved (origin=${this.config.origin ?? "unverified"}, session=${this.session?.id ?? "none"})`
+    );
+    if (this.session?.active) {
+      this.pushClientEvent(WALLET_EVENTS.LOCKED, {});
+    }
+    for (const key of this.eventSubscriptions.keys()) {
+      if (key === WALLET_EVENTS.IDENTITY_CHANGED) continue;
+      this.suspendedSubscriptions.add(key);
+    }
+    this.cleanupEventSubscriptions();
+    this.autoApprovedIntents.clear();
+    this.settleInFlight(ERROR_CODES.WALLET_LOCKED, WALLET_LOCKED_MESSAGE, { reason: "locked" });
+    this.sphere = null;
+  }
+  /**
+   * The Sphere instance is gone for a NON-LOCK reason (a generic init failure leaves
+   * `sphere === null, isLocked === false` in the wallet).
+   * This is a DEAD END: unlocking does not cure it, so it revokes the session and pushes
+   * wallet:disconnected rather than promising an unlock that cannot help.
+   * Subsequent requests answer NOT_CONNECTED (4001); handshakes get the empty refusal
+   * WITHOUT dereferencing a null Sphere.
+   *
+   * Idempotent. Pushes no 'wallet:unavailable' — there is no such event.
+   */
+  setUnavailable() {
+    if (this._walletState === "unavailable") return;
+    assertWalletTransition(this._walletState, "unavailable");
+    this._walletState = "unavailable";
+    logger.warn(
+      "ConnectHost",
+      `Sphere unavailable (non-lock) \u2014 session revoked (origin=${this.config.origin ?? "unverified"})`
+    );
+    this.snapshot = EMPTY_WALLET_SNAPSHOT;
+    this.suspendedSubscriptions.clear();
+    this.revokeSession();
+    this.sphere = null;
+  }
+  /**
+   * Destroy the SESSION (logout, wallet deleted, dApp sphere_disconnect, popup
+   * beforeunload, expiry, identity mismatch at unlock). Pushes wallet:disconnected BEFORE
+   * tearing down, so the dApp stops believing it is connected instead of finding out at
+   * its next 4001.
+   *
+   * This is the TEARDOWN verb. For a lock use setLocked() — a lock never destroys the
+   * session. revokeSession() does NOT touch walletState: the two axes are orthogonal.
+   */
   revokeSession() {
     if (this.session) {
+      logger.debug(
+        "ConnectHost",
+        `Session revoked (origin=${this.config.origin ?? "unverified"}, session=${this.session.id})`
+      );
+      if (this.session.active) {
+        this.pushClientEvent(WALLET_EVENTS.DISCONNECTED, {});
+      }
       this.session.active = false;
       this.cleanupEventSubscriptions();
       this.autoApprovedIntents.clear();
       this.session = null;
       this.grantedPermissions.clear();
     }
+    this.suspendedSubscriptions.clear();
+    this.settleInFlight(ERROR_CODES.NOT_CONNECTED, NOT_CONNECTED_MESSAGE);
   }
-  /**
-   * Notify connected dApp that wallet is locked/logged out, then revoke session.
-   * Call this BEFORE destroy() when the wallet locks so the dApp gets a clean signal
-   * instead of receiving NOT_CONNECTED errors on the next request.
-   */
-  notifyWalletLocked() {
-    if (this.session?.active) {
-      this.pushClientEvent(WALLET_EVENTS.LOCKED, {});
-    }
-    this.revokeSession();
-  }
-  /** Destroy the host, clean up all resources */
+  /** Destroy the host, clean up all resources. Idempotent. */
   destroy() {
     this.revokeSession();
+    this.inFlight.destroy();
     if (this.unsubscribeTransport) {
       this.unsubscribeTransport();
       this.unsubscribeTransport = null;
     }
+    this.sphere = null;
+    this.snapshot = EMPTY_WALLET_SNAPSHOT;
+    if (this._walletState !== "unavailable") {
+      assertWalletTransition(this._walletState, "unavailable");
+      this._walletState = "unavailable";
+    }
   }
   // ===========================================================================
   // Message Handling
@@ -641,6 +1041,7 @@ var ConnectHost = class {
       }
     } catch (error) {
       logger.warn("ConnectHost", "Error handling message:", error);
+      this.sendUnhandledError(msg, error);
     }
   }
   // ===========================================================================
@@ -652,11 +1053,27 @@ var ConnectHost = class {
       this.sendHandshakeResponse([], void 0, void 0);
       return;
     }
+    if (this._walletState !== "live" && !this.snapshot.identity) {
+      this.sendHandshakeResponse([], void 0, void 0);
+      return;
+    }
+    if (!this.checkRateLimit()) {
+      logger.warn("ConnectHost", "Handshake rate-limited", { dapp: dapp.name });
+      this.sendHandshakeResponse([], void 0, void 0);
+      return;
+    }
+    const stateAtPrompt = this._walletState;
+    let locked = stateAtPrompt === "locked";
+    const handshakeDecision = gate(this._walletState, !!this.session?.active, "handshake", "handshake");
+    if (handshakeDecision.kind === "refuse") {
+      this.sendHandshakeResponse([], void 0, void 0);
+      return;
+    }
     const result = checkCompatibility({
       clientProtocol: msg.v,
       walletProtocol: SPHERE_CONNECT_VERSION,
       clientNetwork: msg.network,
-      walletNetworkId: this.sphere.networkId ?? -1,
+      walletNetworkId: this.snapshot.networkId ?? -1,
       minMinor: this.config.minMinorVersion,
       clientSdkVersion: msg.sdkVersion,
       minSdkVersion: this.config.minSdkVersion
@@ -668,7 +1085,7 @@ var ConnectHost = class {
         clientProtocol: msg.v,
         walletProtocol: SPHERE_CONNECT_VERSION,
         clientNetwork: msg.network ?? null,
-        walletNetwork: this.sphere.networkId ?? null
+        walletNetwork: this.snapshot.networkId ?? null
       });
       this.config.onConnectionRejected?.(dapp, result.error, !!msg.silent);
       this.sendHandshakeResponse([], void 0, void 0, result.error, msg.v);
@@ -676,17 +1093,44 @@ var ConnectHost = class {
     }
     const clientInfo = { protocolVersion: msg.v, network: msg.network, sdkVersion: msg.sdkVersion };
     if (msg.sessionId && this.session?.active && this.session.id === msg.sessionId) {
-      const identity2 = this.getPublicIdentity();
-      this.sendHandshakeResponse([...this.grantedPermissions], this.session.id, identity2);
+      const identity2 = locked ? this.snapshotIdentity() : this.getPublicIdentity();
+      this.sendHandshakeResponse(
+        [...this.grantedPermissions],
+        this.session.id,
+        identity2,
+        void 0,
+        void 0,
+        void 0,
+        locked ? true : void 0
+      );
+      if (locked) {
+        this.pushClientEvent(WALLET_EVENTS.LOCKED, {});
+        this.notifyLockedRequest("handshake", "handshake");
+      }
       return;
     }
     const requestedPermissions = msg.permissions;
-    const { approved, grantedPermissions } = await this.config.onConnectionRequest(
-      dapp,
-      requestedPermissions,
-      msg.silent,
-      clientInfo
+    const silent = msg.silent === true || locked;
+    const { approved, grantedPermissions } = await withDeadline(
+      Promise.resolve(
+        this.config.onConnectionRequest(dapp, requestedPermissions, silent, clientInfo)
+      ),
+      this.config.handshakeDeadlineMs ?? DEFAULT_HANDSHAKE_DEADLINE_MS,
+      () => {
+        logger.warn("ConnectHost", "Connection approval prompt timed out", { dapp: dapp.name });
+        return { approved: false, grantedPermissions: [] };
+      }
     );
+    const stateAfterPrompt = this._walletState;
+    if (stateAfterPrompt !== "live" && stateAfterPrompt !== stateAtPrompt) {
+      logger.warn(
+        "ConnectHost",
+        `Wallet left 'live' while the approval prompt was open \u2014 refusing the handshake instead of minting a session (state=${stateAfterPrompt}, origin=${this.config.origin ?? "unverified"})`
+      );
+      this.sendHandshakeResponse([], void 0, void 0);
+      return;
+    }
+    locked = stateAfterPrompt !== "live";
     if (!approved) {
       this.sendHandshakeResponse([], void 0, void 0);
       return;
@@ -703,14 +1147,23 @@ var ConnectHost = class {
       active: true
     };
     this.grantedPermissions = new Set(allPermissions);
-    this.autoSubscribeIdentityChanged();
-    const identity = this.getPublicIdentity();
-    this.sendHandshakeResponse(allPermissions, sessionId, identity);
+    if (!locked) this.autoSubscribeIdentityChanged();
+    const identity = locked ? this.snapshotIdentity() : this.getPublicIdentity();
+    this.sendHandshakeResponse(
+      allPermissions,
+      sessionId,
+      identity,
+      void 0,
+      void 0,
+      void 0,
+      locked ? true : void 0
+    );
+    if (locked) this.pushClientEvent(WALLET_EVENTS.LOCKED, {});
   }
   // `warning` is a forward-compatible deprecation-notice slot (see SphereHandshake.warning);
   // no call site emits one yet — reserved for the deprecation-window policy.
-  sendHandshakeResponse(permissions, sessionId, identity, error, echoV, warning) {
-    const network = typeof this.sphere.networkId === "number" ? { id: this.sphere.networkId } : void 0;
+  sendHandshakeResponse(permissions, sessionId, identity, error, echoV, warning, locked) {
+    const network = typeof this.snapshot.networkId === "number" ? { id: this.snapshot.networkId } : void 0;
     this.transport.send({
       ns: SPHERE_CONNECT_NAMESPACE,
       v: error && echoV ? echoV : SPHERE_CONNECT_VERSION,
@@ -722,7 +1175,8 @@ var ConnectHost = class {
       network,
       sdkVersion: SDK_VERSION,
       error,
-      warning
+      warning,
+      ...locked ? { locked: true } : {}
     });
   }
   // ===========================================================================
@@ -730,12 +1184,12 @@ var ConnectHost = class {
   // ===========================================================================
   async handleRpcRequest(msg) {
     if (!this.session?.active) {
-      this.sendError(msg.id, ERROR_CODES.NOT_CONNECTED, "Not connected");
+      this.sendError(msg.id, ERROR_CODES.NOT_CONNECTED, NOT_CONNECTED_MESSAGE);
       return;
     }
     if (this.session.expiresAt > 0 && Date.now() > this.session.expiresAt) {
-      this.revokeSession();
       this.sendError(msg.id, ERROR_CODES.SESSION_EXPIRED, "Session expired");
+      this.revokeSession();
       return;
     }
     if (!this.checkRateLimit()) {
@@ -744,22 +1198,50 @@ var ConnectHost = class {
     }
     if (msg.method === RPC_METHODS.DISCONNECT) {
       const disconnectedSession = this.session;
-      this.revokeSession();
       this.sendResult(msg.id, { disconnected: true });
+      this.revokeSession();
       if (disconnectedSession && this.config.onDisconnect) {
         Promise.resolve(this.config.onDisconnect(disconnectedSession)).catch((err) => logger.warn("Connect", "onDisconnect handler error", err));
       }
       return;
     }
+    const decision = gate(this._walletState, true, "query", msg.method);
+    if (decision.kind === "refuse") {
+      this.sendError(msg.id, decision.error.code, decision.error.message, decision.error.data);
+      if (decision.error.code === ERROR_CODES.WALLET_LOCKED) {
+        logger.debug("ConnectHost", `Refused query ${msg.method} \u2014 WALLET_LOCKED 4009 (origin=${this.config.origin ?? "unverified"})`);
+        this.notifyLockedRequest("query", msg.method);
+      }
+      return;
+    }
     if (!hasMethodPermission(this.grantedPermissions, msg.method)) {
       this.sendError(msg.id, ERROR_CODES.PERMISSION_DENIED, `Permission denied for ${msg.method}`);
       return;
     }
+    if (decision.kind === "serve-from-snapshot") {
+      const identity = this.snapshotIdentity();
+      if (!identity) {
+        this.sendError(msg.id, ERROR_CODES.WALLET_LOCKED, WALLET_LOCKED_MESSAGE, { reason: "locked" });
+        this.notifyLockedRequest("query", msg.method);
+        return;
+      }
+      this.sendResult(msg.id, identity);
+      return;
+    }
+    this.inFlight.add(msg.id, "query", this.config.requestDeadlineMs ?? DEFAULT_REQUEST_DEADLINE_MS);
     try {
       const result = await this.executeMethod(msg.method, msg.params ?? {});
+      if (!this.inFlight.settle(msg.id)) return;
       this.sendResult(msg.id, result);
     } catch (error) {
-      this.sendError(msg.id, ERROR_CODES.INTERNAL_ERROR, error.message);
+      if (!this.inFlight.settle(msg.id)) return;
+      const isSphereError = error instanceof SphereError || error?.name === "SphereError";
+      if (isSphereError) {
+        const e = error;
+        this.sendError(msg.id, ERROR_CODES.INTERNAL_ERROR, e.message, { reason: e.code });
+        return;
+      }
+      this.sendError(msg.id, ERROR_CODES.INTERNAL_ERROR, INTERNAL_ERROR_MESSAGE);
     }
   }
   // ===========================================================================
@@ -767,68 +1249,109 @@ var ConnectHost = class {
   // ===========================================================================
   async handleIntentRequest(msg) {
     if (!this.session?.active) {
-      this.sendIntentError(msg.id, ERROR_CODES.NOT_CONNECTED, "Not connected");
+      this.sendIntentError(msg.id, ERROR_CODES.NOT_CONNECTED, NOT_CONNECTED_MESSAGE);
       return;
     }
     if (this.session.expiresAt > 0 && Date.now() > this.session.expiresAt) {
-      this.revokeSession();
       this.sendIntentError(msg.id, ERROR_CODES.SESSION_EXPIRED, "Session expired");
+      this.revokeSession();
+      return;
+    }
+    if (!this.checkRateLimit()) {
+      this.sendIntentError(msg.id, ERROR_CODES.RATE_LIMITED, "Too many requests");
+      return;
+    }
+    const decision = gate(this._walletState, true, "intent", msg.action);
+    if (decision.kind === "refuse") {
+      this.sendIntentError(msg.id, decision.error.code, decision.error.message, decision.error.data);
+      if (decision.error.code === ERROR_CODES.WALLET_LOCKED) {
+        logger.debug("ConnectHost", `Refused intent ${msg.action} \u2014 WALLET_LOCKED 4009 (origin=${this.config.origin ?? "unverified"})`);
+        this.notifyLockedRequest("intent", msg.action);
+      }
       return;
     }
     if (!hasIntentPermission(this.grantedPermissions, msg.action)) {
       this.sendIntentError(msg.id, ERROR_CODES.PERMISSION_DENIED, `Permission denied for intent: ${msg.action}`);
       return;
     }
-    const autoHandler = this.autoApprovedIntents.get(msg.action);
-    if (autoHandler) {
-      const autoResponse = await autoHandler(msg.action, msg.params, this.session);
-      if (autoResponse.error) {
-        this.sendIntentError(msg.id, autoResponse.error.code, autoResponse.error.message);
+    const session = this.session;
+    const entry = this.inFlight.add(
+      msg.id,
+      "intent",
+      this.config.intentDeadlineMs ?? DEFAULT_INTENT_DEADLINE_MS
+    );
+    const ctx = {
+      origin: this.config.origin,
+      expiresAt: entry.deadline,
+      signal: entry.controller.signal
+    };
+    try {
+      const autoHandler = this.autoApprovedIntents.get(msg.action);
+      const response = autoHandler ? await autoHandler(msg.action, msg.params, session) : await this.config.onIntent(msg.action, msg.params, session, ctx);
+      if (!this.inFlight.settle(msg.id)) return;
+      if (response.error) {
+        const asserts = CHANNEL_ONLY_CODES.has(response.error.code);
+        if (asserts) {
+          logger.warn(
+            "ConnectHost",
+            `Wallet answered intent ${msg.action} with ${response.error.code}, which describes the channel rather than the spend \u2014 downgrading to INTENT_OUTCOME_UNKNOWN (origin=${this.config.origin ?? "unverified"})`
+          );
+        }
+        this.sendIntentError(
+          msg.id,
+          asserts ? ERROR_CODES.INTENT_OUTCOME_UNKNOWN : response.error.code,
+          asserts ? INTENT_UNKNOWN_MESSAGE : response.error.message
+        );
       } else {
-        this.sendIntentResult(msg.id, autoResponse.result);
+        this.sendIntentResult(msg.id, response.result);
       }
-      return;
-    }
-    const response = await this.config.onIntent(msg.action, msg.params, this.session);
-    if (response.error) {
-      this.sendIntentError(msg.id, response.error.code, response.error.message);
-    } else {
-      this.sendIntentResult(msg.id, response.result);
+    } catch (error) {
+      logger.warn("ConnectHost", `Intent handler threw: ${msg.action}`, error);
+      if (!this.inFlight.settle(msg.id)) return;
+      this.sendIntentError(msg.id, ERROR_CODES.INTERNAL_ERROR, INTERNAL_ERROR_MESSAGE);
     }
   }
   // ===========================================================================
   // Method Router
   // ===========================================================================
   async executeMethod(method, params) {
+    switch (method) {
+      case RPC_METHODS.SUBSCRIBE:
+        return this.handleSubscribe(params.event);
+      case RPC_METHODS.UNSUBSCRIBE:
+        return this.handleUnsubscribe(params.event);
+    }
+    const sphere = this.requireSphere();
     switch (method) {
       case RPC_METHODS.GET_IDENTITY:
         return this.getPublicIdentity();
       case RPC_METHODS.GET_BALANCE:
-        return this.sphere.payments.getBalance(params.coinId);
+        return sphere.payments.getBalance(params.coinId);
       case RPC_METHODS.GET_ASSETS:
-        return this.sphere.payments.getAssets(params.coinId);
+        return sphere.payments.getAssets(params.coinId);
       case RPC_METHODS.GET_FIAT_BALANCE:
-        return { fiatBalance: await this.sphere.payments.getFiatBalance() };
+        return { fiatBalance: await sphere.payments.getFiatBalance() };
       case RPC_METHODS.GET_TOKENS:
         return this.stripTokenSdkData(
-          this.sphere.payments.getTokens(
+          sphere.payments.getTokens(
             params.coinId ? { coinId: params.coinId } : void 0
           )
         );
       case RPC_METHODS.GET_HISTORY:
-        return this.sphere.payments.getHistory();
+        return sphere.payments.getHistory();
       case RPC_METHODS.RESOLVE:
         if (!params.identifier) {
           throw new SphereError("Missing required parameter: identifier", "VALIDATION_ERROR");
         }
-        return this.sphere.resolve(params.identifier);
+        return sphere.resolve(params.identifier);
       case RPC_METHODS.SUBSCRIBE:
         return this.handleSubscribe(params.event);
       case RPC_METHODS.UNSUBSCRIBE:
         return this.handleUnsubscribe(params.event);
       case RPC_METHODS.GET_CONVERSATIONS: {
-        if (!this.sphere.communications) throw new SphereError("Communications module not available", "MODULE_NOT_AVAILABLE");
-        const convos = this.sphere.communications.getConversations();
+        const comms = sphere.communications;
+        if (!comms) throw new SphereError("Communications module not available", "MODULE_NOT_AVAILABLE");
+        const convos = comms.getConversations();
         const result = [];
         const needsResolve = [];
         for (const [peer, messages] of convos) {
@@ -840,7 +1363,7 @@ var ConnectHost = class {
             peerPubkey: peer,
             peerNametag,
             lastMessage: last,
-            unreadCount: this.sphere.communications.getUnreadCount(peer),
+            unreadCount: comms.getUnreadCount(peer),
             messageCount: messages.length
           });
           if (!peerNametag) {
@@ -850,7 +1373,7 @@ var ConnectHost = class {
         if (needsResolve.length > 0) {
           const resolved = await Promise.all(
             needsResolve.map(
-              ({ peerPubkey }) => this.sphere.communications.resolvePeerNametag(peerPubkey).catch((err) => {
+              ({ peerPubkey }) => comms.resolvePeerNametag(peerPubkey).catch((err) => {
                 logger.debug("Connect", "Peer Unicity ID resolution failed", err);
                 return void 0;
               })
@@ -866,9 +1389,10 @@ var ConnectHost = class {
         return result;
       }
       case RPC_METHODS.GET_MESSAGES: {
-        if (!this.sphere.communications) throw new SphereError("Communications module not available", "MODULE_NOT_AVAILABLE");
+        const comms = sphere.communications;
+        if (!comms) throw new SphereError("Communications module not available", "MODULE_NOT_AVAILABLE");
         if (!params.peerPubkey) throw new SphereError("Missing required parameter: peerPubkey", "VALIDATION_ERROR");
-        return this.sphere.communications.getConversationPage(
+        return comms.getConversationPage(
           params.peerPubkey,
           {
             limit: params.limit,
@@ -877,23 +1401,26 @@ var ConnectHost = class {
         );
       }
       case RPC_METHODS.GET_DM_UNREAD_COUNT: {
-        if (!this.sphere.communications) throw new SphereError("Communications module not available", "MODULE_NOT_AVAILABLE");
+        const comms = sphere.communications;
+        if (!comms) throw new SphereError("Communications module not available", "MODULE_NOT_AVAILABLE");
         return {
-          unreadCount: this.sphere.communications.getUnreadCount(
+          unreadCount: comms.getUnreadCount(
             params.peerPubkey
           )
         };
       }
       case RPC_METHODS.MARK_AS_READ: {
-        if (!this.sphere.communications) throw new SphereError("Communications module not available", "MODULE_NOT_AVAILABLE");
+        const comms = sphere.communications;
+        if (!comms) throw new SphereError("Communications module not available", "MODULE_NOT_AVAILABLE");
         if (!params.messageIds || !Array.isArray(params.messageIds)) {
           throw new SphereError("Missing required parameter: messageIds (string[])", "VALIDATION_ERROR");
         }
-        await this.sphere.communications.markAsRead(params.messageIds);
+        await comms.markAsRead(params.messageIds);
         return { marked: true, count: params.messageIds.length };
       }
       case RPC_METHODS.GET_INVOICES: {
-        if (!this.sphere.accounting) throw new SphereError("Accounting module not available", "MODULE_NOT_AVAILABLE");
+        const accounting = sphere.accounting;
+        if (!accounting) throw new SphereError("Accounting module not available", "MODULE_NOT_AVAILABLE");
         const invoiceOpts = {};
         if (params.state !== void 0) invoiceOpts.state = params.state;
         if (params.limit !== void 0) invoiceOpts.limit = params.limit;
@@ -902,14 +1429,15 @@ var ConnectHost = class {
         if (params.sortOrder !== void 0) invoiceOpts.sortOrder = params.sortOrder;
         if (params.createdByMe !== void 0) invoiceOpts.createdByMe = params.createdByMe;
         if (params.targetingMe !== void 0) invoiceOpts.targetingMe = params.targetingMe;
-        return this.sphere.accounting.getInvoices(invoiceOpts);
+        return accounting.getInvoices(invoiceOpts);
       }
       case RPC_METHODS.GET_INVOICE_STATUS: {
-        if (!this.sphere.accounting) throw new SphereError("Accounting module not available", "MODULE_NOT_AVAILABLE");
+        const accounting = sphere.accounting;
+        if (!accounting) throw new SphereError("Accounting module not available", "MODULE_NOT_AVAILABLE");
         if (!params.invoiceId || typeof params.invoiceId !== "string") {
           throw new SphereError("Missing required parameter: invoiceId", "VALIDATION_ERROR");
         }
-        return this.sphere.accounting.getInvoiceStatus(params.invoiceId);
+        return accounting.getInvoiceStatus(params.invoiceId);
       }
       default:
         throw new SphereError(`Unknown method: ${method}`, "VALIDATION_ERROR");
@@ -920,17 +1448,24 @@ var ConnectHost = class {
   // ===========================================================================
   autoSubscribeIdentityChanged() {
     if (this.eventSubscriptions.has(WALLET_EVENTS.IDENTITY_CHANGED)) return;
-    const unsub = this.sphere.on("identity:changed", (data) => {
+    const unsub = this.requireSphere().on("identity:changed", (data) => {
       this.pushClientEvent(WALLET_EVENTS.IDENTITY_CHANGED, data);
     });
     this.eventSubscriptions.set(WALLET_EVENTS.IDENTITY_CHANGED, unsub);
   }
   handleSubscribe(eventName) {
     if (!eventName) throw new SphereError("Missing required parameter: event", "VALIDATION_ERROR");
+    if (isAutoPushedEvent(eventName)) {
+      return { subscribed: true, event: eventName };
+    }
+    if (this._walletState === "locked") {
+      this.suspendedSubscriptions.add(eventName);
+      return { subscribed: true, event: eventName };
+    }
     if (this.eventSubscriptions.has(eventName)) {
       return { subscribed: true, event: eventName };
     }
-    const unsub = this.sphere.on(eventName, (data) => {
+    const unsub = this.requireSphere().on(eventName, (data) => {
       this.transport.send({
         ns: SPHERE_CONNECT_NAMESPACE,
         v: SPHERE_CONNECT_VERSION,
@@ -949,6 +1484,7 @@ var ConnectHost = class {
       unsub();
       this.eventSubscriptions.delete(eventName);
     }
+    this.suspendedSubscriptions.delete(eventName);
     return { unsubscribed: true, event: eventName };
   }
   cleanupEventSubscriptions() {
@@ -970,8 +1506,90 @@ var ConnectHost = class {
       data
     });
   }
+  /** The bound Sphere, or a typed refusal. The ONLY way the router may reach Sphere.
+   *  Unreachable in practice — the gate guarantees 'live' before the router is entered —
+   *  so this is defence in depth, not the primary mechanism. */
+  requireSphere() {
+    if (!this.sphere) {
+      throw new SphereError(
+        this._walletState === "locked" ? WALLET_LOCKED_MESSAGE : "Wallet unavailable",
+        "NOT_INITIALIZED"
+      );
+    }
+    return this.sphere;
+  }
+  /** SNAPSHOT read. `undefined` means "we never saw an identity": callers MUST refuse,
+   *  never answer undefined-as-success — a dApp reads that as "the wallet has no
+   *  identity". Two explicit methods instead of one dual-mode method, so nobody can serve
+   *  a snapshot believing it is live. */
+  snapshotIdentity() {
+    return this.snapshot.identity;
+  }
+  /** InFlightRegistry.onExpire sink. Filled in a later task; declared here so the
+   *  constructor can wire it. */
+  settleExpired(entry) {
+    logger.warn(
+      "ConnectHost",
+      `Host deadline reached, answering on our own: ${entry.kind} ${entry.id} (origin=${this.config.origin ?? "unverified"})`
+    );
+    if (entry.kind === "query") {
+      this.sendError(entry.id, ERROR_CODES.INTERNAL_ERROR, INTERNAL_ERROR_MESSAGE);
+    } else {
+      this.sendIntentError(entry.id, ERROR_CODES.INTENT_OUTCOME_UNKNOWN, INTENT_UNKNOWN_MESSAGE);
+    }
+  }
+  /** Answer every request already in flight with one coded frame each. A request in flight
+   *  when the Sphere goes away otherwise answers -32603 with a raw JS message, returns
+   *  `undefined` AS SUCCESS (sphere_getIdentity), or — for a delegated intent — never
+   *  answers at all until the client's own 120 s timeout. */
+  settleInFlight(code, message, data) {
+    for (const entry of this.inFlight.settleAll()) {
+      if (entry.kind === "query") {
+        this.sendError(entry.id, code, message, data);
+        continue;
+      }
+      this.sendIntentError(entry.id, ERROR_CODES.INTENT_OUTCOME_UNKNOWN, INTENT_UNKNOWN_MESSAGE);
+    }
+  }
+  /**
+   * Notify-only. The host has ALREADY answered and never waits for the wallet.
+   *
+   * The wallet's only permitted reaction is a PASSIVE badge in its PERMANENT chrome; a
+   * dApp request may trigger a CONSENT prompt but never a credential prompt. Volume is
+   * bounded by checkRateLimit(), which guards all three entry points — there is no
+   * coalescing, no cooldown and no cap by design.
+   *
+   * A throwing handler must not break the host.
+   */
+  notifyLockedRequest(kind, name) {
+    try {
+      this.config.onLockedRequest?.({ origin: this.config.origin, kind, name });
+    } catch (err) {
+      logger.warn("ConnectHost", "onLockedRequest handler error", err);
+    }
+  }
+  /** Last-resort answer for a handler that threw before its own catch could run.
+   *  Id-bearing frames get a coded error (InFlightRegistry guarantees exactly one answer
+   *  per id); a handshake gets today's empty refusal, because a failed handshake must
+   *  reveal nothing. */
+  sendUnhandledError(msg, error) {
+    if (msg.type === "request") {
+      if (!this.inFlight.settle(msg.id) && this.inFlight.has(msg.id)) return;
+      this.sendError(msg.id, ERROR_CODES.INTERNAL_ERROR, INTERNAL_ERROR_MESSAGE);
+      return;
+    }
+    if (msg.type === "intent") {
+      this.inFlight.settle(msg.id);
+      this.sendIntentError(msg.id, ERROR_CODES.INTERNAL_ERROR, INTERNAL_ERROR_MESSAGE);
+      return;
+    }
+    if (msg.type === "handshake" && msg.direction === "request") {
+      logger.warn("ConnectHost", "Handshake handler threw; sending the empty refusal", error);
+      this.sendHandshakeResponse([], void 0, void 0);
+    }
+  }
   getPublicIdentity() {
-    const id = this.sphere.identity;
+    const id = this.requireSphere().identity;
     if (!id) return void 0;
     return {
       chainPubkey: id.chainPubkey,
@@ -995,13 +1613,13 @@ var ConnectHost = class {
       result
     });
   }
-  sendError(id, code, message) {
+  sendError(id, code, message, data) {
     this.transport.send({
       ns: SPHERE_CONNECT_NAMESPACE,
       v: SPHERE_CONNECT_VERSION,
       type: "response",
       id,
-      error: { code, message }
+      error: { code, message, ...data !== void 0 ? { data } : {} }
     });
   }
   sendIntentResult(id, result) {
@@ -1013,13 +1631,13 @@ var ConnectHost = class {
       result
     });
   }
-  sendIntentError(id, code, message) {
+  sendIntentError(id, code, message, data) {
     this.transport.send({
       ns: SPHERE_CONNECT_NAMESPACE,
       v: SPHERE_CONNECT_VERSION,
       type: "intent_result",
       id,
-      error: { code, message }
+      error: { code, message, ...data !== void 0 ? { data } : {} }
     });
   }
   checkRateLimit() {
@@ -1058,6 +1676,8 @@ var ConnectClient = class {
   grantedPermissions = [];
   identity = null;
   walletNet = null;
+  walletProto = null;
+  locked = false;
   connected = false;
   pendingRequests = /* @__PURE__ */ new Map();
   eventHandlers = /* @__PURE__ */ new Map();
@@ -1130,12 +1750,37 @@ var ConnectClient = class {
   get walletNetwork() {
     return this.walletNet;
   }
+  /**
+   * The wallet's Connect protocol version, captured from the handshake response `v`.
+   * Null before the first handshake response and after a disconnect.
+   *
+   * Feature-detect with it: compare against '2.1' to decide whether the wallet can be
+   * trusted to send wallet:unlocked / wallet:disconnected. A Connect 2.0 wallet destroys
+   * the session on lock and never emits either, so a dApp waiting for them against one
+   * waits forever.
+   *
+   * CAVEAT: on an ERROR response the host echoes the dApp's own `v` back
+   * (ConnectHost.sendHandshakeResponse), so after a refused connection this may be the
+   * dApp's version rather than the wallet's. Only trust it after a successful handshake.
+   */
+  get walletProtocol() {
+    return this.walletProto;
+  }
+  /**
+   * Whether the wallet was locked at the last handshake or lifecycle event.
+   * A locked client is still CONNECTED: `isConnected` stays true and `session` stays valid.
+   * Requests answer WALLET_LOCKED (4009) until `wallet:unlocked` arrives on the SAME
+   * session — do not disconnect, do not clear the session, do not re-handshake.
+   */
+  get walletLocked() {
+    return this.locked;
+  }
   // ===========================================================================
   // Query (read data)
   // ===========================================================================
   /** Send a query request and return the result */
   async query(method, params) {
-    if (!this.connected) throw new SphereError("Not connected", "NOT_INITIALIZED");
+    if (!this.connected) throw new ConnectError("Not connected", ERROR_CODES.NOT_CONNECTED);
     const id = createRequestId();
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -1145,7 +1790,8 @@ var ConnectClient = class {
       this.pendingRequests.set(id, {
         resolve,
         reject,
-        timer
+        timer,
+        kind: "query"
       });
       this.transport.send({
         ns: SPHERE_CONNECT_NAMESPACE,
@@ -1162,17 +1808,23 @@ var ConnectClient = class {
   // ===========================================================================
   /** Send an intent request. The wallet will open its UI for user confirmation. */
   async intent(action, params) {
-    if (!this.connected) throw new SphereError("Not connected", "NOT_INITIALIZED");
+    if (!this.connected) throw new ConnectError("Not connected", ERROR_CODES.NOT_CONNECTED);
     const id = createRequestId();
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pendingRequests.delete(id);
-        reject(new Error(`Intent timeout: ${action}`));
+        reject(
+          new ConnectError(
+            `Intent outcome unknown \u2014 do not retry; reconcile before acting: ${action}`,
+            ERROR_CODES.INTENT_OUTCOME_UNKNOWN
+          )
+        );
       }, this.intentTimeout);
       this.pendingRequests.set(id, {
         resolve,
         reject,
-        timer
+        timer,
+        kind: "intent"
       });
       this.transport.send({
         ns: SPHERE_CONNECT_NAMESPACE,
@@ -1191,7 +1843,7 @@ var ConnectClient = class {
   on(event, handler) {
     if (!this.eventHandlers.has(event)) {
       this.eventHandlers.set(event, /* @__PURE__ */ new Set());
-      if (this.connected) {
+      if (this.connected && !isAutoPushedEvent(event)) {
         this.query(RPC_METHODS.SUBSCRIBE, { event }).catch((err) => logger.debug("Connect", "Event subscription failed", err));
       }
     }
@@ -1202,7 +1854,7 @@ var ConnectClient = class {
         handlers.delete(handler);
         if (handlers.size === 0) {
           this.eventHandlers.delete(event);
-          if (this.connected) {
+          if (this.connected && !isAutoPushedEvent(event)) {
             this.query(RPC_METHODS.UNSUBSCRIBE, { event }).catch((err) => logger.debug("Connect", "Event unsubscription failed", err));
           }
         }
@@ -1226,15 +1878,36 @@ var ConnectClient = class {
       return;
     }
     if (msg.type === "event") {
-      const handlers = this.eventHandlers.get(msg.event);
-      if (handlers) {
-        for (const handler of handlers) {
-          try {
-            handler(msg.data);
-          } catch (err) {
-            logger.debug("Connect", "Event handler error", err);
-          }
-        }
+      if (!this.connected || !this.sessionId) {
+        logger.warn("Connect", `Ignoring wallet event before a session exists: ${msg.event}`);
+        return;
+      }
+      if (msg.event === WALLET_EVENTS.LOCKED) {
+        this.locked = true;
+      } else if (msg.event === WALLET_EVENTS.UNLOCKED) {
+        this.locked = false;
+        const identity = msg.data?.identity;
+        if (identity) this.identity = identity;
+      } else if (msg.event === WALLET_EVENTS.DISCONNECTED) {
+        this.connected = false;
+      } else if (msg.event === WALLET_EVENTS.IDENTITY_CHANGED) {
+        const data = msg.data;
+        if (data && typeof data.chainPubkey === "string") this.identity = data;
+      }
+      this.dispatchEvent(msg.event, msg.data);
+      if (msg.event === WALLET_EVENTS.DISCONNECTED) {
+        this.cleanup();
+      }
+    }
+  }
+  dispatchEvent(event, data) {
+    const handlers = this.eventHandlers.get(event);
+    if (!handlers) return;
+    for (const handler of handlers) {
+      try {
+        handler(data);
+      } catch (err) {
+        logger.debug("Connect", "Event handler error", err);
       }
     }
   }
@@ -1242,6 +1915,7 @@ var ConnectClient = class {
     if (!this.handshakeResolver) return;
     clearTimeout(this.handshakeResolver.timer);
     const m = msg;
+    this.walletProto = msg.v ?? null;
     if (m.error) {
       this.handshakeResolver.reject(new ConnectError(m.error.message, m.error.code, m.error.data));
       this.handshakeResolver = null;
@@ -1252,12 +1926,16 @@ var ConnectClient = class {
       this.grantedPermissions = msg.permissions;
       this.identity = msg.identity;
       this.walletNet = m.network ?? null;
+      this.locked = m.locked === true;
       this.connected = true;
       if (m.warning) logger.warn("Connect", "Wallet deprecation notice", m.warning.message);
       this.handshakeResolver.resolve({
         sessionId: msg.sessionId,
         permissions: this.grantedPermissions,
-        identity: msg.identity
+        identity: msg.identity,
+        // A resume DURING a lock succeeds: the dApp is connected on the same session and
+        // must not re-handshake. It will get wallet:unlocked when the user unlocks.
+        ...this.locked ? { locked: true } : {}
       });
     } else {
       this.handshakeResolver.reject(new Error("Connection rejected by wallet"));
@@ -1283,9 +1961,19 @@ var ConnectClient = class {
       this.unsubscribeTransport();
       this.unsubscribeTransport = null;
     }
+    if (this.handshakeResolver) {
+      clearTimeout(this.handshakeResolver.timer);
+      this.handshakeResolver.reject(new ConnectError("Disconnected", ERROR_CODES.NOT_CONNECTED));
+      this.handshakeResolver = null;
+    }
     for (const [, pending] of this.pendingRequests) {
       clearTimeout(pending.timer);
-      pending.reject(new Error("Disconnected"));
+      pending.reject(
+        pending.kind === "intent" ? new ConnectError(
+          "Intent outcome unknown \u2014 do not retry; reconcile before acting",
+          ERROR_CODES.INTENT_OUTCOME_UNKNOWN
+        ) : new ConnectError("Disconnected", ERROR_CODES.NOT_CONNECTED)
+      );
     }
     this.pendingRequests.clear();
     this.eventHandlers.clear();
@@ -1294,10 +1982,13 @@ var ConnectClient = class {
     this.grantedPermissions = [];
     this.identity = null;
     this.walletNet = null;
+    this.walletProto = null;
+    this.locked = false;
   }
 };
 export {
   ALL_PERMISSIONS,
+  AUTO_PUSHED_EVENTS,
   ConnectClient,
   ConnectError,
   ConnectHost,
@@ -1317,6 +2008,7 @@ export {
   createRequestId,
   hasIntentPermission,
   hasMethodPermission,
+  isAutoPushedEvent,
   isSphereConnectMessage,
   validatePermissions
 };