@securecoms/agent-bridge 0.11.0 → 0.11.1

package/dist/bridge-agent.js

@@ -0,0 +1,831 @@
+import { RestTransport, RestMlsBackend, SoftwareKeyCustody, MlsGroupKeyProvider, buildOutboundEnvelope, sendWithSelfHeal, KeyedInboxCipher, deriveMlsStoreKey, } from "@agentvault/connect-sdk-ts";
+import { SqliteMlsStateStore } from "@agentvault/connect-mls-store";
+import { decryptFile, encryptFile, computeFileDigest, base64ToBytes, bytesToBase64 } from "@agentvault/crypto";
+import { promises as fsp } from "node:fs";
+import { join, dirname } from "node:path";
+import { LatencyRecorder } from "./latency.js";
+import { shouldProcessRoomMessage } from "./coordination.js";
+import { TokenBucketFloor } from "./rate-limit.js";
+import { materializeAttachment, prepareAttachment } from "./attachments.js";
+/** Default inbound-buffer cap (messages) when deps.maxBuffer is unset. */
+export const DEFAULT_MAX_BUFFER = 1000;
+/**
+ * TTL for the Phase 2 channelMeta cache. `is_dm` is immutable for a channel_id,
+ * so this exists only so a cached `name` (the room display name used by the
+ * @mention filter) re-resolves after a channel rename. Lazy expiry on read.
+ */
+export const CHANNEL_META_TTL_MS = 5 * 60_000;
+/**
+ * TTL for the Phase 2 channel ROSTER cache (channel_id → identity_id → name /
+ * is_agent), used to attribute decrypted messages by sender. Parallels
+ * CHANNEL_META_TTL_MS: a member's display_name can change (rename) and the
+ * member set can change, so a stale roster re-resolves on a later cycle. Lazy
+ * expiry on read. Resolution is best-effort and fail-soft — a miss leaves
+ * sender_name undefined and NEVER blocks or drops a message.
+ */
+export const CHANNEL_ROSTER_TTL_MS = 5 * 60_000;
+const ZERO_TRACEPARENT = "00-" + "0".repeat(32) + "-" + "0".repeat(16) + "-01";
+export class ChannelPendingError extends Error {
+    channelId;
+    constructor(channelId) {
+        super(`channel ${channelId} is not yet admitted (awaiting Welcome)`);
+        this.channelId = channelId;
+        this.name = "ChannelPendingError";
+    }
+}
+export class RateLimitedError extends Error {
+    channelId;
+    retryAfterMs;
+    constructor(channelId, retryAfterMs) {
+        super(`channel ${channelId} send rate limit exceeded (retry in ${retryAfterMs}ms)`);
+        this.channelId = channelId;
+        this.retryAfterMs = retryAfterMs;
+        this.name = "RateLimitedError";
+    }
+}
+export class InvalidPathError extends Error {
+    filePath;
+    constructor(filePath, cause) {
+        super(`cannot read attachment file: ${filePath}`);
+        this.filePath = filePath;
+        this.name = "InvalidPathError";
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+export const BRIDGE_VERSION = "0.0.0"; // surfaced by /healthz; bump with package.json
+function hexToBytes(h) {
+    return new Uint8Array(Buffer.from(h, "hex"));
+}
+export class BridgeAgent {
+    cfg;
+    transport;
+    provider;
+    backend; // stored for peek-then-join in ingestOnce
+    custody;
+    fetchImpl;
+    joinState = new Map();
+    /**
+     * Phase 2: lazy channel-metadata cache (channel_id → { is_dm, name, at }) used
+     * by the multi-agent room @mention filter at ingest. Populated/refreshed from a
+     * SINGLE listChannels() per ingest cycle on a cache miss. A channel that cannot
+     * be resolved (network error, or not present in the listing) stays UNKNOWN → the
+     * filter fails OPEN.
+     *
+     * `is_dm` is immutable for a given channel_id (no misclassification risk), so the
+     * TTL exists only to keep `name` fresh after a channel rename — an entry older
+     * than CHANNEL_META_TTL_MS is treated as a miss and re-resolved on the next cycle.
+     */
+    channelMeta = new Map();
+    /**
+     * Phase 2 (sender attribution): per-channel roster cache
+     * (channel_id → identity_id → { name, is_agent }) resolved from the GET
+     * members endpoint. Same lazy/TTL/fail-soft discipline as channelMeta: an
+     * unresolved channel (network error, or no entry) leaves sender_name
+     * undefined and never blocks ingest. Resolved AT MOST ONCE per ingest cycle
+     * per channel on a miss.
+     */
+    channelRoster = new Map();
+    buffer = [];
+    maxBuffer;
+    /** Cumulative count of messages shed by the buffer cap (surfaced on health()/metrics()). */
+    droppedMessages = 0;
+    /**
+     * Cumulative count of ROOM messages dropped by the @mention filter (item 3 /
+     * ADR-0002 ethos). Surfaced on health()/metrics() so an agent correctly filtering
+     * most room traffic is distinguishable from an idle/wedged one.
+     */
+    filteredRoomMessages = 0;
+    /** Cumulative count of sends shed by the per-channel rate-limit floor (surfaced on health()/metrics()). */
+    rateLimitedSends = 0;
+    /** Cumulative count of requestWelcome calls fired for no-local-state deliveries (self-heal signal). */
+    welcomeRequestsSent = 0;
+    /**
+     * 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 = new Map();
+    /** Minimum gap between requestWelcome calls for the same channel (2 minutes). */
+    static REQUEST_WELCOME_COOLDOWN_MS = 120_000;
+    rateFloor;
+    waiters = [];
+    pingHandle;
+    safetyTimer;
+    listeners = new Set();
+    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;
+    constructor(cfg, deps = {}) {
+        this.cfg = cfg;
+        const seed = hexToBytes(cfg.signingPrivateKey);
+        this.custody = SoftwareKeyCustody.fromPrivateKey("ed25519", seed);
+        this.transport =
+            deps.transport ??
+                new RestTransport({ baseUrl: cfg.apiBase, bearerToken: cfg.apiKey, connectIdentityId: cfg.identityId });
+        this.backend =
+            deps.backend ??
+                new RestMlsBackend({ baseUrl: cfg.apiBase, bearerToken: cfg.apiKey });
+        this.store = new SqliteMlsStateStore({
+            dbPath: cfg.storePath,
+            identityId: cfg.identityId,
+            cipherFor: () => new KeyedInboxCipher(deriveMlsStoreKey(seed)),
+        });
+        this.provider = new MlsGroupKeyProvider({
+            store: this.store,
+            backend: this.backend,
+            deviceId: cfg.deviceId,
+            identity: new TextEncoder().encode(cfg.identityId),
+            // 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.
+            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.fetchImpl = deps.fetchImpl ?? fetch;
+        this.latency = deps.latency ?? new LatencyRecorder();
+        this.maxBuffer = deps.maxBuffer ?? DEFAULT_MAX_BUFFER;
+        this.rateFloor = new TokenBucketFloor({
+            capacity: cfg.rateLimitCapacity ?? 20,
+            refillPerMinute: cfg.rateLimitRefillPerMinute ?? 20,
+        });
+        // Track 5: attachment receive deps
+        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 ?? join(dirname(cfg.storePath), "attachments");
+    }
+    /**
+     * Enforce the inbound-buffer cap with a DROP-OLDEST policy.
+     *
+     * The buffer is uniformly ordered oldest→newest: ingestOnce() appends freshly
+     * decrypted inbound at the BACK (newest), and requeueFront() unshifts un-acked
+     * messages at the FRONT — those re-buffered messages were consumed earlier, so
+     * they are by definition OLDER than whatever already sits in the buffer. In
+     * every push path the newest messages therefore live at the back. To honour
+     * "the most-recent survive" we always shed from the FRONT, then record the
+     * shed so a silently-dropping daemon stays observable (item 3 / ADR-0002).
+     */
+    capBuffer() {
+        if (this.maxBuffer <= 0)
+            return;
+        const overflow = this.buffer.length - this.maxBuffer;
+        if (overflow > 0) {
+            this.buffer.splice(0, overflow); // drop the oldest, keep the newest maxBuffer
+            this.droppedMessages += overflow;
+        }
+    }
+    async start() {
+        this.startedAt = Date.now();
+        // B1 carry-forward: a restart loses the in-memory pending bundle, so always
+        // re-publish so the owner's cycle-A admission watcher (re)adds this leaf.
+        await this.provider.publishKeyPackage();
+        this.startReceivePump();
+    }
+    async reconcileJoin(channelId) {
+        if (this.joinState.get(channelId) === "JOINED")
+            return true;
+        try {
+            // Reconcile, not a plain join. joinAndReconcile = ensureSession(join)
+            // (consume the Welcome, or early-return if we already hold state) THEN
+            // drain pending commits so we converge on the group's CURRENT epoch.
+            // A plain ensureSession(join) lands at the Welcome's epoch and never
+            // advances: if the owner adds another member after we joined (a commit
+            // bumps the epoch), every later message arrives at an epoch we don't
+            // hold, fails to decrypt, and piles up unconsumed — the channel goes
+            // silent for the agent even though it is a member. Reconciling on
+            // (re)join applies that commit and unsticks it.
+            await this.provider.joinAndReconcile(channelId, this.cfg.enclaveId);
+            this.joinState.set(channelId, "JOINED");
+            return true;
+        }
+        catch {
+            // "no Welcome available yet" — the owner watcher hasn't added us. Stay
+            // PENDING; the pump MUST NOT die. Retried on the next cycle/use.
+            this.joinState.set(channelId, "PENDING");
+            return false;
+        }
+    }
+    /**
+     * Per-channel send-floor check. No-op on allow; throws RateLimitedError on a
+     * trip (incrementing the observable counter). `kind` namespaces the bucket so
+     * room and a2a traffic on the same channel are tracked separately.
+     */
+    enforceRateFloor(kind, channelId) {
+        const key = `${kind}:${channelId}`;
+        if (!this.rateFloor.tryConsume(key)) {
+            this.rateLimitedSends++;
+            throw new RateLimitedError(channelId, this.rateFloor.msUntilNextToken(key));
+        }
+    }
+    async send(channelId, text, messageId) {
+        const meta = this.freshMeta(channelId);
+        if (meta && !meta.is_dm)
+            this.enforceRateFloor("room", channelId);
+        const joined = await this.reconcileJoin(channelId);
+        if (!joined)
+            throw new ChannelPendingError(channelId);
+        const id = messageId ?? crypto.randomUUID();
+        const sendStart = performance.now();
+        // Self-heal-on-send (Phase 1.1) via the SHARED SDK seam. reconcileJoin only
+        // converges on the FIRST join (it early-returns once JOINED), so a bridge
+        // that fell behind because a peer committed would seal at a stale epoch and
+        // be rejected with an epoch-stale 400. sendWithSelfHeal reconciles per send
+        // (drain pending commits) and retries once on a stale 400.
+        // send.encrypt = MLS application-message seal (XChaCha20-Poly1305 over the
+        // group's current epoch secret). send.publish = relay to the backend over
+        // the persistent transport. send.total = the full agent-visible send cost.
+        await sendWithSelfHeal(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: "text",
+            bodyPlaintext: JSON.stringify({ text }),
+            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 sendA2A(channelId, a2a, messageId) {
+        this.enforceRateFloor("a2a", channelId);
+        const joined = await this.reconcileJoin(channelId);
+        if (!joined)
+            throw new ChannelPendingError(channelId);
+        const id = messageId ?? crypto.randomUUID();
+        const sendStart = performance.now();
+        // Self-heal-on-send (Phase 1.1) via the SHARED SDK seam (mirrors send()).
+        await sendWithSelfHeal(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: "a2a",
+            bodyPlaintext: JSON.stringify({ type: "a2a", a2a_version: a2a.a2a_version, kind: a2a.kind, object: a2a.object }),
+            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" };
+    }
+    sendDeps() {
+        return {
+            uploadBlob: (ciphertext, channelId) => this.uploadBlobImpl(ciphertext, channelId),
+            encryptFile,
+            bytesToBase64,
+            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);
+        // prepareAttachment reads, encrypts, and uploads the file — wrap readFile failures
+        // as InvalidPathError so the HTTP layer can return a clear 400 instead of 500.
+        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 sendWithSelfHeal(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, {
+            headers: { authorization: `Bearer ${this.cfg.apiKey}` },
+        });
+        if (!res.ok)
+            throw new Error(`list_channels failed: ${res.status}`);
+        const rows = (await res.json());
+        return rows.map((r) => ({
+            channel_id: r.channel_id,
+            name: r.name ?? null,
+            is_dm: r.is_dm,
+            joined: true,
+        }));
+    }
+    /** A live channelMeta entry, or undefined if missing OR expired past the TTL. */
+    freshMeta(channelId) {
+        const hit = this.channelMeta.get(channelId);
+        if (!hit)
+            return undefined;
+        // Lazy TTL expiry: a stale entry is treated as a miss so `name` re-resolves
+        // on the next cycle's single refresh. (is_dm is immutable; this is for name.)
+        if (Date.now() - hit.at >= CHANNEL_META_TTL_MS)
+            return undefined;
+        return { is_dm: hit.is_dm, name: hit.name };
+    }
+    /**
+     * One-shot, whole-listing refresh of channelMeta. Called AT MOST ONCE per
+     * ingest cycle (the caller guards with a cycle-local "refreshed" flag), so a
+     * burst of K unknown channels fires a single listChannels() instead of K. Any
+     * listChannels failure is swallowed (UNKNOWN → fail open) so ingest never
+     * blocks on the network.
+     */
+    async refreshChannelMeta() {
+        try {
+            const now = Date.now();
+            const channels = await this.listChannels();
+            for (const c of channels) {
+                this.channelMeta.set(c.channel_id, { is_dm: c.is_dm, name: c.name, at: now });
+            }
+        }
+        catch {
+            /* network error → leave cache as-is → unresolved channels fail open */
+        }
+    }
+    /** A live roster for a channel, or undefined if missing OR expired past the TTL. */
+    freshRoster(channelId) {
+        const hit = this.channelRoster.get(channelId);
+        if (!hit)
+            return undefined;
+        if (Date.now() - hit.at >= CHANNEL_ROSTER_TTL_MS)
+            return undefined;
+        return hit.members;
+    }
+    /**
+     * Resolve one channel's roster (members + display names + is-agent) from the
+     * GET members endpoint into the roster cache. Called AT MOST ONCE per ingest
+     * cycle per channel on a cache miss. Fail-soft: any error leaves the cache
+     * as-is so the affected senders stay unresolved (sender_name undefined) —
+     * attribution must NEVER block or drop a message.
+     */
+    async refreshChannelRoster(channelId) {
+        try {
+            const url = `${this.cfg.apiBase}/api/v1/channels/${encodeURIComponent(channelId)}/members?caller_identity_id=${encodeURIComponent(this.cfg.identityId)}`;
+            const res = await this.fetchImpl(url, {
+                headers: { authorization: `Bearer ${this.cfg.apiKey}` },
+            });
+            if (!res.ok)
+                return; // fail-soft: leave unresolved
+            const rows = (await res.json());
+            const members = new Map();
+            for (const r of rows) {
+                members.set(r.identity_id, { name: r.display_name, is_agent: r.is_agent });
+            }
+            this.channelRoster.set(channelId, { members, at: Date.now() });
+        }
+        catch {
+            /* network/parse error → leave cache as-is → senders fail soft (unresolved) */
+        }
+    }
+    async reportStatus(channelId, state, detail) {
+        const joined = await this.reconcileJoin(channelId);
+        if (!joined)
+            throw new ChannelPendingError(channelId);
+        // Self-heal-on-send (Phase 1.1) via the SHARED SDK seam (mirrors send()).
+        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({
+                v: 1,
+                type: "agent_status",
+                state,
+                at: new Date().toISOString(),
+                ...(detail ? { detail } : {}),
+            }),
+            bindingId: "",
+            bindingVersion: "0.0.0",
+            agentSkillId: null,
+            epoch,
+            traceparent: ZERO_TRACEPARENT,
+            references: [],
+            stage5Outcome: "allow",
+            stage5Evaluators: [],
+        }), (envelope) => this.transport.publish(envelope));
+    }
+    startReceivePump() {
+        // Device-scoped WS ping stream (channel arg ignored by RestTransport).
+        const sub = this.transport.subscribeDeliveryPings("");
+        this.pingHandle = { close: sub.close };
+        void (async () => {
+            try {
+                for await (const _ping of sub.pings) {
+                    await this.ingestOnce();
+                }
+            }
+            catch {
+                /* stream closed — pump exits cleanly */
+            }
+        })();
+        // Safety floor: drain every 25s even if a ping is missed.
+        this.safetyTimer = setInterval(() => {
+            void this.ingestOnce();
+        }, 25_000);
+    }
+    async ingestOnce() {
+        // Phase 0: peek at pending delivery rows to find channel IDs. Reconcile
+        // join for each unjoined channel so that receiveOnce can load the MLS state
+        // and decrypt application messages. Without this, application decryption
+        // silently fails because the MLS group manager hasn't been initialised for
+        // the channel yet (the Welcome must be consumed via ensureSession first).
+        const cycleStart = performance.now();
+        try {
+            const rows = await this.latency.time("recv.pull", () => this.backend.pullDelivery(this.cfg.deviceId));
+            const channelIds = new Set();
+            for (const row of rows) {
+                if (row.connect_channel_id)
+                    channelIds.add(row.connect_channel_id);
+            }
+            for (const cid of channelIds) {
+                if (this.joinState.get(cid) !== "JOINED") {
+                    await this.reconcileJoin(cid);
+                }
+            }
+            // Self-heal: a channel we received delivery for but still have NO local MLS
+            // state for (after attempting a join) is diverged — ask the committer to
+            // re-Welcome us. Rate-limited per channel. (No string-matching; the
+            // persisted-state check is the signal.) Use hasPersistedChannelState (store
+            // + in-memory), NOT the in-memory-only hasChannelState: a healthy agent
+            // whose manager is merely cold this cycle (e.g. a stray-welcome-only cycle)
+            // has persisted state and must NOT trigger a spurious heal/epoch-churn.
+            for (const row of rows) {
+                const cid = row.connect_channel_id;
+                const gid = row.group_id;
+                if (!cid || !gid)
+                    continue;
+                if (await this.provider.hasPersistedChannelState(cid))
+                    continue;
+                const now = performance.now();
+                const last = this.lastWelcomeRequest.get(cid) ?? -Infinity;
+                if (now - last < BridgeAgent.REQUEST_WELCOME_COOLDOWN_MS)
+                    continue;
+                this.lastWelcomeRequest.set(cid, now);
+                try {
+                    await this.backend.requestWelcome(gid, this.cfg.deviceId);
+                    this.welcomeRequestsSent++;
+                }
+                catch { /* best-effort; retried next eligible cycle */ }
+            }
+        }
+        catch {
+            /* best-effort; receiveOnce proceeds regardless */
+        }
+        let entries;
+        try {
+            // recv.decrypt = pull + MLS open of any queued application messages
+            // (symmetric AEAD over the sender's epoch secret) for this device.
+            entries = await this.latency.time("recv.decrypt", () => this.provider.receiveOnce(this.cfg.deviceId));
+        }
+        catch {
+            return; // never let a receive error kill the pump
+        }
+        // Only record a cycle when there was actually something to process — empty
+        // poll ticks (the 25s safety drain) would otherwise dominate the metric.
+        if (!entries.length)
+            return;
+        // S-1: resolve channel metadata AT MOST ONCE per cycle. If any entry's
+        // channel is missing/expired in the cache, do a SINGLE listChannels() for the
+        // whole cycle and set metaRefreshed so no second call fires this tick. Any
+        // channel still unknown after that one refresh fails OPEN (buffers) with no
+        // further calls. ≤1 listChannels() per ingest cycle.
+        let metaRefreshed = false;
+        if (entries.some((m) => this.freshMeta(m.channelId) === undefined)) {
+            await this.refreshChannelMeta();
+            metaRefreshed = true;
+        }
+        // S-1 (roster): resolve each distinct channel's roster AT MOST ONCE per
+        // cycle on a miss, so a burst across K channels fires at most K member
+        // fetches (one per channel) and a single channel with N messages fires
+        // exactly one. Fail-soft inside refreshChannelRoster (a miss leaves
+        // sender_name undefined; never blocks ingest).
+        const rosterRefreshed = new Set();
+        for (const m of entries) {
+            if (rosterRefreshed.has(m.channelId))
+                continue;
+            rosterRefreshed.add(m.channelId);
+            if (this.freshRoster(m.channelId) === undefined) {
+                await this.refreshChannelRoster(m.channelId);
+            }
+        }
+        const acked = [];
+        for (const m of entries) {
+            try {
+                const parsed = JSON.parse(new TextDecoder().decode(m.plaintext));
+                // Handle non-text messages: artifact_share → materialize; others → skip+ack
+                if (parsed.type && parsed.type !== "text") {
+                    if (parsed.type === "artifact_share") {
+                        // Track 5: fail-soft — a download/decrypt/digest failure acks the message
+                        // (no redelivery), increments the counter, and logs but never throws.
+                        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 : undefined;
+                            const meta = await materializeAttachment(parsed, { attachmentsDir: this.attachmentsDirImpl, channelId: m.channelId, messageId: m.messageId }, {
+                                downloadBlob: this.downloadBlobImpl,
+                                decryptFile,
+                                computeFileDigest,
+                                base64ToBytes,
+                                mkdirp: (d) => fsp.mkdir(d, { recursive: true }).then(() => undefined),
+                                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}\n`);
+                        }
+                    }
+                    // other non-text control/status messages: skip (still ack below)
+                    acked.push(m.queueId);
+                    continue;
+                }
+                if (typeof parsed.text === "string") {
+                    // Phase 2 — multi-agent room @mention filter. Classify the channel:
+                    //   DM     → always buffer (1:1, no filtering)
+                    //   Room   → buffer only if the @mention filter says this agent should
+                    //            see it; a message @mentioning a *different* agent is
+                    //            skipped (but still acked so it isn't redelivered forever)
+                    //   UNKNOWN→ fail OPEN: buffer (never silently drop the unclassifiable)
+                    // Metadata was resolved once at the top of the cycle (metaRefreshed).
+                    // freshMeta is a pure cache read here — no per-message network call.
+                    void metaRefreshed;
+                    const meta = this.freshMeta(m.channelId);
+                    // sender_type is the on-wire envelope field (see envelope-builder /
+                    // fake-backend). The @mention filter passes it through; Phase 2 also
+                    // surfaces it on BridgeMessage as sender_is_agent (same derivation,
+                    // not recomputed differently).
+                    const senderType = m.envelope.sender_type;
+                    const senderIsAgent = senderType === "agent" ? true : senderType === "human" ? false : undefined;
+                    let shouldBuffer = true;
+                    if (meta && meta.is_dm === false) {
+                        shouldBuffer = shouldProcessRoomMessage(parsed.text, this.cfg.agentName ?? this.cfg.identityId, this.cfg.identityId, { senderIsAgent, roomDisplayName: meta.name ?? undefined });
+                        if (!shouldBuffer)
+                            this.filteredRoomMessages++; // item 3: observable filtering
+                    }
+                    if (shouldBuffer) {
+                        // Phase 2: attribute the sender. Roster lookup is a pure cache
+                        // read here (resolved once per cycle above) — never a per-message
+                        // network call. Unresolved → sender_name undefined (fail-soft;
+                        // consumer falls back to sender_id). NEVER drop/delay on a miss.
+                        const senderName = this.freshRoster(m.channelId)?.get(m.envelope.sender_id)?.name;
+                        this.buffer.push({
+                            channel_id: m.channelId,
+                            message_id: m.messageId,
+                            sender_id: m.envelope.sender_id,
+                            text: parsed.text,
+                            ts: m.receivedAt,
+                            sender_name: senderName,
+                            sender_is_agent: senderIsAgent,
+                        });
+                        // Bound the buffer: a never-draining consumer must not OOM the daemon.
+                        // Newest was just appended at the back → shed the oldest from the front.
+                        this.capBuffer();
+                    }
+                    // Filtered-out room messages are still acked below (no redelivery loop).
+                }
+                acked.push(m.queueId);
+            }
+            catch {
+                // non-JSON / unparseable: ack to avoid redelivery loop
+                acked.push(m.queueId);
+            }
+        }
+        if (acked.length) {
+            try {
+                await this.latency.time("recv.ack", () => this.provider.ackDelivery(this.cfg.deviceId, acked));
+            }
+            catch {
+                /* retried next cycle */
+            }
+        }
+        // recv.cycle = the full receive-and-decrypt cost for a non-empty tick
+        // (pull + decrypt + parse + ack), i.e. the recipient half of the envelope.
+        this.latency.record("recv.cycle", performance.now() - cycleStart);
+        if (this.buffer.length) {
+            for (const l of this.listeners)
+                l();
+            const w = this.waiters.splice(0);
+            for (const r of w)
+                r();
+        }
+    }
+    async drain(channelId, waitSeconds) {
+        let got = this.takeBuffered(channelId);
+        if (got.length || waitSeconds <= 0)
+            return got;
+        const cap = Math.min(waitSeconds, 50) * 1000;
+        await new Promise((resolve) => {
+            // review FATAL-3: one-shot guard — timer and ingestOnce both call wake();
+            // the first wins, the second is a no-op, preventing a late timer from
+            // splicing an unrelated waiter under a concurrent drain.
+            let fired = false;
+            let timer;
+            const wake = () => {
+                if (fired)
+                    return;
+                fired = true;
+                clearTimeout(timer);
+                const i = this.waiters.indexOf(wake);
+                if (i >= 0)
+                    this.waiters.splice(i, 1);
+                resolve();
+            };
+            timer = setTimeout(wake, cap);
+            this.waiters.push(wake);
+        });
+        return this.takeBuffered(channelId);
+    }
+    /** Notify-only SSE signal: fired after a buffer push. Listener pulls via takeBuffered. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Synchronous splice of buffered messages (all, or one channel). Shared by drain + SSE. */
+    takeBuffered(channelId) {
+        if (channelId === undefined)
+            return this.buffer.splice(0);
+        const keep = [];
+        const out = [];
+        for (const m of this.buffer)
+            (m.channel_id === channelId ? out : keep).push(m);
+        this.buffer.length = 0;
+        this.buffer.push(...keep);
+        return out;
+    }
+    /**
+     * Put messages back at the front (SSE/disconnect write-failure recovery).
+     *
+     * The re-buffered messages are older un-acked deliveries, so they go at the
+     * FRONT (oldest). A large un-acked backlog re-buffered on reconnect is exactly
+     * the OOM case Phase 1 item 4 targets, so this path is capped too. capBuffer()
+     * sheds from the front, preserving the newest maxBuffer messages across the
+     * combined [requeued-older..., existing-newer...] buffer.
+     */
+    requeueFront(msgs) {
+        if (msgs.length) {
+            this.buffer.unshift(...msgs);
+            this.capBuffer();
+        }
+    }
+    /**
+     * Poke subscribers + waiters to drain the buffer now. Used after a
+     * disconnect re-buffers un-acked messages so a still-connected consumer
+     * (e.g. a replacement WS) redelivers them without waiting for new inbound.
+     * Mirrors the notify tail of ingestOnce.
+     */
+    wakeListeners() {
+        for (const l of this.listeners)
+            l();
+        const w = this.waiters.splice(0);
+        for (const r of w)
+            r();
+    }
+    health() {
+        let joined = 0;
+        for (const s of this.joinState.values())
+            if (s === "JOINED")
+                joined++;
+        return {
+            status: "ok",
+            identity_id: this.cfg.identityId,
+            joined_channels: joined,
+            buffered: this.buffer.length,
+            dropped: this.droppedMessages,
+            filtered_room: this.filteredRoomMessages,
+            rate_limited: this.rateLimitedSends,
+            permanently_skipped: this.provider.permanentlySkippedCount(),
+            failed_attachments: this.failedAttachments,
+            uptime_s: this.startedAt ? Math.floor((Date.now() - this.startedAt) / 1000) : 0,
+            version: BRIDGE_VERSION,
+        };
+    }
+    /**
+     * Loopback observability snapshot served at GET /v1/metrics.
+     *
+     * `stages`: per-stage SecureComs-envelope latency percentiles (ms), measured
+     * locally and monotonically — send.encrypt / send.publish / send.total (the
+     * sender half) and recv.pull / recv.decrypt / recv.ack / recv.cycle (the
+     * recipient half). Excludes the agent's LLM time entirely.
+     *
+     * `errors` (ADR-0002): per-channel decrypt-error / stuck snapshot from the MLS
+     * provider, so a wedged channel is OBSERVABLE here instead of looking idle. A
+     * channel appears only once it has had a decrypt error; `stuck:true` means
+     * repeated failures with no intervening successful decrypt.
+     *
+     * `dropped` (Phase 1 item 4): cumulative count of inbound messages shed by the
+     * bounded-buffer cap. A daemon silently dropping messages under backpressure is
+     * exactly the blindness ADR-0002 eliminates, so the shed is surfaced here (and
+     * on health()) rather than swallowed.
+     *
+     * `filteredRoomMessages` (item 3 / ADR-0002 ethos): cumulative ROOM messages
+     * dropped by the @mention filter. A silently-filtered room message produces no
+     * other signal, so an agent correctly filtering 95% of room traffic would look
+     * identical to an idle/wedged one without this counter.
+     *
+     * `permanentlySkipped` (ADR-0002 ethos): cumulative count of inbound rows
+     * acked-and-dropped because they were provably past-epoch undecryptable
+     * (forward-secrecy secret gone), so a self-healed poison row is observable
+     * here instead of silently dropped.
+     */
+    metrics() {
+        return {
+            stages: this.latency.snapshot(),
+            errors: this.provider.errorStats(),
+            dropped: this.droppedMessages,
+            filteredRoomMessages: this.filteredRoomMessages,
+            rateLimitedSends: this.rateLimitedSends,
+            permanentlySkipped: this.provider.permanentlySkippedCount(),
+            welcomeRequestsSent: this.welcomeRequestsSent,
+            failedAttachments: this.failedAttachments,
+        };
+    }
+    async close() {
+        this.pingHandle?.close();
+        if (this.safetyTimer)
+            clearInterval(this.safetyTimer);
+        this.store.close(); // review SERIOUS-2: release the DatabaseSync handle/WAL
+    }
+}