sentinelayer-cli 0.9.2 → 0.9.3

package/package.json

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

package/src/commands/session.js

@@ -44,9 +44,11 @@ import {
   createSession,
   DEFAULT_TTL_SECONDS,
   getSession,
+  isSessionCacheExpired,
   listActiveSessions,
   listAllSessions,
   recordSessionProvisionedIdentities,
+  refreshSessionCacheForRemoteActivity,
   updateSessionTitle,
 } from "../session/store.js";
 import { appendToStream, readStream, tailStream } from "../session/stream.js";
@@ -330,11 +332,44 @@ function formatRelativeAge(isoTimestamp) {
 
 async function ensureLocalSessionForRemoteCommand(
   sessionId,
-  { targetPath, title = "", skipRemoteProbe = false } = {},
+  { targetPath, title = "", skipRemoteProbe = false, remoteSession = null } = {},
 ) {
   const existing = await getSession(sessionId, { targetPath });
   if (existing) {
-    return { materialized: false, session: existing };
+    if (!isSessionCacheExpired(existing)) {
+      return { materialized: false, refreshed: false, session: existing };
+    }
+    const existingStatus = normalizeString(existing.status).toLowerCase();
+    const locallyClosedByStatus = existingStatus === "expired" || existingStatus === "archived";
+    if (locallyClosedByStatus && !skipRemoteProbe) {
+      throw new Error(
+        `Session '${sessionId}' is ${existingStatus} locally; run \`sl session join ${sessionId}\` to verify remote access before posting.`,
+      );
+    }
+
+    let access = { accessible: Boolean(skipRemoteProbe), reason: "" };
+    if (!skipRemoteProbe) {
+      access = await probeSessionAccess(sessionId, { targetPath }).catch((error) => ({
+        accessible: false,
+        reason: normalizeString(error?.message) || "probe_failed",
+      }));
+    }
+    if (!access?.accessible) {
+      throw new Error(
+        `Session '${sessionId}' is expired locally and remote access failed (${access?.reason || "unknown"}).`,
+      );
+    }
+
+    const refreshed = await refreshSessionCacheForRemoteActivity(sessionId, {
+      targetPath,
+      title,
+      lastInteractionAt:
+        normalizeString(remoteSession?.lastInteractionAt) ||
+        normalizeString(remoteSession?.lastActivityAt) ||
+        normalizeString(remoteSession?.updatedAt) ||
+        normalizeString(remoteSession?.createdAt),
+    });
+    return { materialized: false, refreshed: Boolean(refreshed), session: refreshed || existing };
   }
   // `skipRemoteProbe` is set by callers that have already verified the session
   // via `verifyRemoteSession` (the singleton GET) — re-probing the legacy
@@ -356,7 +391,7 @@ async function ensureLocalSessionForRemoteCommand(
     sessionId,
     title: normalizeString(title) || `remote-${String(sessionId).slice(0, 8)}`,
   });
-  return { materialized: true, session: created };
+  return { materialized: true, refreshed: false, session: created };
 }
 
 async function ensureWorkspaceSession({
@@ -470,56 +505,16 @@ function normalizeAgentId(value, fallbackValue = "cli-user") {
   return normalized || fallbackValue;
 }
 
-// Derive a stable, human-friendly fallback agent id from the active auth
-// session — `human-<github_username>` if logged in via GitHub, else
-// `human-<email-localpart>` as a last resort. We resolve this lazily and
-// cache per process so repeated `sl session say` calls don't churn auth.
-//
-// Carter's complaint: "we aren't auto naming these agents per joining,
-// we need to figure out a fingerprint for them somehow.. maybe at joining
-// we ask for name?" — auth-derived names are the cleanest deterministic
-// fingerprint we already have. Fall through to "cli-user" only if the
-// CLI is genuinely unauthenticated (CI fixture, fresh checkout).
-let _cachedAuthAgentId = undefined; // undefined = not yet resolved
-async function _resolveAuthAgentId(targetPath) {
-  if (_cachedAuthAgentId !== undefined) return _cachedAuthAgentId;
-  try {
-    const auth = await resolveActiveAuthSession({
-      cwd: targetPath || process.cwd(),
-      env: process.env,
-      autoRotate: false,
-    });
-    const username = normalizeString(auth?.user?.githubUsername).toLowerCase();
-    if (username) {
-      _cachedAuthAgentId = `human-${username.replace(/[^a-z0-9._-]+/g, "-")}`;
-      return _cachedAuthAgentId;
-    }
-    const email = normalizeString(auth?.user?.email).toLowerCase();
-    if (email) {
-      const local = email.split("@")[0].replace(/[^a-z0-9._-]+/g, "-");
-      if (local) {
-        _cachedAuthAgentId = `human-${local}`;
-        return _cachedAuthAgentId;
-      }
-    }
-  } catch {
-    /* unauthenticated → fall through */
-  }
-  _cachedAuthAgentId = "";
-  return "";
+// Preserve the literal default identity for `session say`. This command is
+// often used by agents as a low-friction relay; silently rewriting the default
+// `cli-user` to the authenticated human makes a forgotten --agent flag look
+// like the workspace owner authored the message.
+export function resolveSessionSayAgentId(value) {
+  return normalizeAgentId(value, "cli-user");
 }
 
-// Wrapper that prefers the auth-derived id over the literal `cli-user`
-// placeholder when the caller didn't pass --name/--agent. Callers that
-// supplied a name keep round-tripping verbatim.
-async function defaultAgentId(value, targetPath) {
-  const explicit = normalizeString(value);
-  if (explicit && explicit.toLowerCase() !== "cli-user") {
-    return normalizeAgentId(value, "cli-user");
-  }
-  const authId = await _resolveAuthAgentId(targetPath);
-  if (authId) return authId;
-  return normalizeAgentId(value, "cli-user");
+async function defaultAgentId(value, _targetPath) {
+  return resolveSessionSayAgentId(value);
 }
 
 async function runWithConcurrency(items = [], concurrency = 1, worker = async () => null) {
@@ -933,6 +928,7 @@ export function registerSessionCommand(program) {
           targetPath,
           title: normalizeString(remoteSession.title),
           skipRemoteProbe: true,
+          remoteSession,
         });
         const payload = {
           command: "session ensure",
@@ -942,6 +938,7 @@ export function registerSessionCommand(program) {
           resumed: true,
           attached: true,
           materializedLocalSession: localSession.materialized,
+          refreshedLocalSession: Boolean(localSession.refreshed),
           verificationSource: verification.source,
           dashboardUrl: buildDashboardUrl(explicitSessionId),
         };
@@ -1145,6 +1142,7 @@ export function registerSessionCommand(program) {
         targetPath,
         title: normalizeString(remoteSession.title),
         skipRemoteProbe: true,
+        remoteSession,
       });
 
       const explicitAgent = normalizeString(options.agent);
@@ -1195,6 +1193,7 @@ export function registerSessionCommand(program) {
         status: joined.status,
         joinedAt: joined.joinedAt,
         materializedLocalSession: localSession.materialized,
+        refreshedLocalSession: Boolean(localSession.refreshed),
         verificationSource: verification.source,
         eventCount: Number.isFinite(eventCount) ? eventCount : 0,
         agentCount: Number.isFinite(agentCount) ? agentCount : 0,
@@ -1277,6 +1276,7 @@ export function registerSessionCommand(program) {
         agentId,
         event: persisted,
         materializedLocalSession: localSession.materialized,
+        refreshedLocalSession: Boolean(localSession.refreshed),
         remoteSync: remoteSync || undefined,
       };
       if (shouldEmitJson(options, command)) {
@@ -1364,6 +1364,7 @@ export function registerSessionCommand(program) {
         agentId,
         event: persisted,
         materializedLocalSession: localSession.materialized,
+        refreshedLocalSession: Boolean(localSession.refreshed),
         remoteSync,
       };
       if (shouldEmitJson(options, command)) {

package/src/session/recap.js

@@ -198,6 +198,35 @@ function buildRecapText({
   ).trim();
 }
 
+// Multi-agent session etiquette + read-path rules surfaced in the
+// context_briefing payload an agent receives on first join. Web
+// renders this as markdown (see sentinelayer-web Session.tsx
+// SessionMessage), so headers/lists/inline code are intentional.
+//
+// Keep this short and operationally actionable. Anything that's
+// purely doctrinal belongs in AGENTS.md, not the per-join briefing.
+const AGENT_JOIN_RULES = [
+  "**Welcome to this session.** Quick rules so we coordinate cleanly:",
+  "",
+  "**Reading the room** — When you join, the recap above summarizes activity since the last quiet stretch. To read further back, run `sl session read --remote --tail 50 --json` (bump `--tail` if you need more). Do this BEFORE responding so you don't repeat questions or miss a lock-and-claim someone else already opened.",
+  "",
+  "**Polling cadence** — Poll new events at most once per 60s (`sl session listen` or `sl session read --remote --tail N`). More frequent than that wastes budget and can hit per-user rate limits. Less frequent than ~5min and peers may think you went idle.",
+  "",
+  "**Writing back** — You can use **markdown**: bold, italic, lists, fenced code, and `inline code`. The web dashboard renders it. Plain text also works. Keep posts terse and technical — link to the work, don't recap it.",
+  "",
+  "**Coordination** — Lock-and-claim before you start a scope another agent could be on. If you push back on someone's approach, cite the specific assumption you disagree with and the file:line evidence.",
+  "",
+  "**Stop conditions** — If the human asks you to stop, stop. If 60+ minutes of total session silence, stop polling.",
+].join("\n");
+
+function buildAgentJoinBriefingText({ recap = "", forAgent = "" } = {}) {
+  const trimmedRecap = normalizeString(recap);
+  const trimmedAgent = normalizeString(forAgent);
+  const greeting = trimmedAgent ? `**${trimmedAgent}** joined. ${trimmedRecap}` : trimmedRecap;
+  const recapBlock = greeting || "Welcome — no prior session activity to summarize yet.";
+  return `${recapBlock}\n\n---\n\n${AGENT_JOIN_RULES}`;
+}
+
 function buildPeriodicText(recap = {}) {
   const summary = recap.summary && typeof recap.summary === "object" ? recap.summary : {};
   const elapsedMinutes = Number(summary.elapsedMinutes || 0);
@@ -303,6 +332,7 @@ export async function emitContextBriefing(
     maxEvents = DEFAULT_RECAP_MAX_EVENTS,
     targetPath = process.cwd(),
     nowIso = new Date().toISOString(),
+    includeJoinRules = true,
   } = {}
 ) {
   const recap = await buildSessionRecap(sessionId, {
@@ -311,6 +341,9 @@ export async function emitContextBriefing(
     targetPath,
     nowIso,
   });
+  const briefingMessage = includeJoinRules
+    ? buildAgentJoinBriefingText({ recap: recap.text, forAgent: forAgentId })
+    : recap.text;
   const event = createAgentEvent({
     event: "context_briefing",
     agentId: SENTI_AGENT_ID,
@@ -319,7 +352,9 @@ export async function emitContextBriefing(
     ts: recap.generatedAt,
     payload: {
       forAgent: normalizeString(forAgentId) || null,
+      message: briefingMessage,
       recap: recap.text,
+      rules: includeJoinRules ? AGENT_JOIN_RULES : null,
       ephemeral: true,
       style: RECAP_STYLE,
       generatedAt: recap.generatedAt,

package/src/session/remote-hydrate.js

@@ -20,7 +20,12 @@
 
 import { listSessionsFromApi, pollHumanMessages, pollSessionEvents } from "./sync.js";
 import { appendToStream, readStream } from "./stream.js";
-import { createSession, getSession } from "./store.js";
+import {
+  createSession,
+  getSession,
+  isSessionCacheExpired,
+  refreshSessionCacheForRemoteActivity,
+} from "./store.js";
 import { readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
 import {
   addSessionEventIdentityKeys,
@@ -42,10 +47,8 @@ async function readExistingRelayKeys(sessionId, { targetPath = process.cwd() } =
 
 async function ensureLocalSessionShell(sessionId, { targetPath = process.cwd() } = {}) {
   const existing = await getSession(sessionId, { targetPath });
-  if (existing) {
-    return { materialized: false, session: existing };
-  }
   let remoteStatus = "";
+  let remoteSession = null;
   const remoteList = await listSessionsFromApi({
     targetPath,
     includeArchived: true,
@@ -53,14 +56,40 @@ async function ensureLocalSessionShell(sessionId, { targetPath = process.cwd() }
   }).catch(() => null);
   if (remoteList?.ok) {
     const match = (remoteList.sessions || []).find((entry) => entry?.sessionId === sessionId);
+    remoteSession = match || null;
     remoteStatus = String(match?.archiveStatus || match?.status || "").trim().toLowerCase();
   }
+  if (existing) {
+    const existingStatus = String(existing.status || "").trim().toLowerCase();
+    const locallyClosedByStatus = existingStatus === "expired" || existingStatus === "archived";
+    const remoteAllowsRefresh =
+      ["active", "pending"].includes(remoteStatus) || (!remoteStatus && !locallyClosedByStatus);
+    if (isSessionCacheExpired(existing) && remoteAllowsRefresh) {
+      const refreshed = await refreshSessionCacheForRemoteActivity(sessionId, {
+        targetPath,
+        title: remoteSession?.title || "",
+        lastInteractionAt:
+          remoteSession?.lastInteractionAt ||
+          remoteSession?.lastActivityAt ||
+          remoteSession?.updatedAt ||
+          remoteSession?.createdAt ||
+          "",
+      });
+      return {
+        materialized: false,
+        refreshed: Boolean(refreshed),
+        session: refreshed || existing,
+        remoteStatus,
+      };
+    }
+    return { materialized: false, refreshed: false, session: existing, remoteStatus };
+  }
   const created = await createSession({
     targetPath,
     sessionId,
     title: `remote-${String(sessionId).slice(0, 8)}`,
   });
-  return { materialized: true, session: created, remoteStatus };
+  return { materialized: true, refreshed: false, session: created, remoteStatus };
 }
 
 function sourceFullyRelayed(events = [], successfulKeys = new Set()) {

package/src/session/store.js

@@ -388,7 +388,8 @@ function normalizeMetadata(raw = {}, { sessionId, targetPath, nowIso } = {}) {
 }
 
 function isExpired(metadata, nowIso = new Date().toISOString()) {
-  if (!metadata || normalizeSessionStatus(metadata.status) === SESSION_STATUS_EXPIRED) {
+  const status = normalizeSessionStatus(metadata?.status);
+  if (!metadata || status === SESSION_STATUS_EXPIRED || status === SESSION_STATUS_ARCHIVED) {
     return true;
   }
   const expiryEpoch = Date.parse(normalizeIsoTimestamp(metadata.expiresAt, nowIso));
@@ -399,6 +400,10 @@ function isExpired(metadata, nowIso = new Date().toISOString()) {
   return nowEpoch >= expiryEpoch;
 }
 
+export function isSessionCacheExpired(metadata, nowIso = new Date().toISOString()) {
+  return isExpired(metadata, nowIso);
+}
+
 function buildSessionPayload(metadata, paths, nowIso = new Date().toISOString()) {
   return {
     sessionId: metadata.sessionId,
@@ -526,6 +531,53 @@ export async function updateSessionTitle(
   return buildSessionPayload(saved, loaded.paths, nowIso);
 }
 
+export async function refreshSessionCacheForRemoteActivity(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    title = "",
+    ttlSeconds = DEFAULT_TTL_SECONDS,
+    lastInteractionAt = "",
+    nowIso = new Date().toISOString(),
+  } = {}
+) {
+  const loaded = await loadMetadata(sessionId, { targetPath });
+  if (!loaded) {
+    return null;
+  }
+  const normalizedTtlSeconds = normalizePositiveInteger(ttlSeconds, DEFAULT_TTL_SECONDS);
+  const remoteInteractionIso = normalizeIsoTimestamp(
+    lastInteractionAt,
+    loaded.metadata.lastInteractionAt || loaded.metadata.createdAt || nowIso
+  );
+  const currentInteractionEpoch = Date.parse(
+    normalizeIsoTimestamp(loaded.metadata.lastInteractionAt, loaded.metadata.createdAt || nowIso)
+  );
+  const remoteInteractionEpoch = Date.parse(remoteInteractionIso);
+  const lastInteractionIso =
+    Number.isFinite(remoteInteractionEpoch) &&
+    (!Number.isFinite(currentInteractionEpoch) || remoteInteractionEpoch > currentInteractionEpoch)
+      ? remoteInteractionIso
+      : normalizeIsoTimestamp(loaded.metadata.lastInteractionAt, nowIso);
+
+  const metadata = {
+    ...loaded.metadata,
+    updatedAt: nowIso,
+    expiresAt: toIsoAfterSeconds(nowIso, normalizedTtlSeconds),
+    ttlSeconds: normalizedTtlSeconds,
+    status: SESSION_STATUS_ACTIVE,
+    expiredAt: null,
+    lastInteractionAt: lastInteractionIso,
+  };
+  const normalizedTitle = normalizeString(title);
+  if (normalizedTitle) {
+    metadata.title = normalizedTitle;
+  }
+
+  const saved = await saveMetadata(metadata, loaded.paths);
+  return buildSessionPayload(saved, loaded.paths, nowIso);
+}
+
 export async function recordSessionRemoteTitleSync(
   sessionId,
   {