@securecoms/agent-bridge 0.1.0 → 0.3.0

package/dist/bin.js

@@ -502,6 +502,144 @@ var payloadsSchema = {
           "type": "object"
         }
       }
+    },
+    "agent_action": {
+      "description": 'The agent_action E2E message body (agent action tree). NOT a message_type \u2014 it rides envelope message_type "system_event"; this "type":"agent_action" field is a body-level discriminator. Two phases: partial (throttled, incremental upsert-by-id while an agent works) and settled (one authoritative full-tree frame, terminal for its runId). Note: this def is compiled standalone (see validate.ts validateAgentActionPayload), so its node sub-schema is nested under a LOCAL $defs (resolved relative to this def, not the sibling top-level $defs) rather than cross-referenced.',
+      "$defs": {
+        "node": {
+          "type": "object",
+          "required": [
+            "id",
+            "type",
+            "title",
+            "status",
+            "ts"
+          ],
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "parentId": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "step",
+                "tool_call",
+                "sub_task",
+                "result"
+              ]
+            },
+            "title": {
+              "type": "string"
+            },
+            "status": {
+              "type": "string",
+              "enum": [
+                "pending",
+                "running",
+                "done",
+                "error"
+              ]
+            },
+            "detail": {
+              "type": "object",
+              "properties": {
+                "args": {},
+                "output": {},
+                "error": {
+                  "type": "string"
+                }
+              }
+            },
+            "ts": {
+              "type": "number"
+            }
+          }
+        }
+      },
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "v",
+            "type",
+            "phase",
+            "agentActionVersion",
+            "runId",
+            "nodes"
+          ],
+          "properties": {
+            "v": {
+              "const": 1
+            },
+            "type": {
+              "const": "agent_action"
+            },
+            "phase": {
+              "const": "partial"
+            },
+            "agentActionVersion": {
+              "const": "1"
+            },
+            "runId": {
+              "type": "string"
+            },
+            "nodes": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/node"
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "v",
+            "type",
+            "phase",
+            "agentActionVersion",
+            "runId",
+            "startedAt",
+            "endedAt",
+            "nodes"
+          ],
+          "properties": {
+            "v": {
+              "const": 1
+            },
+            "type": {
+              "const": "agent_action"
+            },
+            "phase": {
+              "const": "settled"
+            },
+            "agentActionVersion": {
+              "const": "1"
+            },
+            "runId": {
+              "type": "string"
+            },
+            "startedAt": {
+              "type": "number"
+            },
+            "endedAt": {
+              "type": "number"
+            },
+            "resultMessageId": {
+              "type": "string"
+            },
+            "nodes": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/node"
+              }
+            }
+          }
+        }
+      ]
     }
   }
 };
@@ -521,6 +659,11 @@ for (const t of MESSAGE_TYPES) {
   }
   payloadValidators.set(t, ajv.compile(def));
 }
+var agentActionDef = payloadDefs["agent_action"];
+if (!agentActionDef) {
+  throw new Error(`payloads.schema.json is missing the "agent_action" $defs schema`);
+}
+var agentActionValidator = ajv.compile(agentActionDef);
 
 // ../connect-core/dist/envelope/sign.js
 import { canonicalize } from "@agentvault/crypto/canonical";
@@ -853,6 +996,24 @@ async function staleEpochErrorFromResponse(res) {
     return null;
   return new StaleEpochError(Number(d.client_epoch ?? 0), Number(d.server_epoch ?? 0));
 }
+var AgentPausedError = class extends ConnectSdkError {
+  constructor() {
+    super("agent_paused: sending is paused for this agent in this room");
+  }
+};
+async function agentPausedErrorFromResponse(res) {
+  if (res.status !== 403)
+    return null;
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    return null;
+  }
+  const detail = body?.detail;
+  const err = detail?.error;
+  return err === "agent_paused" ? new AgentPausedError() : null;
+}
 
 // ../connect-sdk-ts/dist/envelope-builder.js
 async function buildOutboundEnvelope(p) {
@@ -957,7 +1118,7 @@ var ALWAYS_SAMPLE = /* @__PURE__ */ new Set([
 var KNOWN = new Set(Object.values(SPAN));
 
 // ../connect-sdk-ts/dist/groupkey/mls.js
-import { MLSGroupManager, bytesToHex, hexToBytes } from "@agentvault/crypto";
+import { MLSGroupManager, bytesToHex, hexToBytes, verifyApprovalArtifact } from "@agentvault/crypto";
 
 // ../connect-sdk-ts/dist/groupkey/operation-queue.js
 var MlsOperationQueue = class {
@@ -986,11 +1147,27 @@ var MlsOperationQueue = class {
   chainSize(channelId) {
     return this.inFlight.get(channelId) ?? 0;
   }
+  /** Number of channels with an in-flight or queued op. 0 == fully idle. */
+  get activeChannels() {
+    return this.chains.size;
+  }
+  /**
+   * H1 graceful-drain barrier: resolve once every op currently chained (in-flight
+   * + already queued) has SETTLED. Ops enqueued AFTER this call are not awaited —
+   * the caller must stop accepting new work first (e.g. close the ping stream).
+   * Uses allSettled so a rejected op can't make the drain reject. Lets a graceful
+   * shutdown wait for an in-flight commit/join/ack to finish before the DB handle
+   * is released, so a SIGTERM/`kickstart -k` can't tear MLS state mid-operation.
+   */
+  async idle() {
+    await Promise.allSettled([...this.chains.values()]);
+  }
 };
 
 // ../connect-sdk-ts/dist/groupkey/mls.js
 var LABEL = "agentvault-connect-v1";
 var DEFAULT_STUCK_THRESHOLD = 2;
+var DEFAULT_QUARANTINE_THRESHOLD = 8;
 var BootstrapRaceLostError = class extends Error {
   constructor() {
     super("bootstrap race lost: another device created the group; join instead");
@@ -1010,10 +1187,24 @@ var HealAddAfterRemoveError = class extends Error {
     this.cause = cause;
   }
 };
+var GuestHealStaleKpError = class extends Error {
+  constructor(kpId) {
+    super(`healDivergedGuest: fresh key package ${kpId} is gone/consumed \u2014 refusing to seal an un-openable Welcome`);
+    this.name = "GuestHealStaleKpError";
+  }
+};
+var ForgedCredentialError = class extends Error {
+  constructor(expected, actual) {
+    super(`heal: KeyPackage credential identity ${actual} != intended ${expected} \u2014 refusing to Add a forged leaf`);
+    this.name = "ForgedCredentialError";
+  }
+};
 var MlsGroupKeyProvider = class {
   o;
   suite;
   managers = /* @__PURE__ */ new Map();
+  /** One-time libsodium (WASM) warm-up guard — see ensureCryptoReady(). */
+  cryptoWarmed = false;
   /**
    * Per-CHANNEL Promise-chain mutex (gen2's MlsOperationQueue, ported). Every
    * manager-mutating operation on a channel takes this lock keyed by channelId,
@@ -1034,6 +1225,12 @@ var MlsGroupKeyProvider = class {
    * holds that channel's lock).
    */
   locks = new MlsOperationQueue();
+  /** Per-DEVICE publish mutex (B1). Serializes publishKeyPackage's check-then-act
+   *  guard so two callers (ingestOnce divergence branch vs selfHealSweep) cannot
+   *  both pass "no pending bundle", both POST, and orphan the first bundle when the
+   *  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();
   /**
    * Per-channel decrypt-error / stuck tracker (ADR-0002). Bounded by the number
    * of channels this device touches (channels are bounded; an entry is created
@@ -1043,14 +1240,22 @@ var MlsGroupKeyProvider = class {
    */
   errors = /* @__PURE__ */ new Map();
   stuckThreshold;
+  /** Consecutive-error threshold at which a wedged channel's row is quarantined
+   * (ack-drained). See {@link MlsGroupKeyProviderOpts.quarantineThreshold}. */
+  quarantineThreshold;
   /** Cumulative count of past-epoch application rows permanently skipped (acked
    *  and drained) because forward-secrecy has deleted their epoch's secrets. Read
    *  via {@link permanentlySkippedCount}. */
   permanentlySkipped = 0;
+  /** Cumulative count of rows ack-drained via QUARANTINE (P0a), as distinct from
+   *  the past-epoch {@link permanentlySkipped} drain. Read via
+   *  {@link quarantineDrainedCount}. */
+  quarantineDrained = 0;
   constructor(o) {
     this.o = o;
     this.suite = o.suite ?? "xchacha20poly1305";
     this.stuckThreshold = Math.max(1, o.stuckThreshold ?? DEFAULT_STUCK_THRESHOLD);
+    this.quarantineThreshold = Math.max(1, o.quarantineThreshold ?? DEFAULT_QUARANTINE_THRESHOLD);
   }
   get deviceId() {
     return this.o.deviceId;
@@ -1068,7 +1273,14 @@ var MlsGroupKeyProvider = class {
     const cid = row.connect_channel_id;
     if (!cid)
       return;
-    const e = this.errors.get(cid) ?? { decryptErrors: 0, consecutiveErrors: 0, lastErrorAt: null };
+    const e = this.errors.get(cid) ?? {
+      decryptErrors: 0,
+      consecutiveErrors: 0,
+      lastErrorAt: null,
+      quarantined: false,
+      wedgedRun: 0,
+      wedgedSignalled: false
+    };
     e.decryptErrors += 1;
     e.consecutiveErrors += 1;
     e.lastErrorAt = Date.now();
@@ -1078,12 +1290,42 @@ var MlsGroupKeyProvider = class {
    * A commit/application row for the channel decrypted cleanly: the channel is
    * advancing, so clear the consecutive-error run (un-sticks it). Leaves the
    * cumulative `decryptErrors` total intact for diagnostics. No-op for a channel
-   * that never errored.
+   * that never errored. Also clears QUARANTINE state (P0a): a healed/rejoined
+   * channel resumes normal processing and can quarantine again later if it
+   * re-wedges (the onWedged guard is reset so the hook can fire again).
    */
   recordDecryptSuccess(channelId) {
     const e = this.errors.get(channelId);
-    if (e && e.consecutiveErrors !== 0)
+    if (!e)
+      return;
+    if (e.consecutiveErrors !== 0)
       e.consecutiveErrors = 0;
+    e.wedgedRun = 0;
+    e.quarantined = false;
+    e.wedgedSignalled = false;
+  }
+  /**
+   * Called from the decrypt-failure catch in {@link receiveOnce} when the
+   * channel's consecutive-error run has just reached {@link quarantineThreshold}
+   * and the row was NOT already drained via the past-epoch `permanentlyDead`
+   * check (P0a, daemon-stability). Marks the channel quarantined and fires
+   * {@link MlsGroupKeyProviderOpts.onWedged} exactly once per episode. Does NOT
+   * itself ack the row — the caller pushes `row.queue_id` onto the same acked
+   * list the `permanentlyDead` drain uses, flushed via `ackDelivery` at the end
+   * of `receiveOnce`. Deliberately independent of `liveEpoch`: it must work even
+   * when there is no local state for the channel at all (the no-local-state /
+   * Hermes storm case), because quarantine is a pure consecutive-failure-count
+   * decision, not an epoch comparison.
+   */
+  quarantineChannel(channelId) {
+    const e = this.errors.get(channelId);
+    if (!e)
+      return;
+    e.quarantined = true;
+    if (!e.wedgedSignalled) {
+      e.wedgedSignalled = true;
+      this.o.onWedged?.(channelId);
+    }
   }
   /**
    * Snapshot of per-channel decrypt-error / stuck state (ADR-0002 observability).
@@ -1100,11 +1342,42 @@ var MlsGroupKeyProvider = class {
         decryptErrors: e.decryptErrors,
         consecutiveErrors: e.consecutiveErrors,
         lastErrorAt: e.lastErrorAt,
-        stuck: e.consecutiveErrors >= this.stuckThreshold
+        stuck: e.consecutiveErrors >= this.stuckThreshold,
+        quarantined: e.quarantined
       };
     }
     return out;
   }
+  /**
+   * H1 graceful shutdown: resolve once every in-flight per-channel op AND the
+   * publish lock have settled, or `deadlineMs` elapses (bounded so a hung network
+   * op can't block process exit). The caller MUST have already stopped feeding new
+   * work (closed the ping stream) so the queues can actually drain. Loops because a
+   * settling op can chain a follow-on (e.g. a commit that then drains a pending
+   * commit). Lets close() wait for an in-flight commit/join/ack to finish before
+   * the DB handle is released — a SIGTERM / `kickstart -k` can no longer tear MLS
+   * state mid-operation (a half-applied commit, or a join whose Welcome was acked
+   * but whose state was not yet saved).
+   */
+  async drainInFlight(deadlineMs = 5e3) {
+    let timer;
+    const deadline = new Promise((res) => {
+      timer = setTimeout(res, deadlineMs);
+      timer.unref?.();
+    });
+    const drain = (async () => {
+      while (this.locks.activeChannels > 0 || this.publishLock.activeChannels > 0) {
+        await this.locks.idle();
+        await this.publishLock.idle();
+      }
+    })();
+    try {
+      await Promise.race([drain, deadline]);
+    } finally {
+      if (timer)
+        clearTimeout(timer);
+    }
+  }
   /** Total past-epoch rows permanently skipped (acked without decrypting) since
    *  this provider was instantiated. A permanently-undecryptable row is one whose
    *  `row.epoch` is strictly less than the channel's live epoch: forward-secrecy
@@ -1112,6 +1385,12 @@ var MlsGroupKeyProvider = class {
   permanentlySkippedCount() {
     return this.permanentlySkipped;
   }
+  /** Total rows ack-drained via QUARANTINE (P0a) since this provider was
+   *  instantiated — a wedged channel's undecryptable backlog, distinct from the
+   *  past-epoch {@link permanentlySkippedCount} drain. */
+  quarantineDrainedCount() {
+    return this.quarantineDrained;
+  }
   /** Evict the live in-memory MLS group manager for a channel. Used when the
    *  device leaves or deletes a channel: dropping the persisted store record is
    *  not enough on its own, because a warm manager keeps decrypting until the
@@ -1280,16 +1559,99 @@ var MlsGroupKeyProvider = class {
     const w = rows.find((r) => r.message_type === "welcome" && r.connect_channel_id != null);
     return w?.connect_channel_id ?? null;
   }
+  /**
+   * Initialize the ts-mls libsodium (WASM) backend ONCE before any store
+   * operation that deserializes a persisted KeyPackage. generateKeyPackage
+   * awaits sodium.ready and is pure in-memory (it neither publishes to the
+   * backend nor writes the store), so the throwaway bundle is a side-effect-free
+   * warm-up. Without it, the FIRST loadPendingBundle at boot (the republish
+   * guard, and the join path) runs while WASM is still cold, throws deep in the
+   * crypto ("Cannot read properties of undefined (reading '_malloc')"), is caught
+   * and misread as "no held bundle", and the daemon mints + republishes a FRESH
+   * KeyPackage on every restart — orphaning every Welcome sealed to the prior
+   * published KP (the root cause of "fresh DM never opens" across restarts).
+   * Idempotent and cheap (~ms); the flag makes repeat calls no-ops.
+   */
+  async ensureCryptoReady() {
+    if (this.cryptoWarmed)
+      return;
+    await new MLSGroupManager().generateKeyPackage(this.o.identity);
+    this.cryptoWarmed = true;
+  }
   async publishKeyPackage() {
+    await this.ensureCryptoReady();
+    return this.publishLock.run(this.o.deviceId, () => this.publishKeyPackageUnlocked());
+  }
+  /**
+   * Force a FRESH published KeyPackage even when a pending bundle is already held.
+   *
+   * `publishKeyPackage`'s republish guard deliberately no-ops while a bundle is
+   * held (so a normal re-publish can't orphan a leaf a queued Welcome needs). But
+   * the reset self-heal reaches here only AFTER a fully-verified supersede Welcome
+   * FAILED to open ("No matching secret found") — proving the currently-published
+   * KP has diverged from our held bundle, so that bundle is already useless for
+   * opening any Welcome sealed to the published KP. Delete it (dropping the guard)
+   * and publish anew under the same device publish-lock, so the server's published
+   * KP now matches a bundle we hold and the owner's re-Welcome is openable. Returns
+   * the new KP id. Only the reset-unopenable self-heal calls this.
+   */
+  async forceRepublishKeyPackage() {
+    return this.publishLock.run(this.o.deviceId, async () => {
+      await this.o.store.deletePendingBundle(this.o.deviceId);
+      return this.publishKeyPackageUnlocked();
+    });
+  }
+  /**
+   * True iff we hold a pending bundle AND the server's currently-advertised
+   * KeyPackage for this device is that SAME bundle's public KeyPackage.
+   *
+   * The reset self-heal uses this to avoid a needless — and harmful —
+   * force-republish. A failed `joinFromWelcome` on a supersede proves only that
+   * THIS Welcome's sealed KP != our held bundle; it does NOT prove the CURRENTLY
+   * published KP diverged. In the common case the reset committer simply sealed to
+   * an OLDER KP snapshot while the current published KP still equals our held
+   * bundle — a plain re-Welcome (re-sealed to the current published KP) then opens,
+   * and deleting the shared per-device bundle would ORPHAN other channels' openable
+   * Welcomes sealed to it (the multichannel-join case). Only when this returns
+   * false (published KP genuinely diverged from held) is a force-republish warranted:
+   * in the normal single-daemon case every currently-sealed Welcome uses the published
+   * KP, so deleting the held bundle orphans nothing; a Welcome sealed to the held
+   * bundle can only exist in a rare multi-instance / out-of-band-republish window, and
+   * even then a supersede Welcome self-heals next cycle (held == published again).
+   *
+   * Best-effort: any error resolving either side returns false, so the caller
+   * force-republishes (the conservative recovery). */
+  async heldBundleMatchesPublishedKp() {
+    try {
+      const bundle = await this.o.store.loadPendingBundle(this.o.deviceId);
+      if (!bundle)
+        return false;
+      const heldHex = bytesToHex(MLSGroupManager.serializeKeyPackage(bundle.publicPackage));
+      const published = await this.o.backend.fetchKeyPackages([this.o.deviceId]);
+      const pubHex = published[this.o.deviceId];
+      return !!pubHex && pubHex === heldHex;
+    } catch {
+      return false;
+    }
+  }
+  async publishKeyPackageUnlocked() {
     if (await this.o.store.loadPendingBundle(this.o.deviceId)) {
       console.warn("publishKeyPackage: pending bundle exists; skipping republish");
-      return;
+      return await this.o.store.loadLastKpId(this.o.deviceId) ?? "";
     }
+    console.warn(`publishKeyPackage: minting a fresh KeyPackage (rotation) for device ${this.o.deviceId.slice(0, 8)}`);
     const mgr = new MLSGroupManager();
     const bundle = await mgr.generateKeyPackage(this.o.identity);
     const hex = bytesToHex(MLSGroupManager.serializeKeyPackage(bundle.publicPackage));
-    await this.o.backend.publishKeyPackage(this.o.deviceId, hex);
-    await this.o.store.savePendingBundle(this.o.deviceId, bundle);
+    const id = await this.o.backend.publishKeyPackage(this.o.deviceId, hex);
+    await this.o.store.saveLastKpAndBundle(this.o.deviceId, id, bundle);
+    return id;
+  }
+  /** The server-assigned id of the last KeyPackage this device published,
+   * or null if none has been published yet. Lets a diverged guest's self-heal
+   * signal name its outstanding KP (P2-A). */
+  async getLastPublishedKpId() {
+    return this.o.store.loadLastKpId(this.o.deviceId);
   }
   async ensureSession(channelId, opts) {
     return this.locks.run(channelId, () => this.ensureSessionUnlocked(channelId, opts));
@@ -1297,6 +1659,7 @@ var MlsGroupKeyProvider = class {
   async ensureSessionUnlocked(channelId, opts) {
     if (!opts.forceReinit && await this.o.store.load(channelId))
       return;
+    await this.ensureCryptoReady();
     let bundle = await this.o.store.loadPendingBundle(this.o.deviceId);
     if (!bundle && (opts.bootstrap || opts.forceReinit)) {
       await this.publishKeyPackage();
@@ -1327,7 +1690,6 @@ var MlsGroupKeyProvider = class {
       });
       await this.o.store.save(channelId, mgr.exportState());
       this.managers.set(channelId, mgr);
-      await this.o.store.deletePendingBundle(this.o.deviceId);
       return;
     }
     if (opts.bootstrap) {
@@ -1355,30 +1717,23 @@ var MlsGroupKeyProvider = class {
       });
       this.managers.set(channelId, mgr);
       await this.o.store.save(channelId, mgr.exportState());
-      await this.o.store.deletePendingBundle(this.o.deviceId);
     } else {
       const rows = await this.o.backend.pullDelivery(this.o.deviceId);
       const w = rows.find((r) => r.message_type === "welcome" && (r.connect_channel_id === channelId || r.connect_channel_id == null));
       if (!w)
         throw new Error("ensureSession(join): no Welcome available yet for this channel");
       const mgr = new MLSGroupManager();
-      await mgr.joinFromWelcome(hexToBytes(w.payload), bundle);
+      try {
+        await mgr.joinFromWelcome(hexToBytes(w.payload), bundle);
+      } catch (err) {
+        this.recordDecryptError(w, err);
+        console.warn(`ensureSession(join): discarding un-openable Welcome for channel ${channelId} (queue_id=${w.queue_id}); private KeyPackage key no longer held`);
+        await this.o.backend.ackDelivery(this.o.deviceId, [w.queue_id]);
+        return;
+      }
       this.managers.set(channelId, mgr);
       await this.o.store.save(channelId, mgr.exportState());
       await this.o.backend.ackDelivery(this.o.deviceId, [w.queue_id]);
-      const remaining = await this.o.backend.pullDelivery(this.o.deviceId);
-      let burstPending = false;
-      for (const r of remaining) {
-        if (r.message_type !== "welcome")
-          continue;
-        const cid = r.connect_channel_id;
-        if (!cid || !await this.o.store.load(cid)) {
-          burstPending = true;
-          break;
-        }
-      }
-      if (!burstPending)
-        await this.o.store.deletePendingBundle(this.o.deviceId);
     }
   }
   /**
@@ -1397,7 +1752,7 @@ var MlsGroupKeyProvider = class {
   async addMemberToLiveGroup(channelId, newDeviceId) {
     return this.locks.run(channelId, () => this.evictOnThrow(channelId, () => this.addMemberToLiveGroupUnlocked(channelId, newDeviceId, 0)));
   }
-  async addMemberToLiveGroupUnlocked(channelId, newDeviceId, _attempt) {
+  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]);
@@ -1405,6 +1760,13 @@ var MlsGroupKeyProvider = class {
     if (!hex)
       throw new Error(`addMemberToLiveGroup: no published KeyPackage for device ${newDeviceId}`);
     const pkg = MLSGroupManager.deserializeKeyPackage(hexToBytes(hex));
+    if (opts?.expectedIdentityId) {
+      const cred = pkg.leafNode.credential;
+      const claimed = cred.credentialType === "basic" ? new TextDecoder().decode(cred.identity) : "";
+      if (claimed !== opts.expectedIdentityId) {
+        throw new ForgedCredentialError(opts.expectedIdentityId, claimed);
+      }
+    }
     const priorEpoch = Number(mgr.epoch);
     const { commit, welcome } = await mgr.addMembers([pkg]);
     const members = [.../* @__PURE__ */ new Set([...init.member_device_ids ?? [this.o.deviceId], newDeviceId])];
@@ -1426,7 +1788,13 @@ var MlsGroupKeyProvider = class {
         await this.drainChannelCommitsUnlocked(this.o.deviceId, channelId);
       } catch {
       }
-      return this.addMemberToLiveGroupUnlocked(channelId, newDeviceId, _attempt + 1);
+      try {
+        const work = await this.o.backend.getCommitterWork(channelId);
+        if (!work.adds.includes(newDeviceId))
+          return;
+      } catch {
+      }
+      return this.addMemberToLiveGroupUnlocked(channelId, newDeviceId, _attempt + 1, opts);
     }
     await this.o.store.save(channelId, mgr.exportState());
   }
@@ -1618,7 +1986,7 @@ var MlsGroupKeyProvider = class {
    * Unlocked committer ops this composes (removeDeviceFromLiveGroupUnlocked /
    * addMemberToLiveGroupUnlocked) — no weaker path is introduced.
    */
-  async healDivergedMember(channelId, memberDeviceId) {
+  async healDivergedMember(channelId, memberDeviceId, opts) {
     return this.locks.run(channelId, () => this.evictOnThrow(channelId, async () => {
       const kps = await this.o.backend.fetchKeyPackages([memberDeviceId]);
       const hex = kps[memberDeviceId];
@@ -1629,6 +1997,9 @@ var MlsGroupKeyProvider = class {
         throw new Error(`healDivergedMember: unexpected credential type ${cred.credentialType} (expected basic)`);
       }
       const identity = new TextDecoder().decode(cred.identity);
+      if (opts?.expectedIdentityId && identity !== opts.expectedIdentityId) {
+        throw new ForgedCredentialError(opts.expectedIdentityId, identity);
+      }
       const mgr = await this.manager(channelId);
       const leaves = mgr.leafIndicesForIdentity(identity);
       if (leaves.length > 1) {
@@ -1645,7 +2016,7 @@ var MlsGroupKeyProvider = class {
         }
       }
       try {
-        await this.addMemberToLiveGroupUnlocked(channelId, memberDeviceId, 0);
+        await this.addMemberToLiveGroupUnlocked(channelId, memberDeviceId, 0, opts);
       } catch (e) {
         if (removeLanded)
           throw new HealAddAfterRemoveError(e);
@@ -1653,6 +2024,48 @@ var MlsGroupKeyProvider = class {
       }
     }));
   }
+  /** Re-Welcome a fallen-behind GUEST (same device, stale leaf) back to the live
+   *  epoch. Identical crypto to healDivergedMember (Remove-first same-device, then
+   *  re-Add at the live epoch); named separately for the Phase 2 guest dispatch/
+   *  sweep call sites and for the cross-tenant authz that differs only server-side.
+   *  Caller contract (like the member path): the guest republishes a fresh
+   *  KeyPackage first, then resetChannelForRejoin + joinAndReconcile after.
+   *
+   *  Phase 2 fail-closed gate: `expectedKpId` is the id of the guest's fresh,
+   *  retained KeyPackage (the one the caller confirmed the guest republished).
+   *  Before doing anything else we fetch it BY ID and refuse
+   *  ({@link GuestHealStaleKpError}) if it's gone — never Remove+re-Add on the
+   *  strength of "some KeyPackage is published for this device", because that
+   *  could be stale, consumed, or absent and would seal an un-openable Welcome,
+   *  bricking the guest instead of healing it. Once the gate passes we delegate to
+   *  the proven {@link healDivergedMember}: given `publish_key_package`'s
+   *  delete-and-replace semantics and the guest's pending-bundle republish guard,
+   *  the by-device fetch inside healDivergedMember resolves to exactly this same
+   *  KeyPackage — the id-fetch here is the fail-closed contract, the member heal
+   *  is the mechanism. */
+  async healDivergedGuest(channelId, guestDeviceId, expectedKpId) {
+    const hex = await this.o.backend.fetchKeyPackageById(expectedKpId);
+    if (!hex)
+      throw new GuestHealStaleKpError(expectedKpId);
+    return this.healDivergedMember(channelId, guestDeviceId);
+  }
+  /** Re-Welcome a diverged agent/member with BOTH the fail-closed fresh-KP gate
+   *  AND the TOCTOU-safe anti-forgery check. Mirrors {@link healDivergedGuest}'s
+   *  id-by-value gate (refuse if `expectedKpId` is gone/consumed →
+   *  {@link GuestHealStaleKpError}, never sealing an un-openable Welcome), then
+   *  delegates to {@link healDivergedMember} with `expectedIdentityId` so the
+   *  committed-bytes assertion binds the re-Added leaf to the intended identity
+   *  (throws {@link ForgedCredentialError} on a credential-identity mismatch,
+   *  including on the 409-retry path). This is the entry point the owner's
+   *  agent-diverged heal sweep uses: `expectedKpId`/`expectedIdentityId` come from
+   *  the welcome-request row the agent published, so a compromised agent cannot
+   *  substitute a KeyPackage that forges a different identity. */
+  async healDivergedMemberFresh(channelId, memberDeviceId, expectedKpId, expectedIdentityId) {
+    const hex = await this.o.backend.fetchKeyPackageById(expectedKpId);
+    if (!hex)
+      throw new GuestHealStaleKpError(expectedKpId);
+    return this.healDivergedMember(channelId, memberDeviceId, { expectedIdentityId });
+  }
   /**
    * Member-side: drop the diverged local state for a channel so a subsequent
    * {@link joinAndReconcile} consumes the committer's fresh Welcome (from
@@ -1687,6 +2100,56 @@ var MlsGroupKeyProvider = class {
       this.errors.delete(channelId);
     });
   }
+  /** Owner-attested reset supersede (owner/web side, Task 9). Mirrors the
+   * ensureSession forceReinit branch but posts a client-chosen new_group_id +
+   * signed attestation to the reset-mode endpoint, then builds + distributes
+   * the new group. Runs under the channel lock (serialized against
+   * receiveOnce / committer ops).
+   *
+   * `opts.otherDeviceIds` MUST be the CHANNEL-WIDE union of every active
+   * member device holding an unconsumed KeyPackage (H2) -- the caller (the web
+   * client's members-endpoint enumeration) is responsible for that union;
+   * this method only handles the mechanical THIS-device exclusion: this
+   * device is the committer that creates the group, so it must not be in the
+   * MLS addMembers set (adding your own new leaf via addMembers is
+   * nonsensical / unsupported). The wire member_device_ids below re-includes
+   * it as [deviceId, ...others] (deduped), so the Task-2 completeness guard
+   * (required subset of supplied) is still satisfied even though it never
+   * goes through addMembers. */
+  async resetSessionSupersede(channelId, opts) {
+    return this.locks.run(channelId, async () => {
+      let bundle = await this.o.store.loadPendingBundle(this.o.deviceId);
+      if (!bundle) {
+        await this.publishKeyPackage();
+        bundle = await this.o.store.loadPendingBundle(this.o.deviceId);
+      }
+      if (!bundle)
+        throw new Error("resetSessionSupersede: call publishKeyPackage() first");
+      const others = [...new Set(opts.otherDeviceIds)].filter((d) => d !== this.o.deviceId);
+      const reinit = await this.o.backend.resetReinitConnectChannelGroup(channelId, [this.o.deviceId, ...others], { newGroupId: opts.newGroupId, signatureHex: opts.signatureHex, nonceHex: opts.nonceHex, signedContentHex: opts.signedContentHex });
+      const mgr = new MLSGroupManager();
+      await mgr.createGroup(new TextEncoder().encode(reinit.group_id), bundle);
+      const kps = await this.o.backend.fetchKeyPackages(others);
+      const pkgs = others.map((d) => {
+        const hex = kps[d];
+        if (!hex)
+          throw new Error(`resetSessionSupersede: no published KeyPackage for device ${d}`);
+        return MLSGroupManager.deserializeKeyPackage(hexToBytes(hex));
+      });
+      const { commit, welcome } = await mgr.addMembers(pkgs);
+      await this.o.backend.distribute(reinit.group_id, {
+        device_id: this.o.deviceId,
+        commit: bytesToHex(commit),
+        commit_epoch: Number(mgr.epoch),
+        expected_epoch: reinit.current_epoch,
+        member_device_ids: [this.o.deviceId, ...others],
+        welcomes: welcome ? others.map((d) => ({ target_device_id: d, payload: bytesToHex(welcome) })) : []
+      });
+      await this.o.store.save(channelId, mgr.exportState());
+      this.managers.set(channelId, mgr);
+      await this.o.store.deletePendingBundle(this.o.deviceId);
+    });
+  }
   /** Returns true when an in-memory MLS manager is live for the channel.
    * Cheap synchronous check; does NOT consult the store. */
   hasChannelState(channelId) {
@@ -1700,6 +2163,19 @@ var MlsGroupKeyProvider = class {
       return true;
     return await this.o.store.load(channelId) !== 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.
+   *
+   * Primarily used by the gate (S20) to assert that a peer-committer 409-retry
+   * does NOT create a duplicate leaf for an already-added device. A return value
+   * of 1 is the expected healthy state; 0 means not yet a member; > 1 means a
+   * duplicate-leaf bug fired (the S3 guard failed to suppress the re-Add).
+   */
+  async leafCountForIdentity(channelId, identityId) {
+    const mgr = await this.manager(channelId);
+    return mgr.leafIndicesForIdentity(identityId).length;
+  }
   /** Returns true when the live in-memory MLS tree for `channelId` contains at
    * least one leaf bearing `identityId` as its credential. Used by the agent
    * admission watcher (liveness §4.3) to decide whether an Add+Welcome is still
@@ -1719,18 +2195,130 @@ var MlsGroupKeyProvider = class {
     const r = await this.o.backend.getConnectChannelGroup(channelId);
     return { exists: r.exists, groupId: r.group_id, epoch: r.current_epoch };
   }
+  /**
+   * Verified group supersede for the agent's receive pump (owner-attested reset).
+   * Returns true when the channel's state was swapped to the new group and the
+   * Welcome row acked; false when the supersede was REFUSED (row left un-acked).
+   *
+   * FAIL-CLOSED order (spec §3): step-0 pin-presence guard FIRST (no pinned owner
+   * ⇒ refuse, never call verify), then structural signer check, then attestation
+   * verify against the NON-EMPTY pinned key, then post-join group-id assertion.
+   */
+  async trySupersede(channelId, row, heldGroupId) {
+    const owner = this.o.onResolvePinnedOwner ? await this.o.onResolvePinnedOwner(channelId) : null;
+    if (!owner || !owner.publicKeyHex) {
+      this.recordDecryptError(row, new Error("supersede refused: no pinned owner key (step-0 guard)"));
+      return false;
+    }
+    const retired = await this.o.store.loadRetiredGroupIds(channelId);
+    if (retired.includes(row.group_id)) {
+      this.recordDecryptError(row, new Error(`supersede refused: group ${row.group_id} is retired (rollback/replay)`));
+      return false;
+    }
+    const att = await this.o.backend.fetchResetAttestation(row.group_id);
+    if (!att) {
+      this.recordDecryptError(row, new Error(`supersede refused: no attestation for group ${row.group_id}`));
+      return false;
+    }
+    if (att.signerIdentityId !== owner.identityId) {
+      this.recordDecryptError(row, new Error("supersede refused: signer is not the pinned owner"));
+      return false;
+    }
+    let content;
+    try {
+      content = JSON.parse(att.signedContent);
+    } catch {
+      this.recordDecryptError(row, new Error("supersede refused: unparseable signed_content"));
+      return false;
+    }
+    if (content.channel_id !== row.connect_channel_id || content.new_group_id !== row.group_id) {
+      this.recordDecryptError(row, new Error("supersede refused: attestation channel/group mismatch"));
+      return false;
+    }
+    const ok = await verifyApprovalArtifact({ content, signature: att.signatureHex, signerPublicKey: owner.publicKeyHex, createdAt: "", version: 1 }, owner.publicKeyHex);
+    if (!ok) {
+      this.recordDecryptError(row, new Error("supersede refused: signature does not verify against pinned owner key"));
+      return false;
+    }
+    const bundle = await this.o.store.loadPendingBundle(this.o.deviceId);
+    if (!bundle) {
+      this.recordDecryptError(row, new Error("supersede refused: no pending KeyPackage bundle to open the new Welcome"));
+      return false;
+    }
+    return await this.locks.run(channelId, async () => {
+      const mgr = new MLSGroupManager();
+      try {
+        await mgr.joinFromWelcome(hexToBytes(row.payload), bundle);
+      } catch (err) {
+        this.recordDecryptError(row, err);
+        if (typeof process !== "undefined" && process.env?.SECURECOMS_TRACE_DELIVERY) {
+          console.warn(`[trace] supersede joinFromWelcome FAILED ch=${channelId.slice(0, 8)} g=${row.group_id.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)} -> self-heal`);
+        }
+        let requested = false;
+        try {
+          requested = await this.o.onSupersedeUnopenable?.(channelId, row.group_id) ?? false;
+        } catch {
+        }
+        if (requested) {
+          try {
+            await this.o.backend.ackDelivery(this.o.deviceId, [row.queue_id]);
+          } catch {
+          }
+        }
+        return false;
+      }
+      if (new TextDecoder().decode(mgr.groupId) !== row.group_id) {
+        this.recordDecryptError(row, new Error("supersede refused: post-join group id != attested new_group_id"));
+        return false;
+      }
+      this.evictChannelState(channelId);
+      await this.o.store.delete(channelId);
+      await this.o.store.discardStaging(channelId);
+      await this.o.store.addRetiredGroupId(channelId, heldGroupId);
+      this.errors.delete(channelId);
+      this.managers.set(channelId, mgr);
+      await this.o.store.save(channelId, mgr.exportState());
+      await this.o.backend.ackDelivery(this.o.deviceId, [row.queue_id]);
+      return true;
+    });
+  }
   async receiveOnce(deviceId) {
     const rows = await this.o.backend.pullDelivery(deviceId);
+    if (typeof process !== "undefined" && process.env?.SECURECOMS_TRACE_DELIVERY && rows.length) {
+      console.warn(`[trace] receiveOnce pulled ${rows.length}: ` + rows.map((r) => `${r.message_type}@e${r.epoch}/ch${(r.connect_channel_id || "-").slice(0, 8)}/g${(r.group_id || "-").slice(0, 8)}`).join(", "));
+    }
     const appEntries = [];
     const handshakeAcked = [];
+    const supersededChannelIds = [];
     const order = { welcome: 0, commit: 1, application: 2 };
     rows.sort((a, b) => order[a.message_type] - order[b.message_type]);
     for (const row of rows) {
       try {
         if (row.message_type === "welcome") {
           const wcid = row.connect_channel_id;
-          if (wcid && await this.o.store.load(wcid)) {
-            handshakeAcked.push(row.queue_id);
+          if (wcid) {
+            const existing = await this.o.store.load(wcid);
+            if (existing) {
+              let heldGroupId = null;
+              try {
+                const mgr = await this.manager(wcid);
+                heldGroupId = new TextDecoder().decode(mgr.groupId);
+              } catch {
+                heldGroupId = null;
+              }
+              if (typeof process !== "undefined" && process.env?.SECURECOMS_TRACE_DELIVERY) {
+                console.warn(`[trace] welcome ch=${wcid.slice(0, 8)} rowGroup=${(row.group_id || "-").slice(0, 8)} heldGroup=${heldGroupId ? heldGroupId.slice(0, 8) : "NULL"} -> ${heldGroupId === null ? "SKIP(manager-unloadable)" : heldGroupId === row.group_id ? "stray-ack" : "trySupersede"}`);
+              }
+              if (heldGroupId !== null && heldGroupId === row.group_id) {
+                handshakeAcked.push(row.queue_id);
+              } else if (heldGroupId !== null && heldGroupId !== row.group_id) {
+                const ok = await this.trySupersede(wcid, row, heldGroupId);
+                if (ok)
+                  supersededChannelIds.push(wcid);
+              }
+            } else if (typeof process !== "undefined" && process.env?.SECURECOMS_TRACE_DELIVERY) {
+              console.warn(`[trace] welcome ch=${wcid.slice(0, 8)} rowGroup=${(row.group_id || "-").slice(0, 8)} -> NO-LOCAL-STATE (leave un-acked for join path)`);
+            }
           }
         } else if (row.message_type === "commit") {
           const cid = row.connect_channel_id;
@@ -1764,12 +2352,14 @@ var MlsGroupKeyProvider = class {
             plaintext,
             envelope,
             receivedAt: Date.now(),
-            retryCount: 0
+            retryCount: 0,
+            expires_at: row.expires_at
           });
         }
       } catch (err) {
         this.recordDecryptError(row, err);
         const cid = row.connect_channel_id;
+        let drained = false;
         if (cid && typeof row.epoch === "number") {
           let liveEpoch;
           try {
@@ -1781,12 +2371,27 @@ var MlsGroupKeyProvider = class {
           if (permanentlyDead) {
             handshakeAcked.push(row.queue_id);
             this.permanentlySkipped++;
+            drained = true;
+          }
+        }
+        if (!drained && cid) {
+          const e = this.errors.get(cid);
+          if (e) {
+            e.wedgedRun += 1;
+            if (e.wedgedRun >= this.quarantineThreshold) {
+              handshakeAcked.push(row.queue_id);
+              this.quarantineDrained++;
+              this.quarantineChannel(cid);
+            }
           }
         }
       }
     }
     if (handshakeAcked.length)
       await this.o.backend.ackDelivery(deviceId, handshakeAcked);
+    if (supersededChannelIds.length) {
+      Object.defineProperty(appEntries, "supersededChannelIds", { value: supersededChannelIds, enumerable: false });
+    }
     return appEntries;
   }
   /**
@@ -1867,11 +2472,38 @@ var FRAME_PARSERS = {
       roomId: d?.room_id ? str(d.room_id) : void 0,
       requestingDeviceId: str(d?.requesting_device_id),
       requestingIdentityId: d?.requesting_identity_id ? str(d.requesting_identity_id) : void 0,
+      freshKpId: d?.fresh_kp_id ? String(d.fresh_kp_id) : void 0,
       requestId: d?.request_id ? str(d.request_id) : void 0
     }
+  }),
+  // Diverged-guest heal Phase 2 (P2-A): the server wakes surviving devices to
+  // heal a guest whose ratchet tree diverged. Durable state is the
+  // mls_guest_heal_request row; this frame is just the wakeup hint.
+  mls_guest_heal_requested: (d) => ({
+    guestHealRequest: {
+      groupId: str(d?.group_id),
+      channelId: str(d?.channel_id),
+      enclaveId: str(d?.enclave_id),
+      guestIdentityId: str(d?.guest_identity_id),
+      guestDeviceId: str(d?.guest_device_id),
+      freshKpId: str(d?.fresh_kp_id),
+      requestId: str(d?.request_id)
+    }
   })
 };
 var S2C_FRAME_NAMES = new Set(Object.keys(FRAME_PARSERS));
+var TERMINAL_FRAME_EVENTS = /* @__PURE__ */ new Set([
+  "device_revoked",
+  "identity.revoked"
+]);
+function terminalFrameReason(frame) {
+  if (!frame || typeof frame !== "object")
+    return void 0;
+  const f = frame;
+  if (typeof f.event !== "string" || !TERMINAL_FRAME_EVENTS.has(f.event))
+    return void 0;
+  return typeof f.data?.reason === "string" && f.data.reason ? f.data.reason : f.event;
+}
 function parseServerFrame(frame) {
   if (!frame || typeof frame !== "object")
     return void 0;
@@ -1887,8 +2519,22 @@ function openDeliveryPings(o) {
   const rng = o.rng ?? Math.random;
   const maxQueue = o.maxQueue ?? 8;
   const stableResetMs = o.stableResetMs ?? 1e4;
+  const hardened = o.hardened ?? false;
+  const now = o.now ?? (() => Date.now());
+  const silenceMs = o.silenceMs ?? 9e4;
+  const watchdogMs = o.watchdogMs ?? 3e4;
+  const wakeGapMs = o.wakeGapMs ?? 12e4;
+  const authWarCap = o.authWarCap ?? 3;
+  const authWarWindowMs = o.authWarWindowMs ?? 12e4;
+  const lifecycle = (event, detail) => {
+    try {
+      o.onLifecycle?.(event, detail);
+    } catch {
+    }
+  };
   let closed = false;
   let attempt = 0;
+  let connectGen = 0;
   let sock;
   let backoffTimer;
   let stableTimer;
@@ -1900,6 +2546,17 @@ function openDeliveryPings(o) {
       pongTimer = void 0;
     }
   };
+  let terminalReason;
+  let lastInboundAt = 0;
+  let lastTickAt;
+  let watchdogTimer;
+  const authCloses = [];
+  const stopWatchdog = () => {
+    if (watchdogTimer) {
+      clearInterval(watchdogTimer);
+      watchdogTimer = void 0;
+    }
+  };
   const queue = [];
   let waiter;
   let iterStarted = false;
@@ -1919,9 +2576,18 @@ function openDeliveryPings(o) {
     if (stableTimer)
       clearTimeout(stableTimer);
     stopPong();
-    try {
-      sock?.close();
-    } catch {
+    stopWatchdog();
+    const ws = sock;
+    sock = void 0;
+    if (ws) {
+      ws.onopen = null;
+      ws.onmessage = null;
+      ws.onclose = null;
+      ws.onerror = null;
+      try {
+        ws.close();
+      } catch {
+      }
     }
     if (waiter) {
       const w = waiter;
@@ -1932,13 +2598,60 @@ function openDeliveryPings(o) {
   const scheduleReconnect = () => {
     if (closed)
       return;
+    if (backoffTimer)
+      clearTimeout(backoffTimer);
+    connectGen += 1;
     attempt += 1;
     const ceil = Math.min(cap, base * 2 ** (attempt - 1));
     backoffTimer = setTimeout(connect, Math.floor(rng() * ceil));
   };
+  const forceCycle = (event, detail) => {
+    if (closed)
+      return;
+    lifecycle(event, detail);
+    const ws = sock;
+    sock = void 0;
+    if (stableTimer)
+      clearTimeout(stableTimer);
+    stopPong();
+    if (ws) {
+      ws.onopen = null;
+      ws.onmessage = null;
+      ws.onclose = null;
+      ws.onerror = null;
+      try {
+        ws.close();
+      } catch {
+      }
+    }
+    scheduleReconnect();
+  };
+  const startWatchdog = () => {
+    if (!hardened || watchdogTimer)
+      return;
+    lastTickAt = now();
+    watchdogTimer = setInterval(() => {
+      if (closed)
+        return;
+      const t = now();
+      const gap = lastTickAt !== void 0 ? t - lastTickAt : 0;
+      if (lastTickAt !== void 0 && gap > wakeGapMs) {
+        lastTickAt = t;
+        attempt = 0;
+        forceCycle("wake", `${gap}ms gap`);
+        return;
+      }
+      lastTickAt = t;
+      if (sock && sock.readyState === 1 && t - lastInboundAt > silenceMs) {
+        forceCycle("halfopen", `${t - lastInboundAt}ms silent`);
+      }
+    }, watchdogMs);
+  };
   async function connect() {
     if (closed)
       return;
+    const gen = connectGen;
+    terminalReason = void 0;
     let token;
     try {
       token = await o.tokenProvider();
@@ -1946,15 +2659,17 @@ function openDeliveryPings(o) {
       scheduleReconnect();
       return;
     }
-    if (closed)
+    if (closed || gen !== connectGen)
       return;
     const sep = o.url.includes("?") ? "&" : "?";
     const ws = new o.wsImpl(`${o.url}${sep}token=${encodeURIComponent(token)}`);
     sock = ws;
     ws.onopen = () => {
       push({ reconnected: true });
+      lastInboundAt = now();
       stableTimer = setTimeout(() => {
         attempt = 0;
+        authCloses.length = 0;
       }, stableResetMs);
       stopPong();
       pongTimer = setInterval(() => {
@@ -1966,8 +2681,26 @@ function openDeliveryPings(o) {
       }, PRESENCE_PONG_MS);
     };
     ws.onmessage = (e) => {
+      lastInboundAt = now();
+      let f;
+      try {
+        f = JSON.parse(String(e.data));
+      } catch {
+        return;
+      }
+      if (hardened) {
+        const tr = terminalFrameReason(f);
+        if (tr) {
+          terminalReason = tr;
+        } else if (f?.event === "ping") {
+          try {
+            if (ws.readyState === 1)
+              ws.send(JSON.stringify({ event: "pong" }));
+          } catch {
+          }
+        }
+      }
       try {
-        const f = JSON.parse(String(e.data));
         const ping = parseServerFrame(f);
         if (ping)
           push(ping);
@@ -1983,14 +2716,41 @@ function openDeliveryPings(o) {
       stopPong();
       if (closed)
         return;
-      if (e.code === 4001) {
+      const code = e.code;
+      if (!hardened) {
+        if (code === 4001) {
+          end();
+          return;
+        }
+        scheduleReconnect();
+        return;
+      }
+      const tr = terminalReason;
+      terminalReason = void 0;
+      if (code === 4006 || tr && code === 4001) {
+        lifecycle("terminal", tr ?? `code ${code}`);
         end();
         return;
       }
+      if (code === 4001) {
+        const t = now();
+        authCloses.push(t);
+        while (authCloses.length && t - authCloses[0] > authWarWindowMs)
+          authCloses.shift();
+        if (authCloses.length >= authWarCap) {
+          lifecycle("terminal", `auth war-cap ${authCloses.length}/${authWarWindowMs}ms`);
+          end();
+          return;
+        }
+        lifecycle("reconnect", "auth-4001");
+        scheduleReconnect();
+        return;
+      }
       scheduleReconnect();
     };
   }
   void connect();
+  startWatchdog();
   const pings = {
     [Symbol.asyncIterator]() {
       if (iterStarted)
@@ -2105,6 +2865,11 @@ var RestTransport = class {
       if (stale)
         throw stale;
     }
+    if (res.status === 403) {
+      const paused = await agentPausedErrorFromResponse(res.clone ? res.clone() : res);
+      if (paused)
+        throw paused;
+    }
     if (!res.ok)
       throw new Error(`publish failed: ${res.status}`);
     const j = await res.json();
@@ -2120,7 +2885,13 @@ var RestTransport = class {
     if (this.opts.connectIdentityId) {
       wsUrl += `?connect_identity_id=${encodeURIComponent(this.opts.connectIdentityId)}`;
     }
-    const handle = openDeliveryPings({ url: wsUrl, tokenProvider: this.tokenProvider, wsImpl: this.ws });
+    const handle = openDeliveryPings({
+      url: wsUrl,
+      tokenProvider: this.tokenProvider,
+      wsImpl: this.ws,
+      hardened: this.opts.hardenedReconnect ?? false,
+      onLifecycle: this.opts.onWsLifecycle
+    });
     this._controlSend = handle.send;
     const close = () => {
       if (this._controlSend === handle.send)
@@ -2195,10 +2966,11 @@ var RestMlsBackend = class {
     return { device_id: String(j.device_id) };
   }
   async publishKeyPackage(deviceId, keyPackageHex) {
-    await this.post("/api/v1/mls/key-packages", {
+    const j = await this.post("/api/v1/mls/key-packages", {
       key_package: keyPackageHex,
       device_id: deviceId
     });
+    return String(j.id);
   }
   async getConnectChannelGroup(channelId) {
     const j = await this.get(`/api/v1/mls/connect-channels/${channelId}/group`);
@@ -2235,10 +3007,37 @@ var RestMlsBackend = class {
       member_device_ids: Array.isArray(j.member_device_ids) ? j.member_device_ids.map(String) : []
     };
   }
-  async fetchKeyPackages(deviceIds) {
-    const j = await this.get(`/api/v1/mls/key-packages/batch?device_ids=${deviceIds.join(",")}`);
+  async resetReinitConnectChannelGroup(channelId, memberDeviceIds, att) {
+    const committer = memberDeviceIds[0];
+    if (!committer)
+      throw new Error("resetReinitConnectChannelGroup: empty member set");
+    const j = await this.post(`/api/v1/mls/connect-channels/${channelId}/reinit`, {
+      member_device_ids: memberDeviceIds,
+      committer_device_id: committer,
+      mode: "reset",
+      new_group_id: att.newGroupId,
+      reset_attestation_signature: att.signatureHex,
+      reset_attestation_nonce: att.nonceHex,
+      reset_attestation_content: att.signedContentHex
+    });
+    return {
+      group_id: String(j.group_id),
+      current_epoch: Number(j.current_epoch),
+      member_device_ids: Array.isArray(j.member_device_ids) ? j.member_device_ids.map(String) : []
+    };
+  }
+  async fetchKeyPackages(deviceIds) {
+    const j = await this.get(`/api/v1/mls/key-packages/batch?device_ids=${deviceIds.join(",")}`);
     return Object.fromEntries(Object.entries(j).map(([k, v]) => [k, String(v)]));
   }
+  async fetchKeyPackageById(kpId) {
+    try {
+      const j = await this.get(`/api/v1/mls/key-packages/by-id/${kpId}`);
+      return String(j.key_package);
+    } catch {
+      return null;
+    }
+  }
   async distribute(groupId, req) {
     await this.post(`/api/v1/mls/groups/${groupId}/distribute`, {
       ...req,
@@ -2255,13 +3054,48 @@ var RestMlsBackend = class {
       queue_ids: queueIds
     });
   }
-  async requestWelcome(groupId, deviceId) {
-    await this.post(`/api/v1/mls/groups/${groupId}/request-welcome`, { device_id: deviceId });
+  async requestWelcome(groupId, deviceId, freshKpId) {
+    const body = { device_id: deviceId };
+    if (freshKpId)
+      body.fresh_kp_id = freshKpId;
+    await this.post(`/api/v1/mls/groups/${groupId}/request-welcome`, body);
+  }
+  async getCommitterWork(channelId) {
+    const j = await this.get(`/api/v1/mls/connect-channels/${channelId}/committer-work`);
+    return {
+      adds: Array.isArray(j.adds) ? j.adds.map(String) : [],
+      removes: Array.isArray(j.removes) ? j.removes.map(String) : []
+    };
+  }
+  async acquireCommitLease(channelId) {
+    const res = await this.f(this.opts.baseUrl + `/api/v1/mls/connect-channels/${channelId}/commit-lease`, { method: "POST", headers: this.headers(), body: JSON.stringify({}) });
+    if (res.status === 409 || res.status === 503)
+      return null;
+    if (!res.ok)
+      throw new Error(`commit-lease ${res.status}`);
+    const j = await res.json();
+    return String(j.token);
+  }
+  async releaseCommitLease(channelId, token) {
+    await this.f(this.opts.baseUrl + `/api/v1/mls/connect-channels/${channelId}/commit-lease/release`, { method: "POST", headers: this.headers(), body: JSON.stringify({ token }) }).catch(() => {
+    });
+  }
+  async fetchResetAttestation(groupId) {
+    try {
+      const j = await this.get(`/api/v1/mls/groups/${groupId}/reset-attestation`);
+      return {
+        signedContent: String(j.signed_content),
+        signatureHex: String(j.signature_hex),
+        signerIdentityId: String(j.signer_identity_id)
+      };
+    } catch {
+      return null;
+    }
   }
 };
 
 // ../connect-sdk-ts/dist/mls/fake-backend.js
-import { bytesToHex as bytesToHex2 } from "@agentvault/crypto";
+import { bytesToHex as bytesToHex2, hexToBytes as hexToBytes2 } from "@agentvault/crypto";
 
 // ../connect-sdk-ts/dist/receive/inbox-cipher.js
 import { hkdf } from "@noble/hashes/hkdf";
@@ -2311,9 +3145,10 @@ var HKDF_INFO = new TextEncoder().encode("connect-guest-recovery-wrap-v1");
 
 // ../connect-mls-store/dist/sqlite-store.js
 import { DatabaseSync } from "node:sqlite";
+import { MLSGroupManager as MLSGroupManager2, bytesToHex as bytesToHex3, hexToBytes as hexToBytes3 } from "@agentvault/crypto";
 
 // ../connect-mls-store/dist/schema.js
-var SCHEMA_VERSION = 1;
+var SCHEMA_VERSION = 4;
 function openSchema(db) {
   db.exec("PRAGMA journal_mode=WAL");
   const row = db.prepare("PRAGMA user_version").get();
@@ -2328,8 +3163,39 @@ function openSchema(db) {
         PRIMARY KEY (identity_id, channel_id)
       );
     `);
-    db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
   }
+  if (row.user_version < 2) {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS mls_identity_pin (
+        owner_identity_id TEXT PRIMARY KEY,
+        public_key_hex    TEXT NOT NULL,
+        key_algo          TEXT NOT NULL,
+        pinned_at         INTEGER NOT NULL
+      );
+    `);
+  }
+  if (row.user_version < 3) {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS mls_retired_group (
+        channel_id TEXT NOT NULL,
+        group_id   TEXT NOT NULL,
+        PRIMARY KEY (channel_id, group_id)
+      );
+    `);
+  }
+  if (row.user_version < 4) {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS mls_pending_bundle (
+        identity_id   TEXT NOT NULL,
+        ref           TEXT NOT NULL,
+        kp_id         TEXT,
+        sealed_bundle BLOB,
+        updated_at    INTEGER NOT NULL,
+        PRIMARY KEY (identity_id, ref)
+      );
+    `);
+  }
+  db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
 }
 
 // ../connect-mls-store/dist/errors.js
@@ -2347,13 +3213,39 @@ var MlsStoreSealError = class extends Error {
 };
 
 // ../connect-mls-store/dist/sqlite-store.js
+function encodeBundle(bundle) {
+  const pp = bundle.privatePackage;
+  const obj = {
+    pub: bytesToHex3(MLSGroupManager2.serializeKeyPackage(bundle.publicPackage)),
+    initPriv: bytesToHex3(pp.initPrivateKey),
+    hpkePriv: bytesToHex3(pp.hpkePrivateKey),
+    sigPriv: bytesToHex3(pp.signaturePrivateKey)
+  };
+  return new TextEncoder().encode(JSON.stringify(obj));
+}
+function decodeBundle(bytes) {
+  const obj = JSON.parse(new TextDecoder().decode(bytes));
+  return {
+    publicPackage: MLSGroupManager2.deserializeKeyPackage(hexToBytes3(obj.pub)),
+    privatePackage: {
+      initPrivateKey: hexToBytes3(obj.initPriv),
+      hpkePrivateKey: hexToBytes3(obj.hpkePriv),
+      signaturePrivateKey: hexToBytes3(obj.sigPriv)
+    }
+  };
+}
 var SqliteMlsStateStore = class {
   db;
   id;
   cipher;
-  // Bundles stay in-memory (spec §4): private half not durably serializable.
-  // Per-instance map → per-identity store instances are naturally isolated (§6.1).
+  // In-memory write-through cache over the durable mls_pending_bundle table.
+  // Persisting the bundle (schema v4) is the root-cause fix for restart-induced
+  // KeyPackage rotation: with the bundle in-memory ONLY, every restart lost it,
+  // re-minted+re-published a fresh KP, and orphaned every Welcome sealed to the
+  // prior published KP. The cache avoids re-unsealing on every access; sqlite is
+  // the source of truth across process restarts.
   bundles = /* @__PURE__ */ new Map();
+  lastKpIds = /* @__PURE__ */ new Map();
   constructor(opts) {
     this.id = opts.identityId;
     this.cipher = opts.cipherFor(opts.identityId);
@@ -2422,12 +3314,74 @@ var SqliteMlsStateStore = class {
   }
   async savePendingBundle(ref, bundle) {
     this.bundles.set(ref, bundle);
+    const sealed = await this.cipher.seal(encodeBundle(bundle));
+    this.db.prepare(`INSERT INTO mls_pending_bundle (identity_id, ref, sealed_bundle, updated_at)
+       VALUES (?,?,?,?)
+       ON CONFLICT(identity_id, ref) DO UPDATE SET sealed_bundle=excluded.sealed_bundle, updated_at=excluded.updated_at`).run(this.id, ref, sealed, Date.now());
   }
   async loadPendingBundle(ref) {
-    return this.bundles.get(ref) ?? null;
+    const cached = this.bundles.get(ref);
+    if (cached)
+      return cached;
+    const row = this.db.prepare("SELECT sealed_bundle FROM mls_pending_bundle WHERE identity_id=? AND ref=?").get(this.id, ref);
+    if (!row?.sealed_bundle)
+      return null;
+    let bundle;
+    try {
+      bundle = decodeBundle(await this.cipher.open(row.sealed_bundle));
+    } catch (e) {
+      if (typeof process !== "undefined" && process.env?.SECURECOMS_TRACE_DELIVERY) {
+        console.warn(`[trace] loadPendingBundle: unseal/decode FAILED for ref ${ref.slice(0, 8)}: ${e?.message}`);
+      }
+      return null;
+    }
+    this.bundles.set(ref, bundle);
+    return bundle;
   }
   async deletePendingBundle(ref) {
     this.bundles.delete(ref);
+    this.db.prepare("UPDATE mls_pending_bundle SET sealed_bundle=NULL, updated_at=? WHERE identity_id=? AND ref=?").run(Date.now(), this.id, ref);
+  }
+  async saveLastKpId(deviceId, id) {
+    this.lastKpIds.set(deviceId, id);
+    this.db.prepare(`INSERT INTO mls_pending_bundle (identity_id, ref, kp_id, updated_at)
+       VALUES (?,?,?,?)
+       ON CONFLICT(identity_id, ref) DO UPDATE SET kp_id=excluded.kp_id, updated_at=excluded.updated_at`).run(this.id, deviceId, id, Date.now());
+  }
+  async loadLastKpId(deviceId) {
+    const cached = this.lastKpIds.get(deviceId);
+    if (cached)
+      return cached;
+    const row = this.db.prepare("SELECT kp_id FROM mls_pending_bundle WHERE identity_id=? AND ref=?").get(this.id, deviceId);
+    if (!row?.kp_id)
+      return null;
+    this.lastKpIds.set(deviceId, row.kp_id);
+    return row.kp_id;
+  }
+  async saveLastKpAndBundle(deviceId, id, bundle) {
+    this.lastKpIds.set(deviceId, id);
+    this.bundles.set(deviceId, bundle);
+    const sealed = await this.cipher.seal(encodeBundle(bundle));
+    this.db.prepare(`INSERT INTO mls_pending_bundle (identity_id, ref, kp_id, sealed_bundle, updated_at)
+       VALUES (?,?,?,?,?)
+       ON CONFLICT(identity_id, ref) DO UPDATE SET kp_id=excluded.kp_id, sealed_bundle=excluded.sealed_bundle, updated_at=excluded.updated_at`).run(this.id, deviceId, id, sealed, Date.now());
+  }
+  async savePinnedIdentityKey(identityId, key) {
+    this.db.prepare(`INSERT INTO mls_identity_pin (owner_identity_id, public_key_hex, key_algo, pinned_at)
+       VALUES (?,?,?,?)
+       ON CONFLICT(owner_identity_id) DO UPDATE SET
+         public_key_hex=excluded.public_key_hex, key_algo=excluded.key_algo, pinned_at=excluded.pinned_at`).run(identityId, key.publicKeyHex, key.keyAlgo, Date.now());
+  }
+  async loadPinnedIdentityKey(identityId) {
+    const row = this.db.prepare("SELECT public_key_hex, key_algo FROM mls_identity_pin WHERE owner_identity_id=?").get(identityId);
+    return row ? { publicKeyHex: row.public_key_hex, keyAlgo: row.key_algo } : null;
+  }
+  async addRetiredGroupId(channelId, groupId) {
+    this.db.prepare("INSERT OR IGNORE INTO mls_retired_group (channel_id, group_id) VALUES (?,?)").run(channelId, groupId);
+  }
+  async loadRetiredGroupIds(channelId) {
+    const rows = this.db.prepare("SELECT group_id FROM mls_retired_group WHERE channel_id=?").all(channelId);
+    return rows.map((r) => r.group_id);
   }
   /** @internal test-only */
   _rawMainForTest(identityId, channelId) {
@@ -2439,6 +3393,11 @@ var SqliteMlsStateStore = class {
   }
 };
 
+// src/bridge-agent.ts
+import { decryptFile, encryptFile, computeFileDigest, base64ToBytes as base64ToBytes2, bytesToBase64 as bytesToBase642 } from "@agentvault/crypto";
+import { promises as fsp } from "node:fs";
+import { join as join2, dirname as dirname2 } from "node:path";
+
 // src/latency.ts
 var DEFAULT_CAPACITY = 1024;
 function round(n) {
@@ -2586,6 +3545,148 @@ var TokenBucketFloor = class {
   }
 };
 
+// src/decrypt-error-log-limiter.ts
+var DEFAULT_DECRYPT_ERROR_LOG_WINDOW_MS = 6e4;
+var MAX_DISTINCT_PER_WINDOW = 4;
+function normalizeMessage(m) {
+  return m.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "<id>").replace(/[0-9a-f]{16,}/gi, "<hex>");
+}
+var DecryptErrorLogLimiter = class {
+  windowMs;
+  now;
+  log;
+  windows = /* @__PURE__ */ new Map();
+  constructor(opts = {}) {
+    this.windowMs = opts.windowMs ?? DEFAULT_DECRYPT_ERROR_LOG_WINDOW_MS;
+    this.now = opts.now ?? Date.now;
+    this.log = opts.log ?? ((line) => console.warn(line));
+  }
+  /**
+   * Record one decrypt error for `channelId`. Logs immediately if this is
+   * the channel's first error since its window opened (or its prior window
+   * had already elapsed, in which case a summary for that just-closed
+   * window is flushed first); otherwise the error is counted silently
+   * toward the window's eventual summary line.
+   */
+  record(channelId, info) {
+    const t = this.now();
+    const w = this.windows.get(channelId);
+    if (!w) {
+      this.logFirst(channelId, info);
+      this.windows.set(channelId, { windowStart: t, count: 1, lastEpoch: info.epoch, lastMessage: info.message, loggedKeys: /* @__PURE__ */ new Set([normalizeMessage(info.message)]) });
+      return;
+    }
+    if (t - w.windowStart >= this.windowMs) {
+      this.flushSummary(channelId, w);
+      this.logFirst(channelId, info);
+      this.windows.set(channelId, { windowStart: t, count: 1, lastEpoch: info.epoch, lastMessage: info.message, loggedKeys: /* @__PURE__ */ new Set([normalizeMessage(info.message)]) });
+      return;
+    }
+    w.count += 1;
+    w.lastEpoch = info.epoch;
+    w.lastMessage = info.message;
+    const key = normalizeMessage(info.message);
+    if (!w.loggedKeys.has(key) && w.loggedKeys.size < MAX_DISTINCT_PER_WINDOW) {
+      this.logFirst(channelId, info);
+      w.loggedKeys.add(key);
+    }
+  }
+  /**
+   * Clear a channel's window (e.g. once the caller learns the channel
+   * cleared/healed) so its NEXT error logs immediately as a fresh "first"
+   * rather than being folded into a stale window's summary. There is
+   * currently no onDecryptSuccess-style hook from the SDK to wire this to
+   * automatically (see bridge-agent.ts's onDecryptError wiring comment) —
+   * exposed here so a future success signal (or a caller with its own
+   * channel-cleared signal) can reset explicitly. In its absence, the
+   * window simply rolls over on interval elapse, which is an accepted
+   * simplification (see report).
+   */
+  reset(channelId) {
+    this.windows.delete(channelId);
+  }
+  logFirst(channelId, info) {
+    this.log(
+      `[bridge] decrypt error on channel ${channelId} (queue ${info.queueId ?? "?"}, epoch ${info.epoch ?? "?"}): ${info.message}`
+    );
+  }
+  flushSummary(channelId, w) {
+    if (w.count <= 1) return;
+    const seconds = Math.round(this.windowMs / 1e3);
+    this.log(
+      `[bridge] decrypt errors on channel ${channelId}: ${w.count} in last ${seconds}s (epoch ${w.lastEpoch ?? "?"}, ${w.lastMessage})`
+    );
+  }
+};
+
+// src/attachments.ts
+import { basename } from "node:path";
+function sanitizeFilename(name, fallback) {
+  const base = basename(name ?? "");
+  const cleaned = base.replace(/[/\\]/g, "").replace(/^\.+$/, "");
+  return cleaned.length > 0 ? cleaned : fallback;
+}
+var MIME_BY_EXT = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  pdf: "application/pdf",
+  txt: "text/plain",
+  md: "text/markdown",
+  json: "application/json",
+  csv: "text/csv",
+  html: "text/html",
+  mp4: "video/mp4",
+  mp3: "audio/mpeg",
+  zip: "application/zip",
+  wav: "audio/wav"
+};
+function mimeForName(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot < 0 || dot === name.length - 1) return "application/octet-stream";
+  return MIME_BY_EXT[name.slice(dot + 1).toLowerCase()] ?? "application/octet-stream";
+}
+async function prepareAttachment(filePath, caption, channelId, deps) {
+  const bytes = await deps.readFile(filePath);
+  const name = basename(filePath);
+  const { encryptedData, fileKey, fileNonce, digest } = deps.encryptFile(bytes);
+  const blobId = await deps.uploadBlob(encryptedData, channelId);
+  const body = {
+    v: 1,
+    type: "artifact_share",
+    name,
+    mime: mimeForName(name),
+    size: bytes.length,
+    blobId,
+    fileKey: deps.bytesToBase64(fileKey),
+    fileNonce: deps.bytesToBase64(fileNonce),
+    digest
+  };
+  if (caption) body.text = caption;
+  return body;
+}
+async function materializeAttachment(body, ctx, deps) {
+  const ciphertext = await deps.downloadBlob(body.blobId);
+  const sha2565 = deps.computeFileDigest(ciphertext);
+  if (sha2565 !== body.digest) {
+    throw new Error(`attachment digest mismatch for blob ${body.blobId}`);
+  }
+  const plain = deps.decryptFile(
+    ciphertext,
+    deps.base64ToBytes(body.fileKey),
+    deps.base64ToBytes(body.fileNonce)
+  );
+  const safeName = sanitizeFilename(body.name, ctx.messageId);
+  const dir = `${ctx.attachmentsDir}/${ctx.channelId}`;
+  const path = `${dir}/${ctx.messageId}-${safeName}`;
+  await deps.mkdirp(dir);
+  await deps.writeFile(path, plain);
+  return { filename: safeName, mime: body.mime, size: plain.length, path, sha256: sha2565 };
+}
+
 // src/bridge-agent.ts
 var DEFAULT_MAX_BUFFER = 1e3;
 var CHANNEL_META_TTL_MS = 5 * 6e4;
@@ -2606,16 +3707,48 @@ var RateLimitedError = class extends Error {
     this.name = "RateLimitedError";
   }
 };
+var InvalidPathError = class extends Error {
+  constructor(filePath, cause) {
+    super(`cannot read attachment file: ${filePath}`);
+    this.filePath = filePath;
+    this.name = "InvalidPathError";
+    if (cause !== void 0) this.cause = cause;
+  }
+};
+var AgentPausedSendError = class extends Error {
+  constructor(channelId) {
+    super(`agent is paused in channel ${channelId}; send suppressed (no self-heal, no retry)`);
+    this.channelId = channelId;
+    this.name = "AgentPausedSendError";
+  }
+};
+var UnknownActionRunError = class extends Error {
+  constructor(runId) {
+    super(`unknown or already-settled agent action run: ${runId}`);
+    this.runId = runId;
+    this.name = "UnknownActionRunError";
+  }
+};
 var BRIDGE_VERSION = "0.0.0";
-function hexToBytes2(h) {
+function hexToBytes4(h) {
   return new Uint8Array(Buffer.from(h, "hex"));
 }
 var BridgeAgent = class _BridgeAgent {
   constructor(cfg, deps = {}) {
     this.cfg = cfg;
-    const seed = hexToBytes2(cfg.signingPrivateKey);
+    const seed = hexToBytes4(cfg.signingPrivateKey);
     this.custody = SoftwareKeyCustody.fromPrivateKey("ed25519", seed);
-    this.transport = deps.transport ?? new RestTransport({ baseUrl: cfg.apiBase, bearerToken: cfg.apiKey, connectIdentityId: cfg.identityId });
+    this.transport = deps.transport ?? new RestTransport({
+      baseUrl: cfg.apiBase,
+      bearerToken: cfg.apiKey,
+      connectIdentityId: cfg.identityId,
+      // P1b: hardened delivery-ping reconnect (verify-before-terminal +
+      // half-open + wake + auth war-cap). On by default for the daemon;
+      // SECURECOMS_WS_HARDENED=false reverts to the legacy 4001-terminal path.
+      hardenedReconnect: process.env.SECURECOMS_WS_HARDENED !== "false",
+      onWsLifecycle: (event, detail) => process.stderr.write(`[bridge] delivery-ping ${event}${detail ? ` (${detail})` : ""}
+`)
+    });
     this.backend = deps.backend ?? new RestMlsBackend({ baseUrl: cfg.apiBase, bearerToken: cfg.apiKey });
     this.store = new SqliteMlsStateStore({
       dbPath: cfg.storePath,
@@ -2630,12 +3763,47 @@ var BridgeAgent = class _BridgeAgent {
       // ADR-0002: count + log agent-side decrypt failures. Without this hook the
       // daemon was 100% blind to a wedged channel (it "looked idle"); the
       // provider's errorStats() snapshot is surfaced on GET /v1/metrics below.
+      // P0b (daemon-stability): logging is routed through decryptErrorLogLimiter
+      // rather than a raw console.warn per failure — a wedged channel used to
+      // redeliver the same undecryptable row on every pullDelivery cycle and
+      // produced a 114 MB / 765,000-line daemon log in a single day. The
+      // limiter still logs the first failure immediately and collapses every
+      // repeat within 60s into one summary line; errorStats() below is fed
+      // directly by the provider and is completely unaffected.
       onDecryptError: (row, err) => {
         const cid = row.connect_channel_id ?? "(unmapped)";
-        console.warn(
-          `[bridge] decrypt error on channel ${cid} (queue ${row.queue_id}, epoch ${row.epoch}): ${err instanceof Error ? err.message : String(err)}`
-        );
-      }
+        this.decryptErrorLogLimiter.record(cid, {
+          epoch: row.epoch,
+          queueId: row.queue_id,
+          message: err instanceof Error ? err.message : String(err)
+        });
+      },
+      // P0b (daemon-stability): fired EXACTLY ONCE by the SDK (P0a) when a
+      // channel's decrypt-failure run crosses quarantineThreshold and its
+      // stuck row has been ack-drained. Log one quarantine line, then
+      // best-effort trigger the SAME held-KP re-Welcome heal used by
+      // ingestOnce's Task-11 branch and selfHealSweep (see
+      // healWedgedChannel below) — never throws back into the SDK caller.
+      onWedged: (channelId) => {
+        try {
+          console.warn(
+            `[bridge] channel ${channelId} quarantined after persistent decrypt failures \u2014 signalling re-Welcome`
+          );
+          void this.healWedgedChannel(channelId);
+        } catch {
+        }
+      },
+      // Owner-attested Reset Secure Session (Task 8): the SDK's step-0 guard
+      // calls this before honoring an owner-authored supersede. It must return
+      // a value ONLY when the structural owner is unambiguous AND a pin exists
+      // for it — never trust a bare in-memory cache without reconfirming
+      // against the persisted pin (see resolvePinnedOwnerHook below).
+      onResolvePinnedOwner: (channelId) => this.resolvePinnedOwnerHook(channelId),
+      // P1a self-heal: a verified reset supersede whose Welcome we cannot open
+      // (sealed to a stale published KeyPackage) — ask the committer to re-Welcome
+      // us to the reset group with our CURRENT KeyPackage. Cooldown-guarded, never
+      // throws (mirrors the divergence-heal signal path).
+      onSupersedeUnopenable: (channelId, groupId) => this.healSupersedeUnopenable(channelId, groupId)
     });
     this.fetchImpl = deps.fetchImpl ?? fetch;
     this.latency = deps.latency ?? new LatencyRecorder();
@@ -2644,6 +3812,37 @@ var BridgeAgent = class _BridgeAgent {
       capacity: cfg.rateLimitCapacity ?? 20,
       refillPerMinute: cfg.rateLimitRefillPerMinute ?? 20
     });
+    this.actionClock = deps.actionThrottleNow ?? Date.now;
+    this.rng = deps.rng ?? Math.random;
+    this.actionRateFloor = new TokenBucketFloor({ capacity: 1, refillPerMinute: 30, now: this.actionClock });
+    this.globalActionRateFloor = new TokenBucketFloor({ capacity: 1, refillPerMinute: 30, now: this.actionClock });
+    const self = this;
+    this.downloadBlobImpl = deps.downloadBlob ?? async function(blobId) {
+      const url = `${cfg.apiBase}/api/v1/attachments/${encodeURIComponent(blobId)}?caller_identity_id=${encodeURIComponent(cfg.identityId)}`;
+      const res = await self.fetchImpl(url, { headers: { authorization: `Bearer ${cfg.apiKey}` } });
+      if (!res.ok) throw new Error(`download blob failed: ${res.status}`);
+      return new Uint8Array(await res.arrayBuffer());
+    };
+    this.uploadBlobImpl = deps.uploadBlob ?? async function(ciphertext, channelId) {
+      const url = `${cfg.apiBase}/api/v1/attachments?channel_id=${encodeURIComponent(channelId)}&caller_identity_id=${encodeURIComponent(cfg.identityId)}`;
+      const res = await self.fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/octet-stream", authorization: `Bearer ${cfg.apiKey}` },
+        body: ciphertext
+      });
+      if (!res.ok) throw new Error(`upload blob failed: ${res.status}`);
+      const j = await res.json();
+      return String(j.attachment_id);
+    };
+    this.attachmentsDirImpl = deps.attachmentsDir ?? join2(dirname2(cfg.storePath), "attachments");
+    this.action = {
+      begin: (channelId) => this.actionBegin(channelId),
+      start: (opts) => this.actionStart(opts),
+      update: (runId, nodeId, patch) => this.actionUpdate(runId, nodeId, patch),
+      finish: (runId, nodeId, patch) => this.actionFinish(runId, nodeId, patch),
+      settle: (runId, opts) => this.actionSettle(runId, opts),
+      wrap: (runId, fn, opts) => this.actionWrap(runId, fn, opts)
+    };
   }
   transport;
   provider;
@@ -2673,6 +3872,15 @@ var BridgeAgent = class _BridgeAgent {
    * per channel on a miss.
    */
   channelRoster = /* @__PURE__ */ new Map();
+  /**
+   * Task 8 (owner-attested Reset Secure Session): per-channel STRUCTURAL owner
+   * cache, fed by resolveAndPinOwner() on every roster refresh and consumed by
+   * the onResolvePinnedOwner hook passed to MlsGroupKeyProvider. "anomalous"
+   * means the DM roster shape was not exactly one non-self, non-agent
+   * counterpart, OR the freshly-fetched key no longer matches an existing pin —
+   * either way the hook must fail closed (return null) for that channel.
+   */
+  channelOwner = /* @__PURE__ */ new Map();
   buffer = [];
   maxBuffer;
   /** Cumulative count of messages shed by the buffer cap (surfaced on health()/metrics()). */
@@ -2687,11 +3895,111 @@ var BridgeAgent = class _BridgeAgent {
   rateLimitedSends = 0;
   /** Cumulative count of requestWelcome calls fired for no-local-state deliveries (self-heal signal). */
   welcomeRequestsSent = 0;
+  /** 2026-07-03 latency triage: cumulative delivery pings received on the WS
+   *  stream. 0 while messages still flow = the stream is dead and inbound is
+   *  riding the 25s safety floor (surfaced on health()/metrics). */
+  pingsReceived = 0;
+  /** True once close() begins — gates the ping-stream-death stderr warning so
+   *  a normal shutdown doesn't cry wolf. */
+  closingDown = false;
+  /**
+   * Track 5: cumulative count of artifact_share messages where download/decrypt/digest
+   * failed. Fail-soft — failures are acked (no redelivery), logged to stderr, and this
+   * counter is incremented. Surfaced on health()/metrics().
+   */
+  failedAttachments = 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;
+  // H1: bound the graceful-shutdown drain so a hung in-flight op can't block exit.
+  static GRACEFUL_DRAIN_MS = 5e3;
+  /**
+   * P0b (daemon-stability): collapses the onDecryptError console.warn from
+   * "one line per failure" (the 114 MB/765k-line-in-a-day log source) to at
+   * most one line immediately + one summary line per 60s per channel. LOG
+   * OUTPUT ONLY — does not touch errorStats()/quarantine counters, which
+   * live entirely in the SDK provider and are unaffected by this class.
+   */
+  decryptErrorLogLimiter = new DecryptErrorLogLimiter();
+  /**
+   * Task 12: proactive self-heal sweep kill-switch. Task 11's held-KP signal
+   * only fires reactively, from ingestOnce's Phase-0 pass over PULLED delivery
+   * rows — an idle-but-wiped channel therefore loses its NEXT message (the
+   * very message that would have proven it diverged). selfHealSweep() closes
+   * that gap by proactively walking every non-DM member channel at boot and
+   * on an interval. `SECURECOMS_SELF_HEAL_SWEEP=false` disables it, falling
+   * back to the delivery-row-driven Task 11 behaviour only.
+   */
+  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;
+  // 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;
+  selfHealTimer;
+  bootSweepTimer;
+  rng;
   rateFloor;
+  /**
+   * agent.action.* run state, keyed by runId.
+   *
+   * Review M3 (bug fix): the ORIGINAL comment here said "deliberately
+   * unbounded" — but nothing ever bounded it either. Only actionSettle()
+   * deleted an entry; a begun-but-never-settled run (agent crash, bug,
+   * dropped/never-sent reply) leaked for the daemon's entire lifetime. Now
+   * bounded by MAX_UNSETTLED_ACTION_RUNS (LRU eviction by startedAt) plus a
+   * lazy ACTION_RUN_STALE_MS sweep, both applied on every actionBegin() —
+   * mirrors the send-side inbound-buffer bound (capBuffer/maxBuffer).
+   */
+  actionRuns = /* @__PURE__ */ new Map();
+  /** Review M3: hard cap on concurrently-tracked UNSETTLED runs. Exceeding it
+   *  evicts the oldest (LRU by startedAt) to make room — never grows past
+   *  this regardless of how many runs are begun and abandoned. */
+  static MAX_UNSETTLED_ACTION_RUNS = 50;
+  /** Review M3: an unsettled run older than this (by startedAt, relative to
+   *  actionClock()) is swept away on the next actionBegin(), independent of
+   *  the count-based cap — bounds memory even when begin() calls are rare. */
+  static ACTION_RUN_STALE_MS = 60 * 6e4;
+  // 60 minutes
+  /** Review I3/M3: injected clock (defaults Date.now) for the action-partial
+   *  token buckets AND the stale-run sweep — a single seam so tests can
+   *  simulate elapsed time deterministically. */
+  actionClock;
+  /**
+   * Per-run token bucket for `agent_action` PARTIAL frames (Global
+   * Constraint: do NOT model on the unthrottled reportStatus; do NOT reuse
+   * `rateFloor`/`enforceRateFloor`, whose semantics are "throw past
+   * capacity" — partials instead COALESCE: a throttled call just leaves its
+   * change in `dirty` for the next allowed send to pick up).
+   *
+   * Review I3 (bug fix): capacity 1 / refill 60-per-minute was EXACTLY the
+   * backend's MESSAGING_LIMIT (60/60s per sender) — no headroom. Partials +
+   * the settled frame + the agent's real reply + reportStatus all compete
+   * for that one shared per-sender budget, so a long run's settled frame or
+   * reply could 429 right at the end. Lowered to 30/min (~1 per 2s) so
+   * partials alone use at most ~half the identity's send budget, leaving
+   * headroom for the settled frame / reply / status traffic riding the SAME
+   * cap. Independent of `cfg.rateLimitCapacity` (room/a2a/attachment floor).
+   * `settled` frames bypass this bucket entirely — they always send, exactly
+   * once, per run.
+   */
+  actionRateFloor;
+  /**
+   * Review I3 (bug fix): a GLOBAL bucket shared across every run, on top of
+   * the per-run bucket above. Without this, N concurrent runs each get their
+   * OWN ~30/min budget, so the partial send rate multiplies with agent
+   * concurrency and can still blow past the shared 60/min identity edge cap
+   * (each run individually "has headroom" but the SUM doesn't). Same
+   * capacity/refill as the per-run bucket — it caps the aggregate, not any
+   * single run.
+   */
+  globalActionRateFloor;
+  /** Public `agent.action.*` surface — assigned once at the end of the constructor. */
+  action;
   waiters = [];
   pingHandle;
   safetyTimer;
@@ -2699,6 +4007,12 @@ var BridgeAgent = class _BridgeAgent {
   startedAt = 0;
   store;
   latency;
+  /** Track 5: injectable blob download fn (default: fetch-based). */
+  downloadBlobImpl;
+  /** Track 5: injectable blob upload fn (default: fetch-based). */
+  uploadBlobImpl;
+  /** Track 5: directory where received attachments are saved. */
+  attachmentsDirImpl;
   /**
    * Enforce the inbound-buffer cap with a DROP-OLDEST policy.
    *
@@ -2722,6 +4036,14 @@ var BridgeAgent = class _BridgeAgent {
     this.startedAt = Date.now();
     await this.provider.publishKeyPackage();
     this.startReceivePump();
+    if (this.selfHealSweepEnabled) {
+      this.bootSweepTimer = setTimeout(() => void this.selfHealSweep(), this.sweepJitter());
+      this.bootSweepTimer.unref?.();
+    }
+  }
+  /** C3: a random 0..SELF_HEAL_SWEEP_JITTER_MS decorrelation offset. */
+  sweepJitter() {
+    return Math.floor(this.rng() * _BridgeAgent.SELF_HEAL_SWEEP_JITTER_MS);
   }
   async reconcileJoin(channelId) {
     if (this.joinState.get(channelId) === "JOINED") return true;
@@ -2734,6 +4056,145 @@ var BridgeAgent = class _BridgeAgent {
       return false;
     }
   }
+  /**
+   * The held-KP re-Welcome signal (Task 11), shared by EVERY heal path: the
+   * reactive no-local-state branch in ingestOnce(), the proactive
+   * selfHealSweep() (Task 12), the onWedged forked-state recovery
+   * (healWedgedChannel), and the reset supersede (healSupersedeUnopenable).
+   *
+   * Before asking the committer to (re-)Welcome us, it RECONCILES the server's
+   * published KeyPackage to our held bundle. This is the fix for the observed
+   * "fresh DM never replies" AND "reset doesn't work": the committer seals every
+   * Welcome to our SERVER-PUBLISHED KP, but that KP had diverged from our
+   * locally-HELD bundle, so joinFromWelcome throws "No matching secret found" /
+   * "private KeyPackage key no longer held" and the Welcome is discarded. A bare
+   * re-Welcome re-seals to the SAME diverged published KP — un-openable again —
+   * looping until the channel quarantines. So:
+   *   - published == held  → publishKeyPackage() (no-op while held; mints only if
+   *     somehow none is held), then re-Welcome re-seals to the current KP we hold.
+   *   - published != held  → forceRepublishKeyPackage() re-syncs the server to a
+   *     bundle we hold, so the owner's re-Welcome is openable. Orphan-safe: a
+   *     diverged published KP means every other pending Welcome sealed via the
+   *     server is un-openable too, so replacing the shared per-device bundle
+   *     strands nothing that was openable (see heldBundleMatchesPublishedKp).
+   * getLastPublishedKpId then names the reconciled KP so the owner re-seals to it.
+   * Callers own their cooldown/rate-limit gate and try/catch — this does neither.
+   */
+  async signalHeldKpWelcome(groupId) {
+    if (await this.provider.heldBundleMatchesPublishedKp()) {
+      await this.provider.publishKeyPackage();
+    } else {
+      await this.provider.forceRepublishKeyPackage();
+    }
+    const freshKpId = await this.provider.getLastPublishedKpId() ?? void 0;
+    await this.backend.requestWelcome(groupId, this.cfg.deviceId, freshKpId);
+    this.welcomeRequestsSent++;
+  }
+  /**
+   * P0b (daemon-stability): the onWedged→heal path. onWedged only hands us a
+   * `connect_channel_id` — resolve it to an MLS groupId the SAME way
+   * selfHealSweep does, via the read-only getConnectChannelGroup probe
+   * (never initConnectChannelGroup, which side-effects a member_device_ids
+   * union + commit), then fire the existing held-KP re-Welcome signal.
+   * Respects the SAME per-channel cooldown (lastWelcomeRequest /
+   * REQUEST_WELCOME_COOLDOWN_MS) used by ingestOnce's Task-11 branch and
+   * selfHealSweep — this must never hammer requestWelcome on its own.
+   *
+   * Best-effort in every sense: if the channel has no resolvable group (no
+   * local state to probe from), this logs nothing further and just returns —
+   * the channel is left to the next selfHealSweep pass or reactive Task-11
+   * branch, mirroring how those two paths already treat an unresolvable
+   * group (`continue`, no signal). ANY failure along the way (probe throws,
+   * signal throws) is swallowed: a wedge heal must never throw back into the
+   * SDK's onWedged caller. Single-shot per wedge episode — full rejoin
+   * reliability is P1, not this hook's job.
+   */
+  async healWedgedChannel(channelId) {
+    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);
+      }
+      await this.signalHeldKpWelcome(g.group_id);
+    } catch {
+    }
+  }
+  /**
+   * P1a self-heal (onSupersedeUnopenable): a fully-verified reset supersede whose
+   * Welcome we cannot open — it was sealed to a stale published KeyPackage our
+   * held bundle no longer matches ("No matching secret found"). trySupersede has
+   * verified owner + attestation + signature, so this is a real reset we WANT; we
+   * just can't open THIS Welcome. Ask the committer to re-Welcome us to the reset
+   * `groupId` with our CURRENT KeyPackage (signalHeldKpWelcome republishes/ensures
+   * a held KP, then requestWelcome), so the owner re-seals a Welcome we can open
+   * and the reset converges. The groupId is known (handed in), so no probe needed.
+   *
+   * Returns true ONLY when a re-Welcome was actually requested — trySupersede then
+   * discards the un-openable row. Under the shared per-channel cooldown (or on any
+   * failure) returns false, so trySupersede LEAVES the row for a bounded retry
+   * rather than dropping it with no replacement in flight. Never throws.
+   */
+  async healSupersedeUnopenable(channelId, groupId) {
+    try {
+      const now = performance.now();
+      const last = this.lastWelcomeRequest.get(channelId) ?? -Infinity;
+      if (now - last < _BridgeAgent.REQUEST_WELCOME_COOLDOWN_MS) return false;
+      this.lastWelcomeRequest.set(channelId, now);
+      await this.signalHeldKpWelcome(groupId);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Task 12: proactive self-heal sweep. ingestOnce's Task-11 divergence
+   * branch only fires reactively — off a delivery ROW that already arrived
+   * for a diverged channel. A wiped-but-IDLE channel (no traffic since the
+   * wipe) never produces that row, so its next real message would be the
+   * 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.
+   *
+   * Each channel is wrapped in its own try/catch: `listChannels` filters at
+   * the identity level while `requestWelcome` (via request_welcome) gates at
+   * the device level, so a channel where this identity is a member but this
+   * DEVICE never held a leaf can 403 on the signal call. That's harmless and
+   * must not abort the sweep for every other channel.
+   */
+  async selfHealSweep() {
+    let chans;
+    try {
+      chans = await this.listChannels();
+    } catch {
+      return;
+    }
+    for (const c of chans) {
+      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;
+        const now = performance.now();
+        const last = this.lastWelcomeRequest.get(c.channel_id) ?? -Infinity;
+        if (now - last < _BridgeAgent.REQUEST_WELCOME_COOLDOWN_MS) continue;
+        this.lastWelcomeRequest.set(c.channel_id, now);
+        await this.signalHeldKpWelcome(g.group_id);
+      } catch {
+      }
+    }
+  }
   /**
    * Per-channel send-floor check. No-op on allow; throws RateLimitedError on a
    * trip (incrementing the observable counter). `kind` namespaces the bucket so
@@ -2746,6 +4207,40 @@ var BridgeAgent = class _BridgeAgent {
       throw new RateLimitedError(channelId, this.rateFloor.msUntilNextToken(key));
     }
   }
+  /**
+   * The ONE seam every application-send path (send/sendA2A/sendAttachment)
+   * calls to publish, wrapping the SDK's {@link sendWithSelfHeal} with the
+   * daemon's per-room-pause terminal classification (Task 9).
+   *
+   * `AgentPausedError` (Task 8's SDK classification of the backend's 403
+   * `agent_paused`) means an owner/admin has deliberately muted this agent in
+   * this room — NOT a transient/network failure. That distinction MUST be
+   * made here, before control returns to any caller, so:
+   *   - it never reaches a heal/self-heal trigger (healWedgedChannel /
+   *     onWedged re-Welcome are wired off the RECEIVE path via SDK provider
+   *     callbacks, not off a send failure — this seam guarantees a send
+   *     failure never grows one either, now or as the code evolves), and
+   *   - it never gets treated as a generic/retryable failure by a caller —
+   *     rethrown as the daemon's OWN typed `AgentPausedSendError` (mirroring
+   *     ChannelPendingError/RateLimitedError, both also bridge-agent.ts
+   *     locals) so http-server.ts/ws-server.ts can `instanceof`-check it the
+   *     same way they already do for those two, instead of it falling into
+   *     their generic "internal error" bucket.
+   * Any other error (including StaleEpochError retries, which sendWithSelfHeal
+   * already resolves internally) propagates unchanged.
+   */
+  async sendWithSelfHealTerminal(...args2) {
+    const [, channelId] = args2;
+    try {
+      return await sendWithSelfHeal(...args2);
+    } catch (e) {
+      if (e instanceof AgentPausedError) {
+        console.warn(`[bridge] send suppressed: agent paused in channel ${channelId}`);
+        throw new AgentPausedSendError(channelId);
+      }
+      throw e;
+    }
+  }
   async send(channelId, text, messageId) {
     const meta = this.freshMeta(channelId);
     if (meta && !meta.is_dm) this.enforceRateFloor("room", channelId);
@@ -2753,7 +4248,7 @@ var BridgeAgent = class _BridgeAgent {
     if (!joined) throw new ChannelPendingError(channelId);
     const id = messageId ?? crypto.randomUUID();
     const sendStart = performance.now();
-    await sendWithSelfHeal(
+    await this.sendWithSelfHealTerminal(
       this.provider,
       channelId,
       (epoch) => this.latency.time(
@@ -2789,7 +4284,7 @@ var BridgeAgent = class _BridgeAgent {
     if (!joined) throw new ChannelPendingError(channelId);
     const id = messageId ?? crypto.randomUUID();
     const sendStart = performance.now();
-    await sendWithSelfHeal(
+    await this.sendWithSelfHealTerminal(
       this.provider,
       channelId,
       (epoch) => this.latency.time(
@@ -2819,6 +4314,59 @@ var BridgeAgent = class _BridgeAgent {
     this.latency.record("send.total", performance.now() - sendStart);
     return { message_id: id, status: "sent" };
   }
+  sendDeps() {
+    return {
+      uploadBlob: (ciphertext, channelId) => this.uploadBlobImpl(ciphertext, channelId),
+      encryptFile,
+      bytesToBase64: bytesToBase642,
+      readFile: (p) => fsp.readFile(p).then((b) => new Uint8Array(b))
+    };
+  }
+  async sendAttachment(channelId, filePath, caption) {
+    this.enforceRateFloor("attachment", channelId);
+    const joined = await this.reconcileJoin(channelId);
+    if (!joined) throw new ChannelPendingError(channelId);
+    let body;
+    try {
+      body = await prepareAttachment(filePath, caption, channelId, this.sendDeps());
+    } catch (e) {
+      if (e.code === "ENOENT" || e.code === "EACCES" || e.code === "ENOTDIR" || e.code === "EISDIR") {
+        throw new InvalidPathError(filePath, e);
+      }
+      throw e;
+    }
+    const id = crypto.randomUUID();
+    const sendStart = performance.now();
+    await this.sendWithSelfHealTerminal(
+      this.provider,
+      channelId,
+      (epoch) => this.latency.time(
+        "send.encrypt",
+        () => buildOutboundEnvelope({
+          custody: this.custody,
+          groupKey: this.provider,
+          messageId: id,
+          channelId,
+          enclaveId: this.cfg.enclaveId,
+          senderId: this.cfg.identityId,
+          senderType: "agent",
+          type: "artifact_share",
+          bodyPlaintext: JSON.stringify(body),
+          bindingId: "",
+          bindingVersion: "0.0.0",
+          agentSkillId: null,
+          epoch,
+          traceparent: ZERO_TRACEPARENT,
+          references: [],
+          stage5Outcome: "allow",
+          stage5Evaluators: []
+        })
+      ),
+      (envelope) => this.latency.time("send.publish", () => this.transport.publish(envelope))
+    );
+    this.latency.record("send.total", performance.now() - sendStart);
+    return { message_id: id, status: "sent" };
+  }
   async listChannels() {
     const url = `${this.cfg.apiBase}/api/v1/enclaves/${this.cfg.enclaveId}/channels?caller_identity_id=${encodeURIComponent(this.cfg.identityId)}`;
     const res = await this.fetchImpl(url, {
@@ -2886,9 +4434,77 @@ var BridgeAgent = class _BridgeAgent {
         members.set(r.identity_id, { name: r.display_name, is_agent: r.is_agent });
       }
       this.channelRoster.set(channelId, { members, at: Date.now() });
+      await this.resolveAndPinOwner(channelId, rows);
     } catch {
     }
   }
+  /**
+   * Task 8 (owner-attested Reset Secure Session): STRUCTURAL owner selection —
+   * NEVER read the server's `role` field to pick the owner. In a DM the owner
+   * is the SINGLE non-self, non-agent counterpart; any other roster shape
+   * (zero or 2+ non-agent counterparts) is anomalous and REFUSES (no pin, no
+   * supersede eligibility). On the first clean sighting of an unambiguous
+   * owner with no existing pin, TOFU-pin its public key. On a later sighting
+   * where a pin already exists and the freshly-fetched key differs, this is an
+   * anomaly: surface it (log) and refuse — NEVER silently re-pin. Fail-soft:
+   * this must never throw into the roster refresh path.
+   */
+  async resolveAndPinOwner(channelId, rows) {
+    try {
+      const counterparts = rows.filter((r) => r.identity_id !== this.cfg.identityId && !r.is_agent);
+      if (counterparts.length !== 1) {
+        this.channelOwner.set(channelId, "anomalous");
+        return;
+      }
+      const owner = counterparts[0];
+      const publicKeyHex = owner.public_key ?? "";
+      if (!publicKeyHex) {
+        this.channelOwner.set(channelId, "anomalous");
+        return;
+      }
+      this.channelOwner.set(channelId, { identityId: owner.identity_id, publicKeyHex });
+      const existing = await this.store.loadPinnedIdentityKey(owner.identity_id);
+      if (!existing) {
+        await this.store.savePinnedIdentityKey(owner.identity_id, {
+          publicKeyHex,
+          keyAlgo: owner.key_algo ?? "ed25519"
+        });
+      } else if (existing.publicKeyHex !== publicKeyHex) {
+        console.warn(
+          `[bridge] pin mismatch for owner ${owner.identity_id} on channel ${channelId}: pinned != roster`
+        );
+        this.channelOwner.set(channelId, "anomalous");
+      }
+    } catch {
+    }
+  }
+  /**
+   * Task 8: the `onResolvePinnedOwner` hook handed to MlsGroupKeyProvider. The
+   * SDK's step-0 guard calls this before honoring an owner-authored supersede;
+   * returning null makes it fail closed. Returns a value ONLY when (a) the
+   * structural owner cache has an unambiguous entry for this channel AND (b) a
+   * persisted pin still exists and matches it — a bare in-memory cache hit is
+   * never trusted on its own, it is always reconfirmed against the store.
+   */
+  async resolvePinnedOwnerHook(channelId) {
+    const cached = this.channelOwner.get(channelId);
+    const TRACE = typeof process !== "undefined" && process.env?.SECURECOMS_TRACE_DELIVERY;
+    if (!cached || cached === "anomalous") {
+      if (TRACE) console.warn(`[trace] resolvePinnedOwner ch=${channelId.slice(0, 8)} -> NULL: cache ${!cached ? "MISSING (cold)" : "anomalous"}`);
+      return null;
+    }
+    const pin = await this.store.loadPinnedIdentityKey(cached.identityId);
+    if (!pin) {
+      if (TRACE) console.warn(`[trace] resolvePinnedOwner ch=${channelId.slice(0, 8)} -> NULL: NO PERSISTED PIN for owner ${cached.identityId.slice(0, 8)} (cache had ${cached.publicKeyHex.slice(0, 8)})`);
+      return null;
+    }
+    if (pin.publicKeyHex !== cached.publicKeyHex) {
+      if (TRACE) console.warn(`[trace] resolvePinnedOwner ch=${channelId.slice(0, 8)} -> NULL: PIN MISMATCH pin=${pin.publicKeyHex.slice(0, 8)} cache=${cached.publicKeyHex.slice(0, 8)}`);
+      return null;
+    }
+    if (TRACE) console.warn(`[trace] resolvePinnedOwner ch=${channelId.slice(0, 8)} -> OK owner=${cached.identityId.slice(0, 8)}`);
+    return { identityId: cached.identityId, publicKeyHex: pin.publicKeyHex };
+  }
   async reportStatus(channelId, state, detail) {
     const joined = await this.reconcileJoin(channelId);
     if (!joined) throw new ChannelPendingError(channelId);
@@ -2923,20 +4539,213 @@ var BridgeAgent = class _BridgeAgent {
       (envelope) => this.transport.publish(envelope)
     );
   }
+  /** `runId` must exist and not have settled yet — settle() is terminal. */
+  requireActionRun(runId) {
+    const run = this.actionRuns.get(runId);
+    if (!run || run.settled) throw new UnknownActionRunError(runId);
+    return run;
+  }
+  /**
+   * Build + send one `agent_action` E2E body over `system_event` (mirrors
+   * sendA2A/reportStatus's envelope construction — same self-heal seam). Used
+   * for BOTH partial and settled frames; the caller decides whether a send is
+   * throttle-gated (partials, via flushActionPartial) or unconditional
+   * (settled, always exactly once).
+   */
+  async sendActionFrame(channelId, body) {
+    const joined = await this.reconcileJoin(channelId);
+    if (!joined) throw new ChannelPendingError(channelId);
+    await sendWithSelfHeal(
+      this.provider,
+      channelId,
+      (epoch) => buildOutboundEnvelope({
+        custody: this.custody,
+        groupKey: this.provider,
+        messageId: crypto.randomUUID(),
+        channelId,
+        enclaveId: this.cfg.enclaveId,
+        senderId: this.cfg.identityId,
+        senderType: "agent",
+        type: "system_event",
+        bodyPlaintext: JSON.stringify(body),
+        bindingId: "",
+        bindingVersion: "0.0.0",
+        agentSkillId: null,
+        epoch,
+        traceparent: ZERO_TRACEPARENT,
+        references: [],
+        stage5Outcome: "allow",
+        stage5Evaluators: []
+      }),
+      (envelope) => this.transport.publish(envelope)
+    );
+  }
+  /**
+   * The coalescing throttle (review H4 / Global Constraint: ~1/sec per run).
+   * If the run has no dirty nodes, no-op. If the per-run bucket has no token,
+   * no-op too — the change stays in `dirty` and rides along with whatever the
+   * NEXT allowed send captures (a later start/update/finish call, or settle(),
+   * which always flushes regardless of the bucket). This is the coalescing:
+   * a burst of rapid calls collapses into however many sends the ~1/sec floor
+   * actually allows, each carrying every node changed since the last send.
+   */
+  async flushActionPartial(runId, run) {
+    if (run.dirty.size === 0) return;
+    if (!this.actionRateFloor.tryConsume(`action:${runId}`)) return;
+    if (!this.globalActionRateFloor.tryConsume("action:__global__")) return;
+    const nodes = [...run.dirty].map((id) => run.nodes.get(id)).filter((n) => n !== void 0);
+    run.dirty.clear();
+    await this.sendActionFrame(run.channelId, {
+      v: 1,
+      type: "agent_action",
+      agentActionVersion: "1",
+      phase: "partial",
+      runId,
+      nodes
+    });
+  }
+  /** Review M3: drop any unsettled run older than ACTION_RUN_STALE_MS
+   *  (relative to `now`). Lazy — invoked on every actionBegin() rather than
+   *  a background timer, mirroring the client store's orphan-TTL pattern. */
+  sweepStaleActionRuns(now) {
+    for (const [runId, run] of this.actionRuns) {
+      if (now - run.startedAt >= _BridgeAgent.ACTION_RUN_STALE_MS) this.actionRuns.delete(runId);
+    }
+  }
+  actionBegin(channelId) {
+    const now = this.actionClock();
+    this.sweepStaleActionRuns(now);
+    if (this.actionRuns.size >= _BridgeAgent.MAX_UNSETTLED_ACTION_RUNS) {
+      let oldestId;
+      let oldestAt = Infinity;
+      for (const [id, r] of this.actionRuns) {
+        if (r.startedAt < oldestAt) {
+          oldestAt = r.startedAt;
+          oldestId = id;
+        }
+      }
+      if (oldestId !== void 0) this.actionRuns.delete(oldestId);
+    }
+    const runId = crypto.randomUUID();
+    this.actionRuns.set(runId, {
+      channelId,
+      nodes: /* @__PURE__ */ new Map(),
+      dirty: /* @__PURE__ */ new Set(),
+      startedAt: now,
+      settled: false
+    });
+    return runId;
+  }
+  async actionStart(opts) {
+    const run = this.requireActionRun(opts.runId);
+    const nodeId = crypto.randomUUID();
+    const node = {
+      id: nodeId,
+      type: opts.type,
+      title: opts.title,
+      status: "running",
+      ts: Date.now(),
+      ...opts.parentId !== void 0 ? { parentId: opts.parentId } : {}
+    };
+    run.nodes.set(nodeId, node);
+    run.dirty.add(nodeId);
+    await this.flushActionPartial(opts.runId, run);
+    return nodeId;
+  }
+  async actionUpdate(runId, nodeId, patch) {
+    const run = this.requireActionRun(runId);
+    const existing = run.nodes.get(nodeId);
+    if (!existing) throw new UnknownActionRunError(`${runId}/${nodeId}`);
+    const updated = {
+      ...existing,
+      ...patch.status !== void 0 ? { status: patch.status } : {},
+      ...patch.detail !== void 0 ? { detail: patch.detail } : {},
+      ts: Date.now()
+    };
+    run.nodes.set(nodeId, updated);
+    run.dirty.add(nodeId);
+    await this.flushActionPartial(runId, run);
+  }
+  async actionFinish(runId, nodeId, patch) {
+    await this.actionUpdate(runId, nodeId, patch);
+  }
+  async actionSettle(runId, opts = {}) {
+    const run = this.requireActionRun(runId);
+    run.settled = true;
+    run.dirty.clear();
+    const nodes = [...run.nodes.values()];
+    await this.sendActionFrame(run.channelId, {
+      v: 1,
+      type: "agent_action",
+      agentActionVersion: "1",
+      phase: "settled",
+      runId,
+      startedAt: run.startedAt,
+      endedAt: Date.now(),
+      ...opts.resultMessageId !== void 0 ? { resultMessageId: opts.resultMessageId } : {},
+      nodes
+    });
+    this.actionRuns.delete(runId);
+  }
+  /**
+   * Auto-capture seam (Task 4 "auto-capture"): wraps a tool-call / sub-agent
+   * invocation so a bare agent gets a start→finish node pair without hand-
+   * rolling the begin/start/update/finish calls itself. Success → status
+   * "done"; a thrown error → status "error" with the message captured in
+   * `detail.error`, then the original error is rethrown (wrap never swallows).
+   */
+  async actionWrap(runId, fn, opts) {
+    const nodeId = await this.actionStart({
+      runId,
+      type: opts.type,
+      title: opts.title,
+      ...opts.parentId !== void 0 ? { parentId: opts.parentId } : {}
+    });
+    try {
+      const result = await fn();
+      await this.actionFinish(runId, nodeId, { status: "done" });
+      return result;
+    } catch (err) {
+      await this.actionFinish(runId, nodeId, {
+        status: "error",
+        detail: { error: err instanceof Error ? err.message : String(err) }
+      });
+      throw err;
+    }
+  }
   startReceivePump() {
     const sub = this.transport.subscribeDeliveryPings("");
     this.pingHandle = { close: sub.close };
     void (async () => {
       try {
-        for await (const _ping of sub.pings) {
+        for await (const ping of sub.pings) {
+          this.pingsReceived++;
+          if (ping?.reconnected) {
+            process.stderr.write("[bridge] delivery-ping WS (re)connected \u2014 push inbound active\n");
+          }
           await this.ingestOnce();
         }
       } catch {
       }
+      if (!this.closingDown) {
+        process.stderr.write(
+          "[bridge] delivery-ping stream ENDED (terminal WS close, e.g. 4001) \u2014 inbound reduced to the 25s safety-floor drain until the daemon restarts\n"
+        );
+      }
     })();
     this.safetyTimer = setInterval(() => {
       void this.ingestOnce();
     }, 25e3);
+    if (this.selfHealSweepEnabled) {
+      const scheduleSweep = () => {
+        this.selfHealTimer = setTimeout(() => {
+          void this.selfHealSweep();
+          scheduleSweep();
+        }, _BridgeAgent.SELF_HEAL_SWEEP_INTERVAL_MS + this.sweepJitter());
+        this.selfHealTimer.unref?.();
+      };
+      scheduleSweep();
+    }
   }
   async ingestOnce() {
     const cycleStart = performance.now();
@@ -2951,6 +4760,11 @@ var BridgeAgent = class _BridgeAgent {
           await this.reconcileJoin(cid);
         }
       }
+      for (const cid of channelIds) {
+        if (this.freshRoster(cid) === void 0) {
+          await this.refreshChannelRoster(cid);
+        }
+      }
       for (const row of rows) {
         const cid = row.connect_channel_id;
         const gid = row.group_id;
@@ -2961,8 +4775,7 @@ var BridgeAgent = class _BridgeAgent {
         if (now - last < _BridgeAgent.REQUEST_WELCOME_COOLDOWN_MS) continue;
         this.lastWelcomeRequest.set(cid, now);
         try {
-          await this.backend.requestWelcome(gid, this.cfg.deviceId);
-          this.welcomeRequestsSent++;
+          await this.signalHeldKpWelcome(gid);
         } catch {
         }
       }
@@ -2974,6 +4787,9 @@ var BridgeAgent = class _BridgeAgent {
     } catch {
       return;
     }
+    for (const cid of entries.supersededChannelIds ?? []) {
+      this.joinState.set(cid, "JOINED");
+    }
     if (!entries.length) return;
     let metaRefreshed = false;
     if (entries.some((m) => this.freshMeta(m.channelId) === void 0)) {
@@ -2995,6 +4811,42 @@ var BridgeAgent = class _BridgeAgent {
           new TextDecoder().decode(m.plaintext)
         );
         if (parsed.type && parsed.type !== "text") {
+          if (parsed.type === "artifact_share") {
+            try {
+              const senderName = this.freshRoster(m.channelId)?.get(m.envelope.sender_id)?.name;
+              const senderType = m.envelope.sender_type;
+              const senderIsAgent = senderType === "agent" ? true : senderType === "human" ? false : void 0;
+              const meta = await materializeAttachment(
+                parsed,
+                { attachmentsDir: this.attachmentsDirImpl, channelId: m.channelId, messageId: m.messageId },
+                {
+                  downloadBlob: this.downloadBlobImpl,
+                  decryptFile,
+                  computeFileDigest,
+                  base64ToBytes: base64ToBytes2,
+                  mkdirp: (d) => fsp.mkdir(d, { recursive: true }).then(() => void 0),
+                  writeFile: (p, data) => fsp.writeFile(p, data)
+                }
+              );
+              this.buffer.push({
+                channel_id: m.channelId,
+                message_id: m.messageId,
+                sender_id: m.envelope.sender_id,
+                text: typeof parsed.text === "string" ? parsed.text : "",
+                ts: m.receivedAt,
+                sender_name: senderName,
+                sender_is_agent: senderIsAgent,
+                attachments: [meta]
+              });
+              this.capBuffer();
+            } catch (e) {
+              this.failedAttachments++;
+              process.stderr.write(
+                `[bridge] attachment failed on ${m.messageId}: ${e.message}
+`
+              );
+            }
+          }
           acked.push(m.queueId);
           continue;
         }
@@ -3119,6 +4971,8 @@ var BridgeAgent = class _BridgeAgent {
       filtered_room: this.filteredRoomMessages,
       rate_limited: this.rateLimitedSends,
       permanently_skipped: this.provider.permanentlySkippedCount(),
+      failed_attachments: this.failedAttachments,
+      delivery_pings: this.pingsReceived,
       uptime_s: this.startedAt ? Math.floor((Date.now() - this.startedAt) / 1e3) : 0,
       version: BRIDGE_VERSION
     };
@@ -3159,12 +5013,17 @@ var BridgeAgent = class _BridgeAgent {
       filteredRoomMessages: this.filteredRoomMessages,
       rateLimitedSends: this.rateLimitedSends,
       permanentlySkipped: this.provider.permanentlySkippedCount(),
-      welcomeRequestsSent: this.welcomeRequestsSent
+      welcomeRequestsSent: this.welcomeRequestsSent,
+      failedAttachments: this.failedAttachments
     };
   }
   async close() {
+    this.closingDown = true;
     this.pingHandle?.close();
     if (this.safetyTimer) clearInterval(this.safetyTimer);
+    if (this.bootSweepTimer) clearTimeout(this.bootSweepTimer);
+    if (this.selfHealTimer) clearTimeout(this.selfHealTimer);
+    await this.provider.drainInFlight(_BridgeAgent.GRACEFUL_DRAIN_MS);
     this.store.close();
   }
 };
@@ -3226,6 +5085,7 @@ var BRIDGE_ERRORS = {
   body_too_large: { http: 400, message: "request body exceeds the size limit" },
   channel_pending: { http: 503, message: "channel not yet admitted; retry shortly" },
   rate_limited: { http: 429, message: "rate limit exceeded; retry shortly" },
+  unknown_action_run: { http: 404, message: "unknown or already-settled action run" },
   internal: { http: 500, message: "internal error" }
 };
 function errorBody(code, detail) {
@@ -3271,6 +5131,11 @@ var a2aSchema = z.object({
   kind: z.enum(["message", "task", "artifact"]),
   object: z.record(z.unknown())
 });
+var sendAttachmentSchema = z.object({
+  channel_id: z.string().min(1),
+  path: z.string().min(1),
+  caption: z.string().optional()
+});
 var sendSchema = z.object({
   channel_id: z.string().min(1),
   text: z.string().optional(),
@@ -3365,6 +5230,12 @@ function createHttpServer(agent, opts) {
         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);
         return json(res, 200, r);
       }
+      if (method === "POST" && path === "/v1/send-attachment") {
+        const parsed = sendAttachmentSchema.safeParse(JSON.parse(await readBody(req, OTHER_CAP)));
+        if (!parsed.success) return jsonError(res, "invalid_request", parsed.error.issues);
+        const r = await agent.sendAttachment(parsed.data.channel_id, parsed.data.path, parsed.data.caption);
+        return json(res, 200, r);
+      }
       if (method === "POST" && path === "/v1/status") {
         const parsed = statusSchema.safeParse(JSON.parse(await readBody(req, OTHER_CAP)));
         if (!parsed.success) return jsonError(res, "invalid_request", parsed.error.issues);
@@ -3414,6 +5285,7 @@ function createHttpServer(agent, opts) {
       }
       if (e instanceof ChannelPendingError) return jsonError(res, "channel_pending");
       if (e instanceof RateLimitedError) return jsonError(res, "rate_limited");
+      if (e instanceof InvalidPathError) return jsonError(res, "invalid_request", e.message);
       if (e instanceof SyntaxError) return jsonError(res, "invalid_json");
       process.stderr.write(`[bridge] request error: ${e?.message ?? e}
 `);
@@ -3623,26 +5495,99 @@ async function handleInbound(sock, agent, data, inflight) {
     }
     return;
   }
+  const NODE_TYPES = ["step", "tool_call", "sub_task", "result"];
+  const NODE_STATUSES = ["pending", "running", "done", "error"];
+  const actionError = (e) => {
+    sendJson(sock, wsErrorFrame(e instanceof UnknownActionRunError ? "unknown_action_run" : "invalid_request"));
+  };
+  if (m.type === "action_begin") {
+    if (typeof m.channel_id !== "string" || !m.channel_id) {
+      sendJson(sock, wsErrorFrame("invalid_request", "channel_id required"));
+      return;
+    }
+    try {
+      sendJson(sock, { type: "action_begun", run_id: agent.action.begin(m.channel_id) });
+    } catch (e) {
+      actionError(e);
+    }
+    return;
+  }
+  if (m.type === "action_start") {
+    if (typeof m.run_id !== "string" || !m.run_id || typeof m.title !== "string" || !m.title || !NODE_TYPES.includes(m.node_type)) {
+      sendJson(sock, wsErrorFrame("invalid_request", "run_id, node_type, title required"));
+      return;
+    }
+    try {
+      const nodeId = await agent.action.start({
+        runId: m.run_id,
+        type: m.node_type,
+        title: m.title,
+        parentId: typeof m.parent_id === "string" && m.parent_id ? m.parent_id : void 0
+      });
+      sendJson(sock, { type: "action_started", node_id: nodeId });
+    } catch (e) {
+      actionError(e);
+    }
+    return;
+  }
+  if (m.type === "action_update" || m.type === "action_finish") {
+    if (typeof m.run_id !== "string" || !m.run_id || typeof m.node_id !== "string" || !m.node_id) {
+      sendJson(sock, wsErrorFrame("invalid_request", "run_id and node_id required"));
+      return;
+    }
+    try {
+      if (m.type === "action_finish") {
+        if (m.status !== "done" && m.status !== "error") {
+          sendJson(sock, wsErrorFrame("invalid_request", "finish status must be done|error"));
+          return;
+        }
+        await agent.action.finish(m.run_id, m.node_id, { status: m.status, detail: m.detail });
+      } else {
+        if (m.status !== void 0 && !NODE_STATUSES.includes(m.status)) {
+          sendJson(sock, wsErrorFrame("invalid_request", "bad status"));
+          return;
+        }
+        await agent.action.update(m.run_id, m.node_id, { status: m.status, detail: m.detail });
+      }
+      sendJson(sock, { type: "ok" });
+    } catch (e) {
+      actionError(e);
+    }
+    return;
+  }
+  if (m.type === "action_settle") {
+    if (typeof m.run_id !== "string" || !m.run_id) {
+      sendJson(sock, wsErrorFrame("invalid_request", "run_id required"));
+      return;
+    }
+    try {
+      await agent.action.settle(m.run_id, { resultMessageId: typeof m.result_message_id === "string" && m.result_message_id ? m.result_message_id : void 0 });
+      sendJson(sock, { type: "action_settled", run_id: m.run_id });
+    } catch (e) {
+      actionError(e);
+    }
+    return;
+  }
   sendJson(sock, wsErrorFrame("invalid_request"));
 }
 
 // src/bin.ts
 import { readFileSync as readFileSync3, mkdirSync, writeFileSync as writeFileSync2, rmSync, existsSync as existsSync2, realpathSync } from "node:fs";
-import { join as join3, dirname as dirname4 } from "node:path";
+import { join as join4, dirname as dirname5 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir, userInfo } from "node:os";
 import { spawnSync } from "node:child_process";
 
 // src/service/install.ts
-import { dirname as dirname2 } from "node:path";
+import { dirname as dirname3 } from "node:path";
 
 // src/service/config.ts
-import { basename, extname, isAbsolute, resolve } from "node:path";
+import { basename as basename2, extname, isAbsolute, resolve } from "node:path";
 function slugify(s) {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
 }
 function deriveServiceConfig(input) {
-  const stem = input.label ?? basename(input.credentialPath, extname(input.credentialPath));
+  const stem = input.label ?? basename2(input.credentialPath, extname(input.credentialPath));
   const slug = slugify(stem);
   const cred = isAbsolute(input.credentialPath) ? input.credentialPath : resolve(input.credentialPath);
   const args2 = ["--credential", cred];
@@ -3718,7 +5663,7 @@ WantedBy=default.target
 var ServiceUnsupportedError = class extends Error {
 };
 function tokenHint(input) {
-  return `${dirname2(input.credentialPath)}/bridge-token`;
+  return `${dirname3(input.credentialPath)}/bridge-token`;
 }
 function requireOk(r, what) {
   if (r.status !== 0) throw new Error(`${what} failed (exit ${r.status})${r.stderr ? `: ${r.stderr.trim()}` : ""}`);
@@ -3726,8 +5671,8 @@ function requireOk(r, what) {
 function installService(input, deps) {
   const cfg = deriveServiceConfig(input);
   if (deps.platform === "darwin") {
-    deps.mkdirp(dirname2(cfg.plistPath));
-    deps.mkdirp(dirname2(cfg.logPath));
+    deps.mkdirp(dirname3(cfg.plistPath));
+    deps.mkdirp(dirname3(cfg.logPath));
     deps.writeFile(cfg.plistPath, renderLaunchdPlist(cfg));
     deps.run("launchctl", ["bootout", `gui/${cfg.uid}/${cfg.label}`]);
     requireOk(deps.run("launchctl", ["bootstrap", `gui/${cfg.uid}`, cfg.plistPath]), "launchctl bootstrap");
@@ -3736,7 +5681,7 @@ function installService(input, deps) {
     return { label: cfg.label, filePath: cfg.plistPath, logHint: cfg.logPath, tokenHint: tokenHint(input) };
   }
   if (deps.platform === "linux") {
-    deps.mkdirp(dirname2(cfg.unitPath));
+    deps.mkdirp(dirname3(cfg.unitPath));
     deps.writeFile(cfg.unitPath, renderSystemdUnit(cfg));
     deps.run("systemctl", ["--user", "daemon-reload"]);
     deps.run("loginctl", ["enable-linger", deps.user]);
@@ -3764,7 +5709,7 @@ function uninstallService(input, deps) {
 }
 
 // src/service/resolve-bin.ts
-import { join as join2, dirname as dirname3 } from "node:path";
+import { join as join3, dirname as dirname4 } from "node:path";
 import { createRequire } from "node:module";
 var GlobalInstallPermissionError = class extends Error {
   constructor(message) {
@@ -3789,7 +5734,7 @@ function resolveStableBinScript(input, deps) {
     if (deps.fileExists(input.binScript)) return input.binScript;
     throw new Error(`bin path does not exist and is not an npx cache path: ${input.binScript}`);
   }
-  const pkgRoot = dirname3(dirname3(input.binScript));
+  const pkgRoot = dirname4(dirname4(input.binScript));
   const inst = deps.run("npm", ["i", "-g", pkgRoot, "--install-links"]);
   if (inst.status !== 0) {
     if (/EACCES|permission denied/i.test(inst.stderr)) {
@@ -3802,7 +5747,7 @@ function resolveStableBinScript(input, deps) {
   }
   const root = deps.run("npm", ["root", "-g"]);
   if (root.status !== 0) throw new Error(`npm root -g failed (exit ${root.status})`);
-  const stable = join2(root.stdout.trim(), input.packageName, "dist", "bin.js");
+  const stable = join3(root.stdout.trim(), input.packageName, "dist", "bin.js");
   if (!deps.fileExists(stable)) throw new Error(`global install did not produce ${stable}`);
   return stable;
 }
@@ -3816,6 +5761,10 @@ function loadPackageMeta(importMetaUrl) {
 function nodeMajorOk(version) {
   return Number(version.split(".")[0]) >= 24;
 }
+function tokenFingerprint(token) {
+  const prefixLen = Math.min(6, token.length);
+  return `${token.slice(0, prefixLen)}... (${token.length} chars)`;
+}
 function argOrEnv(flag, env) {
   const i = process.argv.indexOf(flag);
   if (i >= 0 && process.argv[i + 1]) return process.argv[i + 1];
@@ -3921,7 +5870,7 @@ async function main() {
 `);
     process.exit(1);
   }
-  const tokenFile = daemon.tokenFile ?? join3(dirname4(credentialPath), "bridge-token");
+  const tokenFile = daemon.tokenFile ?? join4(dirname5(credentialPath), "bridge-token");
   const token = resolveToken({ tokenFile, token: daemon.token });
   const agent = new BridgeAgent(cfg);
   await agent.start();
@@ -3935,7 +5884,12 @@ async function main() {
     agentWs.close();
     server.close();
     closeAllSseStreams();
-    void agent.close().finally(() => process.exit(0));
+    const hard = setTimeout(() => process.exit(0), 8e3);
+    hard.unref?.();
+    void agent.close().finally(() => {
+      clearTimeout(hard);
+      process.exit(0);
+    });
   };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
@@ -3944,7 +5898,7 @@ async function main() {
     const wsScheme = tls ? "wss" : "ws";
     process.stderr.write(`[bridge] listening on ${scheme}://${daemon.bind}:${daemon.port} (agent WS at ${wsScheme}://${daemon.bind}:${daemon.port}/v1/ws)
 `);
-    process.stderr.write(`BRIDGE_TOKEN=${token}
+    process.stderr.write(`[bridge] bearer token: ${tokenFingerprint(token)} (token file: ${tokenFile})
 `);
   });
 }
@@ -3959,5 +5913,6 @@ if (isMain) {
 }
 export {
   nodeMajorOk,
-  parseVerb
+  parseVerb,
+  tokenFingerprint
 };