sentinelayer-cli 0.8.12 → 0.9.2

package/src/session/remote-hydrate.js

@@ -18,11 +18,159 @@
  * sync, and vice-versa.
  */
 
-import { pollHumanMessages, pollSessionEvents } from "./sync.js";
-import { appendToStream } from "./stream.js";
+import { listSessionsFromApi, pollHumanMessages, pollSessionEvents } from "./sync.js";
+import { appendToStream, readStream } from "./stream.js";
+import { createSession, getSession } from "./store.js";
 import { readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
+import {
+  addSessionEventIdentityKeys,
+  sessionEventHasKnownIdentity,
+} 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() } = {}) {
+  const knownKeys = new Set();
+  const events = await readStream(sessionId, { targetPath, tail: 0 }).catch(() => []);
+  for (const event of events) {
+    addSessionEventIdentityKeys(knownKeys, event);
+  }
+  return knownKeys;
+}
+
+async function ensureLocalSessionShell(sessionId, { targetPath = process.cwd() } = {}) {
+  const existing = await getSession(sessionId, { targetPath });
+  if (existing) {
+    return { materialized: false, session: existing };
+  }
+  let remoteStatus = "";
+  const remoteList = await listSessionsFromApi({
+    targetPath,
+    includeArchived: true,
+    limit: 200,
+  }).catch(() => null);
+  if (remoteList?.ok) {
+    const match = (remoteList.sessions || []).find((entry) => entry?.sessionId === sessionId);
+    remoteStatus = String(match?.archiveStatus || match?.status || "").trim().toLowerCase();
+  }
+  const created = await createSession({
+    targetPath,
+    sessionId,
+    title: `remote-${String(sessionId).slice(0, 8)}`,
+  });
+  return { materialized: true, session: created, remoteStatus };
+}
+
+function sourceFullyRelayed(events = [], successfulKeys = new Set()) {
+  const relayedEvents = Array.isArray(events) ? events : [];
+  if (relayedEvents.length === 0) return true;
+  return relayedEvents.every((event) => sessionEventHasKnownIdentity(event, successfulKeys));
+}
+
+function markPostKillEvent(event = {}) {
+  if (!event || typeof event !== "object" || Array.isArray(event)) return event;
+  const payload = event.payload && typeof event.payload === "object" && !Array.isArray(event.payload)
+    ? event.payload
+    : {};
+  return {
+    ...event,
+    _post_kill: true,
+    payload: {
+      ...payload,
+      _post_kill: true,
+    },
+  };
+}
+
+function normalizePositiveInteger(value, fallbackValue) {
+  if (value === undefined || value === null || String(value).trim() === "") {
+    return fallbackValue;
+  }
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    return fallbackValue;
+  }
+  return Math.floor(normalized);
+}
+
+async function pollSessionEventPages({
+  sessionId,
+  targetPath,
+  since,
+  _pollEvents,
+  limit,
+  maxPages,
+  forceCircuitProbe = false,
+}) {
+  const normalizedLimit = Math.max(
+    1,
+    Math.min(DEFAULT_EVENT_PAGE_LIMIT, normalizePositiveInteger(limit, DEFAULT_EVENT_PAGE_LIMIT)),
+  );
+  const normalizedMaxPages = Math.max(
+    1,
+    Math.min(100, normalizePositiveInteger(maxPages, DEFAULT_MAX_EVENT_PAGES)),
+  );
+  const events = [];
+  let cursor = typeof since === "string" && since.trim() ? since.trim() : null;
+  let reason = "";
+  let pageCount = 0;
+
+  for (let page = 0; page < normalizedMaxPages; page += 1) {
+    const result = await _pollEvents(sessionId, {
+      targetPath,
+      since: cursor,
+      limit: normalizedLimit,
+      forceCircuitProbe,
+    });
+    pageCount += 1;
+    if (!result?.ok) {
+      return {
+        ok: events.length > 0,
+        reason: result?.reason || "poll_failed",
+        events,
+        cursor,
+        pageCount,
+        complete: false,
+        truncated: events.length > 0,
+      };
+    }
+
+    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;
+    cursor = nextCursor || cursor;
+
+    if (pageEvents.length < normalizedLimit) {
+      return {
+        ok: true,
+        reason: "",
+        events,
+        cursor,
+        pageCount,
+        complete: true,
+        truncated: false,
+      };
+    }
+    if (!progressed) {
+      reason = "cursor_not_advanced";
+      break;
+    }
+  }
+
+  return {
+    ok: events.length > 0,
+    reason: reason || "max_event_pages_reached",
+    events,
+    cursor,
+    pageCount,
+    complete: false,
+    truncated: true,
+  };
+}
 
 /**
  * Fetch new human messages for a session, append them to the local
@@ -46,6 +194,10 @@ export async function hydrateSessionFromRemote({
   _poll = pollHumanMessages,
   _pollEvents = pollSessionEvents,
   _append = appendToStream,
+  _ensureLocalSession = ensureLocalSessionShell,
+  probeOpenCircuit = true,
+  eventPageLimit = DEFAULT_EVENT_PAGE_LIMIT,
+  maxEventPages = DEFAULT_MAX_EVENT_PAGES,
 } = {}) {
   if (!sessionId || typeof sessionId !== "string") {
     return {
@@ -74,25 +226,56 @@ export async function hydrateSessionFromRemote({
   // Run both pollers in parallel — they hit different endpoints and
   // are independent. A human-only poll stays fast even when the
   // events poll is heavy.
-  const [humanResult, eventsResult] = await Promise.all([
+  let [humanResult, eventsResult] = await Promise.all([
     _poll(sessionId, { targetPath, since: humanCursor }),
-    _pollEvents(sessionId, { targetPath, since: eventsCursor }),
+    pollSessionEventPages({
+      sessionId,
+      targetPath,
+      since: eventsCursor,
+      _pollEvents,
+      limit: eventPageLimit,
+      maxPages: maxEventPages,
+    }),
   ]);
 
+  if (
+    probeOpenCircuit &&
+    humanResult?.reason === "circuit_breaker_open" &&
+    eventsResult?.reason === "circuit_breaker_open"
+  ) {
+    [humanResult, eventsResult] = await Promise.all([
+      _poll(sessionId, { targetPath, since: humanCursor, forceCircuitProbe: true }),
+      pollSessionEventPages({
+        sessionId,
+        targetPath,
+        since: eventsCursor,
+        _pollEvents,
+        limit: eventPageLimit,
+        maxPages: maxEventPages,
+        forceCircuitProbe: true,
+      }),
+    ]);
+  }
+
   // Dedup across sources — both endpoints can return the same event
   // (e.g. a human relay event). Cursor values are unique per event.
   const seenCursors = new Set();
+  const seenKeys = new Set();
   const merged = [];
   for (const e of humanResult?.events || []) {
     const c = (e && typeof e === "object" && typeof e.cursor === "string") ? e.cursor : "";
     if (c && seenCursors.has(c)) continue;
+    if (sessionEventHasKnownIdentity(e, seenKeys)) continue;
     if (c) seenCursors.add(c);
+    addSessionEventIdentityKeys(seenKeys, e);
     merged.push(e);
   }
   for (const e of eventsResult?.events || []) {
     const c = (e && typeof e === "object" && typeof e.cursor === "string") ? e.cursor : "";
     if (c && seenCursors.has(c)) continue;
+    if (sessionEventHasKnownIdentity(e, seenKeys)) continue;
     if (c) seenCursors.add(c);
+    addSessionEventIdentityKeys(seenKeys, e);
     merged.push(e);
   }
 
@@ -112,10 +295,33 @@ export async function hydrateSessionFromRemote({
   }
 
   let relayed = 0;
-  for (const event of merged) {
+  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) {
+    try {
+      const localSession = await _ensureLocalSession(sessionId, { targetPath });
+      materializedLocalSession = Boolean(localSession?.materialized);
+      remoteStatus = String(localSession?.remoteStatus || "").trim().toLowerCase();
+    } catch {
+      // Keep the old degraded behavior: append attempts below will
+      // fail visibly in the returned counters, but remote polling still
+      // returns a structured result.
+    }
+  }
+  const appendEvents =
+    remoteStatus && !["active", "pending"].includes(remoteStatus)
+      ? newEvents.map((event) => markPostKillEvent(event))
+      : newEvents;
+  for (const event of appendEvents) {
     try {
-      await _append(sessionId, event, { targetPath });
+      await _append(sessionId, event, { targetPath, syncRemote: false });
       relayed += 1;
+      addSessionEventIdentityKeys(successfulRelayKeys, event);
     } catch {
       // Append errors are observable via the stream but should not
       // abort the rest of the batch — partial relay is still progress.
@@ -123,11 +329,13 @@ export async function hydrateSessionFromRemote({
   }
 
   let persistedCursor = false;
-  if (typeof humanResult?.cursor === "string" && humanResult.cursor.trim()) {
+  const humanCursorSafe = sourceFullyRelayed(humanResult?.events || [], successfulRelayKeys);
+  const eventsCursorSafe = sourceFullyRelayed(eventsResult?.events || [], successfulRelayKeys);
+  if (humanCursorSafe && typeof humanResult?.cursor === "string" && humanResult.cursor.trim()) {
     const result = await writeSyncCursor(sessionId, humanResult.cursor, { targetPath }).catch(() => null);
     persistedCursor = Boolean(result && result.written);
   }
-  if (typeof eventsResult?.cursor === "string" && eventsResult.cursor.trim()) {
+  if (eventsCursorSafe && typeof eventsResult?.cursor === "string" && eventsResult.cursor.trim()) {
     await writeSyncCursor(sessionId, eventsResult.cursor, {
       targetPath,
       suffix: EVENTS_CURSOR_SUFFIX,
@@ -145,5 +353,12 @@ export async function hydrateSessionFromRemote({
     eventsRelayed: (eventsResult?.events || []).length,
     eventsCursor:
       typeof eventsResult?.cursor === "string" ? eventsResult.cursor : eventsCursor || null,
+    eventsPageCount: Number(eventsResult?.pageCount || 0),
+    eventsBackfillComplete: Boolean(eventsResult?.complete !== false),
+    eventsBackfillTruncated: Boolean(eventsResult?.truncated),
+    eventsBackfillReason: eventsResult?.complete === false ? eventsResult?.reason || "" : "",
+    materializedLocalSession,
+    localAppendComplete: humanCursorSafe && eventsCursorSafe,
+    remoteStatus: remoteStatus || null,
   };
 }

package/src/session/setup-guides.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import process from "node:process";
 
 import { buildAgentsSessionGuideContent } from "../legacy-cli.js";
+import { renderCoordinationBulletList } from "./coordination-guidance.js";
 import { getSession } from "./store.js";
 
 const SECTION_START_MARKER = "<!-- SENTINELAYER_SESSION_COORDINATION:START -->";
@@ -26,21 +27,8 @@ function buildSessionCoordinationSection() {
   return `${SECTION_START_MARKER}
 ${SECTION_HEADING}
 
-### Before You Start
-- Check for active sessions: \`sl session list\`
-- Join if one exists: \`sl session join <id> --name <your-name>\`
-- Read recent context: \`sl session read <id> --tail 20\`
-
-### While Working
-- Emit status every 5 min: \`sl session say <id> "status: <what you're doing>"\`
-- Lock files before editing: \`sl session say <id> "lock: <file> - <intent>"\`
-- Unlock when done: \`sl session say <id> "unlock: <file> - done"\`
-- Post findings: \`sl session say <id> "finding: [P2] <title> in <file>:<line>"\`
-
-### On Problems
-- Unexpected file change? Ask: \`sl session say <id> "help: unexpected change in <file>"\`
-- Need another agent's work? Request: \`sl session say <id> "handoff: @<agent> <description>"\`
-- Found issues for others? Assign: \`sl session say <id> "assign: @<agent> <task>"\`
+### Required Etiquette
+${renderCoordinationBulletList()}
 
 ### What Not To Do
 - Do not break your autonomous loop on unexpected file changes; ask in session first.

package/src/session/store.js

@@ -43,6 +43,21 @@ function normalizeNonNegativeInteger(value, fallbackValue = 0) {
   return Math.floor(normalized);
 }
 
+function normalizeCreateSessionId(value) {
+  const normalized = normalizeString(value);
+  if (!normalized) return randomUUID();
+  if (
+    normalized === "." ||
+    normalized === ".." ||
+    normalized.includes("/") ||
+    normalized.includes("\\") ||
+    normalized.includes("..")
+  ) {
+    throw new Error("sessionId must not contain path traversal segments.");
+  }
+  return normalized;
+}
+
 function normalizeIsoTimestamp(value, fallbackIso = new Date().toISOString()) {
   const normalized = normalizeString(value);
   if (!normalized) {
@@ -148,7 +163,7 @@ function toRelativePosix(baseDir, absolutePath) {
 
 function normalizeDateKeyFromCloseoutPath(closeoutPath = "", fallbackIso = new Date().toISOString()) {
   const normalized = toPosixPath(closeoutPath);
-  const match = /\/observability\/(\d{4}-\d{2}-\d{2})\//.exec(`/${normalized}`);
+  const match = /\/observability\/(\d{4}-\d{2}-\d{2})\//.exec("/" + normalized);
   if (match) {
     return match[1];
   }
@@ -168,6 +183,31 @@ function normalizeSharedResources(raw = {}, { nowIso = new Date().toISOString()
   };
 }
 
+function normalizeRemoteTitleSync(raw = {}, { nowIso = new Date().toISOString() } = {}) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return null;
+  }
+  const title = normalizeString(raw.title);
+  const lastAttemptAt = raw.lastAttemptAt
+    ? normalizeIsoTimestamp(raw.lastAttemptAt, nowIso)
+    : null;
+  const lastSyncedAt = raw.lastSyncedAt
+    ? normalizeIsoTimestamp(raw.lastSyncedAt, nowIso)
+    : null;
+  const failureReason = normalizeString(raw.failureReason) || null;
+  const pending = Boolean(raw.pending);
+  if (!pending && !title && !lastAttemptAt && !lastSyncedAt && !failureReason) {
+    return null;
+  }
+  return {
+    pending,
+    title: title || null,
+    lastAttemptAt,
+    lastSyncedAt,
+    failureReason,
+  };
+}
+
 function normalizeTemplateAgent(raw = {}) {
   const source = raw && typeof raw === "object" ? raw : {};
   return {
@@ -330,6 +370,7 @@ function normalizeMetadata(raw = {}, { sessionId, targetPath, nowIso } = {}) {
     createdAt,
     updatedAt: normalizeIsoTimestamp(raw.updatedAt, nowIso),
     expiresAt,
+    title: normalizeString(raw.title) || null,
     ttlSeconds,
     renewalCount: Math.max(0, Number(raw.renewalCount || 0)),
     maxLifetimeSeconds: normalizePositiveInteger(raw.maxLifetimeSeconds, MAX_SESSION_LIFETIME_SECONDS),
@@ -341,6 +382,7 @@ function normalizeMetadata(raw = {}, { sessionId, targetPath, nowIso } = {}) {
     archiveStatus: normalizeString(raw.archiveStatus) || "pending",
     codebaseContext: normalizeCodebaseContext(raw.codebaseContext || {}),
     sharedResources: normalizeSharedResources(raw.sharedResources || {}, { nowIso }),
+    remoteTitleSync: normalizeRemoteTitleSync(raw.remoteTitleSync || null, { nowIso }),
     template: normalizeSessionTemplate(raw.template || null),
   };
 }
@@ -364,7 +406,10 @@ function buildSessionPayload(metadata, paths, nowIso = new Date().toISOString())
     metadataPath: paths.metadataPath,
     streamPath: paths.streamPath,
     createdAt: metadata.createdAt,
+    updatedAt: metadata.updatedAt,
     expiresAt: metadata.expiresAt,
+    lastInteractionAt: metadata.lastInteractionAt,
+    title: metadata.title,
     elapsedTimer: buildElapsedTimer(metadata.createdAt, nowIso),
     renewalCount: metadata.renewalCount,
     status: metadata.status,
@@ -372,6 +417,7 @@ function buildSessionPayload(metadata, paths, nowIso = new Date().toISOString())
     s3Path: metadata.s3Path,
     codebaseContext: metadata.codebaseContext,
     sharedResources: metadata.sharedResources,
+    remoteTitleSync: metadata.remoteTitleSync,
     template: metadata.template,
   };
 }
@@ -406,11 +452,22 @@ export async function createSession({
   targetPath = process.cwd(),
   ttlSeconds = DEFAULT_TTL_SECONDS,
   template = null,
+  sessionId: requestedSessionId = "",
+  title = "",
+  createdAt = "",
+  expiresAt = "",
+  lastInteractionAt = "",
 } = {}) {
   const resolvedTargetPath = path.resolve(String(targetPath || "."));
   const normalizedTtlSeconds = normalizePositiveInteger(ttlSeconds, DEFAULT_TTL_SECONDS);
-  const sessionId = randomUUID();
+  const sessionId = normalizeCreateSessionId(requestedSessionId);
   const nowIso = new Date().toISOString();
+  const createdIso = normalizeIsoTimestamp(createdAt, nowIso);
+  const expiresIso = normalizeIsoTimestamp(
+    expiresAt,
+    toIsoAfterSeconds(createdIso, normalizedTtlSeconds)
+  );
+  const interactionIso = normalizeIsoTimestamp(lastInteractionAt, createdIso);
   const paths = resolveSessionPaths(sessionId, { targetPath: resolvedTargetPath });
   const codebaseContext = await collectSessionCodebaseContext(resolvedTargetPath);
 
@@ -419,20 +476,22 @@ export async function createSession({
       schemaVersion: SESSION_SCHEMA_VERSION,
       sessionId,
       targetPath: resolvedTargetPath,
-      createdAt: nowIso,
+      createdAt: createdIso,
       updatedAt: nowIso,
-      expiresAt: toIsoAfterSeconds(nowIso, normalizedTtlSeconds),
+      expiresAt: expiresIso,
+      title: normalizeString(title) || null,
       ttlSeconds: normalizedTtlSeconds,
       renewalCount: 0,
       maxLifetimeSeconds: MAX_SESSION_LIFETIME_SECONDS,
       status: SESSION_STATUS_ACTIVE,
-      lastInteractionAt: nowIso,
+      lastInteractionAt: interactionIso,
       expiredAt: null,
       archivedAt: null,
       s3Path: null,
       archiveStatus: "pending",
       codebaseContext,
       sharedResources: normalizeSharedResources({}, { nowIso }),
+      remoteTitleSync: null,
       template: normalizeSessionTemplate(template),
     },
     {
@@ -449,6 +508,59 @@ export async function createSession({
   return buildSessionPayload(metadata, paths, nowIso);
 }
 
+export async function updateSessionTitle(
+  sessionId,
+  { targetPath = process.cwd(), title = "" } = {}
+) {
+  const loaded = await loadMetadata(sessionId, { targetPath });
+  if (!loaded) {
+    return null;
+  }
+  const nowIso = new Date().toISOString();
+  const metadata = {
+    ...loaded.metadata,
+    title: normalizeString(title) || null,
+    updatedAt: nowIso,
+  };
+  const saved = await saveMetadata(metadata, loaded.paths);
+  return buildSessionPayload(saved, loaded.paths, nowIso);
+}
+
+export async function recordSessionRemoteTitleSync(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    title = "",
+    pending = false,
+    failureReason = "",
+    lastAttemptAt = "",
+    lastSyncedAt = "",
+  } = {}
+) {
+  const loaded = await loadMetadata(sessionId, { targetPath });
+  if (!loaded) {
+    return null;
+  }
+  const nowIso = new Date().toISOString();
+  const metadata = {
+    ...loaded.metadata,
+    remoteTitleSync: normalizeRemoteTitleSync(
+      {
+        pending: Boolean(pending),
+        title: normalizeString(title) || normalizeString(loaded.metadata.title) || null,
+        lastAttemptAt: lastAttemptAt || nowIso,
+        lastSyncedAt:
+          !pending && !normalizeString(failureReason) ? lastSyncedAt || nowIso : lastSyncedAt || null,
+        failureReason: normalizeString(failureReason) || null,
+      },
+      { nowIso },
+    ),
+    updatedAt: nowIso,
+  };
+  const saved = await saveMetadata(metadata, loaded.paths);
+  return buildSessionPayload(saved, loaded.paths, nowIso);
+}
+
 export async function getSession(sessionId, { targetPath = process.cwd() } = {}) {
   const loaded = await loadMetadata(sessionId, { targetPath });
   if (!loaded) {

package/src/session/stream.js

@@ -3,6 +3,7 @@ import process from "node:process";
 import { setTimeout as sleep } from "node:timers/promises";
 
 import { createAgentEvent, normalizeAgentEvent } from "../events/schema.js";
+import { enrichEventWithMentions } from "./mentions.js";
 import { resolveSessionPaths } from "./paths.js";
 import { redactEventPayload } from "./redact.js";
 import { syncSessionEventToApi } from "./sync.js";
@@ -223,7 +224,7 @@ function filterBySince(events = [], since) {
 export async function appendToStream(
   sessionId,
   event,
-  { targetPath = process.cwd(), maxEvents = DEFAULT_MAX_STREAM_EVENTS } = {}
+  { targetPath = process.cwd(), maxEvents = DEFAULT_MAX_STREAM_EVENTS, syncRemote = true } = {}
 ) {
   const paths = resolveSessionPaths(sessionId, { targetPath });
   const metadata = await readSessionMetadata(paths);
@@ -235,7 +236,14 @@ export async function appendToStream(
   }
 
   const rawEvent = materializeCanonicalEvent(paths.sessionId, event);
-  const canonicalEvent = redactEventPayload(rawEvent);
+  // Parse `@<name>` mentions out of the message text and surface them
+  // as payload.to + payload.mentions so the listener (sl session listen)
+  // and Senti daemon can route to/notify the addressed agent. Pure +
+  // idempotent — if the caller already supplied an explicit `to/recipient`
+  // we leave it alone. Runs before redaction so the redactor sees a
+  // stable shape.
+  const enrichedEvent = enrichEventWithMentions(rawEvent);
+  const canonicalEvent = redactEventPayload(enrichedEvent);
   const nowIso = new Date().toISOString();
   const normalizedMaxEvents = normalizePositiveInteger(maxEvents, DEFAULT_MAX_STREAM_EVENTS);
 
@@ -252,10 +260,12 @@ export async function appendToStream(
     await releaseLock(paths.lockPath);
   }
 
-  // Best-effort dashboard sync. Never block local stream durability on API state.
-  void syncSessionEventToApi(paths.sessionId, canonicalEvent, {
-    targetPath,
-  }).catch(() => {});
+  if (syncRemote) {
+    // Best-effort dashboard sync. Never block local stream durability on API state.
+    void syncSessionEventToApi(paths.sessionId, canonicalEvent, {
+      targetPath,
+    }).catch(() => {});
+  }
 
   return canonicalEvent;
 }
@@ -320,7 +330,7 @@ export async function* tailStream(
     }
 
     try {
-      await sleep(normalizedPollMs, null, signal ? { signal } : undefined);
+      await sleep(normalizedPollMs, null, signal ? { signal, ref: false } : { ref: false });
     } catch (error) {
       if (error && typeof error === "object" && error.name === "AbortError") {
         return;