sentinelayer-cli 0.8.12 → 0.9.2

package/src/review/investor-dd-orchestrator.js

@@ -37,6 +37,8 @@ import {
 import { notifyRunCompleted } from "./investor-dd-notification.js";
 import { attachReproducibilityChain } from "./reproducibility-chain.js";
 import { renderInvestorDdHtml } from "./investor-dd-html-report.js";
+import { runDevTestBotPhase } from "./investor-dd-devtestbot.js";
+import { redactDdEmailError } from "./dd-report-email-client.js";
 
 const INVESTOR_DD_PERSONAS = Object.freeze([
   "security",
@@ -164,10 +166,95 @@ function buildSummaryMarkdown({ runId, summary, routing, byPersona }) {
     lines.push(`- **${sev}**: ${count}`);
   }
   lines.push("");
+  if (summary.devTestBot) {
+    lines.push("## devTestBot");
+    lines.push("");
+    lines.push(`- Skipped: ${summary.devTestBot.skipped ? "yes" : "no"}`);
+    lines.push(`- Subagents: ${summary.devTestBot.swarmCount || 0}`);
+    lines.push(`- Identities: ${summary.devTestBot.identityCount || 0}`);
+    lines.push(`- Findings: ${summary.devTestBot.findingCount || 0}`);
+    lines.push(`- Artifacts: ${summary.devTestBot.artifactRoot || "n/a"}`);
+    lines.push("");
+  }
   lines.push(`Total: ${allFindings.length}`);
   return lines.join("\n");
 }
 
+async function triggerReportEmail({ reportEmail, runResult, dryRun, emit }) {
+  const to = String(reportEmail?.to || "").trim();
+  if (!to) return null;
+
+  if (dryRun && reportEmail.skipWhenDryRun !== false) {
+    const result = { queued: false, skipped: true, runId: runResult.runId, to, code: "DD_EMAIL_DRY_RUN" };
+    emit({
+      type: "dd_email_skipped",
+      event: "dd_email_skipped",
+      runId: runResult.runId,
+      to,
+      reason: "dry_run",
+    });
+    return result;
+  }
+
+  const client = reportEmail.client;
+  if (!client || typeof client.send !== "function") {
+    const result = { queued: false, runId: runResult.runId, to, code: "DD_EMAIL_CLIENT_MISSING" };
+    emit({
+      type: "dd_email_error",
+      event: "dd_email_error",
+      runId: runResult.runId,
+      to,
+      code: result.code,
+      error: "DD report email client is not configured.",
+    });
+    return result;
+  }
+
+  try {
+    const result = await client.send({ runId: runResult.runId, to, run: runResult });
+    if (result?.queued) {
+      emit({
+        type: "dd_email_queued",
+        event: "dd_email_queued",
+        runId: String(result.runId || runResult.runId),
+        to: String(result.to || to),
+        messageId: result.messageId || "",
+        replay: Boolean(result.replay),
+        sent: result.sent !== false,
+      });
+      return result;
+    }
+
+    emit({
+      type: "dd_email_error",
+      event: "dd_email_error",
+      runId: runResult.runId,
+      to,
+      code: String(result?.code || "DD_EMAIL_FAILED"),
+      status: Number(result?.status || 0),
+      error: redactDdEmailError(result?.error || "DD report email request failed."),
+    });
+    return result || { queued: false, runId: runResult.runId, to };
+  } catch (err) {
+    const result = {
+      queued: false,
+      runId: runResult.runId,
+      to,
+      code: "DD_EMAIL_EXCEPTION",
+      error: redactDdEmailError(err instanceof Error ? err.message : String(err)),
+    };
+    emit({
+      type: "dd_email_error",
+      event: "dd_email_error",
+      runId: runResult.runId,
+      to,
+      code: result.code,
+      error: result.error,
+    });
+    return result;
+  }
+}
+
 /**
  * Run the investor-DD orchestration end to end.
  *
@@ -183,6 +270,10 @@ function buildSummaryMarkdown({ runId, summary, routing, byPersona }) {
  * @param {object} [params.liveValidator.devTestBot]    - DevTestBot client.
  * @param {object} [params.liveValidator.aidenid]       - AIdenID client.
  * @param {number} [params.liveValidator.maxInteractions]
+ * @param {object|false} [params.devTestBot]     - Automated devTestBot phase config.
+ * @param {object|null} [params.reportEmail]     - Optional API-side report email trigger.
+ * @param {string} [params.reportEmail.to]
+ * @param {object} [params.reportEmail.client]   - { send({ runId, to, run }) }.
  * @param {object} [params.notification]         - Optional notification config.
  * @param {string} [params.notification.notifyEmail]
  * @param {object} [params.notification.emailClient]
@@ -198,6 +289,8 @@ export async function runInvestorDd({
   dryRun = false,
   compliancePacks = COMPLIANCE_PACK_CATALOG,
   liveValidator = null,
+  devTestBot = {},
+  reportEmail = null,
   notification = null,
 } = {}) {
   if (!rootPath) throw new TypeError("runInvestorDd requires rootPath");
@@ -207,6 +300,10 @@ export async function runInvestorDd({
   const artifactBase = outputDir
     ? path.resolve(outputDir, runId, INVESTOR_DD_ARTIFACT_SUBDIR)
     : path.resolve(rootPath, ".sentinelayer", "runs", runId, INVESTOR_DD_ARTIFACT_SUBDIR);
+  const runRoot = path.dirname(artifactBase);
+  const outputRoot = outputDir
+    ? path.resolve(outputDir)
+    : path.resolve(rootPath, ".sentinelayer");
   await fsp.mkdir(artifactBase, { recursive: true });
 
   const streamPath = path.join(artifactBase, "stream.ndjson");
@@ -244,9 +341,11 @@ export async function runInvestorDd({
   let terminationReason = "ok";
   let reconciliationAvailable = false;
   let compliance = null;
+  let devTestBotPhase = null;
+  let budgetState = null;
 
   if (!dryRun) {
-    const budgetState = createBudgetState({
+    budgetState = createBudgetState({
       maxUsd: resolvedBudget.maxCostUsd,
       maxRuntimeMs: resolvedBudget.maxRuntimeMinutes * 60_000,
     });
@@ -274,6 +373,20 @@ export async function runInvestorDd({
       totalGaps: compliance.totalGaps,
     });
 
+    devTestBotPhase = await runDevTestBotPhase({
+      runId,
+      rootPath,
+      outputRoot,
+      runRoot,
+      artifactDir: artifactBase,
+      files,
+      findings,
+      budget: budgetState,
+      options: devTestBot === false ? { enabled: false } : devTestBot || {},
+      onEvent: emit,
+    });
+    findings.push(...(devTestBotPhase.findings || []));
+
     // Live-web validation (Jules): optional; only runs when both
     // devTestBot + aidenid clients are supplied (pluggable contracts).
     if (
@@ -346,6 +459,16 @@ export async function runInvestorDd({
       ? { totalCovered: compliance.totalCovered, totalGaps: compliance.totalGaps }
       : null,
     reconciliation: reconciliationAvailable,
+    devTestBot: devTestBotPhase
+      ? {
+          skipped: Boolean(devTestBotPhase.skipped),
+          reason: devTestBotPhase.reason || "",
+          identityCount: devTestBotPhase.plan?.identityCount || devTestBotPhase.identities?.length || 0,
+          swarmCount: devTestBotPhase.plan?.swarmCount || devTestBotPhase.subagents?.length || 0,
+          findingCount: devTestBotPhase.findingCount || 0,
+          artifactRoot: devTestBotPhase.artifactRoot || "",
+        }
+      : null,
   };
   await writeJson(path.join(artifactBase, "summary.json"), summary);
 
@@ -369,6 +492,17 @@ export async function runInvestorDd({
     durationSeconds,
     terminationReason,
   });
+
+  const runResult = { runId, artifactDir: artifactBase, summary, findings, devTestBot: devTestBotPhase };
+  if (reportEmail) {
+    runResult.reportEmail = await triggerReportEmail({
+      reportEmail,
+      runResult,
+      dryRun,
+      emit,
+    });
+  }
+
   await streamHandle.close();
 
   const artifactFiles = await fsp.readdir(artifactBase);
@@ -385,8 +519,6 @@ export async function runInvestorDd({
   }
   await writeJson(path.join(artifactBase, "manifest.json"), manifest);
 
-  const runResult = { runId, artifactDir: artifactBase, summary, findings };
-
   // Fire-and-forget notification dispatch (email + dashboard). Failures
   // are non-fatal — the report is already persisted to disk + manifest.
   if (notification && (notification.emailClient || notification.dashboardClient)) {

package/src/review/omargate-orchestrator.js

@@ -321,7 +321,13 @@ async function runOmarPersonaSwarm({
     }));
   }
 
-  const parentRunDirectory = deterministic?.artifacts?.runDirectory || targetPath;
+  const parentRunDirectory =
+    deterministic?.artifacts?.runDirectory || path.join(targetPath, ".sentinelayer", "reviews", runId);
+  const systemPrompt = buildPersonaReviewPrompt({
+    personaId,
+    targetPath,
+    deterministicSummary: deterministic?.summary || {},
+  });
   const subagentResults = await runWithConcurrency(
     partitions.map((files, index) => ({ files, subagentIndex: index + 1 })),
     maxConcurrent,
@@ -380,6 +386,7 @@ async function runOmarPersonaSwarm({
           model: model || undefined,
           sessionId: `${subagentRunId}-ai`,
           maxCostUsd: budget.maxCostUsd,
+          systemPrompt,
           dryRun,
           env: process.env,
         });
@@ -450,6 +457,7 @@ async function runOmarPersonaSwarm({
           summary: result?.summary || summarizeFindings(findings),
           costUsd: result?.usage?.costUsd || 0,
           model: result?.model || model || null,
+          artifacts: result?.artifacts || null,
           durationMs: Date.now() - subagentStart,
         };
       } catch (err) {
@@ -564,6 +572,7 @@ async function runOmarPersonaSwarm({
         costUsd: result.costUsd || 0,
         durationMs: result.durationMs || 0,
         error: result.error || null,
+        artifacts: result.artifacts || null,
       })),
     },
   };
@@ -786,16 +795,23 @@ export async function runOmarGateOrchestrator({
         targetPath,
         mode: "full",
         runId: `${runId}-${personaId}`,
-        runDirectory: targetPath,
+        runDirectory: path.join(
+          deterministic?.artifacts?.runDirectory || path.join(targetPath, ".sentinelayer", "reviews", runId),
+          "personas",
+          personaId
+        ),
         deterministic: {
           summary: detSummary,
           findings: detFindings,
+          scope: deterministic?.scope || {},
+          layers: deterministic?.layers || {},
           metadata: deterministic?.metadata || {},
         },
         outputDir,
         provider: provider || undefined,
         model: model || undefined,
         maxCostUsd: perPersonaCost,
+        systemPrompt,
         dryRun,
         env: process.env,
       });
@@ -857,6 +873,7 @@ export async function runOmarGateOrchestrator({
         summary: result?.summary || { P0: 0, P1: 0, P2: 0, P3: 0 },
         costUsd: personaCost,
         model: result?.model || model || null,
+        artifacts: result?.artifacts || null,
         durationMs: Date.now() - personaStart,
       };
     } catch (err) {
@@ -977,6 +994,7 @@ export async function runOmarGateOrchestrator({
       model: r.model || null,
       error: r.error || null,
       swarm: r.swarm || null,
+      artifacts: r.artifacts || null,
     })),
     personaHealth,
     findings: reconciledFindings,

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

@@ -70,6 +70,28 @@ function normalizeConfidenceFloor(value) {
   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 = {},
@@ -202,15 +224,28 @@ export function reconcileReviewFindings({
       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),
@@ -260,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);
   };
 
@@ -354,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")

package/src/scan/generator.js

@@ -2,7 +2,7 @@ import YAML from "yaml";
 
 export const DEFAULT_SCAN_WORKFLOW_PATH = ".github/workflows/omar-gate.yml";
 export const DEFAULT_SCAN_SECRET_NAME = "SENTINELAYER_TOKEN";
-export const SENTINELAYER_ACTION_REF = "mrrCarter/sentinelayer-v1-action@55a2c158f637d7d92e26ab0ef3ba81db791da4be";
+export const SENTINELAYER_ACTION_REF = "mrrCarter/sentinelayer-v1-action@b13504565105b2496c5b1dbb7a3e9bf914c2a9f8";
 export const SUPPORTED_E2E_HINTS = Object.freeze(["auto", "yes", "no"]);
 export const SUPPORTED_PLAYWRIGHT_MODES = Object.freeze(["auto", "off", "baseline", "audit"]);
 

package/src/session/coordination-guidance.js

@@ -0,0 +1,49 @@
+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`.",
+  "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 listener for replies: `sl session listen --session <id> --agent <your-name> --interval 60 --active-interval 5 --emit ndjson`; this idles at 60s and switches to 5s after human activity. 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/event-identity.js

@@ -0,0 +1,139 @@
+function keyString(value) {
+  return String(value || "").trim();
+}
+
+function timestampKey(...values) {
+  for (const value of values) {
+    const normalized = keyString(value);
+    if (!normalized) continue;
+    const epoch = Date.parse(normalized);
+    if (Number.isFinite(epoch)) {
+      return new Date(epoch).toISOString();
+    }
+    return normalized;
+  }
+  return "";
+}
+
+function stableJsonValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => stableJsonValue(item));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entryValue]) => [key, stableJsonValue(entryValue)])
+    );
+  }
+  return value;
+}
+
+function stableStringify(value) {
+  return JSON.stringify(stableJsonValue(value));
+}
+
+export function sessionEventIdentityKeys(event = {}) {
+  if (!event || typeof event !== "object") return [];
+  const keys = [];
+  const id = keyString(event.id);
+  if (id) {
+    keys.push(`id:${id}`);
+  }
+  if (typeof event.cursor === "string" && event.cursor.trim()) {
+    keys.push(`cursor:${event.cursor.trim()}`);
+  }
+  if (typeof event.eventId === "string" && event.eventId.trim()) {
+    keys.push(`event:${event.eventId.trim()}`);
+  }
+  if (typeof event.idempotencyToken === "string" && event.idempotencyToken.trim()) {
+    keys.push(`idempotency:${event.idempotencyToken.trim()}`);
+  }
+  const payload = event.payload && typeof event.payload === "object" ? event.payload : {};
+  const messageId = typeof payload.messageId === "string" ? payload.messageId.trim() : "";
+  if (messageId) {
+    keys.push(`message:${messageId}`);
+  }
+  const timestamp = timestampKey(event.ts, event.timestamp, event.at);
+  const hasPayloadSignal = Object.keys(payload).length > 0;
+  const hasFingerprintSignal =
+    id || messageId || keyString(event.eventId) || keyString(event.idempotencyToken) ||
+    keyString(event.agent?.id || event.agentId) || timestamp || hasPayloadSignal;
+  if (hasFingerprintSignal) {
+    try {
+      keys.push(`fingerprint:${stableStringify({
+        event: event.event || event.type || "",
+        id,
+        eventId: keyString(event.eventId),
+        idempotencyToken: keyString(event.idempotencyToken),
+        agent: event.agent?.id || event.agentId || "",
+        payload,
+        ts: timestamp,
+      })}`);
+    } catch {
+      // Best-effort duplicate suppression only.
+    }
+  }
+  const message = keyString(payload.message || payload.text || payload.body);
+  if (message) {
+    try {
+      keys.push(`content:${stableStringify({
+        event: keyString(event.event || event.type),
+        agent: keyString(event.agent?.id || event.agentId || payload.agentId || payload.authorId),
+        payload: {
+          channel: keyString(payload.channel),
+          clientKind: keyString(payload.clientKind),
+          message,
+          source: keyString(payload.source),
+          to: payload.to || payload.recipient || payload.mentions || null,
+        },
+        ts: timestampKey(event.ts, event.timestamp, event.at),
+      })}`);
+    } catch {
+      // Best-effort duplicate suppression only.
+    }
+  }
+  return keys;
+}
+
+export function sessionEventHasKnownIdentity(event = {}, knownKeys = new Set()) {
+  const keys = sessionEventIdentityKeys(event);
+  return keys.length > 0 && keys.some((key) => knownKeys.has(key));
+}
+
+export function addSessionEventIdentityKeys(knownKeys, event = {}) {
+  for (const key of sessionEventIdentityKeys(event)) {
+    knownKeys.add(key);
+  }
+}
+
+export function dedupeSessionEvents(events = []) {
+  const normalizedEvents = Array.isArray(events) ? events : [];
+  const deduped = [];
+  const indexByKey = new Map();
+
+  for (const event of normalizedEvents) {
+    const keys = sessionEventIdentityKeys(event);
+    const existingIndexes = keys
+      .map((key) => indexByKey.get(key))
+      .filter((index) => Number.isInteger(index) && index >= 0);
+    const existingIndex = existingIndexes.length > 0 ? Math.min(...existingIndexes) : -1;
+
+    if (existingIndex >= 0) {
+      deduped[existingIndex] = event;
+      for (const key of keys) {
+        indexByKey.set(key, existingIndex);
+      }
+      continue;
+    }
+
+    const nextIndex = deduped.length;
+    deduped.push(event);
+    for (const key of keys) {
+      indexByKey.set(key, nextIndex);
+    }
+  }
+
+  return deduped;
+}