sentinelayer-cli 0.20.0 → 0.22.0

package/package.json

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

package/src/commands/session.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import process from "node:process";
 import { setTimeout as sleep } from "node:timers/promises";
 import { createHash, randomUUID } from "node:crypto";
+import { spawn as defaultSpawn } from "node:child_process";
 
 import pc from "picocolors";
 
@@ -63,6 +64,7 @@ import {
 import { readSessionPreview } from "../session/preview.js";
 import {
   createSessionMessageAction,
+  fetchSessionPinnedMessages,
   listSessionMessageActions,
   listSessionsFromApi,
   probeSessionAccess,
@@ -75,6 +77,7 @@ import {
 import { hydrateSessionFromRemote } from "../session/remote-hydrate.js";
 import { mergeLiveSources } from "../session/live-source.js";
 import { listenSessionEvents } from "../session/listener.js";
+import { SESSION_LIVE_SUCCESS_TIPS } from "../session/coordination-guidance.js";
 import { buildSessionRecap } from "../session/recap.js";
 import { computeTranscriptStats } from "../session/transcript.js";
 import { deriveSessionTitle } from "../session/senti-naming.js";
@@ -1403,6 +1406,41 @@ function formatListenerCatchupNotice(catchup = {}) {
   ].join(" ");
 }
 
+// Periodic in-session coaching reminder surfaced by `session listen`. Keeps
+// agents continually nudged toward good coordination (ack, claim work, reply
+// in-thread, surface findings). `tick` makes each emission idempotent so the
+// same reminder is not deduped across the run.
+export function buildSessionCoachingEvent({
+  sessionId,
+  agentId,
+  agentModel = "cli",
+  displayName = "",
+  listenerId = "",
+  tick = 0,
+  tips = SESSION_LIVE_SUCCESS_TIPS,
+} = {}) {
+  const tipList = Array.isArray(tips) && tips.length ? tips : SESSION_LIVE_SUCCESS_TIPS;
+  return createAgentEvent({
+    event: "session_coaching",
+    sessionId,
+    agent: {
+      id: agentId,
+      model: normalizeString(agentModel) || "cli",
+      role: "listener",
+      displayName: normalizeString(displayName) || agentId,
+      clientKind: "cli",
+    },
+    eventId: `session-coaching-${listenerId || agentId}-${tick}`,
+    idempotencyToken: `session-coaching:${listenerId || agentId}:${tick}`,
+    payload: compactPayload({
+      source: "session_listen",
+      kind: "coaching",
+      message: "Session success reminders:",
+      tips: [...tipList],
+    }),
+  });
+}
+
 function buildListenerCatchupEvent({
   sessionId,
   agentId,
@@ -1537,6 +1575,102 @@ export function shouldBlockImplicitCliUserSessionSay(identity = {}) {
   return identity?.source === "fallback" && normalizeString(identity?.agentId) === "cli-user";
 }
 
+/**
+ * Wake hook for `session listen --wake "<command>"`. This is the reusable
+ * notify->resume bridge: when the listener emits an event addressed to this
+ * agent (or broadcast — including low-noise actions like ack/like), it runs a
+ * host command so the host can resume/wake its agent. The event JSON is piped
+ * to the command's stdin and key fields are exposed as SL_WAKE_* env vars.
+ *
+ * Bursts are coalesced: if a wake is already running, the latest event is
+ * queued and fired once when the current one finishes, so a flood of activity
+ * triggers one trailing wake instead of a storm of processes.
+ */
+export function createSessionWakeRunner({
+  command,
+  sessionId,
+  agentId,
+  emit = () => {},
+  spawnImpl = defaultSpawn,
+} = {}) {
+  const wakeCommand = normalizeString(command);
+  let busy = false;
+  let pending = null;
+
+  const run = (event) => {
+    if (!wakeCommand) return;
+    if (busy) {
+      pending = event ?? {};
+      return;
+    }
+    busy = true;
+    const env = {
+      ...process.env,
+      SL_WAKE_SESSION_ID: normalizeString(sessionId),
+      SL_WAKE_AGENT_ID: normalizeString(agentId),
+      SL_WAKE_EVENT_TYPE: normalizeString(event?.event),
+      SL_WAKE_EVENT_CURSOR: normalizeString(event?.cursor),
+      SL_WAKE_EVENT_SEQUENCE: String(event?.sequenceId ?? event?.sequence_id ?? ""),
+      SL_WAKE_ACTOR_ID: normalizeString(event?.agent?.id || event?.agentId),
+    };
+    let child;
+    try {
+      child = spawnImpl(wakeCommand, { shell: true, env, stdio: ["pipe", "ignore", "ignore"] });
+    } catch (error) {
+      busy = false;
+      emit({ status: "error", reason: normalizeString(error?.message) || "spawn_failed" });
+      return;
+    }
+    emit({
+      status: "fired",
+      eventType: env.SL_WAKE_EVENT_TYPE,
+      cursor: env.SL_WAKE_EVENT_CURSOR,
+      actorId: env.SL_WAKE_ACTOR_ID,
+    });
+    try {
+      if (child && child.stdin) {
+        child.stdin.write(JSON.stringify(event ?? {}));
+        child.stdin.end();
+      }
+    } catch {
+      // Broken pipe (command ignored stdin) is non-fatal for a wake hook.
+    }
+    const finish = (reason) => {
+      busy = false;
+      if (reason) emit({ status: "error", reason });
+      const next = pending;
+      pending = null;
+      if (next !== null) run(next);
+    };
+    if (child && typeof child.on === "function") {
+      child.on("error", (error) => finish(normalizeString(error?.message) || "wake_failed"));
+      child.on("exit", (code) => finish(code && code !== 0 ? `exit_${code}` : ""));
+    } else {
+      finish("");
+    }
+  };
+
+  return { trigger: run, hasCommand: Boolean(wakeCommand) };
+}
+
+// Message actions (ack/like/dislike/reply/view/working_on) must be authored by
+// a concrete agent identity. The CLI's bare `cli-user` default is a reserved
+// label the API rejects (api_422), so treat it as "unset" and resolve the real
+// agent the same way `session say` does (explicit --agent > SENTINELAYER_AGENT_ID
+// > the single joined agent). Returns the resolved identity; callers should use
+// shouldBlockImplicitCliUserSessionSay() to refuse the implicit cli-user
+// fallback before sending a request that is guaranteed to fail.
+export async function resolveMessageActionIdentity({
+  sessionId,
+  optionAgent = "",
+  targetPath = process.cwd(),
+  env = process.env,
+} = {}) {
+  const explicit = normalizeString(optionAgent);
+  const agentSeed = explicit && explicit.toLowerCase() !== "cli-user" ? explicit : "";
+  return resolveSessionSayIdentity({ sessionId, agentId: agentSeed, targetPath, env });
+}
+
 async function ensureSessionSayAgentRegistered(
   sessionId,
   agent = {},
@@ -1610,6 +1744,41 @@ async function resolveSessionAgentEnvelope(
   return Object.fromEntries(Object.entries(envelope).filter(([, value]) => value !== undefined));
 }
 
+// Builds the lock/unlock say-convention directive the session daemon parses
+// into the authoritative file-lock registry. Kept pure + exported for testing.
+export function buildSessionLockDirective(verb, file, intent = "") {
+  const normalizedFile = normalizeString(file);
+  const normalizedIntent = normalizeString(intent);
+  if (verb === "unlock") {
+    return `unlock: ${normalizedFile} - ${normalizedIntent || "done"}`;
+  }
+  return normalizedIntent ? `lock: ${normalizedFile} - ${normalizedIntent}` : `lock: ${normalizedFile}`;
+}
+
+// Posts a coordination directive (e.g. "lock: <file> - <intent>") as a session
+// message so the session daemon processes it into the authoritative file-lock
+// registry. Used by `session lock`/`unlock` as ergonomic sugar over the
+// say-convention; locks are advisory + daemon-enforced with TTL auto-release,
+// so this is a best-effort post.
+async function postSessionDirectiveMessage(sessionId, message, {
+  agentId,
+  targetPath = process.cwd(),
+} = {}) {
+  const clientMessageId = `cli-${randomUUID()}`;
+  const agent = await resolveSessionAgentEnvelope(sessionId, agentId, { targetPath });
+  await ensureSessionSayAgentRegistered(sessionId, agent, { targetPath });
+  const event = createAgentEvent({
+    event: "session_message",
+    agent,
+    sessionId,
+    payload: { message, channel: "session", clientMessageId },
+  });
+  event.eventId = clientMessageId;
+  event.idempotencyToken = clientMessageId;
+  const result = await syncSessionEventToApi(sessionId, event, { targetPath });
+  return { event, result };
+}
+
 async function runWithConcurrency(items = [], concurrency = 1, worker = async () => null) {
   const normalizedItems = Array.isArray(items) ? items : [];
   const normalizedConcurrency = Math.max(
@@ -2879,7 +3048,23 @@ export function registerSessionCommand(program) {
     }
     await ensureLocalSessionForRemoteCommand(normalizedSessionId, { targetPath });
     const note = normalizeString(noteOverride) || normalizeString(options.note);
-    const agentId = await defaultAgentId(options.agent, targetPath);
+    // Resolve the authoring agent. The bare `cli-user` default is rejected by
+    // the API (api_422); resolveMessageActionIdentity treats it as unset and
+    // falls back to the joined agent. If no concrete identity resolves, fail
+    // with actionable guidance instead of firing a request guaranteed to 422.
+    const identity = await resolveMessageActionIdentity({
+      sessionId: normalizedSessionId,
+      optionAgent: options.agent,
+      targetPath,
+      env: process.env,
+    });
+    if (shouldBlockImplicitCliUserSessionSay(identity)) {
+      throw new Error(
+        identity.identityWarning ||
+          `${commandName} requires an agent identity; pass --agent <id>, set SENTINELAYER_AGENT_ID, or run session join --agent <id> first.`,
+      );
+    }
+    const agentId = identity.agentId;
     const idempotencyKey =
       normalizeString(options.idempotencyKey) ||
       defaultActionIdempotencyKey({
@@ -2970,7 +3155,7 @@ export function registerSessionCommand(program) {
     .option("--target-cursor <cursor>", "Target event cursor")
     .option("--target-action-id <uuid>", "Target a threaded reply/action by action UUID")
     .option("--note <text>", "Optional action note or reply body")
-    .option("--agent <id>", "Agent id for local idempotency metadata", "cli-user")
+    .option("--agent <id>", "Agent id authoring the action (defaults to the joined session agent)")
     .option("--idempotency-key <key>", "Explicit idempotency key")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
@@ -2984,7 +3169,7 @@ export function registerSessionCommand(program) {
     .option("--target-sequence <n>", "Target event sequence id")
     .option("--target-cursor <cursor>", "Target event cursor")
     .option("--target-action-id <uuid>", "Target a threaded reply/action by action UUID")
-    .option("--agent <id>", "Agent id for local idempotency metadata", "cli-user")
+    .option("--agent <id>", "Agent id authoring the action (defaults to the joined session agent)")
     .option("--idempotency-key <key>", "Explicit idempotency key")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
@@ -3005,7 +3190,7 @@ export function registerSessionCommand(program) {
   session
     .command("reply <sessionId> <targetSequenceId> <message...>")
     .description("Reply to a target session event using the message-action channel")
-    .option("--agent <id>", "Agent id for local idempotency metadata", "cli-user")
+    .option("--agent <id>", "Agent id authoring the action (defaults to the joined session agent)")
     .option("--idempotency-key <key>", "Explicit idempotency key")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
@@ -3025,7 +3210,7 @@ export function registerSessionCommand(program) {
   session
     .command("comment <sessionId> <targetSequenceId> <message...>")
     .description("Alias for `session reply`; add a threaded comment to a target event")
-    .option("--agent <id>", "Agent id for local idempotency metadata", "cli-user")
+    .option("--agent <id>", "Agent id authoring the action (defaults to the joined session agent)")
     .option("--idempotency-key <key>", "Explicit idempotency key")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
@@ -3045,7 +3230,7 @@ export function registerSessionCommand(program) {
   session
     .command("view <sessionId> <targetSequenceId>")
     .description("Manually backfill a read receipt for a target session event")
-    .option("--agent <id>", "Agent id for local idempotency metadata", "cli-user")
+    .option("--agent <id>", "Agent id authoring the action (defaults to the joined session agent)")
     .option("--idempotency-key <key>", "Explicit idempotency key")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
@@ -3060,6 +3245,172 @@ export function registerSessionCommand(program) {
       });
     });
 
+  session
+    .command("pins <sessionId>")
+    .description("List the session's pinned messages with their content so agents can read them")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      await ensureLocalSessionForRemoteCommand(normalizedSessionId, { targetPath });
+      const result = await fetchSessionPinnedMessages(normalizedSessionId, { targetPath });
+      if (!result.ok) {
+        throw new Error(`Could not load pinned messages (${result.reason || "unknown"}).`);
+      }
+      const pinLimit = result.pinLimit || 10;
+      const payload = {
+        command: "session pins",
+        sessionId: normalizedSessionId,
+        pinLimit,
+        count: result.count,
+        pins: result.pins,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return payload;
+      }
+      if (!result.count) {
+        console.log(pc.gray("No pinned messages in this session."));
+        return payload;
+      }
+      console.log(pc.bold(`📌 Pinned messages (${result.count}/${pinLimit})`));
+      for (const pin of result.pins) {
+        const seqLabel = pin.targetSequenceId ? `#${pin.targetSequenceId}` : "(unknown sequence)";
+        const author = pin.author || "unknown";
+        const pinnedBy = pin.pinnedBy ? ` · pinned by ${pin.pinnedBy}` : "";
+        const when = pin.pinnedAt ? ` · ${pin.pinnedAt}` : "";
+        console.log("");
+        console.log(pc.cyan(`${seqLabel}  ${author}${pinnedBy}${when}`));
+        if (pin.content) {
+          for (const line of String(pin.content).split("\n")) {
+            console.log(`  ${line}`);
+          }
+        } else {
+          console.log(pc.gray("  (no readable text content for this pinned event)"));
+        }
+      }
+      return payload;
+    });
+
+  const runLockDirectiveCommand = async (verb, sessionId, files, options, command) => {
+    const normalizedSessionId = normalizeString(sessionId);
+    if (!normalizedSessionId) {
+      throw new Error("session id is required.");
+    }
+    const fileList = (Array.isArray(files) ? files : [files])
+      .map((file) => normalizeString(file))
+      .filter(Boolean);
+    if (fileList.length === 0) {
+      throw new Error(`session ${verb} requires at least one file path.`);
+    }
+    const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+    await ensureLocalSessionForRemoteCommand(normalizedSessionId, { targetPath });
+    const identity = await resolveMessageActionIdentity({
+      sessionId: normalizedSessionId,
+      optionAgent: options.agent,
+      targetPath,
+      env: process.env,
+    });
+    if (shouldBlockImplicitCliUserSessionSay(identity)) {
+      throw new Error(
+        identity.identityWarning ||
+          `session ${verb} requires an agent identity; pass --agent <id>, set SENTINELAYER_AGENT_ID, or run session join --agent <id> first.`,
+      );
+    }
+    const intent = normalizeString(options.intent);
+    const processed = [];
+    for (const file of fileList) {
+      const directive = buildSessionLockDirective(verb, file, intent);
+      await postSessionDirectiveMessage(normalizedSessionId, directive, {
+        agentId: identity.agentId,
+        targetPath,
+      });
+      processed.push(file);
+    }
+    const payload = {
+      command: `session ${verb}`,
+      sessionId: normalizedSessionId,
+      agentId: identity.agentId,
+      files: processed,
+    };
+    if (shouldEmitJson(options, command)) {
+      console.log(JSON.stringify(payload, null, 2));
+      return payload;
+    }
+    const action = verb === "lock" ? "Requested lock on" : "Released";
+    console.log(pc.green(`${action} ${processed.length} file(s) as ${identity.agentId}: ${processed.join(", ")}`));
+    if (verb === "lock") {
+      console.log(
+        pc.gray("Senti enforces fail-closed; locks auto-release on TTL. Release with `sl session unlock`."),
+      );
+    }
+    return payload;
+  };
+
+  session
+    .command("lock <sessionId> <files...>")
+    .description("Claim exclusive file locks via Senti (fail-closed, TTL auto-release)")
+    .option("--intent <text>", "Why you're locking these files (shown to peers)")
+    .option("--agent <id>", "Agent id claiming the lock (defaults to the joined session agent)")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, files, options, command) => {
+      await runLockDirectiveCommand("lock", sessionId, files, options, command);
+    });
+
+  session
+    .command("unlock <sessionId> <files...>")
+    .description("Release file locks you hold (Senti only lets the holder release)")
+    .option("--intent <text>", "Optional note on the release")
+    .option("--agent <id>", "Agent id releasing the lock (defaults to the joined session agent)")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, files, options, command) => {
+      await runLockDirectiveCommand("unlock", sessionId, files, options, command);
+    });
+
+  session
+    .command("locks <sessionId>")
+    .description("List active file locks for the session (who holds what, and when they expire)")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      await ensureLocalSessionForRemoteCommand(normalizedSessionId, { targetPath });
+      const locks = await listFileLocks(normalizedSessionId, { targetPath });
+      const lockList = Array.isArray(locks) ? locks : [];
+      const payload = {
+        command: "session locks",
+        sessionId: normalizedSessionId,
+        count: lockList.length,
+        locks: lockList,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return payload;
+      }
+      if (lockList.length === 0) {
+        console.log(pc.gray("No active file locks."));
+        return payload;
+      }
+      console.log(pc.bold(`Active file locks (${lockList.length})`));
+      for (const lock of lockList) {
+        const file = normalizeString(lock.file || lock.filePath) || "(unknown file)";
+        const holder = normalizeString(lock.agentId) || "unknown";
+        const expires = normalizeString(lock.expiresAt);
+        console.log(pc.cyan(`  ${file}`) + pc.gray(`  held by ${holder}${expires ? ` · expires ${expires}` : ""}`));
+      }
+      return payload;
+    });
+
   session
     .command("listen")
     .description("Background-poll a session for events addressed to this agent or broadcast")
@@ -3103,6 +3454,16 @@ export function registerSessionCommand(program) {
     .option("--from-now", "Advance the listen cursor to the latest durable event before polling")
     .option("--replay", "Emit matching historical events on the first poll")
     .option("--max-polls <n>", "Stop after N poll cycles (useful for tests and smoke checks)")
+    .option(
+      "--wake <command>",
+      "Wake hook: run this shell command on each matched event (notify->resume bridge). Event JSON is piped to stdin; SL_WAKE_* env vars are set.",
+    )
+    .option(
+      "--coaching-interval <seconds>",
+      "Seconds between in-session success reminders (ack, claim work, reply in-thread). Default 900; 0 disables.",
+      "900",
+    )
+    .option("--no-coaching", "Do not emit periodic in-session success reminders")
     .action(async (options) => {
       const normalizedSessionId = resolveSessionIdOption(options);
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
@@ -3126,6 +3487,32 @@ export function registerSessionCommand(program) {
       if (!["ndjson", "text"].includes(emitFormat)) {
         throw new Error("--emit must be one of: ndjson, text.");
       }
+      // Optional wake hook: run a host command on each matched event so the
+      // host can resume/wake its agent (the notify->resume bridge).
+      const emitWakeNotice = (payload = {}) => {
+        if (emitFormat === "ndjson") {
+          console.log(
+            JSON.stringify(
+              createAgentEvent({
+                event: "session_wake_hook",
+                agentId,
+                sessionId: normalizedSessionId,
+                payload,
+              }),
+            ),
+          );
+        } else {
+          const status = normalizeString(payload.status) || "fired";
+          const detail = payload.reason ? ` (${payload.reason})` : payload.eventType ? ` ${payload.eventType}` : "";
+          console.log(pc.cyan(`wake hook ${status}${detail}`));
+        }
+      };
+      const wakeRunner = createSessionWakeRunner({
+        command: options.wake,
+        sessionId: normalizedSessionId,
+        agentId,
+        emit: emitWakeNotice,
+      });
       const requestedTransport = normalizeString(options.transport).toLowerCase() || "auto";
       if (!["auto", "stream", "poll"].includes(requestedTransport)) {
         throw new Error("--transport must be one of: auto, stream, poll.");
@@ -3150,6 +3537,44 @@ export function registerSessionCommand(program) {
       const presenceIntervalMs = Math.max(1, presenceIntervalSeconds) * 1000;
       let lastPresenceHeartbeatMs = 0;
 
+      // Periodic in-session success reminders (ack, claim work, reply
+      // in-thread). Long-running interactive listeners only — skipped under
+      // --max-polls (smoke/test) and when --no-coaching is set.
+      const coachingIntervalSeconds =
+        options.coaching === false
+          ? 0
+          : parsePositiveInteger(options.coachingInterval, "coaching-interval", 900);
+      let coachingTick = 0;
+      const emitCoaching = () => {
+        if (emitFormat === "ndjson") {
+          console.log(
+            JSON.stringify(
+              buildSessionCoachingEvent({
+                sessionId: normalizedSessionId,
+                agentId,
+                agentModel,
+                displayName,
+                listenerId,
+                tick: coachingTick++,
+              }),
+            ),
+          );
+        } else {
+          console.log(pc.cyan("Session success reminders:"));
+          for (const tip of SESSION_LIVE_SUCCESS_TIPS) {
+            console.log(pc.gray(`  - ${tip}`));
+          }
+        }
+      };
+      let coachingTimer = null;
+      if (coachingIntervalSeconds > 0 && maxPolls === null) {
+        emitCoaching();
+        coachingTimer = setInterval(emitCoaching, coachingIntervalSeconds * 1000);
+        if (coachingTimer && typeof coachingTimer.unref === "function") {
+          coachingTimer.unref();
+        }
+      }
+
       if (emitFormat === "text") {
         console.log(
           pc.gray(
@@ -3214,6 +3639,9 @@ export function registerSessionCommand(program) {
             } else {
               console.log(formatEventLine(event));
             }
+            // Fire the wake hook for any matched event (incl. ack/like) so the
+            // host can resume its agent.
+            wakeRunner.trigger(event);
           },
           onError: async (result) => {
             const reason = normalizeString(result?.reason) || "poll_failed";
@@ -3257,6 +3685,9 @@ export function registerSessionCommand(program) {
           },
         });
       } finally {
+        if (coachingTimer) {
+          clearInterval(coachingTimer);
+        }
         process.removeListener("SIGINT", onSigint);
       }
     });

package/src/legacy-cli.js

@@ -226,6 +226,11 @@ function printUsage() {
   console.log("  sl session comment <id> <seq> \"msg\"  Alias for threaded reply");
   console.log("  sl session read <id> --remote --agent <id>  Read stream events and auto-record views");
   console.log("  sl session view <id> <seq>          Manually backfill a read receipt");
+  console.log("  sl session pins <id> --json         List pinned messages with content (readable by agents)");
+  console.log("  sl session lock <id> <files...> --intent <why>  Claim file locks (fail-closed, TTL auto-release)");
+  console.log("  sl session unlock <id> <files...>   Release file locks you hold");
+  console.log("  sl session locks <id> --json        List active file locks (holder + expiry)");
+  console.log("  sl session listen --session <id> --agent <id>  Background-poll a session for new events");
   console.log("  sl session recap now <id> --remote --json  Summarize current owners, locks, and work");
   console.log("  sl session daemon --session <id>    Run Senti recaps/checkpoints for long rooms");
   console.log("  sl session read <id> --tail 20      Read local session stream events");

package/src/session/coordination-guidance.js

@@ -21,6 +21,23 @@ export function getCoordinationEtiquetteItems() {
   return [...COORDINATION_ETIQUETTE_ITEMS];
 }
 
+// Short, punchy success reminders surfaced periodically by `session listen` so
+// agents are continually nudged to coordinate well (Carter: "keep reminding
+// agents how to be successful... always ack and say if you're working on
+// something"). Kept tight on purpose — this fires on a timer, so it must stay
+// low-noise.
+export const SESSION_LIVE_SUCCESS_TIPS = Object.freeze([
+  "Ack messages you've read: `sl session react <id> ack --target-sequence <n>` — don't go silent.",
+  "Say what you're doing: claim work with `sl session action <id> working_on --target-sequence <n>`.",
+  'Reply in-thread with `sl session reply <id> <seq> "..."`; start a new top-level post only when needed.',
+  "Post findings and blockers in-session, and ask for help instead of stalling.",
+  "Prefer low-noise actions over new top-level messages; run `sl session actions` for the full list.",
+]);
+
+export function getSessionLiveSuccessTips() {
+  return [...SESSION_LIVE_SUCCESS_TIPS];
+}
+
 export function renderCoordinationNumberedList({
   items = COORDINATION_ETIQUETTE_ITEMS,
   indent = "",

package/src/session/sync.js

@@ -1643,6 +1643,123 @@ export async function listSessionMessageActions(
   }
 }
 
+function pinnedEventContentText(event = {}) {
+  const payload = event && typeof event === "object" ? event.payload || {} : {};
+  return (
+    normalizeString(payload.note) ||
+    normalizeString(payload.message) ||
+    normalizeString(payload.text) ||
+    normalizeString(payload.content) ||
+    normalizeString(payload.summary) ||
+    ""
+  );
+}
+
+function pinnedEventAuthorId(event = {}) {
+  const agent = event && typeof event === "object" ? event.agent || {} : {};
+  return normalizeString(agent.id || agent.agentId) || normalizeString(event.agentId) || "";
+}
+
+/**
+ * Resolve the session's active pinned messages, enriched with each pinned
+ * message's author and content so a CLI agent can actually read them (not just
+ * see sequence numbers). Pins come from the action projection
+ * (`projection.pinnedMessages`, capped at `projection.pinLimit`); content is
+ * resolved per pinned sequence via `/events/before`. Bounded by the pin cap
+ * (<= 10), so at most ~10 single-event lookups.
+ */
+export async function fetchSessionPinnedMessages(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    resolveAuthSession = resolveActiveAuthSession,
+    fetchImpl = fetchWithTimeout,
+    nowMs = Date.now,
+    listActions = listSessionMessageActions,
+    fetchEventsBefore = pollSessionEventsBefore,
+  } = {}
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return { ok: false, reason: "invalid_session_id", pins: [], pinLimit: 0, count: 0 };
+  }
+
+  const actionsResult = await listActions(normalizedSessionId, {
+    targetPath,
+    timeoutMs,
+    resolveAuthSession,
+    fetchImpl,
+    nowMs,
+  });
+  if (!actionsResult || !actionsResult.ok) {
+    return {
+      ok: false,
+      reason: normalizeString(actionsResult?.reason) || "actions_read_failed",
+      pins: [],
+      pinLimit: 0,
+      count: 0,
+    };
+  }
+
+  const projection = actionsResult.projection && typeof actionsResult.projection === "object"
+    ? actionsResult.projection
+    : {};
+  const pinLimit = Number(projection.pinLimit) || 0;
+  const pinnedActions = Array.isArray(projection.pinnedMessages) ? projection.pinnedMessages : [];
+
+  const pins = await Promise.all(
+    pinnedActions.map(async (action) => {
+      const targetSequenceId = Number(action?.targetSequenceId) || 0;
+      const base = {
+        targetSequenceId,
+        targetCursor: normalizeString(action?.targetCursor) || null,
+        pinnedBy: normalizeString(action?.actorId) || "",
+        pinnedByKind: normalizeString(action?.actorKind) || "",
+        pinnedAt: normalizeString(action?.createdAt) || "",
+        author: "",
+        content: "",
+        resolved: false,
+      };
+      if (targetSequenceId <= 0) {
+        return base;
+      }
+      const eventsResult = await fetchEventsBefore(normalizedSessionId, {
+        targetPath,
+        beforeSequence: targetSequenceId + 1,
+        limit: 1,
+        timeoutMs,
+        resolveAuthSession,
+        fetchImpl,
+        nowMs,
+      });
+      if (eventsResult && eventsResult.ok && Array.isArray(eventsResult.events)) {
+        const match =
+          eventsResult.events.find(
+            (event) => Number(event?.sequenceId) === targetSequenceId,
+          ) ||
+          eventsResult.events[eventsResult.events.length - 1] ||
+          null;
+        if (match) {
+          base.author = pinnedEventAuthorId(match);
+          base.content = pinnedEventContentText(match);
+          base.resolved = true;
+        }
+      }
+      return base;
+    }),
+  );
+
+  return {
+    ok: true,
+    reason: "",
+    sessionId: normalizedSessionId,
+    pins,
+    pinLimit,
+    count: pins.length,
+  };
+}
+
 export async function createSessionMessageAction(
   sessionId,
   {