sentinelayer-cli 0.30.3 → 0.30.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.30.3",
+  "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,
@@ -76,6 +80,8 @@ import { appendToStream, readStream, tailStream } from "../session/stream.js";
 import {
   addSessionEventIdentityKeys,
   dedupeSessionEvents,
+  sessionEventIdentityKeys,
+  sessionEventUpgradesExisting,
   sessionEventHasKnownIdentity,
 } from "../session/event-identity.js";
 import { readSessionPreview } from "../session/preview.js";
@@ -701,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(() => []);
@@ -1602,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,
@@ -1651,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,
@@ -2115,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 {
@@ -2288,6 +2411,7 @@ async function hydrateJoinBriefingContext(sessionId, { targetPath, limit = 100 }
       reason: "",
       remoteEvents: Array.isArray(remoteTail.events) ? remoteTail.events.length : 0,
       appended: appended.appended,
+      upgraded: appended.upgraded,
       skipped: appended.skipped,
       failed: appended.failed,
       cursor: remoteTail.cursor || null,
@@ -2305,6 +2429,34 @@ async function hydrateJoinBriefingContext(sessionId, { targetPath, limit = 100 }
   }
 }
 
+function remoteSessionEventUpgradesLocal(localEvent = {}, remoteEvent = {}) {
+  return sessionEventUpgradesExisting(localEvent, remoteEvent);
+}
+
+function indexSessionEventIdentityKeys(indexByKey, eventList = [], event = {}, index = -1) {
+  if (!indexByKey || !Array.isArray(eventList) || index < 0) return;
+  for (const key of sessionEventIdentityKeys(event)) {
+    const existingIndex = indexByKey.get(key);
+    const existingEvent = Number.isInteger(existingIndex) && existingIndex >= 0
+      ? eventList[existingIndex]
+      : null;
+    if (!existingEvent || remoteSessionEventUpgradesLocal(existingEvent, event)) {
+      indexByKey.set(key, index);
+    }
+  }
+}
+
+function findSessionEventIdentityIndex(indexByKey, event = {}) {
+  if (!indexByKey) return -1;
+  for (const key of sessionEventIdentityKeys(event)) {
+    const index = indexByKey.get(key);
+    if (Number.isInteger(index) && index >= 0) {
+      return index;
+    }
+  }
+  return -1;
+}
+
 async function appendMissingRemoteEvents(sessionId, remoteEvents = [], { targetPath } = {}) {
   const events = Array.isArray(remoteEvents) ? remoteEvents : [];
   if (events.length === 0) {
@@ -2315,18 +2467,47 @@ async function appendMissingRemoteEvents(sessionId, remoteEvents = [], { targetP
     };
   }
   const knownKeys = new Set();
+  const localIndexByKey = new Map();
   const localEvents = await readStream(sessionId, {
     targetPath,
     tail: 0,
   });
-  for (const event of localEvents) {
+  for (const [index, event] of localEvents.entries()) {
     addSessionEventIdentityKeys(knownKeys, event);
+    indexSessionEventIdentityKeys(localIndexByKey, localEvents, event, index);
   }
 
   let appended = 0;
+  let upgraded = 0;
   let skipped = 0;
   let failed = 0;
   for (const event of events) {
+    const existingIndex = findSessionEventIdentityIndex(localIndexByKey, event);
+    if (existingIndex >= 0) {
+      const existing = localEvents[existingIndex];
+      if (!remoteSessionEventUpgradesLocal(existing, event)) {
+        skipped += 1;
+        continue;
+      }
+      // Keep the richer canonical API row in local history when it
+      // upgrades an optimistic/local post that had no durable cursor yet.
+      // Future reads can then page by sequence instead of rediscovering the
+      // upgrade every time.
+      try {
+        const persisted = await appendToStream(sessionId, event, {
+          targetPath,
+          syncRemote: false,
+        });
+        localEvents.push(persisted);
+        addSessionEventIdentityKeys(knownKeys, persisted);
+        indexSessionEventIdentityKeys(localIndexByKey, localEvents, persisted, localEvents.length - 1);
+        upgraded += 1;
+      } catch {
+        addSessionEventIdentityKeys(knownKeys, event);
+        failed += 1;
+      }
+      continue;
+    }
     if (sessionEventHasKnownIdentity(event, knownKeys)) {
       skipped += 1;
       continue;
@@ -2345,6 +2526,7 @@ async function appendMissingRemoteEvents(sessionId, remoteEvents = [], { targetP
   }
   return {
     appended,
+    upgraded,
     skipped,
     failed,
   };
@@ -3998,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",
@@ -4050,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,
@@ -4132,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
@@ -4314,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({
@@ -4330,7 +4539,7 @@ export function registerSessionCommand(program) {
               provider,
               clientKind,
               listenerId,
-              lifecycle,
+              lifecycle: publishLifecycle,
             });
           },
         });
@@ -4853,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;
@@ -4874,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) {
@@ -4954,12 +5162,29 @@ export function registerSessionCommand(program) {
         const displayEvents = [...allEvents];
         let remoteTailAppended = 0;
         let remoteTailDisplayedOnly = 0;
-        if (remoteTail?.ok && Array.isArray(remoteTail.events) && remoteTail.events.length > 0) {
+        let remoteTailUpgraded = 0;
+        const remoteTailAppendEvents = includeControlEvents
+          ? remoteTail?.events
+          : filterSessionMaterialEvents(remoteTail?.events || []);
+        if (remoteTail?.ok && Array.isArray(remoteTailAppendEvents) && remoteTailAppendEvents.length > 0) {
           const knownKeys = new Set();
-          for (const event of allEvents) {
+          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];
+              if (remoteSessionEventUpgradesLocal(existing, event)) {
+                displayEvents[existingIndex] = event;
+                addSessionEventIdentityKeys(knownKeys, event);
+                indexSessionEventIdentityKeys(displayIndexByKey, displayEvents, event, existingIndex);
+                remoteTailUpgraded += 1;
+              }
+              continue;
+            }
             if (sessionEventHasKnownIdentity(event, knownKeys)) {
               continue;
             }
@@ -4970,10 +5195,12 @@ export function registerSessionCommand(program) {
               });
               displayEvents.push(appended);
               addSessionEventIdentityKeys(knownKeys, appended);
+              indexSessionEventIdentityKeys(displayIndexByKey, displayEvents, appended, displayEvents.length - 1);
               remoteTailAppended += 1;
             } catch {
               displayEvents.push(event);
               addSessionEventIdentityKeys(knownKeys, event);
+              indexSessionEventIdentityKeys(displayIndexByKey, displayEvents, event, displayEvents.length - 1);
               remoteTailDisplayedOnly += 1;
             }
           }
@@ -4987,10 +5214,11 @@ export function registerSessionCommand(program) {
         const recentHumanActivity = remoteActions?.ok
           ? readProjectionRecentHumanActivity(remoteActions)
           : [];
+        const dedupedDisplayEvents = dedupeSessionEvents(displayEvents);
         const transcriptEvents = includeControlEvents
-          ? displayEvents
-          : displayEvents.filter((event) => !isSessionControlEvent(event));
-        const hiddenControlEventCount = displayEvents.length - transcriptEvents.length;
+          ? dedupedDisplayEvents
+          : dedupedDisplayEvents.filter((event) => !isSessionControlEvent(event));
+        const hiddenControlEventCount = dedupedDisplayEvents.length - transcriptEvents.length;
         const events = mergeSessionActionEvents(transcriptEvents, actionEvents).slice(-tail);
         const autoView = recordSessionReadViews(normalizedSessionId, events, {
           targetPath,
@@ -5037,9 +5265,12 @@ 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,
+                      upgraded: remoteTailUpgraded,
                       controlEventCount: remoteTailStats?.controlEventCount || 0,
                       materialEventCount: remoteTailStats?.materialEventCount || 0,
                       latestEvent: remoteTailStats?.latestEvent || null,
@@ -5111,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 {
@@ -5139,6 +5371,9 @@ export function registerSessionCommand(program) {
           continue;
         }
         addSessionEventIdentityKeys(seenFollowEvents, event);
+        if (!includeControlEvents && isSessionControlEvent(event)) {
+          continue;
+        }
         if (emitJson) {
           console.log(JSON.stringify(event));
         } else {
@@ -5580,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);
@@ -5597,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, {
@@ -5629,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,
@@ -5643,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 }));
@@ -5684,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,
@@ -5704,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 {
@@ -5727,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) => {
@@ -5743,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, {
@@ -5765,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
@@ -5830,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,
@@ -5861,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/event-identity.js

@@ -15,6 +15,24 @@ function timestampKey(...values) {
   return "";
 }
 
+export function readSessionEventSequence(event = {}) {
+  const value = Number(event?.sequenceId ?? event?.sequence_id ?? event?.sequence);
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+
+export function sessionEventHasDurableCursor(event = {}) {
+  return Boolean(keyString(event?.cursor));
+}
+
+export function sessionEventUpgradesExisting(existingEvent = {}, candidateEvent = {}) {
+  const existingSequence = readSessionEventSequence(existingEvent);
+  const candidateSequence = readSessionEventSequence(candidateEvent);
+  if (candidateSequence > 0 && existingSequence <= 0) {
+    return true;
+  }
+  return sessionEventHasDurableCursor(candidateEvent) && !sessionEventHasDurableCursor(existingEvent);
+}
+
 function stableJsonValue(value) {
   if (Array.isArray(value)) {
     return value.map((item) => stableJsonValue(item));
@@ -51,6 +69,10 @@ export function sessionEventIdentityKeys(event = {}) {
     keys.push(`idempotency:${event.idempotencyToken.trim()}`);
   }
   const payload = event.payload && typeof event.payload === "object" ? event.payload : {};
+  const clientMessageId = typeof payload.clientMessageId === "string" ? payload.clientMessageId.trim() : "";
+  if (clientMessageId) {
+    keys.push(`client-message:${clientMessageId}`);
+  }
   const messageId = typeof payload.messageId === "string" ? payload.messageId.trim() : "";
   if (messageId) {
     keys.push(`message:${messageId}`);

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

@@ -29,20 +29,49 @@ import {
 import { cursorAdvances, readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
 import {
   addSessionEventIdentityKeys,
+  sessionEventIdentityKeys,
   sessionEventHasKnownIdentity,
+  sessionEventUpgradesExisting,
 } from "./event-identity.js";
+import { isSessionControlEvent } from "./control-events.js";
 
 const EVENTS_CURSOR_SUFFIX = "events";
 const DEFAULT_EVENT_PAGE_LIMIT = 200;
 const DEFAULT_MAX_EVENT_PAGES = 25;
 
-async function readExistingRelayKeys(sessionId, { targetPath = process.cwd() } = {}) {
+function indexRelayEventIdentityKeys(indexByKey, eventList = [], event = {}, index = -1) {
+  if (!indexByKey || !Array.isArray(eventList) || index < 0) return;
+  for (const key of sessionEventIdentityKeys(event)) {
+    const existingIndex = indexByKey.get(key);
+    const existingEvent = Number.isInteger(existingIndex) && existingIndex >= 0
+      ? eventList[existingIndex]
+      : null;
+    if (!existingEvent || sessionEventUpgradesExisting(existingEvent, event)) {
+      indexByKey.set(key, index);
+    }
+  }
+}
+
+function findRelayEventIdentityIndex(indexByKey, event = {}) {
+  if (!indexByKey) return -1;
+  for (const key of sessionEventIdentityKeys(event)) {
+    const index = indexByKey.get(key);
+    if (Number.isInteger(index) && index >= 0) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+async function readExistingRelayState(sessionId, { targetPath = process.cwd() } = {}) {
   const knownKeys = new Set();
   const events = await readStream(sessionId, { targetPath, tail: 0 }).catch(() => []);
-  for (const event of events) {
+  const indexByKey = new Map();
+  for (const [index, event] of events.entries()) {
     addSessionEventIdentityKeys(knownKeys, event);
+    indexRelayEventIdentityKeys(indexByKey, events, event, index);
   }
-  return knownKeys;
+  return { knownKeys, events, indexByKey };
 }
 
 async function ensureLocalSessionShell(sessionId, { targetPath = process.cwd() } = {}) {
@@ -92,10 +121,13 @@ async function ensureLocalSessionShell(sessionId, { targetPath = process.cwd() }
   return { materialized: true, refreshed: false, session: created, remoteStatus };
 }
 
-function sourceFullyRelayed(events = [], successfulKeys = new Set()) {
+function sourceFullyRelayed(events = [], successfulKeys = new Set(), failedKeys = new Set()) {
   const relayedEvents = Array.isArray(events) ? events : [];
   if (relayedEvents.length === 0) return true;
-  return relayedEvents.every((event) => sessionEventHasKnownIdentity(event, successfulKeys));
+  return relayedEvents.every((event) =>
+    !sessionEventHasKnownIdentity(event, failedKeys) &&
+    sessionEventHasKnownIdentity(event, successfulKeys)
+  );
 }
 
 function markPostKillEvent(event = {}) {
@@ -242,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 {
@@ -341,12 +374,37 @@ export async function hydrateSessionFromRemote({
   let relayed = 0;
   let materializedLocalSession = false;
   let remoteStatus = "";
-  const successfulRelayKeys =
-    merged.length > 0 ? await readExistingRelayKeys(sessionId, { targetPath }) : new Set();
-  const newEvents = successfulRelayKeys.size > 0
-    ? merged.filter((event) => !sessionEventHasKnownIdentity(event, successfulRelayKeys))
-    : merged;
-  if (newEvents.length > 0) {
+  const relayState = merged.length > 0
+    ? await readExistingRelayState(sessionId, { targetPath })
+    : { knownKeys: new Set(), events: [], indexByKey: new Map() };
+  const successfulRelayKeys = relayState.knownKeys;
+  const existingRelayEvents = relayState.events;
+  const existingRelayIndexByKey = relayState.indexByKey;
+  const newEvents = [];
+  for (const event of merged) {
+    const existingIndex = findRelayEventIdentityIndex(existingRelayIndexByKey, event);
+    if (existingIndex >= 0) {
+      const existing = existingRelayEvents[existingIndex];
+      if (sessionEventUpgradesExisting(existing, event)) {
+        newEvents.push(event);
+      }
+      continue;
+    }
+    if (!sessionEventHasKnownIdentity(event, successfulRelayKeys)) {
+      newEvents.push(event);
+    }
+  }
+  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);
@@ -357,24 +415,35 @@ 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 {
-      await _append(sessionId, event, { targetPath, syncRemote: false });
+      const persisted = await _append(sessionId, event, { targetPath, syncRemote: false });
       relayed += 1;
-      addSessionEventIdentityKeys(successfulRelayKeys, event);
+      const persistedEvent = persisted && typeof persisted === "object" ? persisted : event;
+      existingRelayEvents.push(persistedEvent);
+      addSessionEventIdentityKeys(successfulRelayKeys, persistedEvent);
+      indexRelayEventIdentityKeys(
+        existingRelayIndexByKey,
+        existingRelayEvents,
+        persistedEvent,
+        existingRelayEvents.length - 1,
+      );
     } catch {
+      addSessionEventIdentityKeys(failedRelayKeys, event);
       // Append errors are observable via the stream but should not
       // abort the rest of the batch — partial relay is still progress.
     }
   }
 
   let persistedCursor = false;
-  const humanCursorSafe = sourceFullyRelayed(humanResult?.events || [], successfulRelayKeys);
-  const eventsCursorSafe = sourceFullyRelayed(eventsResult?.events || [], successfulRelayKeys);
+  const humanCursorSafe = sourceFullyRelayed(humanResult?.events || [], successfulRelayKeys, failedRelayKeys);
+  const eventsCursorSafe = sourceFullyRelayed(eventsResult?.events || [], successfulRelayKeys, failedRelayKeys);
   if (humanCursorSafe && typeof humanResult?.cursor === "string" && humanResult.cursor.trim()) {
     const result = await writeSyncCursor(sessionId, humanResult.cursor, { targetPath }).catch(() => null);
     persistedCursor = Boolean(result && result.written);
@@ -395,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),