sentinelayer-cli 0.40.0 → 0.42.0

package/src/session/first-message.js

@@ -1,5 +1,6 @@
 import { createAgentEvent } from "../events/schema.js";
 import { appendToStream } from "./stream.js";
+import { syncSessionEventToApi } from "./sync.js";
 
 export const FIRST_MESSAGE_AGENT = Object.freeze({
   id: "senti",
@@ -72,7 +73,7 @@ export function buildFirstSentiMessage({ sessionId } = {}) {
 
 /**
  * Post the first-Senti-message as the opening event of a freshly created
- * session. Best-effort + non-blocking — a failure never fails session
+ * session. Best-effort with bounded remote sync — a failure never fails session
  * creation. Returns { posted, reason }.
  */
 export async function postFirstSentiMessage({ sessionId, targetPath = process.cwd() } = {}) {
@@ -91,8 +92,15 @@ export async function postFirstSentiMessage({ sessionId, targetPath = process.cw
     },
   });
   try {
-    await appendToStream(sid, event, { targetPath, awaitRemoteSync: true });
-    return { posted: true, reason: "posted" };
+    const persisted = await appendToStream(sid, event, {
+      targetPath, syncRemote: false, lockTimeoutMs: 500,
+    });
+    const remoteSync = await syncSessionEventToApi(sid, persisted, {
+      targetPath, timeoutMs: 2_000,
+    }).catch(() => ({ synced: false, reason: "sync_failed" }));
+    // Keep posted's existing local-durability meaning; remote acknowledgement
+    // is explicit and must never be inferred from this compatibility field.
+    return { posted: true, reason: "posted", remoteSynced: Boolean(remoteSync.synced), remoteSync };
   } catch (error) {
     return { posted: false, reason: normalizeString(error?.message) || "append_failed" };
   }

package/src/session/listener.js

@@ -1,8 +1,14 @@
 import { setTimeout as delay } from "node:timers/promises";
 
-import { pollSessionEvents, pollSessionEventsBefore, streamSessionEvents } from "./sync.js";
+import {
+  pollSessionEvents,
+  pollSessionEventsBefore,
+  streamSessionEvents,
+  updateSessionReadCursor,
+} from "./sync.js";
 import { cursorAdvances, readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
 import { isSessionListenerLifecycleEvent } from "./control-events.js";
+import { sessionMessageRoutingEvent } from "./message-edits.js";
 
 const BROADCAST_RECIPIENTS = new Set([
   "*",
@@ -14,8 +20,10 @@ const BROADCAST_RECIPIENTS = new Set([
   "all-agents",
 ]);
 
-const DEFAULT_ACTIVE_INTERVAL_SECONDS = 5;
+const DEFAULT_ACTIVE_INTERVAL_SECONDS = 60;
 const DEFAULT_ACTIVE_WINDOW_SECONDS = 300;
+const DEFAULT_POLL_JITTER_RATIO = 0.2;
+const DEFAULT_MAX_POLL_BACKOFF_SECONDS = 300;
 const MAX_CLOCK_SKEW_MS = 60_000;
 
 function normalizeString(value) {
@@ -38,10 +46,6 @@ function normalizePositiveInteger(value, fallbackValue) {
   return Math.floor(normalized);
 }
 
-function isListenerStopDirective(event = {}) {
-  return normalizeString(event?.event) === "listener_stop";
-}
-
 function isPlainObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -65,6 +69,7 @@ function addRecipientValue(values, value) {
 }
 
 export function collectSessionEventRecipients(event = {}) {
+  event = sessionMessageRoutingEvent(event);
   const values = [];
   if (!isPlainObject(event)) return values;
   const payload = isPlainObject(event.payload) ? event.payload : {};
@@ -87,6 +92,7 @@ export function collectSessionEventRecipients(event = {}) {
 
 export function eventMatchesAgent(event = {}, agentId = "") {
   if (!isPlainObject(event)) return false;
+  event = sessionMessageRoutingEvent(event);
   const normalizedAgentId = normalizeComparableId(agentId);
   if (!normalizedAgentId) return false;
 
@@ -128,6 +134,46 @@ function cursorFromEvents(events = [], fallbackCursor = null) {
   return cursor;
 }
 
+function latestSequenceTarget(events = [], fallbackCursor = null) {
+  let targetSequenceId = null;
+  let targetCursor = normalizeString(fallbackCursor) || "";
+  for (const event of Array.isArray(events) ? events : []) {
+    const sequence = Number(event?.sequenceId ?? event?.sequence_id ?? event?.sequence);
+    if (Number.isFinite(sequence) && sequence > 0) {
+      if (targetSequenceId === null || sequence > targetSequenceId) {
+        targetSequenceId = Math.floor(sequence);
+        targetCursor = normalizeString(event?.cursor) || targetCursor;
+      }
+      continue;
+    }
+    const cursor = normalizeString(event?.cursor);
+    if (cursor) targetCursor = cursor;
+  }
+  return { targetSequenceId, targetCursor };
+}
+
+export function computeListenerPollDelay({
+  baseDelayMs,
+  consecutiveFailures = 0,
+  retryAfterMs = null,
+  jitterRatio = DEFAULT_POLL_JITTER_RATIO,
+  maxBackoffMs = DEFAULT_MAX_POLL_BACKOFF_SECONDS * 1000,
+  randomValue = Math.random(),
+} = {}) {
+  const base = Math.max(1, Math.floor(Number(baseDelayMs) || 1));
+  const failures = Math.max(0, Math.floor(Number(consecutiveFailures) || 0));
+  const maxBackoff = Math.max(base, Math.floor(Number(maxBackoffMs) || base));
+  const exponential = failures > 0
+    ? Math.min(maxBackoff, base * (2 ** Math.min(failures - 1, 20)))
+    : base;
+  const retryFloor = Math.max(0, Math.ceil(Number(retryAfterMs) || 0));
+  const boundedJitterRatio = Math.max(0, Math.min(0.5, Number(jitterRatio) || 0));
+  const boundedRandom = Math.max(0, Math.min(1, Number(randomValue) || 0));
+  const jitter = Math.floor(exponential * boundedJitterRatio * boundedRandom);
+  const jitteredBackoff = Math.min(maxBackoff, exponential + jitter);
+  return Math.max(retryFloor, jitteredBackoff);
+}
+
 function eventIdentityKey(event = {}) {
   const cursor = normalizeString(event?.cursor);
   if (cursor) return `cursor:${cursor}`;
@@ -141,6 +187,41 @@ function eventIdentityKey(event = {}) {
   });
 }
 
+function listenerControlType(control = {}) {
+  return normalizeLower(control?.type || control?.action || control?.event);
+}
+
+function listenerControlIssuedAtMs(control = {}) {
+  for (const key of ["issuedAtMs", "issued_at_ms"]) {
+    const epoch = Number(control?.[key]);
+    if (Number.isFinite(epoch) && epoch > 0) return epoch;
+  }
+  for (const key of ["issuedAt", "issued_at"]) {
+    const epoch = Date.parse(normalizeString(control?.[key]));
+    if (Number.isFinite(epoch)) return epoch;
+  }
+  return 0;
+}
+
+function listenerControlIdentityKey(control = {}) {
+  const explicitId = normalizeString(
+    control?.controlId || control?.control_id || control?.id,
+  );
+  if (explicitId) return `control:${explicitId}`;
+  return JSON.stringify({
+    type: listenerControlType(control),
+    issuedAt: normalizeString(control?.issuedAt || control?.issued_at),
+    targetAgentId: normalizeComparableId(
+      control?.targetAgentId ||
+        control?.target_agent_id ||
+        control?.payload?.targetAgentId ||
+        control?.payload?.target_agent_id,
+    ),
+    broadcast: Boolean(control?.broadcast || control?.payload?.broadcast),
+    reason: normalizeString(control?.reason || control?.payload?.reason),
+  });
+}
+
 function eventTimestampMs(event = {}) {
   for (const key of ["ts", "timestamp", "createdAt", "at"]) {
     const epoch = Date.parse(normalizeString(event?.[key]));
@@ -241,6 +322,8 @@ export async function listenSessionEvents({
   intervalSeconds = 60,
   activeIntervalSeconds = DEFAULT_ACTIVE_INTERVAL_SECONDS,
   activeWindowSeconds = DEFAULT_ACTIVE_WINDOW_SECONDS,
+  jitterRatio = DEFAULT_POLL_JITTER_RATIO,
+  maxBackoffSeconds = DEFAULT_MAX_POLL_BACKOFF_SECONDS,
   limit = 200,
   since = undefined,
   replay = false,
@@ -249,6 +332,7 @@ export async function listenSessionEvents({
   maxPolls = null,
   signal,
   onEvent = async () => {},
+  onControl = async () => {},
   onError = async () => {},
   onCatchup = async () => {},
   onLifecycle = async () => {},
@@ -256,12 +340,14 @@ export async function listenSessionEvents({
   _poll = pollSessionEvents,
   _pollLatest = pollSessionEventsBefore,
   _stream = streamSessionEvents,
+  _updateReadCursor = updateSessionReadCursor,
   _readCursor = readSyncCursor,
   _writeCursor = writeSyncCursor,
   _sleep = defaultSleep,
   _setInterval = setInterval,
   _clearInterval = clearInterval,
   _nowMs = Date.now,
+  _random = Math.random,
 } = {}) {
   const normalizedSessionId = normalizeString(sessionId);
   const normalizedAgentId = normalizeComparableId(agentId) || "cli-user";
@@ -293,10 +379,16 @@ export async function listenSessionEvents({
   let streamAttempted = false;
   let streamFallbackReason = "";
   let heartbeatCount = 0;
+  let consecutivePollFailures = 0;
+  let readCursorUpdates = 0;
+  let readCursorReason = "";
+  let deliveredControls = 0;
+  let ignoredControls = 0;
   let catchupNotified = false;
   let catchupEventCount = 0;
   let catchupMatchingEventCount = 0;
   const emittedKeys = new Set();
+  const deliveredControlKeys = new Set();
   const maxPollCount = normalizePositiveInteger(maxPolls, 0);
   const pollLimit = normalizePositiveInteger(limit, 200);
   const idleSleepMs = Math.max(1, normalizePositiveInteger(intervalSeconds, 60)) * 1000;
@@ -306,6 +398,9 @@ export async function listenSessionEvents({
   const activeWindowMs =
     Math.max(1, normalizePositiveInteger(activeWindowSeconds, DEFAULT_ACTIVE_WINDOW_SECONDS)) *
     1000;
+  const maxBackoffMs =
+    Math.max(1, normalizePositiveInteger(maxBackoffSeconds, DEFAULT_MAX_POLL_BACKOFF_SECONDS)) *
+    1000;
   const autoStreamIdleTimeoutMs =
     normalizedTransport === "auto" ? Math.max(5_000, Math.min(idleSleepMs, 30_000)) : 0;
 
@@ -354,6 +449,11 @@ export async function listenSessionEvents({
       ? new Date(lastHumanActivityMs).toISOString()
       : null,
     lastSleepMs,
+    consecutivePollFailures,
+    readCursorUpdates,
+    readCursorReason,
+    deliveredControls,
+    ignoredControls,
     reason: lastReason,
     ...extra,
   });
@@ -397,7 +497,7 @@ export async function listenSessionEvents({
         cursor: cursor || null,
         candidateCursor: nextCursor,
       });
-      return false;
+      return { processed: false, retryAfterMs: null };
     }
 
     const observedAtMs = Number(_nowMs()) || Date.now();
@@ -413,7 +513,6 @@ export async function listenSessionEvents({
       if (isRecentActivity(activityMs, observedAtMs, activeWindowMs)) {
         lastHumanActivityMs = Math.max(lastHumanActivityMs, activityMs);
       }
-      if (timestampMs && timestampMs < startedAtMs && isListenerStopDirective(event)) continue;
       if (isSessionListenerLifecycleEvent(event)) continue;
       if (!eventMatchesAgent(event, normalizedAgentId)) continue;
       visibleEvents.push(event);
@@ -471,8 +570,71 @@ export async function listenSessionEvents({
       persistedCursor = Boolean(writeResult?.written) || persistedCursor;
       cursor = nextCursor;
     }
+    // A fetch cursor echoed on an empty page is transport state, not new read
+    // progress. Writing it would recreate one operational write per idle poll.
+    const readTarget = events.length > 0
+      ? latestSequenceTarget(events, nextCursor)
+      : { targetSequenceId: null, targetCursor: "" };
+    let readCursorResult = null;
+    if (readTarget.targetSequenceId || readTarget.targetCursor) {
+      readCursorResult = await _updateReadCursor(normalizedSessionId, {
+        targetPath,
+        targetSequenceId: readTarget.targetSequenceId,
+        targetCursor: readTarget.targetCursor,
+        agentId: normalizedAgentId,
+      }).catch((error) => ({
+        ok: false,
+        reason: normalizeString(error?.message) || "read_cursor_write_failed",
+      }));
+      if (readCursorResult?.ok) {
+        readCursorUpdates += 1;
+        readCursorReason = "";
+      } else {
+        readCursorReason = normalizeString(readCursorResult?.reason) || "read_cursor_write_failed";
+      }
+    }
     primed = true;
-    return true;
+    return {
+      processed: true,
+      retryAfterMs: Number(readCursorResult?.retryAfterMs) || null,
+    };
+  }
+
+  async function processControlBatch(controlsInput = []) {
+    const controls = Array.isArray(controlsInput) ? controlsInput : [];
+    const observedAtMs = Number(_nowMs()) || Date.now();
+    for (const control of controls) {
+      if (!isPlainObject(control)) {
+        ignoredControls += 1;
+        continue;
+      }
+      const issuedAtMs = listenerControlIssuedAtMs(control);
+      const fresh =
+        issuedAtMs >= startedAtMs - MAX_CLOCK_SKEW_MS &&
+        issuedAtMs <= observedAtMs + MAX_CLOCK_SKEW_MS;
+      if (
+        !listenerControlType(control) ||
+        !fresh ||
+        !eventMatchesAgent(control, normalizedAgentId)
+      ) {
+        ignoredControls += 1;
+        continue;
+      }
+      const key = listenerControlIdentityKey(control);
+      if (deliveredControlKeys.has(key)) {
+        ignoredControls += 1;
+        continue;
+      }
+      deliveredControlKeys.add(key);
+      try {
+        await onControl(control);
+        deliveredControls += 1;
+      } catch (error) {
+        deliveredControlKeys.delete(key);
+        throw error;
+      }
+      if (signal?.aborted) break;
+    }
   }
 
   async function notifyHeartbeat({ stopping = false, nextPollMs = null } = {}) {
@@ -492,7 +654,7 @@ export async function listenSessionEvents({
   }
 
   let streamHeartbeatTimer = null;
-  let streamHeartbeatInFlight = false;
+  let streamMaintenanceInFlight = null;
   const streamHeartbeatMs = Math.max(1_000, Math.min(idleSleepMs, 60_000));
 
   function stopStreamHeartbeatTimer() {
@@ -503,14 +665,49 @@ export async function listenSessionEvents({
 
   function startStreamHeartbeatTimer() {
     stopStreamHeartbeatTimer();
-    streamHeartbeatTimer = _setInterval(async () => {
-      if (signal?.aborted || streamHeartbeatInFlight) return;
-      streamHeartbeatInFlight = true;
-      try {
-        await notifyHeartbeat({ nextPollMs: streamHeartbeatMs });
-      } finally {
-        streamHeartbeatInFlight = false;
+    streamHeartbeatTimer = _setInterval(() => {
+      if (signal?.aborted || streamMaintenanceInFlight) {
+        return streamMaintenanceInFlight;
       }
+      const maintenance = (async () => {
+        const result = await _poll(normalizedSessionId, {
+          targetPath,
+          since: cursor,
+          limit: 1,
+          listenerAgentId: normalizedAgentId,
+          signal,
+        });
+        if (signal?.aborted) return;
+        if (result?.ok) {
+          await processControlBatch(result.listenerControls);
+        } else {
+          await onError({
+            ok: false,
+            reason: `control_poll_${normalizeString(result?.reason) || "failed"}`,
+            cursor: cursor || null,
+            retryAfterMs: Number(result?.retryAfterMs) || null,
+            status: Number(result?.status) || null,
+          });
+        }
+        if (!signal?.aborted) {
+          await notifyHeartbeat({ nextPollMs: streamHeartbeatMs });
+        }
+      })().catch(async (error) => {
+        if (signal?.aborted || shouldAbort(error, signal)) return;
+        await onError({
+          ok: false,
+          reason: "control_poll_failed",
+          cursor: cursor || null,
+          detail: normalizeString(error?.message),
+        }).catch(() => {});
+      });
+      streamMaintenanceInFlight = maintenance;
+      maintenance.finally(() => {
+        if (streamMaintenanceInFlight === maintenance) {
+          streamMaintenanceInFlight = null;
+        }
+      });
+      return maintenance;
     }, streamHeartbeatMs);
   }
 
@@ -534,6 +731,9 @@ export async function listenSessionEvents({
         onEvent: async (event) => {
           await processEventBatch([event], normalizeString(event?.cursor) || cursor);
         },
+        onCursor: async (streamCursor) => {
+          await processEventBatch([], streamCursor);
+        },
         onError: async (error) => {
           lastReason = `stream_${normalizeString(error?.reason) || "error"}`;
           await onError({
@@ -545,8 +745,9 @@ export async function listenSessionEvents({
         onHeartbeat: async () => {
           await notifyHeartbeat({ nextPollMs: streamHeartbeatMs });
         },
-      }).finally(() => {
+      }).finally(async () => {
         stopStreamHeartbeatTimer();
+        await streamMaintenanceInFlight;
       });
       if (!streamResult?.ok) {
         streamFallbackReason = normalizeString(streamResult?.reason) || lastReason || "stream_failed";
@@ -567,24 +768,44 @@ export async function listenSessionEvents({
         targetPath,
         since: cursor,
         limit: pollLimit,
+        listenerAgentId: normalizedAgentId,
       });
 
+      let cursorRetryAfterMs = null;
       if (result?.ok) {
         lastReason = "";
-        await processEventBatch(result.events, result.cursor);
+        consecutivePollFailures = 0;
+        await processControlBatch(result.listenerControls);
+        if (signal?.aborted) break;
+        const processed = await processEventBatch(result.events, result.cursor);
+        cursorRetryAfterMs = Number(processed?.retryAfterMs) || null;
       } else {
         lastReason = normalizeString(result?.reason) || "poll_failed";
+        consecutivePollFailures += 1;
         await onError({
           ok: false,
           reason: lastReason,
           cursor: result?.cursor || cursor || null,
+          retryAfterMs: Number(result?.retryAfterMs) || null,
+          status: Number(result?.status) || null,
         });
       }
 
       const willStop = maxPollCount > 0 && pollCount >= maxPollCount;
       const heartbeatAtMs = Number(_nowMs()) || Date.now();
       const humanActive = isRecentActivity(lastHumanActivityMs, heartbeatAtMs, activeWindowMs);
-      const nextSleepMs = humanActive ? Math.min(idleSleepMs, activeSleepMs) : idleSleepMs;
+      const baseSleepMs = humanActive ? Math.min(idleSleepMs, activeSleepMs) : idleSleepMs;
+      const nextSleepMs = computeListenerPollDelay({
+        baseDelayMs: baseSleepMs,
+        consecutiveFailures: consecutivePollFailures,
+        retryAfterMs: Math.max(
+          Number(result?.retryAfterMs) || 0,
+          Number(cursorRetryAfterMs) || 0,
+        ),
+        jitterRatio,
+        maxBackoffMs,
+        randomValue: _random(),
+      });
       await notifyHeartbeat({ nextPollMs: willStop ? null : nextSleepMs, stopping: willStop });
 
       if (willStop) break;
@@ -619,6 +840,11 @@ export async function listenSessionEvents({
     matched,
     emitted,
     persistedCursor,
+    readCursorUpdates,
+    readCursorReason,
+    deliveredControls,
+    ignoredControls,
+    consecutivePollFailures,
     catchupNotified,
     catchupEventCount,
     catchupMatchingEventCount,

package/src/session/listeners.js

@@ -1,4 +1,4 @@
-import { pollSessionEventsBefore } from "./sync.js";
+import { fetchSessionPresence } from "./sync.js";
 
 const LISTENER_EVENT_TYPES = new Set([
   "session_listener_started",
@@ -10,9 +10,6 @@ const LISTENER_EVENT_TYPES = new Set([
 // listener likely died without a clean stop — show it as stale, not live.
 const DEFAULT_STALE_AFTER_MS = 180_000;
 const MAX_STALE_GRACE_MS = 60_000;
-const DEFAULT_LISTENER_FETCH_LIMIT = 200;
-const DEFAULT_LISTENER_FETCH_MAX_PAGES = 5;
-const MAX_LISTENER_FETCH_MAX_PAGES = 25;
 
 function normalizeString(value) {
   return String(value || "").trim();
@@ -144,94 +141,86 @@ export function summarizeListeners(events = [], { nowMs = Date.now(), staleAfter
   return rows;
 }
 
+function presenceEntryEpochMs(entry = {}) {
+  const explicit = Number(entry.lastSeenMs ?? entry.last_seen_ms);
+  if (Number.isFinite(explicit) && explicit > 0) {
+    return Math.floor(explicit);
+  }
+  const parsed = Date.parse(
+    normalizeString(entry.lastSeen || entry.last_seen || entry.updatedAt || entry.updated_at),
+  );
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function presenceRows(entries = [], nowMs = Date.now()) {
+  return (Array.isArray(entries) ? entries : [])
+    .map((entry) => {
+      const agentId = normalizeString(entry?.agentId || entry?.agent_id || entry?.id);
+      if (!agentId) return null;
+      const seenAtMs = presenceEntryEpochMs(entry);
+      const ageMs = seenAtMs === null ? null : Math.max(0, nowMs - seenAtMs);
+      return {
+        agentId,
+        displayName: normalizeString(entry?.displayName || entry?.display_name) || agentId,
+        model: normalizeString(entry?.model),
+        status: "present",
+        active: null,
+        cadenceSeconds: null,
+        idleIntervalSeconds: null,
+        activeIntervalSeconds: null,
+        presenceIntervalSeconds: null,
+        presenceKeepaliveSeconds: null,
+        nextPollSeconds: null,
+        staleAfterSeconds: null,
+        lastSeenAt: seenAtMs ? new Date(seenAtMs).toISOString() : null,
+        lastSeenAgoSeconds: ageMs === null ? null : Math.round(ageMs / 1000),
+        lastHumanActivityAt: null,
+      };
+    })
+    .filter(Boolean)
+    .sort((left, right) => (right.lastSeenAt || "").localeCompare(left.lastSeenAt || ""));
+}
+
 /**
- * Fetch recent session events from the API and summarize the listeners.
- * `limit` controls the raw API page size. Busy rooms can push durable
- * keepalive heartbeats out of a single tail page, so we walk a small bounded
- * number of older pages while the tail contains no listener lifecycle events
- * and the sequence cursor advances.
+ * Fetch the authoritative ephemeral presence roster.
+ *
+ * There is intentionally no event-tail compatibility path. A server without
+ * the presence endpoint, a disabled rollout flag, or degraded Redis produces
+ * an unknown roster instead of silently making every listener a durable
+ * heartbeat writer again.
  */
 export async function fetchSessionListeners(
   sessionId,
   {
     targetPath = process.cwd(),
-    limit = DEFAULT_LISTENER_FETCH_LIMIT,
-    maxPages = DEFAULT_LISTENER_FETCH_MAX_PAGES,
     nowMs = Date.now,
     forceCircuitProbe = true,
-    poll = pollSessionEventsBefore,
+    fetchPresence = fetchSessionPresence,
   } = {}
 ) {
-  const pageLimit = Math.max(
-    1,
-    Math.min(DEFAULT_LISTENER_FETCH_LIMIT, positiveInt(limit) || DEFAULT_LISTENER_FETCH_LIMIT),
-  );
-  const maxPageCount = Math.max(
-    1,
-    Math.min(MAX_LISTENER_FETCH_MAX_PAGES, positiveInt(maxPages) || DEFAULT_LISTENER_FETCH_MAX_PAGES),
-  );
-  let beforeSequence = null;
-  let latestResult = null;
-  let allEvents = [];
-  let pageCount = 0;
-  let listenerEventCount = 0;
-  let partial = false;
-  let partialReason = "";
-
-  for (let page = 0; page < maxPageCount; page += 1) {
-    const result = await poll(sessionId, {
-      targetPath,
-      beforeSequence,
-      limit: pageLimit,
-      forceCircuitProbe,
-    });
-    pageCount += 1;
-
-    if (!result?.ok) {
-      if (!latestResult) {
-        return {
-          ok: false,
-          reason: normalizeString(result?.reason) || "fetch_failed",
-          listeners: [],
-          pageCount,
-          scannedEventCount: allEvents.length,
-          listenerEventCount: 0,
-          partial: false,
-        };
-      }
-      partial = true;
-      partialReason = normalizeString(result?.reason) || "partial_fetch";
-      break;
-    }
-
-    latestResult = result;
-    const pageEvents = Array.isArray(result.events) ? result.events : [];
-    allEvents = [...pageEvents, ...allEvents];
-    listenerEventCount += pageEvents.filter((event) =>
-      LISTENER_EVENT_TYPES.has(normalizeString(event?.event))
-    ).length;
-
-    if (pageEvents.length < pageLimit) break;
-    if (listenerEventCount > 0) break;
-
-    const candidateBeforeSequence = Number(result.beforeSequence || 0);
-    if (!Number.isFinite(candidateBeforeSequence) || candidateBeforeSequence <= 0) break;
-    const currentBeforeSequence = Number(beforeSequence || 0);
-    if (currentBeforeSequence > 0 && candidateBeforeSequence >= currentBeforeSequence) break;
-    beforeSequence = Math.floor(candidateBeforeSequence);
-  }
-
-  const listeners = summarizeListeners(allEvents, { nowMs: nowMs() });
+  const result = await fetchPresence(sessionId, {
+    targetPath,
+    forceCircuitProbe,
+  });
+  const presenceStatus = normalizeString(result?.status).toLowerCase() || "degraded";
+  const authoritative = Boolean(result?.ok && result?.enabled !== false && presenceStatus === "ok");
+  const listeners = authoritative
+    ? presenceRows(result.present, Number(nowMs()) || Date.now())
+    : [];
   return {
-    ok: true,
+    ok: authoritative,
+    authoritative,
+    enabled: result?.enabled ?? null,
+    presenceStatus,
+    reason: authoritative ? "" : normalizeString(result?.reason) || "presence_unknown",
+    retryAfterMs: Number(result?.retryAfterMs) || null,
     sessionId: normalizeString(sessionId),
     listeners,
-    pageCount,
-    scannedEventCount: allEvents.length,
-    listenerEventCount,
-    beforeSequence: latestResult?.beforeSequence || beforeSequence || null,
-    partial,
-    reason: partial ? partialReason : "",
+    pageCount: 0,
+    scannedEventCount: 0,
+    listenerEventCount: 0,
+    beforeSequence: null,
+    partial: false,
   };
 }
 
@@ -239,7 +228,9 @@ export function formatListenerLine(row) {
   const cadence = row.cadenceSeconds ? `${row.cadenceSeconds}s` : "—";
   const seen = row.lastSeenAgoSeconds === null ? "never" : `${row.lastSeenAgoSeconds}s ago`;
   const statusLabel =
-    row.status === "active"
+    row.status === "present"
+      ? "● present"
+      : row.status === "active"
       ? "● active"
       : row.status === "idle"
         ? "○ idle"