sentinelayer-cli 0.11.0 → 0.11.2

package/package.json

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

package/src/commands/session.js

@@ -1397,6 +1397,7 @@ export function registerSessionCommand(program) {
       }
       const persisted = await appendToStream(normalizedSessionId, event, {
         targetPath,
+        syncRemote: !localSession.materialized,
       });
       const payload = {
         command: "session say",
@@ -1768,6 +1769,8 @@ export function registerSessionCommand(program) {
           tail: 0,
         });
         const displayEvents = [...allEvents];
+        let remoteTailAppended = 0;
+        let remoteTailDisplayedOnly = 0;
         if (remoteTail?.ok && Array.isArray(remoteTail.events) && remoteTail.events.length > 0) {
           const knownKeys = new Set();
           for (const event of allEvents) {
@@ -1784,13 +1787,19 @@ export function registerSessionCommand(program) {
               });
               displayEvents.push(appended);
               addSessionEventIdentityKeys(knownKeys, appended);
+              remoteTailAppended += 1;
             } catch {
               displayEvents.push(event);
               addSessionEventIdentityKeys(knownKeys, event);
+              remoteTailDisplayedOnly += 1;
             }
           }
         }
         const events = dedupeSessionEvents(displayEvents).slice(-tail);
+        const remoteVerified = Boolean(
+          options.remote &&
+            ((hydration && hydration.ok) || (remoteTail && remoteTail.ok))
+        );
         const payload = {
           command: "session read",
           targetPath,
@@ -1798,6 +1807,15 @@ export function registerSessionCommand(program) {
           tail,
           count: events.length,
           events,
+          displaySource: !options.remote
+            ? "local"
+            : remoteTail?.ok
+              ? "remote_verified_tail"
+              : hydration?.ok
+                ? "hydrated_local"
+                : "local_only",
+          remoteVerified,
+          localEventCount: allEvents.length,
           remote: hydration
             ? {
                 ...hydration,
@@ -1807,6 +1825,9 @@ export function registerSessionCommand(program) {
                       reason: remoteTail.reason || "",
                       count: Array.isArray(remoteTail.events) ? remoteTail.events.length : 0,
                       cursor: remoteTail.cursor || null,
+                      verified: Boolean(remoteTail.ok),
+                      appended: remoteTailAppended,
+                      displayedOnly: remoteTailDisplayedOnly,
                     }
                   : null,
               }
@@ -2488,6 +2509,8 @@ export function registerSessionCommand(program) {
           count: remote.count,
           nextCursor: remote.nextCursor || null,
           hasMore: Boolean(remote.hasMore),
+          truncated: Boolean(remote.truncated),
+          warnings: Array.isArray(remote.warnings) ? remote.warnings : [],
           sessions: trimmed,
         };
         if (emitJson) {
@@ -2531,6 +2554,13 @@ export function registerSessionCommand(program) {
             ),
           );
         }
+        if (remote.truncated) {
+          console.log(
+            pc.yellow(
+              "Remote session listing is truncated by the page cap; JSON output includes nextCursor for resume.",
+            ),
+          );
+        }
         return;
       }
 

package/src/session/listener.js

@@ -1,7 +1,7 @@
 import { setTimeout as delay } from "node:timers/promises";
 
 import { pollSessionEvents } from "./sync.js";
-import { readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
+import { cursorAdvances, readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
 
 const BROADCAST_RECIPIENTS = new Set([
   "*",
@@ -123,6 +123,19 @@ function cursorFromEvents(events = [], fallbackCursor = null) {
   return cursor;
 }
 
+function eventIdentityKey(event = {}) {
+  const cursor = normalizeString(event?.cursor);
+  if (cursor) return `cursor:${cursor}`;
+  const sequence = normalizeString(event?.sequenceId || event?.sequence_id || event?.sequence);
+  if (sequence) return `sequence:${sequence}`;
+  return JSON.stringify({
+    event: normalizeString(event?.event),
+    agent: normalizeString(event?.agent?.id || event?.agentId),
+    ts: normalizeString(event?.ts || event?.timestamp || event?.createdAt || event?.at),
+    message: normalizeString(event?.payload?.message || event?.payload?.text || event?.payload?.detail),
+  });
+}
+
 function eventTimestampMs(event = {}) {
   for (const key of ["ts", "timestamp", "createdAt", "at"]) {
     const epoch = Date.parse(normalizeString(event?.[key]));
@@ -238,6 +251,7 @@ export async function listenSessionEvents({
   let matched = 0;
   let persistedCursor = false;
   let lastReason = "";
+  const emittedKeys = new Set();
   const maxPollCount = normalizePositiveInteger(maxPolls, 0);
   const pollLimit = normalizePositiveInteger(limit, 200);
   const idleSleepMs = Math.max(1, normalizePositiveInteger(intervalSeconds, 60)) * 1000;
@@ -262,32 +276,46 @@ export async function listenSessionEvents({
     if (result?.ok) {
       lastReason = "";
       const events = Array.isArray(result.events) ? result.events : [];
-      const observedAtMs = Number(_nowMs()) || Date.now();
-      for (const event of events) {
-        const activityMs = humanActivityTimestampMs(event, observedAtMs);
-        if (isRecentActivity(activityMs, observedAtMs, activeWindowMs)) {
-          lastHumanActivityMs = Math.max(lastHumanActivityMs, activityMs);
+      const nextCursor = normalizeString(result.cursor) || cursorFromEvents(events, cursor);
+      const cursorMovedBackward = Boolean(nextCursor && cursor && !cursorAdvances(nextCursor, cursor));
+      if (cursorMovedBackward) {
+        lastReason = "cursor_not_advanced";
+        await onError({
+          ok: false,
+          reason: lastReason,
+          cursor: cursor || null,
+          candidateCursor: nextCursor,
+        });
+      } else {
+        const observedAtMs = Number(_nowMs()) || Date.now();
+        for (const event of events) {
+          const activityMs = humanActivityTimestampMs(event, observedAtMs);
+          if (isRecentActivity(activityMs, observedAtMs, activeWindowMs)) {
+            lastHumanActivityMs = Math.max(lastHumanActivityMs, activityMs);
+          }
+        }
+        const shouldEmitBatch = primed || Boolean(replay);
+        for (const event of events) {
+          if (!eventMatchesAgent(event, normalizedAgentId)) continue;
+          const key = eventIdentityKey(event);
+          if (emittedKeys.has(key)) continue;
+          matched += 1;
+          if (!shouldEmitBatch && eventTimestampMs(event) < startedAtMs) continue;
+          await onEvent(event);
+          emittedKeys.add(key);
+          emitted += 1;
         }
-      }
-      const shouldEmitBatch = primed || Boolean(replay);
-      for (const event of events) {
-        if (!eventMatchesAgent(event, normalizedAgentId)) continue;
-        matched += 1;
-        if (!shouldEmitBatch && eventTimestampMs(event) < startedAtMs) continue;
-        await onEvent(event);
-        emitted += 1;
-      }
 
-      const nextCursor = normalizeString(result.cursor) || cursorFromEvents(events, cursor);
-      if (nextCursor && nextCursor !== cursor) {
-        const writeResult = await _writeCursor(normalizedSessionId, nextCursor, {
-          targetPath,
-          suffix: cursorSuffix,
-        }).catch(() => null);
-        persistedCursor = Boolean(writeResult?.written) || persistedCursor;
-        cursor = nextCursor;
+        if (nextCursor && nextCursor !== cursor) {
+          const writeResult = await _writeCursor(normalizedSessionId, nextCursor, {
+            targetPath,
+            suffix: cursorSuffix,
+          }).catch(() => null);
+          persistedCursor = Boolean(writeResult?.written) || persistedCursor;
+          cursor = nextCursor;
+        }
+        primed = true;
       }
-      primed = true;
     } else {
       lastReason = normalizeString(result?.reason) || "poll_failed";
       await onError({

package/src/session/remote-hydrate.js

@@ -26,7 +26,7 @@ import {
   isSessionCacheExpired,
   refreshSessionCacheForRemoteActivity,
 } from "./store.js";
-import { readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
+import { cursorAdvances, readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
 import {
   addSessionEventIdentityKeys,
   sessionEventHasKnownIdentity,
@@ -166,11 +166,15 @@ async function pollSessionEventPages({
       };
     }
 
-    const pageEvents = Array.isArray(result.events) ? result.events : [];
-    events.push(...pageEvents);
     const nextCursor =
       typeof result.cursor === "string" && result.cursor.trim() ? result.cursor.trim() : cursor;
-    const progressed = nextCursor && nextCursor !== cursor;
+    const progressed = nextCursor && cursorAdvances(nextCursor, cursor);
+    if (nextCursor && cursor && !progressed) {
+      reason = "cursor_not_advanced";
+      break;
+    }
+    const pageEvents = Array.isArray(result.events) ? result.events : [];
+    events.push(...pageEvents);
     cursor = nextCursor || cursor;
 
     if (pageEvents.length < normalizedLimit) {

package/src/session/sync-cursor.js

@@ -46,6 +46,62 @@ export async function readSyncCursor(sessionId, { targetPath, suffix = "" } = {}
   }
 }
 
+function parseStableCursor(cursor) {
+  const normalized = typeof cursor === "string" ? cursor.trim() : "";
+  const match = /^(\d{10,}):([0-9a-fA-F]{1,16})$/.exec(normalized);
+  if (!match) return null;
+  const timeMs = Number(match[1]);
+  const sequence = Number.parseInt(match[2], 16);
+  if (!Number.isFinite(timeMs) || !Number.isFinite(sequence)) return null;
+  return { timeMs, sequence };
+}
+
+function parseIsoCursor(cursor) {
+  const normalized = typeof cursor === "string" ? cursor.trim() : "";
+  if (!normalized || normalized.includes(":") === false) return null;
+  const epoch = Date.parse(normalized);
+  return Number.isFinite(epoch) ? epoch : null;
+}
+
+export function compareSyncCursors(candidate, current) {
+  const next = typeof candidate === "string" ? candidate.trim() : "";
+  const previous = typeof current === "string" ? current.trim() : "";
+  if (!next) return null;
+  if (!previous) return 1;
+  if (next === previous) return 0;
+
+  const nextStable = parseStableCursor(next);
+  const previousStable = parseStableCursor(previous);
+  if (nextStable && previousStable) {
+    if (nextStable.sequence !== previousStable.sequence) {
+      return nextStable.sequence > previousStable.sequence ? 1 : -1;
+    }
+    if (nextStable.timeMs !== previousStable.timeMs) {
+      return nextStable.timeMs > previousStable.timeMs ? 1 : -1;
+    }
+    return 0;
+  }
+
+  const nextIso = parseIsoCursor(next);
+  const previousIso = parseIsoCursor(previous);
+  if (nextIso !== null && previousIso !== null) {
+    if (nextIso === previousIso) return 0;
+    return nextIso > previousIso ? 1 : -1;
+  }
+
+  return null;
+}
+
+export function cursorAdvances(candidate, current) {
+  const comparison = compareSyncCursors(candidate, current);
+  if (comparison === null) {
+    const next = typeof candidate === "string" ? candidate.trim() : "";
+    const previous = typeof current === "string" ? current.trim() : "";
+    return Boolean(next && next !== previous);
+  }
+  return comparison > 0;
+}
+
 /**
  * Persist the human-message cursor for a session. No-op when cursor is
  * empty so we never overwrite a real value with an empty one.
@@ -61,6 +117,26 @@ export async function writeSyncCursor(sessionId, cursor, { targetPath, suffix =
   if (!sessionId || !normalized) {
     return { written: false, path: filePath };
   }
+  const existing = await readSyncCursor(sessionId, { targetPath, suffix });
+  const comparison = compareSyncCursors(normalized, existing);
+  if (existing && comparison !== null && comparison < 0) {
+    return {
+      written: false,
+      path: filePath,
+      reason: "stale_cursor",
+      previousCursor: existing,
+      cursor: normalized,
+    };
+  }
+  if (existing && comparison === 0) {
+    return {
+      written: false,
+      path: filePath,
+      reason: "unchanged",
+      previousCursor: existing,
+      cursor: normalized,
+    };
+  }
   await fsp.mkdir(path.dirname(filePath), { recursive: true });
   const payload = { cursor: normalized, updatedAt: new Date().toISOString() };
   await fsp.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");

package/src/session/sync.js

@@ -1255,7 +1255,7 @@ export async function pollSessionEventsBefore(
  * @param {number} [options.maxPages]
  * @param {Function} [options.resolveAuthSession]
  * @param {Function} [options.fetchImpl]
- * @returns {Promise<{ok: boolean, reason: string, sessions: Array<object>, count: number, nextCursor: string|null, hasMore: boolean}>}
+ * @returns {Promise<{ok: boolean, reason: string, sessions: Array<object>, count: number, nextCursor: string|null, hasMore: boolean, truncated: boolean, warnings: Array<object>}>}
  */
 export async function listSessionsFromApi({
   targetPath = process.cwd(),
@@ -1283,6 +1283,8 @@ export async function listSessionsFromApi({
       count: 0,
       nextCursor: null,
       hasMore: false,
+      truncated: false,
+      warnings: [],
     };
   }
   if (!session || !session.token) {
@@ -1293,6 +1295,8 @@ export async function listSessionsFromApi({
       count: 0,
       nextCursor: null,
       hasMore: false,
+      truncated: false,
+      warnings: [],
     };
   }
 
@@ -1330,6 +1334,8 @@ export async function listSessionsFromApi({
         count: 0,
         nextCursor: null,
         hasMore: false,
+        truncated: false,
+        warnings: [],
       };
     }
     if (!response || !response.ok) {
@@ -1340,6 +1346,8 @@ export async function listSessionsFromApi({
         count: 0,
         nextCursor: null,
         hasMore: false,
+        truncated: false,
+        warnings: [],
       };
     }
     const payload = await response.json().catch(() => ({}));
@@ -1356,6 +1364,18 @@ export async function listSessionsFromApi({
     if (!fetchAll || !hasMore) break;
   }
 
+  const truncated = Boolean(fetchAll && hasMore && nextCursor);
+  const warnings = truncated
+    ? [
+        {
+          code: "SESSION_LIST_MAX_PAGES_REACHED",
+          message: `Session list stopped after ${normalizedMaxPages} pages; output is partial and nextCursor can resume the listing.`,
+          maxPages: normalizedMaxPages,
+          nextCursor,
+        },
+      ]
+    : [];
+
   return {
     ok: true,
     reason: "",
@@ -1363,6 +1383,8 @@ export async function listSessionsFromApi({
     count,
     nextCursor: nextCursor || null,
     hasMore,
+    truncated,
+    warnings,
   };
 }