sentinelayer-cli 0.8.9 → 0.8.11

package/package.json

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

package/src/commands/session.js

@@ -261,8 +261,11 @@ export function registerSessionCommand(program) {
 
   session
     .command("start")
-    .description("Create a new persistent session with metadata + NDJSON stream")
+    .description(
+      "Start (or resume) a persistent session. By default reuses the most recent active session for this workspace; pass --force-new to always mint a fresh id.",
+    )
     .option("--path <path>", "Workspace path for the session", ".")
+    .option("--title <title>", "Human-readable label (shown in web sidebar + transcript)")
     .option(
       "--template <name>",
       "Optional quick-start template (code-review, security-audit, e2e-test, incident-response, standup)"
@@ -271,6 +274,15 @@ export function registerSessionCommand(program) {
       "--ttl-seconds <seconds>",
       `Session time-to-live in seconds (default ${DEFAULT_TTL_SECONDS}; template defaults override when omitted)`
     )
+    .option(
+      "--force-new",
+      "Always create a new session even if a recent active one exists for this workspace",
+    )
+    .option(
+      "--reuse-window-seconds <seconds>",
+      "Window in which an existing active session for this workspace will be reused (default 3600 = 1h)",
+      "3600",
+    )
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
@@ -284,15 +296,96 @@ export function registerSessionCommand(program) {
         "ttl-seconds",
         templateDefaultTtlSeconds
       );
+      const reuseWindowSeconds = parsePositiveInteger(
+        options.reuseWindowSeconds,
+        "reuse-window-seconds",
+        3600,
+      );
+
+      // Auto-resume: if there's an active local session for this same
+      // workspace path created in the last `reuseWindowSeconds`, reuse
+      // it instead of minting a new id. Kills the orphan-creation
+      // pattern where every CLI invocation produced a fresh empty
+      // session. `--force-new` opts back into the old behavior.
+      let resumed = null;
+      if (!options.forceNew) {
+        try {
+          const active = await listActiveSessions({ targetPath });
+          const cutoffMs = Date.now() - reuseWindowSeconds * 1000;
+          const candidates = active.filter((entry) => {
+            const createdMs = Date.parse(entry.createdAt || "");
+            return Number.isFinite(createdMs) && createdMs >= cutoffMs;
+          });
+          candidates.sort((a, b) =>
+            String(b.lastActivityAt || b.createdAt || "").localeCompare(
+              String(a.lastActivityAt || a.createdAt || ""),
+            ),
+          );
+          if (candidates.length > 0) {
+            resumed = candidates[0];
+          }
+        } catch (error) {
+          // listActiveSessions failure is non-fatal; fall through to fresh create.
+        }
+      }
+
       const startedAt = Date.now();
-      const created = await createSession({
-        targetPath,
-        ttlSeconds,
-        template,
-      });
+      let created;
+      if (resumed) {
+        // Surface the resumed session's metadata in the same shape
+        // createSession returns so downstream code stays unchanged.
+        created = {
+          sessionId: resumed.sessionId,
+          sessionDir: resumed.sessionDir || null,
+          metadataPath: resumed.metadataPath || null,
+          streamPath: resumed.streamPath || null,
+          createdAt: resumed.createdAt,
+          expiresAt: resumed.expiresAt,
+          elapsedTimer: 0,
+          renewalCount: resumed.renewalCount || 0,
+          status: resumed.status || "active",
+          template: resumed.template || null,
+          codebaseContext: resumed.codebaseContext || null,
+          resumed: true,
+        };
+      } else {
+        created = await createSession({
+          targetPath,
+          ttlSeconds,
+          template,
+        });
+      }
       const durationMs = Date.now() - startedAt;
       const launchPlan = template ? buildTemplateLaunchPlan(created.sessionId, template) : [];
       const dashboardUrl = buildDashboardUrl(created.sessionId);
+      const titleArg = normalizeString(options.title);
+
+      // If the caller passed --title, push it to the API so the web
+      // sidebar shows the label (best-effort, non-blocking).
+      if (titleArg) {
+        void (async () => {
+          try {
+            const session = await resolveActiveAuthSession({
+              cwd: targetPath,
+              env: process.env,
+              autoRotate: false,
+            });
+            if (!session?.token || !session?.apiUrl) return;
+            const apiUrl = String(session.apiUrl).replace(/\/+$/, "");
+            await requestJsonMutation(
+              `${apiUrl}/api/v1/sessions/${encodeURIComponent(created.sessionId)}/title`,
+              {
+                method: "POST",
+                operationName: "session.set_title",
+                headers: { Authorization: `Bearer ${session.token}` },
+                body: { title: titleArg },
+              },
+            );
+          } catch (_error) {
+            /* best-effort */
+          }
+        })();
+      }
 
       const payload = {
         command: "session start",
@@ -311,6 +404,8 @@ export function registerSessionCommand(program) {
         template: created.template,
         launchPlan,
         dashboardUrl,
+        resumed: Boolean(resumed),
+        title: titleArg || null,
       };
 
       // Best-effort admin visibility sync. Session creation remains local-first.
@@ -331,8 +426,12 @@ export function registerSessionCommand(program) {
       }
 
       if (template) {
-        console.log(`Session ${created.sessionId} created (template: ${template.id})`);
-        if (launchPlan.length > 0) {
+        console.log(
+          resumed
+            ? `Resumed session ${created.sessionId} (template: ${template.id})`
+            : `Session ${created.sessionId} created (template: ${template.id})`,
+        );
+        if (launchPlan.length > 0 && !resumed) {
           console.log("");
           console.log("Launch your agents:");
           for (const slot of launchPlan) {
@@ -344,13 +443,136 @@ export function registerSessionCommand(program) {
         return;
       }
 
-      console.log(pc.bold("Session created"));
+      console.log(pc.bold(resumed ? "Session resumed" : "Session created"));
       console.log(pc.gray(`Session: ${created.sessionId}`));
-      console.log(pc.gray(`Stream: ${created.streamPath}`));
-      console.log(pc.gray(`Created in ${durationMs}ms`));
+      if (titleArg) console.log(pc.gray(`Title: ${titleArg}`));
+      if (created.streamPath) console.log(pc.gray(`Stream: ${created.streamPath}`));
+      console.log(pc.gray(`${resumed ? "Resumed" : "Created"} in ${durationMs}ms`));
       console.log(
-        `status=${created.status} created_at=${created.createdAt} expires_at=${created.expiresAt} ttl_seconds=${ttlSeconds}`
+        `status=${created.status} created_at=${created.createdAt} expires_at=${created.expiresAt} ttl_seconds=${ttlSeconds}`,
       );
+      if (!resumed) {
+        console.log(
+          pc.gray(
+            "Tip: subsequent `slc session start` in this workspace within an hour will resume this session. Pass --force-new to override.",
+          ),
+        );
+      }
+    });
+
+  session
+    .command("continue")
+    .description("Alias for `session start --resume` — resume the most recent active session for this workspace, or create one if none exists.")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--title <title>", "Title applied if a new session is created")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      // Delegate to session start without --force-new. Commander parses
+      // the args for us via the parent action; here we just shell out.
+      const args = ["session", "start", "--path", String(options.path || ".")];
+      if (options.title) args.push("--title", String(options.title));
+      if (shouldEmitJson(options, command)) args.push("--json");
+      await program.parseAsync(args, { from: "user" });
+    });
+
+  session
+    .command("set-title <sessionId> <title>")
+    .description("Set the human-readable title on a session (visible in web sidebar + transcript).")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, title, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) throw new Error("session id is required.");
+      const normalizedTitle = normalizeString(title);
+      if (!normalizedTitle) throw new Error("title is required.");
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const session = await resolveActiveAuthSession({
+        cwd: targetPath,
+        env: process.env,
+        autoRotate: false,
+      });
+      if (!session?.token || !session?.apiUrl) {
+        throw new Error(`Not authenticated. Run \`${authLoginHint()}\` first.`);
+      }
+      const apiUrl = String(session.apiUrl).replace(/\/+$/, "");
+      const result = await requestJsonMutation(
+        `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/title`,
+        {
+          method: "POST",
+          operationName: "session.set_title",
+          headers: { Authorization: `Bearer ${session.token}` },
+          body: { title: normalizedTitle },
+        },
+      );
+      const payload = {
+        command: "session set-title",
+        sessionId: normalizedSessionId,
+        title: normalizedTitle,
+        result,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(pc.bold(`Title set on ${normalizedSessionId}`));
+      console.log(pc.gray(`title=${normalizedTitle}`));
+    });
+
+  session
+    .command("cleanup")
+    .description("Bulk-archive empty stale sessions on the SentinelLayer dashboard. Targets sessions with ≤1 events older than --cutoff-minutes.")
+    .option("--cutoff-minutes <n>", "Age threshold in minutes (default 60)", "60")
+    .option("--max-events <n>", "Max events to still treat as empty (default 1)", "1")
+    .option("--apply", "Actually archive (default is dry-run)")
+    .option("--path <path>", "Workspace path", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const cutoffMinutes = parsePositiveInteger(options.cutoffMinutes, "cutoff-minutes", 60);
+      const maxEvents = parsePositiveInteger(options.maxEvents, "max-events", 1);
+      const dryRun = !options.apply;
+      const session = await resolveActiveAuthSession({
+        cwd: targetPath,
+        env: process.env,
+        autoRotate: false,
+      });
+      if (!session?.token || !session?.apiUrl) {
+        throw new Error(`Not authenticated. Run \`${authLoginHint()}\` first.`);
+      }
+      const apiUrl = String(session.apiUrl).replace(/\/+$/, "");
+      const result = await requestJsonMutation(
+        `${apiUrl}/api/v1/sessions/sweep`,
+        {
+          method: "POST",
+          operationName: "session.sweep_empty",
+          headers: { Authorization: `Bearer ${session.token}` },
+          body: {
+            cutoffMinutes,
+            maxEvents,
+            dryRun,
+          },
+        },
+      );
+      const payload = {
+        command: "session cleanup",
+        dryRun,
+        cutoffMinutes,
+        maxEvents,
+        result,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      const scanned = result?.scanned || 0;
+      const archived = result?.archived || 0;
+      console.log(pc.bold(dryRun ? "Cleanup dry-run" : "Cleanup applied"));
+      console.log(
+        pc.gray(`scanned=${scanned} archived=${archived} cutoff=${cutoffMinutes}m max-events=${maxEvents}`),
+      );
+      if (dryRun && scanned > 0) {
+        console.log(pc.gray(`Re-run with --apply to archive these ${scanned} sessions.`));
+      }
     });
 
   session

package/src/session/agent-registry.js

@@ -180,6 +180,62 @@ export function generateAgentId(modelName) {
   return `${prefix}-${suffix}`;
 }
 
+// In-process registry of agents registered by *this* CLI process. The
+// dashboard treats any participant without a terminal agent_leave /
+// agent_killed / session_killed event as "active". When a CLI exits via
+// SIGINT/SIGTERM/crash without explicitly leaving, the dashboard shows
+// "Last activity: 15h ago — active" indefinitely. This registry lets a
+// single process-wide exit hook flush leave events for every agent it
+// owns so the participant roster stays honest.
+const _localAgents = new Map(); // key: `${sessionId}::${agentId}` -> { sessionId, agentId, targetPath }
+let _exitHooksInstalled = false;
+
+function _agentKey(sessionId, agentId) {
+  return `${sessionId}::${agentId}`;
+}
+
+function _trackLocalAgent(sessionId, agentId, targetPath) {
+  _localAgents.set(_agentKey(sessionId, agentId), { sessionId, agentId, targetPath });
+  _ensureExitHooksInstalled();
+}
+
+function _untrackLocalAgent(sessionId, agentId) {
+  _localAgents.delete(_agentKey(sessionId, agentId));
+}
+
+async function _emitLeaveForAllLocalAgents(reason) {
+  const entries = [..._localAgents.values()];
+  _localAgents.clear();
+  for (const entry of entries) {
+    try {
+      await emitAgentEvent(
+        entry.sessionId,
+        "agent_leave",
+        { agentId: entry.agentId, reason, model: "unknown", role: "participant" },
+        { targetPath: entry.targetPath },
+      );
+    } catch {
+      // Best-effort: a stuck filesystem or network shouldn't block exit.
+    }
+  }
+}
+
+function _ensureExitHooksInstalled() {
+  if (_exitHooksInstalled) return;
+  _exitHooksInstalled = true;
+  const onSignal = (signal) => {
+    void _emitLeaveForAllLocalAgents("manual").finally(() => {
+      process.removeListener(signal, onSignal);
+      process.kill(process.pid, signal);
+    });
+  };
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+  process.on("beforeExit", () => {
+    void _emitLeaveForAllLocalAgents("manual");
+  });
+}
+
 export async function registerAgent(
   sessionId,
   { agentId = "", model = "", role = "observer", targetPath = process.cwd() } = {}
@@ -234,6 +290,7 @@ export async function registerAgent(
     role: snapshot.role,
     status: snapshot.status,
   }, { targetPath });
+  _trackLocalAgent(paths.sessionId, snapshot.agentId, targetPath);
 
   if (renamedFrom) {
     const welcome = buildSentiWelcome({
@@ -347,6 +404,8 @@ export async function unregisterAgent(
     role: snapshot.role,
     model: snapshot.model,
   }, { targetPath });
+  // Already left explicitly — don't double-emit on process exit.
+  _untrackLocalAgent(paths.sessionId, snapshot.agentId);
 
   return {
     ...snapshot,

package/src/session/remote-hydrate.js

@@ -1,18 +1,29 @@
 /**
  * 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`.
+ * Pulls events from the SentinelLayer API (BOTH human-posted messages
+ * AND agent-posted events) and appends them to the local session log
+ * with a persisted cursor. Powers `slc session sync` and
+ * `slc session read --remote`. The background daemon does the same thing
+ * on a poll loop; this is the synchronous counterpart.
+ *
+ * Why two pollers: Carter caught a multi-agent design bug in the
+ * standup session — agents polling via `pollHumanMessages` only saw
+ * web-posted human messages, never each other's `session_message` /
+ * `agent_response` events. Codex and claude talked past each other
+ * for hours ("Apologies — I missed your 5 updates"). Fix: also poll
+ * the durable `/sessions/{id}/events` endpoint (added in API #467)
+ * which returns ALL events. Per-source cursors keep the two pollers
+ * independent so a stuck human-message read doesn't block agent-event
+ * sync, and vice-versa.
  */
 
-import { pollHumanMessages } from "./sync.js";
+import { pollHumanMessages, pollSessionEvents } from "./sync.js";
 import { appendToStream } from "./stream.js";
 import { readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
 
+const EVENTS_CURSOR_SUFFIX = "events";
+
 /**
  * Fetch new human messages for a session, append them to the local
  * stream, and advance the persisted cursor. Returns a structured
@@ -33,6 +44,7 @@ export async function hydrateSessionFromRemote({
   targetPath = process.cwd(),
   since = undefined,
   _poll = pollHumanMessages,
+  _pollEvents = pollSessionEvents,
   _append = appendToStream,
 } = {}) {
   if (!sessionId || typeof sessionId !== "string") {
@@ -46,29 +58,61 @@ export async function hydrateSessionFromRemote({
     };
   }
 
-  const startCursor =
+  // Per-source cursors. The legacy human-message cursor is in the
+  // session's metadata file; the new agent-events cursor is in a
+  // sibling slot. Keeping them separate prevents a stuck/truncated
+  // poll on one source from poisoning the other.
+  const humanCursor =
     typeof since === "string" || since === null
       ? since
       : await readSyncCursor(sessionId, { targetPath });
+  const eventsCursor =
+    typeof since === "string" || since === null
+      ? since
+      : await readSyncCursor(sessionId, { targetPath, suffix: EVENTS_CURSOR_SUFFIX });
 
-  const polled = await _poll(sessionId, {
-    targetPath,
-    since: startCursor,
-  });
+  // Run both pollers in parallel — they hit different endpoints and
+  // are independent. A human-only poll stays fast even when the
+  // events poll is heavy.
+  const [humanResult, eventsResult] = await Promise.all([
+    _poll(sessionId, { targetPath, since: humanCursor }),
+    _pollEvents(sessionId, { targetPath, since: eventsCursor }),
+  ]);
 
-  if (!polled || !polled.ok) {
+  // Dedup across sources — both endpoints can return the same event
+  // (e.g. a human relay event). Cursor values are unique per event.
+  const seenCursors = new Set();
+  const merged = [];
+  for (const e of humanResult?.events || []) {
+    const c = (e && typeof e === "object" && typeof e.cursor === "string") ? e.cursor : "";
+    if (c && seenCursors.has(c)) continue;
+    if (c) seenCursors.add(c);
+    merged.push(e);
+  }
+  for (const e of eventsResult?.events || []) {
+    const c = (e && typeof e === "object" && typeof e.cursor === "string") ? e.cursor : "";
+    if (c && seenCursors.has(c)) continue;
+    if (c) seenCursors.add(c);
+    merged.push(e);
+  }
+
+  // If BOTH pollers failed, surface the human-message failure (the
+  // legacy contract) so existing callers see no behavior change. If
+  // only one fails, treat the relay as partial-but-successful.
+  if (!humanResult?.ok && !eventsResult?.ok) {
     return {
       ok: false,
-      reason: polled?.reason || "poll_failed",
+      reason: humanResult?.reason || eventsResult?.reason || "poll_failed",
       relayed: 0,
-      dropped: Array.isArray(polled?.dropped) ? polled.dropped.length : 0,
-      cursor: typeof polled?.cursor === "string" ? polled.cursor : startCursor || null,
+      dropped: Array.isArray(humanResult?.dropped) ? humanResult.dropped.length : 0,
+      cursor:
+        typeof humanResult?.cursor === "string" ? humanResult.cursor : humanCursor || null,
       persistedCursor: false,
     };
   }
 
   let relayed = 0;
-  for (const event of polled.events || []) {
+  for (const event of merged) {
     try {
       await _append(sessionId, event, { targetPath });
       relayed += 1;
@@ -79,17 +123,27 @@ export async function hydrateSessionFromRemote({
   }
 
   let persistedCursor = false;
-  if (typeof polled.cursor === "string" && polled.cursor.trim()) {
-    const result = await writeSyncCursor(sessionId, polled.cursor, { targetPath }).catch(() => null);
+  if (typeof humanResult?.cursor === "string" && humanResult.cursor.trim()) {
+    const result = await writeSyncCursor(sessionId, humanResult.cursor, { targetPath }).catch(() => null);
     persistedCursor = Boolean(result && result.written);
   }
+  if (typeof eventsResult?.cursor === "string" && eventsResult.cursor.trim()) {
+    await writeSyncCursor(sessionId, eventsResult.cursor, {
+      targetPath,
+      suffix: EVENTS_CURSOR_SUFFIX,
+    }).catch(() => null);
+  }
 
   return {
     ok: true,
     reason: "",
     relayed,
-    dropped: Array.isArray(polled.dropped) ? polled.dropped.length : 0,
-    cursor: typeof polled.cursor === "string" ? polled.cursor : startCursor || null,
+    dropped: Array.isArray(humanResult?.dropped) ? humanResult.dropped.length : 0,
+    cursor: typeof humanResult?.cursor === "string" ? humanResult.cursor : humanCursor || null,
     persistedCursor,
+    humanRelayed: (humanResult?.events || []).length,
+    eventsRelayed: (eventsResult?.events || []).length,
+    eventsCursor:
+      typeof eventsResult?.cursor === "string" ? eventsResult.cursor : eventsCursor || null,
   };
 }

package/src/session/sync-cursor.js

@@ -13,8 +13,14 @@ import path from "node:path";
 
 import { resolveSessionDir } from "./paths.js";
 
-function cursorPath(sessionId, { targetPath } = {}) {
-  return path.join(resolveSessionDir(sessionId, { targetPath }), "remote-sync-cursor.json");
+function cursorPath(sessionId, { targetPath, suffix = "" } = {}) {
+  // Multiple cursors per session — the legacy file is human-messages,
+  // and `suffix="events"` tracks the agent-events poller separately
+  // so a stuck or skewed read on one source doesn't block the other.
+  const slug = typeof suffix === "string" && suffix.trim()
+    ? `remote-sync-cursor-${suffix.trim().toLowerCase().replace(/[^a-z0-9-]+/g, "-")}.json`
+    : "remote-sync-cursor.json";
+  return path.join(resolveSessionDir(sessionId, { targetPath }), slug);
 }
 
 /**
@@ -26,9 +32,9 @@ function cursorPath(sessionId, { targetPath } = {}) {
  * @param {{targetPath?: string}} [options]
  * @returns {Promise<string|null>}
  */
-export async function readSyncCursor(sessionId, { targetPath } = {}) {
+export async function readSyncCursor(sessionId, { targetPath, suffix = "" } = {}) {
   if (!sessionId) return null;
-  const filePath = cursorPath(sessionId, { targetPath });
+  const filePath = cursorPath(sessionId, { targetPath, suffix });
   try {
     const raw = await fsp.readFile(filePath, "utf-8");
     const parsed = JSON.parse(raw);
@@ -49,8 +55,8 @@ export async function readSyncCursor(sessionId, { targetPath } = {}) {
  * @param {{targetPath?: string}} [options]
  * @returns {Promise<{written: boolean, path: string}>}
  */
-export async function writeSyncCursor(sessionId, cursor, { targetPath } = {}) {
-  const filePath = cursorPath(sessionId, { targetPath });
+export async function writeSyncCursor(sessionId, cursor, { targetPath, suffix = "" } = {}) {
+  const filePath = cursorPath(sessionId, { targetPath, suffix });
   const normalized = typeof cursor === "string" ? cursor.trim() : "";
   if (!sessionId || !normalized) {
     return { written: false, path: filePath };

package/src/session/sync.js

@@ -735,6 +735,143 @@ export async function pollHumanMessages(
   }
 }
 
+/**
+ * Poll the durable session-events endpoint for ALL events (not just
+ * human-posted ones). Fixes the cross-agent blind spot Carter caught
+ * in the standup session: agents polling via `pollHumanMessages` only
+ * saw web-posted human messages, never each other's `session_message`
+ * / `agent_response` events. The result was codex and claude talking
+ * past each other ("Apologies — I missed your 5 updates").
+ *
+ * Endpoint contract: `GET /api/v1/sessions/{id}/events?after=<cursor>&limit=N`.
+ * The API returns events in chronological order with cursor-based
+ * pagination. We map each row to the local NDJSON envelope shape so
+ * `appendToStream` accepts it without modification.
+ *
+ * @param {string} sessionId
+ * @param {object} [options]
+ * @param {string} [options.targetPath]
+ * @param {string|null} [options.since] - cursor to start after; null = full history
+ * @param {number} [options.limit]      - default 200 (max from API)
+ * @param {number} [options.timeoutMs]  - per-request deadline
+ * @returns {Promise<{ok: boolean, reason: string, events: Array<object>, cursor: string|null}>}
+ */
+export async function pollSessionEvents(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    since = null,
+    limit = 200,
+    timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    resolveAuthSession = resolveActiveAuthSession,
+    fetchImpl = fetchWithTimeout,
+    nowMs = Date.now,
+  } = {}
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return {
+      ok: false,
+      reason: "invalid_session_id",
+      events: [],
+      cursor: normalizeString(since) || null,
+    };
+  }
+
+  const normalizedNowMs = Number(nowMs()) || Date.now();
+  if (isCircuitOpen(inboundCircuit, normalizedNowMs)) {
+    return {
+      ok: false,
+      reason: "circuit_breaker_open",
+      events: [],
+      cursor: normalizeString(since) || null,
+    };
+  }
+
+  let session = null;
+  try {
+    session = await resolveAuthSession({
+      cwd: targetPath,
+      env: process.env,
+      autoRotate: false,
+    });
+  } catch {
+    return {
+      ok: false,
+      reason: "no_session",
+      events: [],
+      cursor: normalizeString(since) || null,
+    };
+  }
+  if (!session || !session.token) {
+    return {
+      ok: false,
+      reason: "not_authenticated",
+      events: [],
+      cursor: normalizeString(since) || null,
+    };
+  }
+
+  const apiBaseUrl = resolveApiBaseUrl(session);
+  const query = new URLSearchParams();
+  const normalizedSince = normalizeString(since);
+  if (normalizedSince) {
+    query.set("after", normalizedSince);
+  }
+  query.set("limit", String(Math.max(1, Math.min(200, normalizePositiveInteger(limit, 200)))));
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/events?${query.toString()}`;
+
+  try {
+    const response = await fetchImpl(
+      endpoint,
+      {
+        method: "GET",
+        headers: { Authorization: `Bearer ${session.token}` },
+      },
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS)
+    );
+    if (!response || !response.ok) {
+      recordCircuitFailure(inboundCircuit, normalizedNowMs);
+      return {
+        ok: false,
+        reason: `api_${response ? response.status : "no_response"}`,
+        events: [],
+        cursor: normalizedSince || null,
+      };
+    }
+    const payload = await response.json().catch(() => ({}));
+    recordCircuitSuccess(inboundCircuit);
+
+    const items = Array.isArray(payload?.events) ? payload.events : [];
+    const acceptedEvents = [];
+    let lastCursor = normalizedSince || null;
+    for (const item of items) {
+      if (!item || typeof item !== "object") continue;
+      const cursor = normalizeString(item.cursor);
+      if (cursor) lastCursor = cursor;
+      // Pass through verbatim — the API already returns the NDJSON
+      // envelope shape that appendToStream expects.
+      acceptedEvents.push(item);
+    }
+
+    return {
+      ok: true,
+      reason: "",
+      events: acceptedEvents,
+      cursor: lastCursor,
+    };
+  } catch (error) {
+    recordCircuitFailure(inboundCircuit, normalizedNowMs);
+    return {
+      ok: false,
+      reason: normalizeString(error?.message) || "poll_failed",
+      events: [],
+      cursor: normalizedSince || null,
+    };
+  }
+}
+
+
 /**
  * List sessions owned by the active user via `GET /api/v1/sessions`.
  *