@securecoms/agent-bridge 0.5.0 → 0.7.0

package/dist/index.js

@@ -1,3 +1,12 @@
+// ../connect-core/dist/cadence.js
+var SELF_HEAL_SWEEP_INTERVAL_MS = 9e4;
+var SELF_HEAL_SWEEP_JITTER_MS = 3e4;
+var REQUEST_WELCOME_COOLDOWN_MS = 12e4;
+var WORST_CASE_RESIGNAL_MS = Math.ceil(REQUEST_WELCOME_COOLDOWN_MS / SELF_HEAL_SWEEP_INTERVAL_MS) * (SELF_HEAL_SWEEP_INTERVAL_MS + SELF_HEAL_SWEEP_JITTER_MS);
+function isResignalDue(now, lastAt, cooldownMs = REQUEST_WELCOME_COOLDOWN_MS) {
+  return now - lastAt >= cooldownMs;
+}
+
 // ../connect-core/dist/envelope/types.js
 var MESSAGE_TYPES = [
   "text",
@@ -1326,6 +1335,23 @@ var MlsGroupKeyProvider = class {
    *  server delete-and-replaces. Keyed by deviceId (a provider has one), SEPARATE
    *  from `locks` (channel-keyed) so it never deadlocks against a held channel lock. */
   publishLock = new MlsOperationQueue();
+  /**
+   * M6 (ADR-0013 Decision H): wall-clock ms of the last SUCCESSFUL decrypt per
+   * channel. This is the only evidence-based liveness signal the member has —
+   * every other membership indicator in the daemon (`joinState`, a persisted
+   * store row, a leaf in the tree) is a structural artifact that a forked
+   * channel keeps asserting long after it stopped being able to read anything.
+   *
+   * ⚠️ Deliberately written OUTSIDE the `errors` map, and written BEFORE
+   * {@link recordDecryptSuccess}'s `if (!e) return` early-exit. That guard is
+   * correct for its own purpose (there is no error run to clear for a channel
+   * that never errored) but it means a healthy channel decrypting normally
+   * never touches `errors` at all. Keying this timestamp off that map would
+   * leave it null for exactly the channels that are working — a field that
+   * reports "no successful decrypt" for a healthy channel is worse than no
+   * field, because it inverts the signal it exists to give.
+   */
+  lastDecryptAt = /* @__PURE__ */ new Map();
   /**
    * Per-channel decrypt-error / stuck tracker (ADR-0002). Bounded by the number
    * of channels this device touches (channels are bounded; an entry is created
@@ -1390,6 +1416,7 @@ var MlsGroupKeyProvider = class {
    * re-wedges (the onWedged guard is reset so the hook can fire again).
    */
   recordDecryptSuccess(channelId) {
+    this.lastDecryptAt.set(channelId, Date.now());
     const e = this.errors.get(channelId);
     if (!e)
       return;
@@ -1537,7 +1564,9 @@ var MlsGroupKeyProvider = class {
    * equals newDeviceId (the same device re-admitted).
    */
   async admitGuestDevice(channelId, g) {
-    await this.addMemberToLiveGroup(channelId, g.newDeviceId);
+    await this.addMemberToLiveGroup(channelId, g.newDeviceId, {
+      knownLeafDevices: g.priorDeviceId ? [g.priorDeviceId] : []
+    });
     if (g.priorDeviceId && g.priorDeviceId !== g.newDeviceId) {
       const orderedDeviceIds = g.orderedDeviceIds ?? [g.priorDeviceId, g.newDeviceId];
       await this.removeDeviceFromLiveGroup(channelId, g.priorDeviceId, {
@@ -1562,6 +1591,85 @@ var MlsGroupKeyProvider = class {
   async currentEpoch(channelId) {
     return Number((await this.manager(channelId)).epoch);
   }
+  /**
+   * Converge a BEHIND member in place by replaying the commits it missed,
+   * instead of tearing down its session and being re-admitted.
+   *
+   * Ported from gen2 (#440). This is the primitive SecureComs was missing, and
+   * its absence is why divergence here has been effectively unrecoverable: the
+   * only client-side route back was Remove+Add, which gen2 treats as the
+   * LAST RESORT and rate-limits hard, because they measured it as a divergence
+   * SOURCE (#360 — epoch 1204 in ~6 minutes; "the re-admitter's churn IS the
+   * bug, not the member").
+   *
+   * Replay is strictly cheaper and safer than re-admission:
+   *   - no re-key, no roster change, no epoch movement at all
+   *   - it cannot storm the group, because it only READS
+   *   - it preserves the member's leaf, so it cannot create a duplicate
+   *
+   * The server already implements the whole contract
+   * (`GET /mls/groups/{id}/sync?last_epoch=N` → `{action, messages}`) and has
+   * since before this change. Nothing consumed it. That is the entire defect.
+   *
+   * Returns true when the member converged to the server's epoch. Returns false
+   * when the caller should fall back to re-admission — the gap exceeded the
+   * server's REJOIN_THRESHOLD, there was nothing to apply, or a commit would
+   * not apply (which means the state is genuinely FORKED, not merely behind,
+   * and replay cannot fix a fork).
+   */
+  async resyncByReplay(channelId, groupId) {
+    if (!await this.hasPersistedChannelState(channelId))
+      return false;
+    let from;
+    try {
+      from = await this.currentEpoch(channelId);
+    } catch {
+      return false;
+    }
+    const resp = await this.o.backend.syncGroup(groupId, from, this.o.deviceId);
+    if (resp.action !== "replay")
+      return false;
+    const commits = resp.messages.filter((m) => m.message_type === "commit").sort((a, b) => a.epoch - b.epoch);
+    if (commits.length === 0)
+      return false;
+    let applied = 0;
+    try {
+      await this.locks.run(channelId, async () => {
+        const mgr = await this.manager(channelId);
+        for (const c of commits) {
+          if (c.epoch <= Number(mgr.epoch))
+            continue;
+          await mgr.decrypt(hexToBytes(c.payload));
+          applied++;
+        }
+        if (applied > 0)
+          await this.o.store.save(channelId, mgr.exportState());
+      });
+    } catch (e) {
+      console.warn(`[mls] resyncByReplay ${channelId.slice(0, 8)}: commit failed to apply after ${applied} \u2014 state is forked, not behind:`, e?.message);
+      return false;
+    }
+    if (applied > 0) {
+      this.recordDecryptSuccess(channelId);
+    }
+    return applied > 0;
+  }
+  /**
+   * M6 (ADR-0013 Decision H): wall-clock ms of the last successful decrypt for
+   * `channelId`, or `undefined` if this process has never decrypted anything on
+   * it. Synchronous and allocation-free — it is read from the `/healthz` path,
+   * which must never fan out work, because the conditions it exists to report
+   * are exactly the conditions under which fanned-out work hangs.
+   *
+   * `undefined` is genuinely ambiguous and callers MUST NOT read it as
+   * "broken": it also covers a freshly-restarted daemon and a healthy channel
+   * that has simply been quiet. It is evidence of liveness when present, never
+   * evidence of divergence when absent. Divergence is decided by the held-vs-
+   * server epoch comparison, not by this field.
+   */
+  lastDecryptAtFor(channelId) {
+    return this.lastDecryptAt.get(channelId);
+  }
   /**
    * Run a committer op and, on ANY throw that escapes it, evict the channel's
    * cached MLSGroupManager.
@@ -1785,7 +1893,7 @@ var MlsGroupKeyProvider = class {
     if (!bundle)
       throw new Error("ensureSession: call publishKeyPackage() first");
     if (opts.forceReinit) {
-      const others = opts.otherDeviceIds ?? [];
+      const others = [...new Set(opts.otherDeviceIds ?? [])].filter((d) => d !== this.o.deviceId);
       const reinit = await this.o.backend.reinitConnectChannelGroup(channelId, [this.o.deviceId, ...others]);
       const mgr = new MLSGroupManager();
       await mgr.createGroup(new TextEncoder().encode(reinit.group_id), bundle);
@@ -1815,7 +1923,7 @@ var MlsGroupKeyProvider = class {
         throw new BootstrapRaceLostError();
       const mgr = new MLSGroupManager();
       await mgr.createGroup(new TextEncoder().encode(init.group_id), bundle);
-      const others = opts.otherDeviceIds ?? [];
+      const others = [...new Set(opts.otherDeviceIds ?? [])].filter((d) => d !== this.o.deviceId);
       const kps = await this.o.backend.fetchKeyPackages(others);
       const pkgs = others.map((d) => {
         const hex = kps[d];
@@ -1866,17 +1974,38 @@ var MlsGroupKeyProvider = class {
    * full member roster (unioning in any device ids we pass). That avoids a
    * parallel group_id-by-channel resolver.
    */
-  async addMemberToLiveGroup(channelId, newDeviceId) {
-    return this.locks.run(channelId, () => this.evictOnThrow(channelId, () => this.addMemberToLiveGroupUnlocked(channelId, newDeviceId, 0)));
+  async addMemberToLiveGroup(channelId, newDeviceId, opts) {
+    return this.locks.run(channelId, () => this.evictOnThrow(channelId, () => this.addMemberToLiveGroupUnlocked(channelId, newDeviceId, 0, opts)));
   }
   async addMemberToLiveGroupUnlocked(channelId, newDeviceId, _attempt, opts) {
     const mgr = await this.manager(channelId);
-    const init = await this.o.backend.initConnectChannelGroup(channelId, [this.o.deviceId, newDeviceId]);
     const kps = await this.o.backend.fetchKeyPackages([newDeviceId]);
     const hex = kps[newDeviceId];
     if (!hex)
       throw new Error(`addMemberToLiveGroup: no published KeyPackage for device ${newDeviceId}`);
     const pkg = MLSGroupManager.deserializeKeyPackage(hexToBytes(hex));
+    if (_attempt === 0) {
+      let adds;
+      try {
+        adds = (await this.o.backend.getCommitterWork(channelId)).adds;
+      } catch (e) {
+        throw new Error(`addMemberToLiveGroup: committer-work unreachable for channel ${channelId} \u2014 refusing plain Add for device ${newDeviceId} (fail closed): ` + (e instanceof Error ? e.message : String(e)));
+      }
+      if (!adds.includes(newDeviceId)) {
+        const cred = pkg.leafNode.credential;
+        const claimed = cred.credentialType === "basic" ? new TextDecoder().decode(cred.identity) : null;
+        const leaves = claimed === null ? null : mgr.leafIndicesForIdentity(claimed);
+        if (leaves === null || leaves.length > 0) {
+          const known = opts?.knownLeafDevices ? [...new Set(opts.knownLeafDevices)] : null;
+          const swapSafe = leaves !== null && known !== null && !known.includes(newDeviceId) && known.length === leaves.length;
+          if (!swapSafe) {
+            console.warn(`addMemberToLiveGroup: device ${newDeviceId.slice(0, 8)} is outside the committer-work add-delta and its identity already holds a leaf \u2014 terminal skip (no commit)`);
+            return;
+          }
+        }
+      }
+    }
+    const init = await this.o.backend.initConnectChannelGroup(channelId, [this.o.deviceId, newDeviceId]);
     if (opts?.expectedIdentityId) {
       const cred = pkg.leafNode.credential;
       const claimed = cred.credentialType === "basic" ? new TextDecoder().decode(cred.identity) : "";
@@ -2215,6 +2344,7 @@ var MlsGroupKeyProvider = class {
       await this.o.store.delete(channelId);
       await this.o.store.discardStaging(channelId);
       this.errors.delete(channelId);
+      this.lastDecryptAt.delete(channelId);
     });
   }
   /** Owner-attested reset supersede (owner/web side, Task 9). Mirrors the
@@ -2280,6 +2410,25 @@ var MlsGroupKeyProvider = class {
       return true;
     return await this.o.store.load(channelId) !== null;
   }
+  /**
+   * Returns the group id our persisted (or live in-memory) MLS state holds for
+   * `channelId`, or null when there is no state to read, or when the state
+   * exists but a loaded manager can't be constructed from it. Read-only —
+   * `manager()` only loads from the store and caches in memory; it makes no
+   * backend call and writes nothing to the store. Mirrors the same
+   * held-vs-row comparison the Welcome receive path already does inline
+   * (see the `heldGroupId` decode in the `message_type === "welcome"` branch
+   * of `receiveOnce`) so callers can ask "is my held state for THIS group?"
+   * without duplicating that decode logic.
+   */
+  async heldGroupIdFor(channelId) {
+    try {
+      const mgr = await this.manager(channelId);
+      return new TextDecoder().decode(mgr.groupId);
+    } catch {
+      return null;
+    }
+  }
   /**
    * Return the number of leaves the given identity holds in the live tree for
    * `channelId`. Loads the manager from the store if not already cached.
@@ -3097,6 +3246,22 @@ var RestMlsBackend = class {
     });
     return String(j.id);
   }
+  async syncGroup(groupId, lastEpoch, deviceId) {
+    const deviceParam = deviceId ? `&device_id=${encodeURIComponent(deviceId)}` : "";
+    const j = await this.get(`/api/v1/mls/groups/${groupId}/sync?last_epoch=${encodeURIComponent(String(lastEpoch))}${deviceParam}`);
+    const action = j?.action === "rejoin" ? "rejoin" : "replay";
+    const messages = Array.isArray(j?.messages) ? j.messages : [];
+    return {
+      action,
+      messages: messages.map((m) => ({
+        id: String(m.id),
+        epoch: Number(m.epoch),
+        message_type: String(m.message_type),
+        sender_device_id: String(m.sender_device_id ?? ""),
+        payload: String(m.payload ?? "")
+      }))
+    };
+  }
   async getConnectChannelGroup(channelId) {
     const j = await this.get(`/api/v1/mls/connect-channels/${channelId}/group`);
     return {
@@ -4286,6 +4451,22 @@ var InvalidPathError = class extends Error {
     if (cause !== void 0) this.cause = cause;
   }
 };
+var InvalidMessageIdError = class extends Error {
+  constructor(messageId) {
+    super(`message_id must be a UUID, got: ${messageId}`);
+    this.messageId = messageId;
+    this.name = "InvalidMessageIdError";
+  }
+};
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isUuid(s) {
+  return UUID_RE.test(s);
+}
+function resolveMessageId(messageId) {
+  if (messageId === void 0) return crypto.randomUUID();
+  if (!isUuid(messageId)) throw new InvalidMessageIdError(messageId);
+  return messageId;
+}
 var AgentPausedSendError = class extends Error {
   constructor(channelId) {
     super(`agent is paused in channel ${channelId}; send suppressed (no self-heal, no retry)`);
@@ -4486,10 +4667,75 @@ var BridgeAgent = class _BridgeAgent {
    * counter is incremented. Surfaced on health()/metrics().
    */
   failedAttachments = 0;
+  /**
+   * Task 8: count of live AUTHENTICATED /v1/ws sessions, so a later `status`
+   * verb can tell "bridge process up" (the app's green dot, which only
+   * proves bridge<->backend) apart from "a harness is actually attached"
+   * (a real consumer holding an authenticated session). Only ws-server.ts
+   * mutates this, and only after authedUpgrade() passes — an unauthenticated
+   * socket, or the HTTP /healthz probe, must never move this counter.
+   * Surfaced on health()/metrics().
+   */
+  authSessions = 0;
+  /**
+   * Task 3 (audit M3): count of newest-wins evictions of a prior /v1/ws
+   * session. The daemon's WS is single-consumer newest-wins, so
+   * `agent_sessions` alone can stay >=1 while two connectors flap the same
+   * identity in and out — this counter makes that split-brain visible.
+   * Only ws-server.ts mutates this, via noteSessionEvicted(). Surfaced on
+   * health()/status.
+   */
+  evictions = 0;
   /** Per-channel timestamp of last requestWelcome call, for cooldown enforcement. */
   lastWelcomeRequest = /* @__PURE__ */ new Map();
   /** Minimum gap between requestWelcome calls for the same channel (2 minutes). */
-  static REQUEST_WELCOME_COOLDOWN_MS = 12e4;
+  /**
+   * M6 (ADR-0013 Decision H): the sweep's per-channel observation cache, and the
+   * only thing {@link health} reports divergence from.
+   *
+   * Written by `selfHealSweep` in a `finally`, read synchronously by `health()`.
+   * `health()` must NEVER fan out network calls of its own: a health endpoint
+   * that does I/O hangs under exactly the conditions it exists to report, and
+   * the conditions here are "the delivery service is unreachable or lying".
+   */
+  observations = /* @__PURE__ */ new Map();
+  /**
+   * A3 (dr-evil must-fix #3): true when the sweep found the provider missing a
+   * required capability (stale SDK dist under a newer bridge dist) and ABORTED.
+   * Folded into `observations_stale` (and therefore `degraded`) on health():
+   * a bridge that cannot heal must never present trustworthy-looking data.
+   */
+  providerCapabilityMissing = false;
+  /**
+   * ADR-0013 Decision D: the wipe's OWN anti-thrash bound, deliberately
+   * separate from {@link REQUEST_WELCOME_COOLDOWN_MS} and separately keyed.
+   *
+   * Two bounds exist because they protect different things and must never
+   * share a gate. The request cooldown protects the single committer from
+   * churn; deferring an ask costs a little latency. The wipe bound only stops
+   * the member thrashing its own session; skipping a wipe costs the member its
+   * ONLY route back, permanently. Sharing one map is what starved the repair.
+   */
+  static WIPE_ANTI_THRASH_MS = 6e5;
+  /**
+   * ADR-0013 Decision A (wipe-first): the SHORTER re-wipe floor used only when
+   * the fork is PROVEN (the self-heal sweep's resyncByReplay returned false).
+   *
+   * The 600s WIPE_ANTI_THRASH_MS is the right duty cycle for the reactive
+   * onWedged path, but it is a TRAP for a proven-forked member: while the member
+   * holds forked state the owner's re-Welcome is stray-acked (mls.ts, rowGroup ==
+   * heldGroup) and destroyed, so the member never returns to no-state and the
+   * Welcome never lands via the first-join path. Suppressing the re-wipe for a
+   * full 10 minutes means every owner Welcome in that window is destroyed — the
+   * observed hermes flap. This floor lets a proven-forked member re-wipe promptly
+   * (return to no-state so the next Welcome opens) while still bounding the loop:
+   * ~one 25s member ingest poll + margin, which preserves Decision D ("cannot
+   * loop") because two wipes still cannot fire inside a single poll interval.
+   */
+  static PROVEN_FORK_REWIPE_FLOOR_MS = 3e4;
+  /** Per-channel timestamp of the last state repudiation (Decision D). */
+  lastWipe = /* @__PURE__ */ new Map();
+  static REQUEST_WELCOME_COOLDOWN_MS = REQUEST_WELCOME_COOLDOWN_MS;
   // H1: bound the graceful-shutdown drain so a hung in-flight op can't block exit.
   static GRACEFUL_DRAIN_MS = 5e3;
   /**
@@ -4511,13 +4757,13 @@ var BridgeAgent = class _BridgeAgent {
    */
   selfHealSweepEnabled = process.env.SECURECOMS_SELF_HEAL_SWEEP !== "false";
   /** Task 12: proactive sweep cadence (in addition to the once-at-boot fire). */
-  static SELF_HEAL_SWEEP_INTERVAL_MS = 9e4;
+  static SELF_HEAL_SWEEP_INTERVAL_MS = SELF_HEAL_SWEEP_INTERVAL_MS;
   // C3: add up to this much random jitter to BOTH the boot sweep delay and each
   // periodic interval, so a fleet of daemons restarting/sweeping together does not
   // fire re-Welcome signals at the SAME instant and thundering-herd the single
   // committer (the observed 409 commit-lease saturation). Decorrelation only —
   // C1 already removed the restart KP-rotation storm that caused the herd.
-  static SELF_HEAL_SWEEP_JITTER_MS = 3e4;
+  static SELF_HEAL_SWEEP_JITTER_MS = SELF_HEAL_SWEEP_JITTER_MS;
   selfHealTimer;
   bootSweepTimer;
   rng;
@@ -4656,7 +4902,8 @@ var BridgeAgent = class _BridgeAgent {
       await this.provider.joinAndReconcile(channelId, this.cfg.enclaveId);
       this.joinState.set(channelId, "JOINED");
       return true;
-    } catch {
+    } catch (e) {
+      console.warn(`[bridge] reconcileJoin ${channelId} failed:`, e);
       this.joinState.set(channelId, "PENDING");
       return false;
     }
@@ -4714,20 +4961,40 @@ var BridgeAgent = class _BridgeAgent {
    * SDK's onWedged caller. Single-shot per wedge episode — full rejoin
    * reliability is P1, not this hook's job.
    */
-  async healWedgedChannel(channelId) {
+  async healWedgedChannel(channelId, provenForked = false) {
     try {
       const now = performance.now();
-      const last = this.lastWelcomeRequest.get(channelId) ?? -Infinity;
-      if (now - last < _BridgeAgent.REQUEST_WELCOME_COOLDOWN_MS) return;
       const g = await this.backend.getConnectChannelGroup(channelId);
-      if (!g?.group_id) return;
-      this.lastWelcomeRequest.set(channelId, now);
-      if (await this.provider.hasPersistedChannelState(channelId)) {
-        await this.provider.resetChannelForRejoin(channelId);
-        this.joinState.delete(channelId);
+      if (!g?.group_id) return false;
+      const lastWipe = this.lastWipe.get(channelId) ?? -Infinity;
+      const floor = provenForked ? _BridgeAgent.PROVEN_FORK_REWIPE_FLOOR_MS : _BridgeAgent.WIPE_ANTI_THRASH_MS;
+      let repudiated = false;
+      if (now - lastWipe >= floor) {
+        if (await this.provider.hasPersistedChannelState(channelId)) {
+          await this.provider.resetChannelForRejoin(channelId);
+          repudiated = true;
+        }
+        this.lastWipe.set(channelId, now);
+      } else {
+        console.warn(
+          `[bridge] healWedgedChannel ${channelId}: wipe suppressed by ${provenForked ? "proven-fork re-wipe floor" : "anti-thrash bound"} (${Math.round((floor - (now - lastWipe)) / 1e3)}s remaining) \u2014 NOT repudiated`
+        );
+      }
+      this.joinState.delete(channelId);
+      if (!repudiated && await this.provider.hasPersistedChannelState(channelId)) {
+        console.warn(
+          `[bridge] healWedgedChannel ${channelId}: wipe suppressed and state still held \u2014 NOT requesting (the answer would be stray-acked and would cost the group two commits)`
+        );
+        return false;
       }
+      const last = this.lastWelcomeRequest.get(channelId) ?? -Infinity;
+      if (!isResignalDue(now, last, _BridgeAgent.REQUEST_WELCOME_COOLDOWN_MS)) return repudiated;
+      this.lastWelcomeRequest.set(channelId, now);
       await this.signalHeldKpWelcome(g.group_id);
-    } catch {
+      return repudiated;
+    } catch (e) {
+      console.warn(`[bridge] healWedgedChannel ${channelId} failed:`, e);
+      return false;
     }
   }
   /**
@@ -4749,7 +5016,7 @@ var BridgeAgent = class _BridgeAgent {
     try {
       const now = performance.now();
       const last = this.lastWelcomeRequest.get(channelId) ?? -Infinity;
-      if (now - last < _BridgeAgent.REQUEST_WELCOME_COOLDOWN_MS) return false;
+      if (!isResignalDue(now, last, _BridgeAgent.REQUEST_WELCOME_COOLDOWN_MS)) return false;
       this.lastWelcomeRequest.set(channelId, now);
       await this.signalHeldKpWelcome(groupId);
       return true;
@@ -4757,6 +5024,19 @@ var BridgeAgent = class _BridgeAgent {
       return false;
     }
   }
+  /**
+   * Task 2 (MLS convergence slice): true when we hold persisted state for
+   * `channelId` whose group id does NOT match `serverGroupId` — the group
+   * the server currently says is live for that channel. Holding SOME state
+   * is not proof of health; it is proof of health only for the group the
+   * server currently attests. A null held group id (state present but the
+   * manager can't be loaded from it) is treated as diverged too — we can't
+   * confirm health, so we ask rather than silently trusting stale state.
+   */
+  async isChannelDiverged(channelId, serverGroupId) {
+    const held = await this.provider.heldGroupIdFor(channelId);
+    return held !== serverGroupId;
+  }
   /**
    * Task 12: proactive self-heal sweep. ingestOnce's Task-11 divergence
    * branch only fires reactively — off a delivery ROW that already arrived
@@ -4765,11 +5045,22 @@ var BridgeAgent = class _BridgeAgent {
    * first thing lost. This sweep walks every member channel — rooms AND DMs
    * (H2: a wiped, idle DM with no traffic since the wipe otherwise never
    * proactively re-Welcomes, so it stays dark until the owner happens to send)
-   * — fired once at boot + on SELF_HEAL_SWEEP_INTERVAL_MS, and, for any with no
-   * persisted state even after a reconcile attempt, resolves group_id via
-   * the READ-ONLY getConnectChannelGroup probe (never initConnectChannelGroup,
-   * which would side-effect a member_device_ids union + commit) and applies
-   * the same held-KP signal — respecting the existing per-channel cooldown.
+   * — fired once at boot + on SELF_HEAL_SWEEP_INTERVAL_MS.
+   *
+   * Task 2: holding persisted state is NOT proof of health by itself — it is
+   * proof of health only for the group the server currently says is live for
+   * the channel. The prior rule ("I have persisted state ⇒ healthy ⇒ don't
+   * ask") silently stopped filing welcome-requests for any channel that had
+   * been superseded (e.g. a server-side reset/rotation) while the member
+   * still held state for the OLD group: it could hold state, hold the WRONG
+   * state, and never say anything. So the server's current group_id is
+   * fetched FIRST via the READ-ONLY getConnectChannelGroup probe (never
+   * initConnectChannelGroup, which would side-effect a member_device_ids
+   * union + commit), then the branch is: persisted state whose group id
+   * matches the server's current group ⇒ healthy, skip; persisted state for
+   * a STALE group id ⇒ diverged, signal; no persisted state at all ⇒
+   * reconcile-first (consume an already-queued Welcome) before concluding
+   * divergence. All three paths go through the same per-channel cooldown.
    *
    * Each channel is wrapped in its own try/catch: `listChannels` filters at
    * the identity level while `requestWelcome` (via request_welcome) gates at
@@ -4778,25 +5069,114 @@ var BridgeAgent = class _BridgeAgent {
    * must not abort the sweep for every other channel.
    */
   async selfHealSweep() {
+    if (typeof this.provider.resyncByReplay !== "function" || typeof this.provider.heldGroupIdFor !== "function") {
+      this.providerCapabilityMissing = true;
+      console.error(
+        "[bridge] selfHealSweep ABORTED: provider is missing required capabilities (resyncByReplay/heldGroupIdFor) \u2014 stale SDK dist? Rebuild SDK dist THEN bridge dist. Healing is NOT running; observations are reported STALE."
+      );
+      return;
+    }
+    this.providerCapabilityMissing = false;
     let chans;
     try {
       chans = await this.listChannels();
-    } catch {
+    } catch (e) {
+      console.warn("[bridge] selfHealSweep aborted: listChannels failed:", e);
       return;
     }
     for (const c of chans) {
+      const obs = {
+        channel_id: c.channel_id,
+        state: "probe_failed",
+        held_group_id: null,
+        server_group_id: null,
+        held_epoch: null,
+        server_epoch: null,
+        diverged: null,
+        last_decrypt_at: this.provider.lastDecryptAtFor?.(c.channel_id) ?? null,
+        observed_at: Date.now()
+      };
       try {
-        if (await this.provider.hasPersistedChannelState(c.channel_id)) continue;
-        await this.reconcileJoin(c.channel_id);
-        if (await this.provider.hasPersistedChannelState(c.channel_id)) continue;
         const g = await this.backend.getConnectChannelGroup(c.channel_id);
-        if (!g?.group_id) continue;
+        obs.server_group_id = g?.group_id ?? null;
+        obs.server_epoch = g?.current_epoch ?? null;
+        if (!g?.group_id) {
+          obs.state = "group_unresolvable";
+          continue;
+        }
+        const hasState = await this.provider.hasPersistedChannelState(c.channel_id);
+        if (hasState) {
+          obs.held_group_id = await this.provider.heldGroupIdFor(c.channel_id).catch(() => null);
+          obs.held_epoch = await this.provider.currentEpoch(c.channel_id).catch(() => null);
+          if (!await this.isChannelDiverged(c.channel_id, g.group_id)) {
+            if (obs.held_epoch === null) {
+              obs.state = "probe_failed";
+              obs.diverged = null;
+              continue;
+            }
+            const behind = typeof obs.held_epoch === "number" && typeof obs.server_epoch === "number" && obs.held_epoch < obs.server_epoch;
+            obs.state = behind ? "behind" : "healthy";
+            obs.diverged = behind;
+            if (behind) {
+              const prev = this.observations.get(c.channel_id);
+              const notAdvancing = prev != null && prev.held_epoch === obs.held_epoch;
+              if (notAdvancing) {
+                obs.state = "stuck";
+                if (await this.provider.resyncByReplay(c.channel_id, g.group_id)) {
+                  obs.held_epoch = await this.provider.currentEpoch(c.channel_id).catch(() => null);
+                  obs.last_decrypt_at = this.provider.lastDecryptAtFor?.(c.channel_id) ?? null;
+                  if (obs.held_epoch === null) {
+                    obs.state = "probe_failed";
+                    obs.diverged = null;
+                    continue;
+                  }
+                  obs.state = "healthy";
+                  obs.diverged = false;
+                  console.warn(
+                    `[bridge] selfHealSweep: ${c.channel_id} caught up by REPLAY to epoch ${obs.held_epoch} (no re-admit, no epoch churn)`
+                  );
+                  continue;
+                }
+                const repudiated = await this.healWedgedChannel(c.channel_id, true);
+                console.warn(
+                  `[bridge] selfHealSweep: ${c.channel_id} STUCK at epoch ${obs.held_epoch} (server=${obs.server_epoch}) across two sweeps \u2014 ${repudiated ? "repudiated and re-requested" : "repair SUPPRESSED (anti-thrash); state unchanged"}`
+                );
+              }
+              continue;
+            }
+            console.debug(
+              `[bridge] selfHealSweep: ${c.channel_id} ${behind ? `BEHIND (held=${obs.held_epoch} server=${obs.server_epoch}) \u2014 reporting only, action predicate is group-id` : "healthy, held group matches server"} \u2014 skipping`
+            );
+            continue;
+          }
+          obs.state = "diverged";
+          obs.diverged = true;
+          console.warn(`[bridge] selfHealSweep: ${c.channel_id} holds STALE group state \u2014 signalling re-Welcome`);
+        } else {
+          obs.state = "no_local_state";
+          obs.diverged = false;
+          await this.reconcileJoin(c.channel_id);
+          if (await this.provider.hasPersistedChannelState(c.channel_id)) {
+            obs.held_group_id = await this.provider.heldGroupIdFor(c.channel_id).catch(() => null);
+            obs.held_epoch = await this.provider.currentEpoch(c.channel_id).catch(() => null);
+            if (obs.held_epoch === null) {
+              obs.state = "probe_failed";
+              obs.diverged = null;
+              continue;
+            }
+            obs.state = "healthy";
+            continue;
+          }
+        }
         const now = performance.now();
         const last = this.lastWelcomeRequest.get(c.channel_id) ?? -Infinity;
-        if (now - last < _BridgeAgent.REQUEST_WELCOME_COOLDOWN_MS) continue;
+        if (!isResignalDue(now, last, _BridgeAgent.REQUEST_WELCOME_COOLDOWN_MS)) continue;
         this.lastWelcomeRequest.set(c.channel_id, now);
         await this.signalHeldKpWelcome(g.group_id);
-      } catch {
+      } catch (e) {
+        console.warn(`[bridge] selfHealSweep: channel ${c.channel_id} failed:`, e);
+      } finally {
+        this.observations.set(c.channel_id, obs);
       }
     }
   }
@@ -4851,7 +5231,7 @@ var BridgeAgent = class _BridgeAgent {
     if (meta && !meta.is_dm) this.enforceRateFloor("room", channelId);
     const joined = await this.reconcileJoin(channelId);
     if (!joined) throw new ChannelPendingError(channelId);
-    const id = messageId ?? crypto.randomUUID();
+    const id = resolveMessageId(messageId);
     const sendStart = performance.now();
     await this.sendWithSelfHealTerminal(
       this.provider,
@@ -4888,7 +5268,7 @@ var BridgeAgent = class _BridgeAgent {
     this.enforceRateFloor("a2a", channelId);
     const joined = await this.reconcileJoin(channelId);
     if (!joined) throw new ChannelPendingError(channelId);
-    const id = messageId ?? crypto.randomUUID();
+    const id = resolveMessageId(messageId);
     const sendStart = performance.now();
     await this.sendWithSelfHealTerminal(
       this.provider,
@@ -5429,11 +5809,12 @@ var BridgeAgent = class _BridgeAgent {
         if (await this.provider.hasPersistedChannelState(cid)) continue;
         const now = performance.now();
         const last = this.lastWelcomeRequest.get(cid) ?? -Infinity;
-        if (now - last < _BridgeAgent.REQUEST_WELCOME_COOLDOWN_MS) continue;
+        if (!isResignalDue(now, last, _BridgeAgent.REQUEST_WELCOME_COOLDOWN_MS)) continue;
         this.lastWelcomeRequest.set(cid, now);
         try {
           await this.signalHeldKpWelcome(gid);
-        } catch {
+        } catch (e) {
+          console.warn(`[bridge] ingestOnce: signalHeldKpWelcome for ${cid} failed:`, e);
         }
       }
     } catch {
@@ -5622,11 +6003,55 @@ var BridgeAgent = class _BridgeAgent {
     const w = this.waiters.splice(0);
     for (const r of w) r();
   }
+  /**
+   * Task 8: record a newly authenticated /v1/ws session. Called by
+   * ws-server.ts exactly once per connection, AFTER authedUpgrade() passes
+   * (never for a socket closed 1008 for bad auth, and never for the HTTP
+   * /healthz probe, which is not a /v1/ws session at all).
+   */
+  noteSessionOpen() {
+    this.authSessions++;
+  }
+  /**
+   * Task 8: record an authenticated /v1/ws session ending. Clamped at 0 so a
+   * stray extra close (e.g. a double-fired cleanup) can't go negative and
+   * poison the next open/close cycle.
+   */
+  noteSessionClose() {
+    this.authSessions = Math.max(0, this.authSessions - 1);
+  }
+  /**
+   * Task 3 (audit M3): record a prior /v1/ws session being evicted by a
+   * newer connection for the same identity (newest-wins). Called by
+   * ws-server.ts right after prior.cleanup() in the eviction path.
+   */
+  noteSessionEvicted() {
+    this.evictions++;
+  }
   health() {
     let joined = 0;
     for (const s of this.joinState.values()) if (s === "JOINED") joined++;
+    const channels = [...this.observations.values()];
+    const newest = channels.reduce((m, o) => Math.max(m, o.observed_at), 0);
+    const stalePeriodMs = _BridgeAgent.SELF_HEAL_SWEEP_INTERVAL_MS + _BridgeAgent.SELF_HEAL_SWEEP_JITTER_MS;
+    const observationsStale = this.providerCapabilityMissing || channels.length === 0 || Date.now() - newest > stalePeriodMs;
+    const divergedChannels = channels.filter((o) => o.diverged === true).length;
+    const liveChannels = channels.map((o) => ({
+      ...o,
+      last_decrypt_at: this.provider.lastDecryptAtFor?.(o.channel_id) ?? o.last_decrypt_at
+    }));
     return {
+      // Deliberately still unconditional. `agent-bridge status` and any external
+      // monitor read this field, and a monitor that restarts non-ok bridges would
+      // loop forever on a diverged agent. The additive fields below land first so
+      // the data can be trusted; flipping this to "degraded" is its own change.
       status: "ok",
+      sweep_enabled: this.selfHealSweepEnabled,
+      observations_stale: observationsStale,
+      diverged_channels: divergedChannels,
+      // A2: the truthful roll-up gates read instead of `status` (D-3).
+      degraded: divergedChannels > 0 || observationsStale,
+      channels: liveChannels,
       identity_id: this.cfg.identityId,
       joined_channels: joined,
       buffered: this.buffer.length,
@@ -5636,6 +6061,8 @@ var BridgeAgent = class _BridgeAgent {
       permanently_skipped: this.provider.permanentlySkippedCount(),
       failed_attachments: this.failedAttachments,
       delivery_pings: this.pingsReceived,
+      agent_sessions: this.authSessions,
+      evictions: this.evictions,
       uptime_s: this.startedAt ? Math.floor((Date.now() - this.startedAt) / 1e3) : 0,
       version: BRIDGE_VERSION,
       ...this.memory.stats?.() ?? {}
@@ -5995,7 +6422,7 @@ function createHttpServer(agent, opts) {
       if (method === "POST" && path === "/v1/send") {
         const parsed = sendSchema.safeParse(JSON.parse(await readBody(req, SEND_CAP)));
         if (!parsed.success) return jsonError(res, "invalid_request", parsed.error.issues);
-        const r = parsed.data.a2a ? await agent.sendA2A(parsed.data.channel_id, parsed.data.a2a, parsed.data.idempotency_key) : await agent.send(parsed.data.channel_id, parsed.data.text, parsed.data.idempotency_key);
+        const r = parsed.data.a2a ? await agent.sendA2A(parsed.data.channel_id, parsed.data.a2a) : await agent.send(parsed.data.channel_id, parsed.data.text);
         return json(res, 200, r);
       }
       if (method === "POST" && path === "/v1/send-attachment") {
@@ -6126,12 +6553,14 @@ function attachAgentWebSocket(server, agent, opts) {
       sock.close(1008, "unauthorized");
       return;
     }
+    agent.noteSessionOpen();
     if (current && current.sock !== sock) {
       const prior = current;
       if (prior.sock.readyState === WebSocket.OPEN) {
         prior.sock.close(1e3, "replaced by newer connection");
       }
       prior.cleanup();
+      agent.noteSessionEvicted();
     }
     sock.isAlive = true;
     sock.on("pong", () => {
@@ -6161,6 +6590,7 @@ function attachAgentWebSocket(server, agent, opts) {
     const cleanup = () => {
       if (cleaned) return;
       cleaned = true;
+      agent.noteSessionClose();
       unsubscribe();
       if (inflight.size) {
         agent.requeueFront([...inflight.values()]);
@@ -6247,9 +6677,8 @@ async function handleInbound(sock, agent, data, inflight) {
       sendJson(sock, wsErrorFrame("invalid_request"));
       return;
     }
-    const idempotencyKey = typeof m.idempotency_key === "string" ? m.idempotency_key : void 0;
     try {
-      const r = await agent.send(m.channel_id, m.text, idempotencyKey);
+      const r = await agent.send(m.channel_id, m.text);
       sendJson(sock, { type: "sent", message_id: r.message_id });
     } catch (e) {
       if (e instanceof ChannelPendingError) {