sentinelayer-cli 0.24.0 → 0.25.0

package/package.json

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

@@ -62,6 +62,11 @@ import {
   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";
@@ -124,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;
@@ -2719,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", ".")
@@ -2729,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") {
@@ -2766,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,
@@ -2784,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 : [];
@@ -2824,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));
@@ -2836,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

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;
 

package/src/legacy-cli.js

@@ -2294,6 +2294,9 @@ ${renderCoordinationNumberedList()}
 - Finding: \`sl session say <id> "finding: [P2] missing rate limit on POST /api/auth/login"\`
 - Help: \`sl session say <id> "help: unexpected change in package.json - who modified it?"\`
 - Done: \`sl session say <id> "done: PR merged, auth hardening complete"\`
+
+## Reserved Seat Onboarding
+- If \`sl session join\` returns \`onboardingGuide.markdownPath\`, read that file before posting; it contains your reserved-seat SOUL instructions, role, and first actions.
 `;
 }
 

package/src/session/invitations.js

@@ -0,0 +1,241 @@
+import { createHmac, randomUUID } from "node:crypto";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import { requestJsonMutation } from "../auth/http.js";
+import { resolveActiveAuthSession } from "../auth/service.js";
+import { renderCoordinationBulletList } from "./coordination-guidance.js";
+import { resolveSessionPaths } from "./paths.js";
+
+export const SESSION_INVITATION_ACCEPT_ROUTE_ID =
+  "POST /api/v1/sessions/{session_id}/invitations/accept";
+export const SESSION_MUTATION_ORIGIN = "https://sentinelayer.com";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function safeFileToken(value, fallback = "onboarding") {
+  const normalized = normalizeString(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return (normalized || fallback).slice(0, 80);
+}
+
+export function canonicalSessionRef(value) {
+  const raw = normalizeString(value);
+  if (!raw) return "unavailable";
+  return raw.toLowerCase();
+}
+
+export function createSessionMutationCsrfToken({
+  bearerToken,
+  sessionId,
+  routeId,
+  idempotencyKey,
+} = {}) {
+  const secret = normalizeString(bearerToken);
+  if (!secret) return "";
+  const message = [
+    "session-mutation-csrf:v1",
+    canonicalSessionRef(sessionId),
+    normalizeString(routeId),
+    normalizeString(idempotencyKey),
+  ].join("\0");
+  return createHmac("sha256", secret).update(message, "utf-8").digest("hex");
+}
+
+export function createSessionMutationHeaders({
+  bearerToken,
+  sessionId,
+  routeId,
+  idempotencyKey,
+  origin = SESSION_MUTATION_ORIGIN,
+} = {}) {
+  const token = normalizeString(bearerToken);
+  const normalizedOrigin = normalizeString(origin) || SESSION_MUTATION_ORIGIN;
+  return {
+    Authorization: `Bearer ${token}`,
+    Origin: normalizedOrigin,
+    "Sec-Fetch-Site": "same-site",
+    "X-Sentinelayer-Session-Mutation": "session-mutation",
+    "X-CSRF-Token": createSessionMutationCsrfToken({
+      bearerToken: token,
+      sessionId,
+      routeId,
+      idempotencyKey,
+    }),
+  };
+}
+
+export function createSessionMutationIdempotencyKey(operationName = "invitation-accept") {
+  const operation = normalizeString(operationName)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32) || "session-mutation";
+  return `sl-cli-${operation}-${randomUUID()}`;
+}
+
+export async function acceptSessionInvitation(
+  sessionId,
+  {
+    invitationToken,
+    seatKey = "",
+    agentId = "",
+    targetPath = process.cwd(),
+    idempotencyKey = "",
+    origin = SESSION_MUTATION_ORIGIN,
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = {},
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedInvitationToken = normalizeString(invitationToken);
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+  if (!normalizedInvitationToken) {
+    throw new Error("invite token is required.");
+  }
+
+  const auth = await resolveAuthSession({
+    cwd: targetPath,
+    env: process.env,
+    autoRotate: false,
+  });
+  if (!auth?.token || !auth?.apiUrl) {
+    throw new Error("Not authenticated. Run `sl auth login` first.");
+  }
+
+  const resolvedIdempotencyKey =
+    normalizeString(idempotencyKey) || createSessionMutationIdempotencyKey("session-invite-accept");
+  const apiUrl = normalizeString(auth.apiUrl).replace(/\/+$/, "");
+  const body = {
+    token: normalizedInvitationToken,
+  };
+  const normalizedSeatKey = normalizeString(seatKey);
+  const normalizedAgentId = normalizeString(agentId);
+  if (normalizedSeatKey) body.seatKey = normalizedSeatKey;
+  if (normalizedAgentId) body.agentId = normalizedAgentId;
+
+  const result = await requestMutation(
+    `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/invitations/accept`,
+    {
+      method: "POST",
+      operationName: "session.invitation_accept",
+      idempotencyKey: resolvedIdempotencyKey,
+      headers: createSessionMutationHeaders({
+        bearerToken: auth.token,
+        sessionId: normalizedSessionId,
+        routeId: SESSION_INVITATION_ACCEPT_ROUTE_ID,
+        idempotencyKey: resolvedIdempotencyKey,
+        origin,
+      }),
+      body,
+    },
+  );
+
+  return {
+    idempotencyKey: resolvedIdempotencyKey,
+    result,
+  };
+}
+
+export function normalizeSessionOnboarding(onboarding = {}, claimedSeat = null) {
+  const onboardingSource =
+    onboarding && typeof onboarding === "object" && !Array.isArray(onboarding) ? onboarding : {};
+  const seatSource =
+    claimedSeat && typeof claimedSeat === "object" && !Array.isArray(claimedSeat) ? claimedSeat : {};
+  const normalized = {
+    seatKey: normalizeString(onboardingSource.seatKey) || normalizeString(seatSource.seatKey) || null,
+    agentId:
+      normalizeString(onboardingSource.agentId) ||
+      normalizeString(seatSource.claimedAgentId) ||
+      normalizeString(seatSource.agentId) ||
+      null,
+    displayName:
+      normalizeString(onboardingSource.displayName) || normalizeString(seatSource.displayName) || null,
+    role: normalizeString(onboardingSource.role) || normalizeString(seatSource.role) || null,
+    instructions:
+      normalizeString(onboardingSource.instructions) || normalizeString(seatSource.instructions) || null,
+  };
+  return Object.values(normalized).some(Boolean) ? normalized : null;
+}
+
+function renderOnboardingMarkdown({ sessionId, onboarding, claimedSeat, agentId }) {
+  const lines = [
+    "# Senti Session Onboarding",
+    "",
+    `Session: ${sessionId}`,
+    `Agent: ${normalizeString(onboarding.agentId) || normalizeString(agentId) || "unknown"}`,
+  ];
+  if (onboarding.displayName) lines.push(`Display name: ${onboarding.displayName}`);
+  if (onboarding.role) lines.push(`Role: ${onboarding.role}`);
+  if (onboarding.seatKey) lines.push(`Seat key: ${onboarding.seatKey}`);
+  if (claimedSeat?.seatType) lines.push(`Seat type: ${normalizeString(claimedSeat.seatType)}`);
+  lines.push("", "## SOUL Instructions", "");
+  lines.push(onboarding.instructions || "No seat-specific instructions were provided.");
+  lines.push("", "## Session Etiquette", "", renderCoordinationBulletList());
+  lines.push(
+    "",
+    "## First Actions",
+    "",
+    `- Read recent room context: \`sl session read ${sessionId} --remote --tail 50 --json\``,
+    `- Start a quiet listener: \`sl session listen --session ${sessionId} --agent <your-name> --interval 60 --active-interval 5 --emit ndjson --no-presence\``,
+    `- Post a short plan before editing: \`sl session say ${sessionId} \"plan: <scope>; files: <paths>\"\``,
+    "- Review `AGENTS.md` / `CLAUDE.md`, then keep `tasks/todo.md` current for work status.",
+    "- Add any Carter correction pattern to `tasks/lessons.md` before continuing the next slice.",
+  );
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeSessionOnboardingBrief(
+  sessionId,
+  {
+    onboarding,
+    claimedSeat = null,
+    agentId = "",
+    targetPath = process.cwd(),
+  } = {},
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedOnboarding = normalizeSessionOnboarding(onboarding, claimedSeat);
+  if (!normalizedSessionId || !normalizedOnboarding) {
+    return null;
+  }
+  const paths = resolveSessionPaths(normalizedSessionId, { targetPath });
+  const owner = safeFileToken(normalizedOnboarding.agentId || agentId || normalizedOnboarding.seatKey);
+  const dir = path.join(paths.sentiDir, "onboarding");
+  const jsonPath = path.join(dir, `${owner}.json`);
+  const markdownPath = path.join(dir, `${owner}.md`);
+  const payload = {
+    schemaVersion: "1.0.0",
+    sessionId: normalizedSessionId,
+    agentId: normalizeString(agentId) || normalizedOnboarding.agentId || null,
+    onboarding: normalizedOnboarding,
+    claimedSeat: claimedSeat && typeof claimedSeat === "object" ? claimedSeat : null,
+    writtenAt: new Date().toISOString(),
+  };
+  await fsp.mkdir(dir, { recursive: true });
+  await Promise.all([
+    fsp.writeFile(jsonPath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8"),
+    fsp.writeFile(
+      markdownPath,
+      renderOnboardingMarkdown({
+        sessionId: normalizedSessionId,
+        onboarding: normalizedOnboarding,
+        claimedSeat,
+        agentId,
+      }),
+      "utf-8",
+    ),
+  ]);
+  return {
+    jsonPath,
+    markdownPath,
+    onboarding: normalizedOnboarding,
+  };
+}

package/src/session/stream.js

@@ -15,6 +15,10 @@ const DEFAULT_LOCK_POLL_MS = 25;
 const DEFAULT_MAX_STREAM_EVENTS = 10_000;
 const DEFAULT_REMOTE_REFRESH_TTL_SECONDS = 24 * 60 * 60;
 const REMOTE_REFRESH_TIMEOUT_MS = 2_500;
+const METADATA_WRITE_RETRY_ATTEMPTS = 5;
+const METADATA_WRITE_RETRY_DELAY_MS = 50;
+
+let metadataWriteCounter = 0;
 
 function normalizeString(value) {
   return String(value || "").trim();
@@ -68,11 +72,36 @@ async function readSessionMetadata(paths) {
   }
 }
 
+function isRetryableMetadataWriteError(error) {
+  const code = error && typeof error === "object" ? error.code : "";
+  return code === "EPERM" || code === "EACCES" || code === "EBUSY";
+}
+
+async function replaceMetadataFile(tmpPath, metadataPath) {
+  for (let attempt = 1; attempt <= METADATA_WRITE_RETRY_ATTEMPTS; attempt += 1) {
+    try {
+      await fsp.rename(tmpPath, metadataPath);
+      return;
+    } catch (error) {
+      if (!isRetryableMetadataWriteError(error) || attempt >= METADATA_WRITE_RETRY_ATTEMPTS) {
+        throw error;
+      }
+      await sleep(METADATA_WRITE_RETRY_DELAY_MS * attempt);
+    }
+  }
+}
+
 async function writeSessionMetadata(paths, metadata = {}) {
   await fsp.mkdir(paths.sessionDir, { recursive: true });
-  const tmpPath = `${paths.metadataPath}.${process.pid}.${Date.now()}.tmp`;
+  metadataWriteCounter = (metadataWriteCounter + 1) % Number.MAX_SAFE_INTEGER;
+  const tmpPath = `${paths.metadataPath}.${process.pid}.${Date.now()}.${metadataWriteCounter}.tmp`;
   await fsp.writeFile(tmpPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf-8");
-  await fsp.rename(tmpPath, paths.metadataPath);
+  try {
+    await replaceMetadataFile(tmpPath, paths.metadataPath);
+  } catch (error) {
+    await fsp.rm(tmpPath, { force: true }).catch(() => {});
+    throw error;
+  }
 }
 
 function remoteStatusAllowsLocalRefresh(remoteSession = {}) {