sentinelayer-cli 0.8.8 → 0.8.10

package/package.json

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

package/src/commands/session.js

@@ -261,8 +261,11 @@ export function registerSessionCommand(program) {
 
   session
     .command("start")
-    .description("Create a new persistent session with metadata + NDJSON stream")
+    .description(
+      "Start (or resume) a persistent session. By default reuses the most recent active session for this workspace; pass --force-new to always mint a fresh id.",
+    )
     .option("--path <path>", "Workspace path for the session", ".")
+    .option("--title <title>", "Human-readable label (shown in web sidebar + transcript)")
     .option(
       "--template <name>",
       "Optional quick-start template (code-review, security-audit, e2e-test, incident-response, standup)"
@@ -271,6 +274,15 @@ export function registerSessionCommand(program) {
       "--ttl-seconds <seconds>",
       `Session time-to-live in seconds (default ${DEFAULT_TTL_SECONDS}; template defaults override when omitted)`
     )
+    .option(
+      "--force-new",
+      "Always create a new session even if a recent active one exists for this workspace",
+    )
+    .option(
+      "--reuse-window-seconds <seconds>",
+      "Window in which an existing active session for this workspace will be reused (default 3600 = 1h)",
+      "3600",
+    )
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
@@ -284,15 +296,96 @@ export function registerSessionCommand(program) {
         "ttl-seconds",
         templateDefaultTtlSeconds
       );
+      const reuseWindowSeconds = parsePositiveInteger(
+        options.reuseWindowSeconds,
+        "reuse-window-seconds",
+        3600,
+      );
+
+      // Auto-resume: if there's an active local session for this same
+      // workspace path created in the last `reuseWindowSeconds`, reuse
+      // it instead of minting a new id. Kills the orphan-creation
+      // pattern where every CLI invocation produced a fresh empty
+      // session. `--force-new` opts back into the old behavior.
+      let resumed = null;
+      if (!options.forceNew) {
+        try {
+          const active = await listActiveSessions({ targetPath });
+          const cutoffMs = Date.now() - reuseWindowSeconds * 1000;
+          const candidates = active.filter((entry) => {
+            const createdMs = Date.parse(entry.createdAt || "");
+            return Number.isFinite(createdMs) && createdMs >= cutoffMs;
+          });
+          candidates.sort((a, b) =>
+            String(b.lastActivityAt || b.createdAt || "").localeCompare(
+              String(a.lastActivityAt || a.createdAt || ""),
+            ),
+          );
+          if (candidates.length > 0) {
+            resumed = candidates[0];
+          }
+        } catch (error) {
+          // listActiveSessions failure is non-fatal; fall through to fresh create.
+        }
+      }
+
       const startedAt = Date.now();
-      const created = await createSession({
-        targetPath,
-        ttlSeconds,
-        template,
-      });
+      let created;
+      if (resumed) {
+        // Surface the resumed session's metadata in the same shape
+        // createSession returns so downstream code stays unchanged.
+        created = {
+          sessionId: resumed.sessionId,
+          sessionDir: resumed.sessionDir || null,
+          metadataPath: resumed.metadataPath || null,
+          streamPath: resumed.streamPath || null,
+          createdAt: resumed.createdAt,
+          expiresAt: resumed.expiresAt,
+          elapsedTimer: 0,
+          renewalCount: resumed.renewalCount || 0,
+          status: resumed.status || "active",
+          template: resumed.template || null,
+          codebaseContext: resumed.codebaseContext || null,
+          resumed: true,
+        };
+      } else {
+        created = await createSession({
+          targetPath,
+          ttlSeconds,
+          template,
+        });
+      }
       const durationMs = Date.now() - startedAt;
       const launchPlan = template ? buildTemplateLaunchPlan(created.sessionId, template) : [];
       const dashboardUrl = buildDashboardUrl(created.sessionId);
+      const titleArg = normalizeString(options.title);
+
+      // If the caller passed --title, push it to the API so the web
+      // sidebar shows the label (best-effort, non-blocking).
+      if (titleArg) {
+        void (async () => {
+          try {
+            const session = await resolveActiveAuthSession({
+              cwd: targetPath,
+              env: process.env,
+              autoRotate: false,
+            });
+            if (!session?.token || !session?.apiUrl) return;
+            const apiUrl = String(session.apiUrl).replace(/\/+$/, "");
+            await requestJsonMutation(
+              `${apiUrl}/api/v1/sessions/${encodeURIComponent(created.sessionId)}/title`,
+              {
+                method: "POST",
+                operationName: "session.set_title",
+                headers: { Authorization: `Bearer ${session.token}` },
+                body: { title: titleArg },
+              },
+            );
+          } catch (_error) {
+            /* best-effort */
+          }
+        })();
+      }
 
       const payload = {
         command: "session start",
@@ -311,6 +404,8 @@ export function registerSessionCommand(program) {
         template: created.template,
         launchPlan,
         dashboardUrl,
+        resumed: Boolean(resumed),
+        title: titleArg || null,
       };
 
       // Best-effort admin visibility sync. Session creation remains local-first.
@@ -331,8 +426,12 @@ export function registerSessionCommand(program) {
       }
 
       if (template) {
-        console.log(`Session ${created.sessionId} created (template: ${template.id})`);
-        if (launchPlan.length > 0) {
+        console.log(
+          resumed
+            ? `Resumed session ${created.sessionId} (template: ${template.id})`
+            : `Session ${created.sessionId} created (template: ${template.id})`,
+        );
+        if (launchPlan.length > 0 && !resumed) {
           console.log("");
           console.log("Launch your agents:");
           for (const slot of launchPlan) {
@@ -344,13 +443,136 @@ export function registerSessionCommand(program) {
         return;
       }
 
-      console.log(pc.bold("Session created"));
+      console.log(pc.bold(resumed ? "Session resumed" : "Session created"));
       console.log(pc.gray(`Session: ${created.sessionId}`));
-      console.log(pc.gray(`Stream: ${created.streamPath}`));
-      console.log(pc.gray(`Created in ${durationMs}ms`));
+      if (titleArg) console.log(pc.gray(`Title: ${titleArg}`));
+      if (created.streamPath) console.log(pc.gray(`Stream: ${created.streamPath}`));
+      console.log(pc.gray(`${resumed ? "Resumed" : "Created"} in ${durationMs}ms`));
       console.log(
-        `status=${created.status} created_at=${created.createdAt} expires_at=${created.expiresAt} ttl_seconds=${ttlSeconds}`
+        `status=${created.status} created_at=${created.createdAt} expires_at=${created.expiresAt} ttl_seconds=${ttlSeconds}`,
       );
+      if (!resumed) {
+        console.log(
+          pc.gray(
+            "Tip: subsequent `slc session start` in this workspace within an hour will resume this session. Pass --force-new to override.",
+          ),
+        );
+      }
+    });
+
+  session
+    .command("continue")
+    .description("Alias for `session start --resume` — resume the most recent active session for this workspace, or create one if none exists.")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--title <title>", "Title applied if a new session is created")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      // Delegate to session start without --force-new. Commander parses
+      // the args for us via the parent action; here we just shell out.
+      const args = ["session", "start", "--path", String(options.path || ".")];
+      if (options.title) args.push("--title", String(options.title));
+      if (shouldEmitJson(options, command)) args.push("--json");
+      await program.parseAsync(args, { from: "user" });
+    });
+
+  session
+    .command("set-title <sessionId> <title>")
+    .description("Set the human-readable title on a session (visible in web sidebar + transcript).")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, title, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) throw new Error("session id is required.");
+      const normalizedTitle = normalizeString(title);
+      if (!normalizedTitle) throw new Error("title is required.");
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const session = await resolveActiveAuthSession({
+        cwd: targetPath,
+        env: process.env,
+        autoRotate: false,
+      });
+      if (!session?.token || !session?.apiUrl) {
+        throw new Error(`Not authenticated. Run \`${authLoginHint()}\` first.`);
+      }
+      const apiUrl = String(session.apiUrl).replace(/\/+$/, "");
+      const result = await requestJsonMutation(
+        `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/title`,
+        {
+          method: "POST",
+          operationName: "session.set_title",
+          headers: { Authorization: `Bearer ${session.token}` },
+          body: { title: normalizedTitle },
+        },
+      );
+      const payload = {
+        command: "session set-title",
+        sessionId: normalizedSessionId,
+        title: normalizedTitle,
+        result,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(pc.bold(`Title set on ${normalizedSessionId}`));
+      console.log(pc.gray(`title=${normalizedTitle}`));
+    });
+
+  session
+    .command("cleanup")
+    .description("Bulk-archive empty stale sessions on the SentinelLayer dashboard. Targets sessions with ≤1 events older than --cutoff-minutes.")
+    .option("--cutoff-minutes <n>", "Age threshold in minutes (default 60)", "60")
+    .option("--max-events <n>", "Max events to still treat as empty (default 1)", "1")
+    .option("--apply", "Actually archive (default is dry-run)")
+    .option("--path <path>", "Workspace path", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const cutoffMinutes = parsePositiveInteger(options.cutoffMinutes, "cutoff-minutes", 60);
+      const maxEvents = parsePositiveInteger(options.maxEvents, "max-events", 1);
+      const dryRun = !options.apply;
+      const session = await resolveActiveAuthSession({
+        cwd: targetPath,
+        env: process.env,
+        autoRotate: false,
+      });
+      if (!session?.token || !session?.apiUrl) {
+        throw new Error(`Not authenticated. Run \`${authLoginHint()}\` first.`);
+      }
+      const apiUrl = String(session.apiUrl).replace(/\/+$/, "");
+      const result = await requestJsonMutation(
+        `${apiUrl}/api/v1/sessions/sweep`,
+        {
+          method: "POST",
+          operationName: "session.sweep_empty",
+          headers: { Authorization: `Bearer ${session.token}` },
+          body: {
+            cutoffMinutes,
+            maxEvents,
+            dryRun,
+          },
+        },
+      );
+      const payload = {
+        command: "session cleanup",
+        dryRun,
+        cutoffMinutes,
+        maxEvents,
+        result,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      const scanned = result?.scanned || 0;
+      const archived = result?.archived || 0;
+      console.log(pc.bold(dryRun ? "Cleanup dry-run" : "Cleanup applied"));
+      console.log(
+        pc.gray(`scanned=${scanned} archived=${archived} cutoff=${cutoffMinutes}m max-events=${maxEvents}`),
+      );
+      if (dryRun && scanned > 0) {
+        console.log(pc.gray(`Re-run with --apply to archive these ${scanned} sessions.`));
+      }
     });
 
   session

package/src/session/agent-registry.js

@@ -7,6 +7,11 @@ import { STUCK_THRESHOLDS } from "../agents/jules/pulse.js";
 import { createAgentEvent } from "../events/schema.js";
 import { resolveSessionPaths } from "./paths.js";
 import { emitContextBriefing } from "./recap.js";
+import {
+  assignFriendlyName,
+  buildSentiWelcome,
+  shouldAutoRenameInRegistry,
+} from "./senti-naming.js";
 import { appendToStream } from "./stream.js";
 
 const AGENT_SNAPSHOT_SCHEMA_VERSION = "1.0.0";
@@ -181,7 +186,26 @@ export async function registerAgent(
 ) {
   const paths = resolveSessionPaths(sessionId, { targetPath });
   const nowIso = new Date().toISOString();
-  const resolvedAgentId = normalizeString(agentId) || generateAgentId(model);
+  const originalCallerAgentId = normalizeString(agentId);
+  let resolvedAgentId = originalCallerAgentId || generateAgentId(model);
+  let renamedFrom = "";
+
+  // Senti orchestrator hook: when the caller didn't supply an id, or
+  // supplied an explicit placeholder (`cli-user`, `agent-…`, `guest-…`),
+  // pick a friendly sequential name like `claude-3` / `codex-2` /
+  // `guest-1` so participants have a "face" in the transcript instead of
+  // a random hex blob. Caller-supplied real ids are NEVER renamed
+  // (kill tests like PR 348/351 register `codex-task-holder-1` with
+  // model="" and need the id to round-trip verbatim).
+  if (shouldAutoRenameInRegistry({ originalCallerAgentId })) {
+    const existingAgents = await listAgentsInternal(paths);
+    const friendly = assignFriendlyName({ model, existingAgents });
+    if (friendly && friendly !== resolvedAgentId.toLowerCase()) {
+      renamedFrom = resolvedAgentId;
+      resolvedAgentId = friendly;
+    }
+  }
+
   const snapshotPath = buildAgentSnapshotPath(paths, resolvedAgentId);
 
   const snapshot = normalizeAgentSnapshot(
@@ -210,6 +234,21 @@ export async function registerAgent(
     role: snapshot.role,
     status: snapshot.status,
   }, { targetPath });
+
+  if (renamedFrom) {
+    const 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 });
+  }
+
   if (normalizeString(snapshot.agentId).toLowerCase() !== "senti") {
     await emitContextBriefing(paths.sessionId, {
       forAgentId: snapshot.agentId,
@@ -223,6 +262,26 @@ export async function registerAgent(
   };
 }
 
+async function listAgentsInternal(paths) {
+  try {
+    const entries = await fsp.readdir(paths.agentsDir, { withFileTypes: true });
+    const out = [];
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      const raw = await readAgentSnapshot(path.join(paths.agentsDir, entry.name));
+      if (raw && typeof raw === "object" && raw.agentId) {
+        out.push({ agentId: raw.agentId, model: raw.model || "" });
+      }
+    }
+    return out;
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
+
 export async function heartbeatAgent(
   sessionId,
   agentId,

package/src/session/remote-hydrate.js

@@ -1,18 +1,29 @@
 /**
  * One-shot remote hydrator for the local NDJSON stream.
  *
- * Wraps `pollHumanMessages` (which speaks to the SentinelLayer API) with
- * a persisted cursor + `appendToStream`, so a CLI invocation can pull
- * web-posted messages into the local session log on demand. The
- * background daemon already does this on a poll loop; this module is
- * the synchronous counterpart that powers `slc session sync` and
- * `slc session read --remote`.
+ * Pulls events from the SentinelLayer API (BOTH human-posted messages
+ * AND agent-posted events) and appends them to the local session log
+ * with a persisted cursor. Powers `slc session sync` and
+ * `slc session read --remote`. The background daemon does the same thing
+ * on a poll loop; this is the synchronous counterpart.
+ *
+ * Why two pollers: Carter caught a multi-agent design bug in the
+ * standup session — agents polling via `pollHumanMessages` only saw
+ * web-posted human messages, never each other's `session_message` /
+ * `agent_response` events. Codex and claude talked past each other
+ * for hours ("Apologies — I missed your 5 updates"). Fix: also poll
+ * the durable `/sessions/{id}/events` endpoint (added in API #467)
+ * which returns ALL events. Per-source cursors keep the two pollers
+ * independent so a stuck human-message read doesn't block agent-event
+ * sync, and vice-versa.
  */
 
-import { pollHumanMessages } from "./sync.js";
+import { pollHumanMessages, pollSessionEvents } from "./sync.js";
 import { appendToStream } from "./stream.js";
 import { readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
 
+const EVENTS_CURSOR_SUFFIX = "events";
+
 /**
  * Fetch new human messages for a session, append them to the local
  * stream, and advance the persisted cursor. Returns a structured
@@ -33,6 +44,7 @@ export async function hydrateSessionFromRemote({
   targetPath = process.cwd(),
   since = undefined,
   _poll = pollHumanMessages,
+  _pollEvents = pollSessionEvents,
   _append = appendToStream,
 } = {}) {
   if (!sessionId || typeof sessionId !== "string") {
@@ -46,29 +58,61 @@ export async function hydrateSessionFromRemote({
     };
   }
 
-  const startCursor =
+  // Per-source cursors. The legacy human-message cursor is in the
+  // session's metadata file; the new agent-events cursor is in a
+  // sibling slot. Keeping them separate prevents a stuck/truncated
+  // poll on one source from poisoning the other.
+  const humanCursor =
     typeof since === "string" || since === null
       ? since
       : await readSyncCursor(sessionId, { targetPath });
+  const eventsCursor =
+    typeof since === "string" || since === null
+      ? since
+      : await readSyncCursor(sessionId, { targetPath, suffix: EVENTS_CURSOR_SUFFIX });
 
-  const polled = await _poll(sessionId, {
-    targetPath,
-    since: startCursor,
-  });
+  // 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([
+    _poll(sessionId, { targetPath, since: humanCursor }),
+    _pollEvents(sessionId, { targetPath, since: eventsCursor }),
+  ]);
 
-  if (!polled || !polled.ok) {
+  // 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 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 (c) seenCursors.add(c);
+    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 (c) seenCursors.add(c);
+    merged.push(e);
+  }
+
+  // If BOTH pollers failed, surface the human-message failure (the
+  // legacy contract) so existing callers see no behavior change. If
+  // only one fails, treat the relay as partial-but-successful.
+  if (!humanResult?.ok && !eventsResult?.ok) {
     return {
       ok: false,
-      reason: polled?.reason || "poll_failed",
+      reason: humanResult?.reason || eventsResult?.reason || "poll_failed",
       relayed: 0,
-      dropped: Array.isArray(polled?.dropped) ? polled.dropped.length : 0,
-      cursor: typeof polled?.cursor === "string" ? polled.cursor : startCursor || null,
+      dropped: Array.isArray(humanResult?.dropped) ? humanResult.dropped.length : 0,
+      cursor:
+        typeof humanResult?.cursor === "string" ? humanResult.cursor : humanCursor || null,
       persistedCursor: false,
     };
   }
 
   let relayed = 0;
-  for (const event of polled.events || []) {
+  for (const event of merged) {
     try {
       await _append(sessionId, event, { targetPath });
       relayed += 1;
@@ -79,17 +123,27 @@ export async function hydrateSessionFromRemote({
   }
 
   let persistedCursor = false;
-  if (typeof polled.cursor === "string" && polled.cursor.trim()) {
-    const result = await writeSyncCursor(sessionId, polled.cursor, { targetPath }).catch(() => null);
+  if (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()) {
+    await writeSyncCursor(sessionId, eventsResult.cursor, {
+      targetPath,
+      suffix: EVENTS_CURSOR_SUFFIX,
+    }).catch(() => null);
+  }
 
   return {
     ok: true,
     reason: "",
     relayed,
-    dropped: Array.isArray(polled.dropped) ? polled.dropped.length : 0,
-    cursor: typeof polled.cursor === "string" ? polled.cursor : startCursor || null,
+    dropped: Array.isArray(humanResult?.dropped) ? humanResult.dropped.length : 0,
+    cursor: typeof humanResult?.cursor === "string" ? humanResult.cursor : humanCursor || null,
     persistedCursor,
+    humanRelayed: (humanResult?.events || []).length,
+    eventsRelayed: (eventsResult?.events || []).length,
+    eventsCursor:
+      typeof eventsResult?.cursor === "string" ? eventsResult.cursor : eventsCursor || null,
   };
 }

package/src/session/senti-naming.js

@@ -0,0 +1,180 @@
+/**
+ * Senti — auto-name + welcome anonymous participants.
+ *
+ * When an agent joins without a clear name + model, Senti steps in:
+ *
+ *  1. `assignFriendlyName({ model, existingAgents })` — generates a
+ *     stable, human-readable id like "guest-3", "claude-2",
+ *     "codex-anon-1" derived from the model family + the next free
+ *     ordinal in the session. Sequential beats hex-suffix for the
+ *     ChatGPT-style "everyone has a face" UX Carter asked for.
+ *
+ *  2. `buildSentiWelcome({ agentId, model, role })` — produces the
+ *     payload for an `agent_identified` event Senti emits in the
+ *     stream so the new participant + everyone watching sees the
+ *     auto-assignment + how to override it.
+ *
+ *  3. `isAnonymousAgent({ agentId, model })` — single-source check
+ *     for "this registration didn't carry real identity" used by
+ *     callers to decide whether to invoke (1) and (2). Generic
+ *     prefixes (`agent-…`, `cli-user`) and unknown models qualify.
+ *
+ * This module never touches the network or the disk; it's pure naming
+ * logic that the agent-registry wires into the registration path.
+ */
+
+const ANONYMOUS_AGENT_PREFIXES = Object.freeze(["agent-", "cli-user", "guest-"]);
+const ANONYMOUS_MODELS = Object.freeze(["", "unknown", "cli", "anonymous"]);
+
+/**
+ * Strict: should the agent-registry auto-rename this registration?
+ *
+ * The hook's contract is "if a name is already there, leave it alone; if
+ * not, give them one." So we ONLY auto-rename when the caller gave us
+ * nothing OR the literal default placeholder `cli-user`. Any other
+ * caller-supplied id — even ones that *look* generic like `agent-alpha`,
+ * `guest-team`, or `codex-task-holder-1` — was an intentional choice and
+ * round-trips verbatim.
+ *
+ * Why so strict:
+ *  - e2e test #91 (CLI session commands flow) does `session join
+ *    --name agent-alpha` and asserts the id round-trips. The previous
+ *    rule (`agent-` prefix => rename) clobbered it.
+ *  - PR 348/351 kill tests register `codex-task-holder-1` with model=""
+ *    and need verbatim round-trip.
+ *  - `isAnonymousAgent` is intentionally separate and stays permissive
+ *    (model can flag) for downstream callers that decide whether to
+ *    *welcome* a participant; the registry hook is stricter.
+ *
+ * @param {{originalCallerAgentId: string}} params
+ * @returns {boolean}
+ */
+export function shouldAutoRenameInRegistry({ originalCallerAgentId = "" } = {}) {
+  const id = normalize(originalCallerAgentId).toLowerCase();
+  if (!id) return true;
+  return id === "cli-user";
+}
+
+/**
+ * @typedef {object} AgentLike
+ * @property {string} agentId
+ * @property {string} [model]
+ */
+
+function normalize(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+function familyFromModel(modelName) {
+  const lower = normalize(modelName).toLowerCase();
+  if (!lower || lower === "unknown" || lower === "anonymous") return "guest";
+  if (lower.includes("claude") || lower.includes("sonnet") || lower.includes("opus")) {
+    return "claude";
+  }
+  if (lower.includes("codex") || lower.includes("gpt-")) return "codex";
+  if (lower.includes("gemini")) return "gemini";
+  if (lower.includes("senti") || lower.includes("sentinel")) return "senti";
+  if (lower === "cli") return "guest";
+  // Otherwise use the first sanitized token so distinct providers stay
+  // distinct even when we don't recognize them.
+  const token = lower.split(/[\s:/_-]+/).find(Boolean) || "guest";
+  return token.replace(/[^a-z0-9]/g, "") || "guest";
+}
+
+/**
+ * Given the existing agent roster + the model the new participant
+ * declared (which may be empty/unknown), pick the next free ordinal
+ * within that family and return `<family>-<ordinal>`. Stable across
+ * runs because we pass the existing agents in.
+ *
+ * @param {{model?: string, existingAgents?: Array<AgentLike>}} params
+ * @returns {string}
+ */
+export function assignFriendlyName({ model = "", existingAgents = [] } = {}) {
+  const family = familyFromModel(model);
+  const taken = new Set(
+    (Array.isArray(existingAgents) ? existingAgents : [])
+      .map((agent) => normalize(agent && agent.agentId).toLowerCase())
+      .filter(Boolean),
+  );
+  for (let n = 1; n <= 9999; n += 1) {
+    const candidate = `${family}-${n}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+  // Pathological fallback — should never hit in practice, but a
+  // 4-digit ceiling without an escape would be a footgun.
+  return `${family}-${Date.now().toString(36)}`;
+}
+
+/**
+ * Decide whether the registration looks anonymous and therefore needs
+ * Senti to step in with a friendly name. We treat any of:
+ *
+ *  - empty / fallback agentId (`agent-…`, `cli-user`, `guest-…`)
+ *  - empty / unknown / cli model
+ *
+ * as a signal. Either alone is enough — the cli-user default agent
+ * still wants Senti's welcome the first time.
+ *
+ * @param {AgentLike} agent
+ * @returns {boolean}
+ */
+export function isAnonymousAgent(agent = {}) {
+  const id = normalize(agent.agentId).toLowerCase();
+  const model = normalize(agent.model).toLowerCase();
+  const idAnonymous =
+    !id ||
+    ANONYMOUS_AGENT_PREFIXES.some((prefix) => id.startsWith(prefix));
+  const modelAnonymous = ANONYMOUS_MODELS.includes(model);
+  return idAnonymous || modelAnonymous;
+}
+
+/**
+ * Build the payload Senti emits as `agent_identified` when it has
+ * stepped in to name a participant. Consumers (CLI / web) render it
+ * verbatim; the `instructions` line tells the user how to override.
+ *
+ * @param {{
+ *   agentId: string,
+ *   model?: string,
+ *   role?: string,
+ *   sessionId?: string,
+ *   wasAnonymous: boolean,
+ *   originalAgentId?: string,
+ * }} params
+ * @returns {{
+ *   alert: "agent_identified",
+ *   agentId: string,
+ *   model: string,
+ *   role: string,
+ *   wasAnonymous: boolean,
+ *   originalAgentId: string,
+ *   message: string,
+ *   instructions: string,
+ * }}
+ */
+export function buildSentiWelcome({
+  agentId,
+  model = "unknown",
+  role = "observer",
+  wasAnonymous = false,
+  originalAgentId = "",
+} = {}) {
+  const cleanModel = normalize(model) || "unknown";
+  const cleanRole = normalize(role) || "observer";
+  const cleanId = normalize(agentId);
+  const message = wasAnonymous
+    ? `Welcome ${cleanId}. I auto-named you because you joined without a name; introduce yourself anytime.`
+    : `Welcome ${cleanId}. You're in as ${cleanRole}.`;
+  const instructions = `Update with: sl session rename <sessionId> ${cleanId} --to <new-id> [--model <model>]`;
+  return {
+    alert: "agent_identified",
+    agentId: cleanId,
+    model: cleanModel,
+    role: cleanRole,
+    wasAnonymous: Boolean(wasAnonymous),
+    originalAgentId: normalize(originalAgentId),
+    message,
+    instructions,
+  };
+}

package/src/session/sync-cursor.js

@@ -13,8 +13,14 @@ import path from "node:path";
 
 import { resolveSessionDir } from "./paths.js";
 
-function cursorPath(sessionId, { targetPath } = {}) {
-  return path.join(resolveSessionDir(sessionId, { targetPath }), "remote-sync-cursor.json");
+function cursorPath(sessionId, { targetPath, suffix = "" } = {}) {
+  // Multiple cursors per session — the legacy file is human-messages,
+  // and `suffix="events"` tracks the agent-events poller separately
+  // so a stuck or skewed read on one source doesn't block the other.
+  const slug = typeof suffix === "string" && suffix.trim()
+    ? `remote-sync-cursor-${suffix.trim().toLowerCase().replace(/[^a-z0-9-]+/g, "-")}.json`
+    : "remote-sync-cursor.json";
+  return path.join(resolveSessionDir(sessionId, { targetPath }), slug);
 }
 
 /**
@@ -26,9 +32,9 @@ function cursorPath(sessionId, { targetPath } = {}) {
  * @param {{targetPath?: string}} [options]
  * @returns {Promise<string|null>}
  */
-export async function readSyncCursor(sessionId, { targetPath } = {}) {
+export async function readSyncCursor(sessionId, { targetPath, suffix = "" } = {}) {
   if (!sessionId) return null;
-  const filePath = cursorPath(sessionId, { targetPath });
+  const filePath = cursorPath(sessionId, { targetPath, suffix });
   try {
     const raw = await fsp.readFile(filePath, "utf-8");
     const parsed = JSON.parse(raw);
@@ -49,8 +55,8 @@ export async function readSyncCursor(sessionId, { targetPath } = {}) {
  * @param {{targetPath?: string}} [options]
  * @returns {Promise<{written: boolean, path: string}>}
  */
-export async function writeSyncCursor(sessionId, cursor, { targetPath } = {}) {
-  const filePath = cursorPath(sessionId, { targetPath });
+export async function writeSyncCursor(sessionId, cursor, { targetPath, suffix = "" } = {}) {
+  const filePath = cursorPath(sessionId, { targetPath, suffix });
   const normalized = typeof cursor === "string" ? cursor.trim() : "";
   if (!sessionId || !normalized) {
     return { written: false, path: filePath };

package/src/session/sync.js

@@ -735,6 +735,143 @@ export async function pollHumanMessages(
   }
 }
 
+/**
+ * Poll the durable session-events endpoint for ALL events (not just
+ * human-posted ones). Fixes the cross-agent blind spot Carter caught
+ * in the standup session: agents polling via `pollHumanMessages` only
+ * saw web-posted human messages, never each other's `session_message`
+ * / `agent_response` events. The result was codex and claude talking
+ * past each other ("Apologies — I missed your 5 updates").
+ *
+ * Endpoint contract: `GET /api/v1/sessions/{id}/events?after=<cursor>&limit=N`.
+ * The API returns events in chronological order with cursor-based
+ * pagination. We map each row to the local NDJSON envelope shape so
+ * `appendToStream` accepts it without modification.
+ *
+ * @param {string} sessionId
+ * @param {object} [options]
+ * @param {string} [options.targetPath]
+ * @param {string|null} [options.since] - cursor to start after; null = full history
+ * @param {number} [options.limit]      - default 200 (max from API)
+ * @param {number} [options.timeoutMs]  - per-request deadline
+ * @returns {Promise<{ok: boolean, reason: string, events: Array<object>, cursor: string|null}>}
+ */
+export async function pollSessionEvents(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    since = null,
+    limit = 200,
+    timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    resolveAuthSession = resolveActiveAuthSession,
+    fetchImpl = fetchWithTimeout,
+    nowMs = Date.now,
+  } = {}
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return {
+      ok: false,
+      reason: "invalid_session_id",
+      events: [],
+      cursor: normalizeString(since) || null,
+    };
+  }
+
+  const normalizedNowMs = Number(nowMs()) || Date.now();
+  if (isCircuitOpen(inboundCircuit, normalizedNowMs)) {
+    return {
+      ok: false,
+      reason: "circuit_breaker_open",
+      events: [],
+      cursor: normalizeString(since) || null,
+    };
+  }
+
+  let session = null;
+  try {
+    session = await resolveAuthSession({
+      cwd: targetPath,
+      env: process.env,
+      autoRotate: false,
+    });
+  } catch {
+    return {
+      ok: false,
+      reason: "no_session",
+      events: [],
+      cursor: normalizeString(since) || null,
+    };
+  }
+  if (!session || !session.token) {
+    return {
+      ok: false,
+      reason: "not_authenticated",
+      events: [],
+      cursor: normalizeString(since) || null,
+    };
+  }
+
+  const apiBaseUrl = resolveApiBaseUrl(session);
+  const query = new URLSearchParams();
+  const normalizedSince = normalizeString(since);
+  if (normalizedSince) {
+    query.set("after", normalizedSince);
+  }
+  query.set("limit", String(Math.max(1, Math.min(200, normalizePositiveInteger(limit, 200)))));
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/events?${query.toString()}`;
+
+  try {
+    const response = await fetchImpl(
+      endpoint,
+      {
+        method: "GET",
+        headers: { Authorization: `Bearer ${session.token}` },
+      },
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS)
+    );
+    if (!response || !response.ok) {
+      recordCircuitFailure(inboundCircuit, normalizedNowMs);
+      return {
+        ok: false,
+        reason: `api_${response ? response.status : "no_response"}`,
+        events: [],
+        cursor: normalizedSince || null,
+      };
+    }
+    const payload = await response.json().catch(() => ({}));
+    recordCircuitSuccess(inboundCircuit);
+
+    const items = Array.isArray(payload?.events) ? payload.events : [];
+    const acceptedEvents = [];
+    let lastCursor = normalizedSince || null;
+    for (const item of items) {
+      if (!item || typeof item !== "object") continue;
+      const cursor = normalizeString(item.cursor);
+      if (cursor) lastCursor = cursor;
+      // Pass through verbatim — the API already returns the NDJSON
+      // envelope shape that appendToStream expects.
+      acceptedEvents.push(item);
+    }
+
+    return {
+      ok: true,
+      reason: "",
+      events: acceptedEvents,
+      cursor: lastCursor,
+    };
+  } catch (error) {
+    recordCircuitFailure(inboundCircuit, normalizedNowMs);
+    return {
+      ok: false,
+      reason: normalizeString(error?.message) || "poll_failed",
+      events: [],
+      cursor: normalizedSince || null,
+    };
+  }
+}
+
+
 /**
  * List sessions owned by the active user via `GET /api/v1/sessions`.
  *

package/src/session/transcript.js

@@ -41,6 +41,7 @@ const TRANSCRIPT_EVENT_KINDS = new Set([
   "session_message",
   "session_say",
   "agent_response",
+  "session_usage",
   "human_relay",
   "agent_join",
   "agent_left",
@@ -153,9 +154,14 @@ function eventTimestamp(event) {
 
 function eventBody(event) {
   const payload = event && typeof event.payload === "object" ? event.payload : {};
+  // session_usage carries the response inside payload.response.text
+  const responseText =
+    typeof payload.response === "object" && payload.response
+      ? payload.response.text
+      : payload.response;
   const text =
     payload.message ||
-    payload.response ||
+    responseText ||
     payload.text ||
     payload.alert ||
     payload.reason ||

package/src/session/usage.js

@@ -0,0 +1,213 @@
+/**
+ * Session usage emitter — records every LLM interaction inside a session
+ * as a `session_usage` event so consumers (web dashboard, transcript
+ * download, telemetry sync) can surface live, accurate token + cost
+ * counters per-agent + session-wide.
+ *
+ * Senti orchestrator philosophy: "tokens on point every time any LLM
+ * interacts." Every persona / Jules / Codex / Claude call inside a
+ * session should land here so the running tally is authoritative.
+ *
+ * Event shape:
+ *
+ *   {
+ *     event: "session_usage",
+ *     ts: ISO8601,
+ *     agent: { id, model },
+ *     payload: {
+ *       interactionId,           // stable id for the LLM call
+ *       agentId, model, role,
+ *       inputTokens, outputTokens, totalTokens,
+ *       costUsd,
+ *       durationMs,              // wall-clock duration of the call
+ *       prompt: { tokens, chars },
+ *       response: { tokens, chars, text? },
+ *       usage: {                 // mirrors transcript.js payload.usage
+ *         totalTokens,
+ *         costUsd,
+ *         inputTokens,
+ *         outputTokens,
+ *       },
+ *     }
+ *   }
+ *
+ * Design choice: emit BOTH the convenient flat fields AND a
+ * `payload.usage` block, so transcript.js's existing usage roll-up
+ * picks it up without changes, while web UIs can display the structured
+ * fields directly without re-parsing.
+ */
+
+import process from "node:process";
+import { randomUUID } from "node:crypto";
+
+import { createAgentEvent } from "../events/schema.js";
+import { resolveSessionPaths } from "./paths.js";
+import { appendToStream } from "./stream.js";
+
+const SESSION_USAGE_EVENT = "session_usage";
+
+function n(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+function num(value) {
+  const v = Number(value);
+  return Number.isFinite(v) && v >= 0 ? v : 0;
+}
+
+function clipText(text, max = 4000) {
+  const s = n(text);
+  if (s.length <= max) return s;
+  return `${s.slice(0, max)}…`;
+}
+
+/**
+ * Emit a `session_usage` event into the session's NDJSON stream.
+ *
+ * @param {string} sessionId
+ * @param {object} params
+ * @param {string} params.agentId
+ * @param {string} [params.agentModel]
+ * @param {string} [params.role]
+ * @param {number} [params.inputTokens]
+ * @param {number} [params.outputTokens]
+ * @param {number} [params.costUsd]
+ * @param {number} [params.durationMs]
+ * @param {string} [params.prompt]            full prompt text (clipped)
+ * @param {string} [params.response]          full response text (clipped)
+ * @param {string} [params.interactionId]     opaque id for cross-event correlation
+ * @param {string} [params.targetPath]        workspace path (default cwd)
+ * @returns {Promise<{ event: string, interactionId: string, totalTokens: number, costUsd: number }>}
+ */
+export async function emitLLMInteraction(
+  sessionId,
+  {
+    agentId,
+    agentModel = "",
+    role = "",
+    inputTokens = 0,
+    outputTokens = 0,
+    costUsd = 0,
+    durationMs = 0,
+    prompt = "",
+    response = "",
+    interactionId = "",
+    targetPath = process.cwd(),
+  } = {},
+) {
+  const sid = n(sessionId);
+  if (!sid) throw new Error("sessionId is required.");
+  const aid = n(agentId);
+  if (!aid) throw new Error("agentId is required.");
+
+  const paths = resolveSessionPaths(sid, { targetPath });
+  const ts = new Date().toISOString();
+  const id = n(interactionId) || randomUUID();
+  const inT = Math.floor(num(inputTokens));
+  const outT = Math.floor(num(outputTokens));
+  const totalT = inT + outT;
+  const cost = Math.round(num(costUsd) * 1_000_000) / 1_000_000;
+
+  const promptText = clipText(prompt);
+  const responseText = clipText(response);
+
+  const payload = {
+    interactionId: id,
+    agentId: aid,
+    model: n(agentModel) || "unknown",
+    role: n(role) || "observer",
+    inputTokens: inT,
+    outputTokens: outT,
+    totalTokens: totalT,
+    costUsd: cost,
+    durationMs: Math.max(0, Math.floor(num(durationMs))),
+    prompt: { tokens: inT, chars: promptText.length },
+    response: {
+      tokens: outT,
+      chars: responseText.length,
+      text: responseText || undefined,
+    },
+    // Mirror into payload.usage so transcript.js + telemetry sync pick
+    // it up via the same code path used for ad-hoc agent_response usage.
+    usage: {
+      totalTokens: totalT,
+      costUsd: cost,
+      inputTokens: inT,
+      outputTokens: outT,
+    },
+  };
+
+  const envelope = createAgentEvent({
+    event: SESSION_USAGE_EVENT,
+    agentId: aid,
+    agentModel: n(agentModel) || "unknown",
+    sessionId: paths.sessionId,
+    payload,
+    ts,
+  });
+
+  await appendToStream(paths.sessionId, envelope, { targetPath });
+  return {
+    event: SESSION_USAGE_EVENT,
+    interactionId: id,
+    totalTokens: totalT,
+    costUsd: cost,
+  };
+}
+
+/**
+ * Aggregate `session_usage` events into a per-agent + global tally.
+ * Pure helper for renderers that want a snapshot at a point in time.
+ *
+ * @param {Array<object>} events
+ * @returns {{
+ *   perAgent: Map<string, { agentId, model, totalTokens, inputTokens, outputTokens, costUsd, interactions }>,
+ *   totals: { totalTokens, inputTokens, outputTokens, costUsd, interactions },
+ * }}
+ */
+export function aggregateSessionUsage(events = []) {
+  const perAgent = new Map();
+  const totals = {
+    totalTokens: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    costUsd: 0,
+    interactions: 0,
+  };
+  for (const event of events) {
+    if (!event || event.event !== SESSION_USAGE_EVENT) continue;
+    const payload = event.payload || {};
+    const agentId = n(payload.agentId || event.agent?.id);
+    if (!agentId) continue;
+    if (!perAgent.has(agentId)) {
+      perAgent.set(agentId, {
+        agentId,
+        model: n(payload.model || event.agent?.model) || "unknown",
+        totalTokens: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        costUsd: 0,
+        interactions: 0,
+      });
+    }
+    const record = perAgent.get(agentId);
+    record.totalTokens += num(payload.totalTokens);
+    record.inputTokens += num(payload.inputTokens);
+    record.outputTokens += num(payload.outputTokens);
+    record.costUsd += num(payload.costUsd);
+    record.interactions += 1;
+
+    totals.totalTokens += num(payload.totalTokens);
+    totals.inputTokens += num(payload.inputTokens);
+    totals.outputTokens += num(payload.outputTokens);
+    totals.costUsd += num(payload.costUsd);
+    totals.interactions += 1;
+  }
+  totals.costUsd = Math.round(totals.costUsd * 1_000_000) / 1_000_000;
+  for (const record of perAgent.values()) {
+    record.costUsd = Math.round(record.costUsd * 1_000_000) / 1_000_000;
+  }
+  return { perAgent, totals };
+}
+
+export const SESSION_USAGE_EVENT_KIND = SESSION_USAGE_EVENT;