sentinelayer-cli 0.9.0 → 0.9.3

package/src/commands/session.js

@@ -29,7 +29,7 @@ import {
   registerAgent,
   unregisterAgent,
 } from "../session/agent-registry.js";
-import { stopSenti } from "../session/daemon.js";
+import { startSenti, stopSenti } from "../session/daemon.js";
 import { listRuntimeRuns } from "../session/runtime-bridge.js";
 import {
   listFileLocks,
@@ -44,22 +44,32 @@ import {
   createSession,
   DEFAULT_TTL_SECONDS,
   getSession,
+  isSessionCacheExpired,
   listActiveSessions,
   listAllSessions,
   recordSessionProvisionedIdentities,
+  refreshSessionCacheForRemoteActivity,
   updateSessionTitle,
 } from "../session/store.js";
 import { appendToStream, readStream, tailStream } from "../session/stream.js";
+import {
+  addSessionEventIdentityKeys,
+  dedupeSessionEvents,
+  sessionEventHasKnownIdentity,
+} from "../session/event-identity.js";
 import { readSessionPreview } from "../session/preview.js";
 import {
   listSessionsFromApi,
   probeSessionAccess,
+  pollSessionEventsBefore,
+  syncSessionEventToApi,
   syncSessionMetadataToApi,
 } from "../session/sync.js";
 import { hydrateSessionFromRemote } from "../session/remote-hydrate.js";
 import { mergeLiveSources } from "../session/live-source.js";
 import { listenSessionEvents } from "../session/listener.js";
 import { deriveSessionTitle } from "../session/senti-naming.js";
+import { pushSessionTitleToApi } from "../session/title-sync.js";
 import {
   buildDashboardUrl,
   buildTemplateLaunchPlan,
@@ -111,6 +121,10 @@ function remoteSessionLookupDisabled() {
   return String(process.env.SENTINELAYER_SKIP_REMOTE_SYNC || "").trim() === "1";
 }
 
+function sentiAutostartDisabled() {
+  return String(process.env.SENTINELAYER_SKIP_SENTI_AUTOSTART || "").trim() === "1";
+}
+
 function mergeResumeCandidate(existing, incoming) {
   if (!existing) return incoming;
   const existingActivity = Number(existing._activityMs || 0);
@@ -194,29 +208,190 @@ async function findReusableSessionCandidate({
   return candidates[0] || null;
 }
 
-async function pushSessionTitleToApi(sessionId, title, { targetPath } = {}) {
-  const normalizedTitle = normalizeString(title);
-  if (!normalizedTitle || remoteSessionLookupDisabled()) return;
+// Verify that a session id is reachable for the active user via the API
+// singleton endpoint added in API PR #483 (`GET /api/v1/sessions/{id}`).
+//
+// Carter's complaint: "I can't create a session from the web and still have
+// it available for you guys in CLI" — the historical CLI flow assumed the
+// session was created locally first, so attaching to a web/peer-created
+// session left the agent guessing about access. Singleton GET resolves
+// that with one round-trip and gives us metadata for friendly output.
+//
+// Behaviour contract:
+//   - Returns `{ ok: true, source, session, status }` on success.
+//   - Returns `{ ok: false, reason: "not_found", status: 404 }` when the
+//     session genuinely isn't visible to the caller (404 + list fallback
+//     also empty). Callers should map this to a friendly "not found" exit.
+//   - Returns `{ ok: false, reason: "forbidden", status: 403 }` for explicit
+//     deny (caller is authenticated but not a member).
+//   - On 5xx: retries ONCE, then surfaces `{ ok: false, reason: "api_5xx" }`.
+//   - On 404 from the singleton: falls back to filtering the list endpoint
+//     so users on stale prod servers (pre-#483) aren't blocked. If the list
+//     contains the session id we treat it as success and return that row.
+//   - When `SENTINELAYER_SKIP_REMOTE_SYNC=1` (test bootstrap), short-circuits
+//     to `{ ok: true, source: "skipped", session: null }` so unit tests
+//     can exercise the local materialization path without a real API.
+async function verifyRemoteSession(sessionId, { targetPath } = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return { ok: false, reason: "invalid_session_id" };
+  }
+  if (remoteSessionLookupDisabled()) {
+    return { ok: true, source: "skipped", session: null };
+  }
+  let auth;
   try {
-    const session = await resolveActiveAuthSession({
-      cwd: targetPath,
+    auth = await resolveActiveAuthSession({
+      cwd: targetPath || process.cwd(),
       env: process.env,
       autoRotate: false,
     });
-    if (!session?.token || !session?.apiUrl) return;
-    const apiUrl = String(session.apiUrl).replace(/\/+$/, "");
-    await requestJsonMutation(
-      `${apiUrl}/api/v1/sessions/${encodeURIComponent(sessionId)}/title`,
-      {
-        method: "POST",
-        operationName: "session.set_title",
-        headers: { Authorization: `Bearer ${session.token}` },
-        body: { title: normalizedTitle },
-      },
-    );
   } catch {
-    /* best-effort */
+    return { ok: false, reason: "no_session" };
+  }
+  if (!auth || !auth.token) {
+    return { ok: false, reason: "not_authenticated", status: 401 };
+  }
+  const apiUrl = String(auth.apiUrl || "").replace(/\/+$/, "");
+  if (!apiUrl) {
+    return { ok: false, reason: "no_api_url" };
+  }
+  const endpoint = `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}`;
+  const headers = { Authorization: `Bearer ${auth.token}` };
+  let lastReason = "unknown";
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    let response;
+    try {
+      response = await fetch(endpoint, { method: "GET", headers });
+    } catch (err) {
+      lastReason = normalizeString(err?.message) || "fetch_failed";
+      continue;
+    }
+    if (response && response.ok) {
+      const body = await response.json().catch(() => ({}));
+      const sessionPayload = body && body.session && typeof body.session === "object"
+        ? body.session
+        : body && typeof body === "object"
+          ? body
+          : null;
+      return {
+        ok: true,
+        source: "singleton",
+        session: sessionPayload,
+        status: response.status,
+      };
+    }
+    if (!response) {
+      lastReason = "no_response";
+      continue;
+    }
+    if (response.status === 404) {
+      // Pre-#483 fallback: scan the list endpoint once for the same id.
+      const listResult = await listSessionsFromApi({
+        targetPath,
+        includeArchived: false,
+        limit: 50,
+      }).catch(() => null);
+      if (listResult && listResult.ok) {
+        const found = (listResult.sessions || []).find(
+          (entry) => normalizeString(entry?.sessionId) === normalizedSessionId,
+        );
+        if (found) {
+          return { ok: true, source: "list_fallback", session: found, status: 200 };
+        }
+      }
+      return { ok: false, reason: "not_found", status: 404 };
+    }
+    if (response.status === 403) {
+      return { ok: false, reason: "forbidden", status: 403 };
+    }
+    if (response.status >= 500 && response.status < 600) {
+      lastReason = `api_${response.status}`;
+      continue; // retry once on 5xx
+    }
+    return { ok: false, reason: `api_${response.status}`, status: response.status };
   }
+  return { ok: false, reason: lastReason };
+}
+
+// Render an absolute ISO timestamp as a coarse "Nm ago" / "Nh ago" / "Nd ago"
+// label for human-readable join output. Returns `"never"` for missing input
+// and `"just now"` for sub-minute deltas.
+function formatRelativeAge(isoTimestamp) {
+  const epoch = Date.parse(normalizeString(isoTimestamp));
+  if (!Number.isFinite(epoch)) return "never";
+  const deltaMs = Date.now() - epoch;
+  if (deltaMs < 60_000) return "just now";
+  const minutes = Math.floor(deltaMs / 60_000);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+async function ensureLocalSessionForRemoteCommand(
+  sessionId,
+  { targetPath, title = "", skipRemoteProbe = false, remoteSession = null } = {},
+) {
+  const existing = await getSession(sessionId, { targetPath });
+  if (existing) {
+    if (!isSessionCacheExpired(existing)) {
+      return { materialized: false, refreshed: false, session: existing };
+    }
+    const existingStatus = normalizeString(existing.status).toLowerCase();
+    const locallyClosedByStatus = existingStatus === "expired" || existingStatus === "archived";
+    if (locallyClosedByStatus && !skipRemoteProbe) {
+      throw new Error(
+        `Session '${sessionId}' is ${existingStatus} locally; run \`sl session join ${sessionId}\` to verify remote access before posting.`,
+      );
+    }
+
+    let access = { accessible: Boolean(skipRemoteProbe), reason: "" };
+    if (!skipRemoteProbe) {
+      access = await probeSessionAccess(sessionId, { targetPath }).catch((error) => ({
+        accessible: false,
+        reason: normalizeString(error?.message) || "probe_failed",
+      }));
+    }
+    if (!access?.accessible) {
+      throw new Error(
+        `Session '${sessionId}' is expired locally and remote access failed (${access?.reason || "unknown"}).`,
+      );
+    }
+
+    const refreshed = await refreshSessionCacheForRemoteActivity(sessionId, {
+      targetPath,
+      title,
+      lastInteractionAt:
+        normalizeString(remoteSession?.lastInteractionAt) ||
+        normalizeString(remoteSession?.lastActivityAt) ||
+        normalizeString(remoteSession?.updatedAt) ||
+        normalizeString(remoteSession?.createdAt),
+    });
+    return { materialized: false, refreshed: Boolean(refreshed), session: refreshed || existing };
+  }
+  // `skipRemoteProbe` is set by callers that have already verified the session
+  // via `verifyRemoteSession` (the singleton GET) — re-probing the legacy
+  // `/events?limit=1` endpoint here would be a redundant round-trip and, for
+  // tests that mock only the singleton, would spuriously 404.
+  if (!skipRemoteProbe) {
+    const access = await probeSessionAccess(sessionId, { targetPath }).catch((error) => ({
+      accessible: false,
+      reason: normalizeString(error?.message) || "probe_failed",
+    }));
+    if (!access?.accessible) {
+      throw new Error(
+        `Session '${sessionId}' was not found locally and remote access failed (${access?.reason || "unknown"}).`,
+      );
+    }
+  }
+  const created = await createSession({
+    targetPath,
+    sessionId,
+    title: normalizeString(title) || `remote-${String(sessionId).slice(0, 8)}`,
+  });
+  return { materialized: true, refreshed: false, session: created };
 }
 
 async function ensureWorkspaceSession({
@@ -296,13 +471,16 @@ async function ensureWorkspaceSession({
 
   const effectiveTitle = titleArg || normalizeString(created.title) || fallbackTitle;
   const titleAuto = !titleArg && !resumedCandidate;
+  const pendingTitleSync = Boolean(created.remoteTitleSync?.pending && effectiveTitle);
   const shouldPushTitle = Boolean(
     titleArg ||
       titleAuto ||
+      pendingTitleSync ||
       (resumedCandidate && effectiveTitle && !normalizeString(resumedCandidate.title))
   );
+  let titleSync = null;
   if (shouldPushTitle) {
-    void pushSessionTitleToApi(created.sessionId, effectiveTitle, { targetPath });
+    titleSync = await pushSessionTitleToApi(created.sessionId, effectiveTitle, { targetPath });
   }
 
   return {
@@ -315,6 +493,7 @@ async function ensureWorkspaceSession({
     durationMs: Date.now() - startedAt,
     title: effectiveTitle || null,
     titleAuto,
+    titleSync,
   };
 }
 
@@ -326,6 +505,18 @@ function normalizeAgentId(value, fallbackValue = "cli-user") {
   return normalized || fallbackValue;
 }
 
+// Preserve the literal default identity for `session say`. This command is
+// often used by agents as a low-friction relay; silently rewriting the default
+// `cli-user` to the authenticated human makes a forgotten --agent flag look
+// like the workspace owner authored the message.
+export function resolveSessionSayAgentId(value) {
+  return normalizeAgentId(value, "cli-user");
+}
+
+async function defaultAgentId(value, _targetPath) {
+  return resolveSessionSayAgentId(value);
+}
+
 async function runWithConcurrency(items = [], concurrency = 1, worker = async () => null) {
   const normalizedItems = Array.isArray(items) ? items : [];
   const normalizedConcurrency = Math.max(
@@ -579,6 +770,7 @@ export function registerSessionCommand(program) {
         resumed,
         title: effectiveTitle || null,
         titleAuto: Boolean(ensured.titleAuto),
+        titleSync: ensured.titleSync || undefined,
       };
 
       // Best-effort admin visibility sync. Session creation remains local-first.
@@ -594,6 +786,20 @@ export function registerSessionCommand(program) {
         codebaseContext: created.codebaseContext,
       }).catch(() => {});
 
+      // Auto-start the Senti orchestrator daemon. Without this, every
+      // session ran with `Senti actions: 1` (just the welcome alert)
+      // because nothing kicked the daemon ticking — agents joining
+      // never got greeted, mentions never routed, recaps never fired.
+      // Best-effort + non-blocking: the daemon registers itself in an
+      // in-memory map keyed by (sessionId, targetPath) and tolerates
+      // being started for an already-active session (returns the
+      // existing handle). If the daemon fails to start (unauth env,
+      // missing model proxy), the session keeps working — Senti just
+      // stays quiet, same as before this change.
+      if (!sentiAutostartDisabled()) {
+        void startSenti(created.sessionId, { targetPath }).catch(() => {});
+      }
+
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
         return;
@@ -653,6 +859,10 @@ export function registerSessionCommand(program) {
     .command("ensure")
     .description("Join or create the canonical session for this workspace and emit JSON")
     .option("--path <path>", "Workspace path for the session", ".")
+    .option(
+      "--session <id>",
+      "Attach to an explicit remote-created session id (verifies + materializes local state, like `session join`).",
+    )
     .option("--title <title>", "Title applied if a new or unnamed resumed session needs one")
     .option(
       "--ttl-seconds <seconds>",
@@ -686,6 +896,56 @@ export function registerSessionCommand(program) {
         "reuse-window-seconds",
         3600,
       );
+
+      // --session <id> short-circuit: behave like `session join`. This is the
+      // path Carter cared about — "create on web, share id, attach in CLI".
+      // We verify the session is reachable, materialize a minimal local
+      // NDJSON if missing, and emit the same `{sessionId, title, resumed}`
+      // contract callers already consume from `ensure`.
+      const explicitSessionId = normalizeString(options.session);
+      if (explicitSessionId) {
+        const verification = await verifyRemoteSession(explicitSessionId, { targetPath });
+        if (!verification.ok) {
+          if (verification.status === 404 || verification.reason === "not_found") {
+            throw new Error(
+              `Session not found, archived, or not accessible to your account. (id=${explicitSessionId})`,
+            );
+          }
+          if (verification.status === 403 || verification.reason === "forbidden") {
+            throw new Error(
+              `Session '${explicitSessionId}' exists but your account is not a member.`,
+            );
+          }
+          if (verification.reason === "not_authenticated") {
+            throw new Error(`Not authenticated. Run \`${authLoginHint()}\` first.`);
+          }
+          throw new Error(
+            `Failed to verify session '${explicitSessionId}' (${verification.reason || "unknown"}). Try again in a moment.`,
+          );
+        }
+        const remoteSession = verification.session || {};
+        const localSession = await ensureLocalSessionForRemoteCommand(explicitSessionId, {
+          targetPath,
+          title: normalizeString(remoteSession.title),
+          skipRemoteProbe: true,
+          remoteSession,
+        });
+        const payload = {
+          command: "session ensure",
+          targetPath,
+          sessionId: explicitSessionId,
+          title: normalizeString(remoteSession.title) || localSession?.session?.title || null,
+          resumed: true,
+          attached: true,
+          materializedLocalSession: localSession.materialized,
+          refreshedLocalSession: Boolean(localSession.refreshed),
+          verificationSource: verification.source,
+          dashboardUrl: buildDashboardUrl(explicitSessionId),
+        };
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
       const ensured = await ensureWorkspaceSession({
         targetPath,
         ttlSeconds,
@@ -701,6 +961,7 @@ export function registerSessionCommand(program) {
         title: ensured.title || null,
         resumed: Boolean(ensured.resumedCandidate),
         dashboardUrl: buildDashboardUrl(ensured.created.sessionId),
+        titleSync: ensured.titleSync || undefined,
       };
       console.log(JSON.stringify(payload, null, 2));
     });
@@ -832,8 +1093,14 @@ export function registerSessionCommand(program) {
 
   session
     .command("join <sessionId>")
-    .description("Join an active session")
-    .option("--name <name>", "Agent display name")
+    .description(
+      "Attach to a remote-created session for posting and listening, materializing minimal local state on demand.",
+    )
+    .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.",
+    )
     .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", ".")
@@ -844,27 +1111,106 @@ export function registerSessionCommand(program) {
         throw new Error("session id is required.");
       }
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+
+      // PR #483 contract: verify the session exists and the caller has access
+      // BEFORE materializing local cache state. Without this we'd silently
+      // create a phantom local NDJSON for a session that's archived or owned
+      // by another tenant — which is the bug Carter reported when asking for
+      // a clean "share an id from web → join in CLI" flow.
+      const verification = await verifyRemoteSession(normalizedSessionId, { targetPath });
+      if (!verification.ok) {
+        if (verification.status === 404 || verification.reason === "not_found") {
+          throw new Error(
+            `Session not found, archived, or not accessible to your account. (id=${normalizedSessionId})`,
+          );
+        }
+        if (verification.status === 403 || verification.reason === "forbidden") {
+          throw new Error(
+            `Session '${normalizedSessionId}' exists but your account is not a member.`,
+          );
+        }
+        if (verification.reason === "not_authenticated") {
+          throw new Error(`Not authenticated. Run \`${authLoginHint()}\` first.`);
+        }
+        throw new Error(
+          `Failed to verify session '${normalizedSessionId}' (${verification.reason || "unknown"}). Try again in a moment.`,
+        );
+      }
+
+      const remoteSession = verification.session || {};
+      const localSession = await ensureLocalSessionForRemoteCommand(normalizedSessionId, {
+        targetPath,
+        title: normalizeString(remoteSession.title),
+        skipRemoteProbe: true,
+        remoteSession,
+      });
+
+      const explicitAgent = normalizeString(options.agent);
+      const agentSeed = explicitAgent || normalizeString(options.name);
+      const resolvedAgentId = await defaultAgentId(agentSeed, targetPath);
+      const role = normalizeString(options.role) || "coder";
+      const model = normalizeString(options.model) || "cli";
+
+      // `registerAgent` already writes the canonical `agent_join` event to the
+      // local NDJSON and best-effort relays it to /events via appendToStream
+      // → syncSessionEventToApi. That gives us the exact `post-agent` parity
+      // the spec calls for when `--agent <granted>` is provided. We don't
+      // double-emit; we just record whether the explicit agent path was used
+      // so the JSON output can advertise it to callers (and tests).
       const joined = await registerAgent(normalizedSessionId, {
         targetPath,
-        agentId: normalizeAgentId(options.name, "cli-user"),
-        model: normalizeString(options.model) || "cli",
-        role: options.role || "coder",
+        agentId: resolvedAgentId,
+        model,
+        role,
       });
+      const agentJoinRelayed =
+        Boolean(explicitAgent) &&
+        Boolean(resolvedAgentId) &&
+        resolvedAgentId !== "cli-user" &&
+        resolvedAgentId !== "unknown" &&
+        !resolvedAgentId.startsWith("human-");
+
+      const eventCount = Number(remoteSession.eventCount ?? remoteSession.events ?? 0);
+      const agents = Array.isArray(remoteSession.agents) ? remoteSession.agents : [];
+      const agentCount = Number(remoteSession.agentCount ?? agents.length ?? 0);
+      const lastActivityIso =
+        normalizeString(remoteSession.lastInteractionAt) ||
+        normalizeString(remoteSession.lastActivityAt) ||
+        normalizeString(remoteSession.updatedAt) ||
+        normalizeString(remoteSession.createdAt) ||
+        "";
+      const remoteTitle = normalizeString(remoteSession.title);
+
       const payload = {
         command: "session join",
+        joined: true,
         targetPath,
         sessionId: normalizedSessionId,
+        title: remoteTitle || null,
         agentId: joined.agentId,
         role: joined.role,
         model: joined.model,
         status: joined.status,
         joinedAt: joined.joinedAt,
+        materializedLocalSession: localSession.materialized,
+        refreshedLocalSession: Boolean(localSession.refreshed),
+        verificationSource: verification.source,
+        eventCount: Number.isFinite(eventCount) ? eventCount : 0,
+        agentCount: Number.isFinite(agentCount) ? agentCount : 0,
+        lastActivityAt: lastActivityIso || null,
+        agentJoinRelayed,
       };
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
         return;
       }
-      console.log(pc.bold(`Joined session ${normalizedSessionId}`));
+      const titleLabel = remoteTitle ? `"${remoteTitle}"` : "(untitled)";
+      const ageLabel = lastActivityIso ? formatRelativeAge(lastActivityIso) : "never";
+      console.log(
+        pc.bold(
+          `Joined session ${titleLabel} (${normalizedSessionId}) — ${payload.eventCount} events, ${payload.agentCount} agents, last activity ${ageLabel}`,
+        ),
+      );
       console.log(pc.gray(`agent=${joined.agentId} role=${joined.role} model=${joined.model}`));
     });
 
@@ -885,7 +1231,10 @@ export function registerSessionCommand(program) {
         throw new Error("message is required.");
       }
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
-      const agentId = normalizeAgentId(options.agent, "cli-user");
+      const agentId = await defaultAgentId(options.agent, targetPath);
+      const localSession = await ensureLocalSessionForRemoteCommand(normalizedSessionId, {
+        targetPath,
+      });
       const to = normalizeString(options.to);
       const eventPayload = {
         message: normalizedMessage,
@@ -894,12 +1243,29 @@ export function registerSessionCommand(program) {
       if (to) {
         eventPayload.to = to;
       }
+      const clientMessageId = `cli-${randomUUID()}`;
       const event = createAgentEvent({
         event: "session_message",
         agentId,
         sessionId: normalizedSessionId,
         payload: eventPayload,
       });
+      event.eventId = clientMessageId;
+      event.idempotencyToken = clientMessageId;
+      let remoteSync = null;
+      if (localSession.materialized) {
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+          remoteSync = await syncSessionEventToApi(normalizedSessionId, event, {
+            targetPath,
+          });
+          if (remoteSync?.synced) break;
+        }
+        if (!remoteSync?.synced) {
+          throw new Error(
+            `Remote send failed (${remoteSync?.reason || "unknown"}); local cache was not updated.`,
+          );
+        }
+      }
       const persisted = await appendToStream(normalizedSessionId, event, {
         targetPath,
       });
@@ -909,6 +1275,97 @@ export function registerSessionCommand(program) {
         sessionId: normalizedSessionId,
         agentId,
         event: persisted,
+        materializedLocalSession: localSession.materialized,
+        refreshedLocalSession: Boolean(localSession.refreshed),
+        remoteSync: remoteSync || undefined,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(formatEventLine(persisted));
+    });
+
+  session
+    .command("post-agent <sessionId> <message>")
+    .description("Post an authenticated agent message through the canonical session event API")
+    .requiredOption("--agent <id>", "Granted agent id to post as")
+    .option("--model <model>", "Agent model/provider hint", "cli")
+    .option("--display-name <name>", "Human-readable agent display name")
+    .option("--role <role>", "Agent role metadata: coder, reviewer, tester, observer", "coder")
+    .option("--to <agent>", "Direct the message to a specific agent id")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, message, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const normalizedMessage = normalizeString(message);
+      if (!normalizedMessage) {
+        throw new Error("message is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const agentId = normalizeAgentId(options.agent, "");
+      if (!agentId || agentId === "cli-user" || agentId === "unknown" || agentId.startsWith("human-")) {
+        throw new Error("post-agent requires a granted non-human agent id.");
+      }
+      const localSession = await ensureLocalSessionForRemoteCommand(normalizedSessionId, {
+        targetPath,
+      });
+      const to = normalizeString(options.to);
+      const eventPayload = {
+        message: normalizedMessage,
+        channel: "session",
+        source: "agent",
+        clientKind: "cli",
+      };
+      if (to) {
+        eventPayload.to = to;
+      }
+      const agent = {
+        id: agentId,
+        model: normalizeString(options.model) || "cli",
+        displayName: normalizeString(options.displayName) || undefined,
+        role: normalizeString(options.role) || "coder",
+        clientKind: "cli",
+      };
+      const clientMessageId = `cli-agent-${randomUUID()}`;
+      const event = createAgentEvent({
+        event: "session_message",
+        agent,
+        sessionId: normalizedSessionId,
+        payload: eventPayload,
+      });
+      event.eventId = clientMessageId;
+      event.idempotencyToken = clientMessageId;
+
+      let remoteSync = null;
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        remoteSync = await syncSessionEventToApi(normalizedSessionId, event, {
+          targetPath,
+        });
+        if (remoteSync?.synced) break;
+      }
+      if (!remoteSync?.synced) {
+        throw new Error(
+          `Agent post failed (${remoteSync?.reason || "unknown"}). Ensure this user has an active grant for '${agentId}'.`,
+        );
+      }
+
+      const persisted = await appendToStream(normalizedSessionId, event, {
+        targetPath,
+        syncRemote: false,
+      });
+      const payload = {
+        command: "session post-agent",
+        targetPath,
+        sessionId: normalizedSessionId,
+        agentId,
+        event: persisted,
+        materializedLocalSession: localSession.materialized,
+        refreshedLocalSession: Boolean(localSession.refreshed),
+        remoteSync,
       };
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
@@ -926,7 +1383,17 @@ export function registerSessionCommand(program) {
       "Agent id to receive messages for",
       process.env.SENTINELAYER_AGENT_ID || "cli-user",
     )
-    .option("--interval <seconds>", "Polling interval in seconds (default 60)", "60")
+    .option("--interval <seconds>", "Idle polling interval in seconds (default 60)", "60")
+    .option(
+      "--active-interval <seconds>",
+      "Polling interval after recent human activity (default 5)",
+      "5",
+    )
+    .option(
+      "--active-window <seconds>",
+      "Seconds after a human message to keep the active interval (default 300)",
+      "300",
+    )
     .option("--emit <format>", "Output format: ndjson or text", "ndjson")
     .option("--limit <n>", "Maximum events to request per poll (default 200)", "200")
     .option("--path <path>", "Workspace path for the session", ".")
@@ -938,6 +1405,12 @@ export function registerSessionCommand(program) {
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
       const agentId = normalizeAgentId(options.agent, "cli-user");
       const intervalSeconds = parsePositiveInteger(options.interval, "interval", 60);
+      const activeIntervalSeconds = parsePositiveInteger(
+        options.activeInterval,
+        "active-interval",
+        5,
+      );
+      const activeWindowSeconds = parsePositiveInteger(options.activeWindow, "active-window", 300);
       const limit = parsePositiveInteger(options.limit, "limit", 200);
       const emitFormat = normalizeString(options.emit).toLowerCase() || "ndjson";
       if (!["ndjson", "text"].includes(emitFormat)) {
@@ -955,7 +1428,7 @@ export function registerSessionCommand(program) {
       if (emitFormat === "text") {
         console.log(
           pc.gray(
-            `Listening to session ${normalizedSessionId} as ${agentId}; interval=${intervalSeconds}s. Press Ctrl+C to stop.`,
+            `Listening to session ${normalizedSessionId} as ${agentId}; idle=${intervalSeconds}s active=${activeIntervalSeconds}s/${activeWindowSeconds}s. Press Ctrl+C to stop.`,
           ),
         );
       }
@@ -966,6 +1439,8 @@ export function registerSessionCommand(program) {
           targetPath,
           agentId,
           intervalSeconds,
+          activeIntervalSeconds,
+          activeWindowSeconds,
           limit,
           since,
           replay: Boolean(options.replay),
@@ -1029,11 +1504,17 @@ export function registerSessionCommand(program) {
       const emitJson = shouldEmitJson(options, command);
 
       let hydration = null;
+      let remoteTail = null;
       if (options.remote) {
         hydration = await hydrateSessionFromRemote({
           sessionId: normalizedSessionId,
           targetPath,
         });
+        remoteTail = await pollSessionEventsBefore(normalizedSessionId, {
+          targetPath,
+          limit: tail,
+          timeoutMs: 15_000,
+        });
         if (!emitJson) {
           if (hydration.ok) {
             console.log(
@@ -1041,6 +1522,13 @@ export function registerSessionCommand(program) {
                 `Hydrated from remote: relayed=${hydration.relayed} dropped=${hydration.dropped}.`,
               ),
             );
+            if (hydration.eventsBackfillComplete === false) {
+              console.log(
+                pc.yellow(
+                  `Remote backfill still has more pages (${hydration.eventsBackfillReason || "incomplete"}); latest tail was fetched directly.`,
+                ),
+              );
+            }
           } else {
             console.log(
               pc.yellow(
@@ -1052,10 +1540,34 @@ export function registerSessionCommand(program) {
       }
 
       if (!options.follow) {
-        const events = await readStream(normalizedSessionId, {
+        const allEvents = await readStream(normalizedSessionId, {
           targetPath,
-          tail,
+          tail: 0,
         });
+        const displayEvents = [...allEvents];
+        if (remoteTail?.ok && Array.isArray(remoteTail.events) && remoteTail.events.length > 0) {
+          const knownKeys = new Set();
+          for (const event of allEvents) {
+            addSessionEventIdentityKeys(knownKeys, event);
+          }
+          for (const event of remoteTail.events) {
+            if (sessionEventHasKnownIdentity(event, knownKeys)) {
+              continue;
+            }
+            try {
+              const appended = await appendToStream(normalizedSessionId, event, {
+                targetPath,
+                syncRemote: false,
+              });
+              displayEvents.push(appended);
+              addSessionEventIdentityKeys(knownKeys, appended);
+            } catch {
+              displayEvents.push(event);
+              addSessionEventIdentityKeys(knownKeys, event);
+            }
+          }
+        }
+        const events = dedupeSessionEvents(displayEvents).slice(-tail);
         const payload = {
           command: "session read",
           targetPath,
@@ -1063,7 +1575,19 @@ export function registerSessionCommand(program) {
           tail,
           count: events.length,
           events,
-          remote: hydration,
+          remote: hydration
+            ? {
+                ...hydration,
+                tailProbe: remoteTail
+                  ? {
+                      ok: Boolean(remoteTail.ok),
+                      reason: remoteTail.reason || "",
+                      count: Array.isArray(remoteTail.events) ? remoteTail.events.length : 0,
+                      cursor: remoteTail.cursor || null,
+                    }
+                  : null,
+              }
+            : hydration,
         };
         if (emitJson) {
           console.log(JSON.stringify(payload, null, 2));
@@ -1121,10 +1645,15 @@ export function registerSessionCommand(program) {
       if (!emitJson) {
         console.log(pc.gray(`Following session ${normalizedSessionId}... Press Ctrl+C to stop.`));
       }
+      const seenFollowEvents = new Set();
       for await (const event of tailStream(normalizedSessionId, {
         targetPath,
         replayTail: tail,
       })) {
+        if (sessionEventHasKnownIdentity(event, seenFollowEvents)) {
+          continue;
+        }
+        addSessionEventIdentityKeys(seenFollowEvents, event);
         if (emitJson) {
           console.log(JSON.stringify(event));
         } else {
@@ -1178,6 +1707,11 @@ export function registerSessionCommand(program) {
         dropped: result.dropped,
         cursor: result.cursor,
         persistedCursor: result.persistedCursor,
+        humanRelayed: result.humanRelayed,
+        eventsRelayed: result.eventsRelayed,
+        eventsCursor: result.eventsCursor,
+        materializedLocalSession: result.materializedLocalSession,
+        localAppendComplete: result.localAppendComplete,
         access: access || undefined,
       };
       if (shouldEmitJson(options, command)) {
@@ -1517,7 +2051,7 @@ export function registerSessionCommand(program) {
         throw new Error("session id is required.");
       }
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
-      const agentId = normalizeAgentId(options.agent, "cli-user");
+      const agentId = await defaultAgentId(options.agent, targetPath);
       const left = await unregisterAgent(normalizedSessionId, agentId, {
         reason: options.reason || "manual",
         targetPath,