sentinelayer-cli 0.8.4 → 0.8.6

package/package.json

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

package/src/commands/session.js

@@ -1,3 +1,4 @@
+import fsp from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 import { randomUUID } from "node:crypto";
@@ -44,10 +45,13 @@ import {
   DEFAULT_TTL_SECONDS,
   getSession,
   listActiveSessions,
+  listAllSessions,
   recordSessionProvisionedIdentities,
 } from "../session/store.js";
 import { appendToStream, readStream, tailStream } from "../session/stream.js";
+import { readSessionPreview } from "../session/preview.js";
 import { syncSessionMetadataToApi } from "../session/sync.js";
+import { hydrateSessionFromRemote } from "../session/remote-hydrate.js";
 import {
   buildDashboardUrl,
   buildTemplateLaunchPlan,
@@ -450,6 +454,10 @@ export function registerSessionCommand(program) {
     .description("Read recent session messages")
     .option("--tail <n>", "Number of recent events", "20")
     .option("--follow", "Continuously follow new events")
+    .option(
+      "--remote",
+      "Hydrate from the SentinelLayer API before reading (pulls web-posted messages into the local NDJSON)",
+    )
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, options, command) => {
@@ -461,6 +469,29 @@ export function registerSessionCommand(program) {
       const tail = parsePositiveInteger(options.tail, "tail", 20);
       const emitJson = shouldEmitJson(options, command);
 
+      let hydration = null;
+      if (options.remote) {
+        hydration = await hydrateSessionFromRemote({
+          sessionId: normalizedSessionId,
+          targetPath,
+        });
+        if (!emitJson) {
+          if (hydration.ok) {
+            console.log(
+              pc.gray(
+                `Hydrated from remote: relayed=${hydration.relayed} dropped=${hydration.dropped}.`,
+              ),
+            );
+          } else {
+            console.log(
+              pc.yellow(
+                `Remote hydrate skipped (${hydration.reason}); showing local stream only.`,
+              ),
+            );
+          }
+        }
+      }
+
       if (!options.follow) {
         const events = await readStream(normalizedSessionId, {
           targetPath,
@@ -473,6 +504,7 @@ export function registerSessionCommand(program) {
           tail,
           count: events.length,
           events,
+          remote: hydration,
         };
         if (emitJson) {
           console.log(JSON.stringify(payload, null, 2));
@@ -499,6 +531,59 @@ export function registerSessionCommand(program) {
       }
     });
 
+  session
+    .command("sync <sessionId>")
+    .description(
+      "Pull human messages from the SentinelLayer API into the local NDJSON stream",
+    )
+    .option(
+      "--since <iso>",
+      "Override the persisted cursor and start from this ISO timestamp",
+    )
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const sinceArg = options.since == null ? undefined : String(options.since);
+
+      const result = await hydrateSessionFromRemote({
+        sessionId: normalizedSessionId,
+        targetPath,
+        since: sinceArg,
+      });
+
+      const payload = {
+        command: "session sync",
+        targetPath,
+        sessionId: normalizedSessionId,
+        ok: result.ok,
+        reason: result.reason || "",
+        relayed: result.relayed,
+        dropped: result.dropped,
+        cursor: result.cursor,
+        persistedCursor: result.persistedCursor,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      if (result.ok) {
+        console.log(
+          `Hydrated session ${normalizedSessionId}: relayed=${result.relayed} dropped=${result.dropped}.`,
+        );
+      } else {
+        console.log(
+          pc.yellow(
+            `Hydrate skipped (${result.reason}). Local stream is unchanged; cursor=${result.cursor || "<none>"}.`,
+          ),
+        );
+      }
+    });
+
   session
     .command("status <sessionId>")
     .description("Show session status, agents, and health")
@@ -581,6 +666,94 @@ export function registerSessionCommand(program) {
       }
     });
 
+  session
+    .command("export <sessionId>")
+    .description(
+      "Export full transcript + metadata + agents + tasks as JSON (compliance / portability / context handoff)",
+    )
+    .option(
+      "--format <fmt>",
+      "Output format: json (single object) or ndjson (one event per line)",
+      "json",
+    )
+    .option("--out <file>", "Write to file instead of stdout")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .action(async (sessionId, options) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const format = String(options.format || "json").trim().toLowerCase();
+      if (format !== "json" && format !== "ndjson") {
+        throw new Error(`--format must be 'json' or 'ndjson' (received '${format}').`);
+      }
+
+      const sessionPayload = await getSession(normalizedSessionId, { targetPath });
+      if (!sessionPayload) {
+        throw new Error(`Session '${normalizedSessionId}' was not found.`);
+      }
+
+      const [agents, events, tasks] = await Promise.all([
+        listAgents(normalizedSessionId, {
+          targetPath,
+          includeInactive: true,
+        }),
+        readStream(normalizedSessionId, {
+          targetPath,
+          tail: 0,
+        }),
+        listSessionTasks(normalizedSessionId, {
+          targetPath,
+          limit: 5_000,
+        }),
+      ]);
+
+      let output;
+      if (format === "ndjson") {
+        const lines = [];
+        lines.push(JSON.stringify({ kind: "session", value: sessionPayload }));
+        for (const agent of agents) lines.push(JSON.stringify({ kind: "agent", value: agent }));
+        for (const event of events) lines.push(JSON.stringify({ kind: "event", value: event }));
+        for (const task of tasks.tasks || []) lines.push(JSON.stringify({ kind: "task", value: task }));
+        output = `${lines.join("\n")}\n`;
+      } else {
+        output = `${JSON.stringify(
+          {
+            command: "session export",
+            exportedAt: new Date().toISOString(),
+            session: sessionPayload,
+            agents,
+            events,
+            tasks: tasks.tasks || [],
+            counts: {
+              agents: agents.length,
+              events: events.length,
+              tasks: (tasks.tasks || []).length,
+            },
+          },
+          null,
+          2,
+        )}\n`;
+      }
+
+      const outArg = normalizeString(options.out);
+      if (outArg) {
+        const outPath = path.resolve(process.cwd(), outArg);
+        await fsp.mkdir(path.dirname(outPath), { recursive: true });
+        await fsp.writeFile(outPath, output, "utf-8");
+        console.log(
+          pc.gray(
+            `Exported ${events.length} events / ${agents.length} agents / ${
+              (tasks.tasks || []).length
+            } tasks → ${outPath}`,
+          ),
+        );
+      } else {
+        process.stdout.write(output);
+      }
+    });
+
   session
     .command("leave <sessionId>")
     .description("Leave a session")
@@ -617,31 +790,129 @@ export function registerSessionCommand(program) {
 
   session
     .command("list")
-    .description("List active sessions")
+    .description("List sessions in the local workspace cache")
+    .option(
+      "--include-archived",
+      "Include archived/expired sessions (past conversations)",
+    )
+    .option(
+      "--limit <n>",
+      "Maximum sessions to return (default 50; ignored on --json)",
+      "50",
+    )
     .option("--path <path>", "Workspace path for sessions", ".")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
-      const sessions = await listActiveSessions({
-        targetPath,
-      });
+      const includeArchived = Boolean(options.includeArchived);
+      const limit = parsePositiveInteger(options.limit, "limit", 50);
+      const sessions = includeArchived
+        ? await listAllSessions({ targetPath })
+        : await listActiveSessions({ targetPath });
+      const trimmed = shouldEmitJson(options, command) ? sessions : sessions.slice(0, limit);
       const payload = {
         command: "session list",
         targetPath,
+        includeArchived,
         count: sessions.length,
-        sessions,
+        sessions: trimmed,
       };
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
         return;
       }
       if (sessions.length === 0) {
-        console.log(pc.yellow("No active sessions."));
+        console.log(
+          pc.yellow(
+            includeArchived
+              ? "No sessions in cache."
+              : "No active sessions. Run with --include-archived to see history.",
+          ),
+        );
+        return;
+      }
+      for (const item of trimmed) {
+        const archive = item.archiveStatus ? ` archive=${item.archiveStatus}` : "";
+        console.log(
+          `${item.sessionId} status=${item.status}${archive} created=${item.createdAt} expires=${item.expiresAt}`,
+        );
+      }
+      if (sessions.length > trimmed.length) {
+        console.log(
+          pc.gray(
+            `… ${sessions.length - trimmed.length} more (raise --limit or use --json).`,
+          ),
+        );
+      }
+    });
+
+  session
+    .command("history")
+    .description(
+      "Past conversations with a one-line preview of the most recent message (alias for `session list --include-archived` + previews)",
+    )
+    .option("--limit <n>", "Maximum sessions to return", "50")
+    .option("--no-preview", "Skip the per-session preview lookup")
+    .option("--path <path>", "Workspace path for sessions", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const limit = parsePositiveInteger(options.limit, "limit", 50);
+      const wantPreview = options.preview !== false;
+      const sessions = await listAllSessions({ targetPath });
+      const trimmed = shouldEmitJson(options, command) ? sessions : sessions.slice(0, limit);
+
+      let previews = new Map();
+      if (wantPreview && trimmed.length > 0) {
+        const entries = await Promise.all(
+          trimmed.map(async (item) => [
+            item.sessionId,
+            await readSessionPreview(item.sessionId, { targetPath }),
+          ]),
+        );
+        previews = new Map(entries);
+      }
+
+      if (shouldEmitJson(options, command)) {
+        const payload = {
+          command: "session history",
+          targetPath,
+          count: sessions.length,
+          sessions: trimmed.map((item) => ({
+            ...item,
+            preview: previews.get(item.sessionId) || null,
+          })),
+        };
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      if (sessions.length === 0) {
+        console.log(pc.yellow("No sessions in cache."));
         return;
       }
-      for (const item of sessions) {
+      for (const item of trimmed) {
+        const archive = item.archiveStatus.padEnd(8);
+        const head =
+          `${archive} ${item.sessionId} created=${item.createdAt}` +
+          (item.archivedAt ? ` archived=${item.archivedAt}` : "");
+        if (!wantPreview) {
+          console.log(head);
+          continue;
+        }
+        const preview = previews.get(item.sessionId);
+        if (preview && preview.message) {
+          const speaker = preview.agentId ? `${preview.agentId}: ` : "";
+          console.log(`${head}\n  ${pc.gray(`${speaker}${preview.message}`)}`);
+        } else {
+          console.log(`${head}\n  ${pc.gray("(no messages yet)")}`);
+        }
+      }
+      if (sessions.length > trimmed.length) {
         console.log(
-          `${item.sessionId} status=${item.status} created_at=${item.createdAt} expires_at=${item.expiresAt}`
+          pc.gray(
+            `… ${sessions.length - trimmed.length} more (raise --limit or use --json).`,
+          ),
         );
       }
     });

package/src/session/live-source.js

@@ -0,0 +1,308 @@
+/**
+ * Live session-event source — composes `fs.watch` (instant local notify
+ * when the NDJSON file changes) and SSE (`/api/v1/sessions/<id>/stream`,
+ * server-pushed updates) into a single async iterator.
+ *
+ * The two lanes give us the WebRTC-like behavior the user asked about
+ * without the WebRTC operational tax: same-machine peers see each
+ * other's writes through `fs.watch` immediately; remote peers receive
+ * via SSE the moment the API persists. A single stream emits both, with
+ * dedup by event id so the same event seen on both lanes only surfaces
+ * once.
+ *
+ * Tests inject `_watch`, `_sse`, and `_readEvents` so the iterator can
+ * be exercised hermetically; production uses `node:fs` watch + native
+ * fetch streaming.
+ */
+
+import fs from "node:fs";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import { resolveSessionPaths } from "./paths.js";
+import { readStream } from "./stream.js";
+
+const DEFAULT_RECONNECT_BACKOFF_MS = 2_000;
+const MAX_RECONNECT_BACKOFF_MS = 30_000;
+
+function eventKey(event) {
+  if (!event || typeof event !== "object") return null;
+  if (event.id) return `id:${event.id}`;
+  if (event.eventId) return `id:${event.eventId}`;
+  const ts = event.ts || event.timestamp;
+  const kind = event.event || event.type;
+  if (ts && kind) return `${ts}::${kind}`;
+  return null;
+}
+
+/**
+ * Watch a session's NDJSON file with `fs.watch`. Whenever the file
+ * changes (append-only writes happen on every event), re-read the tail
+ * and emit any events the consumer hasn't seen yet. Falls back to a
+ * 500 ms poll on platforms where `fs.watch` is unreliable (some
+ * Windows + network mounts) — controlled by `_watch` for tests.
+ *
+ * Async generator yields `{ source: "fs", event }`.
+ */
+export async function* watchLocalStream({
+  sessionId,
+  targetPath,
+  signal,
+  initialTail = 50,
+  _watch = fs.watch,
+  _readEvents = readStream,
+} = {}) {
+  if (!sessionId) return;
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  let lastTs = null;
+
+  // Replay the tail first so any caller getting the iterator catches
+  // up with the in-flight context before live events start arriving.
+  const initial = await _readEvents(sessionId, { targetPath, tail: initialTail });
+  for (const event of initial) {
+    const candidate = event.ts || event.timestamp;
+    if (candidate) lastTs = candidate;
+    yield { source: "fs", event };
+  }
+
+  let pendingResolve = null;
+  let pendingPromise = null;
+  const queue = [];
+
+  function notify() {
+    if (pendingResolve) {
+      const r = pendingResolve;
+      pendingResolve = null;
+      pendingPromise = null;
+      r();
+    }
+  }
+
+  let watcher = null;
+  try {
+    watcher = _watch(paths.streamPath, { persistent: false }, () => notify());
+  } catch {
+    // If watch can't attach (file missing yet, locked filesystem), we
+    // fall back to a 500ms poll so the iterator still makes progress.
+    watcher = {
+      close() {},
+    };
+    (async () => {
+      while (!signal?.aborted) {
+        await sleep(500);
+        notify();
+      }
+    })();
+  }
+
+  const aborted = () => Boolean(signal?.aborted);
+  if (signal) signal.addEventListener("abort", () => notify(), { once: true });
+
+  try {
+    while (!aborted()) {
+      // Wait for any change notification.
+      pendingPromise = new Promise((resolve) => {
+        pendingResolve = resolve;
+      });
+      await pendingPromise;
+      if (aborted()) break;
+
+      const events = await _readEvents(sessionId, { targetPath, tail: 0, since: lastTs });
+      for (const event of events) {
+        const candidate = event.ts || event.timestamp;
+        if (lastTs && candidate && candidate <= lastTs) continue;
+        if (candidate) lastTs = candidate;
+        queue.push({ source: "fs", event });
+      }
+      while (queue.length > 0) {
+        yield queue.shift();
+      }
+    }
+  } finally {
+    try {
+      watcher.close();
+    } catch {
+      /* swallow */
+    }
+  }
+}
+
+/**
+ * Subscribe to the API's SSE stream for a session. Emits each parsed
+ * data: line as `{ source: "sse", event }`. Auto-reconnects on
+ * connection drop with exponential backoff capped at 30s.
+ *
+ * `_sseFetch` defaults to `fetch` but tests can stub it.
+ */
+export async function* watchRemoteStream({
+  apiBaseUrl,
+  sessionId,
+  token,
+  signal,
+  _sseFetch = fetch,
+  reconnectBackoffMs = DEFAULT_RECONNECT_BACKOFF_MS,
+} = {}) {
+  if (!apiBaseUrl || !sessionId || !token) return;
+  const endpoint = `${apiBaseUrl.replace(/\/+$/, "")}/api/v1/sessions/${encodeURIComponent(
+    sessionId,
+  )}/stream`;
+  let backoff = reconnectBackoffMs;
+
+  while (!signal?.aborted) {
+    let response;
+    try {
+      response = await _sseFetch(endpoint, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: "text/event-stream",
+        },
+        signal,
+      });
+    } catch (err) {
+      if (signal?.aborted) return;
+      yield { source: "sse", error: String(err?.message || err) };
+      await sleep(backoff);
+      backoff = Math.min(backoff * 2, MAX_RECONNECT_BACKOFF_MS);
+      continue;
+    }
+
+    if (!response || !response.ok || !response.body) {
+      yield { source: "sse", error: `HTTP ${response?.status || "?"}` };
+      await sleep(backoff);
+      backoff = Math.min(backoff * 2, MAX_RECONNECT_BACKOFF_MS);
+      continue;
+    }
+
+    backoff = reconnectBackoffMs;
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    try {
+      while (!signal?.aborted) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const frames = buffer.split(/\n\n/);
+        buffer = frames.pop() || "";
+        for (const frame of frames) {
+          for (const line of frame.split(/\r?\n/)) {
+            if (!line.startsWith("data:")) continue;
+            const payload = line.slice(5).trim();
+            if (!payload || payload === "[done]") continue;
+            try {
+              const event = JSON.parse(payload);
+              yield { source: "sse", event };
+            } catch {
+              yield { source: "sse", raw: payload };
+            }
+          }
+        }
+      }
+    } finally {
+      try {
+        await reader.cancel();
+      } catch {
+        /* swallow */
+      }
+    }
+
+    if (signal?.aborted) return;
+    await sleep(backoff);
+  }
+}
+
+/**
+ * Compose `fs.watch` and SSE into one event stream. Each emitted event
+ * carries its `source` so consumers can tell which lane saw it first;
+ * we dedup by event id so the same event arriving on both lanes only
+ * surfaces once.
+ *
+ * @param {object} params
+ * @param {string} params.sessionId
+ * @param {string} [params.targetPath]
+ * @param {string} [params.apiBaseUrl]
+ * @param {string} [params.token]
+ * @param {AbortSignal} [params.signal]
+ * @returns {AsyncIterable<{source: "fs"|"sse", event?: object, raw?: string, error?: string}>}
+ */
+export async function* mergeLiveSources({
+  sessionId,
+  targetPath,
+  apiBaseUrl,
+  token,
+  signal,
+  _localIterator,
+  _remoteIterator,
+} = {}) {
+  if (!sessionId) return;
+
+  const localIterable = _localIterator
+    ? _localIterator
+    : watchLocalStream({ sessionId, targetPath, signal });
+  const remoteIterable =
+    _remoteIterator || (apiBaseUrl && token)
+      ? _remoteIterator
+        ? _remoteIterator
+        : watchRemoteStream({ apiBaseUrl, sessionId, token, signal })
+      : null;
+
+  const seen = new Set();
+  const queue = [];
+  let pending = null;
+
+  const wakeUp = () => {
+    if (pending) {
+      const r = pending;
+      pending = null;
+      r();
+    }
+  };
+
+  async function pump(iterable) {
+    if (!iterable) return;
+    try {
+      for await (const item of iterable) {
+        queue.push(item);
+        wakeUp();
+        if (signal?.aborted) break;
+      }
+    } catch (err) {
+      queue.push({ source: "merge", error: String(err?.message || err) });
+      wakeUp();
+    }
+  }
+
+  pump(localIterable);
+  if (remoteIterable) pump(remoteIterable);
+
+  // Make sure abort wakes the iterator promptly so the consumer doesn't
+  // hang waiting on a `pending` promise that nothing is going to
+  // resolve once the upstream sources finish.
+  if (signal) signal.addEventListener("abort", () => wakeUp(), { once: true });
+
+  while (!signal?.aborted) {
+    if (queue.length === 0) {
+      await new Promise((resolve) => {
+        pending = resolve;
+      });
+      if (signal?.aborted) break;
+      continue;
+    }
+    const item = queue.shift();
+    if (item.event) {
+      const key = eventKey(item.event);
+      if (key) {
+        if (seen.has(key)) continue;
+        seen.add(key);
+        if (seen.size > 5000) {
+          // bound memory — older keys roll out
+          const trimmed = Array.from(seen).slice(-2500);
+          seen.clear();
+          for (const k of trimmed) seen.add(k);
+        }
+      }
+    }
+    yield item;
+  }
+}

package/src/session/preview.js

@@ -0,0 +1,91 @@
+/**
+ * Per-session message preview — used by `slc session history` to show
+ * the last meaningful line of each past conversation, ChatGPT-style.
+ *
+ * "Meaningful" filters out heartbeats / agent_join / file-lock churn
+ * so the preview doesn't get drowned in machine traffic.
+ */
+
+import { readStream } from "./stream.js";
+
+const PREVIEW_EVENTS = new Set([
+  "session_message",
+  "session_say",
+  "agent_response",
+  "human_relay",
+  "daemon_alert",
+  "session_admin_kill",
+]);
+
+const HEAD_LIMIT = 40;
+const PREVIEW_TAIL_SCAN = 50;
+
+function trim(value, limit = HEAD_LIMIT) {
+  const text = String(value == null ? "" : value).trim();
+  if (!text) return "";
+  if (text.length <= limit) return text;
+  return `${text.slice(0, Math.max(0, limit - 1))}…`;
+}
+
+/**
+ * Pick the most recent user-visible message from an event list. Returns
+ * the head of its body and the speaker so the caller can render
+ * `<agentId>: <message>`.
+ *
+ * @param {Array<object>} events
+ * @returns {{ts: string|null, agentId: string|null, kind: string|null, message: string|null}}
+ */
+export function pickLatestPreview(events = []) {
+  if (!Array.isArray(events) || events.length === 0) {
+    return { ts: null, agentId: null, kind: null, message: null };
+  }
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const event = events[i] || {};
+    const kind = String(event.event || event.type || "").trim();
+    if (!kind || !PREVIEW_EVENTS.has(kind)) continue;
+    const payload = event.payload && typeof event.payload === "object" ? event.payload : {};
+    const text =
+      payload.message ||
+      payload.response ||
+      payload.alert ||
+      payload.reason ||
+      payload.text;
+    if (!text) continue;
+    return {
+      ts: event.ts || event.timestamp || null,
+      agentId:
+        (event.agent && event.agent.id) ||
+        event.agentId ||
+        payload.agentId ||
+        null,
+      kind,
+      message: trim(text),
+    };
+  }
+  return { ts: null, agentId: null, kind: null, message: null };
+}
+
+/**
+ * Lift a preview line for a single session by tailing the stream.
+ * Failures are non-fatal — missing stream / parse errors yield a null
+ * preview rather than throwing, so the history listing stays resilient
+ * across mixed-state caches.
+ *
+ * @param {string} sessionId
+ * @param {{targetPath?: string, tail?: number}} [options]
+ * @returns {Promise<{ts: string|null, agentId: string|null, kind: string|null, message: string|null}>}
+ */
+export async function readSessionPreview(
+  sessionId,
+  { targetPath = process.cwd(), tail = PREVIEW_TAIL_SCAN } = {},
+) {
+  if (!sessionId) {
+    return { ts: null, agentId: null, kind: null, message: null };
+  }
+  try {
+    const events = await readStream(sessionId, { targetPath, tail });
+    return pickLatestPreview(events);
+  } catch {
+    return { ts: null, agentId: null, kind: null, message: null };
+  }
+}

package/src/session/remote-hydrate.js

@@ -0,0 +1,95 @@
+/**
+ * One-shot remote hydrator for the local NDJSON stream.
+ *
+ * Wraps `pollHumanMessages` (which speaks to the SentinelLayer API) with
+ * a persisted cursor + `appendToStream`, so a CLI invocation can pull
+ * web-posted messages into the local session log on demand. The
+ * background daemon already does this on a poll loop; this module is
+ * the synchronous counterpart that powers `slc session sync` and
+ * `slc session read --remote`.
+ */
+
+import { pollHumanMessages } from "./sync.js";
+import { appendToStream } from "./stream.js";
+import { readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
+
+/**
+ * Fetch new human messages for a session, append them to the local
+ * stream, and advance the persisted cursor. Returns a structured
+ * summary the CLI can render directly. Failures degrade — we never
+ * throw out of this helper for transient/auth issues so wrappers can
+ * still serve a local-only read.
+ *
+ * @param {object} params
+ * @param {string} params.sessionId
+ * @param {string} [params.targetPath]
+ * @param {string|null} [params.since]   - Override persisted cursor.
+ * @param {Function}    [params._poll]   - Test seam.
+ * @param {Function}    [params._append] - Test seam.
+ * @returns {Promise<{ok: boolean, reason: string, relayed: number, dropped: number, cursor: string|null, persistedCursor: boolean}>}
+ */
+export async function hydrateSessionFromRemote({
+  sessionId,
+  targetPath = process.cwd(),
+  since = undefined,
+  _poll = pollHumanMessages,
+  _append = appendToStream,
+} = {}) {
+  if (!sessionId || typeof sessionId !== "string") {
+    return {
+      ok: false,
+      reason: "invalid_session_id",
+      relayed: 0,
+      dropped: 0,
+      cursor: null,
+      persistedCursor: false,
+    };
+  }
+
+  const startCursor =
+    typeof since === "string" || since === null
+      ? since
+      : await readSyncCursor(sessionId, { targetPath });
+
+  const polled = await _poll(sessionId, {
+    targetPath,
+    since: startCursor,
+  });
+
+  if (!polled || !polled.ok) {
+    return {
+      ok: false,
+      reason: polled?.reason || "poll_failed",
+      relayed: 0,
+      dropped: Array.isArray(polled?.dropped) ? polled.dropped.length : 0,
+      cursor: typeof polled?.cursor === "string" ? polled.cursor : startCursor || null,
+      persistedCursor: false,
+    };
+  }
+
+  let relayed = 0;
+  for (const event of polled.events || []) {
+    try {
+      await _append(sessionId, event, { targetPath });
+      relayed += 1;
+    } catch {
+      // Append errors are observable via the stream but should not
+      // abort the rest of the batch — partial relay is still progress.
+    }
+  }
+
+  let persistedCursor = false;
+  if (typeof polled.cursor === "string" && polled.cursor.trim()) {
+    const result = await writeSyncCursor(sessionId, polled.cursor, { targetPath }).catch(() => null);
+    persistedCursor = Boolean(result && result.written);
+  }
+
+  return {
+    ok: true,
+    reason: "",
+    relayed,
+    dropped: Array.isArray(polled.dropped) ? polled.dropped.length : 0,
+    cursor: typeof polled.cursor === "string" ? polled.cursor : startCursor || null,
+    persistedCursor,
+  };
+}

package/src/session/store.js

@@ -484,6 +484,52 @@ export async function listActiveSessions({ targetPath = process.cwd() } = {}) {
   return sessions;
 }
 
+/**
+ * List every session known to the local cache. Unlike
+ * `listActiveSessions`, this includes archived AND expired sessions so
+ * the CLI can surface past conversations the way ChatGPT exposes its
+ * left-rail history.
+ *
+ * Each entry carries `archiveStatus` (`"active"` | `"archived"` |
+ * `"expired"`) so the consumer can group/filter without re-deriving
+ * lifecycle from the raw timestamps.
+ *
+ * @param {{targetPath?: string}} [options]
+ * @returns {Promise<Array<object>>}
+ */
+export async function listAllSessions({ targetPath = process.cwd() } = {}) {
+  const resolvedTargetPath = path.resolve(String(targetPath || "."));
+  const sessionsRoot = resolveSessionsRoot({ targetPath: resolvedTargetPath });
+  let entries = [];
+  try {
+    entries = await fsp.readdir(sessionsRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+
+  const sessions = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const loaded = await loadMetadata(entry.name, { targetPath: resolvedTargetPath });
+    if (!loaded) continue;
+
+    const payload = buildSessionPayload(loaded.metadata, loaded.paths);
+    let archiveStatus = "active";
+    if (loaded.metadata.status === SESSION_STATUS_ARCHIVED) {
+      archiveStatus = "archived";
+    } else if (isExpired(loaded.metadata)) {
+      archiveStatus = "expired";
+    }
+    sessions.push({ ...payload, archiveStatus });
+  }
+
+  sessions.sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+  return sessions;
+}
+
 export async function renewSession(sessionId, { targetPath = process.cwd() } = {}) {
   const loaded = await loadMetadata(sessionId, { targetPath });
   if (!loaded) {

package/src/session/sync-cursor.js

@@ -0,0 +1,62 @@
+/**
+ * Per-session sync cursor persistence.
+ *
+ * The daemon keeps the human-message poll cursor in memory; one-shot CLI
+ * commands (`slc session sync`, `slc session read --remote`) need a
+ * cursor that survives across invocations so successive runs only fetch
+ * what is new. We persist the cursor next to the stream NDJSON in the
+ * session directory.
+ */
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { resolveSessionDir } from "./paths.js";
+
+function cursorPath(sessionId, { targetPath } = {}) {
+  return path.join(resolveSessionDir(sessionId, { targetPath }), "remote-sync-cursor.json");
+}
+
+/**
+ * Read the persisted human-message cursor for a session. Returns `null`
+ * when no cursor has been recorded yet, or when the file is missing,
+ * empty, or malformed — callers should treat that as "first sync".
+ *
+ * @param {string} sessionId
+ * @param {{targetPath?: string}} [options]
+ * @returns {Promise<string|null>}
+ */
+export async function readSyncCursor(sessionId, { targetPath } = {}) {
+  if (!sessionId) return null;
+  const filePath = cursorPath(sessionId, { targetPath });
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const cursor = typeof parsed?.cursor === "string" ? parsed.cursor.trim() : "";
+    return cursor || null;
+  } catch (err) {
+    if (err && err.code === "ENOENT") return null;
+    return null;
+  }
+}
+
+/**
+ * Persist the human-message cursor for a session. No-op when cursor is
+ * empty so we never overwrite a real value with an empty one.
+ *
+ * @param {string} sessionId
+ * @param {string|null|undefined} cursor
+ * @param {{targetPath?: string}} [options]
+ * @returns {Promise<{written: boolean, path: string}>}
+ */
+export async function writeSyncCursor(sessionId, cursor, { targetPath } = {}) {
+  const filePath = cursorPath(sessionId, { targetPath });
+  const normalized = typeof cursor === "string" ? cursor.trim() : "";
+  if (!sessionId || !normalized) {
+    return { written: false, path: filePath };
+  }
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
+  const payload = { cursor: normalized, updatedAt: new Date().toISOString() };
+  await fsp.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+  return { written: true, path: filePath };
+}