sentinelayer-cli 0.40.0 → 0.42.0

package/src/commands/session.js

@@ -42,11 +42,20 @@ import {
 } from "../session/daemon-spawn.js";
 import { listRuntimeRuns } from "../session/runtime-bridge.js";
 import {
+  guardFileLeases,
   listFileLocks,
   lockFile,
   releaseFileLocksForAgent,
+  renewFileLease,
   unlockFile,
 } from "../session/file-locks.js";
+import {
+  formatFileLeaseDenialSummary,
+  installFileLeaseIntegrations,
+  runFileLeaseGuardHook,
+  safeFileLeaseErrorMessage,
+  uninstallFileLeaseIntegrations,
+} from "../session/file-lease-integrations.js";
 import {
   injectSessionGuides,
   setupSessionGuides,
@@ -64,7 +73,7 @@ import {
   refreshSessionCacheForRemoteActivity,
   updateSessionTitle,
 } from "../session/store.js";
-import { fetchSessionListeners, formatListenerLine, summarizeListeners } from "../session/listeners.js";
+import { fetchSessionListeners, formatListenerLine } from "../session/listeners.js";
 import {
   getListenerProcessStatus,
   removeListenerPidRecord,
@@ -82,6 +91,27 @@ import {
   normalizeSessionOnboarding,
   writeSessionOnboardingBrief,
 } from "../session/invitations.js";
+import {
+  cancelAdmission,
+  fetchOwnAdmissionReceipt,
+  parseScope as parseAdmissionScope,
+  parseTtlSeconds as parseAdmissionTtlSeconds,
+  runAdmissionJoin,
+} from "../session/admission.js";
+import {
+  assertCanonicalAgentId,
+  canonicalAgentId,
+  currentAdmittedAgent,
+  withAgentAdmission,
+} from "../session/admission-auth.js";
+import {
+  claimTicket,
+  listTickets,
+  releaseTicketLease,
+  renewTicketLease,
+  submitTicket,
+  ticketEvents,
+} from "../session/tickets.js";
 import { postFirstSentiMessage } from "../session/first-message.js";
 import { createListenerHostWake } from "../session/wake/listen-wake.js";
 import { appendToStream, readStream, tailStream } from "../session/stream.js";
@@ -95,6 +125,8 @@ import {
 import { readSessionPreview } from "../session/preview.js";
 import {
   createSessionMessageAction,
+  editSessionMessage,
+  fetchJsonWithFullTimeout,
   fetchSessionUsageLedger,
   fetchSessionPinnedMessages,
   listSessionMessageActions,
@@ -103,11 +135,16 @@ import {
   pollHumanMessages,
   pollSessionEvents,
   pollSessionEventsBefore,
+  requestSessionListenerStop,
+  renewSessionPresence,
   searchSessionEvents,
   syncSessionEventToApi,
   syncSessionMetadataToApi,
+  updateSessionReadCursor,
 } from "../session/sync.js";
 import { hydrateSessionFromRemote } from "../session/remote-hydrate.js";
+import { messageRevision, replyRevisionEvent, sessionMessageRoutingEvent } 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";
 import { SESSION_LIVE_SUCCESS_TIPS } from "../session/coordination-guidance.js";
@@ -442,7 +479,9 @@ async function confirmSessionEventVisible(
       }
       lastReason = "not_visible";
       const nextCursor = normalizeString(result.cursor);
-      if (!events.length || !nextCursor || nextCursor === pageCursor) {
+      const scanExhausted = result.scanExhausted ?? result.scan_exhausted;
+      const emptyScanCanContinue = !events.length && scanExhausted === false;
+      if (!nextCursor || nextCursor === pageCursor || (!events.length && !emptyScanCanContinue)) {
         break;
       }
       pageCursor = nextCursor;
@@ -558,11 +597,6 @@ const SESSION_MESSAGE_ACTION_DESCRIPTIONS = Object.freeze([
     command: "sl session action <id> disregard --target-sequence <n>",
     description: "Mark a message as intentionally ignored or superseded.",
   },
-  {
-    type: "view",
-    command: "sl session view <id> <sequence>",
-    description: "Manually backfill a read receipt for a target message; remote reads record views automatically.",
-  },
 ]);
 
 function normalizeSessionMessageActionType(value) {
@@ -654,6 +688,11 @@ function buildSessionActionEvent(sessionId, action = {}) {
     },
     sessionId,
     ts: actionCreatedAt(action),
+    messageRevision: messageRevision(action),
+    editedAt: action.editedAt,
+    editedBy: action.editedBy,
+    canEdit: action.canEdit,
+    revisionEvidence: action.revisionEvidence,
     payload: {
       actionId: id,
       actionType,
@@ -661,6 +700,7 @@ function buildSessionActionEvent(sessionId, action = {}) {
       targetCursor: actionTargetCursor(action) || null,
       targetActionId: actionTargetActionId(action) || null,
       note: normalizeString(action.note) || null,
+      metadata: action.metadata && typeof action.metadata === "object" ? action.metadata : undefined,
       message: actionDisplayMessage(action),
       source: "session_action",
     },
@@ -960,12 +1000,12 @@ function normalizeAutoViewTimeoutMs(value) {
   return Math.max(50, Math.min(5_000, Math.floor(parsed)));
 }
 
-async function writeSessionReadViews(sessionId, writeTargets = [], {
+async function writeSessionReadCursor(sessionId, target = null, {
   targetPath,
   agentId,
   timeoutMs = SESSION_READ_AUTO_VIEW_TIMEOUT_MS,
 } = {}) {
-  if (!Array.isArray(writeTargets) || writeTargets.length === 0) {
+  if (!target) {
     return;
   }
   const totalTimeoutMs = normalizeAutoViewTimeoutMs(timeoutMs);
@@ -983,50 +1023,31 @@ async function writeSessionReadViews(sessionId, writeTargets = [], {
   }
 
   try {
-    for (const target of writeTargets) {
-      if (controller.signal.aborted) {
-        break;
-      }
-      const elapsedMs = Math.max(0, Date.now() - startedAt);
-      const remainingMs = Math.max(1, totalTimeoutMs - elapsedMs);
-      const result = await createSessionMessageAction(sessionId, {
-        actionType: "view",
-        targetPath,
-        targetSequenceId: target.targetSequenceId,
-        targetCursor: target.targetCursor,
-        metadata: {
-          source: "cli_read",
-          agentId,
-        },
-        idempotencyKey: defaultActionIdempotencyKey({
-          actionType: "view",
-          targetSequenceId: target.targetSequenceId,
-          targetCursor: target.targetCursor,
-          agentId,
-        }),
-        timeoutMs: remainingMs,
-        signal: controller.signal,
-      });
-      if (!result?.ok) {
-        break;
-      }
-    }
+    const elapsedMs = Math.max(0, Date.now() - startedAt);
+    const remainingMs = Math.max(1, totalTimeoutMs - elapsedMs);
+    await updateSessionReadCursor(sessionId, {
+      targetPath,
+      targetSequenceId: target.targetSequenceId,
+      targetCursor: target.targetCursor,
+      agentId,
+      timeoutMs: remainingMs,
+      signal: controller.signal,
+    });
   } finally {
     clearTimeout(timeoutHandle);
   }
 }
 
-function recordSessionReadViews(sessionId, events = [], {
+function recordSessionReadCursor(sessionId, events = [], {
   targetPath,
   agentId,
   enabled = false,
-  maxTargets = 50,
   timeoutMs = SESSION_READ_AUTO_VIEW_TIMEOUT_MS,
 } = {}) {
-  const maxAutoViewTargets = Math.max(0, Math.min(200, Number(maxTargets) || 0));
+  const normalizedAgentId = normalizeString(agentId);
   const summary = {
     enabled: Boolean(enabled),
-    agentId: normalizeString(agentId) || "cli-user",
+    agentId: normalizedAgentId || "cli-user",
     targetCount: 0,
     attempted: 0,
     recorded: 0,
@@ -1042,26 +1063,22 @@ function recordSessionReadViews(sessionId, events = [], {
     return summary;
   }
 
-  const seenTargets = new Set();
-  const targets = [];
+  let target = null;
   for (const event of Array.isArray(events) ? events : []) {
-    const target = sessionReadViewTarget(event);
-    if (!target || seenTargets.has(target.key)) {
-      continue;
+    const candidate = sessionReadViewTarget(event);
+    if (!candidate) continue;
+    summary.targetCount += 1;
+    if (
+      !target ||
+      Number(candidate.targetSequenceId || 0) >= Number(target.targetSequenceId || 0)
+    ) {
+      target = candidate;
     }
-    seenTargets.add(target.key);
-    targets.push(target);
   }
-  summary.targetCount = targets.length;
+  summary.skipped = Math.max(0, summary.targetCount - (target ? 1 : 0));
+  summary.queued = target ? 1 : 0;
 
-  const writeTargets = maxAutoViewTargets > 0 ? targets.slice(-maxAutoViewTargets) : [];
-  summary.skipped = Math.max(0, targets.length - writeTargets.length);
-  summary.queued = writeTargets.length;
-  if (summary.skipped > 0) {
-    summary.reason = "target_cap_reached";
-  }
-
-  if (writeTargets.length === 0) {
+  if (!target) {
     if (!summary.reason) {
       summary.reason = "no_targets";
     }
@@ -1069,13 +1086,13 @@ function recordSessionReadViews(sessionId, events = [], {
   }
 
   summary.background = true;
-  if (!summary.reason) {
-    summary.reason = "queued_best_effort";
-  }
+  summary.reason = "queued_monotonic_upsert";
 
-  void writeSessionReadViews(sessionId, writeTargets, {
+  void writeSessionReadCursor(sessionId, target, {
     targetPath,
-    agentId: summary.agentId,
+    // Omit a placeholder identity so the server can bind human reads to the
+    // authenticated principal. Explicit agent reads still carry their grant.
+    agentId: normalizedAgentId,
     timeoutMs,
   }).catch(() => {
     // Best-effort view receipts must never affect transcript rendering.
@@ -1412,19 +1429,22 @@ async function findReusableSessionCandidate({
 //     can exercise the local materialization path without a real API.
 async function fetchRemoteSessionDetail(endpoint, headers) {
   let response;
+  let payload;
   try {
-    response = await fetch(endpoint, { method: "GET", headers });
+    ({ response, payload } = await fetchJsonWithFullTimeout(
+      endpoint, { method: "GET", headers, redirect: "error" }, 2_000,
+    ));
   } catch (err) {
     return {
       ok: false,
       response: null,
       status: 0,
-      reason: normalizeString(err?.message) || "fetch_failed",
+      reason: err?.name === "AbortError" ? "request_timeout" : (normalizeString(err?.message) || "fetch_failed"),
       retryable: true,
     };
   }
   if (response && response.ok) {
-    return { ok: true, response, status: response.status, reason: "", retryable: false };
+    return { ok: true, payload, status: response.status, reason: "", retryable: false };
   }
   if (!response) {
     return { ok: false, response: null, status: 0, reason: "no_response", retryable: true };
@@ -1439,8 +1459,7 @@ async function fetchRemoteSessionDetail(endpoint, headers) {
   };
 }
 
-async function parseRemoteSessionDetailResponse(response) {
-  const body = await response.json().catch(() => ({}));
+function parseRemoteSessionDetailResponse(body) {
   return body && body.session && typeof body.session === "object"
     ? body.session
     : body && typeof body === "object"
@@ -1483,7 +1502,7 @@ async function verifyRemoteSession(sessionId, { targetPath } = {}) {
     return {
       ok: true,
       source: "singleton",
-      session: await parseRemoteSessionDetailResponse(detail.response),
+      session: parseRemoteSessionDetailResponse(detail.payload),
       status: detail.status,
     };
   }
@@ -1777,7 +1796,13 @@ export async function ensureWorkspaceSession({
   );
   let titleSync = null;
   if (shouldPushTitle) {
-    titleSync = await pushSessionTitleToApi(created.sessionId, effectiveTitle, { targetPath });
+    titleSync = await pushSessionTitleToApi(created.sessionId, effectiveTitle, {
+      targetPath,
+      // Startup uses the already validated credential; rotation and Retry-After
+      // sleeps belong to explicit auth/title operations, not optional startup.
+      autoRotate: false,
+      maxRetries: 0,
+    });
   }
 
   return {
@@ -1796,11 +1821,8 @@ export async function ensureWorkspaceSession({
 }
 
 function normalizeAgentId(value, fallbackValue = "cli-user") {
-  const normalized = normalizeString(value)
-    .toLowerCase()
-    .replace(/[^a-z0-9._-]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-  return normalized || fallbackValue;
+  // One canonicalisation for authorisation and execution (see admission-auth.js).
+  return canonicalAgentId(value) || fallbackValue;
 }
 
 function canPublishListenerPresence(agentId) {
@@ -1855,13 +1877,6 @@ function normalizeSessionObservationText(rawValue, fieldName, maxLength) {
   return value;
 }
 
-function listenerLifecycleEventName(type = "") {
-  const normalized = normalizeString(type).toLowerCase();
-  if (normalized === "started") return "session_listener_started";
-  if (normalized === "stopped") return "session_listener_stopped";
-  return "session_listener_heartbeat";
-}
-
 function compactPayload(record = {}) {
   return Object.fromEntries(
     Object.entries(record).filter(([, value]) => value !== undefined)
@@ -1948,11 +1963,6 @@ async function publishListenerPresenceEvent({
   lifecycle = {},
 } = {}) {
   const normalizedType = normalizeString(lifecycle.type) || "heartbeat";
-  const eventName = listenerLifecycleEventName(normalizedType);
-  const idempotencyStep = listenerLifecycleIdempotencyStep({
-    ...lifecycle,
-    type: normalizedType,
-  });
   const identity = inferSessionAgentIdentity({
     agentId,
     model: agentModel,
@@ -1960,49 +1970,23 @@ async function publishListenerPresenceEvent({
     provider,
     clientKind,
   });
-  const event = createAgentEvent({
-    event: eventName,
-    sessionId,
-    agent: {
-      id: agentId,
-      model: normalizeString(identity.model) || "cli",
-      role: "listener",
-      displayName: normalizeString(identity.displayName) || agentId,
-      provider: normalizeString(identity.provider) || undefined,
-      clientKind: normalizeString(identity.clientKind) || "cli",
-    },
-    eventId: `session-listener-${listenerId}-${normalizedType}-${idempotencyStep}`,
-    idempotencyToken: `session-listener:${listenerId}:${normalizedType}:${idempotencyStep}`,
-    payload: compactPayload({
-      source: "session_listen",
-      listenerId,
-      lifecycle: normalizedType,
-      state: normalizeString(lifecycle.state) || normalizedType,
-      active: lifecycle.active,
-      cursor: lifecycle.cursor || null,
-      cursorSuffix: lifecycle.cursorSuffix,
-      cursorSource: lifecycle.cursorSource,
-      pollCount: lifecycle.pollCount,
-      heartbeatCount: lifecycle.heartbeatCount,
-      matched: lifecycle.matched,
-      emitted: lifecycle.emitted,
-      persistedCursor: lifecycle.persistedCursor,
-      idleIntervalSeconds: lifecycle.idleIntervalSeconds,
-      activeIntervalSeconds: lifecycle.activeIntervalSeconds,
-      activeWindowSeconds: lifecycle.activeWindowSeconds,
-      presenceIntervalSeconds: lifecycle.presenceIntervalSeconds,
-      presenceKeepaliveSeconds: lifecycle.presenceKeepaliveSeconds,
-      lastHumanActivityAt: lifecycle.lastHumanActivityAt,
-      lastSleepMs: lifecycle.lastSleepMs,
-      nextPollMs: lifecycle.nextPollMs,
-      reason: lifecycle.reason || null,
-      startedAt: lifecycle.startedAt,
-      stoppedAt: lifecycle.stoppedAt,
-      aborted: lifecycle.aborted,
-      stopping: lifecycle.stopping,
-    }),
+  return renewSessionPresence(sessionId, {
+    targetPath,
+    agentId,
+    state:
+      normalizedType === "stopped"
+        ? "stopped"
+        : normalizeString(lifecycle.state) || normalizedType,
+    listenerId,
+    model: normalizeString(identity.model) || "cli",
+    displayName: normalizeString(identity.displayName) || agentId,
+    provider: normalizeString(identity.provider),
+    clientKind: normalizeString(identity.clientKind) || "cli",
+    observedAt:
+      lifecycle.stoppedAt ||
+      lifecycle.startedAt ||
+      new Date().toISOString(),
   });
-  return syncSessionEventToApi(sessionId, event, { targetPath });
 }
 
 function formatListenerCatchupNotice(catchup = {}) {
@@ -2400,17 +2384,6 @@ async function resolveSessionAgentEnvelope(
   return Object.fromEntries(Object.entries(envelope).filter(([, value]) => value !== undefined));
 }
 
-// Builds the lock/unlock say-convention directive the session daemon parses
-// into the authoritative file-lock registry. Kept pure + exported for testing.
-export function buildSessionLockDirective(verb, file, intent = "") {
-  const normalizedFile = normalizeString(file);
-  const normalizedIntent = normalizeString(intent);
-  if (verb === "unlock") {
-    return `unlock: ${normalizedFile} - ${normalizedIntent || "done"}`;
-  }
-  return normalizedIntent ? `lock: ${normalizedFile} - ${normalizedIntent}` : `lock: ${normalizedFile}`;
-}
-
 async function runWithConcurrency(items = [], concurrency = 1, worker = async () => null) {
   const normalizedItems = Array.isArray(items) ? items : [];
   const normalizedConcurrency = Math.max(
@@ -2446,6 +2419,11 @@ function formatEventLine(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 || "")}`;
+  }
   const payload = event.payload && typeof event.payload === "object" ? event.payload : {};
   if (type === "session_action" || type === "session_reply" || type === "session_reaction") {
     const actionType = normalizeString(payload.actionType) || type.replace(/^session_/, "");
@@ -2866,6 +2844,43 @@ async function emitAgentKilledEvent(sessionId, agentId, {
   return event;
 }
 
+function collectOption(value, previous) {
+  return [...(previous || []), value];
+}
+
+/**
+ * Wrap a command action so it runs as its agent: inside that agent's admission when
+ * this machine holds one (every session API call then uses the admission credential
+ * and never the human token), on the legacy path when it holds none, and refused when
+ * what it holds is expired or unusable. `resolveIds` names the (session, agent) pair
+ * exactly the way the action itself resolves it.
+ */
+function asAdmittedAgent(resolveIds, action) {
+  return async (...args) => {
+    const { sessionId, agentId } = await resolveIds(...args);
+    return withAgentAdmission(sessionId, agentId, () => action(...args));
+  };
+}
+
+async function sessionSayAgent(sessionId, _messageParts, options) {
+  const sid = normalizeString(sessionId);
+  const identity = await resolveSessionSayIdentity({
+    sessionId: sid,
+    agentId: options.agent,
+    targetPath: path.resolve(process.cwd(), String(options.path || ".")),
+  });
+  return { sessionId: sid, agentId: identity.agentId };
+}
+
+async function sessionReadAgent(sessionId, options) {
+  const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+  return { sessionId: normalizeString(sessionId), agentId: await defaultAgentId(options.agent, targetPath) };
+}
+
+async function sessionListenAgent(options) {
+  return { sessionId: resolveSessionIdOption(options), agentId: normalizeAgentId(options.agent, "cli-user") };
+}
+
 export function registerSessionCommand(program) {
   const session = program
     .command("session")
@@ -2980,8 +2995,9 @@ export function registerSessionCommand(program) {
       };
 
       // Best-effort admin visibility sync. Session creation remains local-first.
+      let metadataSync = Promise.resolve(null);
       if (remoteSync.attempted) {
-        void syncSessionMetadataToApi(created.sessionId, {
+        metadataSync = syncSessionMetadataToApi(created.sessionId, {
           targetPath,
           sessionId: created.sessionId,
           status: created.status,
@@ -2991,7 +3007,7 @@ export function registerSessionCommand(program) {
           ttlSeconds,
           template: created.template,
           codebaseContext: created.codebaseContext,
-        }).catch(() => {});
+        }, { targetPath, timeoutMs: 2_000 }).catch(() => null);
       }
 
       // Make the session managed by default: spawn the Senti daemon as a
@@ -3028,6 +3044,14 @@ export function registerSessionCommand(program) {
         }).catch((error) => ({ posted: false, reason: normalizeString(error?.message) || "error" }));
       }
       payload.firstMessage = firstMessage;
+      // Own the request lifecycle; do not leave a referenced fetch running
+      // after emitting the single JSON document (even with --no-daemon).
+      const metadataResult = await metadataSync;
+      if (remoteSync.attempted) {
+        remoteSync.status = metadataResult?.synced ? "synced" : "degraded";
+        remoteSync.metadataSynced = Boolean(metadataResult?.synced);
+        remoteSync.reason = metadataResult?.synced ? "metadata_acknowledged" : (metadataResult?.reason || "metadata_sync_failed");
+      }
 
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
@@ -3368,7 +3392,7 @@ export function registerSessionCommand(program) {
     .option("--name <name>", "Agent display name (legacy alias for --agent)")
     .option(
       "--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.",
+      "Granted agent id to register in the participant roster. Join state and onboarding are returned locally and never appended to the transcript.",
     )
     .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")
@@ -3376,6 +3400,21 @@ export function registerSessionCommand(program) {
     .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", ".")
+    .option(
+      "--goal <text>",
+      "Request goal-and-scope admission: say what this agent is coming to do. A room owner approves it on the web; the agent then receives its own scoped, expiring identity.",
+    )
+    .option("--deliverable <text>", "An output this agent will produce (repeatable)", collectOption, [])
+    .option("--stop-when <text>", "A condition that ends this agent's work (repeatable)", collectOption, [])
+    .option(
+      "--scope <actions>",
+      "Comma-separated actions to request: session.read, session.post, session.react, tickets.read, tickets.work",
+    )
+    .option("--ttl <duration>", "How long the grant should last, e.g. 90m or 2h (5m..24h)", "2h")
+    .option("--provider <name>", "Model provider hint for the admission request")
+    .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("--json", "Emit machine-readable output")
     .action(async (sessionId, options, command) => {
       const normalizedSessionId = normalizeString(sessionId);
@@ -3386,6 +3425,34 @@ export function registerSessionCommand(program) {
       const explicitAgent = normalizeString(options.agent);
       const legacyName = normalizeString(options.name);
       const inviteToken = normalizeString(options.inviteToken);
+      const emitJson = shouldEmitJson(options, command);
+      // ONE requested identity for the whole join, validated before any side effect.
+      // --name is the identity only when --agent is absent (its legacy alias); beside an
+      // explicit --agent it is a free-text display label. Either way the identity is
+      // used in its canonical spelling from here on, so the admission, its receipt,
+      // the local registration and every later implicit command name the same agent.
+      if (!explicitAgent) assertCanonicalAgentId(legacyName, "--name");
+      const requestedAgent = canonicalAgentId(explicitAgent || legacyName);
+      if (options.cancelAdmission) {
+        const cancelled = await cancelAdmission(normalizedSessionId, {
+          agentId: requestedAgent,
+          targetPath,
+        });
+        const payload = {
+          command: "session join",
+          joined: false,
+          sessionId: normalizedSessionId,
+          admission: {
+            status: cancelled?.status || "cancelled",
+            admissionId: cancelled?.admissionId || null,
+          },
+        };
+        if (emitJson) console.log(JSON.stringify(payload, null, 2));
+        else console.log(`Admission request ${payload.admission.admissionId || ""} cancelled.`);
+        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;
       let invitationAcceptResult = null;
       if (inviteToken) {
@@ -3393,7 +3460,7 @@ export function registerSessionCommand(program) {
           targetPath,
           invitationToken: inviteToken,
           seatKey: options.seatKey,
-          agentId: explicitAgent || legacyName,
+          agentId: requestedAgent,
           idempotencyKey: options.idempotencyKey,
         });
         invitationAcceptResult =
@@ -3401,6 +3468,55 @@ export function registerSessionCommand(program) {
             ? invitationAccept.result
             : null;
       }
+      let admission = 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, {
+          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 }) => {
+            // stderr, so --json stdout stays a single parseable document.
+            const line = `Waiting for a room owner to approve this agent: ${approveUrl}`;
+            if (emitJson) process.stderr.write(`${line}\n`);
+            else console.log(pc.yellow(line));
+          },
+        });
+        if (admission.status !== "active") {
+          // Only an ACTIVE admission joins. Pending, denied, cancelled or expired never
+          // registers the agent or materializes the room for it.
+          process.exitCode = admission.status === "pending" ? 3 : 4;
+          const payload = {
+            command: "session join",
+            joined: false,
+            sessionId: normalizedSessionId,
+            agentId: admissionAgent,
+            invitationAccepted: Boolean(invitationAcceptResult),
+            admission,
+          };
+          if (emitJson) {
+            console.log(JSON.stringify(payload, null, 2));
+          } else if (admission.status === "pending") {
+            console.log(pc.yellow(`Admission pending. A room owner approves it here: ${admission.approveUrl || "(see the session page)"}`));
+          } else {
+            console.log(pc.red(`Admission ${admission.status}. The agent was not joined.`));
+          }
+          return;
+        }
+      }
 
       // PR #483 contract: verify the session exists and the caller has access
       // BEFORE materializing local cache state. Without this we'd silently
@@ -3412,7 +3528,48 @@ export function registerSessionCommand(program) {
       // 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 });
+      // An admitted agent proves its grant is live with ITS OWN credential, via the
+      // 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, () =>
+            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 ?? "");
+          if (receiptAgent !== admittedAgentId) {
+            throw new Error(
+              `the admission is for agent "${receiptAgent || "(none)"}", not "${admittedAgentId}"`,
+            );
+          }
+        } catch (error) {
+          process.exitCode = 4;
+          const payload = {
+            command: "session join",
+            joined: false,
+            sessionId: normalizedSessionId,
+            agentId: admittedAgentId,
+            admission: {
+              ...admission,
+              status: "not_accepted",
+              verified: false,
+              reason: error instanceof Error ? error.message : String(error),
+            },
+          };
+          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.`));
+          return;
+        }
+        admission = { ...admission, verified: true, receipt: admissionReceipt };
+      }
+      const verification = admission
+        ? { ok: true, source: "admission_receipt", session: { sessionId: normalizedSessionId } }
+        : await verifyRemoteSession(normalizedSessionId, { targetPath });
       if (!verification.ok) {
         if (verification.status === 404 || verification.reason === "not_found") {
           throw new Error(
@@ -3439,17 +3596,31 @@ export function registerSessionCommand(program) {
         skipRemoteProbe: true,
         remoteSession,
       });
-      const joinHydration = await hydrateJoinBriefingContext(normalizedSessionId, {
-        targetPath,
-      });
+      // History only for a grant that may read it, and then on the admission.
+      const joinHydration = !admission
+        ? await hydrateJoinBriefingContext(normalizedSessionId, { targetPath })
+        : (admissionReceipt?.actions || []).includes("session.read")
+          ? await withAgentAdmission(normalizedSessionId, admittedAgentId, () =>
+              hydrateJoinBriefingContext(normalizedSessionId, { targetPath }),
+            )
+          : { skipped: true, reason: "the grant does not include session.read" };
 
       const acceptedOnboarding = normalizeSessionOnboarding(
         invitationAcceptResult?.onboarding,
         invitationAcceptResult?.claimedSeat,
       );
       const acceptedAgentId = normalizeString(acceptedOnboarding?.agentId);
-      const agentSeed = explicitAgent || acceptedAgentId || legacyName;
+      // 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) ||
@@ -3457,13 +3628,9 @@ export function registerSessionCommand(program) {
       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>` 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).
+      // Registration updates the local participant projection and returns
+      // onboarding directly to this process. It never writes join, identity,
+      // or coaching rows into the transcript.
       const joined = await registerAgent(normalizedSessionId, {
         targetPath,
         agentId: resolvedAgentId,
@@ -3474,13 +3641,12 @@ export function registerSessionCommand(program) {
         trackProcessExit: false,
         awaitRemoteSync: hasConcreteAgentIdentity,
       });
-      const agentJoinRelayed =
-        joined.emittedJoinEvent !== false &&
-        hasConcreteAgentIdentity &&
-        Boolean(resolvedAgentId) &&
-        resolvedAgentId !== "cli-user" &&
-        resolvedAgentId !== "unknown" &&
-        !resolvedAgentId.startsWith("human-");
+      const agentJoinRelayed = false;
+      const localBriefingPayload =
+        joined.onboarding?.contextBriefing?.event?.payload &&
+        typeof joined.onboarding.contextBriefing.event.payload === "object"
+          ? joined.onboarding.contextBriefing.event.payload
+          : null;
       const onboardingBrief = await writeSessionOnboardingBrief(normalizedSessionId, {
         targetPath,
         onboarding: acceptedOnboarding,
@@ -3521,6 +3687,17 @@ export function registerSessionCommand(program) {
         agentCount: Number.isFinite(agentCount) ? agentCount : 0,
         lastActivityAt: lastActivityIso || null,
         agentJoinRelayed,
+        onboardingBriefing: localBriefingPayload
+          ? {
+              forAgent: localBriefingPayload.forAgent || joined.agentId,
+              message: localBriefingPayload.message || "",
+              recap: localBriefingPayload.recap || "",
+              rules: localBriefingPayload.rules || null,
+              generatedAt: localBriefingPayload.generatedAt || null,
+              delivery: "joining_process",
+              persisted: false,
+            }
+          : null,
         invitationAccepted: Boolean(invitationAcceptResult?.ok || invitationAccept),
         invitationAccept: invitationAccept
           ? {
@@ -3536,6 +3713,7 @@ export function registerSessionCommand(program) {
               jsonPath: onboardingBrief.jsonPath,
             }
           : null,
+        admission,
       };
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
@@ -3556,9 +3734,29 @@ export function registerSessionCommand(program) {
         console.log(pc.green(`Invitation accepted${seatLabel}`));
       }
       console.log(pc.gray(`agent=${joined.agentId} role=${joined.role} model=${joined.model}`));
+      if (admission) {
+        if (admission.status === "active") {
+          const expires = new Date(admission.grant.expiresAt * 1000).toISOString();
+          console.log(
+            pc.green(
+              `Admitted${admission.reused ? " (existing grant)" : ""}: ${admission.grant.actions.join(", ")} until ${expires}`,
+            ),
+          );
+          if (admission.identity?.subject) console.log(pc.gray(`identity=${admission.identity.subject}`));
+          console.log(pc.gray(`credential stored at ${admission.credential.storage} (never printed)`));
+        } else if (admission.status === "pending") {
+          console.log(pc.yellow(`Admission pending approval: ${admission.approveUrl}`));
+          console.log(pc.gray("Re-run the same command to resume waiting."));
+        } else {
+          console.log(pc.red(`Admission ${admission.status}.`));
+        }
+      }
       if (payload.onboardingGuide?.markdownPath) {
         console.log(pc.gray(`onboarding=${payload.onboardingGuide.markdownPath}`));
       }
+      if (payload.onboardingBriefing?.recap) {
+        console.log(payload.onboardingBriefing.recap);
+      }
     });
 
   session
@@ -3592,7 +3790,7 @@ export function registerSessionCommand(program) {
     .option("--local-only", "Append only to the local session cache without remote send confirmation")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
-    .action(async (sessionId, messageParts, options, command) => {
+    .action(asAdmittedAgent(sessionSayAgent, async (sessionId, messageParts, options, command) => {
       const normalizedSessionId = normalizeString(sessionId);
       if (!normalizedSessionId) {
         throw new Error("session id is required.");
@@ -3720,7 +3918,7 @@ export function registerSessionCommand(program) {
         console.error(pc.yellow(`Identity warning: ${identity.identityWarning}`));
       }
       console.log(formatEventLine(persisted));
-    });
+    }));
 
   session
     .command("post-agent <sessionId> <message>")
@@ -4010,7 +4208,20 @@ export function registerSessionCommand(program) {
       console.log(formatEventLine(persisted));
     });
 
-  async function runMessageActionCommand({
+  // Every message-action command (react, reply, ack, ...) runs as its authoring
+  // agent: inside that agent's admission when this machine holds one.
+  async function runMessageActionCommand(args = {}) {
+    const sid = normalizeString(args.sessionId);
+    const identity = await resolveMessageActionIdentity({
+      sessionId: sid,
+      optionAgent: args.options?.agent,
+      targetPath: path.resolve(process.cwd(), String(args.options?.path || ".")),
+      env: process.env,
+    });
+    return withAgentAdmission(sid, identity.agentId, () => runMessageActionCommandUnscoped(args));
+  }
+
+  async function runMessageActionCommandUnscoped({
     sessionId,
     actionType,
     options,
@@ -4082,10 +4293,23 @@ export function registerSessionCommand(program) {
     if (!result.ok || !result.action) {
       throw new Error(`Session action failed (${result.reason || "unknown"}).`);
     }
-    const actionEvent = buildSessionActionEvent(normalizedSessionId, result.action);
-    const localAppend = await appendActionEventIfMissing(normalizedSessionId, actionEvent, {
-      targetPath,
-    });
+    const isReadCursorProjection = normalizedActionType === "view";
+    const actionEvent = isReadCursorProjection
+      ? null
+      : buildSessionActionEvent(normalizedSessionId, result.action);
+    const localAppend = isReadCursorProjection
+      ? { appended: false, reason: "read_cursor_projection", event: null }
+      : await appendActionEventIfMissing(normalizedSessionId, actionEvent, {
+          targetPath,
+        });
+    const readCursorProjection = isReadCursorProjection
+      ? {
+          updated: Boolean(result.updated),
+          lastReadSequenceId:
+            Number(result.lastReadSequenceId || result.action.targetSequenceId || 0) || null,
+          targetCursor: targetCursor || null,
+        }
+      : null;
     const payload = {
       command: commandName,
       targetPath,
@@ -4098,11 +4322,22 @@ export function registerSessionCommand(program) {
         appended: Boolean(localAppend.appended),
         reason: localAppend.reason || "",
       },
+      ...(readCursorProjection ? { readCursorProjection } : {}),
     };
     if (shouldEmitJson(options, command)) {
       console.log(JSON.stringify(payload, null, 2));
       return payload;
     }
+    if (readCursorProjection) {
+      const targetLabel = readCursorProjection.lastReadSequenceId
+        ? `#${readCursorProjection.lastReadSequenceId}`
+        : readCursorProjection.targetCursor || "target";
+      const status = readCursorProjection.updated ? "Advanced" : "Confirmed";
+      console.log(
+        pc.green(`${status} read cursor through ${targetLabel}; no transcript event appended.`),
+      );
+      return payload;
+    }
     if (localAppend.event || actionEvent) {
       console.log(formatEventLine(localAppend.event || actionEvent));
     } else {
@@ -4217,20 +4452,50 @@ export function registerSessionCommand(program) {
     });
 
   session
-    .command("view <sessionId> <targetSequenceId>")
-    .description("Manually backfill a read receipt for a target session event")
-    .option("--agent <id>", "Agent id authoring the action (defaults to the joined session agent)")
-    .option("--idempotency-key <key>", "Explicit idempotency key")
+    .command("edit <sessionId> <target> <message...>")
+    .description("Edit your message by sequence or threaded reply UUID; preserves its audit history")
+    .option("--agent <id>", "Authoring agent (defaults to the joined session agent)")
+    .option("--expected-revision <n>", "Guard against concurrent edits; otherwise fetch the current revision once")
+    .option("--idempotency-key <key>", "Reuse an explicit key when retrying the same edit")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
-    .action(async (sessionId, targetSequenceId, options, command) => {
-      await runMessageActionCommand({
-        sessionId,
-        actionType: "view",
-        options,
-        command,
-        commandName: "session view",
-        targetSequenceId: parsePositiveInteger(targetSequenceId, "targetSequenceId", 0),
+    .action(async (sessionId, target, messageParts, options, command) => {
+      const sid = normalizeString(sessionId);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const text = Array.isArray(messageParts) ? messageParts.join(" ") : String(messageParts || "");
+      const sequence = /^\d+$/.test(target) ? Number(target) : null;
+      if (sequence !== null && (!Number.isSafeInteger(sequence) || sequence <= 0)) throw new Error("target sequence must be a positive safe integer.");
+      if (!sequence && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(target)) {
+        throw new Error("Edit target must be a positive message sequence or a threaded reply UUID.");
+      }
+      const identity = await resolveMessageActionIdentity({ sessionId: sid, optionAgent: options.agent, targetPath, env: process.env });
+      if (shouldBlockImplicitCliUserSessionSay(identity)) throw new Error(identity.identityWarning || "session edit requires an authoring agent identity; pass --agent <id>.");
+      const expectedRevision = options.expectedRevision === undefined ? null : Number(options.expectedRevision);
+      if (expectedRevision !== null && (!Number.isSafeInteger(expectedRevision) || expectedRevision <= 0)) throw new Error("expected-revision must be a positive safe integer.");
+      return withAgentAdmission(sid, identity.agentId, async () => {
+        const result = await editSessionMessage(sid, {
+          targetPath,
+          targetSequenceId: sequence,
+          targetActionId: sequence ? "" : target,
+          text,
+          agentId: identity.agentId,
+          expectedRevision,
+          idempotencyKey: options.idempotencyKey,
+          timeoutMs: 15_000,
+        });
+        if (!result.ok) throw new Error(`Session edit failed (${result.reason || "unknown"}). No local message was changed.`);
+        let localAppend = { appended: 0, upgraded: 0, failed: 0 };
+        try {
+          await ensureLocalSessionForRemoteCommand(sid, { targetPath });
+          const current = result.reply ? replyRevisionEvent(sid, result.reply) : result.event;
+          localAppend = await appendMissingRemoteEvents(sid, [current, result.notification].filter(Boolean), { targetPath });
+        } catch {
+          localAppend = { appended: 0, upgraded: 0, failed: 1 };
+        }
+        const payload = { command: "session edit", sessionId: sid, target, ...result, localAppend, localAppendComplete: localAppend.failed === 0 };
+        if (shouldEmitJson(options, command)) console.log(JSON.stringify(payload, null, 2));
+        else console.log(`${result.changed ? "Edited" : "Confirmed"} ${sequence ? `#${sequence}` : `reply ${target}`} at revision ${messageRevision(result.reply || result.event)}.${localAppend.failed ? " Remote edit succeeded; local cache needs sync." : ""}`);
+        return payload;
       });
     });
 
@@ -4319,15 +4584,17 @@ export function registerSessionCommand(program) {
       if (verb === "lock") {
         const result = await lockFile(normalizedSessionId, identity.agentId, file, {
           intent,
+          ttlSeconds: options.ttl,
           targetPath,
-          awaitRemoteSync: true,
         });
         const record = {
           file: result.file || file,
           locked: Boolean(result.locked),
           reason: result.reason || (result.locked ? "locked" : "held_by_other_agent"),
           heldBy: result.heldBy || null,
+          intent: result.lock?.intent || result.lease?.intent || null,
           since: result.since || null,
+          expiresAt: result.lock?.expiresAt || result.lease?.expiresAt || null,
         };
         results.push(record);
         if (result.locked) {
@@ -4341,7 +4608,6 @@ export function registerSessionCommand(program) {
       const result = await unlockFile(normalizedSessionId, identity.agentId, file, {
         reason: intent || "manual_release",
         targetPath,
-        awaitRemoteSync: true,
       });
       const record = {
         file: result.file || file,
@@ -4349,6 +4615,7 @@ export function registerSessionCommand(program) {
         reason: result.reason || (result.unlocked ? "unlocked" : "not_locked"),
         heldBy: result.heldBy || null,
         since: result.since || null,
+        expiresAt: result.lock?.expiresAt || result.lease?.expiresAt || null,
       };
       results.push(record);
       if (result.unlocked) {
@@ -4360,12 +4627,6 @@ export function registerSessionCommand(program) {
       }
     }
 
-    if (failed.length > 0) {
-      const summary = failed
-        .map((item) => `${item.file}${item.heldBy ? ` held by ${item.heldBy}` : ""}`)
-        .join(", ");
-      throw new Error(`session ${verb} failed for ${summary}`);
-    }
     const payload = {
       command: `session ${verb}`,
       sessionId: normalizedSessionId,
@@ -4373,16 +4634,38 @@ export function registerSessionCommand(program) {
       files: processed,
       results,
       skipped,
+      failed,
     };
     if (shouldEmitJson(options, command)) {
       console.log(JSON.stringify(payload, null, 2));
+      if (failed.length > 0) {
+        process.exitCode = 2;
+      }
+      return payload;
+    }
+    if (failed.length > 0) {
+      for (const item of failed) {
+        const details = [
+          item.heldBy ? `held by ${item.heldBy}` : "",
+          item.intent ? `intent: ${item.intent}` : "",
+          item.expiresAt ? `expires ${item.expiresAt}` : "",
+        ].filter(Boolean);
+        console.error(
+          pc.red(
+            `Blocked ${item.file}: ${item.reason}${details.length > 0 ? ` (${details.join(", ")})` : ""}`,
+          ),
+        );
+      }
+      process.exitCode = 2;
       return payload;
     }
-    const action = verb === "lock" ? "Requested lock on" : "Released";
+    const action = verb === "lock" ? "Acquired lease for" : "Released";
     console.log(pc.green(`${action} ${processed.length} file(s) as ${identity.agentId}: ${processed.join(", ")}`));
     if (verb === "lock") {
       console.log(
-        pc.gray("Senti enforces fail-closed; locks auto-release on TTL. Release with `sl session unlock`."),
+        pc.gray(
+          "The SentinelLayer API is authoritative; leases expire by TTL and can be released with `sl session unlock`.",
+        ),
       );
     }
     return payload;
@@ -4390,8 +4673,9 @@ export function registerSessionCommand(program) {
 
   session
     .command("lock <sessionId> <files...>")
-    .description("Claim exclusive file locks via Senti (fail-closed, TTL auto-release)")
+    .description("Claim exclusive API-backed file leases (fail-closed, TTL expiry)")
     .option("--intent <text>", "Why you're locking these files (shown to peers)")
+    .option("--ttl <seconds>", "Lease TTL in seconds (15-3600)", "300")
     .option("--agent <id>", "Agent id claiming the lock (defaults to the joined session agent)")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
@@ -4401,7 +4685,7 @@ export function registerSessionCommand(program) {
 
   session
     .command("unlock <sessionId> <files...>")
-    .description("Release file locks you hold (Senti only lets the holder release)")
+    .description("Release API-backed file leases you hold")
     .option("--intent <text>", "Optional note on the release")
     .option("--agent <id>", "Agent id releasing the lock (defaults to the joined session agent)")
     .option("--path <path>", "Workspace path for the session", ".")
@@ -4410,9 +4694,264 @@ export function registerSessionCommand(program) {
       await runFileLockCommand("unlock", sessionId, files, options, command);
     });
 
+  session
+    .command("renew <sessionId> <files...>")
+    .description("Renew holder-bound file leases without writing session events")
+    .option("--ttl <seconds>", "Renewed lease TTL in seconds (15-3600)", "300")
+    .option("--agent <id>", "Agent id renewing the lease (defaults to the joined session agent)")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, files, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const fileList = (Array.isArray(files) ? files : [files])
+        .map((file) => normalizeString(file))
+        .filter(Boolean);
+      if (fileList.length === 0) {
+        throw new Error("session renew requires at least one file path.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      await ensureLocalSessionForRemoteCommand(normalizedSessionId, { targetPath });
+      const identity = await resolveMessageActionIdentity({
+        sessionId: normalizedSessionId,
+        optionAgent: options.agent,
+        targetPath,
+        env: process.env,
+      });
+      if (shouldBlockImplicitCliUserSessionSay(identity)) {
+        throw new Error(
+          identity.identityWarning ||
+            "session renew requires an agent identity; pass --agent <id>.",
+        );
+      }
+      const results = [];
+      for (const file of fileList) {
+        results.push(
+          await renewFileLease(normalizedSessionId, identity.agentId, file, {
+            ttlSeconds: options.ttl,
+            targetPath,
+          }),
+        );
+      }
+      const payload = {
+        command: "session renew",
+        sessionId: normalizedSessionId,
+        agentId: identity.agentId,
+        allowed: results.every((result) => result.renewed),
+        results,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+      } else if (payload.allowed) {
+        console.log(
+          pc.green(`Renewed ${results.length} file lease(s) as ${identity.agentId}.`),
+        );
+      } else {
+        console.error(
+          pc.red("One or more file leases could not be renewed; edit access is not assured."),
+        );
+      }
+      if (!payload.allowed) {
+        process.exitCode = 2;
+      }
+      return payload;
+    });
+
+  session
+    .command("guard <sessionId> <files...>")
+    .description("Fail-closed authoritative preflight for file edits")
+    .requiredOption("--agent <id>", "Agent id presenting holder capabilities")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, files, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const fileList = (Array.isArray(files) ? files : [files])
+        .map((file) => normalizeString(file))
+        .filter(Boolean);
+      if (fileList.length === 0) {
+        throw new Error("session guard requires at least one file path.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const requestedAgentId = normalizeString(options.agent).toLowerCase();
+      let result;
+      try {
+        result = await guardFileLeases(
+          normalizedSessionId,
+          requestedAgentId,
+          fileList,
+          { targetPath },
+        );
+      } catch (error) {
+        const message = safeFileLeaseErrorMessage(error);
+        result = {
+          ok: false,
+          allowed: false,
+          authoritative: false,
+          sessionId: normalizedSessionId,
+          holderId: requestedAgentId || null,
+          checkedAt: new Date().toISOString(),
+          validUntil: null,
+          files: fileList,
+          guarded: [],
+          denials: fileList.map((file) => ({
+            path: file,
+            reason: "guard_failed",
+          })),
+          error: {
+            code: normalizeString(error?.code) || "FILE_LEASE_GUARD_FAILED",
+            message,
+          },
+        };
+      }
+      const payload = {
+        command: "session guard",
+        ...result,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+      } else if (result.allowed) {
+        console.log(
+          pc.green(`File-lease guard allowed ${fileList.length} edit target(s).`),
+        );
+      } else {
+        if (result.error?.message) {
+          console.error(pc.red(`Authoritative guard failed: ${result.error.message}`));
+        }
+        if ((result.denials || []).length > 0) {
+          console.error(
+            pc.red(`Edit blocked: ${formatFileLeaseDenialSummary(result)}`),
+          );
+        }
+      }
+      if (!result.allowed) {
+        process.exitCode = 2;
+      }
+      return payload;
+    });
+
+  session
+    .command("guard-hook <sessionId>")
+    .description("Claude PreToolUse hook: read tool JSON on stdin and block denied edits")
+    .requiredOption("--agent <id>", "Agent id presenting holder capabilities")
+    .option("--path <path>", "Workspace root", ".")
+    .action(async (sessionId, options) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const result = await runFileLeaseGuardHook({
+        sessionId,
+        agentId: options.agent,
+        targetPath,
+      });
+      process.exitCode = result.exitCode;
+      return result;
+    });
+
+  session
+    .command("guard-install <sessionId>")
+    .description("Install Claude, terminal, and VS Code authoritative lease preflights")
+    .requiredOption("--agent <id>", "Agent id presenting holder capabilities")
+    .option("--path <path>", "Workspace root", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const result = await installFileLeaseIntegrations(
+        sessionId,
+        options.agent,
+        { targetPath },
+      );
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify({
+          command: "session guard-install",
+          ...result,
+        }, null, 2));
+      } else {
+        console.log(
+          pc.green(
+            "Installed Claude PreToolUse blocking plus terminal and VS Code lease preflights.",
+          ),
+        );
+        console.log(
+          pc.yellow(
+            "VS Code native Save cannot be cancelled reliably; run the generated guard task before edits or make it a dependency of mutation tasks.",
+          ),
+        );
+      }
+      return result;
+    });
+
+  session
+    .command("guard-uninstall <sessionId>")
+    .description("Safely remove only fingerprinted SentinelLayer lease preflights before CLI rollback")
+    .requiredOption("--agent <id>", "Agent id that owns the managed integration")
+    .option("--path <path>", "Workspace root", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      let result;
+      try {
+        result = await uninstallFileLeaseIntegrations(
+          sessionId,
+          options.agent,
+          { targetPath },
+        );
+      } catch (error) {
+        result = {
+          ok: false,
+          uninstalled: false,
+          reason: "guard_uninstall_failed",
+          sessionId: normalizeString(sessionId),
+          agentId: normalizeString(options.agent),
+          activeLeases: [],
+          residuals: [],
+          error: {
+            code: normalizeString(error?.code) || "FILE_LEASE_GUARD_UNINSTALL_FAILED",
+            message: safeFileLeaseErrorMessage(error),
+          },
+        };
+      }
+      const payload = {
+        command: "session guard-uninstall",
+        ...result,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+      } else if (result.ok) {
+        console.log(pc.green("Removed the managed SentinelLayer lease preflights."));
+      } else {
+        if (result.error?.message) {
+          console.error(pc.red(`Guard uninstall blocked: ${result.error.message}`));
+        }
+        for (const lease of result.activeLeases || []) {
+          const file = normalizeString(lease.file || lease.path) || "(unknown path)";
+          const holder = normalizeString(lease.agentId || lease.holderId) || "unknown";
+          const expiresAt = normalizeString(lease.expiresAt);
+          console.error(
+            pc.red(
+              `Guard uninstall blocked by ${file} (held by ${holder}${expiresAt ? `, expires ${expiresAt}` : ""}).`,
+            ),
+          );
+        }
+        for (const residual of result.residuals || []) {
+          console.error(
+            pc.red(
+              `Managed artifact retained: ${residual.path || residual.label || residual.artifact} (${residual.reason}).`,
+            ),
+          );
+        }
+      }
+      if (!result.ok) {
+        process.exitCode = 2;
+      }
+      return payload;
+    });
+
   session
     .command("locks <sessionId>")
-    .description("List active file locks for the session (who holds what, and when they expire)")
+    .description("List authoritative active file leases for the session")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, options, command) => {
@@ -4451,11 +4990,11 @@ export function registerSessionCommand(program) {
   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.",
+      "List the authoritative ephemeral listener presence roster. Presence is unknown when the server capability or Redis is unavailable; transcript heartbeats are never scanned.",
     )
     .option("--path <path>", "Workspace path for the session", ".")
-    .option("--limit <n>", "Recent events to scan for heartbeats (default 200)", "200")
-    .option("--max-pages <n>", "Maximum older event pages to scan for heartbeats (default 5)", "5")
+    .option("--limit <n>", "Deprecated compatibility option; no event rows are scanned", "200")
+    .option("--max-pages <n>", "Deprecated compatibility option; no event rows are scanned", "5")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, options, command) => {
       const normalizedSessionId = normalizeString(sessionId);
@@ -4512,12 +5051,18 @@ export function registerSessionCommand(program) {
           };
         }
       }
-      const live = listeners.filter((row) => row.status === "active" || row.status === "idle").length;
+      const live = listeners.filter(
+        (row) => row.status === "present" || row.status === "active" || row.status === "idle",
+      ).length;
       const payload = {
         command: "session listeners",
         sessionId: normalizedSessionId,
         ok: Boolean(result.ok),
         reason: result.ok ? undefined : result.reason,
+        authoritative: Boolean(result.authoritative),
+        presenceStatus: result.presenceStatus || "degraded",
+        presenceEnabled: result.enabled ?? null,
+        retryAfterMs: result.retryAfterMs || null,
         count: listeners.length,
         liveCount: live,
         pageCount: Number(result.pageCount || 0),
@@ -4533,17 +5078,21 @@ export function registerSessionCommand(program) {
         return payload;
       }
       if (!result.ok) {
-        console.log(pc.yellow(`Could not read listeners (${result.reason}).`));
+        console.log(
+          pc.yellow(
+            `Listener presence is unknown (${result.reason}); durable heartbeat history was not scanned.`,
+          ),
+        );
         return payload;
       }
       if (listeners.length === 0) {
-        console.log(pc.gray("No listeners detected (no recent presence heartbeats)."));
+        console.log(pc.gray("No listeners are currently present."));
         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}`));
+        if (row.status === "present" || row.status === "active") console.log(pc.green(`  ${line}`));
         else if (row.status === "idle") console.log(pc.cyan(`  ${line}`));
         else console.log(pc.gray(`  ${line}`));
       }
@@ -4563,7 +5112,7 @@ export function registerSessionCommand(program) {
   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.",
+      "Ask an agent's listener to stop through the ephemeral listener-control plane. 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", ".")
@@ -4576,27 +5125,21 @@ export function registerSessionCommand(program) {
       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 listenerControl = await requestSessionListenerStop(normalizedSessionId, {
+        targetPath,
+        targetAgentId: targetAgent,
       });
-      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(() => {});
+      if (!listenerControl?.ok || !listenerControl?.recorded) {
+        throw new Error(
+          `Listener stop request failed (${normalizeString(listenerControl?.reason) || "not_recorded"}).`,
+        );
+      }
       const payload = {
         command: "session stop-listener",
         sessionId: normalizedSessionId,
         targetAgent: targetAgent || null,
         scope: targetAgent ? "agent" : "all",
-        remoteSync: remoteSync || undefined,
+        listenerControl,
       };
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
@@ -4624,8 +5167,8 @@ export function registerSessionCommand(program) {
     .option("--interval <seconds>", "Idle polling interval in seconds (default 60)", "60")
     .option(
       "--active-interval <seconds>",
-      "Polling interval after recent human activity (default 5)",
-      "5",
+      "Polling interval after recent human activity (default 60)",
+      "60",
     )
     .option(
       "--active-window <seconds>",
@@ -4634,17 +5177,17 @@ export function registerSessionCommand(program) {
     )
     .option(
       "--presence-interval <seconds>",
-      "Minimum seconds between remote listener heartbeat events (default 60)",
+      "Minimum seconds between ephemeral presence renewals (default 60)",
       "60",
     )
     .option(
       "--presence-keepalive <seconds>",
-      "Maximum seconds between unchanged remote listener heartbeat events (default 180)",
+      "Maximum seconds between unchanged ephemeral presence renewals (default 180)",
       "180",
     )
     .option(
       "--no-presence",
-      "Do not publish durable listener lifecycle/heartbeat events",
+      "Do not renew ephemeral remote presence",
     )
     .option(
       "--model <model>",
@@ -4653,7 +5196,7 @@ export function registerSessionCommand(program) {
     )
     .option("--display-name <name>", "Human-readable listener name for presence")
     .option("--emit <format>", "Output format: ndjson or text", "ndjson")
-    .option("--transport <mode>", "Listen transport: auto, stream, or poll (default auto)", "auto")
+    .option("--transport <mode>", "Listen transport: poll, auto, or stream (default poll)", "poll")
     .option("--limit <n>", "Maximum events to request per poll (default 200)", "200")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--since <cursor>", "Override the persisted listen cursor")
@@ -4697,7 +5240,7 @@ export function registerSessionCommand(program) {
       `Total log files to retain including the active file (default ${DEFAULT_ROTATING_LOG_MAX_FILES})`,
       String(DEFAULT_ROTATING_LOG_MAX_FILES),
     )
-    .action(async (options) => {
+    .action(asAdmittedAgent(sessionListenAgent, async (options) => {
       const normalizedSessionId = resolveSessionIdOption(options);
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
       const agentId = normalizeAgentId(options.agent, "cli-user");
@@ -4705,7 +5248,7 @@ export function registerSessionCommand(program) {
       const activeIntervalSeconds = parsePositiveInteger(
         options.activeInterval,
         "active-interval",
-        5,
+        60,
       );
       const activeWindowSeconds = parsePositiveInteger(options.activeWindow, "active-window", 300);
       const presenceIntervalSeconds = parsePositiveInteger(
@@ -4781,7 +5324,7 @@ export function registerSessionCommand(program) {
           "--wake-host requires a valid host (claude|codex) and --resume-session <host-session-id>.",
         );
       }
-      const requestedTransport = normalizeString(options.transport).toLowerCase() || "auto";
+      const requestedTransport = normalizeString(options.transport).toLowerCase() || "poll";
       if (!["auto", "stream", "poll"].includes(requestedTransport)) {
         throw new Error("--transport must be one of: auto, stream, poll.");
       }
@@ -4789,9 +5332,15 @@ export function registerSessionCommand(program) {
         options.maxPolls === undefined
           ? null
           : parsePositiveInteger(options.maxPolls, "max-polls", 1);
-      const listenTransport = requestedTransport === "auto" && maxPolls !== null
-        ? "poll"
-        : requestedTransport;
+      if (currentAdmittedAgent() && requestedTransport === "stream") {
+        throw new Error(
+          "An admitted agent listens by polling: the event stream is not part of an admission grant, so a revoke never has to chase an open stream. Use --transport poll.",
+        );
+      }
+      const listenTransport =
+        requestedTransport === "auto" && (maxPolls !== null || currentAdmittedAgent())
+          ? "poll"
+          : requestedTransport;
       const since = options.since === undefined ? undefined : String(options.since);
       if (options.fromNow && options.since !== undefined) {
         throw new Error("Use either --from-now or --since, not both.");
@@ -4865,14 +5414,15 @@ export function registerSessionCommand(program) {
       const ac = new AbortController();
       const onSigint = () => ac.abort();
       process.on("SIGINT", onSigint);
-      const durablePresenceEnabled = options.presence !== false;
-      const publishPresence = durablePresenceEnabled && canPublishListenerPresence(agentId);
+      const remotePresenceEnabled = options.presence !== false;
+      const publishPresence = remotePresenceEnabled && canPublishListenerPresence(agentId);
       const presenceIntervalMs = Math.max(1, presenceIntervalSeconds) * 1000;
       const effectivePresenceKeepaliveSeconds =
         Math.max(presenceIntervalSeconds, presenceKeepaliveSeconds, intervalSeconds, 1);
       const presenceKeepaliveMs = effectivePresenceKeepaliveSeconds * 1000;
       let lastPresenceHeartbeatMs = 0;
       let lastPresenceHeartbeatFingerprint = "";
+      let nextPresenceAttemptMs = 0;
 
       // Periodic in-session success reminders (ack, claim work, reply
       // in-thread). Long-running interactive listeners only — skipped under
@@ -4920,10 +5470,10 @@ export function registerSessionCommand(program) {
             `Listening to session ${normalizedSessionId} as ${agentId}; transport=${listenTransport} idle=${intervalSeconds}s active=${activeIntervalSeconds}s/${activeWindowSeconds}s. Press Ctrl+C to stop.`,
           ),
         );
-        if (!durablePresenceEnabled) {
+        if (!remotePresenceEnabled) {
           console.log(
             pc.gray(
-              "Remote listener presence is disabled; no durable lifecycle events will be written.",
+              "Remote listener presence is disabled; no liveness writes will be made.",
             ),
           );
         } else if (!publishPresence) {
@@ -4974,21 +5524,17 @@ export function registerSessionCommand(program) {
               console.log(pc.yellow(formatListenerCatchupNotice(catchup)));
             }
           },
-          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;
-              }
+          onControl: async (control) => {
+            const controlType = normalizeString(
+              control?.type || control?.action || control?.event,
+            ).toLowerCase();
+            if (!["stop", "listener_stop"].includes(controlType)) return;
+            if (emitFormat !== "ndjson") {
+              console.log(pc.yellow(`Listener stop requested for ${agentId}; exiting.`));
             }
+            ac.abort();
+          },
+          onEvent: async (event) => {
             if (emitFormat === "ndjson") {
               console.log(JSON.stringify(event));
             } else {
@@ -5054,13 +5600,17 @@ export function registerSessionCommand(program) {
             }
             if (!publishPresence) return;
             const lifecycleType = normalizeString(lifecycle?.type);
+            const presenceAttemptMs = Date.now();
+            if (lifecycleType !== "stopped" && presenceAttemptMs < nextPresenceAttemptMs) {
+              return;
+            }
             const publishLifecycle = {
               ...lifecycle,
               presenceIntervalSeconds,
               presenceKeepaliveSeconds: effectivePresenceKeepaliveSeconds,
             };
             if (lifecycleType === "heartbeat") {
-              const nowMs = Date.now();
+              const nowMs = presenceAttemptMs;
               const heartbeatDecision = shouldPublishListenerPresenceHeartbeat({
                 lifecycle: publishLifecycle,
                 nowMs,
@@ -5075,7 +5625,7 @@ export function registerSessionCommand(program) {
               lastPresenceHeartbeatFingerprint = heartbeatDecision.fingerprint;
               lastPresenceHeartbeatMs = nowMs;
             }
-            await publishListenerPresenceEvent({
+            const presenceResult = await publishListenerPresenceEvent({
               sessionId: normalizedSessionId,
               targetPath,
               agentId,
@@ -5086,6 +5636,15 @@ export function registerSessionCommand(program) {
               listenerId,
               lifecycle: publishLifecycle,
             });
+            if (presenceResult?.ok) {
+              nextPresenceAttemptMs = 0;
+              return;
+            }
+            const retryAfterMs = Math.max(
+              presenceIntervalMs,
+              Number(presenceResult?.retryAfterMs) || 0,
+            );
+            nextPresenceAttemptMs = presenceAttemptMs + retryAfterMs;
           },
         });
       } finally {
@@ -5103,7 +5662,7 @@ export function registerSessionCommand(program) {
           }).catch(() => {});
         }
       }
-    });
+    }));
 
   session
     .command("daemon [sessionId]")
@@ -5565,6 +6124,8 @@ export function registerSessionCommand(program) {
       let hydration = null;
       let remoteTail = null;
       let remoteAppend = null;
+      let listenerPresence = null;
+      let readCursor = null;
       if (options.remote) {
         hydration = await hydrateSessionFromRemote({
           sessionId: normalizedSessionId,
@@ -5592,12 +6153,27 @@ export function registerSessionCommand(program) {
           remoteAppend = await appendMissingRemoteEvents(normalizedSessionId, remoteTail.events, {
             targetPath,
           });
+          readCursor = recordSessionReadCursor(normalizedSessionId, remoteTail.events, {
+            targetPath,
+            agentId,
+            enabled: true,
+          });
         }
+        listenerPresence = await fetchSessionListeners(normalizedSessionId, {
+          targetPath,
+        }).catch((error) => ({
+          ok: false,
+          authoritative: false,
+          presenceStatus: "degraded",
+          reason: normalizeString(error?.message) || "presence_read_failed",
+          listeners: [],
+        }));
       }
       const current = await buildSessionRecap(normalizedSessionId, {
         forAgentId: agentId,
         maxEvents,
         targetPath,
+        listenerPresence,
       });
       const payload = {
         command: "session recap now",
@@ -5622,6 +6198,8 @@ export function registerSessionCommand(program) {
                   }
                 : null,
               appendedTail: remoteAppend,
+              listenerPresence,
+              readCursor,
             }
           : null,
       };
@@ -5656,7 +6234,7 @@ export function registerSessionCommand(program) {
     .option("--include-control-events", "Include listener lifecycle/control-plane events in transcript output")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
-    .action(async (sessionId, options, command) => {
+    .action(asAdmittedAgent(sessionReadAgent, async (sessionId, options, command) => {
       const normalizedSessionId = normalizeString(sessionId);
       if (!normalizedSessionId) {
         throw new Error("session id is required.");
@@ -5841,11 +6419,10 @@ export function registerSessionCommand(program) {
           ? filterSessionActionEventsForTranscriptWindow(visibleActionEvents, transcriptEvents)
           : visibleActionEvents;
         const events = mergeSessionActionEvents(transcriptEvents, actionEvents).slice(-tail);
-        const autoView = recordSessionReadViews(normalizedSessionId, events, {
+        const autoView = recordSessionReadCursor(normalizedSessionId, events, {
           targetPath,
           agentId: readAgentId,
           enabled: Boolean(options.remote && options.view !== false),
-          maxTargets: process.env.SENTINELAYER_SESSION_READ_VIEW_MAX_TARGETS || 50,
           timeoutMs: process.env.SENTINELAYER_SESSION_READ_VIEW_TIMEOUT_MS || SESSION_READ_AUTO_VIEW_TIMEOUT_MS,
         });
         const remoteVerified = Boolean(
@@ -6001,7 +6578,7 @@ export function registerSessionCommand(program) {
           console.log(formatEventLine(event));
         }
       }
-    });
+    }));
 
   session
     .command("search <sessionId> <query>")
@@ -6054,6 +6631,66 @@ export function registerSessionCommand(program) {
       }
     });
 
+  session
+    .command("recall <need>")
+    .description(
+      "Hydrate a session by RETRIEVAL, not full-tail replay: return the top-K relevant memories (dense int8 exact-scan + BM25 + RRF + graph diffusion + ACT-R) each with a one-line provenance path (ENGRAM §1)",
+    )
+    .requiredOption("--session <id>", "Session id to recall from")
+    .option("--role <role>", "Optional role lens folded into the query")
+    .option("--k <n>", "Number of memories to return (default 12, max 50)", "12")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--no-remote", "Skip remote hydrate; recall over the local mirror only")
+    .option("--include-control-events", "Index control-plane events as memories too")
+    .option("--json", "Emit machine-readable output")
+    .action(async (need, options, command) => {
+      const normalizedNeed = normalizeString(need);
+      if (normalizedNeed.length < 2) {
+        throw new Error("need must be at least 2 characters.");
+      }
+      const normalizedSessionId = normalizeString(options.session);
+      if (!normalizedSessionId) {
+        throw new Error("--session <id> is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const k = Math.min(50, parsePositiveInteger(options.k, "k", 12));
+      const emitJson = shouldEmitJson(options, command);
+
+      const result = await runSessionRecall({
+        sessionId: normalizedSessionId,
+        need: normalizedNeed,
+        targetPath,
+        k,
+        role: normalizeString(options.role),
+        remote: options.remote !== false,
+        includeControlEvents: Boolean(options.includeControlEvents),
+      });
+
+      if (emitJson) {
+        console.log(JSON.stringify({ command: "session recall", targetPath, ...result }, null, 2));
+        return;
+      }
+      if (!result.ok) {
+        throw new Error(`Session recall failed (${result.reason || "unknown"}).`);
+      }
+      if (result.backfill && result.backfill.warning) {
+        console.log(pc.yellow(result.backfill.warning));
+      }
+      console.log(
+        pc.gray(
+          `Recalled top ${result.results.length} of ${result.meta.observationCount} memories · pool ${result.poolSize} · ~${result.tokenCut.reductionRatio}x fewer tokens than full replay (${result.tokenCut.recallPackTokens} vs ${result.tokenCut.fullReplayTokens}).`,
+        ),
+      );
+      result.results.forEach((item, index) => {
+        const sequence = item.sequenceId ? `#${item.sequenceId}` : "";
+        console.log(`${String(index + 1).padStart(2)}. ${sequence} ${item.agentId} ${item.kind} (score ${item.score})`);
+        if (item.snippet) {
+          console.log(`    ${item.snippet}`);
+        }
+        console.log(pc.gray(`    why: ${item.provenance}`));
+      });
+    });
+
   session
     .command("sync <sessionId>")
     .description(
@@ -6150,6 +6787,147 @@ export function registerSessionCommand(program) {
       }
     });
 
+  // ---------------------------------------------------------------- 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");
+
+  // 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
+  // live admission in scope; without it, the request would go out on the human token and
+  // claim as the PERSON while this command reported the agent. Refused before any request.
+  async function ticketIdentity(sessionId, options, targetPath) {
+    const identity = await resolveSessionSayIdentity({ sessionId, agentId: options.agent, targetPath });
+    const agent = normalizeString(identity.agentId);
+    if (!agent || agent === "cli-user") return "human";
+    const admitted = currentAdmittedAgent();
+    if (!admitted || admitted.sessionId !== sessionId || admitted.agentId !== agent) {
+      throw new Error(
+        `Agent "${agent}" has no live admission in this room. Ticket work is attributed by the credential, so ` +
+          `without one this would act as you, not as "${agent}". Admit it first: ` +
+          `sl session join ${sessionId} --agent ${agent} --goal "<what it is here to do>"`
+      );
+    }
+    return agent;
+  }
+
+  function ticketOutput(options, command, payload, line) {
+    if (shouldEmitJson(options, command)) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+    console.log(line);
+  }
+
+  ticket
+    .command("list <sessionId>")
+    .description("List the room's tickets (--available: only those claimable now)")
+    .option("--available", "Only tickets that can be claimed now (never blocked work)")
+    .option("--agent <id>", "Agent id reading the backlog (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 targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const result = await listTickets(normalizeString(sessionId), { targetPath, available: Boolean(options.available) });
+      const lines = result.items.map((t) => {
+        const holder = t.lease ? ` · ${t.lease.live ? "leased by" : "lease EXPIRED, was"} ${t.lease.holder}` : "";
+        const done = t.completion && !t.completion.verified ? " (manual, unverified)" : "";
+        return `${t.id}  ${t.status}${done}  v${t.version}  ${t.title}${holder}`;
+      });
+      ticketOutput(options, command, { command: "session ticket list", ...result }, lines.join("\n") || "No tickets.");
+    });
+
+  ticket
+    .command("claim <sessionId> <ticketId>")
+    .description("Claim a ticket: take its fenced lease")
+    .option("--expected-version <n>", "Refuse if the ticket has changed since this version")
+    .option("--agent <id>", "Agent id claiming the ticket (defaults to the joined session agent)")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, ticketId, options, command) => {
+      const sid = normalizeString(sessionId);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const identity = await ticketIdentity(sid, options, targetPath);
+      const expectedVersion =
+        options.expectedVersion === undefined ? null : parsePositiveInteger(options.expectedVersion, "expected-version", 1);
+      const result = await claimTicket(sid, normalizeString(ticketId), { identity, expectedVersion, targetPath });
+      ticketOutput(options, command, { command: "session ticket claim", identity, ...result },
+        `Claimed ${ticketId} (fence ${result.lease.fence}, until ${result.lease.expiresAt}).`);
+    });
+
+  ticket
+    .command("renew <sessionId> <ticketId>")
+    .description("Renew the lease this identity holds on a ticket")
+    .option("--agent <id>", "Agent id holding the lease (defaults to the joined session agent)")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, ticketId, options, command) => {
+      const sid = normalizeString(sessionId);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const identity = await ticketIdentity(sid, options, targetPath);
+      const result = await renewTicketLease(sid, normalizeString(ticketId), { identity, targetPath });
+      ticketOutput(options, command, { command: "session ticket renew", identity, ...result },
+        `Renewed ${ticketId} until ${result.lease.expiresAt}.`);
+    });
+
+  ticket
+    .command("release <sessionId> <ticketId>")
+    .description("Give a ticket back: it returns to open for the next claimant")
+    .option("--reason <text>", "Why it is being released")
+    .option("--agent <id>", "Agent id holding the lease (defaults to the joined session agent)")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, ticketId, options, command) => {
+      const sid = normalizeString(sessionId);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const identity = await ticketIdentity(sid, options, targetPath);
+      const result = await releaseTicketLease(sid, normalizeString(ticketId), {
+        identity, targetPath, reason: normalizeString(options.reason) || null,
+      });
+      ticketOutput(options, command, { command: "session ticket release", identity, ...result }, `Released ${ticketId}.`);
+    });
+
+  ticket
+    .command("submit <sessionId> <ticketId>")
+    .description("Submit the work for review (in_review). Completion needs verification; this is not done.")
+    .option("--sha <sha>", "The implementation commit")
+    .option("--evidence-file <path>", "JSON array of re-checkable evidence claims")
+    .option("--agent <id>", "Agent id holding the lease (defaults to the joined session agent)")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, ticketId, options, command) => {
+      const sid = normalizeString(sessionId);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const identity = await ticketIdentity(sid, options, targetPath);
+      let evidence = [];
+      if (options.evidenceFile) {
+        evidence = JSON.parse(await fsp.readFile(path.resolve(targetPath, String(options.evidenceFile)), "utf8"));
+        if (!Array.isArray(evidence)) throw new Error("--evidence-file must contain a JSON array.");
+      }
+      const result = await submitTicket(sid, normalizeString(ticketId), {
+        identity, targetPath, implementationSha: normalizeString(options.sha) || null, evidence,
+      });
+      ticketOutput(options, command, { command: "session ticket submit", identity, ...result },
+        `Submitted ${ticketId} for review.`);
+    });
+
+  ticket
+    .command("events <sessionId>")
+    .description("The room's ticket events after a cursor, in commit order")
+    .option("--after <cursor>", "Only events after this cursor", "0")
+    .option("--agent <id>", "Agent id reading the feed (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 targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const after = Number.parseInt(String(options.after ?? "0"), 10) || 0;
+      const result = await ticketEvents(normalizeString(sessionId), { after, targetPath });
+      const lines = (result.events || []).map((e) => `#${e.cursor} ${e.kind} ${e.ticketId} v${e.ticketVersion} by ${e.actorId}`);
+      ticketOutput(options, command, { command: "session ticket events", ...result }, lines.join("\n") || "No new ticket events.");
+    });
+
   const checkpoint = session
     .command("checkpoint")
     .description("List, show, create, and generate durable session checkpoints");
@@ -6422,7 +7200,14 @@ export function registerSessionCommand(program) {
         throw new Error(`Session '${normalizedSessionId}' was not found.`);
       }
 
-      const [agents, runtimeRuns, leases, fileLocks, activeTasks, recentEvents] = await Promise.all([
+      const [
+        agents,
+        runtimeRuns,
+        leases,
+        fileLeaseStatus,
+        activeTasks,
+        recentEvents,
+      ] = await Promise.all([
         listAgents(normalizedSessionId, {
           targetPath,
           includeInactive: false,
@@ -6441,10 +7226,22 @@ export function registerSessionCommand(program) {
           includeExpired: true,
           limit: 100,
         }),
-        listFileLocks(normalizedSessionId, {
-          targetPath,
-          emitExpiredEvents: false,
-        }),
+        listFileLocks(normalizedSessionId, { targetPath })
+          .then((activeFileLocks) => ({
+            ok: true,
+            authoritative: true,
+            activeFileLocks,
+            error: null,
+          }))
+          .catch((error) => ({
+            ok: false,
+            authoritative: false,
+            activeFileLocks: [],
+            error: {
+              code: normalizeString(error?.code) || "FILE_LEASE_LIST_FAILED",
+              message: safeFileLeaseErrorMessage(error),
+            },
+          })),
         listSessionTasks(normalizedSessionId, {
           targetPath,
           statuses: ["PENDING", "ACCEPTED"],
@@ -6455,42 +7252,51 @@ export function registerSessionCommand(program) {
           tail: 10,
         }),
       ]);
+      const fileLocks = fileLeaseStatus.activeFileLocks;
 
       const staleAgents = detectStaleAgents(agents, {});
       const staleAgentIds = new Set(staleAgents.map((agent) => normalizeString(agent.agentId)));
       const activeAgents = agents.filter((agent) => !staleAgentIds.has(normalizeString(agent.agentId)));
-      let listenerRows = summarizeListeners(recentEvents);
+      const materialRecentEvents = filterSessionMaterialEvents(recentEvents);
+      const hiddenControlEventCount = recentEvents.length - materialRecentEvents.length;
+      let listenerRows = [];
       let listenerPresence = {
-        source: "local_recent_events",
-        ok: true,
-        count: listenerRows.length,
-        liveCount: listenerRows.filter((row) => row.status === "active" || row.status === "idle").length,
-        listeners: listenerRows,
+        source: "remote_presence",
+        ok: false,
+        authoritative: false,
+        presenceStatus: "degraded",
+        reason: "presence_unknown",
+        count: 0,
+        liveCount: 0,
+        listeners: [],
       };
       try {
         const remoteListeners = await fetchSessionListeners(normalizedSessionId, {
           targetPath,
-          limit: 200,
-          maxPages: 5,
         });
-        if (remoteListeners?.ok && Array.isArray(remoteListeners.listeners) && remoteListeners.listeners.length > 0) {
+        if (remoteListeners?.ok && Array.isArray(remoteListeners.listeners)) {
           listenerRows = remoteListeners.listeners;
           listenerPresence = {
-            source: "remote_events",
+            source: "remote_presence",
             ok: true,
+            authoritative: true,
+            presenceStatus: remoteListeners.presenceStatus || "ok",
             count: listenerRows.length,
-            liveCount: listenerRows.filter((row) => row.status === "active" || row.status === "idle").length,
-            pageCount: Number(remoteListeners.pageCount || 0),
-            scannedEventCount: Number(remoteListeners.scannedEventCount || 0),
-            listenerEventCount: Number(remoteListeners.listenerEventCount || 0),
-            partial: Boolean(remoteListeners.partial),
+            liveCount: listenerRows.filter(
+              (row) => row.status === "present" || row.status === "active" || row.status === "idle",
+            ).length,
             listeners: listenerRows,
           };
         } else if (remoteListeners && remoteListeners.ok === false) {
-          listenerPresence.remoteReason = normalizeString(remoteListeners.reason) || "remote_unavailable";
+          listenerPresence = {
+            ...listenerPresence,
+            presenceStatus: remoteListeners.presenceStatus || "degraded",
+            reason: normalizeString(remoteListeners.reason) || "remote_unavailable",
+            retryAfterMs: remoteListeners.retryAfterMs || null,
+          };
         }
       } catch (error) {
-        listenerPresence.remoteReason = normalizeString(error?.message) || "remote_unavailable";
+        listenerPresence.reason = normalizeString(error?.message) || "remote_unavailable";
       }
       const liveListenerCount = listenerPresence.liveCount;
       const payload = {
@@ -6505,8 +7311,14 @@ export function registerSessionCommand(program) {
         runtimeRuns,
         activeLeases: leases.assignments,
         activeFileLocks: fileLocks,
+        fileLeaseAuthority: {
+          ok: fileLeaseStatus.ok,
+          authoritative: fileLeaseStatus.authoritative,
+          error: fileLeaseStatus.error,
+        },
         activeTasks: activeTasks.tasks,
-        recentEvents,
+        recentEvents: materialRecentEvents,
+        hiddenControlEventCount,
       };
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
@@ -6514,12 +7326,15 @@ export function registerSessionCommand(program) {
       }
 
       console.log(pc.bold(`Session ${normalizedSessionId}`));
+      const listenerText = listenerPresence.authoritative
+        ? `${liveListenerCount}/${listenerRows.length}`
+        : `unknown(${listenerPresence.presenceStatus || "degraded"})`;
       console.log(
         pc.gray(
-          `status=${sessionPayload.status} active=${activeAgents.length} registered=${agents.length} stale=${staleAgents.length} listeners=${liveListenerCount}/${listenerRows.length} runs=${runtimeRuns.length} leases=${leases.assignments.length} locks=${fileLocks.length} tasks=${activeTasks.tasks.length}`
+          `status=${sessionPayload.status} active=${activeAgents.length} registered=${agents.length} stale=${staleAgents.length} listeners=${listenerText} runs=${runtimeRuns.length} leases=${leases.assignments.length} locks=${fileLocks.length} tasks=${activeTasks.tasks.length}`
         )
       );
-      for (const event of recentEvents) {
+      for (const event of materialRecentEvents) {
         console.log(formatEventLine(event));
       }
     });