sentinelayer-cli 0.30.3 → 0.30.4

package/package.json

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

package/src/commands/session.js

@@ -76,6 +76,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";
@@ -2288,6 +2290,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 +2308,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 +2346,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 +2405,7 @@ async function appendMissingRemoteEvents(sessionId, remoteEvents = [], { targetP
   }
   return {
     appended,
+    upgraded,
     skipped,
     failed,
   };
@@ -4954,12 +5015,26 @@ export function registerSessionCommand(program) {
         const displayEvents = [...allEvents];
         let remoteTailAppended = 0;
         let remoteTailDisplayedOnly = 0;
+        let remoteTailUpgraded = 0;
         if (remoteTail?.ok && Array.isArray(remoteTail.events) && remoteTail.events.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) {
+            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 +5045,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 +5064,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,
@@ -5040,6 +5118,7 @@ export function registerSessionCommand(program) {
                       verified: Boolean(remoteTail.ok),
                       appended: remoteTailAppended,
                       displayedOnly: remoteTailDisplayedOnly,
+                      upgraded: remoteTailUpgraded,
                       controlEventCount: remoteTailStats?.controlEventCount || 0,
                       materialEventCount: remoteTailStats?.materialEventCount || 0,
                       latestEvent: remoteTailStats?.latestEvent || null,

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/remote-hydrate.js

@@ -29,20 +29,48 @@ import {
 import { cursorAdvances, readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
 import {
   addSessionEventIdentityKeys,
+  sessionEventIdentityKeys,
   sessionEventHasKnownIdentity,
+  sessionEventUpgradesExisting,
 } from "./event-identity.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 +120,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 = {}) {
@@ -341,11 +372,26 @@ 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;
+  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);
+    }
+  }
   if (newEvents.length > 0) {
     try {
       const localSession = await _ensureLocalSession(sessionId, { targetPath });
@@ -361,20 +407,30 @@ export async function hydrateSessionFromRemote({
     remoteStatus && !["active", "pending"].includes(remoteStatus)
       ? newEvents.map((event) => markPostKillEvent(event))
       : newEvents;
+  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);