sentinelayer-cli 0.39.2 → 0.41.0

package/src/session/checkpoints.js

@@ -3,6 +3,7 @@ import process from "node:process";
 
 import { SentinelayerApiError, requestJson, requestJsonMutation } from "../auth/http.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
+import { pollSessionEventsBefore } from "./sync.js";
 
 const DEFAULT_API_BASE_URL = "https://api.sentinelayer.com";
 const DEFAULT_CHECKPOINT_LIMIT = 100;
@@ -11,6 +12,10 @@ const DEFAULT_MIN_EVENTS = 20;
 const DEFAULT_MAX_EVENTS = 80;
 const DEFAULT_BATCH_MAX_CHECKPOINTS = 5;
 const MAX_BATCH_MAX_CHECKPOINTS = 50;
+const DEFAULT_RESTORE_CONTEXT_EVENTS = 3;
+const DEFAULT_RESTORE_MAX_EVENTS = 120;
+const MAX_RESTORE_CONTEXT_EVENTS = 50;
+const MAX_RESTORE_EVENTS = 200;
 const DEFAULT_CREATED_BY_AGENT_ID = "senti";
 
 function normalizeString(value) {
@@ -33,6 +38,17 @@ function parsePositiveInteger(value, field, fallbackValue = null) {
   return Math.floor(parsed);
 }
 
+function parseNonNegativeInteger(value, field, fallbackValue = 0) {
+  if (value === undefined || value === null || normalizeString(value) === "") {
+    return Math.max(0, Math.floor(Number(fallbackValue) || 0));
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`${field} must be a non-negative integer.`);
+  }
+  return Math.floor(parsed);
+}
+
 function normalizeLimit(value) {
   const parsed = parsePositiveInteger(value, "limit", DEFAULT_CHECKPOINT_LIMIT);
   return Math.max(1, Math.min(MAX_CHECKPOINT_LIMIT, parsed));
@@ -47,6 +63,16 @@ function normalizeBatchMaxCheckpoints(value) {
   return Math.max(1, Math.min(MAX_BATCH_MAX_CHECKPOINTS, parsed));
 }
 
+function normalizeRestoreMaxEvents(value) {
+  const parsed = parsePositiveInteger(value, "max-events", DEFAULT_RESTORE_MAX_EVENTS);
+  return Math.max(1, Math.min(MAX_RESTORE_EVENTS, parsed));
+}
+
+function normalizeRestoreContextEvents(value) {
+  const parsed = parseNonNegativeInteger(value, "context-events", DEFAULT_RESTORE_CONTEXT_EVENTS);
+  return Math.max(0, Math.min(MAX_RESTORE_CONTEXT_EVENTS, parsed));
+}
+
 function stableHash(value) {
   return crypto
     .createHash("sha256")
@@ -148,6 +174,20 @@ function normalizeTokenRange({ tokenStart, tokenEnd } = {}) {
   return { start, end };
 }
 
+function checkpointIdOf(checkpoint = {}) {
+  return normalizeString(checkpoint.checkpointId || checkpoint.checkpoint_id);
+}
+
+function checkpointSequenceValue(checkpoint = {}, camelKey, snakeKey) {
+  const parsed = Number(checkpoint[camelKey] ?? checkpoint[snakeKey]);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 0;
+}
+
+function eventSequenceValue(event = {}) {
+  const parsed = Number(event.sequenceId ?? event.sequence_id ?? event.sequence);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 0;
+}
+
 export function buildManualCheckpointPayload(sessionId, {
   checkpointId = "",
   startSequence,
@@ -235,6 +275,99 @@ export function buildGenerateCheckpointPayload(sessionId, {
   };
 }
 
+export function findCheckpointById(checkpoints = [], checkpointId = "") {
+  const normalizedCheckpointId = normalizeString(checkpointId);
+  if (!normalizedCheckpointId) return null;
+  return Array.isArray(checkpoints)
+    ? checkpoints.find((checkpoint) => checkpointIdOf(checkpoint) === normalizedCheckpointId) || null
+    : null;
+}
+
+export function buildCheckpointRestoreWindow(checkpoint = {}, {
+  contextEvents = DEFAULT_RESTORE_CONTEXT_EVENTS,
+  maxEvents = DEFAULT_RESTORE_MAX_EVENTS,
+} = {}) {
+  const startSequence = checkpointSequenceValue(checkpoint, "startSequence", "start_sequence");
+  const endSequence = checkpointSequenceValue(checkpoint, "endSequence", "end_sequence");
+  if (startSequence <= 0) {
+    throw new Error("checkpoint startSequence is required for restore.");
+  }
+  if (endSequence <= 0) {
+    throw new Error("checkpoint endSequence is required for restore.");
+  }
+  if (startSequence > endSequence) {
+    throw new Error("checkpoint startSequence must be less than or equal to endSequence.");
+  }
+  const normalizedContext = normalizeRestoreContextEvents(contextEvents);
+  const normalizedMaxEvents = normalizeRestoreMaxEvents(maxEvents);
+  const sourceEventCountExpected = endSequence - startSequence + 1;
+  const requestedEventCount = sourceEventCountExpected + normalizedContext * 2;
+  const limit = Math.min(normalizedMaxEvents, requestedEventCount, MAX_RESTORE_EVENTS);
+  return {
+    checkpointId: checkpointIdOf(checkpoint) || null,
+    startSequence,
+    endSequence,
+    contextEvents: normalizedContext,
+    maxEvents: normalizedMaxEvents,
+    limit,
+    beforeSequence: endSequence + normalizedContext + 1,
+    lowerBoundSequence: Math.max(1, startSequence - normalizedContext),
+    sourceEventCountExpected,
+    truncatedByLimit: limit < requestedEventCount,
+  };
+}
+
+export function classifyCheckpointRestoreEvents(events = [], window = {}) {
+  const normalizedEvents = Array.isArray(events) ? events : [];
+  const startSequence = Number(window.startSequence || 0);
+  const endSequence = Number(window.endSequence || 0);
+  const sourceEventCountExpected = Number(window.sourceEventCountExpected || 0);
+  const beforeContextEvents = [];
+  const sourceEvents = [];
+  const afterContextEvents = [];
+  const sourceSequenceIds = new Set();
+
+  for (const event of normalizedEvents) {
+    const sequence = eventSequenceValue(event);
+    if (sequence <= 0) continue;
+    if (sequence < startSequence) {
+      beforeContextEvents.push(event);
+    } else if (sequence > endSequence) {
+      afterContextEvents.push(event);
+    } else {
+      sourceEvents.push(event);
+      sourceSequenceIds.add(sequence);
+    }
+  }
+
+  const missingStart = startSequence > 0 && !sourceSequenceIds.has(startSequence);
+  const missingEnd = endSequence > 0 && !sourceSequenceIds.has(endSequence);
+  const missingSourceEvents = Math.max(0, sourceEventCountExpected - sourceSequenceIds.size);
+  return {
+    events: normalizedEvents,
+    beforeContextEvents,
+    sourceEvents,
+    afterContextEvents,
+    eventCount: normalizedEvents.length,
+    beforeContextCount: beforeContextEvents.length,
+    sourceEventCount: sourceEvents.length,
+    afterContextCount: afterContextEvents.length,
+    missingStart,
+    missingEnd,
+    missingSourceEvents,
+    completeSourceRange:
+      sourceEventCountExpected > 0 &&
+      !missingStart &&
+      !missingEnd &&
+      missingSourceEvents === 0,
+    partial:
+      Boolean(window.truncatedByLimit) ||
+      missingStart ||
+      missingEnd ||
+      missingSourceEvents > 0,
+  };
+}
+
 export function normalizeCheckpointGenerationResult(payload = {}) {
   const source = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
   const checkpoint =
@@ -308,6 +441,63 @@ export async function listSessionCheckpoints(sessionId, {
   };
 }
 
+export async function showSessionCheckpoint(sessionId, checkpointId, {
+  targetPath = process.cwd(),
+  contextEvents = DEFAULT_RESTORE_CONTEXT_EVENTS,
+  maxEvents = DEFAULT_RESTORE_MAX_EVENTS,
+  resolveAuthSession = resolveActiveAuthSession,
+  request = requestJson,
+  fetchEventsBefore = pollSessionEventsBefore,
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+  const normalizedCheckpointId = normalizeString(checkpointId);
+  if (!normalizedCheckpointId) {
+    throw new Error("checkpoint id is required.");
+  }
+
+  const listed = await listSessionCheckpoints(normalizedSessionId, {
+    targetPath,
+    limit: MAX_CHECKPOINT_LIMIT,
+    resolveAuthSession,
+    request,
+  });
+  const checkpoint = findCheckpointById(listed.checkpoints, normalizedCheckpointId);
+  if (!checkpoint) {
+    throw new Error(`Checkpoint '${normalizedCheckpointId}' was not found in session ${normalizedSessionId}.`);
+  }
+  const restoreWindow = buildCheckpointRestoreWindow(checkpoint, {
+    contextEvents,
+    maxEvents,
+  });
+  const remote = await fetchEventsBefore(normalizedSessionId, {
+    targetPath,
+    beforeSequence: restoreWindow.beforeSequence,
+    limit: restoreWindow.limit,
+    forceCircuitProbe: true,
+    resolveAuthSession,
+  });
+  const classified = classifyCheckpointRestoreEvents(remote?.events || [], restoreWindow);
+  return {
+    ok: Boolean(remote?.ok),
+    reason: normalizeString(remote?.reason),
+    sessionId: normalizedSessionId,
+    checkpointId: normalizedCheckpointId,
+    apiUrl: listed.apiUrl,
+    checkpoint,
+    window: {
+      ...restoreWindow,
+      ...classified,
+      remoteOk: Boolean(remote?.ok),
+      remoteReason: normalizeString(remote?.reason),
+      remoteBeforeSequence: remote?.beforeSequence || null,
+      remoteCursor: remote?.cursor || null,
+    },
+  };
+}
+
 export async function createSessionCheckpoint(sessionId, options = {}) {
   const normalizedSessionId = normalizeString(sessionId);
   const {
@@ -446,5 +636,9 @@ export {
   DEFAULT_BATCH_MAX_CHECKPOINTS,
   DEFAULT_MAX_EVENTS,
   DEFAULT_MIN_EVENTS,
+  DEFAULT_RESTORE_CONTEXT_EVENTS,
+  DEFAULT_RESTORE_MAX_EVENTS,
   MAX_BATCH_MAX_CHECKPOINTS,
+  MAX_RESTORE_CONTEXT_EVENTS,
+  MAX_RESTORE_EVENTS,
 };

package/src/session/coordination-guidance.js

@@ -2,12 +2,12 @@ export const COORDINATION_GUIDANCE_TITLE = "Multi-Agent Coordination Protocol";
 
 export const COORDINATION_ETIQUETTE_ITEMS = Object.freeze([
   "Find the recent Senti session for this codebase: run `sl session list --path .` and `sl session list --remote --path .`; join the right room with `sl session join <id> --name <your-name> --role coder`.",
-  "When you have an agent grant, post agent updates with `sl session post-agent <id> \"status: <update>\" --agent <your-agent-id>` so they render as the agent, not the human relay.",
-  "Before implementation, post a short plan and file claims with `sl session say <id> \"plan: <scope>; files: <paths>\"`.",
-  "Claim shared files before editing with `lock: <file> - <intent>` and release them with `unlock: <file> - done`.",
-  "Run one background/secondary listener for replies with `sl session listen --session <id> --agent <your-name> --interval 60 --active-interval 5 --emit ndjson --no-presence`; this idles at 60s, switches to 5s after human activity, and avoids durable listener heartbeat noise. `session listen` now refuses duplicate local listeners for the same session/agent by default; use `--force` only to stop and replace an existing local owner and `--allow-duplicate` only when you intentionally need parallel wake hooks. `session listen` is only a delivery cursor, not a grounding command; join or recap before acting. For your primary interactive listener, omit `--no-presence` so other participants can see you online. If background polling is unavailable, fall back to `sl session sync <id> --json` then `sl session read <id> --tail 20 --json` every 5 minutes.",
-  "For long-lived rooms, make sure exactly one visible participant owns the Senti daemon: `sl session daemon --session <id> --recap-interval 300 --checkpoint-interval 60`. If no durable recap/checkpoint is appearing, run `sl session recap now <id> --remote --agent <your-name> --json` before posting a long plan.",
-  "Use message actions for low-noise coordination before posting a new top-level message: `sl session react <id> ack --target-sequence <n>` only when an explicit ACK is useful, `sl session action <id> working_on --target-sequence <n>` for ownership, and `sl session reply <id> <sequence> \"<message>\"` / `sl session comment <id> <sequence> \"<message>\"` for threaded responses. Read receipts are automatic when you use `sl session read <id> --remote --agent <your-name>`; reserve `sl session view <id> <sequence>` for repair/backfill. Run `sl session actions` for the full list.",
+  "Keep transient activity outside chat with `sl session action <id> working_on --target-sequence <n>`; post through `sl session post-agent` only for a material decision, finding, blocker, handoff, or completion so the transcript remains readable.",
+  "Before implementation, post a short semantic plan only when peers need it; keep routine ownership and progress in message actions.",
+  "Claim shared files outside chat before editing with `sl session lock <id> <file> --agent <your-agent-id> --intent \"<intent>\"`; install terminal/editor preflights once with `sl session guard-install <id> --agent <your-agent-id>`, inspect with `sl session locks <id>`, renew long work with `sl session renew`, and release with `sl session unlock`. Lease lifecycle never belongs in chat; guarded terminal/editor denials report the file, holder, intent, and expiry directly to the blocked agent.",
+  "Run one background/secondary listener for replies with `sl session listen --session <id> --agent <your-name> --transport poll --interval 60 --active-interval 60 --emit ndjson --no-presence`; polling applies bounded jitter, exponential transient backoff, and `Retry-After` as a hard floor. `session listen` refuses duplicate local listeners for the same session/agent by default; use `--force` only to stop and replace an existing local owner and `--allow-duplicate` only when you intentionally need parallel wake hooks. `session listen` is only a delivery cursor, not a grounding command; join or recap before acting. For your primary interactive listener, omit `--no-presence` so it renews an ephemeral TTL outside the transcript. Unsupported or degraded presence remains unknown and never falls back to durable heartbeat events. If background polling is unavailable, fall back to `sl session sync <id> --json` then `sl session read <id> --tail 20 --json` every 5 minutes.",
+  "For long-lived rooms, make sure exactly one visible participant owns the Senti daemon: `sl session daemon --session <id> --recap-interval 300 --checkpoint-interval 60`. Routine room health is a derived status projection, not a transcript event; run `sl session recap now <id> --remote --agent <your-name> --json` for local grounding and use an explicit checkpoint only for a durable semantic handoff.",
+  "Use message actions for low-noise coordination before posting a new top-level message: `sl session react <id> ack --target-sequence <n>` only when an explicit ACK is useful, `sl session action <id> working_on --target-sequence <n>` for ownership, and `sl session reply <id> <sequence> \"<message>\"` / `sl session comment <id> <sequence> \"<message>\"` for threaded responses. `sl session read <id> --remote --agent <your-name>` advances one monotonic per-agent read cursor for the displayed window; it never appends per-message view events; reserve `sl session view <id> <sequence>` for repair/backfill of that same cursor. Run `sl session actions` for the full list.",
   "Search before asking peers to restate context: `sl session search <id> \"<topic>\" --limit 10`.",
   "Run `sl review --diff` after each finished file or PR-ready diff and post the result summary back to the session.",
   "Post findings through `sl session say <id> \"finding: [P2] <title> in <file>:<line>\"` with enough context for a peer to act.",

package/src/session/daemon.js

@@ -22,11 +22,6 @@ import {
   registerAgent,
   unregisterAgent,
 } from "./agent-registry.js";
-import {
-  DEFAULT_FILE_LOCK_TTL_SECONDS,
-  lockFile,
-  unlockFile,
-} from "./file-locks.js";
 import {
   DEFAULT_MAX_EVENTS as DEFAULT_CHECKPOINT_MAX_EVENTS,
   DEFAULT_MIN_EVENTS as DEFAULT_CHECKPOINT_MIN_EVENTS,
@@ -65,8 +60,6 @@ const DEFAULT_CHECKPOINT_INTERVAL_MS = 60_000;
 const DEFAULT_CHECKPOINT_EVENT_THRESHOLD = DEFAULT_CHECKPOINT_MIN_EVENTS;
 const DEFAULT_CHECKPOINT_IDLE_MS = DEFAULT_RECAP_INACTIVITY_MS_OVERRIDE;
 const CHECKPOINT_MEANINGFUL_EVENT_NAMES = new Set([
-  "file_lock",
-  "file_unlock",
   "finding",
   "help_request",
   "help_response",
@@ -84,6 +77,9 @@ const CHECKPOINT_IGNORED_EVENT_NAMES = new Set([
   "agent_status",
   "context_briefing",
   "daemon_alert",
+  "file_lock",
+  "file_lock_expired",
+  "file_unlock",
   "session_checkpoint",
   "session_listen_error",
   "session_recap",
@@ -138,14 +134,27 @@ async function emitSentiEvent(
   payload = {},
   { targetPath = process.cwd(), nowIso = new Date().toISOString() } = {}
 ) {
+  const projectionOnly = normalizeString(event) === "daemon_alert";
   const envelope = createAgentEvent({
     event,
     agentId: SENTI_IDENTITY.id,
     agentModel: SENTI_IDENTITY.model,
     sessionId,
     ts: normalizeIsoTimestamp(nowIso, new Date().toISOString()),
-    payload,
+    payload: projectionOnly
+      ? {
+          ...payload,
+          ephemeral: true,
+          projection: "session_health",
+        }
+      : payload,
   });
+  // Daemon health, presence, conflict hints, and lifecycle notices are
+  // operational projections. They are returned to the caller/status surface,
+  // but never become durable conversation rows.
+  if (projectionOnly) {
+    return envelope;
+  }
   await appendToStream(sessionId, envelope, {
     targetPath,
   });
@@ -731,126 +740,12 @@ async function runHelpWatcher(daemonState) {
   }
 }
 
-function splitFileAndIntent(raw = "") {
-  const normalized = normalizeString(raw);
-  if (!normalized) {
-    return {
-      filePath: "",
-      intent: "",
-    };
-  }
-  const separatorMatch = /\s(?:—|–|-)\s/.exec(normalized);
-  if (!separatorMatch) {
-    return {
-      filePath: normalizeString(normalized),
-      intent: "",
-    };
-  }
-  const separatorIndex = Number(separatorMatch.index || 0);
-  return {
-    filePath: normalizeString(normalized.slice(0, separatorIndex)),
-    intent: normalizeString(normalized.slice(separatorIndex + separatorMatch[0].length)),
-  };
-}
-
-function parseSessionDirective(event = {}) {
-  if (normalizeString(event.event) !== "session_message") {
-    return null;
-  }
-  const message = normalizeString(event.payload?.message);
-  if (!message) {
-    return null;
-  }
-  const directive = /^(lock|unlock)\s*:\s*(.+)$/i.exec(message);
-  if (!directive) {
-    return null;
-  }
-  const action = normalizeString(directive[1]).toLowerCase();
-  const body = normalizeString(directive[2]);
-  const parsed = splitFileAndIntent(body);
-  if (!parsed.filePath) {
-    return null;
-  }
-  return {
-    action,
-    filePath: parsed.filePath,
-    intent: parsed.intent,
-  };
-}
-
-async function maybeHandleSessionDirective(daemonState, event) {
+async function maybeHandleTaskDirective(daemonState, event) {
   const agentId = normalizeString(event.agent?.id);
   if (!agentId || agentId === SENTI_IDENTITY.id) {
     return null;
   }
   const nowIso = normalizeIsoTimestamp(event.ts, new Date().toISOString());
-  const fileDirective = parseSessionDirective(event);
-  if (fileDirective) {
-    if (fileDirective.action === "lock") {
-      const result = await lockFile(
-        daemonState.sessionId,
-        agentId,
-        fileDirective.filePath,
-        {
-          intent: fileDirective.intent,
-          ttlSeconds: DEFAULT_FILE_LOCK_TTL_SECONDS,
-          targetPath: daemonState.targetPath,
-          nowIso,
-        }
-      );
-      if (!result.locked) {
-        await emitSentiEvent(
-          daemonState.sessionId,
-          "daemon_alert",
-          {
-            alert: "file_lock_denied",
-            file: result.file || fileDirective.filePath,
-            requestedBy: agentId,
-            heldBy: result.heldBy || null,
-            since: result.since || null,
-            suggestion: `${fileDirective.filePath} is locked by ${result.heldBy || "another agent"} (${result.since || "recently"}). Coordinate before editing.`,
-          },
-          {
-            targetPath: daemonState.targetPath,
-            nowIso,
-          }
-        );
-      }
-      return result;
-    }
-    if (fileDirective.action === "unlock") {
-      const result = await unlockFile(
-        daemonState.sessionId,
-        agentId,
-        fileDirective.filePath,
-        {
-          reason: "session_message_unlock",
-          targetPath: daemonState.targetPath,
-          nowIso,
-        }
-      );
-      if (!result.unlocked && result.reason === "held_by_other_agent") {
-        await emitSentiEvent(
-          daemonState.sessionId,
-          "daemon_alert",
-          {
-            alert: "file_unlock_denied",
-            file: result.file || fileDirective.filePath,
-            requestedBy: agentId,
-            heldBy: result.heldBy || null,
-            since: result.since || null,
-            suggestion: `${fileDirective.filePath} is locked by ${result.heldBy || "another agent"}. Only the lock holder can release it.`,
-          },
-          {
-            targetPath: daemonState.targetPath,
-            nowIso,
-          }
-        );
-      }
-      return result;
-    }
-  }
-
   try {
     return await handleTaskDirective(daemonState.sessionId, event, {
       targetPath: daemonState.targetPath,
@@ -891,7 +786,7 @@ async function runSessionDirectiveWatcher(daemonState) {
       if (normalizeString(event.event) !== "session_message") {
         continue;
       }
-      await maybeHandleSessionDirective(daemonState, event);
+      await maybeHandleTaskDirective(daemonState, event);
     }
   } catch (error) {
     if (error && typeof error === "object" && error.name === "AbortError") {