sentinelayer-cli 0.8.12 → 0.9.0

package/src/commands/legacy-args.js

@@ -59,7 +59,11 @@ export function buildLegacyArgs(baseArgs, { commandOptions = {}, command } = {})
   appendPassthroughFlag(args, "--provider", commandOptions.provider);
   appendPassthroughFlag(args, "--reuse-omargate", commandOptions.reuseOmargate);
   appendPassthroughFlag(args, "--notify-email", commandOptions.notifyEmail);
+  appendPassthroughFlag(args, "--email-on-complete", commandOptions.emailOnComplete);
   appendPassthroughFlag(args, "--notify-session", commandOptions.notifySession);
+  appendPassthroughFlag(args, "--devtestbot-base-url", commandOptions.devtestbotBaseUrl);
+  appendPassthroughFlag(args, "--devtestbot-scope", commandOptions.devtestbotScope);
+  appendNegatedBooleanFlag(args, "--no-devtestbot", commandOptions.devtestbot);
   // Omar Gate per-persona filter flags (A-CLI-1).
   appendPassthroughFlag(args, "--persona", commandOptions.persona);
   appendPassthroughFlag(args, "--skip-persona", commandOptions.skipPersona);

package/src/commands/omargate.js

@@ -48,9 +48,13 @@ export function registerOmarGateCommand(program, invokeLegacy) {
     .option("--skip-persona <csv>", "Skip these personas (comma-separated IDs)")
     .option("--stream", "Emit NDJSON events to stdout as personas work file-by-file")
     .option("--notify-email <addr>", "Send final report to this email (default: account email)")
+    .option("--email-on-complete <addr>", "Trigger the API-side DD report email after the run completes")
     .option("--notify-session <session-id>", "Stream progress into this Senti session (default: auto-start)")
     .option("--no-email", "Skip email dispatch")
     .option("--no-dashboard", "Skip dashboard card persistence")
+    .option("--devtestbot-base-url <url>", "Approved absolute URL for devTestBot browser lanes")
+    .option("--devtestbot-scope <scope>", "devTestBot runtime scope (default: orchestrator decides)")
+    .option("--no-devtestbot", "Skip the automated devTestBot phase")
     .option("--dry-run", "Validate config + emit plan.json; skip LLM calls")
     .option("--json", "Emit machine-readable final output")
     .action(async (options, command) => {

package/src/commands/session.js

@@ -47,6 +47,7 @@ import {
   listActiveSessions,
   listAllSessions,
   recordSessionProvisionedIdentities,
+  updateSessionTitle,
 } from "../session/store.js";
 import { appendToStream, readStream, tailStream } from "../session/stream.js";
 import { readSessionPreview } from "../session/preview.js";
@@ -57,6 +58,7 @@ import {
 } from "../session/sync.js";
 import { hydrateSessionFromRemote } from "../session/remote-hydrate.js";
 import { mergeLiveSources } from "../session/live-source.js";
+import { listenSessionEvents } from "../session/listener.js";
 import { deriveSessionTitle } from "../session/senti-naming.js";
 import {
   buildDashboardUrl,
@@ -89,6 +91,233 @@ function parsePositiveInteger(rawValue, field, fallbackValue) {
   return Math.floor(normalized);
 }
 
+function normalizeComparablePath(value) {
+  return String(value || "")
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/\/+$/g, "")
+    .toLowerCase();
+}
+
+function latestSessionActivityMs(entry = {}) {
+  for (const key of ["lastInteractionAt", "lastActivityAt", "createdAt"]) {
+    const epoch = Date.parse(normalizeString(entry[key]));
+    if (Number.isFinite(epoch)) return epoch;
+  }
+  return 0;
+}
+
+function remoteSessionLookupDisabled() {
+  return String(process.env.SENTINELAYER_SKIP_REMOTE_SYNC || "").trim() === "1";
+}
+
+function mergeResumeCandidate(existing, incoming) {
+  if (!existing) return incoming;
+  const existingActivity = Number(existing._activityMs || 0);
+  const incomingActivity = Number(incoming._activityMs || 0);
+  const preferIncomingPaths = existing._source !== "local" && incoming._source === "local";
+  const base = preferIncomingPaths ? incoming : existing;
+  const other = preferIncomingPaths ? existing : incoming;
+  return {
+    ...base,
+    title: normalizeString(base.title) || normalizeString(other.title) || null,
+    lastActivityAt:
+      normalizeString(incoming.lastActivityAt) || normalizeString(existing.lastActivityAt) || null,
+    lastInteractionAt:
+      normalizeString(incoming.lastInteractionAt) || normalizeString(existing.lastInteractionAt) || null,
+    _activityMs: Math.max(existingActivity, incomingActivity),
+  };
+}
+
+async function findReusableSessionCandidate({
+  targetPath,
+  reuseWindowSeconds = 3600,
+  resume = true,
+  forceNew = false,
+} = {}) {
+  if (forceNew || resume === false) return null;
+  const cutoffMs = Date.now() - reuseWindowSeconds * 1000;
+  const byId = new Map();
+
+  try {
+    const active = await listActiveSessions({ targetPath });
+    for (const entry of active) {
+      const activityMs = latestSessionActivityMs(entry);
+      if (!activityMs || activityMs < cutoffMs) continue;
+      const candidate = {
+        ...entry,
+        _source: "local",
+        _activityMs: activityMs,
+      };
+      byId.set(entry.sessionId, mergeResumeCandidate(byId.get(entry.sessionId), candidate));
+    }
+  } catch {
+    /* local lookup failure is non-fatal */
+  }
+
+  if (!remoteSessionLookupDisabled()) {
+    try {
+      const remote = await listSessionsFromApi({
+        targetPath,
+        includeArchived: false,
+        limit: 50,
+      });
+      if (remote && remote.ok) {
+        const normalizedTarget = normalizeComparablePath(targetPath);
+        for (const entry of remote.sessions || []) {
+          const codebase = normalizeComparablePath(entry.codebasePath || entry.targetPath);
+          if (!codebase || codebase !== normalizedTarget) continue;
+          if (entry.archiveStatus && entry.archiveStatus !== "active") continue;
+          const activityMs = latestSessionActivityMs(entry);
+          if (!activityMs || activityMs < cutoffMs) continue;
+          const candidate = {
+            sessionId: entry.sessionId,
+            createdAt: entry.createdAt,
+            lastActivityAt: entry.lastActivityAt,
+            expiresAt: entry.expiresAt,
+            status: entry.status || "active",
+            template: entry.templateName || null,
+            title: entry.title || null,
+            _source: "remote",
+            _activityMs: activityMs,
+          };
+          byId.set(entry.sessionId, mergeResumeCandidate(byId.get(entry.sessionId), candidate));
+        }
+      }
+    } catch {
+      /* remote lookup failure is non-fatal */
+    }
+  }
+
+  const candidates = [...byId.values()];
+  candidates.sort((left, right) => Number(right._activityMs || 0) - Number(left._activityMs || 0));
+  return candidates[0] || null;
+}
+
+async function pushSessionTitleToApi(sessionId, title, { targetPath } = {}) {
+  const normalizedTitle = normalizeString(title);
+  if (!normalizedTitle || remoteSessionLookupDisabled()) return;
+  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(sessionId)}/title`,
+      {
+        method: "POST",
+        operationName: "session.set_title",
+        headers: { Authorization: `Bearer ${session.token}` },
+        body: { title: normalizedTitle },
+      },
+    );
+  } catch {
+    /* best-effort */
+  }
+}
+
+async function ensureWorkspaceSession({
+  targetPath,
+  ttlSeconds = DEFAULT_TTL_SECONDS,
+  template = null,
+  title = "",
+  resume = true,
+  forceNew = false,
+  reuseWindowSeconds = 3600,
+} = {}) {
+  const titleArg = normalizeString(title);
+  const fallbackTitle = deriveSessionTitle(targetPath);
+  const startedAt = Date.now();
+  const resumedCandidate = await findReusableSessionCandidate({
+    targetPath,
+    reuseWindowSeconds,
+    resume,
+    forceNew,
+  });
+  let created;
+  const resumeTitle =
+    titleArg || normalizeString(resumedCandidate?.title) || fallbackTitle;
+
+  if (resumedCandidate) {
+    if (resumedCandidate._source === "remote" && !resumedCandidate.sessionDir) {
+      created = await createSession({
+        targetPath,
+        ttlSeconds,
+        sessionId: resumedCandidate.sessionId,
+        title: resumeTitle,
+        createdAt: resumedCandidate.createdAt,
+        expiresAt: resumedCandidate.expiresAt,
+        lastInteractionAt:
+          resumedCandidate.lastInteractionAt ||
+          resumedCandidate.lastActivityAt ||
+          resumedCandidate.createdAt,
+      });
+    } else {
+      created = {
+        sessionId: resumedCandidate.sessionId,
+        sessionDir: resumedCandidate.sessionDir || null,
+        metadataPath: resumedCandidate.metadataPath || null,
+        streamPath: resumedCandidate.streamPath || null,
+        createdAt: resumedCandidate.createdAt,
+        updatedAt: resumedCandidate.updatedAt || null,
+        lastInteractionAt: resumedCandidate.lastInteractionAt || null,
+        expiresAt: resumedCandidate.expiresAt,
+        elapsedTimer: resumedCandidate.elapsedTimer || 0,
+        renewalCount: resumedCandidate.renewalCount || 0,
+        status: resumedCandidate.status || "active",
+        template: resumedCandidate.template || null,
+        title: normalizeString(resumedCandidate.title) || null,
+        codebaseContext: resumedCandidate.codebaseContext || null,
+      };
+      if (resumeTitle && resumeTitle !== created.title) {
+        const updated = await updateSessionTitle(created.sessionId, {
+          targetPath,
+          title: resumeTitle,
+        }).catch(() => null);
+        if (updated) {
+          created = {
+            ...created,
+            ...updated,
+          };
+        }
+      }
+    }
+  } else {
+    created = await createSession({
+      targetPath,
+      ttlSeconds,
+      template,
+      title: titleArg || fallbackTitle,
+    });
+  }
+
+  const effectiveTitle = titleArg || normalizeString(created.title) || fallbackTitle;
+  const titleAuto = !titleArg && !resumedCandidate;
+  const shouldPushTitle = Boolean(
+    titleArg ||
+      titleAuto ||
+      (resumedCandidate && effectiveTitle && !normalizeString(resumedCandidate.title))
+  );
+  if (shouldPushTitle) {
+    void pushSessionTitleToApi(created.sessionId, effectiveTitle, { targetPath });
+  }
+
+  return {
+    created: {
+      ...created,
+      title: effectiveTitle || null,
+      resumed: Boolean(resumedCandidate),
+    },
+    resumedCandidate,
+    durationMs: Date.now() - startedAt,
+    title: effectiveTitle || null,
+    titleAuto,
+  };
+}
+
 function normalizeAgentId(value, fallbackValue = "cli-user") {
   const normalized = normalizeString(value)
     .toLowerCase()
@@ -279,6 +508,15 @@ export function registerSessionCommand(program) {
       "--force-new",
       "Always create a new session even if a recent active one exists for this workspace",
     )
+    .option(
+      "--resume",
+      "Reuse the most recent active session for this workspace when one is inside the reuse window",
+      true,
+    )
+    .option(
+      "--no-resume",
+      "Disable automatic resume and mint a new session unless --force-new is also present",
+    )
     .option(
       "--reuse-window-seconds <seconds>",
       "Window in which an existing active session for this workspace will be reused (default 3600 = 1h)",
@@ -302,149 +540,22 @@ export function registerSessionCommand(program) {
         "reuse-window-seconds",
         3600,
       );
-
-      // Auto-resume: prefer an existing active session for this codebase
-      // over minting a new one. We check both local filesystem state and the
-      // remote registry — local-only resume meant a fresh checkout / second
-      // machine would orphan the room each time, exactly the mess Carter
-      // surfaced ("all of them look like one chat re-created").
-      //
-      // Order:
-      //   1. Local session for the same targetPath inside the reuse window.
-      //   2. Remote active session whose codebasePath matches the absolute
-      //      targetPath, sorted by last activity. We fold these into the
-      //      candidate pool so a session minted on another machine can be
-      //      rejoined rather than duplicated.
-      // `--force-new` opts back into the old "always mint" behavior.
-      let resumed = null;
-      if (!options.forceNew) {
-        const cutoffMs = Date.now() - reuseWindowSeconds * 1000;
-        const candidates = [];
-        try {
-          const active = await listActiveSessions({ targetPath });
-          for (const entry of active) {
-            const createdMs = Date.parse(entry.createdAt || "");
-            if (Number.isFinite(createdMs) && createdMs >= cutoffMs) {
-              candidates.push({ ...entry, _source: "local" });
-            }
-          }
-        } catch {
-          /* local lookup failure is non-fatal */
-        }
-        try {
-          const remote = await listSessionsFromApi({
-            targetPath,
-            includeArchived: false,
-            limit: 50,
-          });
-          if (remote && remote.ok) {
-            const normalizedTarget = String(targetPath).toLowerCase();
-            for (const entry of remote.sessions || []) {
-              const codebase = String(entry.codebasePath || "").toLowerCase();
-              if (!codebase || codebase !== normalizedTarget) continue;
-              if (entry.archiveStatus && entry.archiveStatus !== "active") continue;
-              const lastMs = Date.parse(entry.lastActivityAt || entry.createdAt || "");
-              if (Number.isFinite(lastMs) && lastMs >= cutoffMs) {
-                candidates.push({
-                  sessionId: entry.sessionId,
-                  createdAt: entry.createdAt,
-                  lastActivityAt: entry.lastActivityAt,
-                  expiresAt: entry.expiresAt,
-                  status: entry.status || "active",
-                  template: entry.templateName || null,
-                  title: entry.title || null,
-                  _source: "remote",
-                });
-              }
-            }
-          }
-        } catch {
-          /* remote lookup failure is non-fatal */
-        }
-        if (candidates.length > 0) {
-          // Prefer the most recent activity. Local + remote may name the
-          // same session; dedupe on sessionId before picking.
-          const seen = new Set();
-          const deduped = [];
-          for (const entry of candidates) {
-            if (seen.has(entry.sessionId)) continue;
-            seen.add(entry.sessionId);
-            deduped.push(entry);
-          }
-          deduped.sort((a, b) =>
-            String(b.lastActivityAt || b.createdAt || "").localeCompare(
-              String(a.lastActivityAt || a.createdAt || ""),
-            ),
-          );
-          resumed = deduped[0];
-        }
-      }
-
-      const startedAt = Date.now();
-      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 titleArg = normalizeString(options.title);
+      const ensured = await ensureWorkspaceSession({
+        targetPath,
+        ttlSeconds,
+        template,
+        title: titleArg,
+        resume: options.resume !== false,
+        forceNew: Boolean(options.forceNew),
+        reuseWindowSeconds,
+      });
+      const created = ensured.created;
+      const resumed = Boolean(ensured.resumedCandidate);
+      const durationMs = ensured.durationMs;
       const launchPlan = template ? buildTemplateLaunchPlan(created.sessionId, template) : [];
       const dashboardUrl = buildDashboardUrl(created.sessionId);
-      // Default the title to a stable codebase+date slug so the web sidebar
-      // never fills with anonymous "<null>" rows. The caller can still
-      // override with --title. We skip the auto-title for resumed sessions
-      // because the room already has a name we don't want to clobber.
-      const titleArg = normalizeString(options.title);
-      const autoTitle = !resumed && !titleArg ? deriveSessionTitle(targetPath) : "";
-      const effectiveTitle = titleArg || autoTitle;
-
-      // If a title needs to land on the dashboard, push it. We always push
-      // when the caller passed --title, AND we push the auto-derived title
-      // for fresh (non-resumed) sessions so the room is never anonymous on
-      // the web. Best-effort, non-blocking.
-      if (effectiveTitle) {
-        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: effectiveTitle },
-              },
-            );
-          } catch (_error) {
-            /* best-effort */
-          }
-        })();
-      }
+      const effectiveTitle = ensured.title;
 
       const payload = {
         command: "session start",
@@ -455,7 +566,9 @@ export function registerSessionCommand(program) {
         metadataPath: created.metadataPath,
         streamPath: created.streamPath,
         createdAt: created.createdAt,
+        updatedAt: created.updatedAt,
         expiresAt: created.expiresAt,
+        lastInteractionAt: created.lastInteractionAt,
         ttlSeconds,
         elapsedTimer: created.elapsedTimer,
         renewalCount: created.renewalCount,
@@ -463,9 +576,9 @@ export function registerSessionCommand(program) {
         template: created.template,
         launchPlan,
         dashboardUrl,
-        resumed: Boolean(resumed),
+        resumed,
         title: effectiveTitle || null,
-        titleAuto: Boolean(autoTitle && !titleArg),
+        titleAuto: Boolean(ensured.titleAuto),
       };
 
       // Best-effort admin visibility sync. Session creation remains local-first.
@@ -475,6 +588,7 @@ export function registerSessionCommand(program) {
         status: created.status,
         createdAt: created.createdAt,
         expiresAt: created.expiresAt,
+        title: effectiveTitle || null,
         ttlSeconds,
         template: created.template,
         codebaseContext: created.codebaseContext,
@@ -535,6 +649,62 @@ export function registerSessionCommand(program) {
       await program.parseAsync(args, { from: "user" });
     });
 
+  session
+    .command("ensure")
+    .description("Join or create the canonical session for this workspace and emit JSON")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--title <title>", "Title applied if a new or unnamed resumed session needs one")
+    .option(
+      "--ttl-seconds <seconds>",
+      `Session time-to-live in seconds when a new session is minted (default ${DEFAULT_TTL_SECONDS})`
+    )
+    .option(
+      "--force-new",
+      "Always create a new session even if a recent active one exists for this workspace",
+    )
+    .option(
+      "--resume",
+      "Reuse the most recent active session for this workspace when one is inside the reuse window",
+      true,
+    )
+    .option("--no-resume", "Disable automatic resume and mint a new session")
+    .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 (default for this command)")
+    .action(async (options) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const ttlSeconds = parsePositiveInteger(
+        options.ttlSeconds,
+        "ttl-seconds",
+        DEFAULT_TTL_SECONDS,
+      );
+      const reuseWindowSeconds = parsePositiveInteger(
+        options.reuseWindowSeconds,
+        "reuse-window-seconds",
+        3600,
+      );
+      const ensured = await ensureWorkspaceSession({
+        targetPath,
+        ttlSeconds,
+        title: normalizeString(options.title),
+        resume: options.resume !== false,
+        forceNew: Boolean(options.forceNew),
+        reuseWindowSeconds,
+      });
+      const payload = {
+        command: "session ensure",
+        targetPath,
+        sessionId: ensured.created.sessionId,
+        title: ensured.title || null,
+        resumed: Boolean(ensured.resumedCandidate),
+        dashboardUrl: buildDashboardUrl(ensured.created.sessionId),
+      };
+      console.log(JSON.stringify(payload, null, 2));
+    });
+
   session
     .command("set-title <sessionId> <title>")
     .description("Set the human-readable title on a session (visible in web sidebar + transcript).")
@@ -564,10 +734,15 @@ export function registerSessionCommand(program) {
           body: { title: normalizedTitle },
         },
       );
+      const localUpdated = await updateSessionTitle(normalizedSessionId, {
+        targetPath,
+        title: normalizedTitle,
+      }).catch(() => null);
       const payload = {
         command: "session set-title",
         sessionId: normalizedSessionId,
         title: normalizedTitle,
+        localUpdated: Boolean(localUpdated),
         result,
       };
       if (shouldEmitJson(options, command)) {
@@ -697,6 +872,7 @@ export function registerSessionCommand(program) {
     .command("say <sessionId> <message>")
     .description("Send a message to the session")
     .option("--agent <id>", "Agent id to emit from", "cli-user")
+    .option("--to <agent>", "Direct the message to a specific agent id")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, message, options, command) => {
@@ -710,14 +886,19 @@ export function registerSessionCommand(program) {
       }
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
       const agentId = normalizeAgentId(options.agent, "cli-user");
+      const to = normalizeString(options.to);
+      const eventPayload = {
+        message: normalizedMessage,
+        channel: "session",
+      };
+      if (to) {
+        eventPayload.to = to;
+      }
       const event = createAgentEvent({
         event: "session_message",
         agentId,
         sessionId: normalizedSessionId,
-        payload: {
-          message: normalizedMessage,
-          channel: "session",
-        },
+        payload: eventPayload,
       });
       const persisted = await appendToStream(normalizedSessionId, event, {
         targetPath,
@@ -736,6 +917,93 @@ export function registerSessionCommand(program) {
       console.log(formatEventLine(persisted));
     });
 
+  session
+    .command("listen")
+    .description("Background-poll a session for events addressed to this agent or broadcast")
+    .requiredOption("--session <id>", "Session id to listen to")
+    .option(
+      "--agent <id>",
+      "Agent id to receive messages for",
+      process.env.SENTINELAYER_AGENT_ID || "cli-user",
+    )
+    .option("--interval <seconds>", "Polling interval in seconds (default 60)", "60")
+    .option("--emit <format>", "Output format: ndjson or text", "ndjson")
+    .option("--limit <n>", "Maximum events to request per poll (default 200)", "200")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--since <cursor>", "Override the persisted listen cursor")
+    .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)")
+    .action(async (options) => {
+      const normalizedSessionId = resolveSessionIdOption(options);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const agentId = normalizeAgentId(options.agent, "cli-user");
+      const intervalSeconds = parsePositiveInteger(options.interval, "interval", 60);
+      const limit = parsePositiveInteger(options.limit, "limit", 200);
+      const emitFormat = normalizeString(options.emit).toLowerCase() || "ndjson";
+      if (!["ndjson", "text"].includes(emitFormat)) {
+        throw new Error("--emit must be one of: ndjson, text.");
+      }
+      const maxPolls =
+        options.maxPolls === undefined
+          ? null
+          : parsePositiveInteger(options.maxPolls, "max-polls", 1);
+      const since = options.since === undefined ? undefined : String(options.since);
+      const ac = new AbortController();
+      const onSigint = () => ac.abort();
+      process.on("SIGINT", onSigint);
+
+      if (emitFormat === "text") {
+        console.log(
+          pc.gray(
+            `Listening to session ${normalizedSessionId} as ${agentId}; interval=${intervalSeconds}s. Press Ctrl+C to stop.`,
+          ),
+        );
+      }
+
+      try {
+        await listenSessionEvents({
+          sessionId: normalizedSessionId,
+          targetPath,
+          agentId,
+          intervalSeconds,
+          limit,
+          since,
+          replay: Boolean(options.replay),
+          maxPolls,
+          signal: ac.signal,
+          onEvent: async (event) => {
+            if (emitFormat === "ndjson") {
+              console.log(JSON.stringify(event));
+            } else {
+              console.log(formatEventLine(event));
+            }
+          },
+          onError: async (result) => {
+            const reason = normalizeString(result?.reason) || "poll_failed";
+            if (emitFormat === "ndjson") {
+              console.log(
+                JSON.stringify(
+                  createAgentEvent({
+                    event: "session_listen_error",
+                    agentId,
+                    sessionId: normalizedSessionId,
+                    payload: {
+                      reason,
+                      cursor: result?.cursor || null,
+                    },
+                  }),
+                ),
+              );
+            } else {
+              console.log(pc.yellow(`Listen poll skipped (${reason}).`));
+            }
+          },
+        });
+      } finally {
+        process.removeListener("SIGINT", onSigint);
+      }
+    });
+
   session
     .command("read <sessionId>")
     .description("Read recent session messages")