sentinelayer-cli 0.30.4 → 0.30.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.30.4",
+  "version": "0.30.5",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/session.js

@@ -65,6 +65,10 @@ import {
   updateSessionTitle,
 } from "../session/store.js";
 import { fetchSessionListeners, formatListenerLine } from "../session/listeners.js";
+import {
+  filterSessionMaterialEvents,
+  isSessionControlEvent,
+} from "../session/control-events.js";
 import {
   acceptSessionInvitation,
   normalizeSessionOnboarding,
@@ -703,6 +707,80 @@ function mergeSessionActionEvents(events = [], actionEvents = []) {
     .map((entry) => entry.event);
 }
 
+async function pollSessionEventsBeforeTranscriptTail(sessionId, {
+  targetPath,
+  beforeSequence = null,
+  tail = 20,
+  includeControlEvents = false,
+  timeoutMs = 15_000,
+  maxPages = 10,
+} = {}) {
+  const targetMaterialCount = Math.max(1, Math.floor(Number(tail) || 20));
+  const pageLimit = includeControlEvents
+    ? Math.min(200, targetMaterialCount)
+    : 200;
+  const maxPageCount = Math.max(1, Math.min(25, Math.floor(Number(maxPages) || 10)));
+  let nextBeforeSequence = beforeSequence;
+  let latestResult = null;
+  let combinedEvents = [];
+  let pageCount = 0;
+
+  for (let page = 0; page < maxPageCount; page += 1) {
+    const result = await pollSessionEventsBefore(sessionId, {
+      targetPath,
+      beforeSequence: nextBeforeSequence,
+      limit: pageLimit,
+      timeoutMs,
+    });
+    pageCount += 1;
+    if (!result?.ok) {
+      if (!latestResult) return { ...result, pageCount };
+      latestResult = {
+        ...latestResult,
+        reason: result?.reason || latestResult.reason || "partial_tail_fetch",
+        partial: true,
+      };
+      break;
+    }
+
+    latestResult = result;
+    const pageEvents = Array.isArray(result.events) ? result.events : [];
+    combinedEvents = [...pageEvents, ...combinedEvents];
+    const materialCount = includeControlEvents
+      ? combinedEvents.length
+      : filterSessionMaterialEvents(combinedEvents).length;
+
+    if (includeControlEvents || materialCount >= targetMaterialCount) break;
+    if (pageEvents.length < pageLimit) break;
+
+    const candidateBefore = Number(result.beforeSequence || 0);
+    if (!Number.isFinite(candidateBefore) || candidateBefore <= 0) break;
+    const currentBefore = Number(nextBeforeSequence || 0);
+    if (currentBefore > 0 && candidateBefore >= currentBefore) break;
+    nextBeforeSequence = candidateBefore;
+  }
+
+  if (!latestResult) {
+    return {
+      ok: true,
+      reason: "",
+      events: [],
+      cursor: null,
+      beforeSequence: beforeSequence || null,
+      pageCount,
+    };
+  }
+
+  return {
+    ...latestResult,
+    events: combinedEvents,
+    cursor: normalizeString(combinedEvents[combinedEvents.length - 1]?.cursor) || latestResult.cursor || null,
+    pageCount,
+    materialBackfillComplete:
+      includeControlEvents || filterSessionMaterialEvents(combinedEvents).length >= targetMaterialCount,
+  };
+}
+
 async function appendActionEventIfMissing(sessionId, actionEvent, { targetPath } = {}) {
   if (!actionEvent) return { appended: false, reason: "no_event", event: null };
   const existingEvents = await readStream(sessionId, { targetPath, tail: 0 }).catch(() => []);
@@ -1604,6 +1682,54 @@ function compactPayload(record = {}) {
   );
 }
 
+function listenerPresenceHeartbeatFingerprint(lifecycle = {}) {
+  return JSON.stringify(
+    compactPayload({
+      active: Boolean(lifecycle.active),
+      state: normalizeString(lifecycle.state) || "heartbeat",
+      transport: normalizeString(lifecycle.transport) || null,
+      reason: normalizeString(lifecycle.reason) || null,
+      idleIntervalSeconds: lifecycle.idleIntervalSeconds ?? null,
+      activeIntervalSeconds: lifecycle.activeIntervalSeconds ?? null,
+      activeWindowSeconds: lifecycle.activeWindowSeconds ?? null,
+      lastHumanActivityAt: lifecycle.lastHumanActivityAt || null,
+    }),
+  );
+}
+
+export function shouldPublishListenerPresenceHeartbeat({
+  lifecycle = {},
+  nowMs = Date.now(),
+  lastHeartbeatMs = 0,
+  lastFingerprint = "",
+  presenceIntervalMs = 60_000,
+  presenceKeepaliveMs = 180_000,
+} = {}) {
+  const lifecycleType = normalizeString(lifecycle.type) || "heartbeat";
+  if (lifecycleType !== "heartbeat") {
+    return { publish: true, fingerprint: lastFingerprint, reason: "lifecycle" };
+  }
+  const fingerprint = listenerPresenceHeartbeatFingerprint(lifecycle);
+  if (lifecycle.stopping) {
+    return { publish: true, fingerprint, reason: "stopping" };
+  }
+  const currentMs = Number(nowMs) || Date.now();
+  const previousMs = Number(lastHeartbeatMs) || 0;
+  if (previousMs <= 0) {
+    return { publish: true, fingerprint, reason: "first" };
+  }
+  if (fingerprint !== lastFingerprint) {
+    return { publish: true, fingerprint, reason: "changed" };
+  }
+  const minIntervalMs = Math.max(1, Number(presenceIntervalMs) || 60_000);
+  const keepaliveMs = Math.max(minIntervalMs, Number(presenceKeepaliveMs) || 180_000);
+  const elapsedMs = currentMs - previousMs;
+  if (elapsedMs >= keepaliveMs) {
+    return { publish: true, fingerprint, reason: "keepalive" };
+  }
+  return { publish: false, fingerprint, reason: elapsedMs < minIntervalMs ? "interval" : "unchanged" };
+}
+
 async function publishListenerPresenceEvent({
   sessionId,
   targetPath,
@@ -1653,6 +1779,8 @@ async function publishListenerPresenceEvent({
       idleIntervalSeconds: lifecycle.idleIntervalSeconds,
       activeIntervalSeconds: lifecycle.activeIntervalSeconds,
       activeWindowSeconds: lifecycle.activeWindowSeconds,
+      presenceIntervalSeconds: lifecycle.presenceIntervalSeconds,
+      presenceKeepaliveSeconds: lifecycle.presenceKeepaliveSeconds,
       lastHumanActivityAt: lifecycle.lastHumanActivityAt,
       lastSleepMs: lifecycle.lastSleepMs,
       nextPollMs: lifecycle.nextPollMs,
@@ -2117,13 +2245,6 @@ function formatEventLine(event = {}) {
   return `${ts} ${agentId} ${type}`;
 }
 
-function isSessionControlEvent(event = {}) {
-  const payload = event?.payload && typeof event.payload === "object" ? event.payload : {};
-  const type = normalizeString(event.event || event.type).toLowerCase();
-  if (type.startsWith("session_listener_")) return true;
-  return normalizeString(payload.source).toLowerCase() === "session_listen";
-}
-
 function summarizeSessionTailEvent(event = null) {
   if (!event || typeof event !== "object") return null;
   return {
@@ -4059,6 +4180,11 @@ export function registerSessionCommand(program) {
       "Minimum seconds between remote listener heartbeat events (default 60)",
       "60",
     )
+    .option(
+      "--presence-keepalive <seconds>",
+      "Maximum seconds between unchanged remote listener heartbeat events (default 180)",
+      "180",
+    )
     .option(
       "--no-presence",
       "Do not publish durable listener lifecycle/heartbeat events",
@@ -4111,6 +4237,11 @@ export function registerSessionCommand(program) {
         "presence-interval",
         60,
       );
+      const presenceKeepaliveSeconds = parsePositiveInteger(
+        options.presenceKeepalive,
+        "presence-keepalive",
+        180,
+      );
       const listenerIdentity = inferSessionAgentIdentity({
         agentId,
         model: options.model,
@@ -4193,7 +4324,10 @@ export function registerSessionCommand(program) {
       const durablePresenceEnabled = options.presence !== false;
       const publishPresence = durablePresenceEnabled && canPublishListenerPresence(agentId);
       const presenceIntervalMs = Math.max(1, presenceIntervalSeconds) * 1000;
+      const presenceKeepaliveMs =
+        Math.max(presenceIntervalSeconds, presenceKeepaliveSeconds, 1) * 1000;
       let lastPresenceHeartbeatMs = 0;
+      let lastPresenceHeartbeatFingerprint = "";
 
       // Periodic in-session success reminders (ack, claim work, reply
       // in-thread). Long-running interactive listeners only — skipped under
@@ -4375,11 +4509,25 @@ export function registerSessionCommand(program) {
             }
             if (!publishPresence) return;
             const lifecycleType = normalizeString(lifecycle?.type);
+            const publishLifecycle = {
+              ...lifecycle,
+              presenceIntervalSeconds,
+              presenceKeepaliveSeconds: Math.max(presenceIntervalSeconds, presenceKeepaliveSeconds),
+            };
             if (lifecycleType === "heartbeat") {
               const nowMs = Date.now();
-              if (lastPresenceHeartbeatMs > 0 && nowMs - lastPresenceHeartbeatMs < presenceIntervalMs) {
+              const heartbeatDecision = shouldPublishListenerPresenceHeartbeat({
+                lifecycle: publishLifecycle,
+                nowMs,
+                lastHeartbeatMs: lastPresenceHeartbeatMs,
+                lastFingerprint: lastPresenceHeartbeatFingerprint,
+                presenceIntervalMs,
+                presenceKeepaliveMs,
+              });
+              if (!heartbeatDecision.publish) {
                 return;
               }
+              lastPresenceHeartbeatFingerprint = heartbeatDecision.fingerprint;
               lastPresenceHeartbeatMs = nowMs;
             }
             await publishListenerPresenceEvent({
@@ -4391,7 +4539,7 @@ export function registerSessionCommand(program) {
               provider,
               clientKind,
               listenerId,
-              lifecycle,
+              lifecycle: publishLifecycle,
             });
           },
         });
@@ -4914,9 +5062,6 @@ export function registerSessionCommand(program) {
       const beforeSequence = parseOptionalPositiveInteger(options.beforeSequence, "before-sequence");
       const emitJson = shouldEmitJson(options, command);
       const includeControlEvents = Boolean(options.includeControlEvents);
-      const remoteTailLimit = includeControlEvents
-        ? tail
-        : Math.min(200, Math.max(tail, tail + 20));
       const readAgentId = await defaultAgentId(options.agent, targetPath);
 
       let hydration = null;
@@ -4935,11 +5080,13 @@ export function registerSessionCommand(program) {
         hydration = await hydrateSessionFromRemote({
           sessionId: normalizedSessionId,
           targetPath,
+          includeControlEvents,
         });
-        remoteTail = await pollSessionEventsBefore(normalizedSessionId, {
+        remoteTail = await pollSessionEventsBeforeTranscriptTail(normalizedSessionId, {
           targetPath,
           beforeSequence,
-          limit: remoteTailLimit,
+          tail,
+          includeControlEvents,
           timeoutMs: 15_000,
         });
         if (options.actions !== false) {
@@ -5016,14 +5163,17 @@ export function registerSessionCommand(program) {
         let remoteTailAppended = 0;
         let remoteTailDisplayedOnly = 0;
         let remoteTailUpgraded = 0;
-        if (remoteTail?.ok && Array.isArray(remoteTail.events) && remoteTail.events.length > 0) {
+        const remoteTailAppendEvents = includeControlEvents
+          ? remoteTail?.events
+          : filterSessionMaterialEvents(remoteTail?.events || []);
+        if (remoteTail?.ok && Array.isArray(remoteTailAppendEvents) && remoteTailAppendEvents.length > 0) {
           const knownKeys = new Set();
           const displayIndexByKey = new Map();
           for (const [index, event] of displayEvents.entries()) {
             addSessionEventIdentityKeys(knownKeys, event);
             indexSessionEventIdentityKeys(displayIndexByKey, displayEvents, event, index);
           }
-          for (const event of remoteTail.events) {
+          for (const event of remoteTailAppendEvents) {
             const existingIndex = findSessionEventIdentityIndex(displayIndexByKey, event);
             if (existingIndex >= 0) {
               const existing = displayEvents[existingIndex];
@@ -5115,6 +5265,8 @@ export function registerSessionCommand(program) {
                       count: Array.isArray(remoteTail.events) ? remoteTail.events.length : 0,
                       cursor: remoteTail.cursor || null,
                       beforeSequence: remoteTail.beforeSequence || null,
+                      pageCount: Number(remoteTail.pageCount || 0),
+                      materialBackfillComplete: Boolean(remoteTail.materialBackfillComplete),
                       verified: Boolean(remoteTail.ok),
                       appended: remoteTailAppended,
                       displayedOnly: remoteTailDisplayedOnly,
@@ -5190,6 +5342,7 @@ export function registerSessionCommand(program) {
             signal: ac.signal,
           })) {
             if (item.event) {
+              if (!includeControlEvents && isSessionControlEvent(item.event)) continue;
               if (emitJson) {
                 console.log(JSON.stringify({ source: item.source, event: item.event }));
               } else {
@@ -5218,6 +5371,9 @@ export function registerSessionCommand(program) {
           continue;
         }
         addSessionEventIdentityKeys(seenFollowEvents, event);
+        if (!includeControlEvents && isSessionControlEvent(event)) {
+          continue;
+        }
         if (emitJson) {
           console.log(JSON.stringify(event));
         } else {
@@ -5659,6 +5815,7 @@ export function registerSessionCommand(program) {
       "Hydrate from the SentinelLayer API before exporting and include remote message actions",
     )
     .option("--no-actions", "Do not include remote message actions/replies/reactions")
+    .option("--include-control-events", "Include listener/control-plane events in the exported transcript")
     .option("--path <path>", "Workspace path for the session", ".")
     .action(async (sessionId, options) => {
       const normalizedSessionId = normalizeString(sessionId);
@@ -5676,6 +5833,7 @@ export function registerSessionCommand(program) {
         hydration = await hydrateSessionFromRemote({
           sessionId: normalizedSessionId,
           targetPath,
+          includeControlEvents: Boolean(options.includeControlEvents),
         }).catch((error) => ({ ok: false, reason: error?.message || "hydrate_failed" }));
         if (options.actions !== false) {
           remoteActions = await listSessionMessageActions(normalizedSessionId, {
@@ -5708,7 +5866,12 @@ export function registerSessionCommand(program) {
       const actionEvents = remoteActions?.ok
         ? buildSessionActionEvents(normalizedSessionId, remoteActions.actions)
         : [];
-      const exportEvents = mergeSessionActionEvents(events, actionEvents);
+      const includeControlEvents = Boolean(options.includeControlEvents);
+      const transcriptBaseEvents = includeControlEvents
+        ? events
+        : filterSessionMaterialEvents(events);
+      const hiddenControlEventCount = events.length - transcriptBaseEvents.length;
+      const exportEvents = mergeSessionActionEvents(transcriptBaseEvents, actionEvents);
       const stats = computeTranscriptStats({
         sessionMeta: sessionPayload,
         events: exportEvents,
@@ -5722,6 +5885,15 @@ export function registerSessionCommand(program) {
       if (format === "ndjson") {
         const lines = [];
         lines.push(JSON.stringify({ kind: "session", value: sessionPayload }));
+        lines.push(JSON.stringify({
+          kind: "export_metadata",
+          value: {
+            includeControlEvents,
+            hiddenControlEventCount,
+            rawEventCount: events.length,
+            eventCount: exportEvents.length,
+          },
+        }));
         for (const agent of agents) lines.push(JSON.stringify({ kind: "agent", value: agent }));
         for (const participant of participants) {
           lines.push(JSON.stringify({ kind: "participant", value: participant }));
@@ -5763,10 +5935,12 @@ export function registerSessionCommand(program) {
               registeredAgents: agents.length,
               events: exportEvents.length,
               rawEvents: events.length,
+              hiddenControlEvents: hiddenControlEventCount,
               actions: Array.isArray(remoteActions?.actions) ? remoteActions.actions.length : 0,
               actionEvents: actionEvents.length,
               tasks: (tasks.tasks || []).length,
             },
+            includeControlEvents,
             totals: stats.totals,
           },
           null,
@@ -5783,7 +5957,7 @@ export function registerSessionCommand(program) {
           pc.gray(
             `Exported ${exportEvents.length} events / ${participants.length} participants (${agents.length} registered agents) / ${
               (tasks.tasks || []).length
-            } tasks → ${outPath}`,
+            } tasks${hiddenControlEventCount ? ` (${hiddenControlEventCount} control events omitted)` : ""} → ${outPath}`,
           ),
         );
       } else {
@@ -5806,6 +5980,7 @@ export function registerSessionCommand(program) {
       "Hydrate from the SentinelLayer API before rendering (pulls web-posted messages into the local NDJSON)",
     )
     .option("--no-actions", "Do not include remote message actions/replies/reactions")
+    .option("--include-control-events", "Include listener/control-plane events in the Markdown transcript")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, options, command) => {
@@ -5822,6 +5997,7 @@ export function registerSessionCommand(program) {
         hydration = await hydrateSessionFromRemote({
           sessionId: normalizedSessionId,
           targetPath,
+          includeControlEvents: Boolean(options.includeControlEvents),
         }).catch((error) => ({ ok: false, reason: error?.message || "hydrate_failed" }));
         if (options.actions !== false) {
           remoteActions = await listSessionMessageActions(normalizedSessionId, {
@@ -5844,7 +6020,12 @@ export function registerSessionCommand(program) {
       const actionEvents = remoteActions?.ok
         ? buildSessionActionEvents(normalizedSessionId, remoteActions.actions)
         : [];
-      const transcriptEvents = mergeSessionActionEvents(events, actionEvents);
+      const includeControlEvents = Boolean(options.includeControlEvents);
+      const transcriptBaseEvents = includeControlEvents
+        ? events
+        : filterSessionMaterialEvents(events);
+      const hiddenControlEventCount = events.length - transcriptBaseEvents.length;
+      const transcriptEvents = mergeSessionActionEvents(transcriptBaseEvents, actionEvents);
 
       // Pull GitHub/Google avatar + display name from the active auth
       // session so any human-id seen in the stream renders with the
@@ -5909,6 +6090,8 @@ export function registerSessionCommand(program) {
         rawEventCount: events.length,
         actionCount: Array.isArray(remoteActions?.actions) ? remoteActions.actions.length : 0,
         actionEventCount: actionEvents.length,
+        includeControlEvents,
+        hiddenControlEventCount,
         agentCount: participants.length,
         participantCount: participants.length,
         derivedAgentCount: stats.agents.length,
@@ -5940,6 +6123,9 @@ export function registerSessionCommand(program) {
           `${transcriptEvents.length} events · ${participants.length} participants (${agents.length} registered agents) · actions=${payload.actionCount} · live ${stats.sessionLiveSeconds}s · senti=${stats.sentiActions} · tokens=${stats.totals.tokenTotal} · cost=$${stats.totals.costTotalUsd.toFixed(4)}`,
         ),
       );
+      if (hiddenControlEventCount > 0) {
+        console.log(pc.gray(`${hiddenControlEventCount} control events omitted; rerun with --include-control-events to inspect them.`));
+      }
     });
 
   session

package/src/mcp/session-stdio-server.js

@@ -5,6 +5,7 @@ import { setTimeout as sleep } from "node:timers/promises";
 import { createAgentEvent } from "../events/schema.js";
 import { appendToStream } from "../session/stream.js";
 import { eventMatchesAgent } from "../session/listener.js";
+import { isSessionControlEvent } from "../session/control-events.js";
 import {
   listSessionMessageActions,
   pollSessionEvents,
@@ -102,20 +103,6 @@ function eventAgentId(event = {}) {
   return normalizeAgentId(event?.agent?.id || event?.agentId || event?.agent_id, "");
 }
 
-function eventName(event = {}) {
-  return normalizeString(event?.event || event?.type).toLowerCase();
-}
-
-function isControlEvent(event = {}) {
-  const name = eventName(event);
-  const payload = isPlainObject(event?.payload) ? event.payload : {};
-  return (
-    name.startsWith("session_listen_") ||
-    name === "agent_heartbeat" ||
-    normalizeString(payload.source).toLowerCase() === "session_listen"
-  );
-}
-
 function safePayload(payload = {}) {
   if (!isPlainObject(payload)) return {};
   const next = { ...payload };
@@ -627,7 +614,7 @@ export function createSessionMcpToolHandlers({
       }
 
       const events = (Array.isArray(result.events) ? result.events : []).filter((event) => {
-        if (!includeControlEvents && isControlEvent(event)) return false;
+        if (!includeControlEvents && isSessionControlEvent(event)) return false;
         if (!includeSelf && eventAgentId(event) === agentId) return false;
         return eventMatchesAgent(event, agentId);
       });

package/src/session/control-events.js

@@ -0,0 +1,40 @@
+const SESSION_CONTROL_EVENT_TYPES = new Set([
+  "listener_stop",
+  "session_coaching",
+  "session_listen_catchup",
+  "session_listen_error",
+]);
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function eventType(event = {}) {
+  return normalizeString(event?.event || event?.type).toLowerCase();
+}
+
+function payloadSource(event = {}) {
+  const payload = event?.payload && typeof event.payload === "object" && !Array.isArray(event.payload)
+    ? event.payload
+    : {};
+  return normalizeString(payload.source).toLowerCase();
+}
+
+export function isSessionListenerLifecycleEvent(event = {}) {
+  const type = eventType(event);
+  if (type.startsWith("session_listener_")) return true;
+  return payloadSource(event) === "session_listen";
+}
+
+export function isSessionControlEvent(event = {}) {
+  const type = eventType(event);
+  return (
+    isSessionListenerLifecycleEvent(event) ||
+    type.startsWith("session_listen_") ||
+    SESSION_CONTROL_EVENT_TYPES.has(type)
+  );
+}
+
+export function filterSessionMaterialEvents(events = []) {
+  return (Array.isArray(events) ? events : []).filter((event) => !isSessionControlEvent(event));
+}

package/src/session/listener.js

@@ -2,6 +2,7 @@ import { setTimeout as delay } from "node:timers/promises";
 
 import { pollSessionEvents, pollSessionEventsBefore, streamSessionEvents } from "./sync.js";
 import { cursorAdvances, readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
+import { isSessionListenerLifecycleEvent } from "./control-events.js";
 
 const BROADCAST_RECIPIENTS = new Set([
   "*",
@@ -223,14 +224,6 @@ function isRecentActivity(activityMs, nowMs, windowMs) {
   );
 }
 
-function isListenerLifecycleEvent(event = {}) {
-  if (!isPlainObject(event)) return false;
-  const payload = isPlainObject(event.payload) ? event.payload : {};
-  const eventType = normalizeString(event.event || event.type).toLowerCase();
-  if (eventType.startsWith("session_listener_")) return true;
-  return normalizeString(payload.source).toLowerCase() === "session_listen";
-}
-
 /**
  * Poll session events in the background and emit only events addressed to
  * the current agent or broadcast to everyone. The loop advances its cursor
@@ -409,7 +402,7 @@ export async function listenSessionEvents({
       if (isRecentActivity(activityMs, observedAtMs, activeWindowMs)) {
         lastHumanActivityMs = Math.max(lastHumanActivityMs, activityMs);
       }
-      if (isListenerLifecycleEvent(event)) continue;
+      if (isSessionListenerLifecycleEvent(event)) continue;
       if (!eventMatchesAgent(event, normalizedAgentId)) continue;
       visibleEvents.push(event);
     }

package/src/session/listeners.js

@@ -56,6 +56,8 @@ export function summarizeListeners(events = [], { nowMs = Date.now(), staleAfter
     const active = Boolean(payload.active);
     const idleIntervalSeconds = positiveInt(payload.idleIntervalSeconds);
     const activeIntervalSeconds = positiveInt(payload.activeIntervalSeconds);
+    const presenceKeepaliveSeconds = positiveInt(payload.presenceKeepaliveSeconds);
+    const presenceIntervalSeconds = positiveInt(payload.presenceIntervalSeconds);
     const nextPollSeconds = positiveInt(payload.nextPollMs)
       ? Math.round(positiveInt(payload.nextPollMs) / 1000)
       : null;
@@ -64,9 +66,20 @@ export function summarizeListeners(events = [], { nowMs = Date.now(), staleAfter
     const cadenceSeconds = active
       ? activeIntervalSeconds || nextPollSeconds
       : idleIntervalSeconds || nextPollSeconds;
+    const expectedPresenceSeconds =
+      presenceKeepaliveSeconds ||
+      presenceIntervalSeconds ||
+      cadenceSeconds ||
+      idleIntervalSeconds ||
+      activeIntervalSeconds ||
+      null;
+    const staleAfterForRowMs = Math.max(
+      staleAfterMs,
+      expectedPresenceSeconds ? expectedPresenceSeconds * 2_500 : 0,
+    );
     let status;
     if (stopped) status = "stopped";
-    else if (ageMs !== null && ageMs > staleAfterMs) status = "stale";
+    else if (ageMs !== null && ageMs > staleAfterForRowMs) status = "stale";
     else status = active ? "active" : "idle";
 
     rows.push({
@@ -78,6 +91,8 @@ export function summarizeListeners(events = [], { nowMs = Date.now(), staleAfter
       cadenceSeconds: cadenceSeconds ?? null,
       idleIntervalSeconds,
       activeIntervalSeconds,
+      presenceIntervalSeconds,
+      presenceKeepaliveSeconds,
       nextPollSeconds,
       lastSeenAt: epoch ? new Date(epoch).toISOString() : null,
       lastSeenAgoSeconds: ageMs !== null ? Math.round(ageMs / 1000) : null,

package/src/session/remote-hydrate.js

@@ -33,6 +33,7 @@ import {
   sessionEventHasKnownIdentity,
   sessionEventUpgradesExisting,
 } from "./event-identity.js";
+import { isSessionControlEvent } from "./control-events.js";
 
 const EVENTS_CURSOR_SUFFIX = "events";
 const DEFAULT_EVENT_PAGE_LIMIT = 200;
@@ -273,6 +274,7 @@ export async function hydrateSessionFromRemote({
   probeOpenCircuit = true,
   eventPageLimit = DEFAULT_EVENT_PAGE_LIMIT,
   maxEventPages = DEFAULT_MAX_EVENT_PAGES,
+  includeControlEvents = false,
 } = {}) {
   if (!sessionId || typeof sessionId !== "string") {
     return {
@@ -392,7 +394,17 @@ export async function hydrateSessionFromRemote({
       newEvents.push(event);
     }
   }
-  if (newEvents.length > 0) {
+  let skippedControlEventCount = 0;
+  const materialNewEvents = [];
+  for (const event of newEvents) {
+    if (!includeControlEvents && isSessionControlEvent(event)) {
+      skippedControlEventCount += 1;
+      addSessionEventIdentityKeys(successfulRelayKeys, event);
+      continue;
+    }
+    materialNewEvents.push(event);
+  }
+  if (materialNewEvents.length > 0) {
     try {
       const localSession = await _ensureLocalSession(sessionId, { targetPath });
       materializedLocalSession = Boolean(localSession?.materialized);
@@ -403,10 +415,11 @@ export async function hydrateSessionFromRemote({
       // returns a structured result.
     }
   }
+
   const appendEvents =
     remoteStatus && !["active", "pending"].includes(remoteStatus)
-      ? newEvents.map((event) => markPostKillEvent(event))
-      : newEvents;
+      ? materialNewEvents.map((event) => markPostKillEvent(event))
+      : materialNewEvents;
   const failedRelayKeys = new Set();
   for (const event of appendEvents) {
     try {
@@ -451,6 +464,7 @@ export async function hydrateSessionFromRemote({
     persistedCursor,
     humanRelayed: (humanResult?.events || []).length,
     eventsRelayed: (eventsResult?.events || []).length,
+    controlEventsSkipped: skippedControlEventCount,
     eventsCursor:
       typeof eventsResult?.cursor === "string" ? eventsResult.cursor : eventsCursor || null,
     eventsPageCount: Number(eventsResult?.pageCount || 0),