@securecoms/agent-bridge 0.5.0 → 0.7.0

package/dist/bin.js

@@ -93,6 +93,15 @@ function validateBind(bind, tls) {
   }
 }
 
+// ../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",
@@ -1421,6 +1430,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
@@ -1485,6 +1511,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;
@@ -1632,7 +1659,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, {
@@ -1657,6 +1686,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.
@@ -1880,7 +1988,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);
@@ -1910,7 +2018,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];
@@ -1961,17 +2069,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) : "";
@@ -2310,6 +2439,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
@@ -2375,6 +2505,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.
@@ -3192,6 +3341,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 {
@@ -4422,6 +4587,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)`);
@@ -4622,10 +4803,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;
   /**
@@ -4647,13 +4893,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;
@@ -4792,7 +5038,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;
     }
@@ -4850,20 +5097,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;
     }
   }
   /**
@@ -4885,7 +5152,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;
@@ -4893,6 +5160,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
@@ -4901,11 +5181,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
@@ -4914,25 +5205,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);
       }
     }
   }
@@ -4987,7 +5367,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,
@@ -5024,7 +5404,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,
@@ -5565,11 +5945,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 {
@@ -5758,11 +6139,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,
@@ -5772,6 +6197,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?.() ?? {}
@@ -6038,7 +6465,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") {
@@ -6169,12 +6596,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", () => {
@@ -6204,6 +6633,7 @@ function attachAgentWebSocket(server, agent, opts) {
     const cleanup = () => {
       if (cleaned) return;
       cleaned = true;
+      agent.noteSessionClose();
       unsubscribe();
       if (inflight.size) {
         agent.requeueFront([...inflight.values()]);
@@ -6290,9 +6720,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) {
@@ -6403,9 +6832,9 @@ async function handleInbound(sock, agent, data, inflight) {
 }
 
 // src/bin.ts
-import { readFileSync as readFileSync6, mkdirSync, writeFileSync as writeFileSync2, rmSync, existsSync as existsSync2, realpathSync, readdirSync } from "node:fs";
-import { join as join9, dirname as dirname5, isAbsolute as isAbsolute2, resolve as resolve2 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { readFileSync as readFileSync7, mkdirSync as mkdirSync2, writeFileSync as writeFileSync3, rmSync, existsSync as existsSync2, realpathSync, readdirSync, statSync as statSync2 } from "node:fs";
+import { join as join11, dirname as dirname7, isAbsolute as isAbsolute2, resolve as resolve2 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { homedir as homedir2, userInfo } from "node:os";
 import { spawnSync } from "node:child_process";
 
@@ -6414,10 +6843,83 @@ import { dirname as dirname4 } from "node:path";
 
 // src/service/config.ts
 import { basename as basename2, extname, isAbsolute, resolve } from "node:path";
+
+// src/service/resolve-node.ts
+var REQUIRED_NODE_MAJOR = 24;
+var VERSION_EMBEDDED = [
+  /[\\/]Cellar[\\/]/,
+  // Homebrew keg
+  /[\\/]node[\\/]v?\d+\.\d+/,
+  // nvm, generic .../node/v24.4.1/...
+  /[\\/]nodejs[\\/]\d/,
+  // asdf .../installs/nodejs/24.4.1/...
+  /[\\/]node-versions[\\/]/,
+  // fnm
+  /[\\/]\.volta[\\/]/,
+  // volta
+  /[\\/]\.fnm[\\/]/,
+  // fnm (alt layout)
+  /[\\/]\.nvm[\\/]/,
+  // nvm home
+  /[\\/]\.asdf[\\/]/,
+  // asdf home
+  /[\\/]n[\\/]versions[\\/]/
+  // n
+];
+function isVersionEmbeddedNodePath(p) {
+  return VERSION_EMBEDDED.some((re) => re.test(p));
+}
+var STABLE_LOCATIONS = [
+  "/usr/local/bin/node",
+  // nodejs.org pkg (mac + linux)
+  "/opt/homebrew/bin/node",
+  // Homebrew symlink (arm mac)
+  "/opt/homebrew/opt/node/bin/node",
+  "/usr/bin/node"
+  // system (linux)
+];
+function usable(path, deps) {
+  if (!deps.fileExists(path)) return false;
+  if (isVersionEmbeddedNodePath(path)) return false;
+  const major = deps.nodeMajorOf(path);
+  if (major == null || major < REQUIRED_NODE_MAJOR) return false;
+  const a = deps.archOf(path);
+  if (a != null && a !== deps.arch()) return false;
+  return true;
+}
+function resolveStableNodePath(runningExecPath, deps) {
+  let runningReal;
+  try {
+    runningReal = deps.realpath(runningExecPath);
+  } catch {
+    runningReal = runningExecPath;
+  }
+  for (const loc of STABLE_LOCATIONS) {
+    if (!deps.fileExists(loc)) continue;
+    let locReal;
+    try {
+      locReal = deps.realpath(loc);
+    } catch {
+      continue;
+    }
+    if (locReal === runningReal && usable(loc, deps)) return { path: loc, stable: true };
+  }
+  for (const loc of STABLE_LOCATIONS) {
+    if (usable(loc, deps)) return { path: loc, stable: true };
+  }
+  return { path: runningExecPath, stable: false };
+}
+
+// src/service/config.ts
 function slugify(s) {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
 }
 function deriveServiceConfig(input) {
+  if (isVersionEmbeddedNodePath(input.execPath)) {
+    throw new Error(
+      `install: refusing to bake a version-embedded Node path into the service definition: ${input.execPath}. Re-run install under a system/Homebrew Node, or pass --exec-path <stable-path>.`
+    );
+  }
   const stem = input.label ?? basename2(input.credentialPath, extname(input.credentialPath));
   const slug = slugify(stem);
   const cred = isAbsolute(input.credentialPath) ? input.credentialPath : resolve(input.credentialPath);
@@ -6540,7 +7042,139 @@ function uninstallService(input, deps) {
 }
 
 // src/service/install-prep.ts
-import { join as join8 } from "node:path";
+import { join as join9 } from "node:path";
+
+// src/service/wire.ts
+import { join as join8, dirname as dirname5 } from "node:path";
+import { fileURLToPath } from "node:url";
+function detectHarness(home, statDir) {
+  if (statDir(`${home}/.openclaw`)) return "openclaw";
+  if (statDir(`${home}/.hermes`)) return "hermes";
+  return null;
+}
+function connectorTargetDir(home, harness) {
+  if (harness === "openclaw") return `${home}/.openclaw/local-plugins/securecoms`;
+  return `${home}/.hermes/local-plugins/securecoms`;
+}
+function connectorsSrcDir(importMetaUrl) {
+  const pkgRoot = dirname5(dirname5(fileURLToPath(importMetaUrl)));
+  return join8(pkgRoot, "connectors", "openclaw");
+}
+function parseArg(argv, flag) {
+  const i = argv.indexOf(flag);
+  return i >= 0 ? argv[i + 1] : void 0;
+}
+function resolveEntry(deps) {
+  const identityArg = parseArg(deps.argv, "--identity");
+  if (!identityArg) {
+    deps.log("wire: missing --identity <id|slug>");
+    return null;
+  }
+  const entry = deps.readFleet().find((e) => e.identityId === identityArg || e.slug === identityArg);
+  if (!entry) {
+    deps.log(`wire: unknown identity "${identityArg}" (not found in the local fleet)`);
+    return null;
+  }
+  const harnessArg = parseArg(deps.argv, "--harness");
+  if (harnessArg !== "openclaw" && harnessArg !== "hermes") {
+    deps.log("wire: missing/invalid --harness <openclaw|hermes> (auto-detection did not resolve one)");
+    return null;
+  }
+  return { entry, harness: harnessArg };
+}
+function runWire(deps) {
+  const resolved = resolveEntry(deps);
+  if (!resolved) return 1;
+  const { entry, harness } = resolved;
+  if (harness === "hermes") {
+    deps.log(
+      "[securecoms] Hermes connector is not available yet (fast-follow); detection and target dir only. Nothing installed."
+    );
+    return 1;
+  }
+  const targetDir = connectorTargetDir(deps.home, harness);
+  deps.copyConnector(deps.connectorsSrcDir, targetDir);
+  deps.writeBinding(targetDir, entry.identityId);
+  if (typeof entry.port === "number") {
+    const h = deps.getHealth(entry.port);
+    if (h && (h.agent_sessions ?? 0) >= 1) {
+      deps.log(`wire: ${entry.slug} attached (agent_sessions=${h.agent_sessions})`);
+    } else {
+      deps.log(`wire: connector installed but not yet attached \u2014 restart the harness to pick it up.`);
+    }
+  } else {
+    deps.log(`wire: connector installed (no bridge port known yet) \u2014 restart the harness to pick it up.`);
+  }
+  return 0;
+}
+function runUnwire(deps) {
+  const resolved = resolveEntry(deps);
+  if (!resolved) return 1;
+  const { harness } = resolved;
+  if (harness === "hermes") {
+    deps.log("[securecoms] Hermes connector is not available yet (fast-follow); nothing to remove.");
+    return 0;
+  }
+  deps.removeBinding(connectorTargetDir(deps.home, harness));
+  return 0;
+}
+
+// src/service/harness-wire.ts
+function customFacts(input) {
+  const ws = `ws://127.0.0.1:${input.port ?? "<PORT>"}/v1/ws`;
+  return [
+    `  bridge WS:   ${ws}`,
+    `  token file:  ${input.tokenFilePath}`,
+    `  Bring your own connector: open the WS with the bearer token read from that file.`,
+    `  Protocol reference: the "WebSocket" section of the agent-bridge README.`
+  ].join("\n");
+}
+function autoWireHarness(input, deps) {
+  const h = input.harness;
+  if (!h || h === "none") return { echo: "", wired: false, error: false };
+  const retry = `agent-bridge wire --harness openclaw --identity ${input.slug}`;
+  if (h === "openclaw") {
+    const parent = `${input.home}/.openclaw`;
+    if (!deps.statDir(parent)) {
+      return {
+        echo: `[securecoms] OpenClaw not found at ~/.openclaw \u2014 the bridge service is installed, but the harness was NOT wired.
+  Install OpenClaw, then re-run install, or run: ${retry}
+  (or re-run install with --harness custom).`,
+        wired: false,
+        error: true
+      };
+    }
+    const targetDir = connectorTargetDir(input.home, "openclaw");
+    try {
+      const prev = deps.readBinding(targetDir);
+      deps.copyConnector(input.connectorsSrcDir, targetDir);
+      deps.writeBinding(targetDir, input.identityId);
+      const rebind = prev && prev !== input.identityId ? `
+  rebind: ${prev} \u2192 ${input.identityId}` : "";
+      return {
+        echo: `[securecoms] OpenClaw connector installed and bound to identity ${input.identityId}.${rebind}
+  Now restart OpenClaw to pick up the connector.`,
+        wired: true,
+        error: false
+      };
+    } catch (e) {
+      return {
+        echo: `[securecoms] the bridge service is installed, but wiring the OpenClaw connector FAILED: ${e.message}
+  Retry after fixing the path: ${retry}`,
+        wired: false,
+        error: true
+      };
+    }
+  }
+  if (h === "hermes") {
+    return { echo: `[securecoms] Hermes turnkey connector is coming (Phase 2). For now drive Hermes via the custom WS path:
+${customFacts(input)}`, wired: false, error: false };
+  }
+  return { echo: `[securecoms] Custom harness \u2014 bring your own connector:
+${customFacts(input)}`, wired: false, error: false };
+}
+
+// src/service/install-prep.ts
 function assertReadableCredential(absPath, deps) {
   let raw;
   try {
@@ -6563,10 +7197,10 @@ function assertReadableCredential(absPath, deps) {
   return { deviceId: json2.device_id, identityId: json2.identity_id, issuedAt };
 }
 function durableDir(home, slug) {
-  return join8(home, `securecoms-agent-${slug}`);
+  return join9(home, `securecoms-agent-${slug}`);
 }
 function durableCredentialPath(home, slug) {
-  return join8(durableDir(home, slug), `${slug}.json`);
+  return join9(durableDir(home, slug), `${slug}.json`);
 }
 function takeCustody(args2, deps) {
   const dir = durableDir(args2.home, args2.slug);
@@ -6613,7 +7247,7 @@ function readSiblingDefs(dir, prefix, deps) {
   for (const n of names) {
     if (!n.startsWith(prefix)) continue;
     try {
-      out.push(deps.readFile(join8(dir, n)));
+      out.push(deps.readFile(join9(dir, n)));
     } catch {
     }
   }
@@ -6645,14 +7279,6 @@ async function verifyDaemonUp(args2, deps) {
   }
   return false;
 }
-function harnessSnippet(args2) {
-  const label = args2.harness === "hermes" ? "Hermes" : args2.harness === "openclaw" ? "OpenClaw" : "your harness";
-  return [
-    `# ${label}: point the agent at this bridge`,
-    `SECURECOMS_BRIDGE_URL=ws://127.0.0.1:${args2.port}/v1/ws`,
-    `SECURECOMS_BRIDGE_TOKEN="$(cat ${args2.tokenFilePath})"`
-  ].join("\n");
-}
 async function orchestrateInstall(ctx) {
   const parsed = assertReadableCredential(ctx.credentialAbsPath, ctx.prepDeps);
   const stemForSlug = ctx.label ?? ctx.credentialAbsPath.replace(/^.*[\\/]/, "").replace(/\.[^.]*$/, "");
@@ -6686,12 +7312,194 @@ async function orchestrateInstall(ctx) {
     `  token:   ${result.tokenHint}`,
     `  (Re-running install is the only way to update a live credential \u2014 replacing the download alone does nothing.)`
   ];
-  let harnessSnippetShown = false;
-  if (ctx.harness && ctx.harness !== "none") {
-    lines.push("", harnessSnippet({ slug, port, tokenFilePath: result.tokenHint, harness: ctx.harness }));
-    harnessSnippetShown = true;
+  const wire = autoWireHarness(
+    {
+      harness: ctx.harness,
+      identityId: parsed.identityId,
+      slug,
+      port,
+      home: ctx.home,
+      tokenFilePath: result.tokenHint,
+      connectorsSrcDir: ctx.connectorsSrcDir
+    },
+    ctx.autoWireDeps
+  );
+  if (wire.echo) lines.push("", wire.echo);
+  return { echo: lines.join("\n") + "\n", harnessWired: wire.wired, harnessError: wire.error };
+}
+
+// src/service/fleet.ts
+import { dirname as dirname6 } from "node:path";
+function parseArgFromDef(def, flag) {
+  const esc = flag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`${esc}(?:<\\/string>\\s*<string>|\\s+)([^<\\s]+)`);
+  const m = re.exec(def);
+  return m ? m[1] : null;
+}
+function parseExecPathFromDef(def) {
+  const plist = /<key>ProgramArguments<\/key>\s*<array>\s*<string>([^<]+)<\/string>/.exec(def);
+  if (plist) return plist[1];
+  const unit = /^ExecStart=(\S+)/m.exec(def);
+  return unit ? unit[1] : null;
+}
+function envOf(apiBase) {
+  if (!apiBase) return "unknown";
+  if (apiBase.includes("app.securecoms.ai")) return "prod";
+  return "preprod";
+}
+var SLUG_FROM_PLIST = /com\.securecoms\.bridge\.(.+)\.plist$/;
+var SLUG_FROM_UNIT = /securecoms-bridge-(.+)\.service$/;
+function readFleet(deps) {
+  const sources = [
+    { dir: `${deps.home}/Library/LaunchAgents`, prefix: "com.securecoms.bridge.", slugRe: SLUG_FROM_PLIST },
+    { dir: `${deps.home}/.config/systemd/user`, prefix: "securecoms-bridge-", slugRe: SLUG_FROM_UNIT }
+  ];
+  const byIdentity = /* @__PURE__ */ new Map();
+  for (const src of sources) {
+    for (const name of deps.listDir(src.dir)) {
+      if (!name.startsWith(src.prefix)) continue;
+      const slugMatch = src.slugRe.exec(name);
+      if (!slugMatch) continue;
+      const slug = slugMatch[1];
+      let def;
+      try {
+        def = deps.readFile(`${src.dir}/${name}`);
+      } catch {
+        continue;
+      }
+      const credPath = parseArgFromDef(def, "--credential");
+      const portStr = parseArgFromDef(def, "--port");
+      const interp = parseExecPathFromDef(def);
+      let identityId = `unknown:${slug}`, deviceId = "", label = slug, env = "unknown";
+      let credDir = null;
+      if (credPath) {
+        credDir = dirname6(credPath);
+        try {
+          const c = JSON.parse(deps.readFile(credPath));
+          if (c.identity_id) identityId = c.identity_id;
+          if (c.device_id) deviceId = c.device_id;
+          env = envOf(c.api_base);
+        } catch {
+        }
+      }
+      byIdentity.set(identityId, {
+        identityId,
+        deviceId,
+        slug,
+        label,
+        environment: env,
+        port: portStr ? Number(portStr) : null,
+        interpreterPath: interp,
+        // Fail-loud (Part A posture): a def whose interpreter can't be parsed
+        // is NOT a clean bill of health — it's an unknown we can't vouch for,
+        // so it must surface as a reboot risk for triage, not pass silently.
+        interpreterStable: interp ? !isVersionEmbeddedNodePath(interp) : false,
+        credentialDir: credDir
+      });
+    }
+  }
+  return [...byIdentity.values()];
+}
+
+// src/service/status.ts
+function readFleetStatus(deps) {
+  return deps.readFleet().map((e) => {
+    const up = e.port != null && deps.probeConnect(e.port);
+    let harness = "-";
+    let evictions = 0;
+    if (up && e.port != null) {
+      const h = deps.getHealth(e.port);
+      harness = (h?.agent_sessions ?? 0) >= 1 ? "attached" : "no brain";
+      evictions = h?.evictions ?? 0;
+    }
+    return {
+      slug: e.slug,
+      environment: e.environment,
+      port: e.port,
+      bridge: up ? "up" : "down",
+      harness,
+      interpreter: e.interpreterStable ? "stable" : "REBOOT-RISK",
+      evictions
+    };
+  });
+}
+function renderStatusTable(rows) {
+  const head = ["AGENT", "ENV", "PORT", "BRIDGE", "HARNESS", "INTERPRETER", "FLAPS"];
+  const body = rows.map((r) => [
+    r.slug,
+    r.environment,
+    String(r.port ?? "-"),
+    r.bridge,
+    r.harness,
+    r.interpreter,
+    String(r.evictions)
+  ]);
+  const widths = head.map((h, i) => Math.max(h.length, ...body.map((row) => row[i].length)));
+  const fmt = (cols) => cols.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
+  return [fmt(head), ...body.map(fmt)].join("\n") + "\n";
+}
+
+// src/service/connection-file.ts
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync as readFileSync6,
+  renameSync,
+  unlinkSync,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join as join10 } from "node:path";
+var REAL_FS = {
+  mkdir: (p, mode) => mkdirSync(p, { recursive: true, mode }),
+  chmod: (p, mode) => chmodSync(p, mode),
+  writeFile: (p, data, mode) => writeFileSync2(p, data, { mode }),
+  rename: (a, b) => renameSync(a, b),
+  readFile: (p) => readFileSync6(p, "utf8"),
+  unlink: (p) => unlinkSync(p)
+};
+function securecomsDir(home) {
+  return join10(home, ".securecoms");
+}
+function connectionsDir(home) {
+  return join10(securecomsDir(home), "connections");
+}
+function connectionFilePath(home, identityId) {
+  return join10(connectionsDir(home), `${identityId}.json`);
+}
+function newInstanceId() {
+  return randomUUID();
+}
+function buildConnectionFile(args2) {
+  return {
+    schema: "securecoms.connection/1",
+    identity_id: args2.identityId,
+    bridge_url: `ws://127.0.0.1:${args2.port}/v1/ws`,
+    token_file: args2.tokenFile,
+    instance_id: args2.instanceId,
+    slug: args2.slug ?? args2.identityId,
+    label: args2.label ?? args2.slug ?? args2.identityId,
+    written_at: args2.now
+  };
+}
+function writeConnectionFile(home, doc, deps = REAL_FS) {
+  deps.mkdir(securecomsDir(home), 448);
+  deps.chmod(securecomsDir(home), 448);
+  deps.mkdir(connectionsDir(home), 448);
+  deps.chmod(connectionsDir(home), 448);
+  const path = connectionFilePath(home, doc.identity_id);
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  deps.writeFile(tmp, JSON.stringify(doc, null, 2) + "\n", 384);
+  deps.chmod(tmp, 384);
+  deps.rename(tmp, path);
+}
+function removeConnectionFileIfOwned(home, identityId, instanceId, deps = REAL_FS) {
+  const path = connectionFilePath(home, identityId);
+  try {
+    const cur = JSON.parse(deps.readFile(path));
+    if (cur.instance_id === instanceId) deps.unlink(path);
+  } catch {
   }
-  return { echo: lines.join("\n") + "\n", harnessSnippetShown };
 }
 
 // src/bin.ts
@@ -6709,7 +7517,15 @@ function argOrEnv(flag, env) {
 }
 function parseVerb(argv) {
   const v = argv[2];
-  return v === "install" || v === "uninstall" ? v : null;
+  return v === "install" || v === "uninstall" || v === "status" || v === "wire" || v === "unwire" ? v : null;
+}
+function slugFromCredentialPath(credentialPath) {
+  const dir = dirname7(credentialPath);
+  const base = dir.split(/[\\/]/).pop() ?? "";
+  const m = base.match(/^securecoms-agent-(.+)$/);
+  if (m) return m[1];
+  const file = credentialPath.split(/[\\/]/).pop() ?? "agent";
+  return file.replace(/\.json$/, "");
 }
 function realServiceDeps() {
   return {
@@ -6718,13 +7534,41 @@ function realServiceDeps() {
       const r = spawnSync(cmd, args2, { encoding: "utf8" });
       return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
     },
-    writeFile: (p, data) => writeFileSync2(p, data, { mode: 420 }),
+    writeFile: (p, data) => writeFileSync3(p, data, { mode: 420 }),
     removeFile: (p) => rmSync(p, { force: true }),
-    mkdirp: (p) => mkdirSync(p, { recursive: true }),
+    mkdirp: (p) => mkdirSync2(p, { recursive: true }),
     fileExists: (p) => existsSync2(p),
     user: userInfo().username
   };
 }
+function chooseInstallExecPath(runningExecPath, override, deps) {
+  if (override) return override;
+  const r = resolveStableNodePath(runningExecPath, deps);
+  if (!r.stable) {
+    throw new Error(
+      "install: no reboot-stable Node found. Version-manager Nodes (nvm/asdf/fnm/volta/n) are removed on upgrade and will break the daemon after a reboot. Install a system Node (nodejs.org pkg \u2192 /usr/local/bin/node) or pass --exec-path <stable-path> to override."
+    );
+  }
+  return r.path;
+}
+function realResolveNodeDeps() {
+  const majorOf = (p) => {
+    const r = spawnSync(p, ["--version"], { encoding: "utf8" });
+    if (r.status !== 0) return null;
+    const m = /v?(\d+)\./.exec((r.stdout ?? "").trim());
+    return m ? Number(m[1]) : null;
+  };
+  return {
+    realpath: (p) => realpathSync(p),
+    fileExists: (p) => existsSync2(p),
+    nodeMajorOf: majorOf,
+    arch: () => process.arch,
+    archOf: (p) => {
+      const r = spawnSync(p, ["-p", "process.arch"], { encoding: "utf8" });
+      return r.status === 0 ? (r.stdout ?? "").trim() : null;
+    }
+  };
+}
 function realResolveDeps() {
   return {
     run: (cmd, args2) => {
@@ -6736,10 +7580,10 @@ function realResolveDeps() {
 }
 function realPrepDeps() {
   return {
-    readFile: (p) => readFileSync6(p, "utf8"),
-    writeFileMode: (p, data, mode) => writeFileSync2(p, data, { mode }),
+    readFile: (p) => readFileSync7(p, "utf8"),
+    writeFileMode: (p, data, mode) => writeFileSync3(p, data, { mode }),
     mkdirp: (p, mode) => {
-      mkdirSync(p, { recursive: true, mode: mode ?? 493 });
+      mkdirSync2(p, { recursive: true, mode: mode ?? 493 });
     },
     fileExists: (p) => existsSync2(p),
     realpath: (p) => realpathSync(p),
@@ -6770,11 +7614,111 @@ function realPrepDeps() {
     sleep: (ms) => new Promise((res) => setTimeout(res, ms))
   };
 }
+function realGetHealth(port) {
+  const r = spawnSync(process.execPath, [
+    "-e",
+    `const http=require('http');const q=http.get({host:'127.0.0.1',port:${port},path:'/healthz',timeout:800},res=>{let d='';res.on('data',c=>d+=c);res.on('end',()=>{process.stdout.write(d);process.exit(0)})});q.on('error',()=>process.exit(1));q.on('timeout',()=>process.exit(1));`
+  ], { encoding: "utf8" });
+  if (r.status !== 0) return null;
+  try {
+    return JSON.parse(r.stdout);
+  } catch {
+    return null;
+  }
+}
+function realReadFleet() {
+  return readFleet({
+    home: homedir2(),
+    listDir: (p) => {
+      try {
+        return readdirSync(p);
+      } catch {
+        return [];
+      }
+    },
+    readFile: (p) => readFileSync7(p, "utf8")
+  });
+}
+function runStatus() {
+  const deps = {
+    readFleet: realReadFleet,
+    probeConnect: (port) => {
+      const r = spawnSync(process.execPath, [
+        "-e",
+        `const s=require('net').connect(${port},'127.0.0.1');s.once('connect',()=>{s.destroy();process.exit(0)});s.once('error',()=>process.exit(1));setTimeout(()=>process.exit(1),500);`
+      ]);
+      return r.status === 0;
+    },
+    getHealth: realGetHealth
+  };
+  const rows = readFleetStatus(deps);
+  if (process.argv.includes("--json")) process.stdout.write(JSON.stringify(rows, null, 2) + "\n");
+  else process.stdout.write(renderStatusTable(rows));
+  process.exit(0);
+}
+function realCopyConnector(srcDir, dstDir) {
+  mkdirSync2(dstDir, { recursive: true });
+  for (const name of readdirSync(srcDir)) {
+    const srcPath = join11(srcDir, name);
+    if (statSync2(srcPath).isDirectory()) {
+      realCopyConnector(srcPath, join11(dstDir, name));
+      continue;
+    }
+    if (!/\.(js|json)$/.test(name)) continue;
+    writeFileSync3(join11(dstDir, name), readFileSync7(srcPath));
+  }
+}
+function realWriteBinding(dstDir, identityId) {
+  mkdirSync2(dstDir, { recursive: true });
+  writeFileSync3(join11(dstDir, "securecoms.binding.json"), JSON.stringify({ identity_id: identityId }) + "\n", { mode: 384 });
+}
+function realReadBinding(dstDir) {
+  try {
+    const parsed = JSON.parse(readFileSync7(join11(dstDir, "securecoms.binding.json"), "utf8"));
+    return parsed.identity_id ?? null;
+  } catch {
+    return null;
+  }
+}
+function realRemoveBinding(dstDir) {
+  rmSync(join11(dstDir, "securecoms.binding.json"), { force: true });
+}
+function realStatDir(p) {
+  try {
+    return statSync2(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function realWireArgv() {
+  if (process.argv.includes("--harness")) return process.argv;
+  const detected = detectHarness(homedir2(), realStatDir);
+  return detected ? [...process.argv, "--harness", detected] : process.argv;
+}
+function realWireDeps() {
+  return {
+    home: homedir2(),
+    argv: realWireArgv(),
+    readFleet: realReadFleet,
+    copyConnector: realCopyConnector,
+    writeBinding: realWriteBinding,
+    removeBinding: realRemoveBinding,
+    getHealth: realGetHealth,
+    log: (s) => process.stdout.write(s + "\n"),
+    // bin.ts's OWN import.meta.url — see connectorsSrcDir's doc comment in
+    // wire.ts for why it must be the entry point's URL, not wire.ts's.
+    connectorsSrcDir: connectorsSrcDir(import.meta.url)
+  };
+}
+function runWireVerb(verb) {
+  process.exit(verb === "wire" ? runWire(realWireDeps()) : runUnwire(realWireDeps()));
+}
 async function runServiceVerb(verb) {
   const credentialPath = argOrEnv("--credential", "SECURECOMS_CREDENTIAL");
   const label = argOrEnv("--label", "SECURECOMS_LABEL");
   if (verb === "install" ? !credentialPath : !credentialPath && !label) {
-    process.stderr.write(`usage: agent-bridge ${verb} --credential <path> [--label <name>] [--store <path>] [--port N] [--harness openclaw|hermes|custom]
+    const execPathUsage = verb === "install" ? " [--exec-path <path>]" : "";
+    process.stderr.write(`usage: agent-bridge ${verb} --credential <path> [--label <name>] [--store <path>] [--port N] [--harness openclaw|hermes|custom]${execPathUsage}
 `);
     process.exit(2);
   }
@@ -6787,12 +7731,28 @@ async function runServiceVerb(verb) {
   try {
     if (verb === "install") {
       const credAbs = isAbsolute2(credentialPath) ? credentialPath : resolve2(credentialPath);
+      const installExecPath = chooseInstallExecPath(
+        process.execPath,
+        argOrEnv("--exec-path", "SECURECOMS_EXEC_PATH"),
+        realResolveNodeDeps()
+      );
       const r = await orchestrateInstall({
         credentialAbsPath: credAbs,
         label,
         explicitPort: portStr ? Number(portStr) : void 0,
         harness: argOrEnv("--harness", "SECURECOMS_HARNESS"),
         home: homedir2(),
+        connectorsSrcDir: connectorsSrcDir(import.meta.url),
+        autoWireDeps: {
+          statDir: realStatDir,
+          // reuse bin.ts:235
+          readBinding: realReadBinding,
+          copyConnector: realCopyConnector,
+          // bin.ts:212 — one copy impl
+          writeBinding: realWriteBinding,
+          // bin.ts:226 — writes {identity_id}
+          log: (s) => process.stderr.write(s + "\n")
+        },
         prepDeps: realPrepDeps(),
         // O-1: the real installService is 2-arg; partially apply the deps so
         // orchestrateInstall only ever sees the 1-arg seam.
@@ -6803,13 +7763,14 @@ async function runServiceVerb(verb) {
           // O-2: not dropped
           port,
           label,
-          execPath: process.execPath,
+          execPath: installExecPath,
           binScript,
           home: homedir2(),
           uid: userInfo().uid
         })
       });
       process.stdout.write(r.echo);
+      if (r.harnessError) process.exit(1);
     } else {
       const input = {
         credentialPath: credentialPath ?? "",
@@ -6841,6 +7802,14 @@ async function main() {
     process.exit(1);
   }
   const verb = parseVerb(process.argv);
+  if (verb === "status") {
+    runStatus();
+    return;
+  }
+  if (verb === "wire" || verb === "unwire") {
+    runWireVerb(verb);
+    return;
+  }
   if (verb) {
     await runServiceVerb(verb);
     return;
@@ -6861,11 +7830,11 @@ async function main() {
 `);
     process.exit(1);
   }
-  const tokenFile = daemon.tokenFile ?? join9(dirname5(credentialPath), "bridge-token");
+  const tokenFile = daemon.tokenFile ?? join11(dirname7(credentialPath), "bridge-token");
   const token = resolveToken({ tokenFile, token: daemon.token });
   const agent = new BridgeAgent(cfg);
   await agent.start();
-  const tls = daemon.tls ? { cert: readFileSync6(daemon.tlsCert, "utf8"), key: readFileSync6(daemon.tlsKey, "utf8") } : void 0;
+  const tls = daemon.tls ? { cert: readFileSync7(daemon.tlsCert, "utf8"), key: readFileSync7(daemon.tlsKey, "utf8") } : void 0;
   const { server, closeAllSseStreams } = createHttpServer(agent, { token, allowOrigins: daemon.allowOrigins, tls, websocket: true });
   const agentWs = attachAgentWebSocket(server, agent, { token, allowOrigins: daemon.allowOrigins });
   let down = false;
@@ -6884,6 +7853,10 @@ async function main() {
   };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
+  const instanceId = newInstanceId();
+  const identityId = agent.health().identity_id;
+  const slug = slugFromCredentialPath(credentialPath);
+  process.once("exit", () => removeConnectionFileIfOwned(homedir2(), identityId, instanceId));
   server.listen(daemon.port, daemon.bind, () => {
     const scheme = tls ? "https" : "http";
     const wsScheme = tls ? "wss" : "ws";
@@ -6891,9 +7864,27 @@ async function main() {
 `);
     process.stderr.write(`[bridge] bearer token: ${tokenFingerprint(token)} (token file: ${tokenFile})
 `);
+    const addr = server.address();
+    const boundPort = typeof addr === "object" && addr ? addr.port : daemon.port;
+    try {
+      writeConnectionFile(homedir2(), buildConnectionFile({
+        identityId,
+        port: boundPort,
+        tokenFile,
+        slug,
+        label: slug,
+        instanceId,
+        now: (/* @__PURE__ */ new Date()).toISOString()
+      }));
+      process.stderr.write(`[bridge] connection file: ~/.securecoms/connections/${identityId}.json
+`);
+    } catch (e) {
+      process.stderr.write(`[bridge] WARN: could not write connection file: ${e?.message ?? e}
+`);
+    }
   });
 }
-var here = fileURLToPath(import.meta.url);
+var here = fileURLToPath2(import.meta.url);
 var isMain = !!process.argv[1] && refersToSameFile(here, process.argv[1], realpathSync);
 if (isMain) {
   main().catch((e) => {
@@ -6903,7 +7894,9 @@ if (isMain) {
   });
 }
 export {
+  chooseInstallExecPath,
   nodeMajorOk,
   parseVerb,
+  slugFromCredentialPath,
   tokenFingerprint
 };