sentinelayer-cli 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.21.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

@@ -77,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";
@@ -1405,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,
@@ -1708,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(
@@ -3225,6 +3296,121 @@ export function registerSessionCommand(program) {
       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")
@@ -3272,6 +3458,12 @@ export function registerSessionCommand(program) {
       "--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 || "."));
@@ -3345,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(
@@ -3455,6 +3685,9 @@ export function registerSessionCommand(program) {
           },
         });
       } finally {
+        if (coachingTimer) {
+          clearInterval(coachingTimer);
+        }
         process.removeListener("SIGINT", onSigint);
       }
     });

package/src/legacy-cli.js

@@ -227,6 +227,9 @@ function printUsage() {
   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");

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 = "",