@cotal-ai/core 0.36.0 → 0.38.0

package/dist/endpoint.js

@@ -13,7 +13,7 @@ import { liveKvEntries } from "./kv-scan.js";
 import { ARTIFACT_PART_KIND, isArtifactPart } from "./artifact.js";
 import { assertValidName } from "./resolve.js";
 import { createSpaceStreams, dmDurableConfig, dlvDurableConfig, taskDurableConfig, fanoutDurableConfig, inboxReaderConfig, MAX_MSGS_PER_SUBJECT, MANAGER_LEASE_TTL_MS, MANAGER_LEASE_ATTEMPT_MS } from "./streams.js";
-import { jetstream, jetstreamManager, AckPolicy, DeliverPolicy, } from "@nats-io/jetstream";
+import { jetstream, jetstreamManager, AckPolicy, DeliverPolicy, JetStreamApiCodes, JetStreamApiError, } from "@nats-io/jetstream";
 import {} from "@nats-io/jetstream";
 import { Kvm } from "@nats-io/kv";
 import { Bucket, KvWatchInclude } from "@nats-io/kv/internal";
@@ -31,7 +31,9 @@ export const DEFAULT_SPACE = "main";
  * "connection" ({ connected: boolean }) — true on every successful (re)bind (initial start, manual
  * reconnect, AND background self-heal), false the moment the connection drops (rebuild null window /
  * terminal close). Lets an in-process agent track connectedness off the endpoint's own (re)binds
- * instead of an imperative flag the self-heal path can't reach.
+ * instead of an imperative flag the self-heal path can't reach; "transport" ({ connected, server? })
+ * is the lower-level NATS socket edge, true before the full bind finishes and false during an internal
+ * nats.js reconnect without changing `connection` readiness.
  *
  * Callers MUST attach an "error" listener before `start()`: async faults (incl. NATS
  * permission denials, surfaced via `watchStatus`) are emitted as "error", and Node throws
@@ -105,6 +107,12 @@ export class CotalEndpoint extends EventEmitter {
     jsm;
     kv;
     channelKv;
+    /** The presence/channel-registry watches' own handles. Each is an ORDERED push consumer: its idle
+     *  heartbeat monitor lives on a JS timer independent of the connection, so a drain that doesn't
+     *  `.stop()` it first leaves the monitor to fire into a closing connection every 30s, throwing
+     *  `DrainingConnectionError` out of `reset()` on a timer nothing awaits. */
+    presenceWatchIter;
+    channelWatchIter;
     /** Plane-3 durable-membership registry KV — lazily opened by the privileged delivery daemon (or a
      *  short-lived provisioner). */
     membersKv;
@@ -177,6 +185,15 @@ export class CotalEndpoint extends EventEmitter {
     roster = new Map();
     /** Resolves when the current presence watch has consumed its complete initial KV snapshot. */
     presenceSnapshot = Promise.resolve();
+    /**
+     * Observer-local age of the last presence-KV delivery (any key, including DEL/PURGE). Distinct
+     * from each peer's `ts`: that is the publisher's heartbeat. Whole-bucket silence past TTL is
+     * the observer going deaf, not  N  simultaneous deaths, and sweep must not treat it as the
+     * latter (#1045).
+     */
+    lastPresenceWatchAt = 0;
+    /** Last emitted presence-view freshness. Suppresses duplicate `presence-view` events. */
+    presenceViewFresh = true;
     status = "idle";
     activity;
     /** Mirror of the connector's authoritative attention state, published in presence (advisory). The
@@ -371,10 +388,15 @@ export class CotalEndpoint extends EventEmitter {
     }
     async start() {
         await this.connectAndBind();
-        // nats.js auto-reconnects transient drops; when it exhausts its attempts and the
-        // connection closes for good, rebuild from scratch so an in-process agent (e.g. the
-        // OpenCode plugin) recovers without a host respawn. Armed only after a successful first
-        // connect — a first-connect failure throws to the caller's connect-retry loop instead.
+        // stop() can finish while the INITIAL connectAndBind is still awaiting its broker work. The
+        // rebuild path already closes that race; initial start needs the same fence or the late bind
+        // leaves a fresh nc, heartbeat, consumers, and presence live on an endpoint already stopped.
+        // superviseConnection below: nats.js auto-reconnects transient drops, and when it exhausts its
+        // attempts and the connection closes for good we rebuild from scratch, so an in-process agent
+        // (e.g. the OpenCode plugin) recovers without a host respawn. Armed only after a successful
+        // first connect; a first-connect failure throws to the caller's connect-retry loop instead.
+        if (await this.tearDownIfStopped())
+            return;
         this.superviseConnection();
     }
     /** How far ahead of the current bearer's `exp` a refresh fires, and how soon a FAILED refresh
@@ -382,9 +404,17 @@ export class CotalEndpoint extends EventEmitter {
      *  so whatever `currentBearer` holds is what every attempt presents). */
     static BEARER_REFRESH_MARGIN_MS = 60_000;
     static BEARER_RETRY_MS = 15_000;
+    /**
+     * A condition the endpoint is already surviving. Node rethrows `error` when no listener is
+     * attached, so emitting retry notices on `error` killed hosts that the endpoint intended to
+     * keep running (#891). `warning` is observable and never fatal without a listener.
+     */
+    emitRecoverable(err) {
+        this.emit("warning", err);
+    }
     /** Fetch a fresh bearer from the source, pin its principal to ours, arm the next refresh. On a
      *  fetch/principal failure: THROWS when `initial` (start() must fail loud before first connect);
-     *  otherwise emits "error" and retries — the live connection keeps working until its current JWT
+     *  otherwise emits "warning" and retries — the live connection keeps working until its current JWT
      *  expiry, so a dead auth service is loud without instantly dropping the mesh. */
     async refreshBearer(initial = false) {
         try {
@@ -398,7 +428,7 @@ export class CotalEndpoint extends EventEmitter {
         catch (e) {
             if (initial)
                 throw e;
-            this.emit("error", new Error(`bearer refresh failed (${e instanceof Error ? e.message : String(e)}) - retrying; this connection dies at its current token's expiry if the auth service stays down`));
+            this.emitRecoverable(new Error(`bearer refresh failed (${e instanceof Error ? e.message : String(e)}) - retrying; this connection dies at its current token's expiry if the auth service stays down`));
             this.armBearerRefresh(CotalEndpoint.BEARER_RETRY_MS);
         }
     }
@@ -466,7 +496,7 @@ export class CotalEndpoint extends EventEmitter {
         catch (e) {
             if (initial)
                 throw e;
-            this.emit("error", new Error(`creds refresh failed (${e instanceof Error ? e.message : String(e)}) - retrying; this connection dies at its current JWT's expiry if renewal keeps failing`));
+            this.emitRecoverable(new Error(`creds refresh failed (${e instanceof Error ? e.message : String(e)}) - retrying; this connection dies at its current JWT's expiry if renewal keeps failing`));
             this.armCredsRefresh(CotalEndpoint.CREDS_RETRY_MS);
         }
     }
@@ -546,7 +576,7 @@ export class CotalEndpoint extends EventEmitter {
             await this.swapConnectionOntoFreshCreds();
         }
         catch (e) {
-            this.emit("error", new Error(`creds refresh failed (${e instanceof Error ? e.message : String(e)}) - retrying; this connection dies at its current JWT's expiry if renewal keeps failing`));
+            this.emitRecoverable(new Error(`creds refresh failed (${e instanceof Error ? e.message : String(e)}) - retrying; this connection dies at its current JWT's expiry if renewal keeps failing`));
             this.armCredsRefresh(CotalEndpoint.CREDS_RETRY_MS);
         }
     }
@@ -633,6 +663,11 @@ export class CotalEndpoint extends EventEmitter {
             throw new Error(this.bearerSource
                 ? "this endpoint's user bearer has expired and renewal through the auth exchange is failing - not presenting the expired token to the broker; retrying with backoff"
                 : "this endpoint's user bearer has expired and it holds no bearer source to renew it - re-authenticate and rebuild the endpoint (construct it with a bearer FUNCTION for standing renewal)");
+        const credsExp = this.currentCreds && credsClaims(this.currentCreds).exp;
+        if (typeof credsExp === "number" && credsExp * 1000 <= Date.now())
+            throw new Error(this.credsSource
+                ? "this endpoint's creds have expired and renewal is failing - not presenting the expired credential to the broker; retrying with backoff"
+                : "this endpoint's creds have expired and it holds no creds source to renew them - replace the credential and rebuild the endpoint (pass a creds FUNCTION for standing renewal)");
         this.nc = await dialerFor(this.servers)({
             servers: this.servers,
             // In USER MODE the connection `name` carries the client-chosen inbox nonce (= connId) the callout
@@ -719,7 +754,7 @@ export class CotalEndpoint extends EventEmitter {
         if (this.doRegister) {
             await this.publishPresence();
             this.heartbeatTimer = setInterval(() => {
-                this.publishPresence().catch((e) => this.emit("error", e));
+                this.publishPresence().catch((e) => this.emitRecoverable(e));
             }, this.heartbeatMs);
         }
         // Caller-owned membership watches are INTENT rather than one-connection iterators. Re-open them
@@ -731,6 +766,20 @@ export class CotalEndpoint extends EventEmitter {
         await this.armPlane3();
         // Bound and live — covers initial start, manual reconnect, AND background self-heal (every
         // path lands here). The single signal an in-process agent's connected flag tracks.
+        //
+        // The stopped guard: stop() can land in any await above. Both callers tear the fresh
+        // connection back down (tearDownIfStopped), but an event has no undo, so a late
+        // `connection: true` would be the last edge a listener ever sees on a stopped endpoint and
+        // nothing follows it to correct the record. It belongs here rather than in a consumer because
+        // every listener reads the same edge; MeshAgent carries its own `stopping` guard and so was
+        // never the one exposed, which is the point.
+        //
+        // Measured for the start() caller by the broker suite's mid-bind cell. doRebuild is
+        // also measured, by a separate cell that holds the rebuild's connectAndBind at
+        // armPlane3 after a successful first bind and lands stop() in that window (#1028).
+        // Shared-line reasoning is no longer the rebuild proof.
+        if (this.stopped)
+            return;
         this.emit("connection", { connected: true });
     }
     /** Tear down everything {@link connectAndBind} (re)creates, so a rebind can't leak a
@@ -754,6 +803,20 @@ export class CotalEndpoint extends EventEmitter {
             }
         }
         this.streamMsgs.length = 0;
+        try {
+            this.presenceWatchIter?.stop();
+        }
+        catch {
+            /* already closed with the connection */
+        }
+        this.presenceWatchIter = undefined;
+        try {
+            this.channelWatchIter?.stop();
+        }
+        catch {
+            /* already closed with the connection */
+        }
+        this.channelWatchIter = undefined;
         for (const sub of this.chatSubs.values()) {
             try {
                 sub.unsubscribe();
@@ -766,11 +829,13 @@ export class CotalEndpoint extends EventEmitter {
         this.chatSubDenied.clear();
         this.confirmingChatSubs.clear();
         this.roster.clear();
+        this.lastPresenceWatchAt = 0;
+        this.presenceViewFresh = true;
         this.joinSeq.clear();
         this.channelConfigs.clear();
         this.channelDefaults = {};
         for (const watch of this.membershipFeedWatches)
-            watch.arm = watch.arm.catch(() => { }).then(() => this.disarmMembershipWatch(watch));
+            watch.arm = watch.arm.catch(() => { }).then(() => this.disarmMembershipWatch(watch)).catch((err) => { this.emit("error", err); });
     }
     /** If stop() ran during a rebuild's `await connectAndBind`, the just-bound connection +
      *  heartbeat + supervisor would be left live on a stopped endpoint. Tear that fresh
@@ -806,7 +871,10 @@ export class CotalEndpoint extends EventEmitter {
                 return;
             if (this.nc !== nc)
                 return; // epoch-stale — a rebuild already swapped this connection
-            this.emit("connection", { connected: false }); // dropped — report it before the rebuild kicks in
+            // ORDER IS PART OF THE DIAGNOSTIC CONTRACT. MeshAgent retains endpoint errors only while it is
+            // not bound, so readiness must turn false before the matching terminal-close error is emitted.
+            // Reversing these two lines silently loses the only post-drop reason an agent can report.
+            this.emit("connection", { connected: false });
             this.emit("error", new Error(`mesh connection closed${err ? `: ${err.message}` : ""} - re-establishing`));
             void this.reestablishLoop();
         });
@@ -853,7 +921,11 @@ export class CotalEndpoint extends EventEmitter {
             // The manager's liveness-lease handle too: left bound to the old connection, every renew and
             // re-read after a reconnect times out, and the manager reports its lease unknown for good.
             this.managerLeaseKv = undefined;
-            this.emit("connection", { connected: false }); // null window opened — not live until the rebind below
+            // This is an application-requested epoch teardown, not a transient nats.js blip. The old
+            // status iterator is now stale by construction and its close is epoch-dropped, so this line is
+            // the authoritative raw-liveness edge for the no-nc window until the new watcher seeds true.
+            this.emit("transport", { connected: false });
+            this.emit("connection", { connected: false });
             try {
                 await oldNc?.drain();
             }
@@ -864,9 +936,10 @@ export class CotalEndpoint extends EventEmitter {
             // stop() may have run during the await — don't leave a live connection + heartbeat +
             // supervisor on a stopped endpoint. (Reads this.nc in its own scope — a bare `this.nc`
             // here in doRebuild narrows to `never` via TS inlining connectAndBind's assignment.)
+            // Re-arm on the fresh nc only after this stopped fence accepts it.
             if (await this.tearDownIfStopped())
                 return;
-            this.superviseConnection(); // re-arm on the fresh nc
+            this.superviseConnection();
         }
         finally {
             this.reconnecting = false;
@@ -902,7 +975,7 @@ export class CotalEndpoint extends EventEmitter {
                 }
                 catch (e) {
                     if (!this.stopped)
-                        this.emit("error", e);
+                        this.emitRecoverable(e);
                     const delay = this.nextRetryDelayMs();
                     await new Promise((resolve) => {
                         this.backoffResolve = resolve;
@@ -984,6 +1057,20 @@ export class CotalEndpoint extends EventEmitter {
                 /* already closed */
             }
         }
+        try {
+            this.presenceWatchIter?.stop();
+        }
+        catch {
+            /* already closed */
+        }
+        this.presenceWatchIter = undefined;
+        try {
+            this.channelWatchIter?.stop();
+        }
+        catch {
+            /* already closed */
+        }
+        this.channelWatchIter = undefined;
         try {
             if (this.doRegister) {
                 this.status = "offline";
@@ -1520,6 +1607,22 @@ export class CotalEndpoint extends EventEmitter {
     getRoster() {
         return [...this.roster.values()].sort((a, b) => a.card.name.localeCompare(b.card.name));
     }
+    /**
+     * Freshness of THIS observer's presence watch, not of any peer. `fresh: false` means the
+     * whole bucket has been silent past the liveness window — the view is stale as of
+     * `staleSince`, and {@link getRoster} is last-known rather than a current offline verdict.
+     * A watch that has not yet delivered anything is not stale (there is no T to name).
+     */
+    presenceView() {
+        if (!this.doWatch)
+            return { fresh: true };
+        if (this.lastPresenceWatchAt === 0)
+            return { fresh: true };
+        const staleSince = this.lastPresenceWatchAt + this.ttlMs;
+        if (Date.now() < staleSince)
+            return { fresh: true };
+        return { fresh: false, staleSince };
+    }
     /** Wait until the current presence watch has consumed its initial KV snapshot. An empty bucket
      * emits no watch entry, so the timeout keeps a genuinely empty mesh bounded. */
     async waitForPresenceSnapshot(timeoutMs = 1_000) {
@@ -1723,8 +1826,12 @@ export class CotalEndpoint extends EventEmitter {
                 }
             }
         }
-        catch {
-            /* stream missing — fall through to registry-only channels */
+        catch (e) {
+            // A genuinely absent CHAT stream means there are no retained message counts yet. Every other
+            // failure, especially a STREAM.INFO permission denial, means the count view could not be read
+            // and must stay loud rather than returning a valid-looking registry-only subset.
+            if (!isJetStreamMissing(e, JetStreamApiCodes.StreamNotFound))
+                throw e;
         }
         const channels = new Set([...counts.keys(), ...this.channelConfigs.keys()]);
         return [...channels]
@@ -1950,11 +2057,18 @@ export class CotalEndpoint extends EventEmitter {
                     watch.consumerName = undefined;
                 }
                 else {
-                    // A timeout is deferred only for an epoch that is actually closing/rebuilding; live timeouts stay loud.
                     const closedEpoch = err.name === "ClosedConnectionError" || /^closed connection$/i.test(err.message);
-                    const dyingEpochTimeout = /timeout/i.test(err.message) && (this.reconnecting || !this.nc || this.nc.isClosed());
-                    if (!closedEpoch && !dyingEpochTimeout)
+                    const timeout = err.name === "TimeoutError" || /timeout/i.test(err.message);
+                    const dyingEpochTimeout = timeout && (this.reconnecting || !this.nc || this.nc.isClosed());
+                    // Cleanup of an ordered consumer: a delete timeout means the broker did not answer in time,
+                    // not that the endpoint is unusable. The broker reaps an idle/ephemeral consumer anyway.
+                    // Throwing here killed a live observer over a slow VPN (#1047). Catch, surface, continue.
+                    if (timeout || closedEpoch || dyingEpochTimeout) {
+                        this.emit("error", err);
+                    }
+                    else {
                         throw err;
+                    }
                 }
                 // A terminal close leaves stream/name intact. The endpoint-owned stopped intent is retried
                 // through the fresh JetStream manager before its public stop promise may resolve.
@@ -1981,10 +2095,11 @@ export class CotalEndpoint extends EventEmitter {
             }
         }));
     }
-    /** Fetch recent messages from a channel's JetStream backlog. */
+    /** Fetch recent messages from a channel's JetStream backlog. `signal` cancels the active pull and
+     *  reclaims its ephemeral consumer before the promise rejects. */
     async channelHistory(channel, opts) {
         // history from any sender
-        return this.streamHistory(chatStream(this.space), chatSubject(this.space, "*", "*", channel), opts?.limit ?? 100);
+        return this.streamHistory(chatStream(this.space), chatSubject(this.space, "*", "*", channel), opts?.limit ?? 100, undefined, opts?.signal);
     }
     /** Read a channel's recent history THROUGH THE DELIVERY DAEMON instead of through a consumer this
      *  connection creates itself — the mediated read of SPEC's "Mediated reads (normative)" rule (no raw
@@ -2025,12 +2140,13 @@ export class CotalEndpoint extends EventEmitter {
             throw new Error("readHistory: the delivery daemon returned a malformed page (expected { items, complete })");
         return { items: data.items, complete: data.complete };
     }
-    /** Fetch recent DMs (any sender→any recipient) from the space's DM backlog. God-view only:
+    /** Fetch recent DMs (any sender→any recipient) from the space's DM backlog. `signal` cancels the
+     *  active pull and reclaims its ephemeral consumer. God-view only:
      *  a normal agent/observer's ACL denies CONSUMER.CREATE on DM_<space>, so this throws-and-
      *  skips for them — only an `admin`-profile cred can read it. */
     async dmHistory(opts) {
         // every inst.<recipOwner>.<recipActor>.<sndOwner>.<sndActor> DM — the whole DM subtree (god-view)
-        return this.streamHistory(dmStream(this.space), `${spacePrefix(this.space)}.inst.>`, opts?.limit ?? 100);
+        return this.streamHistory(dmStream(this.space), `${spacePrefix(this.space)}.inst.>`, opts?.limit ?? 100, undefined, opts?.signal);
     }
     /**
      * The `limit` MOST RECENT messages matching `subject`, oldest-first within the page.
@@ -2048,14 +2164,17 @@ export class CotalEndpoint extends EventEmitter {
      * A filtered subject's sequences are non-contiguous (other channels interleave in the same
      * stream), so the window cannot be computed arithmetically. A FAILED attempt holds fewer than a
      * page by definition, so wasted transfer stays page-sized and geometric growth keeps the number of
-     * attempts logarithmic. The one unbounded case is named in the body: a channel whose matches are
-     * all old and sparse walks back to the start of the stream and reads its whole retained set.
+     * attempts logarithmic. A channel with fewer than `limit` matches used to keep widening until
+     * sequence 1 and drain the stream's whole retained set (#840). The walk now stops at the
+     * subject's FIRST matching sequence (the mirror of the last-matching ceiling), probed on the
+     * same CREATE surface, and only after a short drain so a dense page never pays for the floor.
      *
      * `before` pages toward the past: pass the `seq` of the oldest message you already have.
      */
-    async streamHistory(stream, subject, limit, before) {
+    async streamHistory(stream, subject, limit, before, signal) {
         if (!this.nc)
             throw new Error("endpoint not started");
+        signal?.throwIfAborted();
         // A LIMIT THAT IS NOT A FINITE NUMBER HAS NO ANSWER, AND THE SEARCH BELOW CANNOT REFUSE IT.
         // Every comparison against NaN is false, so `limit <= 0` does not fire for one, and neither of
         // the widening loop's exits can ever be true either: `page.length >= NaN` is false forever and
@@ -2091,7 +2210,7 @@ export class CotalEndpoint extends EventEmitter {
             // Deliberately NOT `getMessage({ last_by_subj })`, which would be the obvious way to ask: it
             // needs `$JS.API.STREAM.MSG.GET`, which read credentials do not hold. That grant hole already
             // shipped once from this function and turned every non-admin history read into an empty list.
-            const ceiling = before !== undefined ? before - 1 : await this.lastMatchingSeq(js, stream, subject);
+            const ceiling = before !== undefined ? before - 1 : await this.lastMatchingSeq(js, stream, subject, signal);
             if (ceiling < 1)
                 return [];
             // Widen from the exact ceiling until a window holds a full page, or until the window IS the
@@ -2100,17 +2219,28 @@ export class CotalEndpoint extends EventEmitter {
             // Geometric growth keeps the number of attempts logarithmic, so total wasted transfer is a
             // small multiple of a page.
             //
-            // NAMED POLICY for the remaining case: when a channel's matches are all old and sparse, the
-            // search walks back to sequence 1 and the final drain transfers that subject's whole retained
-            // set. That is chosen deliberately — a FULL page of genuinely recent messages, at the cost of
-            // an unbounded read on a channel that has not been used in a long time — over returning a
-            // short page while older messages exist. The exact ceiling above means this is now reached
-            // only by real sparsity WITHIN a channel, never by the channel simply being quiet lately.
+            // A SHORT PAGE is either "the channel is exhausted" or "the window is still above the
+            // first match". Sequence 1 is the wrong floor for the first of those: three matches at
+            // the high end of a busy stream are exhausted as soon as the window's lower edge passes
+            // the subject's first matching sequence, and walking on to 1 re-reads everyone else's
+            // retained set (#840). Probe that floor only after a short drain so a dense page (one
+            // drain, full) never pays for it. The remaining unbounded-looking case is a subject
+            // whose FIRST match really is near sequence 1; that span is the channel's own, not the
+            // stream's.
             let span = Math.max(limit * 4, 64);
+            let floor = 1;
+            let floorKnown = false;
             for (;;) {
-                const start = Math.max(1, ceiling - span + 1);
-                const page = await this.drainWindow(js, stream, subject, start, ceiling);
-                if (page.length >= limit || start === 1)
+                signal?.throwIfAborted();
+                const start = Math.max(floor, ceiling - span + 1);
+                const page = await this.drainWindow(js, stream, subject, start, ceiling, limit, signal);
+                if (page.length >= limit)
+                    return page.slice(-limit);
+                if (!floorKnown) {
+                    floor = Math.max(1, await this.firstMatchingSeq(js, stream, subject, signal));
+                    floorKnown = true;
+                }
+                if (start <= floor)
                     return page.slice(-limit);
                 span *= 4;
             }
@@ -2144,7 +2274,51 @@ export class CotalEndpoint extends EventEmitter {
      *  (available from the create, before anything is delivered) is 0 for an empty subject, and
      *  otherwise one message carries the sequence. Same CREATE/INFO/NEXT/DELETE surface `drainWindow`
      *  already uses, so no broker authority is added. */
-    async lastMatchingSeq(js, stream, subject) {
+    /** The oldest stream sequence matching `subject`, or 0 when the subject has no messages.
+     *  Mirror of {@link lastMatchingSeq}: same CREATE/INFO/NEXT/DELETE surface, `DeliverPolicy.All`
+     *  instead of `Last`, first delivered seq instead of last. Read credentials already hold this. */
+    async firstMatchingSeq(js, stream, subject, signal) {
+        signal?.throwIfAborted();
+        const consumer = await js.consumers.get(stream, {
+            filter_subjects: [subject],
+            deliver_policy: DeliverPolicy.All,
+        });
+        try {
+            if ((await consumer.info(true)).num_pending === 0)
+                return 0;
+            signal?.throwIfAborted();
+            const iter = await consumer.fetch({ max_messages: 1 });
+            const stop = () => iter.stop(abortReason(signal));
+            signal?.addEventListener("abort", stop, { once: true });
+            try {
+                signal?.throwIfAborted();
+                for await (const m of iter)
+                    return m.seq;
+            }
+            finally {
+                signal?.removeEventListener("abort", stop);
+                iter.stop();
+            }
+            throw new Error(`history: the broker reported messages on ${subject} but delivered none - the read was cut short, not empty`);
+        }
+        finally {
+            try {
+                await consumer.delete();
+            }
+            catch (e) {
+                if (!isJetStreamMissing(e, JetStreamApiCodes.ConsumerNotFound))
+                    throw e;
+            }
+        }
+    }
+    /** The newest stream sequence matching `subject`, or 0 when the subject has no messages.
+     *
+     *  One ordered consumer at `DeliverPolicy.Last` with this subject's filter: its `num_pending`
+     *  (available from the create, before anything is delivered) is 0 for an empty subject, and
+     *  otherwise one message carries the sequence. Same CREATE/INFO/NEXT/DELETE surface `drainWindow`
+     *  already uses, so no broker authority is added. */
+    async lastMatchingSeq(js, stream, subject, signal) {
+        signal?.throwIfAborted();
         const consumer = await js.consumers.get(stream, {
             filter_subjects: [subject],
             deliver_policy: DeliverPolicy.Last,
@@ -2153,9 +2327,19 @@ export class CotalEndpoint extends EventEmitter {
             // Bind-time zero is the ONLY thing that means "this subject has no messages".
             if ((await consumer.info(true)).num_pending === 0)
                 return 0;
+            signal?.throwIfAborted();
             const iter = await consumer.fetch({ max_messages: 1 });
-            for await (const m of iter)
-                return m.seq;
+            const stop = () => iter.stop(abortReason(signal));
+            signal?.addEventListener("abort", stop, { once: true });
+            try {
+                signal?.throwIfAborted();
+                for await (const m of iter)
+                    return m.seq;
+            }
+            finally {
+                signal?.removeEventListener("abort", stop);
+                iter.stop();
+            }
             // Bind said a message was pending and none arrived. The pinned client's pull iterator ends
             // CLEANLY when the connection closes ("we don't propagate the error here"), so this is what a
             // dropped link looks like from here. Returning 0 would make the caller report an empty
@@ -2164,14 +2348,21 @@ export class CotalEndpoint extends EventEmitter {
             throw new Error(`history: the broker reported messages on ${subject} but delivered none - the read was cut short, not empty`);
         }
         finally {
-            await consumer.delete().catch(() => { });
+            try {
+                await consumer.delete();
+            }
+            catch (e) {
+                if (!isJetStreamMissing(e, JetStreamApiCodes.ConsumerNotFound))
+                    throw e;
+            }
         }
     }
     /** Drain every message matching `subject` with sequence in `[start, ceiling]`, oldest-first.
      *  One ephemeral ordered consumer, one batched pull — `AckPolicy.None`, so no per-message ack
      *  round trip. Fetches exactly the pending count so it returns as soon as the window is
      *  delivered rather than blocking for the pull's full expiry. */
-    async drainWindow(js, stream, subject, start, ceiling) {
+    async drainWindow(js, stream, subject, start, ceiling, limit, signal) {
+        signal?.throwIfAborted();
         const out = [];
         const consumer = await js.consumers.get(stream, { filter_subjects: [subject], opt_start_seq: start });
         try {
@@ -2180,36 +2371,51 @@ export class CotalEndpoint extends EventEmitter {
             const pending = (await consumer.info(true)).num_pending;
             if (pending === 0)
                 return out;
-            const iter = await consumer.fetch({ max_messages: pending });
+            signal?.throwIfAborted();
+            // Keep only a small rolling buffer in flight. Stopping a client iterator cannot unsend bytes the
+            // broker already committed to that pull request, so fetching the whole page let an aborted history
+            // read keep filling a constrained shared connection and starve the next dashboard poll. `consume`
+            // replenishes this bounded buffer as it is read, so large pages still complete without committing
+            // all of their bytes to the connection up front.
+            const iter = await consumer.consume({ max_messages: Math.min(pending, 32) });
+            const stop = () => iter.stop(abortReason(signal));
+            signal?.addEventListener("abort", stop, { once: true });
             // PROVE THE WINDOW COMPLETED. The pull iterator ends cleanly on a dropped connection, so a
             // close after three of ten deliveries would otherwise return a convincing three-message page.
             // The window is done when we have reached its upper bound or consumed everything bind said
             // was pending; anything else is a cut-short read and must say so.
             let delivered = 0;
             let complete = false;
-            for await (const m of iter) {
-                delivered++;
-                if (m.seq >= ceiling) { // reached the page's upper bound
-                    if (m.seq === ceiling) {
-                        try {
-                            out.push(m.json());
+            try {
+                signal?.throwIfAborted();
+                for await (const m of iter) {
+                    delivered++;
+                    if (m.seq >= ceiling) { // reached the page's upper bound
+                        if (m.seq === ceiling) {
+                            try {
+                                out.push(m.json());
+                            }
+                            catch { /* skip undecodable */ }
                         }
-                        catch { /* skip undecodable */ }
+                        complete = true;
+                        break;
+                    }
+                    try {
+                        out.push(m.json());
+                        if (out.length > limit)
+                            out.shift();
+                    }
+                    catch { /* skip undecodable */ }
+                    if (delivered >= pending) {
+                        complete = true;
+                        break;
                     }
-                    complete = true;
-                    break;
-                }
-                try {
-                    out.push(m.json());
-                }
-                catch {
-                    /* skip undecodable */
-                }
-                if (delivered >= pending) {
-                    complete = true;
-                    break;
                 }
             }
+            finally {
+                signal?.removeEventListener("abort", stop);
+                iter.stop();
+            }
             if (!complete)
                 throw new Error(`history: read ${delivered} of ${pending} messages on ${subject} before the stream ended early - the window was cut short, not empty`);
             return out;
@@ -2220,7 +2426,13 @@ export class CotalEndpoint extends EventEmitter {
             // up to eight per call, the dashboard makes one call per channel, and a reload repeats it.
             // Left alone that accumulates consumers on the broker until the thresholds expire, and the
             // resulting resource exhaustion would land in streamHistory's catch and read as empty history.
-            await consumer.delete().catch(() => { });
+            try {
+                await consumer.delete();
+            }
+            catch (e) {
+                if (!isJetStreamMissing(e, JetStreamApiCodes.ConsumerNotFound))
+                    throw e;
+            }
         }
     }
     // ---- internals -----------------------------------------------------------
@@ -2232,10 +2444,27 @@ export class CotalEndpoint extends EventEmitter {
      * denial is never mistaken for absence (which already has a benign cause: MCP reconnect).
      */
     watchStatus() {
-        if (!this.nc)
+        const nc = this.nc;
+        if (!nc)
             return;
         void (async () => {
-            for await (const s of this.nc.status()) {
+            for await (const s of nc.status()) {
+                // A rebuild can replace `this.nc` before the old iterator finishes. Late disconnect/close
+                // from that old epoch says nothing about the replacement and must not flip its liveness.
+                if (this.nc !== nc)
+                    continue;
+                if (s.type === "disconnect") {
+                    this.emit("transport", { connected: false, server: s.server });
+                    continue;
+                }
+                if (s.type === "reconnect") {
+                    this.emit("transport", { connected: true, server: s.server });
+                    continue;
+                }
+                if (s.type === "close") {
+                    this.emit("transport", { connected: false });
+                    continue;
+                }
                 if (s.type !== "error")
                     continue;
                 // Suppress the EXPECTED permission violation from a manager-free join we're confirming: an
@@ -2246,9 +2475,24 @@ export class CotalEndpoint extends EventEmitter {
                 this.emit("error", describeStatusError(s.error));
             }
         })().catch((e) => {
-            if (!this.stopped)
+            // Defensive symmetry with the reachable in-loop epoch guard above. Measured against five real
+            // broker loss/reconnect/terminal-close cycles on pinned nats.js 3.4.0: status iterators ended
+            // normally and this catch never fired. Keep an old epoch from surfacing an error if a runtime or
+            // future client version can reject here, but do not treat this as a currently reachable edge.
+            if (!this.stopped && this.nc === nc)
                 this.emit("error", e);
         });
+        // The transport is already live when connect() returns, while the Cotal bind below is still in
+        // progress. Seed this contract explicitly rather than requiring consumers to combine it with the
+        // later, differently-scoped `connection:true` event.
+        //
+        // The same stopped race as the readiness emit at the end of connectAndBind, and it reaches here
+        // FIRST: connectAndBind calls watchStatus right after the dial, so a stop() landing while the
+        // dial is still pending has this seed fire on an endpoint that is already stopped. Measured
+        // through a real pending dial, a stopped endpoint announced a live transport it never had.
+        if (this.stopped)
+            return;
+        this.emit("transport", { connected: true, server: nc.getServer() });
     }
     /** The error message for a guard that finds the endpoint unbound: "reconnecting" during a
      *  rebuild's null window OR an inter-retry backoff (so a concurrent op reports the real
@@ -2309,7 +2553,11 @@ export class CotalEndpoint extends EventEmitter {
             await jsm.consumers.info(stream, name);
             return; // this lifecycle's durable exists — keep its original frontier
         }
-        catch { /* absent; create below */ }
+        catch (e) {
+            if (!isJetStreamMissing(e, JetStreamApiCodes.ConsumerNotFound))
+                throw e;
+            // Genuinely absent consumer: create it below. A denial is not absence.
+        }
         const frontier = (await jsm.streams.info(stream)).state.last_seq;
         try {
             await jsm.consumers.add(stream, dmDurableConfig(this.space, owner, actor, lifecycleUid, { ...opts, activationFrontier: frontier }));
@@ -2321,7 +2569,13 @@ export class CotalEndpoint extends EventEmitter {
                 await jsm.consumers.info(stream, name);
                 return;
             }
-            catch { /* not a lost race */ }
+            catch (probeError) {
+                // The probe never creates a successful result: it either proves the concurrent winner above,
+                // or the original create failure stays authoritative. Preserve a denial from the probe because
+                // it names the missing capability more accurately than an unrelated create conflict.
+                if (isPermissionDenied(probeError))
+                    throw probeError;
+            }
             throw e;
         }
     }
@@ -2443,7 +2697,10 @@ export class CotalEndpoint extends EventEmitter {
         try {
             await (await this.deliveryRegistry()).delete(leaseKey(shardIndex));
         }
-        catch { /* already gone */ }
+        catch {
+            // Intentionally best-effort for EVERY failure: the lease TTL is the crash-safe release authority,
+            // and clean shutdown must continue even when the broker is already gone or draining.
+        }
     }
     /** Read a shard's delivery lease (the daemon-availability signal), or `undefined` if none is live.
      *  READ-ONLY surface — drives Component 6's `cotal_channels` delivery-health field (an agent reads it
@@ -2486,6 +2743,9 @@ export class CotalEndpoint extends EventEmitter {
                 this.managerLeaseKv = await kvm.create(managerBucket(this.space), { ttl: MANAGER_LEASE_TTL_MS });
             }
             catch {
+                // OPEN mode has no broker ACLs, so a permission denial is impossible here. `create` is only
+                // the ensure-exists attempt; `open` below is the authority after either a pre-existing bucket
+                // or a create race, and it still throws if the bucket cannot actually be used.
                 this.managerLeaseKv = await kvm.open(managerBucket(this.space));
             }
         }
@@ -2531,7 +2791,10 @@ export class CotalEndpoint extends EventEmitter {
             else
                 await kv.delete(managerLeaseKey(instanceId), { previousSeq: revision });
         }
-        catch { /* not ours / already gone */ }
+        catch {
+            // Intentionally best-effort for EVERY failure: a revision mismatch means the lease is no longer
+            // ours, while a broker failure is recovered by the bucket TTL. Shutdown must not claim deletion.
+        }
     }
     /** Read a live manager liveness lease, or undefined if NONE (no manager instance holds the space). A
      *  presence/existence check for the CLI's `spawn -f` reuse and `waitLeaseGone`, which only need "is any
@@ -2567,9 +2830,19 @@ export class CotalEndpoint extends EventEmitter {
                 // it returns that instance's latest state, so a DEL here retires only its own key. The
                 // defect was asking one wildcard for the newest message in the whole subtree, where a
                 // stopping peer's tombstone outranks a live sibling's older PUT.
-                const m = await jsm.streams.getMessage(stream, { last_by_subj: subject }).catch(() => null);
+                let m;
+                try {
+                    m = await jsm.streams.getMessage(stream, { last_by_subj: subject });
+                }
+                catch (e) {
+                    if (e.code === JetStreamApiCodes.NoMessageFound)
+                        continue;
+                    throw e;
+                }
                 if (m === null)
                     continue; // key vanished between INFO and GET: it is not a live holder
+                // A 10037 above means the key vanished between INFO and GET: it is not a live holder. A
+                // denial or failed read is not absence and is rethrown.
                 const op = m.header?.get("KV-Operation");
                 if (op === "DEL" || op === "PURGE" || m.data.length === 0)
                     continue;
@@ -2752,10 +3025,7 @@ export class CotalEndpoint extends EventEmitter {
         // delete/recreate a predecessor's in-flight catch-up consumer — the uid disambiguates.
         const cuP = parsePrincipalKey(owner);
         const name = `cu_${cuP ? lifecycleNameKey(cuP.owner, cuP.actor, lifecycleUid) : `${token(owner)}-${lifecycleUid}`}_${generation}`;
-        try {
-            await this.jsm.consumers.delete(chatStream(this.space), name);
-        }
-        catch { /* none */ }
+        await this.deleteConsumerIfPresent(chatStream(this.space), name);
         await this.jsm.consumers.add(chatStream(this.space), {
             name, filter_subject: subject, ack_policy: AckPolicy.None, mem_storage: true,
             inactive_threshold: nanos(30_000), deliver_policy: DeliverPolicy.StartSequence, opt_start_seq: fromSeqExcl + 1,
@@ -2791,10 +3061,7 @@ export class CotalEndpoint extends EventEmitter {
             }
         }
         finally {
-            try {
-                await this.jsm.consumers.delete(chatStream(this.space), name);
-            }
-            catch { /* gone */ }
+            await this.deleteConsumerIfPresent(chatStream(this.space), name);
         }
         return { copied, evicted };
     }
@@ -3155,10 +3422,9 @@ export class CotalEndpoint extends EventEmitter {
     async runFanout() {
         if (!this.js || !this.jsm)
             return;
-        try {
-            await this.jsm.consumers.add(chatStream(this.space), fanoutDurableConfig(this.space, { ackWaitMs: this.ackWaitMs }));
-        }
-        catch { /* exists */ }
+        // Named consumer creation is idempotent for the same config. A denial must not be mistaken for
+        // "already exists"; let the broker response decide and propagate every failure.
+        await this.jsm.consumers.add(chatStream(this.space), fanoutDurableConfig(this.space, { ackWaitMs: this.ackWaitMs }));
         const consumer = await this.js.consumers.get(chatStream(this.space), FANOUT_DURABLE);
         const msgs = await consumer.consume();
         this.streamMsgs.push(msgs);
@@ -3244,10 +3510,8 @@ export class CotalEndpoint extends EventEmitter {
     async runReader() {
         if (!this.js || !this.jsm)
             return;
-        try {
-            await this.jsm.consumers.add(inboxStream(this.space), inboxReaderConfig(this.space, { ackWaitMs: this.ackWaitMs }));
-        }
-        catch { /* exists */ }
+        // Same fail-loud rule as fan-out: idempotent success is success, denial is not existence.
+        await this.jsm.consumers.add(inboxStream(this.space), inboxReaderConfig(this.space, { ackWaitMs: this.ackWaitMs }));
         const consumer = await this.js.consumers.get(inboxStream(this.space), INBOX_READER_DURABLE);
         const msgs = await consumer.consume();
         this.streamMsgs.push(msgs);
@@ -3340,7 +3604,8 @@ export class CotalEndpoint extends EventEmitter {
             });
         }
         catch {
-            // Transfer failed — keep the entry pending (redeliver), bounded by the same ceiling so a poison
+            // EVERY transfer failure is deliberately a retry, never a successful result. Keep the entry
+            // pending (redeliver), bounded by the same ceiling so a poison
             // entry can't head-of-line the shared reader forever.
             if (redeliveries >= READER_MAX_REDELIVERIES) {
                 m.term();
@@ -3366,9 +3631,11 @@ export class CotalEndpoint extends EventEmitter {
         try {
             consumer = await this.js.consumers.get(dlvStream(this.space), dlvDurable(this.owner, this.actor, this.ownLifecycleUid));
         }
-        catch {
-            return;
-        } // no DLV durable — Plane-3 not active for us
+        catch (e) {
+            if (isJetStreamMissing(e, JetStreamApiCodes.ConsumerNotFound))
+                return;
+            throw e; // a denied bind is not proof Plane-3 is absent
+        }
         const msgs = await consumer.consume();
         this.streamMsgs.push(msgs);
         void (async () => {
@@ -3500,13 +3767,9 @@ export class CotalEndpoint extends EventEmitter {
         for (const channel of this.channels) {
             if (!isConcreteChannel(channel) || this.plane3Channels.has(channel))
                 continue;
-            let cls;
-            try {
-                cls = await this.deliveryClassFresh(channel);
-            }
-            catch {
-                continue;
-            }
+            // A missing channel row legitimately resolves through the defaults. A failed/denied registry
+            // read does not prove the channel is live-only, so let it fail startup loudly.
+            const cls = await this.deliveryClassFresh(channel);
             if (cls !== "durable")
                 continue;
             try {
@@ -3518,7 +3781,7 @@ export class CotalEndpoint extends EventEmitter {
             }
             catch (e) {
                 if (!this.isNoResponders(e))
-                    this.emit("error", e); // no daemon ⇒ retry until it recovers
+                    this.emitRecoverable(e); // no daemon ⇒ retry until it recovers
                 void this.reconcileBootJoin(channel);
             }
         }
@@ -3551,7 +3814,7 @@ export class CotalEndpoint extends EventEmitter {
             }
             catch (e) {
                 if (attempt === 0 && !this.isNoResponders(e))
-                    this.emit("error", new Error(`channel "${channel}": boot durable self-join not yet established - retrying until the delivery daemon is reachable (${e.message})`));
+                    this.emitRecoverable(new Error(`channel "${channel}": boot durable self-join not yet established - retrying until the delivery daemon is reachable (${e.message})`));
             }
         }
     }
@@ -3807,8 +4070,22 @@ export class CotalEndpoint extends EventEmitter {
         try {
             return await this.jsm.consumers.info(stream, durable);
         }
-        catch {
-            return null; // 404 — fresh durable
+        catch (e) {
+            if (isJetStreamMissing(e, JetStreamApiCodes.ConsumerNotFound))
+                return null; // structured absence — fresh durable
+            throw e;
+        }
+    }
+    /** Delete one named consumer, swallowing ONLY structured consumer/stream absence. */
+    async deleteConsumerIfPresent(stream, durable) {
+        if (!this.jsm)
+            throw new Error("endpoint not started");
+        try {
+            await this.jsm.consumers.delete(stream, durable);
+        }
+        catch (e) {
+            if (!isJetStreamMissing(e, JetStreamApiCodes.ConsumerNotFound, JetStreamApiCodes.StreamNotFound))
+                throw e;
         }
     }
     /** Current frontier (last sequence) of the chat stream — a channel's join watermark, and the
@@ -3884,10 +4161,7 @@ export class CotalEndpoint extends EventEmitter {
         const out = [];
         // Clear any consumer leaked by a crashed prior read before re-creating it with THIS read's
         // single filter (the read ACL is enforced at create — see the doc above).
-        try {
-            await this.jsm.consumers.delete(stream, name);
-        }
-        catch { /* none; fine */ }
+        await this.deleteConsumerIfPresent(stream, name);
         await this.jsm.consumers.add(stream, {
             name,
             filter_subject: subject,
@@ -3923,10 +4197,7 @@ export class CotalEndpoint extends EventEmitter {
             }
         }
         finally {
-            try {
-                await this.jsm.consumers.delete(stream, name);
-            }
-            catch { /* already gone */ }
+            await this.deleteConsumerIfPresent(stream, name);
         }
         return out;
     }
@@ -3943,6 +4214,8 @@ export class CotalEndpoint extends EventEmitter {
         }
         catch (e) {
             this.emit("error", e);
+            if (isPermissionDenied(e))
+                throw e;
             return 0;
         }
         const noop = { ack: () => { }, nak: () => { }, durable: false };
@@ -3970,14 +4243,18 @@ export class CotalEndpoint extends EventEmitter {
     /**
      * Replay-gated pull of a channel's retained ambient from `sinceSeq` (exclusive) forward — the
      * focus-recall read behind `cotal_inbox`. Returns the messages (NOT emitted — this is a pull,
-     * not a push into context) plus `dropped: true` when the channel's earliest *retained* message
-     * is already newer than the watermark, i.e. some ambient aged out of the per-subject window and
-     * the caller must say so rather than silently short the window.
+     * not a push into context) plus `dropped: true` when the window is not complete: either the
+     * channel's earliest *retained* message is already newer than the watermark (some ambient aged
+     * out of the per-subject window), or replay is off for the channel below. Either way the caller
+     * must say so rather than silently reporting an empty, complete window.
      *
      * Honors the **same** per-channel replay gate as join-backfill ({@link joinPolicyFresh}): a
-     * `replay=off` channel returns nothing, so `focus` can't become a history bypass for a channel
-     * that denies replay to everyone else (the read ACL bounds *which* channels recall can touch; this
-     * app gate bounds *whether* a permitted channel replays).
+     * `replay=off` channel returns no messages, so `focus` can't become a history bypass for a
+     * channel that denies replay to everyone else (the read ACL bounds *which* channels recall can
+     * touch; this app gate bounds *whether* a permitted channel replays). Ingest still ack-drops
+     * focus-mode ambient/mentions on this channel on the promise that they stay recallable (#977) —
+     * the gate means that promise cannot be kept, so it reports `dropped: true` rather than pretend
+     * the window was empty and complete.
      */
     async recallChannel(channel, sinceSeq) {
         if (!this.jsm)
@@ -3986,7 +4263,7 @@ export class CotalEndpoint extends EventEmitter {
             return { messages: [], dropped: false };
         const policy = await this.joinPolicyFresh(channel);
         if (!policy.replay)
-            return { messages: [], dropped: false };
+            return { messages: [], dropped: true };
         const subject = chatSubject(this.space, "*", "*", channel);
         let raw;
         try {
@@ -3994,6 +4271,8 @@ export class CotalEndpoint extends EventEmitter {
         }
         catch (e) {
             this.emit("error", e);
+            if (isPermissionDenied(e))
+                throw e;
             raw = [];
         }
         const collected = [];
@@ -4083,6 +4362,7 @@ export class CotalEndpoint extends EventEmitter {
         let hydrated;
         this.presenceSnapshot = new Promise((resolve) => { hydrated = resolve; });
         const iter = await this.kv.watch();
+        this.presenceWatchIter = iter;
         void (async () => {
             let ready = false;
             for await (const e of iter) {
@@ -4103,6 +4383,7 @@ export class CotalEndpoint extends EventEmitter {
         if (!this.channelKv)
             return;
         const iter = await this.channelKv.watch();
+        this.channelWatchIter = iter;
         void (async () => {
             for await (const e of iter)
                 this.handleChannelEntry(e);
@@ -4134,6 +4415,7 @@ export class CotalEndpoint extends EventEmitter {
         }
     }
     handleKvEntry(e) {
+        this.lastPresenceWatchAt = Date.now();
         if (e.operation === "DEL" || e.operation === "PURGE") {
             this.markOffline(e.key);
             return;
@@ -4157,6 +4439,19 @@ export class CotalEndpoint extends EventEmitter {
             return;
         const prev = this.roster.get(id);
         const stale = Date.now() - raw.ts > this.ttlMs;
+        // A watch recovering from a stall replays the bucket. Those PUTs still carry the publisher's
+        // pre-stall timestamps, so they look TTL-expired even though the peers kept heartbeating on
+        // the broker. Materializing them as offline is the empty-to-full flicker #1045 named: the
+        // observer's catch-up, not N deaths. Keep last-known rows, stay view-stale, and wait for a
+        // live timestamp (or an explicit offline/delete) before changing a known peer.
+        if (stale && raw.status !== "offline") {
+            if (prev)
+                return;
+            this.roster.set(id, this.toOffline(raw));
+            this.emit("roster", this.getRoster());
+            return;
+        }
+        this.setPresenceViewFresh(true);
         // Any offline materialization (a stale snapshot OR a graceful-leave record) drops the advisory
         // attention fields — an offline peer must not carry a stale `[focus]`/`locally muted` hint.
         const p = stale || raw.status === "offline" ? this.toOffline(raw) : raw;
@@ -4210,8 +4505,22 @@ export class CotalEndpoint extends EventEmitter {
         this.emit("presence", { type: "offline", presence: offline });
         this.emit("roster", this.getRoster());
     }
+    setPresenceViewFresh(fresh) {
+        if (fresh === this.presenceViewFresh)
+            return;
+        this.presenceViewFresh = fresh;
+        this.emit("presence-view", this.presenceView());
+    }
     sweep() {
         const now = Date.now();
+        // Whole-bucket silence past TTL is THIS observer going deaf. Real rosters do not lose every
+        // peer in one window, and treating that silence as N offline verdicts empties an online-only
+        // sidebar with nothing saying the window went blind (#1045). Gate the per-peer age-out on
+        // watch freshness; surface the view as stale instead.
+        if (this.lastPresenceWatchAt !== 0 && now - this.lastPresenceWatchAt > this.ttlMs) {
+            this.setPresenceViewFresh(false);
+            return;
+        }
         let changed = false;
         for (const [id, p] of this.roster) {
             if (p.status !== "offline" && now - p.ts > this.ttlMs) {
@@ -4410,6 +4719,18 @@ export function isPermissionDenied(e) {
         return true;
     return /permissions?\s+violation/i.test(String(e?.message ?? ""));
 }
+/** True only for the structured JetStream API absence codes named by the caller. A status 404 or
+ * message regex is too broad here: the catch sites use absence to produce a successful empty/fresh
+ * result, so a permission denial, timeout, or protocol failure must never pass as "not found". */
+function isJetStreamMissing(e, ...codes) {
+    return e instanceof JetStreamApiError && codes.includes(e.code);
+}
+/** The signal's exact abort reason, or the platform-standard AbortError when none was supplied. */
+function abortReason(signal) {
+    return signal?.reason instanceof Error
+        ? signal.reason
+        : new DOMException("This operation was aborted", "AbortError");
+}
 /** True ONLY for a denial on a **publish** — the single case that proves the message was never
  *  ACCEPTED or stored. (Not "never reached the server": the server necessarily received enough of
  *  it to reject it. The distinction matters precisely here, because this helper exists to separate