sentinelayer-cli 0.23.0 → 0.25.0

package/package.json

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

package/src/commands/guide.js

@@ -4,6 +4,13 @@ import path from "node:path";
 
 import pc from "picocolors";
 
+import {
+  createMultiProviderApiClient,
+  resolveApiKey,
+  resolveModel,
+  resolveProvider,
+} from "../ai/client.js";
+import { enrichGuideTickets } from "../guide/enrich.js";
 import {
   defaultGuideExportFileName,
   generateBuildGuide,
@@ -12,6 +19,40 @@ import {
 } from "../guide/generator.js";
 import { renderTerminalMarkdown } from "../ui/markdown.js";
 
+// Optionally split each phase into per-PR tickets with an LLM. Best-effort:
+// any failure leaves the deterministic tickets untouched. Returns the number
+// of phases enriched (0 when disabled or unavailable).
+async function maybeEnrichGuide(guideDoc, options) {
+  if (!options || !options.enrich) return 0;
+  try {
+    const provider = resolveProvider({ provider: options.provider });
+    const model = resolveModel({ provider, model: options.model });
+    const apiKey = resolveApiKey({ provider, explicitApiKey: options.apiKey });
+    if (!apiKey) {
+      console.error(
+        pc.yellow(`! --enrich skipped: no API key for provider '${provider}'. Set the provider key or pass --api-key.`)
+      );
+      return 0;
+    }
+    const limits = {};
+    if (options.maxPhases) limits.maxPhases = Number(options.maxPhases);
+    if (options.maxPrsPerPhase) limits.maxTicketsPerPhase = Number(options.maxPrsPerPhase);
+    const { tickets, enrichedPhases } = await enrichGuideTickets({
+      guide: guideDoc,
+      client: createMultiProviderApiClient(),
+      provider,
+      model,
+      apiKey,
+      limits,
+    });
+    if (enrichedPhases > 0) guideDoc.tickets = tickets;
+    return enrichedPhases;
+  } catch (error) {
+    console.error(pc.yellow(`! --enrich failed, using deterministic tickets: ${error?.message || error}`));
+    return 0;
+  }
+}
+
 function shouldEmitJson(options, command) {
   const local = Boolean(options && options.json);
   const globalFromCommand =
@@ -101,6 +142,12 @@ export function registerGuideCommand(program) {
     .option("--path <path>", "Target workspace path", ".")
     .option("--spec-file <path>", "Spec file path relative to --path")
     .option("--output-file <path>", "Output export file path relative to --path")
+    .option("--enrich", "Split each phase into per-PR tickets with an LLM (opt-in, capped)")
+    .option("--provider <provider>", "LLM provider for --enrich (openai|anthropic|google)")
+    .option("--model <model>", "LLM model for --enrich")
+    .option("--api-key <key>", "Explicit API key for --enrich (else from env)")
+    .option("--max-phases <n>", "Cap how many phases --enrich expands")
+    .option("--max-prs-per-phase <n>", "Cap PRs per phase for --enrich")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
@@ -116,6 +163,7 @@ export function registerGuideCommand(program) {
         projectPath: targetPath,
         specPath,
       });
+      const enrichedPhases = await maybeEnrichGuide(guideDoc, options);
       const exportBody = renderGuideExport({ format, guide: guideDoc });
 
       await fsp.mkdir(path.dirname(outputPath), { recursive: true });
@@ -128,6 +176,7 @@ export function registerGuideCommand(program) {
         specPath,
         outputPath,
         issueCount: guideDoc.tickets.length,
+        enrichedPhases,
       };
 
       if (shouldEmitJson(options, command)) {
@@ -139,6 +188,9 @@ export function registerGuideCommand(program) {
       console.log(pc.gray(`Format: ${format}`));
       console.log(pc.gray(`Output: ${outputPath}`));
       console.log(pc.gray(`Issues: ${guideDoc.tickets.length}`));
+      if (enrichedPhases > 0) {
+        console.log(pc.gray(`LLM-enriched phases: ${enrichedPhases}`));
+      }
     });
 
   guide

package/src/commands/session.js

@@ -61,6 +61,14 @@ import {
   refreshSessionCacheForRemoteActivity,
   updateSessionTitle,
 } from "../session/store.js";
+import { fetchSessionListeners, formatListenerLine } from "../session/listeners.js";
+import {
+  acceptSessionInvitation,
+  normalizeSessionOnboarding,
+  writeSessionOnboardingBrief,
+} from "../session/invitations.js";
+import { postFirstSentiMessage } from "../session/first-message.js";
+import { createListenerHostWake } from "../session/wake/listen-wake.js";
 import { appendToStream, readStream, tailStream } from "../session/stream.js";
 import {
   addSessionEventIdentityKeys,
@@ -121,6 +129,13 @@ function normalizeString(value) {
   return String(value || "").trim();
 }
 
+function optionWasSetByCli(command, optionName) {
+  if (!command || typeof command.getOptionValueSource !== "function") {
+    return false;
+  }
+  return command.getOptionValueSource(optionName) === "cli";
+}
+
 const SESSION_SAY_CONFIRM_ATTEMPTS = 3;
 const SESSION_SAY_CONFIRM_DELAY_MS = 250;
 const SESSION_SAY_CONFIRM_PAGE_LIMIT = 200;
@@ -2236,6 +2251,10 @@ export function registerSessionCommand(program) {
       "--force-new",
       "Always create a new session even if a recent active one exists for this workspace",
     )
+    .option(
+      "--force",
+      "Alias of --force-new (both always mint a fresh session)",
+    )
     .option(
       "--resume",
       "Reuse the most recent active session for this workspace when one is inside the reuse window",
@@ -2279,7 +2298,7 @@ export function registerSessionCommand(program) {
         template,
         title: titleArg,
         resume: options.resume !== false,
-        forceNew: Boolean(options.forceNew),
+        forceNew: Boolean(options.forceNew || options.force),
         reuseWindowSeconds,
       });
       const created = ensured.created;
@@ -2356,6 +2375,21 @@ export function registerSessionCommand(program) {
       }
       payload.sentiDaemon = sentiDaemon;
 
+      // Pin the deterministic first-Senti-message as the opening event of a
+      // NEW room so every joining agent reads the operating protocol
+      // (identity, mandatory commands, reaction/threading/lock/evidence
+      // rules, cadence). Skipped on resume (already posted) and opt-outable
+      // via SENTINELAYER_SKIP_FIRST_MESSAGE=1. Best-effort, never blocks.
+      let firstMessage = { posted: false, reason: "skipped" };
+      const skipFirstMessage = String(process.env.SENTINELAYER_SKIP_FIRST_MESSAGE || "").trim() === "1";
+      if (!resumed && !skipFirstMessage) {
+        firstMessage = await postFirstSentiMessage({
+          sessionId: created.sessionId,
+          targetPath,
+        }).catch((error) => ({ posted: false, reason: normalizeString(error?.message) || "error" }));
+      }
+      payload.firstMessage = firstMessage;
+
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
         return;
@@ -2421,7 +2455,7 @@ export function registerSessionCommand(program) {
       if (!resumed) {
         console.log(
           pc.gray(
-            options.forceNew
+            (options.forceNew || options.force)
               ? `Tip: fresh session minted (--force-new honored). Subsequent \`${cliCommand} session start\` here within an hour will resume this new session.`
               : `Tip: subsequent \`${cliCommand} session start\` in this workspace within an hour will resume this session. Pass --force-new to override.`,
           ),
@@ -2697,6 +2731,9 @@ export function registerSessionCommand(program) {
       "--agent <id>",
       "Granted agent id to emit an agent_join event as. Behaves like post-agent for human/placeholder ids — those are recorded in the local registry only.",
     )
+    .option("--invite-token <token>", "Invitation token to accept before joining the session")
+    .option("--seat-key <key>", "Reserved session seat key to claim while accepting an invite")
+    .option("--idempotency-key <key>", "Explicit idempotency key for invite acceptance")
     .option("--role <role>", "Agent role: coder, reviewer, tester, observer", "coder")
     .option("--model <model>", "Agent model hint", "cli")
     .option("--path <path>", "Workspace path for the session", ".")
@@ -2707,12 +2744,35 @@ export function registerSessionCommand(program) {
         throw new Error("session id is required.");
       }
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const explicitAgent = normalizeString(options.agent);
+      const legacyName = normalizeString(options.name);
+      const inviteToken = normalizeString(options.inviteToken);
+      let invitationAccept = null;
+      let invitationAcceptResult = null;
+      if (inviteToken) {
+        invitationAccept = await acceptSessionInvitation(normalizedSessionId, {
+          targetPath,
+          invitationToken: inviteToken,
+          seatKey: options.seatKey,
+          agentId: explicitAgent || legacyName,
+          idempotencyKey: options.idempotencyKey,
+        });
+        invitationAcceptResult =
+          invitationAccept?.result && typeof invitationAccept.result === "object"
+            ? invitationAccept.result
+            : null;
+      }
 
       // PR #483 contract: verify the session exists and the caller has access
       // BEFORE materializing local cache state. Without this we'd silently
       // create a phantom local NDJSON for a session that's archived or owned
       // by another tenant — which is the bug Carter reported when asking for
       // a clean "share an id from web → join in CLI" flow.
+      //
+      // Invitation acceptance is the only exception to the old ordering:
+      // before the invite is accepted the user may legitimately receive 403,
+      // so --invite-token performs the guarded accept mutation first and this
+      // verification proves membership immediately afterward.
       const verification = await verifyRemoteSession(normalizedSessionId, { targetPath });
       if (!verification.ok) {
         if (verification.status === 404 || verification.reason === "not_found") {
@@ -2744,17 +2804,26 @@ export function registerSessionCommand(program) {
         targetPath,
       });
 
-      const explicitAgent = normalizeString(options.agent);
-      const agentSeed = explicitAgent || normalizeString(options.name);
+      const acceptedOnboarding = normalizeSessionOnboarding(
+        invitationAcceptResult?.onboarding,
+        invitationAcceptResult?.claimedSeat,
+      );
+      const acceptedAgentId = normalizeString(acceptedOnboarding?.agentId);
+      const agentSeed = explicitAgent || acceptedAgentId || legacyName;
       const resolvedAgentId = await defaultAgentId(agentSeed, targetPath);
-      const role = normalizeString(options.role) || "coder";
+      const roleWasExplicit = optionWasSetByCli(command, "role");
+      const role =
+        normalizeString(roleWasExplicit ? options.role : acceptedOnboarding?.role || options.role) ||
+        "coder";
       const model = normalizeString(options.model) || "cli";
+      const hasConcreteAgentIdentity = Boolean(explicitAgent || acceptedAgentId);
 
       // `registerAgent` already writes the canonical `agent_join` event to the
       // local NDJSON and best-effort relays it to /events via appendToStream
       // → syncSessionEventToApi. That gives us the exact `post-agent` parity
-      // the spec calls for when `--agent <granted>` is provided. We don't
-      // double-emit; we just record whether the explicit agent path was used
+      // the spec calls for when `--agent <granted>` or an accepted reserved
+      // seat provides a concrete agent id. We don't double-emit; we record
+      // whether a durable agent identity path was used
       // so the JSON output can advertise it to callers (and tests).
       const joined = await registerAgent(normalizedSessionId, {
         targetPath,
@@ -2762,15 +2831,21 @@ export function registerSessionCommand(program) {
         model,
         role,
         trackProcessExit: false,
-        awaitRemoteSync: Boolean(explicitAgent),
+        awaitRemoteSync: hasConcreteAgentIdentity,
       });
       const agentJoinRelayed =
         joined.emittedJoinEvent !== false &&
-        Boolean(explicitAgent) &&
+        hasConcreteAgentIdentity &&
         Boolean(resolvedAgentId) &&
         resolvedAgentId !== "cli-user" &&
         resolvedAgentId !== "unknown" &&
         !resolvedAgentId.startsWith("human-");
+      const onboardingBrief = await writeSessionOnboardingBrief(normalizedSessionId, {
+        targetPath,
+        onboarding: acceptedOnboarding,
+        claimedSeat: invitationAcceptResult?.claimedSeat || null,
+        agentId: joined.agentId,
+      });
 
       const eventCount = Number(remoteSession.eventCount ?? remoteSession.events ?? 0);
       const agents = Array.isArray(remoteSession.agents) ? remoteSession.agents : [];
@@ -2802,6 +2877,21 @@ export function registerSessionCommand(program) {
         agentCount: Number.isFinite(agentCount) ? agentCount : 0,
         lastActivityAt: lastActivityIso || null,
         agentJoinRelayed,
+        invitationAccepted: Boolean(invitationAcceptResult?.ok || invitationAccept),
+        invitationAccept: invitationAccept
+          ? {
+              idempotencyKey: invitationAccept.idempotencyKey,
+              claimedSeat: invitationAcceptResult?.claimedSeat || null,
+              onboarding: acceptedOnboarding,
+              capacity: invitationAcceptResult?.capacity || null,
+            }
+          : null,
+        onboardingGuide: onboardingBrief
+          ? {
+              markdownPath: onboardingBrief.markdownPath,
+              jsonPath: onboardingBrief.jsonPath,
+            }
+          : null,
       };
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
@@ -2814,7 +2904,17 @@ export function registerSessionCommand(program) {
           `Joined session ${titleLabel} (${normalizedSessionId}) — ${payload.eventCount} events, ${payload.agentCount} agents, last activity ${ageLabel}`,
         ),
       );
+      if (payload.invitationAccepted) {
+        const seat = payload.invitationAccept?.claimedSeat || {};
+        const seatLabel = normalizeString(seat.seatKey)
+          ? `; claimed ${normalizeString(seat.seatType) || "reserved"} seat ${seat.seatKey}`
+          : "";
+        console.log(pc.green(`Invitation accepted${seatLabel}`));
+      }
       console.log(pc.gray(`agent=${joined.agentId} role=${joined.role} model=${joined.model}`));
+      if (payload.onboardingGuide?.markdownPath) {
+        console.log(pc.gray(`onboarding=${payload.onboardingGuide.markdownPath}`));
+      }
     });
 
   session
@@ -3473,6 +3573,108 @@ export function registerSessionCommand(program) {
       return payload;
     });
 
+  session
+    .command("listeners <sessionId>")
+    .description(
+      "List who is actively listening to the session and at what poll cadence (active/idle/stale/stopped), derived from listener presence heartbeats. Mirrors the web roster.",
+    )
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--limit <n>", "Recent events to scan for heartbeats (default 200)", "200")
+    .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 limit = parsePositiveInteger(options.limit, "limit", 200);
+      const result = await fetchSessionListeners(normalizedSessionId, { targetPath, limit });
+      const listeners = Array.isArray(result.listeners) ? result.listeners : [];
+      const live = listeners.filter((row) => row.status === "active" || row.status === "idle").length;
+      const payload = {
+        command: "session listeners",
+        sessionId: normalizedSessionId,
+        ok: Boolean(result.ok),
+        reason: result.ok ? undefined : result.reason,
+        count: listeners.length,
+        liveCount: live,
+        listeners,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return payload;
+      }
+      if (!result.ok) {
+        console.log(pc.yellow(`Could not read listeners (${result.reason}).`));
+        return payload;
+      }
+      if (listeners.length === 0) {
+        console.log(pc.gray("No listeners detected (no recent presence heartbeats)."));
+        return payload;
+      }
+      console.log(pc.bold(`Listeners (${live} live / ${listeners.length} seen)`));
+      for (const row of listeners) {
+        const line = formatListenerLine(row);
+        if (row.status === "active") console.log(pc.green(`  ${line}`));
+        else if (row.status === "idle") console.log(pc.cyan(`  ${line}`));
+        else console.log(pc.gray(`  ${line}`));
+      }
+      return payload;
+    });
+
+  session
+    .command("stop-listener <sessionId>")
+    .description(
+      "Ask an agent's listener to stop (save energy). Posts a listener_stop directive the listener honors on its next poll, then exits cleanly. Targets one agent with --agent; omit it to stop every listener in the room.",
+    )
+    .option("--agent <id>", "Agent whose listener to stop (omit to stop all listeners in the room)")
+    .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 || "."));
+      const targetAgent = normalizeString(options.agent);
+      await ensureLocalSessionForRemoteCommand(normalizedSessionId, { targetPath });
+      const event = createAgentEvent({
+        event: "listener_stop",
+        agent: { id: "session-control", model: "control", persona: "Session Control" },
+        sessionId: normalizedSessionId,
+        payload: {
+          // targetAgentId routes the directive to that agent's listener (an
+          // event recipient); omitting it broadcasts to every listener.
+          ...(targetAgent ? { targetAgentId: targetAgent } : { broadcast: true }),
+          reason: "operator_stop",
+        },
+      });
+      const remoteSync = await syncSessionEventToApi(normalizedSessionId, event, { targetPath }).catch(
+        (error) => ({ synced: false, reason: normalizeString(error?.message) || "sync_failed" }),
+      );
+      await appendToStream(normalizedSessionId, event, { targetPath, syncRemote: false }).catch(() => {});
+      const payload = {
+        command: "session stop-listener",
+        sessionId: normalizedSessionId,
+        targetAgent: targetAgent || null,
+        scope: targetAgent ? "agent" : "all",
+        remoteSync: remoteSync || undefined,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return payload;
+      }
+      console.log(
+        pc.yellow(
+          targetAgent
+            ? `Listener stop requested for ${targetAgent}; it will exit on its next poll.`
+            : "Listener stop requested for ALL listeners in this room.",
+        ),
+      );
+      return payload;
+    });
+
   session
     .command("listen")
     .description("Background-poll a session for events addressed to this agent or broadcast")
@@ -3520,6 +3722,14 @@ 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(
+      "--wake-host <name>",
+      "Auto-wake: resume this host (claude|codex) on each addressed message so listening IS waking. Requires --resume-session.",
+    )
+    .option(
+      "--resume-session <id>",
+      "Host session/rollout id to resume on wake (the claude/codex session id, not the Senti id). Pairs with --wake-host.",
+    )
     .option(
       "--coaching-interval <seconds>",
       "Seconds between in-session success reminders (ack, claim work, reply in-thread). Default 900; 0 disables.",
@@ -3575,6 +3785,25 @@ export function registerSessionCommand(program) {
         agentId,
         emit: emitWakeNotice,
       });
+      // Auto-wake cutover: when --wake-host + --resume-session are given, an
+      // addressed message INSTANTLY resumes the host (claude --resume / codex)
+      // via the built wake bus — turning `listen` into a true waker on the
+      // same poll. resolve-target routing inside ensures real-message-only,
+      // addressed-to-us, never-self.
+      const wakeHost = normalizeString(options.wakeHost);
+      const triggerHostWake = wakeHost
+        ? createListenerHostWake({
+            host: wakeHost,
+            resumeSessionId: options.resumeSession,
+            agentId,
+            sessionId: normalizedSessionId,
+          })
+        : null;
+      if (wakeHost && !triggerHostWake) {
+        throw new Error(
+          "--wake-host requires a valid host (claude|codex) and --resume-session <host-session-id>.",
+        );
+      }
       const requestedTransport = normalizeString(options.transport).toLowerCase() || "auto";
       if (!["auto", "stream", "poll"].includes(requestedTransport)) {
         throw new Error("--transport must be one of: auto, stream, poll.");
@@ -3696,6 +3925,20 @@ export function registerSessionCommand(program) {
             }
           },
           onEvent: async (event) => {
+            // Cut-listener: a `listener_stop` directive addressed to this
+            // agent (from the web "stop listening" control or
+            // `sl session stop-listener`) cleanly exits this listener to save
+            // energy. Untargeted (no targetAgentId) stops every listener.
+            if (normalizeString(event?.event) === "listener_stop") {
+              const target = normalizeString(event?.payload?.targetAgentId);
+              if (!target || target === agentId) {
+                if (emitFormat !== "ndjson") {
+                  console.log(pc.yellow(`Listener stop requested for ${agentId}; exiting.`));
+                }
+                ac.abort();
+                return;
+              }
+            }
             if (emitFormat === "ndjson") {
               console.log(JSON.stringify(event));
             } else {
@@ -3704,6 +3947,16 @@ export function registerSessionCommand(program) {
             // Fire the wake hook for any matched event (incl. ack/like) so the
             // host can resume its agent.
             wakeRunner.trigger(event);
+            // Auto-wake: instantly resume the host on an addressed message.
+            if (triggerHostWake) {
+              void Promise.resolve(triggerHostWake.trigger(event)).then((outcome) => {
+                if (outcome?.woken && emitFormat !== "ndjson") {
+                  console.log(pc.green(`auto-wake: resumed ${wakeHost} (${agentId})`));
+                } else if (outcome && !outcome.woken && outcome.reason !== "not_routed" && emitFormat !== "ndjson") {
+                  console.log(pc.yellow(`auto-wake: ${wakeHost} resume failed (${outcome.reason})`));
+                }
+              });
+            }
           },
           onError: async (result) => {
             const reason = normalizeString(result?.reason) || "poll_failed";
@@ -3726,6 +3979,29 @@ export function registerSessionCommand(program) {
             }
           },
           onLifecycle: async (lifecycle) => {
+            // Wake-confirmation runs on every heartbeat regardless of presence:
+            // re-resume agents that were woken but never acked within the
+            // window; confirm + retire the ones that did. (Carter's receipt
+            // idea — a wake isn't done until the agent actually reads it.)
+            if (triggerHostWake && normalizeString(lifecycle?.type) === "heartbeat") {
+              const outcome = await triggerHostWake
+                .reconcile({
+                  nowMs: Date.now(),
+                  fetchActions: (seq) =>
+                    listSessionMessageActions(normalizedSessionId, {
+                      targetPath,
+                      targetSequenceId: seq,
+                    }),
+                })
+                .catch(() => null);
+              if (outcome && (outcome.retried > 0 || outcome.deadLettered > 0) && emitFormat !== "ndjson") {
+                console.log(
+                  pc.yellow(
+                    `auto-wake reconcile: re-resumed ${outcome.retried}, gave up on ${outcome.deadLettered} (no ack).`,
+                  ),
+                );
+              }
+            }
             if (!publishPresence) return;
             const lifecycleType = normalizeString(lifecycle?.type);
             if (lifecycleType === "heartbeat") {

package/src/coord/events-log.js

@@ -19,7 +19,7 @@ import {
   resolveSentinelDir,
 } from "./paths.js";
 
-const EVENTS_LOCK_TIMEOUT_MS = 5000;
+const EVENTS_LOCK_TIMEOUT_MS = 15_000;
 const EVENTS_LOCK_STALE_MS = 30_000;
 const EVENTS_LOCK_POLL_MS = 25;