sentinelayer-cli 0.8.12 → 0.9.2

package/src/commands/swarm.js

@@ -517,6 +517,9 @@ export function registerSwarmCommand(program) {
     .option("--scenario-file <path>", "Scenario DSL file (.sls) for runtime actions")
     .option("--registry-file <path>", "Optional custom swarm registry file (when building plan inline)")
     .option("--agents <ids>", "Comma-separated agent ids for inline plan mode", "security,testing,reliability")
+    .option("--agent <id>", "Single agent id alias for --agents")
+    .option("--scope <scope>", "Runtime scope alias for --scenario, used by devTestBot")
+    .option("--identity-id <id>", "AIdenID identity id for devTestBot runtime")
     .option("--scenario <id>", "Scenario identifier for inline plan mode", "qa_audit")
     .option(
       "--objective <text>",
@@ -571,7 +574,7 @@ export function registerSwarmCommand(program) {
         const registry = await loadSwarmRegistry({
           registryFile: options.registryFile,
         });
-        const selected = selectSwarmAgents(registry.agents, options.agents);
+        const selected = selectSwarmAgents(registry.agents, options.agent || options.agents);
         if (selected.missing.length > 0) {
           throw new Error(`Unknown agent id(s): ${selected.missing.join(", ")}`);
         }
@@ -581,7 +584,7 @@ export function registerSwarmCommand(program) {
         const selectedAgents = ensureOmarIncluded(registry.agents, selected.selected);
         plan = buildSwarmExecutionPlan({
           targetPath,
-          scenario: scenarioIdOverride || options.scenario,
+          scenario: scenarioIdOverride || options.scope || options.scenario,
           objective: options.objective,
           agents: selectedAgents,
           maxParallel: parseMaxParallel(options.maxParallel),
@@ -612,6 +615,8 @@ export function registerSwarmCommand(program) {
         execute: Boolean(options.execute),
         maxSteps: parseMaxSteps(options.maxSteps),
         startUrl: startUrlOverride || options.startUrl,
+        identityId: options.identityId,
+        devTestBotScope: options.scope || scenarioIdOverride || options.scenario,
         playbookActions,
         outputDir: options.outputDir,
         env: process.env,
@@ -631,6 +636,10 @@ export function registerSwarmCommand(program) {
         stop: runtime.stop,
         usage: runtime.usage,
         eventCount: runtime.eventCount,
+        findingCount: runtime.findingCount,
+        findings: runtime.findings,
+        artifactBundles: runtime.artifactBundles,
+        devTestBotRuns: runtime.devTestBotRuns,
         runtimeDirectory: runtime.runtimeDirectory,
         runtimeJsonPath: runtime.runtimeJsonPath,
         runtimeMarkdownPath: runtime.runtimeMarkdownPath,

package/src/guide/generator.js

@@ -1,3 +1,9 @@
+import {
+  getCoordinationEtiquetteItems,
+  renderCoordinationMarkdownSection,
+  renderCoordinationTicketBlock,
+} from "../session/coordination-guidance.js";
+
 export const SUPPORTED_GUIDE_EXPORT_FORMATS = Object.freeze([
   "jira",
   "linear",
@@ -167,6 +173,8 @@ function buildTicket(phase, index) {
       "",
       "Acceptance criteria:",
       acceptanceBlock || "1. Phase outcomes are verified by deterministic checks.",
+      "",
+      renderCoordinationTicketBlock(),
     ].join("\n"),
   };
 }
@@ -235,6 +243,8 @@ ${goal}
 ## Phase Execution Plan
 ${phaseMarkdown}
 
+${renderCoordinationMarkdownSection()}
+
 ## Suggested PR Sequence
 ${resolvedPhases
   .map((phase, index) => `${index + 1}. ${phase.title} (${phase.effort.label})`)
@@ -246,6 +256,7 @@ ${resolvedPhases
     goal,
     phases: resolvedPhases,
     tickets,
+    coordinationRules: getCoordinationEtiquetteItems(),
     markdown,
   };
 }
@@ -256,12 +267,14 @@ export function renderGuideExport({ format, guide }) {
     project: guide.projectName,
     generated_at: new Date().toISOString(),
     issues: guide.tickets,
+    coordination_rules: Array.isArray(guide.coordinationRules) ? guide.coordinationRules : [],
   };
 
   if (normalized === "jira") {
     return JSON.stringify(
       {
         format: "jira",
+        coordination_rules: payload.coordination_rules,
         issues: payload.issues.map((issue) => ({
           summary: issue.title,
           description: issue.description,
@@ -279,6 +292,7 @@ export function renderGuideExport({ format, guide }) {
     return JSON.stringify(
       {
         format: "linear",
+        coordination_rules: payload.coordination_rules,
         issues: payload.issues.map((issue, index) => ({
           title: issue.title,
           description: issue.description,

package/src/legacy-cli.js

@@ -25,6 +25,10 @@ import { normalizeAgentEvent } from "./events/schema.js";
 import { collectCodebaseIngest, formatIngestSummary } from "./ingest/engine.js";
 import { getExpressTemplate, getPackageJsonTemplate, buildReadmeContent } from "./scaffold/templates.js";
 import { generateScaffold } from "./scaffold/generator.js";
+import {
+  getCoordinationEtiquetteItems,
+  renderCoordinationNumberedList,
+} from "./session/coordination-guidance.js";
 
 let DEFAULT_API_URL = process.env.SENTINELAYER_API_URL || "https://api.sentinelayer.com";
 let DEFAULT_WEB_URL = process.env.SENTINELAYER_WEB_URL || "https://sentinelayer.com";
@@ -1121,6 +1125,10 @@ async function runLocalOmarGateCommand(args) {
     const maxParallel =
       parseInt(getCommandOptionValue(args, "--max-parallel") || "3", 10) || 3;
     const streamEnabled = hasCommandOption(args, "--stream");
+    const devTestBotEnabled = !hasCommandOption(args, "--no-devtestbot");
+    const devTestBotBaseUrl = getCommandOptionValue(args, "--devtestbot-base-url") || "";
+    const devTestBotScope = getCommandOptionValue(args, "--devtestbot-scope") || "";
+    const emailOnComplete = getCommandOptionValue(args, "--email-on-complete") || "";
 
     const targetPath = path.resolve(process.cwd(), pathArg);
     if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
@@ -1128,6 +1136,9 @@ async function runLocalOmarGateCommand(args) {
     }
 
     const { runInvestorDd } = await import("./review/investor-dd-orchestrator.js");
+    const reportEmailClient = emailOnComplete
+      ? await import("./review/dd-report-email-client.js")
+      : null;
     if (!asJson) {
       printSection("Investor-DD Audit");
       printInfo(`Target: ${targetPath}`);
@@ -1141,6 +1152,24 @@ async function runLocalOmarGateCommand(args) {
       outputDir: outputDirArg,
       budgetOptions: { maxCostUsd, maxRuntimeMinutes, maxParallel },
       dryRun,
+      devTestBot: {
+        enabled: devTestBotEnabled,
+        baseUrl: devTestBotBaseUrl,
+        scope: devTestBotScope,
+      },
+      reportEmail: emailOnComplete
+        ? {
+            to: emailOnComplete,
+            client: {
+              send: ({ runId, to }) => reportEmailClient.sendDdReportEmail({
+                runId,
+                to,
+                cwd: targetPath,
+                env: process.env,
+              }),
+            },
+          }
+        : null,
       onEvent: streamEnabled
         ? (event) => process.stdout.write(`${JSON.stringify(event)}\n`)
         : () => {},
@@ -1950,6 +1979,7 @@ function buildCodingAgentConfigTemplate({ agentProfile, projectName }) {
     "Read docs/spec.md, docs/build-guide.md, tasks/todo.md, and AGENT_HANDOFF_PROMPT.md in order.",
     "Work one PR scope at a time and keep changes deterministic.",
     "Run local checks before push: /omargate deep and /audit.",
+    ...getCoordinationEtiquetteItems(),
   ];
 
   if (agentProfile.id === "aider") {
@@ -1960,7 +1990,7 @@ read:
   - tasks/todo.md
   - AGENT_HANDOFF_PROMPT.md
 notes:
-  - ${commonChecklist.join("\n  - ")}
+  - ${commonChecklist.map((item) => JSON.stringify(item)).join("\n  - ")}
 `;
   }
 
@@ -2186,16 +2216,7 @@ Repo context:
 
 ## Multi-Agent Coordination (if session active)
 
-If a SentinelLayer session is active (check \`sl session list\`):
-
-1. **On start:** Run \`sl session join <id> --name <your-name> --role coder\`
-2. **Periodically:** Run \`sl session say <id> "status: working on <file>"\` so others know what you're doing
-3. **On unexpected file change:** Instead of stopping, run:
-   \`sl session say <id> "help: unexpected change in <file> - who modified this?"\`
-   Then check \`sl session read <id> --tail 5\` for the answer and continue.
-4. **On findings:** Run \`sl session say <id> "finding: [P2] <title> in <file>:<line>"\`
-5. **On completion:** Run \`sl session leave <id>\`
-6. **Before modifying a file:** Check \`sl session read <id> --tail 10\` for recent activity on that file
+${renderCoordinationNumberedList()}
 
 Start now and continue autonomously.
 `;
@@ -2204,12 +2225,8 @@ Start now and continue autonomously.
 export function buildAgentsSessionGuideContent() {
   return `# SentinelLayer Session Guide for AI Agents
 
-## Quick Start
-1. Check: \`sl session list\` - is there an active session?
-2. Join: \`sl session join <id> --name <your-short-name> --role <coder|reviewer|tester>\`
-3. Read context: \`sl session read <id> --tail 20\` — see what others are doing
-4. Work: emit status every 5 min, post findings, ask for help instead of stopping
-5. Leave: \`sl session leave <id>\` when done
+## Required Etiquette
+${renderCoordinationNumberedList()}
 
 ## Why This Matters
 - Other agents can see what you're working on and avoid file conflicts
@@ -2299,7 +2316,7 @@ jobs:
           fi
       - name: Run Omar Gate
         id: omar
-        uses: mrrCarter/sentinelayer-v1-action@55a2c158f637d7d92e26ab0ef3ba81db791da4be
+        uses: mrrCarter/sentinelayer-v1-action@b13504565105b2496c5b1dbb7a3e9bf914c2a9f8
         with:
           sentinelayer_token: \${{ secrets.${normalizedSecret} }}${specIdBindingLine}
           scan_mode: \${{ github.event_name == 'workflow_dispatch' && inputs.scan_mode || 'deep' }}

package/src/prompt/generator.js

@@ -1,3 +1,5 @@
+import { getCoordinationEtiquetteItems } from "../session/coordination-guidance.js";
+
 export const SUPPORTED_PROMPT_TARGETS = Object.freeze([
   "claude",
   "cursor",
@@ -34,11 +36,7 @@ const TARGET_GUIDANCE = Object.freeze({
   ],
 });
 
-const SESSION_COORDINATION_GUIDANCE = Object.freeze([
-  "Multi-agent coordination: use `sl session` commands to communicate with other agents.",
-  "Always update the session chat room with your current activity so joining agents have context.",
-  "Never break your autonomous loop on unexpected file changes; ask in the session first.",
-]);
+const SESSION_COORDINATION_GUIDANCE = Object.freeze(getCoordinationEtiquetteItems());
 
 function normalizeTarget(target) {
   const normalized = String(target || "generic").trim().toLowerCase();
@@ -61,14 +59,6 @@ function buildAgentHeader(target) {
   return headers[target] || headers.generic;
 }
 
-function shouldAppendSessionGuidance(specMarkdown) {
-  const normalized = String(specMarkdown || "").toLowerCase();
-  if (!normalized) {
-    return false;
-  }
-  return normalized.includes("coordination protocol") || normalized.includes("session");
-}
-
 export function resolvePromptTarget(target) {
   return normalizeTarget(target);
 }
@@ -96,9 +86,7 @@ export function generateExecutionPrompt({
   }
 
   const operatingRules = [...guidance];
-  if (shouldAppendSessionGuidance(specText)) {
-    operatingRules.push(...SESSION_COORDINATION_GUIDANCE);
-  }
+  operatingRules.push(...SESSION_COORDINATION_GUIDANCE);
   const guidanceMarkdown = operatingRules.map((item, index) => `${index + 1}. ${item}`).join("\n");
 
   const hasAidenId = specText.toLowerCase().includes("aidenid");

package/src/review/ai-review.js

@@ -58,6 +58,20 @@ function sanitizeExcerpt(text) {
     .slice(0, 180);
 }
 
+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 extractJsonPayload(rawText) {
   const text = String(rawText || "").trim();
   if (!text) {
@@ -80,7 +94,10 @@ function extractJsonPayload(rawText) {
   for (const candidate of candidates) {
     try {
       const parsed = JSON.parse(candidate);
-      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      if (Array.isArray(parsed)) {
+        return { findings: parsed };
+      }
+      if (parsed && typeof parsed === "object") {
         return parsed;
       }
     } catch {
@@ -118,14 +135,31 @@ function normalizeConfidence(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 normalizeAiFinding(rawFinding, index) {
   if (!rawFinding || typeof rawFinding !== "object" || Array.isArray(rawFinding)) {
     return null;
   }
 
   const message = normalizeString(rawFinding.title || rawFinding.message);
-  const rationale = normalizeString(rawFinding.rationale || rawFinding.excerpt);
-  const suggestedFix = normalizeString(rawFinding.suggestedFix);
+  const evidence = normalizeString(rawFinding.evidence || rawFinding.excerpt);
+  const rootCause = normalizeString(rawFinding.rootCause || rawFinding.root_cause || rawFinding.rationale);
+  const recommendedFix = normalizeString(
+    rawFinding.recommendedFix || rawFinding.recommended_fix || rawFinding.suggestedFix
+  );
+  const rationale = normalizeString(rawFinding.rationale || rootCause || evidence || rawFinding.excerpt);
+  const suggestedFix = normalizeString(rawFinding.suggestedFix || recommendedFix);
+  const lensEvidence = cloneJsonCompatible(rawFinding.lensEvidence || rawFinding.lens_evidence);
+  const reproduction = cloneJsonCompatible(rawFinding.reproduction);
+  const userImpact = normalizeString(rawFinding.userImpact || rawFinding.user_impact);
+  const trafficLight = normalizeTrafficLight(rawFinding.trafficLight || rawFinding.traffic_light);
 
   return {
     severity: normalizeSeverity(rawFinding.severity),
@@ -134,6 +168,13 @@ function normalizeAiFinding(rawFinding, index) {
     message: message || `AI finding ${index + 1}`,
     rationale: rationale || "AI reviewer flagged a potential issue requiring validation.",
     suggestedFix: suggestedFix || "Review and remediate this finding.",
+    evidence,
+    lensEvidence,
+    reproduction,
+    userImpact,
+    trafficLight,
+    rootCause,
+    recommendedFix: recommendedFix || suggestedFix || "Review and remediate this finding.",
     confidence: normalizeConfidence(rawFinding.confidence),
   };
 }
@@ -212,6 +253,7 @@ export function buildAiReviewPrompt({
   deterministicFindings = [],
   scopedFiles = [],
   specContext = null,
+  systemPrompt = "",
   maxFindings = DEFAULT_AI_MAX_FINDINGS,
 } = {}) {
   const normalizedSummary = deterministicSummary || { P0: 0, P1: 0, P2: 0, P3: 0 };
@@ -226,7 +268,7 @@ export function buildAiReviewPrompt({
   const specAcceptanceCriteriaCount = Number(specContext?.acceptanceCriteriaCount || 0);
   const specPreview = Array.isArray(specContext?.endpointsPreview) ? specContext.endpointsPreview : [];
 
-  return [
+  const basePrompt = [
     "You are Sentinelayer Omar reviewer layer 9.3.",
     "Review the deterministic findings and scoped files. Add ONLY materially new findings.",
     "Do not repeat deterministic findings unless you add new exploitability rationale.",
@@ -241,6 +283,13 @@ export function buildAiReviewPrompt({
     '      "file": "relative/path",',
     '      "line": 1,',
     '      "title": "finding title",',
+    '      "evidence": "concrete code excerpt or static trace evidence",',
+    '      "lensEvidence": {"A": "passed|failed|not_applicable: short evidence"},',
+    '      "reproduction": {"type": "static_trace|manual_step|shell|runtime_probe", "steps": ["step 1"]},',
+    '      "user_impact": "operator/user/system impact",',
+    '      "trafficLight": "green|yellow|red",',
+    '      "rootCause": "why this exists",',
+    '      "recommendedFix": "specific remediation",',
     '      "rationale": "why this matters",',
     '      "suggestedFix": "specific remediation",',
     '      "confidence": 0.0',
@@ -265,6 +314,18 @@ export function buildAiReviewPrompt({
     "Deterministic findings:",
     findingLines || "- none",
   ].join("\n");
+
+  const promptPrelude = normalizeString(systemPrompt);
+  if (!promptPrelude) {
+    return basePrompt;
+  }
+  return [
+    promptPrelude,
+    "",
+    "---",
+    "",
+    basePrompt,
+  ].join("\n");
 }
 
 function maybeEstimateModelCost({ modelId, inputTokens, outputTokens }) {
@@ -305,6 +366,9 @@ function composeAiReviewMarkdown({
             (finding, index) =>
               `${index + 1}. [${finding.severity}] ${finding.file}:${finding.line} ${finding.message}\n` +
               `   rationale: ${finding.rationale}\n` +
+              (finding.evidence ? `   evidence: ${finding.evidence}\n` : "") +
+              (finding.userImpact ? `   user_impact: ${finding.userImpact}\n` : "") +
+              (finding.trafficLight ? `   traffic_light: ${finding.trafficLight}\n` : "") +
               `   suggested_fix: ${finding.suggestedFix}` +
               (finding.confidence === null ? "" : `\n   confidence: ${finding.confidence.toFixed(2)}`)
           )
@@ -335,16 +399,25 @@ function composeAiReviewMarkdown({
 }
 
 function toReviewFinding(aiFinding, index) {
+  const suggestedFix = aiFinding.suggestedFix || aiFinding.recommendedFix;
   return {
     severity: aiFinding.severity,
     file: aiFinding.file,
     line: aiFinding.line,
     message: aiFinding.message,
-    excerpt: sanitizeExcerpt(aiFinding.rationale),
+    excerpt: sanitizeExcerpt(aiFinding.evidence || aiFinding.rationale),
     ruleId: `SL-AI-${String(index + 1).padStart(3, "0")}`,
-    suggestedFix: aiFinding.suggestedFix,
+    suggestedFix,
     layer: "ai_reasoning",
     confidence: aiFinding.confidence,
+    evidence: aiFinding.evidence,
+    lensEvidence: aiFinding.lensEvidence,
+    reproduction: aiFinding.reproduction,
+    userImpact: aiFinding.userImpact,
+    trafficLight: aiFinding.trafficLight,
+    rootCause: aiFinding.rootCause,
+    recommendedFix: aiFinding.recommendedFix || suggestedFix,
+    rationale: aiFinding.rationale,
   };
 }
 
@@ -357,6 +430,20 @@ function buildDryRunResponse({ deterministicSummary, maxFindings } = {}) {
       file: "src/example.js",
       line: 1 + index,
       title: `DRY_RUN finding ${index + 1}`,
+      evidence: "const unsafe = exampleInput;",
+      lensEvidence: {
+        A: "not_applicable: no route/runtime boundary in dry-run fixture",
+        J: "failed: synthetic path needs targeted verification before merge",
+        K: "passed: no AI tool permission escalation in dry-run fixture",
+      },
+      reproduction: {
+        type: "static_trace",
+        steps: ["Inspect src/example.js", "Trace exampleInput into the synthetic finding path"],
+      },
+      user_impact: "Operator sees a synthetic risk used to validate OmarGate evidence plumbing.",
+      trafficLight: index === 0 ? "yellow" : "green",
+      rootCause: "DRY_RUN synthetic root cause for evidence-contract validation.",
+      recommendedFix: "Validate this path with targeted remediation.",
       rationale: `Synthetic AI rationale with deterministic context P1=${deterministicSummary.P1}.`,
       suggestedFix: "Validate this path with targeted remediation.",
       confidence: index === 0 ? 0.72 : 0.54,
@@ -393,6 +480,7 @@ export async function runAiReviewLayer({
   maxToolCalls = 0,
   maxNoProgress = 3,
   warningThresholdPercent = 80,
+  systemPrompt = "",
   dryRun = false,
   env = process.env,
 } = {}) {
@@ -436,6 +524,7 @@ export async function runAiReviewLayer({
     deterministicFindings: deterministic?.findings || [],
     scopedFiles: deterministic?.scope?.scannedRelativeFiles || [],
     specContext: deterministic?.layers?.specBinding || null,
+    systemPrompt,
     maxFindings: normalizedMaxFindings,
   });
 

package/src/review/dd-report-email-client.js

@@ -0,0 +1,148 @@
+import crypto from "node:crypto";
+
+import { resolveActiveAuthSession } from "../auth/service.js";
+import { requestJson } from "../auth/http.js";
+
+export const DD_REPORT_EMAIL_TIMEOUT_MS = 10_000;
+
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+export function normalizeReportEmail(value) {
+  const normalized = normalizeString(value);
+  if (!EMAIL_RE.test(normalized)) {
+    return "";
+  }
+  return normalized;
+}
+
+export function buildReportEmailIdempotencyKey({ runId, to }) {
+  const digest = crypto
+    .createHash("sha256")
+    .update(`${normalizeString(runId)}\0${normalizeString(to).toLowerCase()}`)
+    .digest("hex")
+    .slice(0, 32);
+  return `sl-cli-dd-email-${digest}`;
+}
+
+export function redactDdEmailError(value) {
+  return normalizeString(value)
+    .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]")
+    .replace(/[A-Za-z]:[\\/][^\s"'<>]+/g, "[LOCAL_PATH]")
+    .replace(/api[_-]?key\s*=\s*[^&\s]+/gi, "api_key=[REDACTED]")
+    .slice(0, 500);
+}
+
+function normalizeTimeoutMs(env = process.env) {
+  const parsed = Number(env.SENTINELAYER_DD_EMAIL_TIMEOUT_MS);
+  if (Number.isFinite(parsed) && parsed > 0) {
+    return Math.max(100, Math.floor(parsed));
+  }
+  return DD_REPORT_EMAIL_TIMEOUT_MS;
+}
+
+function errorResult({ runId, to, code, message, status = 0, requestId = null }) {
+  return {
+    queued: false,
+    sent: false,
+    runId: normalizeString(runId),
+    to: normalizeString(to),
+    code: normalizeString(code) || "DD_EMAIL_FAILED",
+    error: redactDdEmailError(message) || "DD report email request failed.",
+    status: Number(status || 0),
+    requestId: requestId ? String(requestId) : null,
+  };
+}
+
+/**
+ * Trigger the API-side investor-DD report email endpoint for a completed run.
+ *
+ * The caller owns run completion and event emission. This helper only handles
+ * auth resolution, bounded network behavior, idempotency, and redacted errors.
+ */
+export async function sendDdReportEmail({
+  runId,
+  to,
+  cwd = process.cwd(),
+  env = process.env,
+  resolveAuthSession = resolveActiveAuthSession,
+  requestJsonImpl = requestJson,
+  timeoutMs = normalizeTimeoutMs(env),
+} = {}) {
+  const normalizedRunId = normalizeString(runId);
+  const normalizedTo = normalizeReportEmail(to);
+  if (!normalizedRunId) {
+    return errorResult({ runId, to, code: "DD_EMAIL_RUN_ID_REQUIRED", message: "runId is required." });
+  }
+  if (!normalizedTo) {
+    return errorResult({ runId, to, code: "DD_EMAIL_INVALID_RECIPIENT", message: "Invalid report email recipient." });
+  }
+
+  let session = null;
+  try {
+    session = await resolveAuthSession({
+      cwd,
+      env,
+      autoRotate: false,
+    });
+  } catch (err) {
+    return errorResult({
+      runId: normalizedRunId,
+      to: normalizedTo,
+      code: "DD_EMAIL_AUTH_UNAVAILABLE",
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  if (!session || !session.token) {
+    return errorResult({
+      runId: normalizedRunId,
+      to: normalizedTo,
+      code: "DD_EMAIL_AUTH_REQUIRED",
+      message: "Authenticate before sending DD report email.",
+    });
+  }
+
+  const apiUrl = normalizeString(session.apiUrl) || "https://api.sentinelayer.com";
+  const endpoint = `${apiUrl.replace(/\/+$/, "")}/api/v1/runs/${encodeURIComponent(
+    normalizedRunId,
+  )}/send-report-email`;
+  const idempotencyKey = buildReportEmailIdempotencyKey({
+    runId: normalizedRunId,
+    to: normalizedTo,
+  });
+
+  try {
+    const response = await requestJsonImpl(endpoint, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${session.token}`,
+      },
+      idempotencyKey,
+      body: { to: normalizedTo },
+      timeoutMs,
+      maxRetries: 1,
+    });
+    return {
+      queued: true,
+      sent: Boolean(response?.sent ?? true),
+      runId: normalizeString(response?.run_id) || normalizedRunId,
+      to: normalizeString(response?.to) || normalizedTo,
+      messageId: normalizeString(response?.message_id),
+      replay: Boolean(response?.replay),
+      idempotencyKey,
+    };
+  } catch (err) {
+    return errorResult({
+      runId: normalizedRunId,
+      to: normalizedTo,
+      code: err?.code || "DD_EMAIL_REQUEST_FAILED",
+      message: err instanceof Error ? err.message : String(err),
+      status: err?.status || 0,
+      requestId: err?.requestId || null,
+    });
+  }
+}