sentinelayer-cli 0.46.4 → 0.48.0

package/src/commands/session.js

@@ -6,6 +6,8 @@ import { createHash, randomUUID } from "node:crypto";
 import { spawn as defaultSpawn } from "node:child_process";
 
 import pc from "picocolors";
+import { appendAttachmentSummary, withAttachmentSummary } from "../session/attachment-summary.js";
+import { formatEditSummary, withEditSummary } from "../session/edit-summary.js";
 
 import { credentialFor, isAuthenticated } from "../auth/credential-destinations.js";
 import { SentinelayerApiError, requestJsonMutation } from "../auth/http.js";
@@ -18,7 +20,7 @@ import {
 import { recordProvisionedIdentity } from "../ai/identity-store.js";
 import { fetchAidenIdCredentials } from "../auth/service.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
-import { resolveOutputRoot } from "../config/service.js";
+import { resolveOutputContext } from "../config/service.js";
 import {
   listAssignments,
   releaseLease,
@@ -33,6 +35,7 @@ import {
   unregisterAgent,
 } from "../session/agent-registry.js";
 import { inferSessionAgentIdentity } from "../session/agent-identity.js";
+import { legacyJoinAdmissionRefusal, verifyLegacyAgentJoin } from "../session/agent-access.js";
 import { startSenti, stopSenti } from "../session/daemon.js";
 import {
   getDaemonStatus,
@@ -61,6 +64,7 @@ import {
   setupSessionGuides,
 } from "../session/setup-guides.js";
 import { listSessionTasks } from "../session/tasks.js";
+import { formatSessionStandup, sessionStandup } from "../session/standup.js";
 import {
   createSession,
   DEFAULT_TTL_SECONDS,
@@ -88,6 +92,8 @@ import {
 } from "../session/control-events.js";
 import {
   acceptSessionInvitation,
+  acceptPendingSessionInvitation,
+  listPendingSessionInvitations,
   normalizeSessionOnboarding,
   writeSessionOnboardingBrief,
 } from "../session/invitations.js";
@@ -118,6 +124,7 @@ import {
 } from "../session/reactions.js";
 import {
   claimTicket,
+  createTicket,
   listTickets,
   releaseTicketLease,
   renewTicketLease,
@@ -139,6 +146,7 @@ import {
   createSessionMessageAction,
   editSessionMessage,
   fetchJsonWithFullTimeout,
+  fetchSessionPresence,
   fetchSessionUsageLedger,
   fetchSessionPinnedMessages,
   listSessionMessageActions,
@@ -155,7 +163,15 @@ import {
   updateSessionReadCursor,
 } from "../session/sync.js";
 import { hydrateSessionFromRemote } from "../session/remote-hydrate.js";
-import { messageRevision, replyRevisionEvent, sessionMessageRoutingEvent } from "../session/message-edits.js";
+import {
+  DEFAULT_ROOM_FILES_LIMIT,
+  DEFAULT_ROOM_FILES_MAX_PAGES,
+  MAX_ROOM_FILES_LIMIT,
+  RoomFileError,
+  downloadRoomFile,
+  listRoomFiles,
+} from "../session/room-files.js";
+import { messageRevision, replyRevisionEvent } from "../session/message-edits.js";
 import { runSessionRecall } from "../session/recall/index.js";
 import { mergeLiveSources } from "../session/live-source.js";
 import { listenSessionEvents } from "../session/listener.js";
@@ -853,7 +869,7 @@ function formatHumanAskLine(event = {}) {
   const message = humanAskMessage(event);
   const shortMessage = message.length > 220 ? `${message.slice(0, 217)}...` : message;
   const suffix = shortMessage ? `: ${shortMessage}` : "";
-  return `${sequenceLabel} ${humanAskAgentId(event)}${ts ? ` ${ts}` : ""}${suffix}`;
+  return appendAttachmentSummary(`${sequenceLabel} ${humanAskAgentId(event)}${ts ? ` ${ts}` : ""}${suffix}`, event);
 }
 
 function formatRemoteHydrateAppendWarning(result = {}) {
@@ -1459,6 +1475,7 @@ async function fetchRemoteSessionDetail(endpoint, credential) {
       endpoint, { method: "GET", credential, redirect: "error" }, 2_000,
     ));
   } catch (err) {
+    if (err?.code === "INVITATION_PENDING") throw err;
     return {
       ok: false,
       response: null,
@@ -1985,6 +2002,7 @@ async function publishListenerPresenceEvent({
   clientKind = "cli",
   listenerId,
   lifecycle = {},
+  minimalPresence = false,
 } = {}) {
   const normalizedType = normalizeString(lifecycle.type) || "heartbeat";
   const identity = inferSessionAgentIdentity({
@@ -1997,6 +2015,7 @@ async function publishListenerPresenceEvent({
   return renewSessionPresence(sessionId, {
     targetPath,
     agentId,
+    minimalPresence,
     state:
       normalizedType === "stopped"
         ? "stopped"
@@ -2439,14 +2458,29 @@ function resolveSessionIdOption(options = {}) {
   return sessionId;
 }
 
+function formatFileSize(bytes) {
+  const value = Number(bytes) || 0;
+  if (value < 1024) return `${value} B`;
+  const units = ["KB", "MB", "GB"];
+  let size = value / 1024;
+  let unit = 0;
+  while (size >= 1024 && unit < units.length - 1) {
+    size /= 1024;
+    unit += 1;
+  }
+  return `${size.toFixed(size < 10 ? 1 : 0)} ${units[unit]}`;
+}
+
 function formatEventLine(event = {}) {
+  return appendAttachmentSummary(formatEventText(event), event);
+}
+
+function formatEventText(event = {}) {
   const ts = normalizeString(event.ts || event.timestamp);
   const type = normalizeString(event.event || event.type) || "event";
   const agentId = normalizeString(event.agent?.id || event.agentId || "unknown");
   if (type === "session_message_edited") {
-    const routed = sessionMessageRoutingEvent(event);
-    const target = event.payload?.targetActionId ? `reply ${event.payload.targetActionId}` : `#${event.payload?.targetSequenceId || "?"}`;
-    return `${ts} ${agentId} ${type} ${target} revision ${event.payload?.messageRevision || "?"}: ${normalizeString(routed.payload?.message || routed.payload?.text || "")}`;
+    return `${ts} ${agentId} ${formatEditSummary(event)}`;
   }
   const payload = event.payload && typeof event.payload === "object" ? event.payload : {};
   if (type === "session_action" || type === "session_reply" || type === "session_reaction") {
@@ -2903,11 +2937,69 @@ async function sessionListenAgent(options) {
   return { sessionId: resolveSessionIdOption(options), agentId: normalizeAgentId(options.agent, "cli-user") };
 }
 
+
+/**
+ * Build the admission-join options object from parsed Commander options.
+ * Extracted so tests can assert the full derivation from CLI flag to
+ * runAdmissionJoin input without network I/O.
+ */
+export function buildAdmissionJoinOptions(options, overrides = {}) {
+  const waitSeconds = Number.parseInt(String(options.waitSeconds ?? "900"), 10);
+  return {
+    agentId: overrides.agentId ?? "",
+    displayName: overrides.displayName ?? "",
+    model: options.model,
+    provider: options.provider,
+    goal: options.goal,
+    deliverables: options.deliverable || [],
+    stopConditions: options.stopWhen || [],
+    actions: parseAdmissionScope(options.scope),
+    ttlSeconds: parseAdmissionTtlSeconds(options.ttl),
+    wait: options.wait !== false,
+    recoverActive: Boolean(options.recoverAdmission),
+    noAutoGrant: options.autoGrant === false,
+    waitTimeoutMs: (Number.isFinite(waitSeconds) && waitSeconds >= 0 ? waitSeconds : 900) * 1000,
+    targetPath: overrides.targetPath ?? process.cwd(),
+    onPending: overrides.onPending ?? (() => {}),
+  };
+}
+
 export function registerSessionCommand(program) {
   const session = program
     .command("session")
     .description("Multi-agent ephemeral coordination sessions");
 
+  const invitations = session.command("invitations").description("List and accept pending room invitations");
+  invitations
+    .command("list")
+    .description("List your pending room invitations")
+    .option("--path <path>", "Workspace path for authentication", ".")
+    .option("--json", "Emit the raw API response")
+    .action(async (options, command) => {
+      const result = await listPendingSessionInvitations({ targetPath: path.resolve(options.path) });
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      const entries = Array.isArray(result) ? result : result?.invitations;
+      if (!Array.isArray(entries) || entries.some((entry) => !normalizeString(entry?.invitationId))) {
+        console.log("Pending invitations retrieved. Use `sl session invitations list --json` to inspect the response.");
+        return;
+      }
+      if (entries.length === 0) console.log("No pending invitations.");
+      for (const entry of entries) console.log(`Invitation: ${entry.invitationId}`);
+    });
+  invitations
+    .command("accept <invitationId>")
+    .description("Accept a pending invitation using its invitationId from invitations list")
+    .option("--path <path>", "Workspace path for authentication", ".")
+    .option("--json", "Emit the raw API response")
+    .action(async (invitationId, options, command) => {
+      const result = await acceptPendingSessionInvitation(invitationId, { targetPath: path.resolve(options.path) });
+      if (shouldEmitJson(options, command)) console.log(JSON.stringify(result, null, 2));
+      else console.log("Invitation accepted.");
+    });
+
   session
     .command("start")
     .description(
@@ -3437,6 +3529,8 @@ export function registerSessionCommand(program) {
     .option("--no-wait", "Request admission and return immediately with the approval URL")
     .option("--wait-seconds <n>", "How long to wait for approval before returning pending", "900")
     .option("--cancel-admission", "Cancel this workspace's pending admission request for the session")
+    .option("--recover-admission", "Recover a live admission with the retained agent key; requires the unchanged --goal/scope/ttl")
+    .option("--no-auto-grant", "Skip auto-grant on 403 IDENTITY_FORGERY; fail immediately instead")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, options, command) => {
       const normalizedSessionId = normalizeString(sessionId);
@@ -3455,6 +3549,27 @@ export function registerSessionCommand(program) {
       // the local registration and every later implicit command name the same agent.
       if (!explicitAgent) assertCanonicalAgentId(legacyName, "--name");
       const requestedAgent = canonicalAgentId(explicitAgent || legacyName);
+      if (options.recoverAdmission && !normalizeString(options.goal)) {
+        throw new Error("--recover-admission requires --goal and the admission's unchanged scope/ttl.");
+      }
+      const rejectLegacyJoin = (verification, agentId) => {
+        process.exitCode = 4;
+        const payload = {
+          command: "session join", joined: false, sessionId: normalizedSessionId,
+          agentId, remoteAgentVerification: verification,
+        };
+        if (emitJson) console.log(JSON.stringify(payload, null, 2));
+        else {
+          const hint = verification.code.includes("UNAVAILABLE")
+            ? "Retry when the API/presence service is available; no new approval was requested."
+            : verification.code.includes("CONTRACT_MISMATCH")
+              ? "Verify the CLI/server contract; no new authorization was created."
+              : verification.code === "LEGACY_GRANT_ROLE_MISMATCH"
+                ? "Use the already-granted role, or request an explicit owner-approved change."
+                : "Request scoped admission with --goal, or have the owner explicitly authorize its legacy grant.";
+          console.log(pc.red(`Agent was not joined: ${verification.code}. ${hint}`));
+        }
+      };
       if (options.cancelAdmission) {
         const cancelled = await cancelAdmission(normalizedSessionId, {
           agentId: requestedAgent,
@@ -3473,6 +3588,13 @@ export function registerSessionCommand(program) {
         else console.log(`Admission request ${payload.admission.admissionId || ""} cancelled.`);
         return;
       }
+      if (requestedAgent && !normalizeString(options.goal)) {
+        const refusal = await legacyJoinAdmissionRefusal(normalizedSessionId, requestedAgent);
+        if (refusal) {
+          rejectLegacyJoin(refusal, requestedAgent);
+          return;
+        }
+      }
       // Membership first. Only a member may ask for an agent to be admitted, so an
       // invitation is accepted BEFORE the admission request, never after.
       let invitationAccept = null;
@@ -3491,24 +3613,15 @@ export function registerSessionCommand(program) {
             : null;
       }
       let admission = null;
+      let admissionJoinOptions = null;
       if (normalizeString(options.goal)) {
         const admissionAgent = requestedAgent;
         if (!admissionAgent) {
           throw new Error("--goal requires --agent <id>: admission is requested for one named agent.");
         }
-        const waitSeconds = Number.parseInt(String(options.waitSeconds ?? "900"), 10);
-        admission = await runAdmissionJoin(normalizedSessionId, {
+        admissionJoinOptions = buildAdmissionJoinOptions(options, {
           agentId: admissionAgent,
           displayName: legacyName && explicitAgent ? legacyName : "",
-          model: options.model,
-          provider: options.provider,
-          goal: options.goal,
-          deliverables: options.deliverable || [],
-          stopConditions: options.stopWhen || [],
-          actions: parseAdmissionScope(options.scope),
-          ttlSeconds: parseAdmissionTtlSeconds(options.ttl),
-          wait: options.wait !== false,
-          waitTimeoutMs: (Number.isFinite(waitSeconds) && waitSeconds >= 0 ? waitSeconds : 900) * 1000,
           targetPath,
           onPending: ({ approveUrl, phase }) => {
             // stderr, so --json stdout stays a single parseable document.
@@ -3524,6 +3637,7 @@ export function registerSessionCommand(program) {
             else console.log(line);
           },
         });
+        admission = await runAdmissionJoin(normalizedSessionId, admissionJoinOptions);
         if (admission.status !== "active") {
           // Only an ACTIVE admission joins. Pending, denied, cancelled or expired never
           // registers the agent or materializes the room for it.
@@ -3550,6 +3664,34 @@ export function registerSessionCommand(program) {
         }
       }
 
+      const admittedAgentId = admission ? requestedAgent : "";
+      const acceptedOnboarding = normalizeSessionOnboarding(
+        invitationAcceptResult?.onboarding,
+        invitationAcceptResult?.claimedSeat,
+      );
+      const acceptedAgentId = normalizeString(acceptedOnboarding?.agentId);
+      if (!admission && !explicitAgent && acceptedAgentId) {
+        assertCanonicalAgentId(acceptedAgentId, "the invitation's agent id");
+      }
+      const agentSeed = admission ? admittedAgentId : explicitAgent || acceptedAgentId || legacyName;
+      const resolvedAgentId = await defaultAgentId(agentSeed, targetPath);
+      if (admission && resolvedAgentId !== admittedAgentId) {
+        throw new Error(`join would register "${resolvedAgentId}", not the admitted agent "${admittedAgentId}".`);
+      }
+      const roleWasExplicit = optionWasSetByCli(command, "role");
+      const role =
+        normalizeString(roleWasExplicit ? options.role : acceptedOnboarding?.role || options.role) ||
+        "coder";
+      const model = normalizeString(options.model) || "cli";
+      const namedLegacyAgent = !admission && Boolean(agentSeed || normalizeString(process.env.SENTINELAYER_AGENT_ID));
+      if (namedLegacyAgent) {
+        const refusal = await legacyJoinAdmissionRefusal(normalizedSessionId, resolvedAgentId);
+        if (refusal) {
+          rejectLegacyJoin(refusal, resolvedAgentId);
+          return;
+        }
+      }
+
       // 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
@@ -3564,21 +3706,36 @@ export function registerSessionCommand(program) {
       // grant's receipt, and never with the human token. A cached "active" is not
       // reported until this succeeds (a revoked grant is not joined), and nothing
       // about the room is fetched on the human's authority.
-      const admittedAgentId = admission ? requestedAgent : "";
       let admissionReceipt = null;
       if (admission) {
-        try {
-          admissionReceipt = await withAgentAdmission(normalizedSessionId, admittedAgentId, () =>
+        const verifyAdmissionReceipt = async () => {
+          const receipt = await withAgentAdmission(normalizedSessionId, admittedAgentId, () =>
             fetchOwnAdmissionReceipt(normalizedSessionId, { targetPath }),
           );
           // The grant must be for EXACTLY the identity this join registers, byte for
           // byte: a receipt for any other spelling is a different agent's authority.
-          const receiptAgent = String(admissionReceipt?.agentId ?? "");
+          const receiptAgent = String(receipt?.agentId ?? "");
           if (receiptAgent !== admittedAgentId) {
             throw new Error(
               `the admission is for agent "${receiptAgent || "(none)"}", not "${admittedAgentId}"`,
             );
           }
+          return receipt;
+        };
+        try {
+          try {
+            admissionReceipt = await verifyAdmissionReceipt();
+          } catch (error) {
+            // One key-possession recovery for a stale bearer, never a different
+            // identity, denied scope, provider/network failure or generic 403.
+            if (options.recoverAdmission || !(error instanceof SentinelayerApiError) ||
+                ![401, 403].includes(error.status) || error.code !== "INVALID_TOKEN") throw error;
+            admission = await runAdmissionJoin(normalizedSessionId, {
+              ...admissionJoinOptions, recoverActive: true,
+            });
+            if (admission.status !== "active") throw new Error("The admission is not active; recovery did not join the agent.");
+            admissionReceipt = await verifyAdmissionReceipt();
+          }
         } catch (error) {
           process.exitCode = 4;
           const payload = {
@@ -3594,7 +3751,7 @@ export function registerSessionCommand(program) {
             },
           };
           if (emitJson) console.log(JSON.stringify(payload, null, 2));
-          else console.log(pc.red(`The API no longer accepts this agent's admission; it was not joined.`));
+          else console.log(pc.red(`The API no longer accepts this agent's admission; it was not joined. For a live grant with a retained key, retry the unchanged request with --recover-admission.`));
           return;
         }
         admission = { ...admission, verified: true, receipt: admissionReceipt };
@@ -3622,6 +3779,16 @@ export function registerSessionCommand(program) {
       }
 
       const remoteSession = verification.session || {};
+      let legacyAgentVerification = null;
+      if (namedLegacyAgent) {
+        legacyAgentVerification = await verifyLegacyAgentJoin(normalizedSessionId, {
+          agentId: resolvedAgentId, role, model, targetPath, remoteSession,
+        });
+        if (!legacyAgentVerification.ok) {
+          rejectLegacyJoin(legacyAgentVerification, resolvedAgentId);
+          return;
+        }
+      }
       const localSession = await ensureLocalSessionForRemoteCommand(normalizedSessionId, {
         targetPath,
         title: normalizeString(remoteSession.title),
@@ -3637,29 +3804,6 @@ export function registerSessionCommand(program) {
             )
           : { skipped: true, reason: "the grant does not include session.read" };
 
-      const acceptedOnboarding = normalizeSessionOnboarding(
-        invitationAcceptResult?.onboarding,
-        invitationAcceptResult?.claimedSeat,
-      );
-      const acceptedAgentId = normalizeString(acceptedOnboarding?.agentId);
-      // An admitted join registers the admitted identity and nothing else. Otherwise an
-      // invitation's onboarding agent id is the identity only when none was given, and
-      // it is held to the same canonical rule before anything is registered locally.
-      if (!admission && !explicitAgent && acceptedAgentId) {
-        assertCanonicalAgentId(acceptedAgentId, "the invitation's agent id");
-      }
-      const agentSeed = admission ? admittedAgentId : explicitAgent || acceptedAgentId || legacyName;
-      const resolvedAgentId = await defaultAgentId(agentSeed, targetPath);
-      if (admission && resolvedAgentId !== admittedAgentId) {
-        throw new Error(`join would register "${resolvedAgentId}", not the admitted agent "${admittedAgentId}".`);
-      }
-      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);
-
       // Registration updates the local participant projection and returns
       // onboarding directly to this process. It never writes join, identity,
       // or coaching rows into the transcript.
@@ -3671,7 +3815,7 @@ export function registerSessionCommand(program) {
         clientKind: "cli",
         role,
         trackProcessExit: false,
-        awaitRemoteSync: hasConcreteAgentIdentity,
+        preserveIdentity: Boolean(admission || namedLegacyAgent),
       });
       const agentJoinRelayed = false;
       const localBriefingPayload =
@@ -3714,6 +3858,7 @@ export function registerSessionCommand(program) {
         materializedLocalSession: localSession.materialized,
         refreshedLocalSession: Boolean(localSession.refreshed),
         verificationSource: verification.source,
+        remoteAgentVerification: legacyAgentVerification,
         joinHydration,
         eventCount: Number.isFinite(eventCount) ? eventCount : 0,
         agentCount: Number.isFinite(agentCount) ? agentCount : 0,
@@ -3820,6 +3965,7 @@ export function registerSessionCommand(program) {
     .option("--stdin", "Read the message body from stdin")
     .option("--force-cli-user", "Allow fallback sends as cli-user when no agent identity can be resolved")
     .option("--local-only", "Append only to the local session cache without remote send confirmation")
+    .option("--no-auto-grant", "Skip auto-grant on 403 IDENTITY_FORGERY; fail immediately instead")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
     .action(asAdmittedAgent(sessionSayAgent, async (sessionId, messageParts, options, command) => {
@@ -3898,6 +4044,7 @@ export function registerSessionCommand(program) {
         for (let attempt = 0; attempt < 2; attempt += 1) {
           remoteSync = await syncSessionEventToApi(normalizedSessionId, event, {
             targetPath,
+            noAutoGrant: options.autoGrant === false,
           });
           if (remoteSync?.synced) break;
         }
@@ -3960,6 +4107,7 @@ export function registerSessionCommand(program) {
     .option("--display-name <name>", "Human-readable agent display name")
     .option("--role <role>", "Agent role metadata: coder, reviewer, tester, observer", "coder")
     .option("--to <agent>", "Direct the message to a specific agent id")
+    .option("--no-auto-grant", "Skip auto-grant on 403 IDENTITY_FORGERY; fail immediately instead")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, message, options, command) => {
@@ -4029,6 +4177,7 @@ export function registerSessionCommand(program) {
       }
       const remoteSync = await syncSessionEventToApi(normalizedSessionId, event, {
         targetPath,
+        noAutoGrant: options.autoGrant === false,
       });
       if (!remoteSync?.synced) {
         throw new Error(
@@ -4096,6 +4245,7 @@ export function registerSessionCommand(program) {
     .option("--proposal <text>", "Suggested remediation or next step")
     .option("--message-file <path>", "Read the observation summary from a UTF-8 file")
     .option("--stdin", "Read the observation summary from stdin")
+    .option("--no-auto-grant", "Skip auto-grant on 403 IDENTITY_FORGERY; fail immediately instead")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, summaryParts, options, command) => {
@@ -4201,6 +4351,7 @@ export function registerSessionCommand(program) {
       }
       const remoteSync = await syncSessionEventToApi(normalizedSessionId, event, {
         targetPath,
+        noAutoGrant: options.autoGrant === false,
       });
       if (!remoteSync?.synced) {
         throw new Error(
@@ -4685,6 +4836,132 @@ export function registerSessionCommand(program) {
       return payload;
     });
 
+  const filesCommand = session
+    .command("files <sessionId>")
+    .description(
+      "List the files published in a room: name, size, type, who uploaded it and when, and the attachment id to download it with",
+    )
+    .option("--limit <n>", `Most files to list (default ${DEFAULT_ROOM_FILES_LIMIT}, max ${MAX_ROOM_FILES_LIMIT})`)
+    .option(
+      "--max-pages <n>",
+      `Most pages of room history to read, 200 events each (default ${DEFAULT_ROOM_FILES_MAX_PAGES})`,
+    )
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .addHelpText(
+      "after",
+      "\nDownload a file with: sl session files get <sessionId> <attachmentId> [--out <path>] [--force]",
+    )
+    .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 limit = parsePositiveInteger(options.limit, "limit", DEFAULT_ROOM_FILES_LIMIT);
+      const maxPages = parsePositiveInteger(options.maxPages, "max-pages", DEFAULT_ROOM_FILES_MAX_PAGES);
+      const result = await listRoomFiles(normalizedSessionId, { targetPath, limit, maxPages });
+      if (!result.ok) {
+        throw new Error(`Could not list room files (${result.reason || "unknown"}).`);
+      }
+      const payload = {
+        command: "session files",
+        sessionId: normalizedSessionId,
+        count: result.count,
+        complete: result.complete,
+        pages: result.pages,
+        scannedEvents: result.scannedEvents,
+        files: result.files,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return payload;
+      }
+      if (!result.count) {
+        console.log(
+          pc.gray(
+            result.complete
+              ? "No files have been published in this room."
+              : `No files in the last ${result.scannedEvents} events; raise --max-pages to read further back.`,
+          ),
+        );
+        return payload;
+      }
+      console.log(pc.bold(`Files published in ${normalizedSessionId} (${result.count}, newest first)`));
+      for (const file of result.files) {
+        const type = file.contentType || file.kind || "unknown type";
+        const who = file.uploadedBy ? ` by ${file.uploadedBy}` : "";
+        const when = file.uploadedAt || file.publishedAt;
+        const message = file.publishedSequenceId ? ` in #${file.publishedSequenceId}` : "";
+        console.log(`${file.filename || "(unnamed)"}  ${formatFileSize(file.sizeBytes)}  ${type}${who}${when ? ` ${when}` : ""}${message}`);
+        console.log(pc.gray(`  attachment id ${file.attachmentId}`));
+      }
+      if (!result.complete) {
+        console.log(pc.gray("More files may exist further back; raise --limit or --max-pages."));
+      }
+      console.log(pc.gray(`Download one with: sl session files get ${normalizedSessionId} <attachmentId> [--out <path>]`));
+      return payload;
+    });
+
+  filesCommand
+    .command("get <sessionId> <attachmentId>")
+    .description(
+      "Download one published room file: streamed to disk, checked against the server's sha256, and written atomically",
+    )
+    .option("--out <path>", "File or directory to write to (default: the server's file name in the workspace)")
+    .option("--force", "Overwrite an existing file")
+    .option("--path <path>", "Workspace path; a relative --out must stay inside it", ".")
+    .option("--json", "Emit machine-readable output")
+    .addHelpText(
+      "after",
+      "\nThe destination folder is checked when the download starts; this does not protect against another local process renaming or relinking folders during the download.",
+    )
+    .action(async (sessionId, attachmentId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      const normalizedAttachmentId = normalizeString(attachmentId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      // `files` also defines --path and --json, so Commander gives them to it: read the merged values.
+      const merged = typeof command?.optsWithGlobals === "function" ? command.optsWithGlobals() : options;
+      const targetPath = path.resolve(process.cwd(), String(merged.path || options.path || "."));
+      let result;
+      try {
+        result = await downloadRoomFile(normalizedSessionId, normalizedAttachmentId, {
+          targetPath,
+          out: options.out,
+          force: Boolean(options.force),
+        });
+      } catch (error) {
+        if (error instanceof RoomFileError) {
+          throw new Error(error.message);
+        }
+        throw error;
+      }
+      const payload = {
+        command: "session files get",
+        sessionId: normalizedSessionId,
+        attachmentId: normalizedAttachmentId,
+        path: result.path,
+        bytes: result.bytes,
+        sha256: result.sha256,
+        verified: result.verified,
+        overwritten: result.overwritten,
+        linkRefetched: result.linkRefetched,
+        attachment: result.attachment,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return payload;
+      }
+      console.log(
+        pc.green(
+          `Saved ${result.attachment.filename || normalizedAttachmentId} (${formatFileSize(result.bytes)}, sha256 verified) to ${result.path}`,
+        ),
+      );
+      return payload;
+    });
+
   const runFileLockCommand = async (verb, sessionId, files, options, command) => {
     const normalizedSessionId = normalizeString(sessionId);
     if (!normalizedSessionId) {
@@ -5331,6 +5608,7 @@ export function registerSessionCommand(program) {
       "--no-presence",
       "Do not renew ephemeral remote presence",
     )
+    .option("--presence-check", "Check once whether the server lists this agent after the first presence renewal")
     .option(
       "--model <model>",
       "Model/provider label to publish with listener presence",
@@ -5587,6 +5865,29 @@ export function registerSessionCommand(program) {
       let lastPresenceHeartbeatMs = 0;
       let lastPresenceHeartbeatFingerprint = "";
       let nextPresenceAttemptMs = 0;
+      let minimalPresence = false;
+      let presenceCheckPending = Boolean(options.presenceCheck);
+      const checkPresence = async () => {
+        if (!presenceCheckPending) return;
+        presenceCheckPending = false;
+        const roster = await fetchSessionPresence(normalizedSessionId, { targetPath });
+        const present = roster.ok
+          ? roster.present.some((entry) => entry.agentId === agentId)
+          : null;
+        if (emitFormat === "ndjson") {
+          console.log(JSON.stringify(createAgentEvent({
+            event: "session_presence_check",
+            agentId,
+            sessionId: normalizedSessionId,
+            payload: { present, reason: roster.reason || null },
+          })));
+        } else if (present !== null) {
+          console.log(`Presence check: ${agentId} is ${present ? "listed" : "not listed"} in session ${normalizedSessionId}.`);
+        }
+        if (present === null) {
+          console.error(`Presence check: ${agentId} presence is unknown (${roster.reason || "presence_read_failed"}).`);
+        }
+      };
 
       // Periodic in-session success reminders (ack, claim work, reply
       // in-thread). Long-running interactive listeners only — skipped under
@@ -5700,7 +6001,7 @@ export function registerSessionCommand(program) {
           },
           onEvent: async (event) => {
             if (emitFormat === "ndjson") {
-              console.log(JSON.stringify(event));
+              console.log(JSON.stringify(withEditSummary(withAttachmentSummary(event))));
             } else {
               console.log(formatEventLine(event));
             }
@@ -5762,7 +6063,10 @@ export function registerSessionCommand(program) {
                 );
               }
             }
-            if (!publishPresence) return;
+            if (!publishPresence) {
+              await checkPresence();
+              return;
+            }
             const lifecycleType = normalizeString(lifecycle?.type);
             const presenceAttemptMs = Date.now();
             if (lifecycleType !== "stopped" && presenceAttemptMs < nextPresenceAttemptMs) {
@@ -5789,7 +6093,7 @@ export function registerSessionCommand(program) {
               lastPresenceHeartbeatFingerprint = heartbeatDecision.fingerprint;
               lastPresenceHeartbeatMs = nowMs;
             }
-            const presenceResult = await publishListenerPresenceEvent({
+            const presenceOptions = {
               sessionId: normalizedSessionId,
               targetPath,
               agentId,
@@ -5799,7 +6103,18 @@ export function registerSessionCommand(program) {
               clientKind,
               listenerId,
               lifecycle: publishLifecycle,
-            });
+              minimalPresence,
+            };
+            let presenceResult = await publishListenerPresenceEvent(presenceOptions);
+            if (!minimalPresence && presenceResult?.reason === "api_403" && presenceResult?.code === "AGENT_IDENTITY_REQUIRED") {
+              minimalPresence = true;
+              console.error("Presence renewal refused (403 AGENT_IDENTITY_REQUIRED; runtime/working require scoped agent credentials); retrying with agentId and model only for this listener session.");
+              presenceResult = await publishListenerPresenceEvent({ ...presenceOptions, minimalPresence });
+            }
+            if (!presenceResult?.ok) {
+              console.error(`Presence renewal failed for ${agentId} (${presenceResult?.reason || "not_recorded"}); the server may not list this listener.`);
+            }
+            await checkPresence();
             if (presenceResult?.ok) {
               nextPresenceAttemptMs = 0;
               return;
@@ -6600,11 +6915,11 @@ export function registerSessionCommand(program) {
           tail,
           beforeSequence,
           count: events.length,
-          events,
+          events: events.map(withAttachmentSummary).map(withEditSummary),
           includeControlEvents,
           hiddenControlEventCount,
           unacknowledgedHumanMessageCount: unacknowledgedHumanMessages.length,
-          unacknowledgedHumanMessages,
+          unacknowledgedHumanMessages: unacknowledgedHumanMessages.map(withAttachmentSummary).map(withEditSummary),
           recentHumanActivityCount: recentHumanActivity.length,
           recentHumanActivity,
           autoView,
@@ -6706,7 +7021,7 @@ export function registerSessionCommand(program) {
             if (item.event) {
               if (!includeControlEvents && isSessionControlEvent(item.event)) continue;
               if (emitJson) {
-                console.log(JSON.stringify({ source: item.source, event: item.event }));
+                console.log(JSON.stringify({ source: item.source, event: withEditSummary(withAttachmentSummary(item.event)) }));
               } else {
                 const sourceTag = item.source === "sse" ? pc.cyan("[sse]") : pc.gray("[fs] ");
                 console.log(`${sourceTag} ${formatEventLine(item.event)}`);
@@ -6737,7 +7052,7 @@ export function registerSessionCommand(program) {
           continue;
         }
         if (emitJson) {
-          console.log(JSON.stringify(event));
+          console.log(JSON.stringify(withEditSummary(withAttachmentSummary(event))));
         } else {
           console.log(formatEventLine(event));
         }
@@ -6795,6 +7110,170 @@ export function registerSessionCommand(program) {
       }
     });
 
+  session
+    .command("events <sessionId>")
+    .description("Return one raw, verifiable page of session events from the remote API (ascending by sequence, no local merge). Use --before-sequence to walk backwards.")
+    .option("--remote", "Fetch from the SentinelLayer API (required; this command is remote-only)")
+    .option("--before-sequence <n>", "Return events older than this sequence id (omit for newest)")
+    .option("--limit <n>", "Maximum events (1-200, default 50)", "50")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--no-auto-grant", "Accepted, has no effect (session events is read-only; reads never auto-grant)")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      if (!options.remote) {
+        throw new Error("session events requires --remote (this command is remote-only; use 'session read' for local streams).");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const beforeSequence = parseOptionalPositiveInteger(options.beforeSequence, "before-sequence");
+      const rawLimit = parsePositiveInteger(options.limit, "limit", 50);
+      if (rawLimit > 200) {
+        throw new Error("limit must be between 1 and 200.");
+      }
+      const limit = Math.max(1, rawLimit);
+      const emitJson = shouldEmitJson(options, command);
+
+      const authSession = await resolveActiveAuthSession({
+        cwd: targetPath,
+        env: process.env,
+        autoRotate: false,
+      });
+      if (!isAuthenticated(authSession)) {
+        throw new Error(`Remote session events requires authentication. Run \`${authLoginHint()}\` first.`);
+      }
+
+      const result = await pollSessionEventsBefore(normalizedSessionId, {
+        targetPath,
+        beforeSequence,
+        limit,
+        timeoutMs: 15_000,
+      });
+
+      const contractViolation = pageContractViolation(normalizedSessionId, beforeSequence, limit, result);
+      const rawNext = result?.rawNextBeforeSequence;
+
+      const payload = {
+        command: "session events",
+        targetPath,
+        sessionId: normalizedSessionId,
+        ok: result.ok && !contractViolation,
+        beforeSequence: beforeSequence || null,
+        count: Array.isArray(result.events) ? result.events.length : 0,
+        nextBeforeSequence: rawNext ?? null,
+        hasMore: Boolean(result.hasMore),
+        partial: Boolean(result.partial),
+        events: Array.isArray(result.events) ? result.events : [],
+        reason: contractViolation ? "page_contract_violation" : (result.reason || ""),
+        contractViolation: contractViolation || undefined,
+      };
+
+      // C3: non-zero exit on failure in --json mode
+      if (emitJson && !payload.ok) {
+        process.exitCode = 1;
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      if (emitJson) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      if (!payload.ok) {
+        if (contractViolation) {
+          throw new Error(`Session events page contract violated: ${contractViolation}`);
+        }
+        throw new Error(`Session events fetch failed (${result.reason || "unknown"}).`);
+      }
+      for (const event of result.events || []) {
+        const seq = Number(event.sequenceId || event.sequence_id || 0);
+        const seqLabel = Number.isFinite(seq) && seq > 0 ? `#${Math.floor(seq)}` : "";
+        console.log(`${seqLabel} ${formatEventLine(event)}`);
+      }
+      if (result.beforeSequence && result.events && result.events.length >= limit) {
+        console.log(pc.gray(`More events before sequence ${result.beforeSequence}.`));
+      }
+    });
+
+
+function pageContractViolation(requestedSessionId, beforeSequence, limit, result) {
+  if (!result || !result.ok) return null;
+
+  const rawEvents = result.rawEvents;
+  const rawNextBeforeSequence = result.rawNextBeforeSequence;
+  const hasMore = result.hasMore;
+  const partial = result.partial;
+
+  // 1. rawEvents is not an Array (missing, or an object)
+  if (!Array.isArray(rawEvents)) {
+    return "page_events_not_array";
+  }
+
+  // C6: coverage fields must be present booleans; absence is fail-closed
+  if (typeof hasMore !== "boolean") {
+    return "page_coverage_fields_missing";
+  }
+  if (typeof partial !== "boolean") {
+    return "page_coverage_fields_missing";
+  }
+
+  // C6: the bridge cannot use a partial page
+  if (partial === true) {
+    return "page_partial";
+  }
+
+  // 5. hasMore === true and rawNextBeforeSequence is null or missing
+  if (hasMore === true && (rawNextBeforeSequence === null || rawNextBeforeSequence === undefined)) {
+    return "page_has_more_without_cursor";
+  }
+
+  // 4. rawNextBeforeSequence is not null and is not a safe positive integer
+  if (rawNextBeforeSequence !== null && rawNextBeforeSequence !== undefined) {
+    if (!Number.isSafeInteger(rawNextBeforeSequence) || rawNextBeforeSequence <= 0) {
+      return "page_next_before_not_safe_positive_integer";
+    }
+    if (Number.isFinite(beforeSequence) && rawNextBeforeSequence >= beforeSequence) {
+      return "next_before_sequence_not_less_than_requested";
+    }
+  }
+
+  // 3. rawEvents.length > the requested limit
+  if (rawEvents.length > limit) {
+    return "page_too_many_events";
+  }
+
+  // 2. Validate each raw event's sequenceId
+  const seen = new Set();
+  for (const event of rawEvents) {
+    const rawSeq = event?.sequenceId;
+    if (typeof rawSeq !== "number" || !Number.isSafeInteger(rawSeq) || rawSeq <= 0) {
+      return "event_sequence_not_safe_positive_integer";
+    }
+
+    // event's sequenceId >= beforeSequence
+    if (Number.isFinite(beforeSequence) && rawSeq >= beforeSequence) {
+      return "event_sequence_not_before_requested";
+    }
+
+    // event carries a sessionId other than the one requested
+    const eventSessionId = normalizeString(event?.sessionId ?? event?.session_id);
+    if (eventSessionId && eventSessionId !== requestedSessionId) {
+      return "event_session_id_mismatch";
+    }
+
+    // duplicate sequence ids
+    if (seen.has(rawSeq)) {
+      return "duplicate_event_sequence";
+    }
+    seen.add(rawSeq);
+  }
+
+  return null;
+}
+
+
   session
     .command("recall <need>")
     .description(
@@ -7230,12 +7709,38 @@ export function registerSessionCommand(program) {
       );
     });
 
+  session
+    .command("standup <sessionId>")
+    .description("Summarize returned ticket records and their evidence without a model call")
+    .option("--since <24h|ISO>", "Include records updated since this time (inclusive)")
+    .option("--agent <id>", "Agent reading the tickets (defaults to the joined session agent)")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const result = await sessionStandup(normalizeString(sessionId), {
+        since: options.since, targetPath: path.resolve(process.cwd(), String(options.path || ".")),
+      });
+      console.log(shouldEmitJson(options, command) ? JSON.stringify(result, null, 2) : formatSessionStandup(result));
+    });
+
   // ---------------------------------------------------------------- tickets
   // The room's shared backlog (API "Ticket Lease Contract (T2)"). Every subcommand is
   // an ACTOR command: the runCli choke point runs it on the agent's admission.
   const ticket = session
     .command("ticket")
-    .description("The room's shared backlog: list, claim, renew, release and submit tickets");
+    .description("The room's shared backlog: list, claim, renew, release and submit tickets")
+    .addHelpText("after", `
+Workflow:
+  sl session ticket list <sessionId> --available --json
+  sl session ticket claim <sessionId> <ticketId> --expected-version <version>
+  sl session ticket renew <sessionId> <ticketId>
+  sl session ticket submit <sessionId> <ticketId> --sha <commit> --evidence-file evidence.json
+
+The evidence file is a JSON array of re-checkable claims. Submit means in_review,
+not done. Use release --reason "handoff" when you cannot continue.
+Agent work requires that agent's live admission; --agent is not authorization.
+Guide: https://sentinelayer.com/docs/senti/overview/
+`);
 
   // Ticket work is attributed by the CREDENTIAL, never by a label: the lease routes take the
   // holder from authentication alone. So an agent identity is allowed only with that agent's
@@ -7264,6 +7769,48 @@ export function registerSessionCommand(program) {
     console.log(line);
   }
 
+  ticket
+    .command("create <sessionId>")
+    .description("Create a ticket in the room. Agent and source attribution are recorded only by servers that support them; the output says whether they were")
+    .requiredOption("--title <text>", "Ticket title")
+    .option("--body <text>", "Ticket description", "")
+    .option("--agent <id>", "Acting agent identity, authorized by the server")
+    .option("--assignee <id>", "Who should own the work")
+    .option("--source-sequence <n>", "Source message in this room")
+    .option("--idempotency-key <key>", "Reuse the key after an uncertain response")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const sid = normalizeString(sessionId), targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const identity = await resolveSessionSayIdentity({ sessionId: sid, agentId: options.agent, targetPath });
+      const agentId = normalizeString(identity.agentId);
+      const result = await createTicket(sid, { title: options.title, body: options.body, assignee: options.assignee,
+        agentId: agentId === "cli-user" ? "" : agentId, targetPath,
+        sourceSequenceId: options.sourceSequence === undefined ? null : parsePositiveInteger(options.sourceSequence, "source-sequence", 1),
+        ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+      });
+      const { agentRequested, agentRecorded, sourceRequested, sourceRecorded } = result.provenance;
+      const creator = result.ticket?.creator;
+      let creatorNote = " Creator: not recorded.";
+      if (typeof creator?.id === "string" && creator.id.trim()) {
+        if (creator.kind === "agent") {
+          const assurance = creator.credentialBound === true && ["session_admission", "agent_token"].includes(creator.identitySource)
+            ? "credential-bound"
+            : creator.credentialBound === false && creator.identitySource === "authorized_agent_grant"
+              ? "authorized account grant; not a separate agent credential"
+              : "identity assurance unavailable";
+          creatorNote = ` Creator: agent ${creator.id} (${assurance}).`;
+        } else if (creator.kind === "account") {
+          creatorNote = ` Creator: account ${creator.id} (the credential holder's physical identity is not established).`;
+        }
+      }
+      const notes = [
+        agentRequested && !agentRecorded ? ` The response did not confirm requested agent ${agentRequested}.` : "",
+        sourceRequested !== null && !sourceRecorded ? ` The response did not confirm source #${sourceRequested}.` : "",
+      ].join("");
+      ticketOutput(options, command, { command: "session ticket create", ...result }, `Created ${result.ticket.id}.${creatorNote}${notes}`);
+    });
+
   ticket
     .command("list <sessionId>")
     .description("List the room's tickets (--available: only those claimable now)")
@@ -7627,7 +8174,7 @@ export function registerSessionCommand(program) {
 
   session
     .command("status <sessionId>")
-    .description("Show session status, agents, and health")
+    .description("Show workspace session status, agents, and file-lock health")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, options, command) => {
@@ -8493,6 +9040,7 @@ export function registerSessionCommand(program) {
       });
       const payload = {
         command: "session setup-guides",
+        skillsInstallCommand: "sl skills install",
         targetPath,
         sessionId: normalizedSessionId,
         sectionHeading: result.sectionHeading,
@@ -8506,6 +9054,7 @@ export function registerSessionCommand(program) {
       }
 
       console.log(pc.bold(`Session guide sync complete for ${normalizedSessionId}`));
+      console.log("Install bundled Senti agent skills: sl skills install");
       console.log(pc.gray(`AGENTS.md: changed=${result.agents.changed} path=${result.agents.path}`));
       console.log(pc.gray(`CLAUDE.md: changed=${result.claude.changed} path=${result.claude.path}`));
       console.log(
@@ -8586,7 +9135,7 @@ export function registerSessionCommand(program) {
       const concurrency = Math.max(1, Math.min(10, requestedConcurrency, count));
       const tags = parseCsvTokens(options.tags, ["session", "swarm"]);
       const apiUrl = normalizeAidenIdApiUrl(options.apiUrl);
-      const outputRoot = await resolveOutputRoot({
+      const { outputRoot, outputFs } = await resolveOutputContext({
         cwd: targetPath,
         outputDirOverride: options.outputDir,
         env: process.env,
@@ -8679,6 +9228,7 @@ export function registerSessionCommand(program) {
       for (const identity of provisioned) {
         await recordProvisionedIdentity({
           outputRoot,
+          outputFs,
           response: identity.response || {},
           context: {
             source: "session-provision-emails",