sentinelayer-cli 0.40.0 → 0.41.0

package/src/session/agent-registry.js

@@ -4,16 +4,14 @@ import path from "node:path";
 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 { buildContextBriefing } from "./recap.js";
 import {
   assignFriendlyName,
   buildSentiWelcome,
   shouldAutoRenameInRegistry,
 } from "./senti-naming.js";
-import { appendToStream } from "./stream.js";
 
 const AGENT_SNAPSHOT_SCHEMA_VERSION = "1.0.0";
 
@@ -177,28 +175,6 @@ async function writeAgentSnapshot(snapshotPath, snapshot) {
   }
 }
 
-async function emitAgentEvent(
-  sessionId,
-  event,
-  payload,
-  { targetPath = process.cwd(), awaitRemoteSync = false } = {}
-) {
-  const envelope = createAgentEvent({
-    event,
-    agent: {
-      id: payload.agentId,
-      model: payload.model,
-      displayName: payload.displayName,
-      provider: payload.provider,
-      role: payload.role,
-      clientKind: payload.clientKind,
-    },
-    sessionId,
-    payload,
-  });
-  await appendToStream(sessionId, envelope, { targetPath, awaitRemoteSync });
-}
-
 function buildAgentSnapshotPath(paths, agentId) {
   const normalizedAgentId = normalizeString(agentId);
   if (!normalizedAgentId) {
@@ -288,17 +264,15 @@ function _untrackLocalAgent(sessionId, agentId) {
   _localAgents.delete(_agentKey(sessionId, agentId));
 }
 
-async function _emitLeaveForAllLocalAgents(reason) {
+async function _leaveAllLocalAgents(reason) {
   const entries = [..._localAgents.values()];
   _localAgents.clear();
   for (const entry of entries) {
     try {
-      await emitAgentEvent(
-        entry.sessionId,
-        "agent_leave",
-        { agentId: entry.agentId, reason, model: "unknown", role: "participant" },
-        { targetPath: entry.targetPath },
-      );
+      await unregisterAgent(entry.sessionId, entry.agentId, {
+        reason,
+        targetPath: entry.targetPath,
+      });
     } catch {
       // Best-effort: a stuck filesystem or network shouldn't block exit.
     }
@@ -309,7 +283,7 @@ function _ensureExitHooksInstalled() {
   if (_exitHooksInstalled) return;
   _exitHooksInstalled = true;
   const onSignal = (signal) => {
-    void _emitLeaveForAllLocalAgents("manual").finally(() => {
+    void _leaveAllLocalAgents("manual").finally(() => {
       process.removeListener(signal, onSignal);
       process.kill(process.pid, signal);
     });
@@ -317,7 +291,7 @@ function _ensureExitHooksInstalled() {
   process.on("SIGINT", onSignal);
   process.on("SIGTERM", onSignal);
   process.on("beforeExit", () => {
-    void _emitLeaveForAllLocalAgents("manual");
+    void _leaveAllLocalAgents("manual");
   });
 }
 
@@ -332,7 +306,6 @@ export async function registerAgent(
     role = "observer",
     targetPath = process.cwd(),
     trackProcessExit = true,
-    awaitRemoteSync = false,
   } = {}
 ) {
   const paths = resolveSessionPaths(sessionId, { targetPath });
@@ -426,46 +399,39 @@ export async function registerAgent(
   );
 
   await writeAgentSnapshot(snapshotPath, snapshot);
-  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 });
   if (trackProcessExit) {
     _trackLocalAgent(paths.sessionId, snapshot.agentId, targetPath);
   }
 
+  let welcome = null;
   if (renamedFrom) {
-    const welcome = buildSentiWelcome({
+    welcome = buildSentiWelcome({
       agentId: snapshot.agentId,
       model: snapshot.model,
       role: snapshot.role,
       wasAnonymous: true,
       originalAgentId: renamedFrom,
     });
-    await emitAgentEvent(paths.sessionId, "agent_identified", {
-      ...welcome,
-      sessionId: paths.sessionId,
-    }, { targetPath });
   }
 
+  let contextBriefing = null;
   if (normalizeString(snapshot.agentId).toLowerCase() !== "senti") {
-    await emitContextBriefing(paths.sessionId, {
+    contextBriefing = await buildContextBriefing(paths.sessionId, {
       forAgentId: snapshot.agentId,
       targetPath,
-      awaitRemoteSync,
     }).catch(() => {});
   }
 
   return {
     ...snapshot,
     snapshotPath,
-    emittedJoinEvent: true,
-    emittedContextBriefing: normalizeString(snapshot.agentId).toLowerCase() !== "senti",
+    emittedJoinEvent: false,
+    emittedContextBriefing: false,
+    returnedContextBriefing: Boolean(contextBriefing),
+    onboarding: {
+      welcome,
+      contextBriefing,
+    },
     refreshedExistingAgent: false,
   };
 }
@@ -607,16 +573,9 @@ export async function unregisterAgent(
   );
 
   await writeAgentSnapshot(snapshotPath, snapshot);
-  await emitAgentEvent(paths.sessionId, "agent_leave", {
-    agentId: snapshot.agentId,
-    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.
+  // Presence and roster state are projections, not transcript events. The
+  // snapshot is authoritative for this workspace; remote listener presence is
+  // renewed through the TTL endpoint.
   _untrackLocalAgent(paths.sessionId, snapshot.agentId);
 
   return {

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") {