@coventia/softphone 0.4.0 → 0.5.1

package/dist/zadarma/index.cjs

@@ -361,6 +361,19 @@ var ERROR_CATALOGUE = {
     message: "The provider does not support this operation.",
     solution: "Guard the UI on the operation before offering it."
   },
+  // ── Line owner (docs/specs/line-owner.md §5) ────────────────────────────────
+  // What `takeLine()` rejects with — and `call()` from `standby`, which takes the line first. Never
+  // emitted on `SoftphoneEvent.Error`: the promise IS the answer, and nothing about the phone is broken.
+  "line/claim-refused": {
+    fatal: false,
+    message: "The line was not moved here: the user is on a call on the softphone that has it.",
+    solution: "Nothing to fix. The line never moves during a call; take it again once that call has ended. Incoming calls keep ringing where they ring now."
+  },
+  "line/unavailable": {
+    fatal: false,
+    message: "The line could not be taken: nothing decided where it is.",
+    solution: "The presence connection is down, the backend predates the line owner, or it did not answer in time. Retry in a moment; incoming calls keep ringing where they ring now."
+  },
   // ── Provider ────────────────────────────────────────────────────────────────
   "provider/provision-failed": {
     fatal: true,
@@ -390,11 +403,47 @@ function createError(code, cause) {
   return new CatalogueError(code, cause);
 }
 
+// src/sources.ts
+function toDigits(number) {
+  return String(number ?? "").replace(/\D/g, "");
+}
+
 // src/transports/sip/ua.ts
 var DEFAULT_ICE_CAP_MS = 3e3;
 var REGISTER_EXPIRES = 580;
-var SIGNAL_REFRESH_DEBOUNCE_MS = 3e4;
 var ERROR_DEBOUNCE_MS = 3e4;
+var OFFER_FORGOTTEN_MS = 12e4;
+var DECLINE_GUARD_CEILING_MS = 12e4;
+var OFFER_PUSH_SLACK_MS = 1e4;
+var INVITE_TRANSACTION_MAX_MS = 32e3;
+var ICT_PROCEEDING = 2;
+var ICT_CALLING = 3;
+function inviteTransactionOf(session) {
+  const tx = session._request?.transaction;
+  return tx && typeof tx.state === "number" && typeof tx.on === "function" ? tx : null;
+}
+function awaitsAnswer(tx) {
+  return tx.state === ICT_CALLING || tx.state === ICT_PROCEEDING;
+}
+function deferredCancelOf(session) {
+  const flag = session._is_canceled;
+  return typeof flag === "boolean" ? flag : null;
+}
+var SUFFIX_MATCH_MIN_DIGITS = 9;
+function sameNumber(a, b) {
+  if (!a || !b) return false;
+  if (a === b) return true;
+  const [shorter, longer] = a.length < b.length ? [a, b] : [b, a];
+  return shorter.length >= SUFFIX_MATCH_MIN_DIGITS && longer.endsWith(shorter);
+}
+function isRefusal(e) {
+  const status = e?.response?.status_code;
+  if (typeof status === "number") return status === 401 || status === 403;
+  return e?.cause === "Authentication Error" || e?.cause === "Rejected";
+}
+function debug(message) {
+  console.debug(`[softphone] ${message}`);
+}
 var CALL_END_CODES = {
   busy: "call/busy",
   "no-answer": "call/no-answer",
@@ -416,9 +465,44 @@ var SipCallEngine = class {
   provider;
   factory;
   #state = "stopped";
+  /**
+   * Which `start()`…`stop()` cycle this is — bumped by `stop()`, which ends one. Everything that awaits
+   * and then acts (builds a UA, subscribes to the signal, sets the state) captures it first and gives up
+   * if a stop has happened since. Not bumped by `start()`: that would cancel work begun just before it,
+   * such as a call placed while the softphone is still starting.
+   *
+   * Without it a stopped phone came back to life: a provisioning or a signal connect still in flight
+   * when `stop()` ran finished afterwards and REGISTERed — and since the PBX routes a call to whichever
+   * client registered last, it quietly took calls from the user's other device while its UI said off.
+   */
+  #run = 0;
   #ua = null;
   /** In-flight `#createUA()`. THE concurrency guard — see `#ensureUA`. */
   #uaInFlight = null;
+  /**
+   * Bumped by every `#teardownUA`. A UA still being provisioned when its reason to exist went away — the offer
+   * ended, the leak guard gave up — is then not built (`#createUA`): built anyway, it would REGISTER for nobody
+   * and nothing would ever tear it down.
+   */
+  #uaEpoch = 0;
+  /**
+   * Dials waiting for the current UA to register (`#callWhenRegistered`): dialled by its `registered`, failed by
+   * `#teardownUA` — but kept when the UA is only being rebuilt on fresh credentials (`#retryOnFreshCredentials`).
+   */
+  #awaitingRegistration = /* @__PURE__ */ new Set();
+  /** `placeCall`s in progress, from before their UA exists: no offer's teardown may pull it from under them. */
+  #dialing = 0;
+  /**
+   * Where the current UA's registration stands: `connecting` (its REGISTER goes out once the WSS is up),
+   * `registering` (a REGISTER is out, unanswered), `registered` (the WSS is up and no REGISTER of ours is out — a
+   * refresh that failed under a live call leaves it here too). What decides how an offer gets a REGISTER sent
+   * after it (`#registerAfterOffer`).
+   */
+  #registration = "connecting";
+  /** An offer arrived while a REGISTER sent BEFORE it was still unanswered: another goes out once it is. */
+  #registerAgain = false;
+  /** A UA has already been rebuilt on fresh credentials since the last registration that worked: not again. */
+  #freshCredentialsTried = false;
   #domain = "";
   #activeCall = null;
   /**
@@ -437,17 +521,52 @@ var SipCallEngine = class {
   #errorListeners = /* @__PURE__ */ new Set();
   #signalUnsub = null;
   #signalConnectionUnsub = null;
+  /** The offer waiting for its INVITE, if any (§4.3). */
+  #offerWait = null;
+  /**
+   * The latest offer pushed while a call was in progress. It used to be dropped for good — the caller then waited
+   * for the provider to offer it again. Now, when the call ends, it is registered for at once if it is still
+   * within its wait (no `offer-ended` for it, inside the leak guard), so it rings as soon as the line is free.
+   */
+  #pendingOffer = null;
+  /** Armed at the REGISTER's 200 OK while an offer waits (`noInviteAfterRegisterMs`). */
   #noInviteTimer;
-  #rejectGuardUntil = 0;
-  #signalRefreshAfter = 0;
+  /**
+   * What the backend has said about the calls offered to this line (`noteOffer`, §5), by `callId` — ended ones
+   * included, for a while. Only for telling, at a decline, which call was declined and whether it is still alive.
+   */
+  #offers = /* @__PURE__ */ new Map();
+  /** Declined calls whose re-offers are being ignored (§4.4). Pruned as they lapse. */
+  #declined = [];
+  /** CANCELs JsSIP still owes for outbound legs that ended before any ringback (§4.7, `#watchOwedCancel`). */
+  #owedCancels = [];
+  /** UAs let go of while owing one: un-REGISTERed, still connected — with the cap that stops them regardless. */
+  #lingering = /* @__PURE__ */ new Map();
   #errorSentAfter = /* @__PURE__ */ new Map();
   now;
   #resolvedFactory = null;
+  /** The loader in flight, shared: the pre-load at `start()` and a first UA racing it fetch the module once. */
+  #factoryLoad = null;
   async #resolveFactory() {
     if (this.#resolvedFactory) return this.#resolvedFactory;
-    this.#resolvedFactory = typeof this.factory === "function" ? await this.factory() : this.factory;
+    if (typeof this.factory !== "function") return this.#resolvedFactory = this.factory;
+    const loader = this.factory;
+    this.#factoryLoad ??= Promise.resolve().then(() => loader()).finally(() => {
+      this.#factoryLoad = null;
+    });
+    this.#resolvedFactory = await this.#factoryLoad;
     return this.#resolvedFactory;
   }
+  /**
+   * Fetch the SIP stack now, not on the first call. It is loaded lazily (`import('jssip')`, SSR-safe — SPEC §10.2),
+   * and that used to happen on the first UA: between the first push after a page load and its REGISTER, measured
+   * 33–109 ms on localhost and more on a slow network or a throttled tab. Fire-and-forget: a failure here only
+   * leaves the lazy path to try again when a UA is built (incoming-call-reliability.md §4.5).
+   */
+  #preloadFactory() {
+    this.#resolveFactory().catch(() => {
+    });
+  }
   get state() {
     return this.#state;
   }
@@ -501,15 +620,29 @@ var SipCallEngine = class {
     for (const listener of [...this.#errorListeners]) listener(error);
   }
   async start() {
+    const run = this.#run;
     this.#setState("starting");
     if (this.provider.registrationMode === "persistent") {
-      await this.#ensureUA();
+      try {
+        await this.#ensureUA();
+      } catch (cause) {
+        if (run === this.#run) throw cause;
+      }
+      if (run !== this.#run) return;
       this.#setState("online");
     } else {
+      this.#preloadFactory();
       const signal = this.provider.incomingSignal;
       if (signal) {
-        await signal.connect();
-        this.#signalUnsub = signal.onSignal(() => void this.#onIncomingSignal());
+        try {
+          await signal.connect();
+        } catch (cause) {
+          if (run !== this.#run) return;
+          signal.disconnect();
+          throw cause;
+        }
+        if (run !== this.#run) return;
+        this.#signalUnsub = signal.onSignal((event) => this.#onIncomingSignal(event));
         this.#signalConnectionUnsub = signal.onConnectionChange?.(
           (connected) => this.#setState(connected ? "online" : "offline")
         ) ?? null;
@@ -518,6 +651,8 @@ var SipCallEngine = class {
     }
   }
   async stop() {
+    this.#run += 1;
+    this.#pendingOffer = null;
     this.#clearNoInviteTimer();
     this.#signalUnsub?.();
     this.#signalUnsub = null;
@@ -528,62 +663,271 @@ var SipCallEngine = class {
     this.#setState("stopped");
   }
   async placeCall(destination, _options) {
-    const ua = await this.#ensureUA();
-    const session = await this.#callWhenRegistered(ua, this.#buildTarget(destination));
-    return this.#wrapCall(session);
+    this.#dialing += 1;
+    const run = this.#run;
+    try {
+      await this.#ensureUA();
+      return await this.#callWhenRegistered(this.#buildTarget(destination), run);
+    } finally {
+      this.#dialing -= 1;
+    }
+  }
+  /**
+   * What the backend says about calls offered to this line (incoming-call-reliability.md §5) — kept only to tell,
+   * at a decline, WHICH call was declined, and so how long its re-offers last (§4.4).
+   *
+   * Per `callId`, every message is idempotent, and they come duplicated, with no order at all — not even between
+   * the `start` and the `end` of one call, which reach different backend instances and are relayed through Redis,
+   * and a stored offer replayed after `hello` can race either. So `ended` is sticky: a `start` after its call's
+   * `end` never makes it live again. An `end` also reaches a softphone that is not the line's owner (a `start` only
+   * the owner): stored all the same, whatever state this engine is in. `null`: the channel went away, so no `end`
+   * can be counted on for the calls still live; a guard following one falls back to its window. What is known to
+   * have ended stays known.
+   */
+  noteOffer(offer) {
+    const now = this.now();
+    for (const [callId, known2] of this.#offers) {
+      if (now - known2.at >= OFFER_FORGOTTEN_MS) this.#offers.delete(callId);
+    }
+    if (offer === null) {
+      for (const [callId, known2] of this.#offers) if (known2.endedAt === null) this.#offers.delete(callId);
+      return;
+    }
+    const known = this.#offers.get(offer.callId);
+    this.#offers.delete(offer.callId);
+    const from = toDigits(offer.from ?? "") || (known?.from ?? "");
+    const fallbackMs = this.#declineFallbackMs();
+    if (offer.state === "end") {
+      this.#offers.set(offer.callId, { from, at: now, endedAt: known?.endedAt ?? now });
+      this.#declined = this.#declined.filter((declined) => declined.callId !== offer.callId);
+      if (from) {
+        this.#declined = this.#declined.map(
+          (declined) => declined.adopts && now >= declined.since && sameNumber(declined.caller, from) ? { ...declined, adopts: false } : declined
+        );
+      }
+      return;
+    }
+    const endedAt = known?.endedAt ?? null;
+    this.#offers.set(offer.callId, { from, at: now, endedAt });
+    if (!from) return;
+    if (endedAt !== null) {
+      const isThatCall = (declined) => declined.adopts && now - declined.at < fallbackMs && endedAt >= declined.since && sameNumber(declined.caller, from);
+      this.#declined = this.#declined.filter((declined) => !isThatCall(declined));
+      return;
+    }
+    this.#declined = this.#declined.map(
+      (declined) => declined.adopts && now - declined.at < fallbackMs && now <= declined.since + OFFER_PUSH_SLACK_MS && sameNumber(declined.caller, from) ? { ...declined, callId: offer.callId, adopts: false } : declined
+    );
   }
   // ── incoming (on-demand: push → register → INVITE) ────────────────────────
-  async #onIncomingSignal() {
-    if (this.now() < this.#rejectGuardUntil) return;
-    if (this.#activeCall) return;
+  /**
+   * The push's own word on what it is (incoming-call-reliability.md §4.1, read by the provider): only an `offer`
+   * registers. Before this, every push did — `answered` after each hang-up included — and the UA it left
+   * registered is where the next call's INVITE never came (F2).
+   */
+  #onIncomingSignal(event) {
+    if (event.kind === "offer") void this.#onOffer(event.from);
+    else if (event.kind === "offer-ended") this.#onOfferEnded(event.from);
+    else debug(`push ignored: ${event.detail}`);
+  }
+  /** `pushedAt`: when its push came, for an offer kept while a call was in progress (`#pendingOffer`). */
+  async #onOffer(from, pushedAt = this.now()) {
+    if (this.#isDeclinedCaller(from)) {
+      debug("offer ignored: the caller just declined is being offered again");
+      return;
+    }
+    if (this.#activeCall) {
+      this.#pendingOffer = { from, at: pushedAt };
+      return;
+    }
+    this.#awaitOffer(from, pushedAt);
+    const ua = this.#ua;
+    if (ua) {
+      this.#registerAfterOffer(ua);
+      return;
+    }
+    const run = this.#run;
+    const epoch = this.#uaEpoch;
     try {
       await this.#ensureUA();
-      this.#armNoInviteTeardown();
     } catch {
-      this.#teardownUA();
+      if (run === this.#run && epoch === this.#uaEpoch) this.#teardownUA();
     }
   }
-  #armNoInviteTeardown() {
-    const ms = this.provider.quirks?.noInviteTeardownMs;
-    if (!ms) return;
+  /**
+   * That offer is over — answered elsewhere, declined, cancelled, timed out (§4.1). A UA still waiting for its
+   * INVITE goes now instead of when a timer says so; never one carrying a call (`#maybeTeardownUA`). Only when the
+   * push names the same caller as the offer waited for: two offers can overlap, and an end that names nobody (a
+   * withheld number, a push with no `callerid`) could be anyone's — the timers bound that wait instead.
+   */
+  #onOfferEnded(from) {
+    const caller = toDigits(from ?? "");
+    if (!caller) return;
+    if (this.#pendingOffer && sameNumber(caller, toDigits(this.#pendingOffer.from ?? ""))) this.#pendingOffer = null;
+    const wait = this.#offerWait;
+    if (!wait || !sameNumber(caller, wait.from)) return;
+    this.#offerOver();
+  }
+  /**
+   * Starts waiting for this offer's INVITE: a leak guard from its push (§4.3), and no no-INVITE timer yet.
+   * `pushedAt` is now, except for an offer kept through a call (`#pendingOffer`).
+   */
+  #awaitOffer(from, pushedAt) {
+    this.#endOfferWait();
+    const ms = this.provider.quirks?.offerWaitMaxMs;
+    const leak = ms ? setTimeout(
+      () => {
+        if (this.#offerWait !== wait) return;
+        debug("offer abandoned: still no INVITE long after its push");
+        this.#offerOver();
+      },
+      Math.max(0, ms - (this.now() - pushedAt))
+    ) : void 0;
+    const wait = { from: toDigits(from ?? ""), at: pushedAt, leak };
+    this.#offerWait = wait;
+  }
+  /**
+   * The offer kept through the call that just ended, if it is still worth registering for: no `offer-ended` for
+   * it, and still inside the leak guard from its push. Taken: it is registered for once, at most.
+   */
+  #takePendingOffer() {
+    const pending = this.#pendingOffer;
+    this.#pendingOffer = null;
+    if (!pending || !this.#signalUnsub) return null;
+    const maxMs = this.provider.quirks?.offerWaitMaxMs;
+    if (maxMs && this.now() - pending.at >= maxMs) return null;
+    return pending;
+  }
+  /** No INVITE is coming for the offer being waited for: its UA goes, unless something else is on it. */
+  #offerOver() {
+    this.#endOfferWait();
+    this.#maybeTeardownUA();
+  }
+  #endOfferWait() {
+    if (this.#offerWait?.leak) clearTimeout(this.#offerWait.leak);
+    this.#offerWait = null;
+    this.#registerAgain = false;
     this.#clearNoInviteTimer();
-    this.#noInviteTimer = setTimeout(() => this.#maybeTeardownUA(), ms);
   }
   /**
-   * Rebuild the incoming-signal channel with fresh credentials, after a registration failure.
+   * A REGISTER sent AFTER this offer's push, on the UA that is already there (§4.2). Whether one is needed depends
+   * on where that UA's registration stands:
+   *   - `connecting`: its REGISTER goes out when the WSS is up — after this push already.
+   *   - `registering`: the REGISTER in flight went out BEFORE this push; another follows its answer.
+   *   - `registered`: a refresh, now.
+   */
+  #registerAfterOffer(ua) {
+    if (this.#registration === "registering") this.#registerAgain = true;
+    else if (this.#registration === "registered") this.#refreshRegistration(ua);
+  }
+  /**
+   * A REGISTER refresh whose 200 OK is HEARD — the no-INVITE wait counts from it (§4.3).
    *
-   * Registration fails when the credentials behind it have gone stale — and for Zadarma those come
-   * from the same WebRTC key the push socket is holding. Tearing down the UA alone leaves that stale
-   * key in place, so every subsequent attempt fails the same way and the phone is dead until the page
-   * is reloaded. Reconnecting re-fetches the key. The legacy hook did exactly this from both of its
-   * `registrationFailed` handlers.
+   * JsSIP's `register()` sends one, but announces `registered` only for a UA that was not registered
+   * (`Registrator.js`: `if (!this._registered)`), so a refresh's 200 OK would pass in silence.
+   * `registrator().onTransportClosed()` clears that flag and sends nothing — it is what JsSIP runs itself when its
+   * WSS drops, before registering again — so after it the refresh is announced like a first registration. On the
+   * wire nothing changes: the same refresh (same Call-ID, next CSeq) the lab saw answered with the INVITE
+   * (Q5). Only called with no REGISTER of ours in flight (`#registration`), so no answer is left orphaned.
    *
-   * Debounced, which the legacy was not: a provider failing every attempt would otherwise become a
-   * tight loop against our backend and theirs.
+   * A JsSIP without that hook still sends the refresh; its 200 OK just cannot be heard, so the wait starts now.
    */
-  async #refreshSignal() {
-    const signal = this.provider.incomingSignal;
-    if (!signal) return;
-    if (this.now() < this.#signalRefreshAfter) return;
-    this.#signalRefreshAfter = this.now() + SIGNAL_REFRESH_DEBOUNCE_MS;
-    try {
-      signal.disconnect();
-      await signal.connect();
-    } catch {
-    }
+  #refreshRegistration(ua) {
+    const registrator = ua.registrator?.();
+    const heard = typeof registrator?.onTransportClosed === "function";
+    if (heard) registrator.onTransportClosed();
+    this.#registration = heard ? "registering" : "registered";
+    ua.register();
+    if (!heard && this.#offerWait) this.#armNoInviteTimer();
+  }
+  /**
+   * Armed at the REGISTER's 200 OK, never at `ua.start()`: on a slow network the WSS alone outlasted the old 5 s,
+   * and the UA was gone before it ever registered (F3). The INVITE follows the 200 OK by ~0.1 s (§2).
+   */
+  #armNoInviteTimer() {
+    this.#clearNoInviteTimer();
+    const ms = this.provider.quirks?.noInviteAfterRegisterMs;
+    if (!ms) return;
+    this.#noInviteTimer = setTimeout(() => {
+      this.#noInviteTimer = void 0;
+      this.#offerOver();
+    }, ms);
   }
   #clearNoInviteTimer() {
     if (this.#noInviteTimer) clearTimeout(this.#noInviteTimer);
     this.#noInviteTimer = void 0;
   }
+  // ── the decline guard (SPEC §3.4, incoming-call-reliability.md §4.4) ───────
+  /**
+   * Whether an offer — or an INVITE — from this caller is a re-offer of a call just declined. The provider re-offers a
+   * declined call until its ring time ends, and nothing in a re-offer tells it from a new call. The guard used to
+   * swallow EVERY offer and INVITE for 35 s, whoever called: a new call in that window was lost (CWA-81, F1).
+   *
+   * Now it holds only for the declined caller, and only while that call lives: until the backend's `end` for it
+   * when it announced the call (`noteOffer`) — at most `DECLINE_GUARD_CEILING_MS` — else for the provider's
+   * fallback window after the decline. Anyone else always rings; so does a caller this cannot name.
+   */
+  #isDeclinedCaller(number) {
+    const fallbackMs = this.#declineFallbackMs();
+    if (!fallbackMs || this.#declined.length === 0) return false;
+    const now = this.now();
+    this.#declined = this.#declined.filter((declined) => {
+      const offer = declined.callId === null ? void 0 : this.#offers.get(declined.callId);
+      if (offer && offer.endedAt === null) return now - declined.at < DECLINE_GUARD_CEILING_MS;
+      return now - declined.at < fallbackMs;
+    });
+    const caller = toDigits(number ?? "");
+    return this.#declined.some((declined) => sameNumber(declined.caller, caller));
+  }
+  /** The decline guard's fallback window — and whether there is a guard at all: only a provider that re-offers. */
+  #declineFallbackMs() {
+    return this.provider.quirks?.declinedCallerGuardMs ?? 0;
+  }
+  /**
+   * The user declined `call`. Remembers the caller as its INVITE named them, and which offer the backend says that
+   * is (§4.4). Only what the backend said about THIS call counts: a call from the same caller that ended before
+   * this one was pushed (`since`) is another call — taking it for this one lost the callback after a second
+   * decline of the same caller.
+   *   - a live offer from that caller, announced around this call's push or after: the guard follows it until
+   *     its `end`;
+   *   - an offer from that caller that ENDED since this call's push (the first leg of a transfer, a ring-group
+   *     call someone else answered): the fallback window — whatever that caller sends next is not that call, so
+   *     no later `start` is taken for it;
+   *   - neither (its `start` lands after the decline): the fallback window, and a `start` from that caller that
+   *     comes around this call's push is taken as this call's (`noteOffer`).
+   *
+   * An INVITE that names nobody (a withheld number) guards nobody. It used to borrow the caller of the latest push,
+   * which with two offers overlapping is someone else's — and that someone's calls were then ignored.
+   */
+  #onDecline(call, since) {
+    if (!this.#declineFallbackMs() || call.direction !== "inbound") return;
+    const caller = toDigits(call.remoteNumber);
+    if (!caller) return;
+    const now = this.now();
+    let latest = null;
+    for (const [callId, offer] of this.#offers) {
+      if (!sameNumber(offer.from, caller) || now - offer.at >= OFFER_FORGOTTEN_MS) continue;
+      if (offer.endedAt === null && offer.at >= since - OFFER_PUSH_SLACK_MS) latest = { callId, ended: false };
+      else if (offer.endedAt !== null && offer.endedAt >= since) latest = { callId, ended: true };
+    }
+    this.#declined.push(
+      latest && !latest.ended ? { caller, callId: latest.callId, adopts: false, at: now, since } : { caller, callId: null, adopts: latest === null, at: now, since }
+    );
+  }
   #onNewSession(session, originator) {
     if (originator !== "remote") return;
-    this.#clearNoInviteTimer();
-    if (this.#activeCall || this.now() < this.#rejectGuardUntil) {
+    if (this.#activeCall) {
+      session.terminate({ status_code: 486, reason_phrase: "Busy Here" });
+      return;
+    }
+    if (this.#isDeclinedCaller(remoteNumberOf(session))) {
+      debug("INVITE declined: the caller just declined is being offered again");
       session.terminate({ status_code: 486, reason_phrase: "Busy Here" });
       return;
     }
-    const call = this.#wrapCall(session);
+    const since = this.#offerWait?.at ?? this.now();
+    this.#endOfferWait();
+    const call = this.#wrapCall(session, since);
     for (const listener of [...this.#incomingListeners]) listener(call);
   }
   // ── UA lifecycle ───────────────────────────────────────────────────────────
@@ -596,18 +940,23 @@ var SipCallEngine = class {
    * torn down. The visible symptom is two `get_webphone_data.php` calls at startup and a phone that
    * never registers.
    *
-   * Concurrency is the normal case here, not an edge: the push socket can signal twice in a
-   * heartbeat (SPEC §3.3 — a push is not an INVITE; it fires for transfers, retries and hangups),
-   * and `placeCall` can land on top of one. So the in-flight promise IS the guard.
+   * Concurrency is the normal case here, not an edge: the push socket can offer twice in a heartbeat
+   * (a push seen on both sockets of a rebuild, two calls at once), and `placeCall` can land on top of
+   * one. So the in-flight promise IS the guard.
    */
   async #ensureUA() {
     if (this.#ua) return this.#ua;
-    this.#uaInFlight ??= this.#createUA().finally(() => {
-      this.#uaInFlight = null;
-    });
+    if (!this.#uaInFlight) {
+      const inFlight = this.#createUA().finally(() => {
+        if (this.#uaInFlight === inFlight) this.#uaInFlight = null;
+      });
+      this.#uaInFlight = inFlight;
+    }
     return this.#uaInFlight;
   }
   async #createUA() {
+    const run = this.#run;
+    const epoch = this.#uaEpoch;
     const factory = await this.#resolveFactory();
     let credentials;
     try {
@@ -617,31 +966,97 @@ var SipCallEngine = class {
       else this.#reportError("provider/provision-failed", cause);
       throw cause;
     }
+    if (run !== this.#run) throw createError("engine/not-started");
+    if (epoch !== this.#uaEpoch) throw createError("call/failed", "the UA was let go of before it was built");
     this.#domain = domainOf(credentials);
     const config = this.#uaConfig(credentials, factory);
     const ua = factory.createUA(config);
-    ua.on("newRTCSession", ({ session, originator }) => this.#onNewSession(session, originator));
+    let reached = false;
+    ua.on("newRTCSession", ({ session, originator }) => {
+      if (ua !== this.#ua) {
+        if (originator === "remote") session.terminate({ status_code: 486, reason_phrase: "Busy Here" });
+        return;
+      }
+      this.#onNewSession(session, originator);
+    });
     ua.on("disconnected", ({ error }) => {
+      if (ua !== this.#ua) return;
+      this.#registration = "connecting";
       if (!error) return;
+      if (!reached && this.#retryOnFreshCredentials("unreachable", ua, credentials)) return;
       this.#setState("reconnecting");
       this.#reportError("net/transport-failed", error);
     });
-    ua.on("connected", () => this.#setState("online"));
+    ua.on("connected", () => {
+      if (ua !== this.#ua) return;
+      reached = true;
+      this.#registration = "registering";
+      this.#setState("online");
+    });
+    ua.on("registered", () => {
+      if (ua !== this.#ua) return;
+      this.#registration = "registered";
+      this.#freshCredentialsTried = false;
+      this.provider.credentialsWorked?.();
+      for (const waiter of [...this.#awaitingRegistration]) waiter.dial(ua);
+      if (this.#registerAgain) {
+        this.#registerAgain = false;
+        this.#refreshRegistration(ua);
+        return;
+      }
+      if (this.#offerWait) this.#armNoInviteTimer();
+    });
     ua.on("registrationFailed", (e) => {
+      if (run !== this.#run) return;
       const detail = e;
+      if (isRefusal(detail) && this.#retryOnFreshCredentials("rejected", ua, credentials)) return;
       this.#reportError("net/registration-failed", {
         cause: detail?.cause,
         status: detail?.response?.status_code,
         domain: this.#domain,
         hint: "A bare 401 with no auth challenge usually means the registrar is in the wrong datacenter (SPEC \xA73.1)."
       });
+      if (ua !== this.#ua) return;
+      if (this.#carriesCall()) {
+        for (const waiter of [...this.#awaitingRegistration]) waiter.fail();
+        this.#registration = "registered";
+        const wait = this.#offerWait;
+        if (wait) {
+          this.#pendingOffer = { from: wait.from || null, at: wait.at };
+          this.#endOfferWait();
+        }
+        return;
+      }
       this.#teardownUA();
-      void this.#refreshSignal();
     });
     this.#ua = ua;
+    this.#registration = "connecting";
     ua.start();
     return ua;
   }
+  /**
+   * The credentials behind `ua` did not work. The provider hears it either way, with the credentials in question
+   * (it forgets them unless it has moved on from them already; a provider whose signal shares them renews that
+   * too); then, if it has new ones to give, the current UA is rebuilt on them — once until a registration works,
+   * and never under a live call. Whoever waited on the old UA — an offer, a dial — waits on the new one. Returns
+   * whether it was rebuilt.
+   *
+   * This replaces the engine's old `#refreshSignal` (a close-then-reopen of the push socket after ANY failed
+   * registration): only the provider knows what its credentials and its signal share.
+   */
+  #retryOnFreshCredentials(reason, ua, credentials) {
+    const fresh = this.provider.credentialsFailed?.(reason, credentials) ?? false;
+    if (!fresh || ua !== this.#ua || this.#freshCredentialsTried) return false;
+    if (this.#carriesCall()) return false;
+    this.#freshCredentialsTried = true;
+    const run = this.#run;
+    this.#teardownUA({ replacing: true });
+    const epoch = this.#uaEpoch;
+    void this.#ensureUA().catch(() => {
+      if (run === this.#run && epoch === this.#uaEpoch) this.#teardownUA();
+    });
+    return true;
+  }
   #uaConfig(credentials, factory) {
     return {
       sockets: [factory.createWebSocket(credentials.wsUrl)],
@@ -659,20 +1074,133 @@ var SipCallEngine = class {
       user_agent: this.provider.quirks?.userAgent ?? "Coventia Softphone"
     };
   }
-  #teardownUA() {
+  /**
+   * Lets the current UA go — and one still being provisioned (`#uaEpoch`). `replacing`: a successor is being
+   * built on fresh credentials right away (`#retryOnFreshCredentials`), so the dials and the offer waiting on
+   * this one carry over to it instead of ending here.
+   */
+  #teardownUA({ replacing = false } = {}) {
+    this.#uaEpoch += 1;
     this.#uaInFlight = null;
-    if (!this.#ua) return;
-    try {
-      this.#ua.terminateSessions({ status_code: 487 });
-      this.#ua.stop();
-    } catch {
+    this.#registration = "connecting";
+    this.#registerAgain = false;
+    if (!replacing) {
+      for (const waiter of [...this.#awaitingRegistration]) waiter.fail();
+      this.#endOfferWait();
     }
+    if (!this.#ua) return;
+    const ua = this.#ua;
     this.#ua = null;
     this.#activeCall = null;
     this.#consultCall = null;
+    try {
+      ua.terminateSessions({ status_code: 487 });
+    } catch {
+    }
+    if (this.#owedCancels.some((owed) => owed.ua === ua)) {
+      this.#linger(ua);
+      return;
+    }
+    try {
+      ua.stop();
+    } catch {
+    }
+  }
+  // ── the CANCEL a hang-up still owes (incoming-call-reliability.md §4.7, F6) ─────────────────────────────
+  /**
+   * Watches an outbound leg — a call or a consult leg — from its creation, for the CANCEL JsSIP may end up owing.
+   *
+   * JsSIP's `terminate()` between sending the INVITE and the first provisional response cannot cancel yet (RFC 3261
+   * §9.1): it marks the session canceled, fails it locally with `Canceled`, and sends the CANCEL when a 1xx comes —
+   * or ACKs and BYEs a late 2xx. Live, that 1xx came 17 s late, the engine had torn the UA down on the call's end, and
+   * the callee's phone rang on for a caller who was gone: a ghost call. Hence: the INVITE went out (`sending`), no
+   * provisional above 100 came (`progress`), and it failed locally `Canceled` → the CANCEL is owed, on this UA.
+   *
+   * Registered BEFORE the leg's own listeners: its `failed` must be on record before the leg's end tears the UA down.
+   */
+  #watchOwedCancel(session, ua) {
+    let sent = false;
+    let ringing = false;
+    session.on("sending", () => sent = true);
+    session.on("progress", () => ringing = true);
+    session.on("failed", ({ originator, cause }) => {
+      if (!sent || originator !== "local" || cause !== "Canceled") return;
+      const tx = inviteTransactionOf(session);
+      const owes = deferredCancelOf(session) ?? (tx ? tx.state === ICT_CALLING : !ringing);
+      if (!owes || tx && !awaitsAnswer(tx)) return;
+      const owed = { ua, session, tx };
+      this.#owedCancels.push(owed);
+      if (tx) this.#followInvite(owed, tx);
+    });
+  }
+  /**
+   * Follows the INVITE an owed CANCEL is waiting on, until it is over. Not just the first one: Zadarma challenges every
+   * INVITE (407), and JsSIP re-sends it with credentials on a NEW transaction — canceled leg or not — in the same tick
+   * that completes the first. Releasing on that first transaction stopped the UA two seconds later, and the re-sent
+   * INVITE's 1xx landed nowhere: the ghost call again (found driving the real JsSIP). So once one is over, the leg's
+   * current transaction is read again a moment later, and followed while it still waits for an answer.
+   */
+  #followInvite(owed, tx) {
+    const settle = () => {
+      if (awaitsAnswer(tx)) return;
+      tx.removeListener?.("stateChanged", settle);
+      queueMicrotask(() => {
+        const latest = inviteTransactionOf(owed.session);
+        if (latest && latest !== tx && awaitsAnswer(latest)) {
+          owed.tx = latest;
+          this.#followInvite(owed, latest);
+          return;
+        }
+        this.#owedCancels = this.#owedCancels.filter((other) => other !== owed);
+        this.#releaseIfSettled(owed.ua);
+      });
+    };
+    tx.on("stateChanged", settle);
+  }
+  /**
+   * Lets `ua` go while it owes a CANCEL: un-REGISTERed at once, as any teardown, but connected until every INVITE it
+   * owes is over — COMPLETED (a final non-2xx: the 487 after the late 1xx's CANCEL), ACCEPTED (a late 2xx, which
+   * JsSIP ACKs and BYEs) or TERMINATED (Timer B, a transport error) — and never longer than Timer B. Detached: the
+   * engine has already moved on (a push or a dial builds a fresh UA), so no timer of its own, no teardown and no
+   * "is a call on it" ever sees this one, and an INVITE reaching it is declined like any let-go UA's.
+   */
+  #linger(ua) {
+    if (this.#lingering.has(ua)) return;
+    this.#lingering.set(ua, setTimeout(() => this.#release(ua), INVITE_TRANSACTION_MAX_MS));
+    ua.on("registered", () => {
+      if (this.#lingering.has(ua)) this.#unregister(ua);
+    });
+    this.#unregister(ua);
+    this.#releaseIfSettled(ua);
+  }
+  #unregister(ua) {
+    try {
+      ua.unregister();
+    } catch {
+    }
+  }
+  /**
+   * Once nothing is owed on a lingering UA, it stops — on the next tick: a late 2xx is ACKed and BYEd in the very
+   * tick that settled it, and JsSIP's own `stop()` then keeps the transport ≤ 2 s for that BYE's answer.
+   */
+  #releaseIfSettled(ua) {
+    if (!this.#lingering.has(ua) || this.#owedCancels.some((owed) => owed.ua === ua)) return;
+    setTimeout(() => this.#release(ua), 0);
+  }
+  #release(ua) {
+    const cap = this.#lingering.get(ua);
+    if (cap === void 0) return;
+    clearTimeout(cap);
+    this.#lingering.delete(ua);
+    this.#owedCancels = this.#owedCancels.filter((owed) => owed.ua !== ua);
+    try {
+      ua.stop();
+    } catch {
+    }
   }
-  /** Place a call once the UA is registered (its 200 OK for REGISTER has arrived). */
   /**
+   * Place a call once the current UA is registered (its 200 OK for REGISTER has arrived).
+   *
    * **No `mediaStream`** — JsSIP calls `getUserMedia` itself, which is what opens a real capture.
    *
    * That is load-bearing, not incidental. Firefox restricts ICE gathering on a page with no active
@@ -682,20 +1210,46 @@ var SipCallEngine = class {
    * contains no candidates. The legacy hook passed `mediaConstraints` and nothing else, for what
    * turns out to be a very good reason.
    */
-  #callWhenRegistered(ua, target) {
+  #callWhenRegistered(target, run) {
     const options = { mediaConstraints: buildAudioConstraints(this.#inputDeviceId), pcConfig: PC_CONFIG };
-    if (ua.isRegistered()) return Promise.resolve(ua.call(target, options));
-    return new Promise((resolve) => {
-      ua.on("registered", () => resolve(ua.call(target, options)));
+    const refusal = () => createError(run === this.#run ? "call/failed" : "engine/not-started");
+    const dial = (registered) => {
+      const session = registered.call(target, options);
+      this.#watchOwedCancel(session, registered);
+      return this.#wrapCall(session);
+    };
+    const ua = this.#ua;
+    if (!ua || run !== this.#run) return Promise.reject(refusal());
+    if (ua.isRegistered()) return Promise.resolve(dial(ua));
+    return new Promise((resolve, reject) => {
+      const waiter = {
+        dial: (registered) => {
+          this.#awaitingRegistration.delete(waiter);
+          try {
+            resolve(dial(registered));
+          } catch (cause) {
+            reject(cause);
+          }
+        },
+        fail: () => {
+          this.#awaitingRegistration.delete(waiter);
+          reject(refusal());
+        }
+      };
+      this.#awaitingRegistration.add(waiter);
     });
   }
-  #wrapCall(session) {
+  /**
+   * `since`, for an inbound call: when its push came (its INVITE, when none was seen) — what `#onDecline` needs to
+   * tell this call from the caller's others.
+   */
+  #wrapCall(session, since = this.now()) {
     const call = new SipEngineCall(session, {
       id: nextCallId(),
       buildTarget: (t) => this.#buildTarget(t),
       placeConsult: (t) => this.#placeConsult(t),
       // The guard is tied to the reject ACTION, not to `ended` — a normal hangup must not arm it.
-      onReject: () => this.#startRejectGuard(),
+      onReject: () => this.#onDecline(call, since),
       iceGatheringCapMs: this.provider.quirks?.iceGatheringCapMs ?? DEFAULT_ICE_CAP_MS,
       // Inbound answers open their own peer connection, so they need the same ICE servers the
       // outbound leg got. Missing here, an ANSWERED call is the one that fails — the half nobody
@@ -712,17 +1266,27 @@ var SipCallEngine = class {
         const code = missed ? "call/missed" : CALL_END_CODES[event.reason];
         if (code) this.#reportError(code, event.cause);
         if (this.#activeCall === call) this.#activeCall = null;
-        this.#maybeTeardownUA();
+        this.#legEnded();
       }
     });
     return call;
   }
+  /**
+   * A leg ended. The UA goes if nothing is left on it (`#maybeTeardownUA`); and once no leg at all is left, an
+   * offer kept through the call (`#pendingOffer`, §4.3) gets its REGISTER — the line is free now.
+   */
+  #legEnded() {
+    const pending = this.#activeCall || this.#consultCall ? null : this.#takePendingOffer();
+    this.#maybeTeardownUA();
+    if (pending) void this.#onOffer(pending.from, pending.at);
+  }
   async #placeConsult(target) {
     const ua = await this.#ensureUA();
     const consultSession = ua.call(this.#buildTarget(target), {
       mediaConstraints: buildAudioConstraints(this.#inputDeviceId),
       pcConfig: PC_CONFIG
     });
+    this.#watchOwedCancel(consultSession, ua);
     const consultCall = new SipEngineCall(consultSession, {
       id: nextCallId(),
       buildTarget: (x) => this.#buildTarget(x),
@@ -733,7 +1297,7 @@ var SipCallEngine = class {
     consultCall.onEvent((event) => {
       if (event.type === "ended") {
         if (this.#consultCall === consultCall) this.#consultCall = null;
-        this.#maybeTeardownUA();
+        this.#legEnded();
       }
     });
     return consultCall;
@@ -746,19 +1310,29 @@ var SipCallEngine = class {
    * session on it, via `terminateSessions`) the instant the main leg's `ended` fires killed that
    * consult leg out from under the transfer before the bridge could use it, and the caller was simply
    * gone. Two real call sites hit this independently (found live, 2026-08-04): the main leg's own
-   * `ended` handler, and `#armNoInviteTeardown`'s 5s timer — the latter re-arms on EVERY push,
-   * including unrelated "answered" pushes Zadarma sends around other account activity, so it can fire
-   * minutes after a transfer with no `#activeCall` and no idea a consult leg is mid-handoff. Both now
-   * route through here rather than checking `#activeCall` alone.
+   * `ended` handler, and the no-INVITE timer — which then re-armed on EVERY push, including the
+   * `answered` pushes Zadarma sends around other account activity, so it could fire minutes after a
+   * transfer with no `#activeCall` and no idea a consult leg was mid-handoff. Every teardown an offer
+   * asks for (its timers, its `offer-ended`) routes through here rather than checking `#activeCall` alone.
+   *
+   * A dial on its way (`#dialing`) counts too: its UA may not even exist yet, and an offer ending must not
+   * take it. So does an offer still waiting for its INVITE: mid-transfer, with only the consult leg left, an
+   * offer registers on this UA — and the consult leg ending used to tear it down and drop that offer, its call
+   * ringing nowhere until the provider offered it again ~30 s later. The wait's own ending (its INVITE, its
+   * `offer-ended`, the no-INVITE timer, the leak guard) clears `#offerWait` before it calls this, so nothing keeps
+   * the UA past those (incoming-call-reliability.md §4.3).
    */
   #maybeTeardownUA() {
     if (this.provider.registrationMode !== "on-demand") return;
-    if (this.#activeCall || this.#consultCall) return;
+    if (this.#activeCall || this.#consultCall || this.#dialing > 0 || this.#offerWait) return;
     this.#teardownUA();
   }
-  #startRejectGuard() {
-    const ms = this.provider.quirks?.rejectGuardMs;
-    if (ms) this.#rejectGuardUntil = this.now() + ms;
+  /**
+   * A live leg is on the current UA: the call or a consult leg. An outbound call counts from the moment its INVITE
+   * is created — `#callWhenRegistered` wraps it there and then — so no failure in between can end it unseen.
+   */
+  #carriesCall() {
+    return this.#activeCall !== null || this.#consultCall !== null;
   }
   #buildTarget(target) {
     return target.includes("@") ? target : `sip:${target}@${this.#domain}`;
@@ -789,6 +1363,8 @@ async function loadJsSipFactory() {
 // src/transports/providers/zadarma.ts
 var PING = { localMs: 3e4, globalMs: 6e4 };
 var KEY_REFRESH_BUFFER_MS = 2 * 60 * 60 * 1e3;
+var KEY_EXPIRY_MARGIN_MS = 6e4;
+var REKEY_DEBOUNCE_MS = 3e4;
 var REBUILD_CONNECT_TIMEOUT_MS = 1e4;
 var REBUILD_RETRY_MS = 3e4;
 var ZADARMA_QUIRKS = {
@@ -796,10 +1372,17 @@ var ZADARMA_QUIRKS = {
   // after a valid digest challenge, indistinguishable from a wrong password (§3.1). The old CRM
   // hook carried this string; the port dropped it, and registration failed for exactly that reason.
   userAgent: "Zadarma webRTC",
-  // Zadarma re-rings a declined call for ~30 s (return_timeout). Swallow those (§3.4).
+  // Zadarma re-offers a declined call until its ring time ends (~30 s by default): the declined caller's offers
+  // are ignored while that call lives — this long after the decline when the backend cannot say (§3.4,
+  // incoming-call-reliability.md §4.4, Q1).
+  declinedCallerGuardMs: 35e3,
+  // The INVITE follows the REGISTER's 200 OK by ~0.1 s. Nothing 10 s after it: no call is coming to this UA.
+  noInviteAfterRegisterMs: 1e4,
+  // A leak guard only: an offer still waiting for its INVITE 2 min after its push is abandoned (§4.3).
+  offerWaitMaxMs: 12e4,
+  // Deprecated names of the two above, same values: this object is exported, and 0.5.1 is a patch. Never read.
   rejectGuardMs: 35e3,
-  // A push is not an INVITE (§3.3). If none arrives, tear the fresh UA down.
-  noInviteTeardownMs: 5e3,
+  noInviteTeardownMs: 1e4,
   // A ceiling on ICE gathering, not a target: JsSIP sends as soon as gathering completes. 3 s leaves
   // room for a TURN allocation (whose relay candidates arrive last) while still bounding the ~40 s
   // Chrome can spend against an unreachable server. See `capIceGathering`.
@@ -809,11 +1392,154 @@ function buildPushUrl(key, sip) {
   const params = new URLSearchParams({ key, integrationType: "site", sipId: sip });
   return `wss://ws.zadarma.com/webrtc_pushes?${params.toString()}`;
 }
-var ZadarmaPushSignal = class {
+function readPush(payload) {
+  let data = payload;
+  if (typeof data === "string") {
+    try {
+      data = JSON.parse(data);
+    } catch {
+      return { kind: "other", detail: "unreadable payload" };
+    }
+  }
+  if (!data || typeof data !== "object") return { kind: "other", detail: "no payload" };
+  const { action, callerid } = data;
+  let from = null;
+  if (typeof callerid === "string" && callerid) from = callerid;
+  else if (typeof callerid === "number") from = String(callerid);
+  if (action === "incoming") return { kind: "offer", from };
+  if (action === "answered") return { kind: "offer-ended", from };
+  return { kind: "other", detail: typeof action === "string" ? `action "${action}"` : "no action" };
+}
+function expiryOf(key) {
+  if (!key.keyExpiresAt) return null;
+  const at = new Date(key.keyExpiresAt).getTime();
+  return Number.isFinite(at) ? at : null;
+}
+var ZadarmaCredentials = class {
   constructor(deps) {
     this.deps = deps;
   }
   deps;
+  #key = null;
+  #keyInFlight = null;
+  #sip = null;
+  #sipInFlight = null;
+  /**
+   * Bumped by `forget`, one per half: a fetch begun before it must not put back what was just forgotten — a
+   * refused credential that comes back from a slow request is still refused.
+   */
+  #keyGeneration = 0;
+  #sipGeneration = 0;
+  /**
+   * The SIP credentials were already refetched once because their WSS could not be reached: if the fresh ones
+   * cannot reach it either, the network is the problem, and asking Zadarma again would not change it. Re-armed by
+   * a registration that works (`worked`), and by forgetting everything (a refusal, a stop).
+   */
+  #unreachableRefetched = false;
+  /** What is in memory right now — both halves, for one key — or `null`. Never fetches. */
+  current() {
+    const key = this.#key?.value;
+    const sip = this.#sip;
+    return key && sip && sip.forKey === key.key ? { key, pass: sip.pass, domain: sip.domain } : null;
+  }
+  /** Their WSS could not be reached: forget the SIP half — once, until `worked()`. Whether it was forgotten. */
+  forgetUnreachable() {
+    if (this.#unreachableRefetched) return false;
+    this.forget("sip");
+    this.#unreachableRefetched = true;
+    return true;
+  }
+  /** A registration worked with what is in memory. */
+  worked() {
+    this.#unreachableRefetched = false;
+  }
+  /** The cached key while it is alive; otherwise a fresh one (and, in the background, its SIP credentials). */
+  key() {
+    const cached2 = this.#key;
+    if (cached2 && (cached2.expiresAt === null || Date.now() < cached2.expiresAt - KEY_EXPIRY_MARGIN_MS)) {
+      return Promise.resolve(cached2.value);
+    }
+    return this.#fetchKey();
+  }
+  /** A new key now, whatever is cached: the refresh ahead of expiry. The old one serves until this one lands. */
+  renew() {
+    return this.#fetchKey();
+  }
+  /** The key and the SIP credentials it bought, from memory when they are there. */
+  async sip() {
+    const key = await this.key();
+    const { pass, domain } = await this.#sipFor(key);
+    return { key, pass, domain };
+  }
+  /** Synchronous up to the request, so a prefetch and a `provision()` racing it share one exchange. */
+  #sipFor(key) {
+    const cached2 = this.#sip;
+    if (cached2 && cached2.forKey === key.key) return Promise.resolve({ pass: cached2.pass, domain: cached2.domain });
+    const inFlight = this.#sipInFlight;
+    if (inFlight && inFlight.forKey === key.key) return inFlight.promise;
+    const generation = this.#sipGeneration;
+    let request;
+    try {
+      request = this.deps.exchangeWebphoneData(key.key, key.sip);
+    } catch (cause) {
+      request = Promise.reject(cause instanceof Error ? cause : new Error(String(cause)));
+    }
+    const promise = request.then((data) => {
+      if (generation === this.#sipGeneration) this.#sip = { forKey: key.key, pass: data.pass, domain: data.domain };
+      return data;
+    });
+    const entry = { forKey: key.key, promise };
+    this.#sipInFlight = entry;
+    void promise.finally(() => {
+      if (this.#sipInFlight === entry) this.#sipInFlight = null;
+    }).catch(() => {
+    });
+    return promise;
+  }
+  /**
+   * Drop what stopped working. `all`: the registrar refused the credentials, so the key behind them may be the
+   * stale part too. `sip`: their WSS could not be reached — the key is fine, the datacenter may not be.
+   */
+  forget(what) {
+    this.#sipGeneration += 1;
+    this.#sip = null;
+    this.#sipInFlight = null;
+    if (what === "sip") return;
+    this.#keyGeneration += 1;
+    this.#key = null;
+    this.#keyInFlight = null;
+    this.#unreachableRefetched = false;
+  }
+  #fetchKey() {
+    if (this.#keyInFlight) return this.#keyInFlight;
+    const generation = this.#keyGeneration;
+    const inFlight = this.deps.fetchKey().then((value) => {
+      if (generation === this.#keyGeneration) {
+        this.#key = { value, expiresAt: expiryOf(value) };
+        void this.#sipFor(value).catch(() => {
+        });
+      }
+      return value;
+    });
+    this.#keyInFlight = inFlight;
+    void inFlight.finally(() => {
+      if (this.#keyInFlight === inFlight) this.#keyInFlight = null;
+    }).catch(() => {
+    });
+    return inFlight;
+  }
+};
+var ZadarmaPushSignal = class {
+  /**
+   * `credentials` is shared with the provider's `provision()`: one key for the push socket and the SIP
+   * credentials, fetched once (§4.5). A signal on its own gets a cache of its own.
+   */
+  constructor(deps, credentials = new ZadarmaCredentials(deps)) {
+    this.deps = deps;
+    this.credentials = credentials;
+  }
+  deps;
+  credentials;
   #socket = null;
   #connected = false;
   #pingTimers = [];
@@ -826,6 +1552,20 @@ var ZadarmaPushSignal = class {
   #retryTimer;
   #unwatchBackground;
   #closed = false;
+  /**
+   * Bumped by `disconnect()`. An open or a rebuild still awaiting its key when the signal is disconnected
+   * must build nothing afterwards — and `#closed` alone cannot say so once a later `connect()` (stop, then
+   * start again) has reset it: the late socket was built beside the new one, and nothing ever closed it.
+   */
+  #run = 0;
+  /**
+   * The key is due for its refresh (`#armRefresh`): the next rebuild fetches a new one instead of reusing the
+   * cached one — and keeps trying, on every retry and every hidden-tab tick, until one arrives.
+   */
+  #renewDue = false;
+  /** A rebuild asked for (`rekey`) while another was in flight: it runs once that one ends. */
+  #rekeyQueued = false;
+  #rekeyAfter = 0;
   #listeners = /* @__PURE__ */ new Set();
   #connectionListeners = /* @__PURE__ */ new Set();
   async connect() {
@@ -834,9 +1574,26 @@ var ZadarmaPushSignal = class {
     this.#unwatchBackground ??= this.deps.watchBackgroundReconnect?.(() => void this.#reopen());
     await this.#open();
   }
+  /**
+   * The registrar refused credentials bought with this socket's key, and the provider has forgotten them: the
+   * socket is rebuilt on a fresh key, make-before-break like every rebuild (`#reopen`).
+   *
+   * Debounced: a registrar refusing every attempt must not become a tight loop against our backend and
+   * Zadarma's. This rebuild used to be the engine's (`#refreshSignal`, a close-then-open); it lives here now
+   * because only the provider knows the push socket and the SIP credentials share one key.
+   */
+  rekey() {
+    if (this.#closed || !this.#socket) return;
+    const now = Date.now();
+    if (now < this.#rekeyAfter) return;
+    this.#rekeyAfter = now + REKEY_DEBOUNCE_MS;
+    if (this.#rebuilding) this.#rekeyQueued = true;
+    else void this.#reopen();
+  }
   async #open() {
-    const { key, sip, keyExpiresAt } = await this.deps.fetchKey();
-    if (this.#closed) return;
+    const run = this.#run;
+    const { key, sip, keyExpiresAt } = await this.credentials.key();
+    if (run !== this.#run) return;
     const socket = this.deps.createPushSocket(buildPushUrl(key, sip));
     this.#socket = socket;
     this.#attach(socket);
@@ -846,8 +1603,8 @@ var ZadarmaPushSignal = class {
    * Wires one socket's events. `this.#socket` is read when an event FIRES, not when it is wired: a socket that
    * has been replaced must stop driving connectivity (our own `close()` of it emits `disconnect`, which would
    * otherwise flip the state to offline right after a perfectly healthy swap). `update` is the exception — it is
-   * forwarded from any socket not yet closed, because a push seen twice is harmless (the engine ignores a
-   * repeated signal mid-call and reuses a UA that already exists) while one seen by neither is a missed call.
+   * forwarded from any socket not yet closed, because a push seen twice is harmless (the engine ignores an offer
+   * mid-call, and a second one only sends one more REGISTER) while one seen by neither is a missed call.
    *
    * With `hooks`, the socket is a rebuild's candidate: its first `connect` or failure goes to the rebuild instead
    * of changing the connection state (it is not current yet).
@@ -859,7 +1616,7 @@ var ZadarmaPushSignal = class {
       this.#setConnected(true);
       this.#startPings(socket);
     });
-    socket.on("update", () => this.#emit());
+    socket.on("update", (payload) => this.#emit(readPush(payload)));
     const lost = () => {
       if (hooks && socket === this.#candidate) return hooks.onFailure();
       if (socket !== this.#socket) return;
@@ -898,13 +1655,19 @@ var ZadarmaPushSignal = class {
    * given at construction. A tab left open past the key's 72 h lifetime would reconnect forever with
    * a dead credential. Absolute, from the backend's `key_expires_at`, so it targets the real expiry
    * rather than restarting a countdown on every reconnect.
+   *
+   * It is also the refresh of the shared credentials (incoming-call-reliability.md §4.5): the new key replaces
+   * the cached one, and its SIP credentials are fetched with it, in the background — no call waits for either.
    */
   #armRefresh(keyExpiresAt) {
     clearTimeout(this.#refreshTimer);
     if (!keyExpiresAt) return;
     const ms = new Date(keyExpiresAt).getTime() - Date.now() - KEY_REFRESH_BUFFER_MS;
     if (!Number.isFinite(ms) || ms <= 0) return;
-    this.#refreshTimer = setTimeout(() => void this.#reopen(), ms);
+    this.#refreshTimer = setTimeout(() => {
+      this.#renewDue = true;
+      void this.#reopen();
+    }, ms);
   }
   /**
    * Replaces the push socket with a fresh one — MAKE-BEFORE-BREAK (presence-client-reporting.md §4.1, T8).
@@ -920,6 +1683,9 @@ var ZadarmaPushSignal = class {
    * throws, the socket errors, or it has not connected within `REBUILD_CONNECT_TIMEOUT_MS` — keeps the old socket
    * and retries, instead of leaving the tab disconnected. Zadarma does not evict the older of two sockets for one
    * sip (multi-tab-leader-election.md §1), so the overlap is safe.
+   *
+   * The key comes from the shared cache — a hidden-tab tick makes no request — unless it is due for its refresh
+   * (`#renewDue`) or has been forgotten after a refused registration (`rekey`).
    */
   async #reopen() {
     if (this.#closed || this.#rebuilding) return;
@@ -931,9 +1697,11 @@ var ZadarmaPushSignal = class {
       return;
     }
     this.#rebuilding = true;
+    const run = this.#run;
     try {
-      const { key, sip, keyExpiresAt } = await this.deps.fetchKey();
-      if (this.#closed) return;
+      const { key, sip, keyExpiresAt } = await (this.#renewDue ? this.credentials.renew() : this.credentials.key());
+      if (run !== this.#run) return;
+      this.#renewDue = false;
       const swapped = await new Promise((resolve) => {
         const socket = this.deps.createPushSocket(buildPushUrl(key, sip));
         this.#candidate = socket;
@@ -961,6 +1729,10 @@ var ZadarmaPushSignal = class {
     } finally {
       this.#rebuilding = false;
     }
+    if (this.#rekeyQueued) {
+      this.#rekeyQueued = false;
+      void this.#reopen();
+    }
   }
   /**
    * The moment of the swap — synchronous, called from the candidate's own `connect` event so nothing can run
@@ -984,8 +1756,17 @@ var ZadarmaPushSignal = class {
     clearTimeout(this.#retryTimer);
     this.#retryTimer = setTimeout(() => void this.#reopen(), REBUILD_RETRY_MS);
   }
+  /**
+   * Closes everything — and forgets the credentials: this is how the engine stops, and a phone that is off holds
+   * no SIP password. The next `connect()` fetches them again.
+   */
   disconnect() {
     this.#closed = true;
+    this.#run += 1;
+    this.#renewDue = false;
+    this.#rekeyQueued = false;
+    this.#rekeyAfter = 0;
+    this.credentials.forget("all");
     this.#stopPings();
     clearTimeout(this.#refreshTimer);
     this.#refreshTimer = void 0;
@@ -1014,16 +1795,11 @@ var ZadarmaPushSignal = class {
     this.#connected = connected;
     for (const listener of [...this.#connectionListeners]) listener(connected);
   }
-  #emit() {
-    for (const listener of [...this.#listeners]) listener();
+  #emit(event) {
+    for (const listener of [...this.#listeners]) listener(event);
   }
 };
 var ZadarmaProvider = class {
-  constructor(deps) {
-    this.deps = deps;
-    this.incomingSignal = new ZadarmaPushSignal(deps);
-  }
-  deps;
   name = "zadarma";
   // Zadarma's PBX ignores a standing registration — it routes INVITEs only to a UA that registered
   // in response to a push (SPEC §3.2). Hence on-demand.
@@ -1031,21 +1807,60 @@ var ZadarmaProvider = class {
   quirks = ZADARMA_QUIRKS;
   incomingSignal;
   /**
-   * Per-registration credentialing: fetch a scoped key, then exchange it in the browser for
-   * ephemeral SIP creds. The key fetch is cheap and backend-cached; doing it here (rather than
-   * sharing state with the push signal) keeps the two paths independent.
+   * One key and one set of SIP credentials for the push socket and every registration (§4.5). Its "unreachable
+   * refetched once" mark lives there too, so a stop — which forgets the credentials — clears it as well.
+   */
+  #credentials;
+  #signal;
+  constructor(deps) {
+    this.#credentials = new ZadarmaCredentials(deps);
+    this.#signal = new ZadarmaPushSignal(deps, this.#credentials);
+    this.incomingSignal = this.#signal;
+  }
+  /**
+   * The SIP credentials, from memory (incoming-call-reliability.md §4.5). They were fetched when the push socket
+   * opened — the key from our backend, then `{ pass, domain }` from Zadarma, in the browser for the geo-routing
+   * (SPEC §3.1) — so a push goes straight to the WSS and the REGISTER. Fetched here only when they are not there:
+   * the background fetch failed, or they were forgotten (`credentialsFailed`).
    */
   async provision() {
-    const { key, sip } = await this.deps.fetchKey();
-    const { pass, domain } = await this.deps.exchangeWebphoneData(key, sip);
-    return {
-      uri: `sip:${sip}@${domain}`,
-      authUser: sip,
-      password: pass,
-      wsUrl: `wss://${domain}:4443`
-    };
+    return toSipCredentials(await this.#credentials.sip());
+  }
+  /**
+   * `rejected` (401/403): the key may be the stale part, so both are forgotten, and the push socket — which
+   * holds the same key — is rebuilt on a fresh one. `unreachable`: only the SIP credentials, and only once
+   * until a registration works: Zadarma may have moved this browser to another datacenter (SPEC §3.1).
+   *
+   * Only if `credentials` — the ones that failed — are still what is in memory: a UA let go of earlier can report
+   * late, when the cache has already moved on to fresh ones, and those must not be thrown away for it.
+   */
+  credentialsFailed(reason, credentials) {
+    if (credentials && !this.#holds(credentials)) return true;
+    if (reason === "rejected") {
+      this.#credentials.forget("all");
+      this.#signal.rekey();
+      return true;
+    }
+    return this.#credentials.forgetUnreachable();
+  }
+  credentialsWorked() {
+    this.#credentials.worked();
+  }
+  #holds(credentials) {
+    const current = this.#credentials.current();
+    if (!current) return false;
+    const held = toSipCredentials(current);
+    return held.uri === credentials.uri && held.authUser === credentials.authUser && held.password === credentials.password;
   }
 };
+function toSipCredentials({ key, pass, domain }) {
+  return {
+    uri: `sip:${key.sip}@${domain}`,
+    authUser: key.sip,
+    password: pass,
+    wsUrl: `wss://${domain}:4443`
+  };
+}
 
 // src/core/token-cache.ts
 var SKEW_MS = 6e4;
@@ -1086,6 +1901,23 @@ function invalidateToken(source) {
 // src/transports/providers/zadarma-browser.ts
 var UnauthorizedKeyError = class extends Error {
 };
+var KeyFetchError = class extends Error {
+  constructor(message, status, retryAfterMs) {
+    super(message);
+    this.status = status;
+    this.retryAfterMs = retryAfterMs;
+  }
+  status;
+  retryAfterMs;
+};
+function retryAfterMsOf(res) {
+  const value = res.headers?.get?.("retry-after");
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  const at = Date.parse(value);
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : void 0;
+}
 function makeFetchKey(config) {
   const attempt = async () => {
     let token;
@@ -1101,7 +1933,7 @@ function makeFetchKey(config) {
     if (!res.ok) {
       const body = await res.json().catch(() => null);
       const message = body?.message ?? `webrtc/key HTTP ${res.status}`;
-      throw res.status === 401 ? new UnauthorizedKeyError(message) : new Error(message);
+      throw res.status === 401 ? new UnauthorizedKeyError(message) : new KeyFetchError(message, res.status, retryAfterMsOf(res));
     }
     const data = await res.json();
     return {
@@ -1256,10 +2088,24 @@ function makeZadarmaBrowserDeps(config) {
   };
 }
 
+// src/core/api-base.ts
+function normalizeApiBase(url) {
+  const trimmed = url.replace(/\/+$/, "");
+  if (!trimmed.endsWith("/api/v1")) return trimmed;
+  console.warn(
+    "[softphone] apiBase should be Coventia's domain only, without /api/v1. Ignoring the /api/v1 suffix."
+  );
+  return trimmed.slice(0, -"/api/v1".length).replace(/\/+$/, "");
+}
+
 // src/transports/zadarma-engine.ts
 function createZadarmaEngine(config) {
   const provider = new ZadarmaProvider(
-    makeZadarmaBrowserDeps({ ...config, tokenSource: cachedTokenSource(config.tokenSource) })
+    makeZadarmaBrowserDeps({
+      ...config,
+      apiBase: normalizeApiBase(config.apiBase),
+      tokenSource: cachedTokenSource(config.tokenSource)
+    })
   );
   return new SipCallEngine(provider, loadJsSipFactory);
 }