sentinelayer-cli 0.35.0 → 0.35.1

package/package.json

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

package/src/commands/session.js

@@ -4401,6 +4401,7 @@ export function registerSessionCommand(program) {
     )
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--limit <n>", "Recent events to scan for heartbeats (default 200)", "200")
+    .option("--max-pages <n>", "Maximum older event pages to scan for heartbeats (default 5)", "5")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, options, command) => {
       const normalizedSessionId = normalizeString(sessionId);
@@ -4410,7 +4411,12 @@ export function registerSessionCommand(program) {
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
       await ensureLocalSessionForRemoteCommand(normalizedSessionId, { targetPath });
       const limit = parsePositiveInteger(options.limit, "limit", 200);
-      const result = await fetchSessionListeners(normalizedSessionId, { targetPath, limit });
+      const maxPages = parsePositiveInteger(options.maxPages, "max-pages", 5);
+      const result = await fetchSessionListeners(normalizedSessionId, {
+        targetPath,
+        limit,
+        maxPages,
+      });
       const listeners = Array.isArray(result.listeners) ? result.listeners : [];
       const live = listeners.filter((row) => row.status === "active" || row.status === "idle").length;
       const payload = {
@@ -4420,6 +4426,11 @@ export function registerSessionCommand(program) {
         reason: result.ok ? undefined : result.reason,
         count: listeners.length,
         liveCount: live,
+        pageCount: Number(result.pageCount || 0),
+        scannedEventCount: Number(result.scannedEventCount || 0),
+        listenerEventCount: Number(result.listenerEventCount || 0),
+        partial: Boolean(result.partial),
+        beforeSequence: result.beforeSequence || null,
         listeners,
       };
       if (shouldEmitJson(options, command)) {
@@ -4689,7 +4700,7 @@ export function registerSessionCommand(program) {
         });
         if (existingListener.running && !options.force) {
           throw new Error(
-            `A local session listener is already running for session ${normalizedSessionId} as ${agentId} (pid ${existingListener.pid}). Use --force to take over or --allow-duplicate if you intentionally need more than one.`,
+            `A session listener is already running for session ${normalizedSessionId} as ${agentId} (pid ${existingListener.pid}). Use --force to take over or --allow-duplicate if you intentionally need more than one.`,
           );
         }
         if (existingListener.running && options.force) {

package/src/session/listener-process.js

@@ -1,4 +1,5 @@
 import fsp from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { execFile } from "node:child_process";
@@ -9,6 +10,7 @@ import { isProcessAlive } from "./daemon-spawn.js";
 import { resolveSessionPaths } from "./paths.js";
 
 const LISTENER_DIR_NAME = "listeners";
+const GLOBAL_LISTENER_DIR_NAME = "session-listeners";
 const execFileAsync = promisify(execFile);
 
 function normalizeString(value) {
@@ -99,12 +101,21 @@ export function resolveListenerPidPath(
   );
 }
 
-export async function readListenerPidRecord(
+export function resolveGlobalListenerPidPath(
   sessionId,
   agentId,
-  { targetPath = process.cwd() } = {},
+  { homeDir = os.homedir() } = {},
 ) {
-  const pidPath = resolveListenerPidPath(sessionId, agentId, { targetPath });
+  return path.join(
+    path.resolve(String(homeDir || os.homedir())),
+    ".sentinelayer",
+    GLOBAL_LISTENER_DIR_NAME,
+    normalizeListenerProcessKey(sessionId),
+    `${normalizeListenerProcessKey(agentId)}.json`,
+  );
+}
+
+async function readPidRecordAtPath(pidPath) {
   try {
     const raw = await fsp.readFile(pidPath, "utf-8");
     const parsed = JSON.parse(raw);
@@ -117,6 +128,44 @@ export async function readListenerPidRecord(
   }
 }
 
+async function writePidRecordAtPath(pidPath, record) {
+  await fsp.mkdir(path.dirname(pidPath), { recursive: true });
+  await fsp.writeFile(pidPath, `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+}
+
+async function removePidRecordAtPath(pidPath, { onlyForPid = null } = {}) {
+  if (onlyForPid != null) {
+    const existing = await readPidRecordAtPath(pidPath);
+    if (existing && Number(existing.pid) !== Number(onlyForPid)) {
+      return false;
+    }
+  }
+  try {
+    await fsp.unlink(pidPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readListenerPidRecord(
+  sessionId,
+  agentId,
+  { targetPath = process.cwd() } = {},
+) {
+  const pidPath = resolveListenerPidPath(sessionId, agentId, { targetPath });
+  return readPidRecordAtPath(pidPath);
+}
+
+export async function readGlobalListenerPidRecord(
+  sessionId,
+  agentId,
+  { homeDir = os.homedir() } = {},
+) {
+  const pidPath = resolveGlobalListenerPidPath(sessionId, agentId, { homeDir });
+  return readPidRecordAtPath(pidPath);
+}
+
 export async function writeListenerPidRecord(
   sessionId,
   agentId,
@@ -129,9 +178,11 @@ export async function writeListenerPidRecord(
     activeIntervalSeconds = null,
     presenceIntervalSeconds = null,
     logFile = "",
+    homeDir = os.homedir(),
   } = {},
 ) {
   const pidPath = resolveListenerPidPath(sessionId, agentId, { targetPath });
+  const globalPidPath = resolveGlobalListenerPidPath(sessionId, agentId, { homeDir });
   const record = {
     pid: Number(pid),
     sessionId: normalizeString(sessionId),
@@ -146,46 +197,42 @@ export async function writeListenerPidRecord(
     logFile: normalizeString(logFile) || undefined,
     startedAt: new Date().toISOString(),
   };
-  await fsp.mkdir(path.dirname(pidPath), { recursive: true });
-  await fsp.writeFile(pidPath, `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+  const globalRecord = {
+    ...record,
+    recordScope: "global",
+    localPidPath: pidPath,
+  };
+  await writePidRecordAtPath(globalPidPath, globalRecord);
+  try {
+    await writePidRecordAtPath(pidPath, record);
+  } catch (error) {
+    await removePidRecordAtPath(globalPidPath, { onlyForPid: pid }).catch(() => {});
+    throw error;
+  }
   return record;
 }
 
 export async function removeListenerPidRecord(
   sessionId,
   agentId,
-  { targetPath = process.cwd(), onlyForPid = null } = {},
+  { targetPath = process.cwd(), onlyForPid = null, homeDir = os.homedir() } = {},
 ) {
   const pidPath = resolveListenerPidPath(sessionId, agentId, { targetPath });
-  if (onlyForPid != null) {
-    const existing = await readListenerPidRecord(sessionId, agentId, { targetPath });
-    if (existing && Number(existing.pid) !== Number(onlyForPid)) {
-      return false;
-    }
-  }
-  try {
-    await fsp.unlink(pidPath);
-    return true;
-  } catch {
-    return false;
-  }
+  const globalPidPath = resolveGlobalListenerPidPath(sessionId, agentId, { homeDir });
+  const localRemoved = await removePidRecordAtPath(pidPath, { onlyForPid });
+  const globalRemoved = await removePidRecordAtPath(globalPidPath, { onlyForPid });
+  return Boolean(localRemoved || globalRemoved);
 }
 
-export async function getListenerProcessStatus(
-  sessionId,
-  agentId,
-  { targetPath = process.cwd(), _readProcessCommandLine = readProcessCommandLine } = {},
+async function listenerStatusFromRecord(
+  record,
+  {
+    sessionId,
+    agentId,
+    recordScope,
+    _readProcessCommandLine = readProcessCommandLine,
+  } = {},
 ) {
-  const record = await readListenerPidRecord(sessionId, agentId, { targetPath });
-  if (!record) {
-    return {
-      running: false,
-      pid: null,
-      stale: false,
-      record: null,
-      listenerKey: normalizeListenerProcessKey(agentId),
-    };
-  }
   const alive = isProcessAlive(record.pid);
   if (!alive) {
     return {
@@ -193,6 +240,7 @@ export async function getListenerProcessStatus(
       pid: null,
       stale: true,
       record,
+      recordScope,
       listenerKey: normalizeListenerProcessKey(agentId),
     };
   }
@@ -205,6 +253,7 @@ export async function getListenerProcessStatus(
       reused: Boolean(commandLine),
       unverified: !commandLine,
       record,
+      recordScope,
       listenerKey: normalizeListenerProcessKey(agentId),
       commandLine,
     };
@@ -214,11 +263,57 @@ export async function getListenerProcessStatus(
     pid: Number(record.pid),
     stale: false,
     record,
+    recordScope,
     listenerKey: normalizeListenerProcessKey(agentId),
     commandLine,
   };
 }
 
+export async function getListenerProcessStatus(
+  sessionId,
+  agentId,
+  {
+    targetPath = process.cwd(),
+    homeDir = os.homedir(),
+    _readProcessCommandLine = readProcessCommandLine,
+  } = {},
+) {
+  const records = [
+    {
+      record: await readGlobalListenerPidRecord(sessionId, agentId, { homeDir }),
+      recordScope: "global",
+    },
+    {
+      record: await readListenerPidRecord(sessionId, agentId, { targetPath }),
+      recordScope: "local",
+    },
+  ];
+  const staleStatuses = [];
+  for (const entry of records) {
+    if (!entry.record) continue;
+    const status = await listenerStatusFromRecord(entry.record, {
+      sessionId,
+      agentId,
+      recordScope: entry.recordScope,
+      _readProcessCommandLine,
+    });
+    if (status.running) {
+      return status;
+    }
+    staleStatuses.push(status);
+  }
+  if (staleStatuses.length === 0) {
+    return {
+      running: false,
+      pid: null,
+      stale: false,
+      record: null,
+      listenerKey: normalizeListenerProcessKey(agentId),
+    };
+  }
+  return staleStatuses[0];
+}
+
 export async function requestListenerProcessStop(
   pid,
   { signal = "SIGTERM", timeoutMs = 3000, pollIntervalMs = 100 } = {},

package/src/session/listeners.js

@@ -10,6 +10,9 @@ const LISTENER_EVENT_TYPES = new Set([
 // listener likely died without a clean stop — show it as stale, not live.
 const DEFAULT_STALE_AFTER_MS = 180_000;
 const MAX_STALE_GRACE_MS = 60_000;
+const DEFAULT_LISTENER_FETCH_LIMIT = 200;
+const DEFAULT_LISTENER_FETCH_MAX_PAGES = 5;
+const MAX_LISTENER_FETCH_MAX_PAGES = 25;
 
 function normalizeString(value) {
   return String(value || "").trim();
@@ -143,24 +146,93 @@ export function summarizeListeners(events = [], { nowMs = Date.now(), staleAfter
 
 /**
  * Fetch recent session events from the API and summarize the listeners.
- * `limit` controls how far back we look for heartbeats.
+ * `limit` controls the raw API page size. Busy rooms can push durable
+ * keepalive heartbeats out of a single tail page, so we walk a small bounded
+ * number of older pages while the tail contains no listener lifecycle events
+ * and the sequence cursor advances.
  */
 export async function fetchSessionListeners(
   sessionId,
   {
     targetPath = process.cwd(),
-    limit = 200,
+    limit = DEFAULT_LISTENER_FETCH_LIMIT,
+    maxPages = DEFAULT_LISTENER_FETCH_MAX_PAGES,
     nowMs = Date.now,
     forceCircuitProbe = true,
     poll = pollSessionEventsBefore,
   } = {}
 ) {
-  const result = await poll(sessionId, { targetPath, limit, forceCircuitProbe });
-  if (!result?.ok) {
-    return { ok: false, reason: normalizeString(result?.reason) || "fetch_failed", listeners: [] };
+  const pageLimit = Math.max(
+    1,
+    Math.min(DEFAULT_LISTENER_FETCH_LIMIT, positiveInt(limit) || DEFAULT_LISTENER_FETCH_LIMIT),
+  );
+  const maxPageCount = Math.max(
+    1,
+    Math.min(MAX_LISTENER_FETCH_MAX_PAGES, positiveInt(maxPages) || DEFAULT_LISTENER_FETCH_MAX_PAGES),
+  );
+  let beforeSequence = null;
+  let latestResult = null;
+  let allEvents = [];
+  let pageCount = 0;
+  let listenerEventCount = 0;
+  let partial = false;
+  let partialReason = "";
+
+  for (let page = 0; page < maxPageCount; page += 1) {
+    const result = await poll(sessionId, {
+      targetPath,
+      beforeSequence,
+      limit: pageLimit,
+      forceCircuitProbe,
+    });
+    pageCount += 1;
+
+    if (!result?.ok) {
+      if (!latestResult) {
+        return {
+          ok: false,
+          reason: normalizeString(result?.reason) || "fetch_failed",
+          listeners: [],
+          pageCount,
+          scannedEventCount: allEvents.length,
+          listenerEventCount: 0,
+          partial: false,
+        };
+      }
+      partial = true;
+      partialReason = normalizeString(result?.reason) || "partial_fetch";
+      break;
+    }
+
+    latestResult = result;
+    const pageEvents = Array.isArray(result.events) ? result.events : [];
+    allEvents = [...pageEvents, ...allEvents];
+    listenerEventCount += pageEvents.filter((event) =>
+      LISTENER_EVENT_TYPES.has(normalizeString(event?.event))
+    ).length;
+
+    if (pageEvents.length < pageLimit) break;
+    if (listenerEventCount > 0) break;
+
+    const candidateBeforeSequence = Number(result.beforeSequence || 0);
+    if (!Number.isFinite(candidateBeforeSequence) || candidateBeforeSequence <= 0) break;
+    const currentBeforeSequence = Number(beforeSequence || 0);
+    if (currentBeforeSequence > 0 && candidateBeforeSequence >= currentBeforeSequence) break;
+    beforeSequence = Math.floor(candidateBeforeSequence);
   }
-  const listeners = summarizeListeners(result.events || [], { nowMs: nowMs() });
-  return { ok: true, sessionId: normalizeString(sessionId), listeners };
+
+  const listeners = summarizeListeners(allEvents, { nowMs: nowMs() });
+  return {
+    ok: true,
+    sessionId: normalizeString(sessionId),
+    listeners,
+    pageCount,
+    scannedEventCount: allEvents.length,
+    listenerEventCount,
+    beforeSequence: latestResult?.beforeSequence || beforeSequence || null,
+    partial,
+    reason: partial ? partialReason : "",
+  };
 }
 
 export function formatListenerLine(row) {