sentinelayer-cli 0.34.7 → 0.35.0

package/package.json

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

package/src/commands/session.js

@@ -65,6 +65,12 @@ import {
   updateSessionTitle,
 } from "../session/store.js";
 import { fetchSessionListeners, formatListenerLine } from "../session/listeners.js";
+import {
+  getListenerProcessStatus,
+  removeListenerPidRecord,
+  requestListenerProcessStop,
+  writeListenerPidRecord,
+} from "../session/listener-process.js";
 import {
   filterSessionMaterialEvents,
   isSessionControlEvent,
@@ -4538,6 +4544,14 @@ export function registerSessionCommand(program) {
     .option("--from-now", "Advance the listen cursor to the latest durable event before polling")
     .option("--replay", "Emit matching historical events on the first poll")
     .option("--max-polls <n>", "Stop after N poll cycles (useful for tests and smoke checks)")
+    .option(
+      "--force",
+      "Stop and replace an existing local listener process for this session/agent",
+    )
+    .option(
+      "--allow-duplicate",
+      "Allow multiple local listeners for the same session/agent (advanced; can duplicate wake hooks)",
+    )
     .option(
       "--wake <command>",
       "Wake hook: run this shell command on each matched event (notify->resume bridge). Metadata JSON is piped to stdin; sanitized SL_WAKE_* env vars are set.",
@@ -4666,18 +4680,59 @@ export function registerSessionCommand(program) {
       if (options.fromNow && options.since !== undefined) {
         throw new Error("Use either --from-now or --since, not both.");
       }
-      const restoreConsoleLog = listenLogPath
-        ? installRotatingConsoleLog({
-            logPath: listenLogPath,
-            maxBytes: parsePositiveInteger(options.logMaxBytes, "log-max-bytes", DEFAULT_ROTATING_LOG_MAX_BYTES),
-            maxFiles: parsePositiveInteger(options.logMaxFiles, "log-max-files", DEFAULT_ROTATING_LOG_MAX_FILES),
-            tee: true,
-          })
-        : null;
+      const listenerId = `listener-${agentId}-${randomUUID()}`;
+      const singletonEnabled = maxPolls === null && !options.allowDuplicate;
+      let listenerPidRecordActive = false;
+      if (singletonEnabled) {
+        const existingListener = await getListenerProcessStatus(normalizedSessionId, agentId, {
+          targetPath,
+        });
+        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.`,
+          );
+        }
+        if (existingListener.running && options.force) {
+          const stopResult = await requestListenerProcessStop(existingListener.pid);
+          if (!stopResult.stopped) {
+            throw new Error(
+              `Unable to stop existing listener pid ${existingListener.pid} for session ${normalizedSessionId} as ${agentId} (${stopResult.reason}). Stop it manually or use --allow-duplicate if parallel listeners are intentional.`,
+            );
+          }
+        }
+        await writeListenerPidRecord(normalizedSessionId, agentId, {
+          targetPath,
+          listenerId,
+          transport: listenTransport,
+          intervalSeconds,
+          activeIntervalSeconds,
+          presenceIntervalSeconds,
+          logFile: listenLogPath,
+        });
+        listenerPidRecordActive = true;
+      }
+      let restoreConsoleLog = null;
+      try {
+        restoreConsoleLog = listenLogPath
+          ? installRotatingConsoleLog({
+              logPath: listenLogPath,
+              maxBytes: parsePositiveInteger(options.logMaxBytes, "log-max-bytes", DEFAULT_ROTATING_LOG_MAX_BYTES),
+              maxFiles: parsePositiveInteger(options.logMaxFiles, "log-max-files", DEFAULT_ROTATING_LOG_MAX_FILES),
+              tee: true,
+            })
+          : null;
+      } catch (error) {
+        if (listenerPidRecordActive) {
+          await removeListenerPidRecord(normalizedSessionId, agentId, {
+            targetPath,
+            onlyForPid: process.pid,
+          }).catch(() => {});
+        }
+        throw error;
+      }
       const ac = new AbortController();
       const onSigint = () => ac.abort();
       process.on("SIGINT", onSigint);
-      const listenerId = `listener-${agentId}-${randomUUID()}`;
       const durablePresenceEnabled = options.presence !== false;
       const publishPresence = durablePresenceEnabled && canPublishListenerPresence(agentId);
       const presenceIntervalMs = Math.max(1, presenceIntervalSeconds) * 1000;
@@ -4909,6 +4964,12 @@ export function registerSessionCommand(program) {
           restoreConsoleLog();
         }
         process.removeListener("SIGINT", onSigint);
+        if (listenerPidRecordActive) {
+          await removeListenerPidRecord(normalizedSessionId, agentId, {
+            targetPath,
+            onlyForPid: process.pid,
+          }).catch(() => {});
+        }
       }
     });
 

package/src/mcp/registry.js

@@ -563,6 +563,47 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
           server: "sentinelayer-session-mcp",
         },
       },
+      {
+        name: "read_history",
+        title: "Read Senti History",
+        description:
+          "Hydrate a bounded recent, older, or after-cursor SentinelLayer session transcript window without recipient filtering.",
+        input_schema: {
+          type: "object",
+          additionalProperties: false,
+          required: ["sessionId"],
+          properties: {
+            sessionId: { type: "string" },
+            cursor: { type: "string" },
+            beforeSequence: { type: "integer", minimum: 1 },
+            limit: { type: "integer", minimum: 1, maximum: 200 },
+            actionLimit: { type: "integer", minimum: 1, maximum: 200 },
+            includeActions: { type: "boolean" },
+            includeControlEvents: { type: "boolean" },
+          },
+        },
+        transport: {
+          type: "internal",
+          method: "POST",
+          url: "sentinelayer://session/read_history",
+          timeout_ms: 15000,
+          auth: { mode: "none" },
+        },
+        budgets: {
+          max_calls_per_run: 60,
+          max_runtime_ms: 15000,
+        },
+        security: {
+          requires_human_approval: false,
+          kill_switch: "enabled",
+          scopes: ["session:read"],
+        },
+        metadata: {
+          provider: "sentinelayer",
+          adapter: "sentinelayer-cli",
+          server: "sentinelayer-session-mcp",
+        },
+      },
       {
         name: "send_message",
         title: "Send Senti Message",
@@ -985,6 +1026,13 @@ export function buildHostedSentiSessionConnectorContract({
       long_lived_cli_token_passthrough_allowed: false,
     },
     tools: [
+      hostedSessionTool({
+        toolName: "join_and_hydrate",
+        operation: "join_and_hydrate",
+        allowedUserArgs: ["limit", "actionLimit", "includeActions"],
+        requiredScopes: ["session:read"],
+        wakePayload: { policy: "bounded_redacted_window", may_include_message_content: true, max_events: 50 },
+      }),
       hostedSessionTool({
         toolName: "poll_inbox",
         operation: "read_history",
@@ -992,6 +1040,13 @@ export function buildHostedSentiSessionConnectorContract({
         requiredScopes: ["session:read"],
         wakePayload: { policy: "bounded_redacted_window", may_include_message_content: true, max_events: 50 },
       }),
+      hostedSessionTool({
+        toolName: "read_history",
+        operation: "read_history",
+        allowedUserArgs: ["cursor", "beforeSequence", "limit", "actionLimit", "includeActions"],
+        requiredScopes: ["session:read"],
+        wakePayload: { policy: "bounded_redacted_window", may_include_message_content: true, max_events: 50 },
+      }),
       hostedSessionTool({
         toolName: "send_message",
         operation: "send_message",
@@ -1279,7 +1334,7 @@ export function validateHostedSentiSessionConnectorContract(payload, { registryP
     const registry = validateMcpToolRegistry(registryPayload);
     const localToolNames = new Set(registry.tools.map((tool) => tool.name));
     const missingLocalTools = parsed.tools
-      .filter((tool) => tool.operation !== "subscribe_wake" && tool.operation !== "presence_renew" && tool.operation !== "runner_teardown")
+      .filter((tool) => tool.operation !== "join_and_hydrate" && tool.operation !== "subscribe_wake" && tool.operation !== "presence_renew" && tool.operation !== "runner_teardown")
       .map((tool) => tool.local_tool_name)
       .filter((toolName) => !localToolNames.has(toolName));
     if (missingLocalTools.length > 0) {

package/src/mcp/session-stdio-server.js

@@ -31,6 +31,8 @@ const SESSION_MCP_CONFIRM_PAGE_LIMIT = 200;
 const SESSION_MCP_CONFIRM_MAX_PAGES = 10;
 const SESSION_MCP_CONFIRM_TOTAL_TIMEOUT_MS = 10_000;
 const SESSION_MCP_CONFIRM_REQUEST_TIMEOUT_MS = 2_000;
+const SESSION_MCP_HISTORY_MAX_PAGES = 10;
+const SESSION_MCP_HISTORY_MIN_RAW_PAGE_LIMIT = DEFAULT_TOOL_LIMIT;
 const JSON_RPC_VERSION = "2.0";
 const CONTENT_LENGTH_PREFIX = "content-length:";
 const SESSION_MESSAGE_ACTION_TYPES = new Set([
@@ -444,6 +446,110 @@ function recentHumanActivityFromActions(remoteActions = null, { limit = DEFAULT_
     : [];
 }
 
+function normalizeHistoryEvents(events = [], { includeControlEvents = false } = {}) {
+  return (Array.isArray(events) ? events : []).filter((event) => {
+    if (!includeControlEvents && isSessionControlEvent(event)) return false;
+    return true;
+  });
+}
+
+async function readSessionHistoryWindow({
+  sessionId,
+  targetPath,
+  cursor = null,
+  beforeSequence = null,
+  limit = DEFAULT_TOOL_LIMIT,
+  includeControlEvents = false,
+  forceCircuitProbe = false,
+  pollSessionEventsFn = pollSessionEvents,
+  pollSessionEventsBeforeFn = pollSessionEventsBefore,
+} = {}) {
+  const source = cursor ? "after_cursor" : beforeSequence ? "before_sequence" : "latest_tail";
+  let pageCursor = cursor;
+  let pageBeforeSequence = beforeSequence;
+  let responseCursor = cursor;
+  let responseBeforeSequence = beforeSequence || null;
+  let rawEventCount = 0;
+  let pages = 0;
+  let events = [];
+
+  while (events.length < limit && pages < SESSION_MCP_HISTORY_MAX_PAGES) {
+    const remaining = Math.max(1, limit - events.length);
+    const pageLimit = Math.max(
+      remaining,
+      Math.min(MAX_TOOL_LIMIT, SESSION_MCP_HISTORY_MIN_RAW_PAGE_LIMIT),
+    );
+    const result = cursor
+      ? await pollSessionEventsFn(sessionId, {
+          targetPath,
+          since: pageCursor,
+          limit: pageLimit,
+          forceCircuitProbe,
+        })
+      : await pollSessionEventsBeforeFn(sessionId, {
+          targetPath,
+          beforeSequence: pageBeforeSequence,
+          limit: pageLimit,
+          forceCircuitProbe,
+        });
+    if (!result?.ok) {
+      if (pages > 0) break;
+      return {
+        ok: false,
+        reason: result?.reason || "read_history_failed",
+        source,
+        cursor: responseCursor,
+        beforeSequence: responseBeforeSequence,
+        events: [],
+        eventCount: 0,
+        pages,
+      };
+    }
+
+    pages += 1;
+    const rawEvents = Array.isArray(result.events) ? result.events : [];
+    rawEventCount += rawEvents.length;
+    const materialEvents = normalizeHistoryEvents(rawEvents, { includeControlEvents });
+    if (cursor) {
+      events.push(...materialEvents);
+      const nextCursor = normalizeString(result.cursor) || pageCursor;
+      responseCursor = nextCursor || responseCursor;
+      if (!rawEvents.length || !nextCursor || nextCursor === pageCursor) break;
+      pageCursor = nextCursor;
+      continue;
+    }
+
+    events = [...materialEvents, ...events];
+    if (pages === 1) {
+      responseCursor = normalizeString(result.cursor) || responseCursor;
+    }
+    const nextBeforeSequence = normalizePositiveInteger(result.beforeSequence || result.before_sequence, null);
+    responseBeforeSequence = nextBeforeSequence;
+    if (!rawEvents.length || !nextBeforeSequence || nextBeforeSequence === pageBeforeSequence) break;
+    pageBeforeSequence = nextBeforeSequence;
+  }
+
+  const windowEvents = cursor ? events.slice(0, limit) : events.slice(-limit);
+  const firstWindowEvent = windowEvents[0] || null;
+  const lastWindowEvent = windowEvents[windowEvents.length - 1] || null;
+  const windowCursor = normalizeString(lastWindowEvent?.cursor);
+  const windowBeforeSequence = normalizePositiveInteger(
+    firstWindowEvent?.sequenceId ?? firstWindowEvent?.sequence_id,
+    null,
+  );
+
+  return {
+    ok: true,
+    reason: "",
+    source,
+    cursor: windowCursor || responseCursor,
+    beforeSequence: cursor ? null : windowBeforeSequence || responseBeforeSequence,
+    events: windowEvents,
+    eventCount: rawEventCount,
+    pages,
+  };
+}
+
 function requireSessionId(input = {}) {
   const sessionId = normalizeString(input.sessionId || input.session_id || input.session);
   if (!sessionId) {
@@ -807,6 +913,83 @@ export function createSessionMcpToolHandlers({
       };
     },
 
+    async read_history(input = {}) {
+      const sessionId = requireSessionId(input);
+      const cursor = normalizeString(input.cursor || input.after || input.since) || null;
+      const beforeSequence = normalizeOptionalPositiveInteger(
+        input.beforeSequence || input.before_sequence,
+        "beforeSequence",
+      );
+      if (cursor && beforeSequence) {
+        throw new Error("Use either cursor/after/since or beforeSequence, not both.");
+      }
+      const limit = normalizeLimit(input.limit || input.tail || input.maxEvents || input.max_events);
+      const actionLimit = normalizeLimit(input.actionLimit || input.action_limit || limit);
+      const includeActions = input.includeActions !== false && input.include_actions !== false;
+      const includeControlEvents = Boolean(input.includeControlEvents || input.include_control_events);
+      const includeRaw = Boolean(input.includeRaw || input.include_raw);
+      const forceCircuitProbe = input.forceCircuitProbe !== false && input.force_circuit_probe !== false;
+
+      const result = await readSessionHistoryWindow({
+        sessionId,
+        targetPath,
+        cursor,
+        beforeSequence,
+        limit,
+        includeControlEvents,
+        forceCircuitProbe,
+        pollSessionEventsFn,
+        pollSessionEventsBeforeFn,
+      });
+      if (!result?.ok) {
+        return {
+          ok: false,
+          reason: result?.reason || "read_history_failed",
+          sessionId,
+          source: result?.source || (cursor ? "after_cursor" : beforeSequence ? "before_sequence" : "latest_tail"),
+          cursor,
+          beforeSequence: beforeSequence || null,
+          events: [],
+          eventCount: 0,
+          materialEventCount: 0,
+        };
+      }
+
+      const events = Array.isArray(result.events) ? result.events : [];
+      const actionResult = includeActions
+        ? await listSessionMessageActionsFn(sessionId, {
+            targetPath,
+            limit: actionLimit,
+            forceCircuitProbe,
+          })
+        : null;
+      const recentHumanActivity = actionResult?.ok
+        ? recentHumanActivityFromActions(actionResult, { limit: actionLimit })
+        : [];
+
+      return {
+        ok: true,
+        reason: "",
+        sessionId,
+        source: result.source,
+        cursor: normalizeString(result.cursor) || cursor,
+        beforeSequence: normalizePositiveInteger(result.beforeSequence || result.before_sequence, null),
+        eventCount: normalizePositiveInteger(result.eventCount, 0),
+        materialEventCount: events.length,
+        pageCount: normalizePositiveInteger(result.pages, 0),
+        recentHumanActivityCount: recentHumanActivity.length,
+        recentHumanActivity,
+        actionProjection: actionResult
+          ? {
+              ok: Boolean(actionResult.ok),
+              reason: actionResult.reason || "",
+              count: Array.isArray(actionResult.actions) ? actionResult.actions.length : 0,
+            }
+          : null,
+        events: includeRaw ? events : events.map((event) => summarizeSessionEvent(event)),
+      };
+    },
+
     async send_message(input = {}) {
       const sessionId = requireSessionId(input);
       const agentId = requireAgentId(input);
@@ -1013,6 +1196,27 @@ export const SESSION_MCP_TOOLS = Object.freeze([
       },
     },
   },
+  {
+    name: "read_history",
+    title: "Read Senti History",
+    description:
+      "Hydrate a bounded recent, older, or after-cursor session transcript window without recipient filtering.",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      required: ["sessionId"],
+      properties: {
+        sessionId: { type: "string", minLength: 1 },
+        cursor: { type: "string" },
+        beforeSequence: { type: "integer", minimum: 1 },
+        limit: { type: "integer", minimum: 1, maximum: MAX_TOOL_LIMIT, default: DEFAULT_TOOL_LIMIT },
+        actionLimit: { type: "integer", minimum: 1, maximum: MAX_TOOL_LIMIT, default: DEFAULT_TOOL_LIMIT },
+        includeActions: { type: "boolean", default: true },
+        includeControlEvents: { type: "boolean", default: false },
+        includeRaw: { type: "boolean", default: false },
+      },
+    },
+  },
   {
     name: "send_message",
     title: "Send Senti Message",
@@ -1285,7 +1489,7 @@ export async function handleMcpJsonRpcMessage(
         version: "0.20.0",
       },
       instructions:
-        "Use native Senti tools for coordination actions and generated sl.* bridge tools for the rest of SentinelLayer CLI. Poll first with poll_inbox, use session_action/session_react/session_reply/session_lock/session_unlock/session_locks for low-noise session work, use send_message for durable posts, and use generated command tools such as sl.auth.status or sl.review.scan for ordinary CLI commands.",
+        "Use native Senti tools for coordination actions and generated sl.* bridge tools for the rest of SentinelLayer CLI. Use poll_inbox for addressed wake-style delivery, read_history for recent/older transcript grounding, session_action/session_react/session_reply/session_lock/session_unlock/session_locks for low-noise session work, send_message for durable posts, and generated command tools such as sl.auth.status or sl.review.scan for ordinary CLI commands.",
     });
   }
 

package/src/scan/generator.js

@@ -230,18 +230,17 @@ export function buildSecurityReviewWorkflow({ secretName = DEFAULT_SCAN_SECRET_N
               google_api_key:
                 "${{ secrets.GOOGLE_GEMINI_API_KEY != '' && secrets.GOOGLE_GEMINI_API_KEY || secrets.GOOGLE_API_KEY }}",
               llm_provider:
-                "${{ secrets.OPENAI_API_KEY != '' && 'openai' || ((secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'google' || 'openai') }}",
+                "${{ (secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'google' || 'openai' }}",
               sentinelayer_token: `\${{ secrets.${normalizedSecret} }}`,
               sentinelayer_managed_llm: `\${{ secrets.GOOGLE_GEMINI_API_KEY == '' && secrets.GOOGLE_API_KEY == '' && secrets.OPENAI_API_KEY == '' && secrets.${normalizedSecret} != '' }}`,
               scan_mode: profile.scanMode || "deep",
               severity_gate: profile.severityGate || "P1",
               model:
-                "${{ secrets.OPENAI_API_KEY != '' && 'gpt-5.3-codex' || ((secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'gemini-3.1-flash-lite' || 'gpt-5.3-codex') }}",
+                "${{ (secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'gemini-3.1-flash-lite' || 'gpt-5.3-codex' }}",
               codex_model: "gpt-5.3-codex",
               model_fallback:
                 "${{ (secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'gemini-3.1-flash-lite' || 'gpt-4.1-mini' }}",
-              use_codex:
-                "${{ secrets.OPENAI_API_KEY != '' || (secrets.GOOGLE_GEMINI_API_KEY == '' && secrets.GOOGLE_API_KEY == '') }}",
+              use_codex: "${{ secrets.GOOGLE_GEMINI_API_KEY == '' && secrets.GOOGLE_API_KEY == '' }}",
               codex_only: "false",
               llm_failure_policy: "block",
               max_daily_scans: "${{ vars.OMAR_MAX_DAILY_SCANS || '200' }}",
@@ -304,9 +303,9 @@ export function buildSecurityReviewWorkflow({ secretName = DEFAULT_SCAN_SECRET_N
                 "${{ secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '' }}",
               OMAR_MANAGED_LLM: `\${{ secrets.GOOGLE_GEMINI_API_KEY == '' && secrets.GOOGLE_API_KEY == '' && secrets.OPENAI_API_KEY == '' && secrets.${normalizedSecret} != '' }}`,
               OMAR_LLM_PROVIDER:
-                "${{ secrets.OPENAI_API_KEY != '' && 'openai' || ((secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'google' || 'openai') }}",
+                "${{ (secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'google' || 'openai' }}",
               OMAR_MODEL:
-                "${{ secrets.OPENAI_API_KEY != '' && 'gpt-5.3-codex' || ((secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'gemini-3.1-flash-lite' || 'gpt-5.3-codex') }}",
+                "${{ (secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'gemini-3.1-flash-lite' || 'gpt-5.3-codex' }}",
               OMAR_MODEL_FALLBACK:
                 "${{ (secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'gemini-3.1-flash-lite' || 'gpt-4.1-mini' }}",
             },
@@ -353,7 +352,7 @@ export function buildSecurityReviewWorkflow({ secretName = DEFAULT_SCAN_SECRET_N
               "        'llm_provider': env('OMAR_LLM_PROVIDER', 'openai'),",
               "        'model': env('OMAR_MODEL', 'gpt-5.3-codex'),",
               "        'model_fallback': env('OMAR_MODEL_FALLBACK', 'gpt-4.1-mini'),",
-              "        'llm_route': 'openai_api_key' if bool_env('OMAR_OPENAI_KEY_PRESENT') else ('google_api_key' if bool_env('OMAR_GOOGLE_KEY_PRESENT') else 'sentinelayer_managed'),",
+              "        'llm_route': 'google_api_key' if bool_env('OMAR_GOOGLE_KEY_PRESENT') else ('openai_api_key' if bool_env('OMAR_OPENAI_KEY_PRESENT') else 'sentinelayer_managed'),",
               "        'google_key_present': bool_env('OMAR_GOOGLE_KEY_PRESENT'),",
               "        'openai_key_present': bool_env('OMAR_OPENAI_KEY_PRESENT'),",
               "        'managed_llm': bool_env('OMAR_MANAGED_LLM'),",

package/src/session/coordination-guidance.js

@@ -5,7 +5,7 @@ export const COORDINATION_ETIQUETTE_ITEMS = Object.freeze([
   "When you have an agent grant, post agent updates with `sl session post-agent <id> \"status: <update>\" --agent <your-agent-id>` so they render as the agent, not the human relay.",
   "Before implementation, post a short plan and file claims with `sl session say <id> \"plan: <scope>; files: <paths>\"`.",
   "Claim shared files before editing with `lock: <file> - <intent>` and release them with `unlock: <file> - done`.",
-  "Run a background/secondary listener for replies with `sl session listen --session <id> --agent <your-name> --interval 60 --active-interval 5 --emit ndjson --no-presence`; this idles at 60s, switches to 5s after human activity, and avoids durable listener heartbeat noise. `session listen` is only a delivery cursor, not a grounding command; join or recap before acting. For your primary interactive listener, omit `--no-presence` so other participants can see you online. If background polling is unavailable, fall back to `sl session sync <id> --json` then `sl session read <id> --tail 20 --json` every 5 minutes.",
+  "Run one background/secondary listener for replies with `sl session listen --session <id> --agent <your-name> --interval 60 --active-interval 5 --emit ndjson --no-presence`; this idles at 60s, switches to 5s after human activity, and avoids durable listener heartbeat noise. `session listen` now refuses duplicate local listeners for the same session/agent by default; use `--force` only to stop and replace an existing local owner and `--allow-duplicate` only when you intentionally need parallel wake hooks. `session listen` is only a delivery cursor, not a grounding command; join or recap before acting. For your primary interactive listener, omit `--no-presence` so other participants can see you online. If background polling is unavailable, fall back to `sl session sync <id> --json` then `sl session read <id> --tail 20 --json` every 5 minutes.",
   "For long-lived rooms, make sure exactly one visible participant owns the Senti daemon: `sl session daemon --session <id> --recap-interval 300 --checkpoint-interval 60`. If no durable recap/checkpoint is appearing, run `sl session recap now <id> --remote --agent <your-name> --json` before posting a long plan.",
   "Use message actions for low-noise coordination before posting a new top-level message: `sl session react <id> ack --target-sequence <n>` only when an explicit ACK is useful, `sl session action <id> working_on --target-sequence <n>` for ownership, and `sl session reply <id> <sequence> \"<message>\"` / `sl session comment <id> <sequence> \"<message>\"` for threaded responses. Read receipts are automatic when you use `sl session read <id> --remote --agent <your-name>`; reserve `sl session view <id> <sequence>` for repair/backfill. Run `sl session actions` for the full list.",
   "Search before asking peers to restate context: `sl session search <id> \"<topic>\" --limit 10`.",

package/src/session/first-message.js

@@ -38,7 +38,7 @@ export function buildFirstSentiMessage({ sessionId } = {}) {
     `7) sl session reply ${sid} <THIS_SEQ> "ACK <AGENT_ID> role=<role> model=<model> locks=none first_action=<one concrete action>" --agent <AGENT_ID>`,
     "",
     "STAY REACHABLE — two honest paths, use YOURS (always pass --agent <AGENT_ID> so the room knows who's listening):",
-    `- Persistent process (Codex/GPT): keep ONE listener alive + a 60s watchdog that restarts it if the pid dies (cursor catch-up replays anything missed):`,
+    `- Persistent process (Codex/GPT): keep ONE listener alive. Re-running listen refuses a duplicate local pid by default; use --force only to stop and replace an existing local owner and --allow-duplicate only for intentional parallel wake hooks. Pair it with a 60s watchdog that restarts it if the pid dies (cursor catch-up replays anything missed):`,
     `  sl session listen --session ${sid} --agent <AGENT_ID> --active-interval 30 --active-window 300 --interval 60 --presence-interval 60 --model <MODEL> --display-name <AGENT_ID>`,
     `- No socket (Claude Code): you are NOT continuously connected — you re-arm a wake each turn. 30-270s while actively waiting, 20-30min idle when quiet. Treat time-critical things as POSTED messages you catch next tick, never assumed instant.`,
     `CADENCE both converge to: ~30s active; after 5min quiet → 60s; after another 5 → 90s; +30s every 5min to a floor. Wake IMMEDIATELY on: new human/ORCH msg, a direct reply/@mention, a lock conflict, a deploy/gate notice.`,

package/src/session/listener-process.js

@@ -0,0 +1,259 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { execFile } from "node:child_process";
+import { setTimeout as sleep } from "node:timers/promises";
+import { promisify } from "node:util";
+
+import { isProcessAlive } from "./daemon-spawn.js";
+import { resolveSessionPaths } from "./paths.js";
+
+const LISTENER_DIR_NAME = "listeners";
+const execFileAsync = promisify(execFile);
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+export function normalizeListenerProcessKey(agentId = "") {
+  return (
+    normalizeString(agentId)
+      .toLowerCase()
+      .replace(/[^a-z0-9._-]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "agent"
+  );
+}
+
+function normalizeCommandLine(value) {
+  return normalizeString(value).toLowerCase();
+}
+
+function listenerCommandLineMatches(commandLine, { sessionId = "", agentId = "" } = {}) {
+  const normalized = normalizeCommandLine(commandLine);
+  if (!normalized) return false;
+  const normalizedSessionId = normalizeString(sessionId).toLowerCase();
+  const normalizedAgentId = normalizeString(agentId).toLowerCase();
+  const hasCliEntry =
+    normalized.includes("sentinelayer-cli") ||
+    /[\\/](?:sl|sentinelayer-cli)\.js\b/.test(normalized);
+  return (
+    hasCliEntry &&
+    normalized.includes("session") &&
+    normalized.includes("listen") &&
+    (!normalizedSessionId || normalized.includes(normalizedSessionId)) &&
+    (!normalizedAgentId || normalized.includes(normalizedAgentId))
+  );
+}
+
+async function readWindowsCommandLine(pid) {
+  const command = [
+    "$ErrorActionPreference = 'Stop';",
+    `$p = Get-CimInstance Win32_Process -Filter "ProcessId = ${Number(pid)}";`,
+    "if ($p) { $p.CommandLine }",
+  ].join(" ");
+  const { stdout } = await execFileAsync(
+    "powershell.exe",
+    ["-NoProfile", "-NonInteractive", "-Command", command],
+    { windowsHide: true, timeout: 2000 },
+  );
+  return normalizeString(stdout);
+}
+
+async function readPosixCommandLine(pid) {
+  if (process.platform === "linux") {
+    try {
+      const raw = await fsp.readFile(`/proc/${Number(pid)}/cmdline`);
+      return normalizeString(raw.toString("utf8").replace(/\0/g, " "));
+    } catch {
+      // Fall through to ps(1), which also covers restricted /proc mounts.
+    }
+  }
+  const { stdout } = await execFileAsync("ps", ["-p", String(Number(pid)), "-o", "command="], {
+    timeout: 2000,
+  });
+  return normalizeString(stdout);
+}
+
+export async function readProcessCommandLine(pid) {
+  const numericPid = Number(pid);
+  if (!Number.isInteger(numericPid) || numericPid <= 0) return "";
+  try {
+    return process.platform === "win32"
+      ? await readWindowsCommandLine(numericPid)
+      : await readPosixCommandLine(numericPid);
+  } catch {
+    return "";
+  }
+}
+
+export function resolveListenerPidPath(
+  sessionId,
+  agentId,
+  { targetPath = process.cwd() } = {},
+) {
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  return path.join(
+    paths.sessionDir,
+    LISTENER_DIR_NAME,
+    `${normalizeListenerProcessKey(agentId)}.json`,
+  );
+}
+
+export async function readListenerPidRecord(
+  sessionId,
+  agentId,
+  { targetPath = process.cwd() } = {},
+) {
+  const pidPath = resolveListenerPidPath(sessionId, agentId, { targetPath });
+  try {
+    const raw = await fsp.readFile(pidPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeListenerPidRecord(
+  sessionId,
+  agentId,
+  {
+    targetPath = process.cwd(),
+    pid = process.pid,
+    listenerId = "",
+    transport = "",
+    intervalSeconds = null,
+    activeIntervalSeconds = null,
+    presenceIntervalSeconds = null,
+    logFile = "",
+  } = {},
+) {
+  const pidPath = resolveListenerPidPath(sessionId, agentId, { targetPath });
+  const record = {
+    pid: Number(pid),
+    sessionId: normalizeString(sessionId),
+    agentId: normalizeString(agentId),
+    listenerKey: normalizeListenerProcessKey(agentId),
+    listenerId: normalizeString(listenerId),
+    targetPath: path.resolve(String(targetPath || ".")),
+    transport: normalizeString(transport) || undefined,
+    intervalSeconds: Number(intervalSeconds) || undefined,
+    activeIntervalSeconds: Number(activeIntervalSeconds) || undefined,
+    presenceIntervalSeconds: Number(presenceIntervalSeconds) || undefined,
+    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");
+  return record;
+}
+
+export async function removeListenerPidRecord(
+  sessionId,
+  agentId,
+  { targetPath = process.cwd(), onlyForPid = null } = {},
+) {
+  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;
+  }
+}
+
+export async function getListenerProcessStatus(
+  sessionId,
+  agentId,
+  { targetPath = process.cwd(), _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 {
+      running: false,
+      pid: null,
+      stale: true,
+      record,
+      listenerKey: normalizeListenerProcessKey(agentId),
+    };
+  }
+  const commandLine = await _readProcessCommandLine(record.pid);
+  if (!listenerCommandLineMatches(commandLine, { sessionId, agentId })) {
+    return {
+      running: false,
+      pid: null,
+      stale: true,
+      reused: Boolean(commandLine),
+      unverified: !commandLine,
+      record,
+      listenerKey: normalizeListenerProcessKey(agentId),
+      commandLine,
+    };
+  }
+  return {
+    running: true,
+    pid: Number(record.pid),
+    stale: false,
+    record,
+    listenerKey: normalizeListenerProcessKey(agentId),
+    commandLine,
+  };
+}
+
+export async function requestListenerProcessStop(
+  pid,
+  { signal = "SIGTERM", timeoutMs = 3000, pollIntervalMs = 100 } = {},
+) {
+  const numericPid = Number(pid);
+  if (!Number.isInteger(numericPid) || numericPid <= 0) {
+    return { requested: false, stopped: true, reason: "invalid_pid" };
+  }
+  if (numericPid === process.pid) {
+    return { requested: false, stopped: false, reason: "self" };
+  }
+  if (!isProcessAlive(numericPid)) {
+    return { requested: false, stopped: true, reason: "not_running" };
+  }
+
+  try {
+    process.kill(numericPid, signal);
+  } catch (error) {
+    if (error?.code === "ESRCH") {
+      return { requested: false, stopped: true, reason: "not_running" };
+    }
+    return {
+      requested: false,
+      stopped: false,
+      reason: normalizeString(error?.code) || "signal_failed",
+    };
+  }
+
+  const deadlineMs = Date.now() + Math.max(1, Number(timeoutMs) || 3000);
+  const sleepMs = Math.max(10, Number(pollIntervalMs) || 100);
+  while (Date.now() < deadlineMs) {
+    if (!isProcessAlive(numericPid)) {
+      return { requested: true, stopped: true, reason: "stopped" };
+    }
+    await sleep(sleepMs);
+  }
+  return { requested: true, stopped: false, reason: "timeout" };
+}

package/src/session/listener.js

@@ -305,6 +305,8 @@ export async function listenSessionEvents({
   const activeWindowMs =
     Math.max(1, normalizePositiveInteger(activeWindowSeconds, DEFAULT_ACTIVE_WINDOW_SECONDS)) *
     1000;
+  const autoStreamIdleTimeoutMs =
+    normalizedTransport === "auto" ? Math.max(5_000, Math.min(idleSleepMs, 30_000)) : 0;
 
   if (fromNow) {
     const latest = await _pollLatest(normalizedSessionId, {
@@ -507,9 +509,6 @@ export async function listenSessionEvents({
         streamHeartbeatInFlight = false;
       }
     }, streamHeartbeatMs);
-    if (streamHeartbeatTimer && typeof streamHeartbeatTimer.unref === "function") {
-      streamHeartbeatTimer.unref();
-    }
   }
 
   await notifyLifecycle(
@@ -527,6 +526,7 @@ export async function listenSessionEvents({
       const streamResult = await _stream(normalizedSessionId, {
         targetPath,
         since: cursor,
+        idleTimeoutMs: autoStreamIdleTimeoutMs,
         signal,
         onEvent: async (event) => {
           await processEventBatch([event], normalizeString(event?.cursor) || cursor);

package/src/session/listeners.js

@@ -147,9 +147,15 @@ export function summarizeListeners(events = [], { nowMs = Date.now(), staleAfter
  */
 export async function fetchSessionListeners(
   sessionId,
-  { targetPath = process.cwd(), limit = 200, nowMs = Date.now, poll = pollSessionEventsBefore } = {}
+  {
+    targetPath = process.cwd(),
+    limit = 200,
+    nowMs = Date.now,
+    forceCircuitProbe = true,
+    poll = pollSessionEventsBefore,
+  } = {}
 ) {
-  const result = await poll(sessionId, { targetPath, limit });
+  const result = await poll(sessionId, { targetPath, limit, forceCircuitProbe });
   if (!result?.ok) {
     return { ok: false, reason: normalizeString(result?.reason) || "fetch_failed", listeners: [] };
   }

package/src/session/sync.js

@@ -1479,6 +1479,7 @@ export async function pollSessionEvents(
  * @param {object} [options]
  * @param {string|null} [options.since] - durable cursor to resume after
  * @param {AbortSignal} [options.signal]
+ * @param {number} [options.idleTimeoutMs] - abort a connected stream after this many silent milliseconds
  * @param {(event: object) => Promise<void>|void} [options.onEvent]
  * @param {(payload: object) => Promise<void>|void} [options.onError]
  * @param {() => Promise<void>|void} [options.onHeartbeat]
@@ -1490,6 +1491,7 @@ export async function streamSessionEvents(
     targetPath = process.cwd(),
     since = null,
     timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    idleTimeoutMs = 0,
     signal = undefined,
     resolveAuthSession = resolveActiveAuthSession,
     fetchImpl = fetch,
@@ -1545,10 +1547,26 @@ export async function streamSessionEvents(
   const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/stream${suffix}`;
   const controller = new AbortController();
   const normalizedTimeoutMs = normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS);
+  const normalizedIdleTimeoutMs = normalizePositiveInteger(idleTimeoutMs, 0);
   const timeoutHandle = setTimeout(() => controller.abort(), normalizedTimeoutMs);
   if (typeof timeoutHandle.unref === "function") {
     timeoutHandle.unref();
   }
+  let idleTimeoutHandle = null;
+  let idleTimedOut = false;
+  const clearIdleTimeout = () => {
+    if (!idleTimeoutHandle) return;
+    clearTimeout(idleTimeoutHandle);
+    idleTimeoutHandle = null;
+  };
+  const armIdleTimeout = () => {
+    if (!normalizedIdleTimeoutMs) return;
+    clearIdleTimeout();
+    idleTimeoutHandle = setTimeout(() => {
+      idleTimedOut = true;
+      controller.abort();
+    }, normalizedIdleTimeoutMs);
+  };
   const forwardAbort = () => controller.abort(signal?.reason);
   if (signal) {
     if (signal.aborted) {
@@ -1574,10 +1592,13 @@ export async function streamSessionEvents(
     );
   } catch (error) {
     clearTimeout(timeoutHandle);
+    clearIdleTimeout();
     if (signal) signal.removeEventListener("abort", forwardAbort);
     return {
       ok: false,
-      reason: isAbortLike(error) || signal?.aborted ? "aborted" : normalizeString(error?.message) || "stream_failed",
+      reason: idleTimedOut
+        ? "stream_idle_timeout"
+        : isAbortLike(error) || signal?.aborted ? "aborted" : normalizeString(error?.message) || "stream_failed",
       cursor: normalizedSince,
       eventCount: 0,
       errorCount: 0,
@@ -1621,7 +1642,9 @@ export async function streamSessionEvents(
       };
     }
 
+    armIdleTimeout();
     for await (const chunk of readResponseTextChunks(response)) {
+      armIdleTimeout();
       buffer += decoder.decode(chunk, { stream: true });
       buffer = buffer.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
       const blocks = buffer.split("\n\n");
@@ -1637,13 +1660,16 @@ export async function streamSessionEvents(
   } catch (error) {
     return {
       ok: false,
-      reason: isAbortLike(error) || signal?.aborted ? "aborted" : normalizeString(error?.message) || "stream_failed",
+      reason: idleTimedOut
+        ? "stream_idle_timeout"
+        : isAbortLike(error) || signal?.aborted ? "aborted" : normalizeString(error?.message) || "stream_failed",
       cursor,
       eventCount,
       errorCount,
       aborted: Boolean(signal?.aborted || isAbortLike(error)),
     };
   } finally {
+    clearIdleTimeout();
     if (signal) signal.removeEventListener("abort", forwardAbort);
   }