sentinelayer-cli 0.30.2 → 0.30.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.30.2",
+  "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

@@ -32,6 +32,7 @@ import {
   registerAgent,
   unregisterAgent,
 } from "../session/agent-registry.js";
+import { inferSessionAgentIdentity } from "../session/agent-identity.js";
 import { startSenti, stopSenti } from "../session/daemon.js";
 import {
   getDaemonStatus,
@@ -75,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";
@@ -1607,20 +1610,30 @@ async function publishListenerPresenceEvent({
   agentId,
   agentModel = "cli",
   displayName = "",
+  provider = "",
+  clientKind = "cli",
   listenerId,
   lifecycle = {},
 } = {}) {
   const normalizedType = normalizeString(lifecycle.type) || "heartbeat";
   const eventName = listenerLifecycleEventName(normalizedType);
+  const identity = inferSessionAgentIdentity({
+    agentId,
+    model: agentModel,
+    displayName,
+    provider,
+    clientKind,
+  });
   const event = createAgentEvent({
     event: eventName,
     sessionId,
     agent: {
       id: agentId,
-      model: normalizeString(agentModel) || "cli",
+      model: normalizeString(identity.model) || "cli",
       role: "listener",
-      displayName: normalizeString(displayName) || agentId,
-      clientKind: "cli",
+      displayName: normalizeString(identity.displayName) || agentId,
+      provider: normalizeString(identity.provider) || undefined,
+      clientKind: normalizeString(identity.clientKind) || "cli",
     },
     eventId: `session-listener-${listenerId}-${normalizedType}-${lifecycle.pollCount ?? 0}`,
     idempotencyToken: `session-listener:${listenerId}:${normalizedType}:${lifecycle.pollCount ?? 0}`,
@@ -1676,20 +1689,30 @@ export function buildSessionCoachingEvent({
   agentId,
   agentModel = "cli",
   displayName = "",
+  provider = "",
+  clientKind = "cli",
   listenerId = "",
   tick = 0,
   tips = SESSION_LIVE_SUCCESS_TIPS,
 } = {}) {
   const tipList = Array.isArray(tips) && tips.length ? tips : SESSION_LIVE_SUCCESS_TIPS;
+  const identity = inferSessionAgentIdentity({
+    agentId,
+    model: agentModel,
+    displayName,
+    provider,
+    clientKind,
+  });
   return createAgentEvent({
     event: "session_coaching",
     sessionId,
     agent: {
       id: agentId,
-      model: normalizeString(agentModel) || "cli",
+      model: normalizeString(identity.model) || "cli",
       role: "listener",
-      displayName: normalizeString(displayName) || agentId,
-      clientKind: "cli",
+      displayName: normalizeString(identity.displayName) || agentId,
+      provider: normalizeString(identity.provider) || undefined,
+      clientKind: normalizeString(identity.clientKind) || "cli",
     },
     eventId: `session-coaching-${listenerId || agentId}-${tick}`,
     idempotencyToken: `session-coaching:${listenerId || agentId}:${tick}`,
@@ -1707,20 +1730,30 @@ function buildListenerCatchupEvent({
   agentId,
   agentModel = "cli",
   displayName = "",
+  provider = "",
+  clientKind = "cli",
   listenerId,
   catchup = {},
 } = {}) {
   const message = formatListenerCatchupNotice(catchup);
   const pollCount = Number(catchup.pollCount || 0);
+  const identity = inferSessionAgentIdentity({
+    agentId,
+    model: agentModel,
+    displayName,
+    provider,
+    clientKind,
+  });
   return createAgentEvent({
     event: "session_listen_catchup",
     sessionId,
     agent: {
       id: agentId,
-      model: normalizeString(agentModel) || "cli",
+      model: normalizeString(identity.model) || "cli",
       role: "listener",
-      displayName: normalizeString(displayName) || agentId,
-      clientKind: "cli",
+      displayName: normalizeString(identity.displayName) || agentId,
+      provider: normalizeString(identity.provider) || undefined,
+      clientKind: normalizeString(identity.clientKind) || "cli",
     },
     eventId: `session-listener-${listenerId}-catchup-${pollCount}`,
     idempotencyToken: `session-listener:${listenerId}:catchup:${pollCount}`,
@@ -1959,6 +1992,9 @@ async function ensureSessionSayAgentRegistered(
   const registered = await rememberAgentIdentity(sessionId, {
     agentId,
     model: normalizeString(agent.model) || "cli",
+    displayName: normalizeString(agent.displayName),
+    provider: normalizeString(agent.provider),
+    clientKind: normalizeString(agent.clientKind) || "cli",
     role: sessionSayRegistryRole(agent.role),
     targetPath,
   });
@@ -1995,12 +2031,24 @@ async function resolveSessionAgentEnvelope(
   const resolvedRole = normalizeString(role) || normalizeString(registeredAgent?.role);
   const resolvedDisplayName =
     normalizeString(displayName) || normalizeString(registeredAgent?.displayName);
+  const identity = inferSessionAgentIdentity({
+    agentId: normalizedAgentId,
+    model: resolvedModel,
+    displayName: resolvedDisplayName,
+    provider: registeredAgent?.provider,
+    clientKind: normalizeString(clientKind) || normalizeString(registeredAgent?.clientKind) || "cli",
+  });
   const envelope = {
     id: normalizedAgentId,
-    model: resolvedModel || undefined,
+    model: normalizeString(identity.model) || resolvedModel || undefined,
     role: resolvedRole || undefined,
-    displayName: resolvedDisplayName || undefined,
-    clientKind: normalizeString(clientKind) || undefined,
+    displayName: normalizeString(identity.displayName) || resolvedDisplayName || undefined,
+    provider: normalizeString(identity.provider) || undefined,
+    clientKind:
+      normalizeString(identity.clientKind) ||
+      normalizeString(clientKind) ||
+      normalizeString(registeredAgent?.clientKind) ||
+      undefined,
   };
   return Object.fromEntries(Object.entries(envelope).filter(([, value]) => value !== undefined));
 }
@@ -2242,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,
@@ -2259,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) {
@@ -2269,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;
@@ -2299,6 +2405,7 @@ async function appendMissingRemoteEvents(sessionId, remoteEvents = [], { targetP
   }
   return {
     appended,
+    upgraded,
     skipped,
     failed,
   };
@@ -3021,6 +3128,8 @@ export function registerSessionCommand(program) {
         targetPath,
         agentId: resolvedAgentId,
         model,
+        displayName: normalizeString(acceptedOnboarding?.displayName),
+        clientKind: "cli",
         role,
         trackProcessExit: false,
         awaitRemoteSync: hasConcreteAgentIdentity,
@@ -3059,6 +3168,9 @@ export function registerSessionCommand(program) {
         agentId: joined.agentId,
         role: joined.role,
         model: joined.model,
+        displayName: joined.displayName || null,
+        provider: joined.provider || null,
+        clientKind: joined.clientKind || null,
         status: joined.status,
         joinedAt: joined.joinedAt,
         materializedLocalSession: localSession.materialized,
@@ -3305,12 +3417,19 @@ export function registerSessionCommand(program) {
       if (to) {
         eventPayload.to = to;
       }
+      const agentIdentity = inferSessionAgentIdentity({
+        agentId,
+        model: options.model,
+        displayName: options.displayName,
+        clientKind: "cli",
+      });
       const agent = {
         id: agentId,
-        model: normalizeString(options.model) || "cli",
-        displayName: normalizeString(options.displayName) || undefined,
+        model: normalizeString(agentIdentity.model) || "cli",
+        displayName: normalizeString(agentIdentity.displayName) || undefined,
+        provider: normalizeString(agentIdentity.provider) || undefined,
         role: normalizeString(options.role) || "coder",
-        clientKind: "cli",
+        clientKind: normalizeString(agentIdentity.clientKind) || "cli",
       };
       const event = createAgentEvent({
         event: "session_message",
@@ -3992,8 +4111,16 @@ export function registerSessionCommand(program) {
         "presence-interval",
         60,
       );
-      const agentModel = normalizeString(options.model) || "cli";
-      const displayName = normalizeString(options.displayName) || agentId;
+      const listenerIdentity = inferSessionAgentIdentity({
+        agentId,
+        model: options.model,
+        displayName: options.displayName,
+        clientKind: "cli",
+      });
+      const agentModel = normalizeString(listenerIdentity.model) || "cli";
+      const displayName = normalizeString(listenerIdentity.displayName) || agentId;
+      const provider = normalizeString(listenerIdentity.provider);
+      const clientKind = normalizeString(listenerIdentity.clientKind) || "cli";
       const limit = parsePositiveInteger(options.limit, "limit", 200);
       const emitFormat = normalizeString(options.emit).toLowerCase() || "ndjson";
       if (!["ndjson", "text"].includes(emitFormat)) {
@@ -4085,6 +4212,8 @@ export function registerSessionCommand(program) {
                 agentId,
                 agentModel,
                 displayName,
+                provider,
+                clientKind,
                 listenerId,
                 tick: coachingTick++,
               }),
@@ -4155,6 +4284,8 @@ export function registerSessionCommand(program) {
                     agentId,
                     agentModel,
                     displayName,
+                    provider,
+                    clientKind,
                     listenerId,
                     catchup,
                   }),
@@ -4257,6 +4388,8 @@ export function registerSessionCommand(program) {
               agentId,
               agentModel,
               displayName,
+              provider,
+              clientKind,
               listenerId,
               lifecycle,
             });
@@ -4882,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;
             }
@@ -4898,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;
             }
           }
@@ -4915,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,
@@ -4968,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/agent-identity.js

@@ -0,0 +1,119 @@
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeLookup(value) {
+  return normalizeString(value).toLowerCase();
+}
+
+function titleFromIdentifier(value) {
+  const parts = normalizeString(value)
+    .replace(/[_-]+/g, " ")
+    .split(/\s+/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (!parts.length) return "";
+  return parts
+    .map((part) => {
+      if (/^[0-9]+$/.test(part)) return part;
+      return `${part.charAt(0).toUpperCase()}${part.slice(1)}`;
+    })
+    .join(" ");
+}
+
+function isWeakModel(value) {
+  const normalized = normalizeLookup(value);
+  return !normalized || ["anonymous", "cli", "unknown", "unreported"].includes(normalized);
+}
+
+function inferFamily(agentId, model) {
+  const haystack = `${agentId} ${model}`.toLowerCase();
+  if (haystack.includes("claude") || haystack.includes("sonnet") || haystack.includes("opus")) {
+    return "claude";
+  }
+  if (haystack.includes("codex") || haystack.includes("gpt-") || haystack.includes("openai")) {
+    return "codex";
+  }
+  if (haystack.includes("gemini") || haystack.includes("google")) return "gemini";
+  if (haystack.includes("grok") || haystack.includes("xai")) return "grok";
+  if (haystack.includes("senti") || haystack.includes("sentinelayer")) return "senti";
+  return "";
+}
+
+function inferModel(family) {
+  if (family === "codex") return "gpt-5-codex";
+  if (family === "claude") return "claude";
+  if (family === "gemini") return "gemini";
+  if (family === "grok") return "grok";
+  if (family === "senti") return "gpt-5.4-mini";
+  return "";
+}
+
+function inferProvider(family, model) {
+  const normalizedModel = normalizeLookup(model);
+  if (family === "claude" || normalizedModel.includes("claude")) return "anthropic";
+  if (family === "codex" || normalizedModel.includes("gpt") || normalizedModel.includes("openai")) {
+    return "openai";
+  }
+  if (family === "gemini" || normalizedModel.includes("gemini")) return "google";
+  if (family === "grok" || normalizedModel.includes("grok")) return "xai";
+  if (family === "senti") return "sentinelayer";
+  return "";
+}
+
+function inferClientKind(family) {
+  if (family === "codex") return "codex";
+  if (family === "claude") return "claude";
+  if (family === "gemini") return "gemini";
+  if (family === "grok") return "grok";
+  if (family === "senti") return "senti";
+  return "";
+}
+
+function inferDisplayName(agentId, family) {
+  const normalizedId = normalizeLookup(agentId);
+  if (normalizedId === "senti") return "Senti";
+  if (normalizedId.includes("claude-verifier")) return "Claude Verifier";
+  if (normalizedId.startsWith("claude")) return "Claude";
+  if (normalizedId.startsWith("codex")) return "Codex";
+  if (normalizedId.startsWith("gemini")) return "Gemini";
+  if (normalizedId.startsWith("grok")) return "Grok";
+  if (family) return titleFromIdentifier(family);
+  return titleFromIdentifier(agentId);
+}
+
+export function inferSessionAgentIdentity(input = {}) {
+  const source =
+    input && typeof input === "object" && !Array.isArray(input)
+      ? input
+      : {};
+  const {
+    agentId = "",
+    model = "",
+    displayName = "",
+    provider = "",
+    clientKind = "",
+  } = source;
+  const normalizedAgentId = normalizeString(agentId);
+  const explicitModel = normalizeString(model);
+  const family = inferFamily(normalizedAgentId, explicitModel);
+  const resolvedModel = isWeakModel(explicitModel)
+    ? inferModel(family) || explicitModel || "unknown"
+    : explicitModel;
+  const resolvedProvider = normalizeString(provider) || inferProvider(family, resolvedModel);
+  const resolvedClientKind = normalizeString(clientKind) || inferClientKind(family) || "cli";
+  const resolvedDisplayName =
+    normalizeString(displayName) || inferDisplayName(normalizedAgentId, family);
+
+  return Object.fromEntries(
+    Object.entries({
+      agentId: normalizedAgentId,
+      model: resolvedModel,
+      displayName: resolvedDisplayName,
+      provider: resolvedProvider,
+      clientKind: resolvedClientKind,
+    }).filter(([, value]) => normalizeString(value)),
+  );
+}
+
+export { titleFromIdentifier };

package/src/session/agent-registry.js

@@ -5,6 +5,7 @@ import process from "node:process";
 
 import { STUCK_THRESHOLDS } from "../agents/jules/pulse.js";
 import { createAgentEvent } from "../events/schema.js";
+import { inferSessionAgentIdentity } from "./agent-identity.js";
 import { resolveSessionPaths } from "./paths.js";
 import { emitContextBriefing } from "./recap.js";
 import {
@@ -120,6 +121,9 @@ function normalizeAgentSnapshot(snapshot = {}, nowIso = new Date().toISOString()
     sessionId: normalizeString(snapshot.sessionId),
     agentId: normalizeString(snapshot.agentId),
     model: normalizeString(snapshot.model) || "unknown",
+    displayName: normalizeString(snapshot.displayName) || "",
+    provider: normalizeString(snapshot.provider) || "",
+    clientKind: normalizeString(snapshot.clientKind) || "",
     role: normalizeRole(snapshot.role || "observer"),
     status: normalizeStatus(snapshot.status, "idle"),
     detail: normalizeString(snapshot.detail) || "",
@@ -149,13 +153,30 @@ async function readAgentSnapshot(snapshotPath) {
   }
 }
 
-async function writeAgentSnapshot(snapshotPath, snapshot) {
+const _snapshotWriteQueues = new Map();
+
+async function writeAgentSnapshotFile(snapshotPath, snapshot) {
   await fsp.mkdir(path.dirname(snapshotPath), { recursive: true });
-  const tmpPath = `${snapshotPath}.${process.pid}.${Date.now()}.tmp`;
+  const tmpPath = `${snapshotPath}.${process.pid}.${Date.now()}.${randomBytes(4).toString("hex")}.tmp`;
   await fsp.writeFile(tmpPath, `${JSON.stringify(snapshot, null, 2)}\n`, "utf-8");
   await fsp.rename(tmpPath, snapshotPath);
 }
 
+async function writeAgentSnapshot(snapshotPath, snapshot) {
+  const previous = _snapshotWriteQueues.get(snapshotPath) || Promise.resolve();
+  const write = previous
+    .catch(() => {})
+    .then(() => writeAgentSnapshotFile(snapshotPath, snapshot));
+  _snapshotWriteQueues.set(snapshotPath, write);
+  try {
+    await write;
+  } finally {
+    if (_snapshotWriteQueues.get(snapshotPath) === write) {
+      _snapshotWriteQueues.delete(snapshotPath);
+    }
+  }
+}
+
 async function emitAgentEvent(
   sessionId,
   event,
@@ -164,7 +185,14 @@ async function emitAgentEvent(
 ) {
   const envelope = createAgentEvent({
     event,
-    agentId: payload.agentId,
+    agent: {
+      id: payload.agentId,
+      model: payload.model,
+      displayName: payload.displayName,
+      provider: payload.provider,
+      role: payload.role,
+      clientKind: payload.clientKind,
+    },
     sessionId,
     payload,
   });
@@ -198,13 +226,15 @@ function isActiveAgentSnapshot(snapshot) {
   return true;
 }
 
-function chooseAgentRefreshModel(value, existingModel) {
+function chooseAgentRefreshModel(value, existingModel, sourceValue = value) {
   const candidate = normalizeString(value);
   const existing = normalizeString(existingModel);
+  const source = normalizeString(sourceValue).toLowerCase();
+  const sourceIsWeak = !source || ["anonymous", "cli", "unknown", "unreported"].includes(source);
   if (!candidate) {
     return existing || "unknown";
   }
-  if (existing && ["cli", "unknown"].includes(candidate.toLowerCase())) {
+  if (existing && (sourceIsWeak || ["cli", "unknown"].includes(candidate.toLowerCase()))) {
     return existing;
   }
   return candidate;
@@ -222,6 +252,19 @@ function chooseAgentRefreshRole(value, existingRole) {
   return candidate;
 }
 
+function chooseAgentRefreshMetadata(value, existingValue, sourceValue = value) {
+  const candidate = normalizeString(value);
+  const existing = normalizeString(existingValue);
+  const source = normalizeString(sourceValue);
+  if (!candidate) {
+    return existing;
+  }
+  if (existing && !source) {
+    return existing;
+  }
+  return candidate;
+}
+
 // In-process registry of agents registered by *this* CLI process. The
 // dashboard treats any participant without a terminal agent_leave /
 // agent_killed / session_killed event as "active". When a CLI exits via
@@ -283,6 +326,9 @@ export async function registerAgent(
   {
     agentId = "",
     model = "",
+    displayName = "",
+    provider = "",
+    clientKind = "",
     role = "observer",
     targetPath = process.cwd(),
     trackProcessExit = true,
@@ -311,6 +357,14 @@ export async function registerAgent(
     }
   }
 
+  const identity = inferSessionAgentIdentity({
+    agentId: resolvedAgentId,
+    model,
+    displayName,
+    provider,
+    clientKind,
+  });
+
   const snapshotPath = buildAgentSnapshotPath(paths, resolvedAgentId);
   const existing = await readAgentSnapshot(snapshotPath);
 
@@ -320,7 +374,10 @@ export async function registerAgent(
         ...existing,
         sessionId: paths.sessionId,
         agentId: resolvedAgentId,
-        model: chooseAgentRefreshModel(model, existing.model),
+        model: chooseAgentRefreshModel(identity.model, existing.model, model),
+        displayName: chooseAgentRefreshMetadata(identity.displayName, existing.displayName, displayName),
+        provider: chooseAgentRefreshMetadata(identity.provider, existing.provider, provider),
+        clientKind: chooseAgentRefreshMetadata(identity.clientKind, existing.clientKind, clientKind),
         role: chooseAgentRefreshRole(role, existing.role),
         status: normalizeString(existing.status) || "idle",
         detail: normalizeString(existing.detail) || "",
@@ -350,7 +407,10 @@ export async function registerAgent(
     {
       sessionId: paths.sessionId,
       agentId: resolvedAgentId,
-      model: normalizeString(model) || "unknown",
+      model: normalizeString(identity.model) || "unknown",
+      displayName: normalizeString(identity.displayName),
+      provider: normalizeString(identity.provider),
+      clientKind: normalizeString(identity.clientKind),
       role,
       status: "idle",
       detail: "",
@@ -369,6 +429,9 @@ export async function registerAgent(
   await emitAgentEvent(paths.sessionId, "agent_join", {
     agentId: snapshot.agentId,
     model: snapshot.model,
+    displayName: snapshot.displayName,
+    provider: snapshot.provider,
+    clientKind: snapshot.clientKind,
     role: snapshot.role,
     status: snapshot.status,
   }, { targetPath, awaitRemoteSync });
@@ -412,6 +475,9 @@ export async function rememberAgentIdentity(
   {
     agentId = "",
     model = "",
+    displayName = "",
+    provider = "",
+    clientKind = "",
     role = "observer",
     targetPath = process.cwd(),
   } = {}
@@ -422,6 +488,13 @@ export async function rememberAgentIdentity(
   if (!resolvedAgentId) {
     throw new Error("agentId is required.");
   }
+  const identity = inferSessionAgentIdentity({
+    agentId: resolvedAgentId,
+    model,
+    displayName,
+    provider,
+    clientKind,
+  });
 
   const snapshotPath = buildAgentSnapshotPath(paths, resolvedAgentId);
   const existing = await readAgentSnapshot(snapshotPath);
@@ -430,7 +503,10 @@ export async function rememberAgentIdentity(
       ...(existing || {}),
       sessionId: paths.sessionId,
       agentId: resolvedAgentId,
-      model: normalizeString(model) || normalizeString(existing?.model) || "unknown",
+      model: chooseAgentRefreshModel(identity.model, existing?.model, model),
+      displayName: chooseAgentRefreshMetadata(identity.displayName, existing?.displayName, displayName),
+      provider: chooseAgentRefreshMetadata(identity.provider, existing?.provider, provider),
+      clientKind: chooseAgentRefreshMetadata(identity.clientKind, existing?.clientKind, clientKind),
       role: normalizeString(role) || normalizeString(existing?.role) || "observer",
       status: normalizeString(existing?.status) || "idle",
       detail: normalizeString(existing?.detail) || "",
@@ -536,6 +612,9 @@ export async function unregisterAgent(
     reason: normalizedReason,
     role: snapshot.role,
     model: snapshot.model,
+    displayName: snapshot.displayName,
+    provider: snapshot.provider,
+    clientKind: snapshot.clientKind,
   }, { targetPath });
   // Already left explicitly — don't double-emit on process exit.
   _untrackLocalAgent(paths.sessionId, snapshot.agentId);

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);