sentinelayer-cli 0.8.11 → 0.9.0

package/src/review/persona-prompts.js

@@ -27,6 +27,29 @@ Non-negotiables for your review:
 
 Your output must help an acquirer decide whether to buy this codebase. Be FOUND-violations accurate, not speculation-padded.`;
 
+export const ELEVEN_LENS_EVIDENCE_APPENDIX = `## 11-lens evidence contract
+Evaluate every confirmed finding through these lenses before returning it:
+
+A. Route/runtime boundary integrity
+B. State, lifecycle, and hook correctness
+C. Render cost, re-render, and scalability mechanics
+D. Hydration, SSR, streaming, and environment divergence
+E. Data fetching, caching, timeout, and freshness behavior
+F. Bundle/dependency footprint and code-splitting risk
+G. Assets, scripts, layout stability, and resource loading
+H. Accessibility, keyboard, focus, and trust-critical UX
+I. Mobile/responsive reliability across 360px, 768px, and desktop
+J. Verification, rollback, and QA readiness
+K. AI governance, provenance, HITL, and agent/tool permission surfaces
+
+For each finding include:
+- lensEvidence: object keyed by lens letter with "passed", "failed", or "not_applicable" plus one short evidence sentence
+- reproduction: object with type (manual_step | shell | runtime_probe | static_trace) and steps array; required for P0/P1
+- user_impact: one sentence describing what a user/operator/system experiences
+- trafficLight: green | yellow | red for automation safety
+- rootCause: why the issue exists
+- recommendedFix: concrete fix path`;
+
 const PERSONA_PROMPTS = {
   security: {
     role: "Nina Patel — Security Specialist",
@@ -291,6 +314,8 @@ ${FAANG_GRADE_PREAMBLE}
 
 ${persona.focus}
 
+${ELEVEN_LENS_EVIDENCE_APPENDIX}
+
 ${checklistBlock}
 ## Context
 Target: ${targetPath || "(not provided)"}
@@ -313,6 +338,10 @@ Return a JSON OBJECT (not array) with this shape — return ONLY the JSON, no ot
       "line": 42,
       "title": "Brief description",
       "evidence": "Concrete code excerpt at file:line (min 1 line)",
+      "lensEvidence": { "A": "not_applicable: no route/runtime boundary impact", "K": "passed: no AI governance surface involved" },
+      "reproduction": { "type": "static_trace", "steps": ["Inspect path/to/file.ext:42", "Trace the value/control flow to the failing behavior"] },
+      "user_impact": "One sentence describing the user/operator/system failure mode",
+      "trafficLight": "green|yellow|red",
       "rootCause": "Why this is a problem",
       "recommendedFix": "Specific code change to apply",
       "confidence": 0.85,
@@ -326,6 +355,8 @@ Rules:
 - Maximum ${maxFindings} findings.
 - Only report findings you have HIGH confidence in (>= 0.7).
 - Every finding MUST have concrete file:line evidence AND a non-empty \`evidence\` code excerpt.
+- Every finding MUST include \`lensEvidence\`, \`user_impact\`, \`trafficLight\`, \`rootCause\`, and \`recommendedFix\`.
+- P0/P1 findings MUST include \`reproduction\` steps.
 - Do NOT repeat findings already in the deterministic scan.
 - Do NOT report hypothetical/speculative issues.
 - Focus on REAL, EXPLOITABLE, IMPACTFUL problems in your domain.
@@ -337,10 +368,12 @@ Rules:
 function buildGenericPrompt({ targetPath, deterministicSummary, maxFindings }) {
   return `You are a senior code reviewer. Analyze the code for security, quality, and reliability issues.
 
+${ELEVEN_LENS_EVIDENCE_APPENDIX}
+
 Target: ${targetPath || "(not provided)"}
 Deterministic scan: P0=${deterministicSummary.P0 || 0} P1=${deterministicSummary.P1 || 0} P2=${deterministicSummary.P2 || 0}
 
-Return a JSON array of up to ${maxFindings} findings with: severity, file, line, title, evidence, rootCause, recommendedFix, confidence.
+Return a JSON object with inspectedFiles, coverage, and up to ${maxFindings} findings. Each finding needs: severity, file, line, title, evidence, lensEvidence, reproduction for P0/P1, user_impact, trafficLight, rootCause, recommendedFix, confidence.
 Only report findings with concrete evidence. Do NOT repeat deterministic findings.`;
 }
 

package/src/review/report.js

@@ -62,6 +62,75 @@ function formatConfidence(value) {
   return Math.max(0, Math.min(1, normalized));
 }
 
+function normalizeConfidenceFloor(value) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized)) {
+    return 0.7;
+  }
+  return Math.max(0, Math.min(1, normalized));
+}
+
+function normalizeTrafficLight(value) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (["green", "yellow", "red"].includes(normalized)) {
+    return normalized;
+  }
+  return "";
+}
+
+function cloneJsonCompatible(value) {
+  if (value === undefined || value === null || value === "") {
+    return null;
+  }
+  if (typeof value === "string") {
+    return normalizeString(value) || null;
+  }
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return null;
+  }
+}
+
+function confidenceFloorForFinding(finding = {}, {
+  source = "ai",
+  confidenceFloors = {},
+  defaultConfidenceFloor = 0.7,
+} = {}) {
+  const persona = normalizeString(finding.persona || finding.personaId || finding.agentId);
+  const layer = normalizeString(finding.layer);
+  const identity = sourceIdentityForFinding(finding, source);
+  const floor =
+    finding.confidenceFloor ??
+    finding.personaConfidenceFloor ??
+    confidenceFloors[identity] ??
+    confidenceFloors[persona] ??
+    confidenceFloors[layer] ??
+    confidenceFloors[source] ??
+    defaultConfidenceFloor;
+  return normalizeConfidenceFloor(floor);
+}
+
+function sourceIdentityForFinding(finding = {}, source = "ai") {
+  if (source === "deterministic") {
+    return "deterministic";
+  }
+  const persona = normalizeString(
+    finding.persona || finding.personaId || finding.agentId || finding.layer
+  );
+  return `ai:${persona || "generic"}`;
+}
+
+function hasMultiSourceConfirmation(finding = {}) {
+  const confirmationSources = Array.isArray(finding.confirmationSources)
+    ? finding.confirmationSources
+    : [];
+  const sourceIdentities = confirmationSources.length > 0
+    ? confirmationSources
+    : (Array.isArray(finding.sources) ? finding.sources : []);
+  return new Set(sourceIdentities.filter(Boolean)).size >= 2;
+}
+
 function dedupeKeyForFinding(finding = {}) {
   const file = toPosixPath(normalizeString(finding.file) || "unknown");
   const line = Number(finding.line || 1);
@@ -104,25 +173,85 @@ function summarizeFindings(findings = []) {
   };
 }
 
+export function dropBelowConfidence(findings = [], { threshold = 0.7 } = {}) {
+  const defaultThreshold = normalizeConfidenceFloor(threshold);
+  const kept = [];
+  const dropped = [];
+
+  for (const finding of findings || []) {
+    const confidence = formatConfidence(finding.confidence);
+    const confidenceFloor = normalizeConfidenceFloor(
+      finding.confidenceFloor ?? finding.personaConfidenceFloor ?? defaultThreshold
+    );
+    if (!hasMultiSourceConfirmation(finding) && confidence < confidenceFloor) {
+      dropped.push({
+        ...finding,
+        confidence,
+        confidenceFloor,
+        droppedReason: "below_confidence_floor_single_source",
+      });
+      continue;
+    }
+    kept.push({
+      ...finding,
+      confidence,
+      confidenceFloor,
+    });
+  }
+
+  return {
+    findings: kept,
+    dropped,
+    droppedCount: dropped.length,
+    threshold: defaultThreshold,
+  };
+}
+
 export function reconcileReviewFindings({
   deterministicFindings = [],
   aiFindings = [],
+  confidenceFloor = 0.7,
+  defaultConfidenceFloor = confidenceFloor,
+  confidenceFloors = {},
 } = {}) {
   const merged = new Map();
+  const normalizedDefaultConfidenceFloor = normalizeConfidenceFloor(defaultConfidenceFloor);
 
   const addFinding = (finding, source) => {
+    const persona = normalizeString(finding.persona || finding.personaId || finding.agentId);
+    const confidenceFloorForSource = confidenceFloorForFinding(finding, {
+      source,
+      confidenceFloors,
+      defaultConfidenceFloor: normalizedDefaultConfidenceFloor,
+    });
+    const evidence = normalizeString(finding.evidence || finding.excerpt);
+    const rootCause = normalizeString(finding.rootCause || finding.root_cause);
+    const recommendedFix = normalizeString(
+      finding.recommendedFix || finding.recommended_fix || finding.suggestedFix
+    );
+    const suggestedFix = normalizeString(finding.suggestedFix || recommendedFix);
     const normalized = {
       findingId: "",
       severity: normalizeSeverity(finding.severity),
       file: toPosixPath(normalizeString(finding.file) || "unknown"),
       line: Math.max(1, Math.floor(Number(finding.line || 1))),
       message: normalizeString(finding.message) || "Unnamed finding",
-      excerpt: normalizeString(finding.excerpt),
+      excerpt: normalizeString(finding.excerpt || evidence || rootCause),
       ruleId: normalizeString(finding.ruleId),
-      suggestedFix: normalizeString(finding.suggestedFix),
+      suggestedFix,
+      evidence,
+      lensEvidence: cloneJsonCompatible(finding.lensEvidence || finding.lens_evidence),
+      reproduction: cloneJsonCompatible(finding.reproduction),
+      userImpact: normalizeString(finding.userImpact || finding.user_impact),
+      trafficLight: normalizeTrafficLight(finding.trafficLight || finding.traffic_light),
+      rootCause,
+      recommendedFix: recommendedFix || suggestedFix,
+      persona,
       layer: normalizeString(finding.layer),
       confidence: source === "deterministic" ? 1 : formatConfidence(finding.confidence),
+      confidenceFloor: confidenceFloorForSource,
       sources: [source],
+      confirmationSources: [sourceIdentityForFinding(finding, source)],
       adjudication: {
         verdict: "pending",
         note: "",
@@ -138,8 +267,25 @@ export function reconcileReviewFindings({
     }
 
     const nextSources = new Set([...(existing.sources || []), source]);
+    const nextConfirmationSources = new Set([
+      ...(existing.confirmationSources || []),
+      ...(normalized.confirmationSources || []),
+    ]);
     const preferred = compareFindingPriority(existing, normalized) <= 0 ? existing : normalized;
     preferred.sources = [...nextSources].sort((left, right) => left.localeCompare(right));
+    preferred.confirmationSources = [...nextConfirmationSources].sort((left, right) =>
+      left.localeCompare(right)
+    );
+    preferred.confidenceFloor = Math.max(
+      normalizeConfidenceFloor(existing.confidenceFloor),
+      normalizeConfidenceFloor(normalized.confidenceFloor)
+    );
+    if (!preferred.persona) {
+      preferred.persona = existing.persona || normalized.persona;
+    }
+    if (!preferred.layer) {
+      preferred.layer = existing.layer || normalized.layer;
+    }
     if (!preferred.excerpt) {
       preferred.excerpt = existing.excerpt || normalized.excerpt;
     }
@@ -149,6 +295,27 @@ export function reconcileReviewFindings({
     if (!preferred.suggestedFix) {
       preferred.suggestedFix = existing.suggestedFix || normalized.suggestedFix;
     }
+    if (!preferred.evidence) {
+      preferred.evidence = existing.evidence || normalized.evidence;
+    }
+    if (!preferred.lensEvidence) {
+      preferred.lensEvidence = existing.lensEvidence || normalized.lensEvidence;
+    }
+    if (!preferred.reproduction) {
+      preferred.reproduction = existing.reproduction || normalized.reproduction;
+    }
+    if (!preferred.userImpact) {
+      preferred.userImpact = existing.userImpact || normalized.userImpact;
+    }
+    if (!preferred.trafficLight) {
+      preferred.trafficLight = existing.trafficLight || normalized.trafficLight;
+    }
+    if (!preferred.rootCause) {
+      preferred.rootCause = existing.rootCause || normalized.rootCause;
+    }
+    if (!preferred.recommendedFix) {
+      preferred.recommendedFix = existing.recommendedFix || normalized.recommendedFix;
+    }
     merged.set(key, preferred);
   };
 
@@ -159,7 +326,10 @@ export function reconcileReviewFindings({
     addFinding(finding, "ai");
   }
 
-  const findings = [...merged.values()].sort((left, right) => {
+  const confidenceFilter = dropBelowConfidence([...merged.values()], {
+    threshold: normalizedDefaultConfidenceFloor,
+  });
+  const findings = confidenceFilter.findings.sort((left, right) => {
     const severityDelta = SEVERITY_RANK[left.severity] - SEVERITY_RANK[right.severity];
     if (severityDelta !== 0) {
       return severityDelta;
@@ -177,7 +347,13 @@ export function reconcileReviewFindings({
 
   return {
     findings,
-    summary: summarizeFindings(findings),
+    droppedFindings: confidenceFilter.dropped,
+    summary: {
+      ...summarizeFindings(findings),
+      confidenceFloor: confidenceFilter.threshold,
+      droppedBelowConfidence: confidenceFilter.droppedCount,
+      droppedBelowConfidenceSingleSource: confidenceFilter.droppedCount,
+    },
   };
 }
 
@@ -234,6 +410,9 @@ function composeReportMarkdown(report = {}) {
               `   confidence: ${(formatConfidence(finding.confidence) * 100).toFixed(0)}%\n` +
               `   sources: ${(finding.sources || []).join(", ") || "none"}\n` +
               `   verdict: ${finding.adjudication?.verdict || "pending"}\n` +
+              (finding.trafficLight ? `   traffic_light: ${finding.trafficLight}\n` : "") +
+              (finding.userImpact ? `   user_impact: ${finding.userImpact}\n` : "") +
+              (finding.rootCause ? `   root_cause: ${finding.rootCause}\n` : "") +
               `   suggested_fix: ${finding.suggestedFix || "Review and remediate as needed."}`
           )
           .join("\n")
@@ -250,6 +429,7 @@ function composeReportMarkdown(report = {}) {
     `- Findings: P0=${report.summary.P0} P1=${report.summary.P1} P2=${report.summary.P2} P3=${report.summary.P3}`,
     `- Blocking: ${report.summary.blocking ? "yes" : "no"}`,
     `- Total findings: ${report.findings.length}`,
+    `- Dropped below confidence floor (single-source): ${report.summary.droppedBelowConfidence || 0}`,
     "",
     "Metadata:",
     `- commit_sha: ${report.metadata.git.commitSha || "unknown"}`,
@@ -280,6 +460,8 @@ export async function buildUnifiedReviewReport({
   deterministic,
   aiLayer = null,
   specFile = "",
+  defaultConfidenceFloor = 0.7,
+  confidenceFloors = {},
 } = {}) {
   const normalizedTargetPath = path.resolve(String(targetPath || "."));
   const normalizedMode = normalizeString(mode) || "full";
@@ -289,6 +471,8 @@ export async function buildUnifiedReviewReport({
   const reconciliation = reconcileReviewFindings({
     deterministicFindings: deterministic?.findings || [],
     aiFindings: aiLayer?.findings || [],
+    defaultConfidenceFloor,
+    confidenceFloors,
   });
   const spec = await resolveSpecMetadata(normalizedTargetPath, specFile);
   const commitSha = runGit(normalizedTargetPath, ["rev-parse", "HEAD"]);
@@ -303,6 +487,7 @@ export async function buildUnifiedReviewReport({
     mode: normalizedMode,
     summary: reconciliation.summary,
     findings: reconciliation.findings,
+    droppedFindings: reconciliation.droppedFindings,
     severityMatrix: buildSeverityMatrix(),
     metadata: {
       git: {

package/src/session/coordination-guidance.js

@@ -0,0 +1,48 @@
+export const COORDINATION_GUIDANCE_TITLE = "Multi-Agent Coordination Protocol";
+
+export const COORDINATION_ETIQUETTE_ITEMS = Object.freeze([
+  "Find the recent Senti session for this codebase: run `sl session list --path .` and `sl session list --remote --path .`; join the right room with `sl session join <id> --name <your-name> --role coder`.",
+  "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 listener for replies: `sl session listen --session <id> --agent <your-name> --interval 60 --emit ndjson`; 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 `sl review --diff` after each finished file or PR-ready diff and post the result summary back to the session.",
+  "Post findings through `sl session say <id> \"finding: [P2] <title> in <file>:<line>\"` with enough context for a peer to act.",
+  "Ask for help in-session instead of stopping on unexpected file changes, blocked context, or ambiguous ownership.",
+  "Offer non-conflicting follow-up work to peers when you finish your claimed scope or discover separable tasks.",
+  "Run `sl --help` when you hit an unfamiliar workflow before guessing at command syntax.",
+  "Leave the session when done with `sl session leave <id>` after posting the final status and verification evidence.",
+]);
+
+export function getCoordinationEtiquetteItems() {
+  return [...COORDINATION_ETIQUETTE_ITEMS];
+}
+
+export function renderCoordinationNumberedList({
+  items = COORDINATION_ETIQUETTE_ITEMS,
+  indent = "",
+} = {}) {
+  return items.map((item, index) => `${indent}${index + 1}. ${item}`).join("\n");
+}
+
+export function renderCoordinationBulletList({
+  items = COORDINATION_ETIQUETTE_ITEMS,
+  indent = "",
+} = {}) {
+  return items.map((item) => `${indent}- ${item}`).join("\n");
+}
+
+export function renderCoordinationMarkdownSection({
+  headingLevel = 2,
+  title = COORDINATION_GUIDANCE_TITLE,
+} = {}) {
+  const level = Math.max(1, Math.min(6, Number.parseInt(String(headingLevel || 2), 10) || 2));
+  return `${"#".repeat(level)} ${title}
+${renderCoordinationNumberedList()}`;
+}
+
+export function renderCoordinationTicketBlock() {
+  return [
+    "Coordination rules:",
+    renderCoordinationNumberedList(),
+  ].join("\n");
+}

package/src/session/daemon.js

@@ -45,6 +45,7 @@ const HELP_MODEL_TIMEOUT_MS = 3_000;
 const HELP_CONTEXT_EVENT_TAIL = 50;
 const HELP_CONTEXT_RESULT_LIMIT = 6;
 const HELP_BLACKBOARD_ENTRY_LIMIT = 40;
+const WATCHER_STARTUP_REPLAY_TAIL = 100;
 const FILE_CONFLICT_WINDOW_MS = 60_000;
 const RENEWAL_WINDOW_MS = 60 * 60 * 1000;
 const RENEWAL_THRESHOLD_EVENTS = 10;
@@ -608,7 +609,7 @@ async function runHelpWatcher(daemonState) {
       targetPath: daemonState.targetPath,
       signal,
       since: daemonState.startedAt,
-      replayTail: 0,
+      replayTail: WATCHER_STARTUP_REPLAY_TAIL,
       pollMs: Math.max(25, Math.min(250, Math.floor(daemonState.helpRequestTimeoutMs / 4))),
     })) {
       if (!daemonState.running) {
@@ -781,7 +782,7 @@ async function runSessionDirectiveWatcher(daemonState) {
       targetPath: daemonState.targetPath,
       signal,
       since: daemonState.startedAt,
-      replayTail: 0,
+      replayTail: WATCHER_STARTUP_REPLAY_TAIL,
       pollMs: 100,
     })) {
       if (!daemonState.running) {

package/src/session/listener.js

@@ -0,0 +1,236 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+import { pollSessionEvents } from "./sync.js";
+import { readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
+
+const BROADCAST_RECIPIENTS = new Set([
+  "*",
+  "all",
+  "broadcast",
+  "everyone",
+  "anyone",
+  "agents",
+  "all-agents",
+]);
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeComparableId(value) {
+  return normalizeString(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function normalizePositiveInteger(value, fallbackValue) {
+  if (value === undefined || value === null || String(value).trim() === "") {
+    return fallbackValue;
+  }
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) return fallbackValue;
+  return Math.floor(normalized);
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function addRecipientValue(values, value) {
+  if (value === undefined || value === null) return;
+  if (Array.isArray(value)) {
+    for (const item of value) addRecipientValue(values, item);
+    return;
+  }
+  if (isPlainObject(value)) {
+    addRecipientValue(values, value.id || value.agentId || value.name);
+    return;
+  }
+  const raw = normalizeString(value);
+  if (!raw) return;
+  for (const token of raw.split(/[\s,;]+/g)) {
+    const normalized = normalizeString(token);
+    if (normalized) values.push(normalized);
+  }
+}
+
+export function collectSessionEventRecipients(event = {}) {
+  const values = [];
+  if (!isPlainObject(event)) return values;
+  const payload = isPlainObject(event.payload) ? event.payload : {};
+  for (const source of [
+    event.to,
+    event.recipient,
+    event.recipients,
+    event.targetAgent,
+    event.targetAgentId,
+    payload.to,
+    payload.recipient,
+    payload.recipients,
+    payload.targetAgent,
+    payload.targetAgentId,
+  ]) {
+    addRecipientValue(values, source);
+  }
+  return values;
+}
+
+export function eventMatchesAgent(event = {}, agentId = "") {
+  if (!isPlainObject(event)) return false;
+  const normalizedAgentId = normalizeComparableId(agentId);
+  if (!normalizedAgentId) return false;
+
+  const payload = isPlainObject(event.payload) ? event.payload : {};
+  if (event.broadcast === true || payload.broadcast === true) return true;
+
+  const recipients = collectSessionEventRecipients(event);
+  if (recipients.length === 0) return true;
+
+  for (const recipient of recipients) {
+    const rawRecipient = normalizeString(recipient).toLowerCase();
+    if (BROADCAST_RECIPIENTS.has(rawRecipient)) return true;
+    const normalizedRecipient = normalizeComparableId(recipient);
+    if (!normalizedRecipient) continue;
+    if (BROADCAST_RECIPIENTS.has(normalizedRecipient)) return true;
+    if (normalizedRecipient === normalizedAgentId) return true;
+  }
+  return false;
+}
+
+export function listenCursorSuffix(agentId = "") {
+  return `listen-${normalizeComparableId(agentId) || "agent"}`;
+}
+
+async function defaultSleep(ms, { signal } = {}) {
+  await delay(ms, undefined, { signal });
+}
+
+function shouldAbort(error, signal) {
+  return Boolean(signal?.aborted || error?.name === "AbortError" || error?.code === "ABORT_ERR");
+}
+
+function cursorFromEvents(events = [], fallbackCursor = null) {
+  let cursor = normalizeString(fallbackCursor) || null;
+  for (const event of events) {
+    const candidate = normalizeString(event?.cursor);
+    if (candidate) cursor = candidate;
+  }
+  return cursor;
+}
+
+function eventTimestampMs(event = {}) {
+  for (const key of ["ts", "timestamp", "createdAt", "at"]) {
+    const epoch = Date.parse(normalizeString(event?.[key]));
+    if (Number.isFinite(epoch)) return epoch;
+  }
+  return 0;
+}
+
+/**
+ * Poll session events in the background and emit only events addressed to
+ * the current agent or broadcast to everyone. The loop advances its cursor
+ * across non-matching events so direct listeners do not replay unrelated
+ * traffic forever.
+ */
+export async function listenSessionEvents({
+  sessionId,
+  targetPath = process.cwd(),
+  agentId = "cli-user",
+  intervalSeconds = 60,
+  limit = 200,
+  since = undefined,
+  replay = false,
+  maxPolls = null,
+  signal,
+  onEvent = async () => {},
+  onError = async () => {},
+  _poll = pollSessionEvents,
+  _readCursor = readSyncCursor,
+  _writeCursor = writeSyncCursor,
+  _sleep = defaultSleep,
+  _nowMs = Date.now,
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedAgentId = normalizeComparableId(agentId) || "cli-user";
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+
+  const cursorSuffix = listenCursorSuffix(normalizedAgentId);
+  let cursor =
+    typeof since === "string" || since === null
+      ? normalizeString(since) || null
+      : await _readCursor(normalizedSessionId, { targetPath, suffix: cursorSuffix });
+  let primed = Boolean(cursor) || Boolean(replay);
+  let pollCount = 0;
+  let emitted = 0;
+  let matched = 0;
+  let persistedCursor = false;
+  let lastReason = "";
+  const maxPollCount = normalizePositiveInteger(maxPolls, 0);
+  const pollLimit = normalizePositiveInteger(limit, 200);
+  const sleepMs = Math.max(1, normalizePositiveInteger(intervalSeconds, 60)) * 1000;
+  const startedAtMs = Number(_nowMs()) || Date.now();
+
+  while (!signal?.aborted) {
+    pollCount += 1;
+    const result = await _poll(normalizedSessionId, {
+      targetPath,
+      since: cursor,
+      limit: pollLimit,
+    });
+
+    if (result?.ok) {
+      lastReason = "";
+      const events = Array.isArray(result.events) ? result.events : [];
+      const shouldEmitBatch = primed || Boolean(replay);
+      for (const event of events) {
+        if (!eventMatchesAgent(event, normalizedAgentId)) continue;
+        matched += 1;
+        if (!shouldEmitBatch && eventTimestampMs(event) < startedAtMs) continue;
+        await onEvent(event);
+        emitted += 1;
+      }
+
+      const nextCursor = normalizeString(result.cursor) || cursorFromEvents(events, cursor);
+      if (nextCursor && nextCursor !== cursor) {
+        const writeResult = await _writeCursor(normalizedSessionId, nextCursor, {
+          targetPath,
+          suffix: cursorSuffix,
+        }).catch(() => null);
+        persistedCursor = Boolean(writeResult?.written) || persistedCursor;
+        cursor = nextCursor;
+      }
+      primed = true;
+    } else {
+      lastReason = normalizeString(result?.reason) || "poll_failed";
+      await onError({
+        ok: false,
+        reason: lastReason,
+        cursor: result?.cursor || cursor || null,
+      });
+    }
+
+    if (maxPollCount > 0 && pollCount >= maxPollCount) break;
+    try {
+      await _sleep(sleepMs, { signal });
+    } catch (error) {
+      if (shouldAbort(error, signal)) break;
+      throw error;
+    }
+  }
+
+  return {
+    ok: true,
+    sessionId: normalizedSessionId,
+    agentId: normalizedAgentId,
+    cursor,
+    cursorSuffix,
+    pollCount,
+    matched,
+    emitted,
+    persistedCursor,
+    reason: lastReason,
+  };
+}