@oneuptime/common 11.5.4 → 11.5.5

package/Server/Utils/AI/SRE/Insights/InsightStore.ts

@@ -0,0 +1,283 @@
+import ObjectID from "../../../../../Types/ObjectID";
+import OneUptimeDate from "../../../../../Types/Date";
+import ColumnLength from "../../../../../Types/Database/ColumnLength";
+import SortOrder from "../../../../../Types/BaseDatabase/SortOrder";
+import AIInsight from "../../../../../Models/DatabaseModels/AIInsight";
+import AIInsightStatus, {
+  AIInsightStatusHelper,
+} from "../../../../../Types/AI/AIInsightStatus";
+import AIInsightService from "../../../../Services/AIInsightService";
+import { InsightCandidate } from "./Types";
+import logger from "../../../Logger";
+import CaptureSpan from "../../../Telemetry/CaptureSpan";
+
+/*
+ * AI Insights — the dedupe/upsert store between detectors and the
+ * AIInsight table. Detectors re-emit the same finding on every scan
+ * tick while the underlying signal persists; the store's job is to keep the
+ * inbox quiet: one row per live finding (refreshed in place), a cooldown on
+ * findings a human already dismissed, and a hard cap on how many NEW rows a
+ * single scan may create.
+ */
+
+/*
+ * G4/G11 volume guardrail: a single scan tick may create at most this many
+ * NEW insights per project. A telemetry storm (deploy gone wrong, detector
+ * mis-tuning) would otherwise flood the inbox — and every new insight fans
+ * out into budgeted triage/fix work. Recurring findings still refresh their
+ * existing rows beyond the cap; drops are logged, never silent.
+ */
+export const MAX_NEW_INSIGHTS_PER_PROJECT_PER_SCAN: number = 10;
+
+/*
+ * G11 noise posture: a human dismissal is the strongest precision signal we
+ * have, so a finding with the same fingerprint stays suppressed for this
+ * many days after the dismissal instead of reappearing on the next tick.
+ * After the cooldown (or after a Resolved insight's signal returns) a fresh
+ * insight is warranted — a resolved issue that reappears is a regression.
+ */
+export const DISMISSED_COOLDOWN_DAYS: number = 7;
+
+/*
+ * Column-safety clamps: DatabaseService validates string columns against the
+ * model's declared lengths and THROWS on overflow, and detectors embed raw
+ * telemetry strings (a span name can be an entire SQL statement, exception
+ * types and service names are unbounded). Clamping here — the single choke
+ * point where candidates become rows — protects every current and future
+ * detector. The fingerprint clamp is applied to the dedupe LOOKUP as well as
+ * the insert, so a clamped fingerprint keeps refreshing the same row instead
+ * of failing (or duplicating) on every tick. Values mirror the
+ * AIInsight column definitions (LongText/ShortText).
+ */
+export const INSIGHT_FINGERPRINT_MAX_LENGTH: number = ColumnLength.LongText;
+export const INSIGHT_TITLE_MAX_LENGTH: number = ColumnLength.LongText;
+export const INSIGHT_SERVICE_NAME_MAX_LENGTH: number = ColumnLength.LongText;
+export const INSIGHT_METRIC_NAME_MAX_LENGTH: number = ColumnLength.LongText;
+export const INSIGHT_TRACE_ID_MAX_LENGTH: number = ColumnLength.ShortText;
+
+export interface UpsertCandidatesResult {
+  // Newly created insights (status Detected) — the scanner routes these.
+  created: Array<AIInsight>;
+  // Existing non-terminal insights refreshed in place.
+  refreshed: number;
+  // Candidates suppressed by the dismissed-fingerprint cooldown.
+  suppressed: number;
+  // Candidates dropped by MAX_NEW_INSIGHTS_PER_PROJECT_PER_SCAN.
+  droppedByCap: number;
+}
+
+export default class InsightStore {
+  /*
+   * Upsert one scan tick's candidates for one project. For each candidate,
+   * the most recent insight with the same (projectId, fingerprint) decides
+   * the outcome:
+   *   - none                          → CREATE (subject to the per-scan cap)
+   *   - non-terminal                  → REFRESH (never touches status)
+   *   - Dismissed within the cooldown → suppress
+   *   - Dismissed past the cooldown,
+   *     or Resolved                   → CREATE (regression / recurrence)
+   * All access is root-props: the scanner is a system actor with explicit
+   * projectId scoping, not a per-user ACL consumer.
+   */
+  @CaptureSpan()
+  public static async upsertCandidates(data: {
+    projectId: ObjectID;
+    candidates: Array<InsightCandidate>;
+    now: Date;
+  }): Promise<UpsertCandidatesResult> {
+    const result: UpsertCandidatesResult = {
+      created: [],
+      refreshed: 0,
+      suppressed: 0,
+      droppedByCap: 0,
+    };
+
+    // No silent caps: dropped fingerprints are logged after the loop.
+    const droppedFingerprints: Array<string> = [];
+
+    for (const candidate of data.candidates) {
+      /*
+       * Per-candidate isolation: one failing candidate (transient DB error,
+       * unexpected data) must not abort the batch — insights created earlier
+       * in this tick are returned for routing either way, and the remaining
+       * candidates still get their chance. Without this, a mid-batch failure
+       * would strand already-created rows in Detected forever (refreshes
+       * never touch status, so they would never be routed).
+       */
+      try {
+        /*
+         * The clamped fingerprint is the row's identity everywhere — lookup
+         * and insert — so dedupe survives the clamp (see the constants).
+         */
+        const fingerprint: string = this.clampToColumn(
+          candidate.fingerprint,
+          INSIGHT_FINGERPRINT_MAX_LENGTH,
+        );
+
+        /*
+         * Most recent row wins: (projectId, fingerprint) is deliberately NOT
+         * unique — terminal rows accumulate as history — so sort by createdAt
+         * to judge against the latest lifecycle state of this finding.
+         */
+        const existing: AIInsight | null = await AIInsightService.findOneBy({
+          query: {
+            projectId: data.projectId,
+            fingerprint: fingerprint,
+          },
+          select: {
+            _id: true,
+            status: true,
+            occurrenceCount: true,
+            humanVerdictAt: true,
+          },
+          sort: { createdAt: SortOrder.Descending },
+          props: { isRoot: true },
+        });
+
+        if (
+          existing &&
+          existing.status &&
+          !AIInsightStatusHelper.isTerminalStatus(existing.status)
+        ) {
+          /*
+           * REFRESH: the finding is still live and already has a row. The
+           * evidence/severity are replaced with this tick's numbers (the
+           * newest picture of the signal), but status is NEVER touched here —
+           * routing (ActionRequired/FixOpened) happened when the row was
+           * created and humans/fix flows own it from there.
+           */
+          await AIInsightService.updateOneById({
+            id: existing.id!,
+            data: {
+              lastSeenAt: data.now,
+              occurrenceCount: (existing.occurrenceCount || 1) + 1,
+              severity: candidate.severity,
+              detailMarkdown: candidate.detailMarkdown,
+              evidence: candidate.evidence,
+            },
+            props: { isRoot: true },
+          });
+
+          result.refreshed++;
+          continue;
+        }
+
+        if (existing && existing.status === AIInsightStatus.Dismissed) {
+          /*
+           * Cooldown is measured from the human's dismissal, inclusive at the
+           * boundary (exactly DISMISSED_COOLDOWN_DAYS old still suppresses).
+           * A Dismissed row without a verdict timestamp cannot prove the
+           * cooldown elapsed, so it suppresses too — when in doubt, stay
+           * quiet (G11 noise posture).
+           */
+          const cooldownMs: number = OneUptimeDate.getMillisecondsInDays(
+            DISMISSED_COOLDOWN_DAYS,
+          );
+
+          const withinCooldown: boolean = existing.humanVerdictAt
+            ? data.now.getTime() -
+                OneUptimeDate.fromString(existing.humanVerdictAt).getTime() <=
+              cooldownMs
+            : true;
+
+          if (withinCooldown) {
+            logger.debug(
+              `AI Insights: suppressing candidate ${fingerprint} for project ${data.projectId.toString()} — dismissed by a human within the last ${DISMISSED_COOLDOWN_DAYS} days.`,
+            );
+
+            result.suppressed++;
+            continue;
+          }
+        }
+
+        /*
+         * CREATE: no live row for this fingerprint (never seen, Resolved, or
+         * Dismissed long enough ago). Subject to the per-scan cap.
+         */
+        if (result.created.length >= MAX_NEW_INSIGHTS_PER_PROJECT_PER_SCAN) {
+          droppedFingerprints.push(fingerprint);
+          result.droppedByCap++;
+          continue;
+        }
+
+        const insight: AIInsight = new AIInsight();
+        insight.projectId = data.projectId;
+        insight.insightType = candidate.insightType;
+        // Defensive initial state — the scanner routes it in the same tick.
+        insight.status = AIInsightStatus.Detected;
+        insight.severity = candidate.severity;
+        insight.fingerprint = fingerprint;
+        insight.title = this.clampToColumn(
+          candidate.title,
+          INSIGHT_TITLE_MAX_LENGTH,
+        );
+        insight.detailMarkdown = candidate.detailMarkdown;
+        insight.evidence = candidate.evidence;
+        insight.firstSeenAt = data.now;
+        insight.lastSeenAt = data.now;
+        insight.occurrenceCount = 1;
+
+        if (candidate.serviceName) {
+          insight.serviceName = this.clampToColumn(
+            candidate.serviceName,
+            INSIGHT_SERVICE_NAME_MAX_LENGTH,
+          );
+        }
+        if (candidate.telemetryServiceId) {
+          insight.telemetryServiceId = candidate.telemetryServiceId;
+        }
+        if (candidate.telemetryExceptionId) {
+          insight.telemetryExceptionId = candidate.telemetryExceptionId;
+        }
+        if (candidate.traceId) {
+          insight.traceId = this.clampToColumn(
+            candidate.traceId,
+            INSIGHT_TRACE_ID_MAX_LENGTH,
+          );
+        }
+        if (candidate.metricName) {
+          insight.metricName = this.clampToColumn(
+            candidate.metricName,
+            INSIGHT_METRIC_NAME_MAX_LENGTH,
+          );
+        }
+
+        const created: AIInsight = await AIInsightService.create({
+          data: insight,
+          props: { isRoot: true },
+        });
+
+        result.created.push(created);
+      } catch (error) {
+        logger.error(
+          `AI Insights: upsert failed for candidate ${candidate.fingerprint} (project ${data.projectId.toString()}) — continuing with the remaining candidates: ${error}`,
+        );
+      }
+    }
+
+    if (result.droppedByCap > 0) {
+      logger.debug(
+        `AI Insights: candidate fingerprints dropped by the per-scan cap for project ${data.projectId.toString()}: ${droppedFingerprints.join(", ")}`,
+      );
+      logger.info(
+        `AI Insights: per-scan new-insight cap (${MAX_NEW_INSIGHTS_PER_PROJECT_PER_SCAN}) reached for project ${data.projectId.toString()} — dropped ${result.droppedByCap} candidate(s) this tick. Recurring findings will re-surface on later ticks if their signal persists.`,
+      );
+    }
+
+    return result;
+  }
+
+  /*
+   * Hard code-unit slice to the column's declared length — the same measure
+   * DatabaseService validates against, so a clamped value can never trip the
+   * length check. No cosmetic ellipsis: detectors own presentation; this is
+   * purely a data-safety guard, and it must be deterministic so a clamped
+   * fingerprint stays stable across ticks.
+   */
+  private static clampToColumn(value: string, maxLength: number): string {
+    if (value.length <= maxLength) {
+      return value;
+    }
+    return value.slice(0, maxLength);
+  }
+}

package/Server/Utils/AI/SRE/Insights/InsightTriageRunner.ts

@@ -0,0 +1,242 @@
+import ObjectID from "../../../../../Types/ObjectID";
+import OneUptimeDate from "../../../../../Types/Date";
+import AIInsight from "../../../../../Models/DatabaseModels/AIInsight";
+import AIInsightEvidence from "../../../../../Types/AI/AIInsightEvidence";
+import AIInsightService from "../../../../Services/AIInsightService";
+import { AI_INSIGHT_TRIAGE_FEATURE } from "../../../../Services/AIService";
+import AIInvestigationEngine from "../AIInvestigationEngine";
+import AIInvestigationQueue from "../InvestigationQueue";
+import { ConfidenceSignal } from "../ConfidenceSignal";
+import { ObservabilityAssistantResult } from "../../Chat/ObservabilityAssistant";
+import logger from "../../../Logger";
+import CaptureSpan from "../../../Telemetry/CaptureSpan";
+
+/*
+ * AI SRE — per-insight preventive triage.
+ *
+ * A deterministic detector filed a AIInsight; this runner executes the
+ * budgeted, read-only Investigation AIRun that triages it: most likely root
+ * cause, estimated blast radius, ONE recommended next action — every claim
+ * cited. Structurally a sibling of IncidentInvestigationRunner: the queue
+ * claims the run and dispatches here; the shared engine owns the run
+ * lifecycle, the agent loop and the confidence signal.
+ *
+ * The difference is the OUTPUT SINK. Insights never page and never open
+ * incidents (the roadmap's Preventive-lane rule), so postAnalysis writes the
+ * summary onto the insight row and NOTHING else — the quiet inbox.
+ */
+
+/*
+ * Cap on the rendered evidence JSON embedded in the triage prompt. Latency
+ * evidence carries span-tree findings that can be large; the numbers matter,
+ * an exhaustive span listing does not.
+ */
+const MAX_RENDERED_EVIDENCE_CHARS: number = 4000;
+
+/*
+ * The preventive-triage framing, prepended to the subject description. The
+ * engine's persona is written for a just-declared incident/alert, so the
+ * request context must recast the situation before the insight is described
+ * (the engine embeds contextSummary into the investigation question — the
+ * same mechanism the incident runner uses to convey its subject).
+ */
+const PREVENTIVE_TRIAGE_FRAMING: string = `IMPORTANT — this is PREVENTIVE TRIAGE, not an incident investigation: NO incident or alert exists and nobody has been paged. A deterministic statistical sensor (no AI involved) watched this project's telemetry and filed the finding described below, with the evidence it computed. Your job:
+- Establish the most likely root cause of the finding.
+- Estimate the blast radius: which services/users/operations are affected, and how badly.
+- Recommend exactly ONE next action (the single most useful thing an engineer should do first).
+Cite the evidence for every factual claim. If the telemetry cannot support a conclusion, say so plainly. Do not refer to "the incident" — there is none.`;
+
+export default class InsightTriageRunner {
+  /*
+   * Execute a claimed triage run: load the insight, build its description
+   * and hand it to the shared engine. Called by AIInvestigationQueue
+   * after a successful claim. Never throws — failures are handed to the
+   * queue's retry policy so a claimed run is always finalized or requeued.
+   */
+  @CaptureSpan()
+  public static async executeTriage(data: {
+    aiRunId: ObjectID;
+    projectId: ObjectID;
+    sentinelInsightId: ObjectID;
+    attemptCount: number;
+  }): Promise<void> {
+    const { aiRunId, projectId, sentinelInsightId, attemptCount } = data;
+
+    let contextSummary: string;
+    try {
+      const insight: AIInsight | null = await AIInsightService.findOneById({
+        id: sentinelInsightId,
+        select: {
+          _id: true,
+          insightType: true,
+          severity: true,
+          title: true,
+          detailMarkdown: true,
+          evidence: true,
+          serviceName: true,
+          traceId: true,
+          metricName: true,
+          firstSeenAt: true,
+          lastSeenAt: true,
+          occurrenceCount: true,
+        },
+        props: { isRoot: true },
+      });
+
+      if (!insight) {
+        throw new Error(
+          "AI insight not found — it may have been deleted after the triage run was enqueued.",
+        );
+      }
+
+      contextSummary = this.buildInsightSummary(insight);
+    } catch (error) {
+      /*
+       * Context assembly failed — the run is claimed, so hand it to the
+       * retry policy rather than leaving it Running until the sweeper.
+       */
+      await AIInvestigationQueue.failOrRequeue({
+        aiRunId,
+        attemptCount,
+        errorMessage: `Failed to build insight context: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        isPermanent: false,
+      });
+      return;
+    }
+
+    await AIInvestigationEngine.executeRun({
+      aiRunId,
+      projectId,
+      attemptCount,
+      request: {
+        feature: AI_INSIGHT_TRIAGE_FEATURE,
+        contextSummary,
+        postAnalysis: async (postData: {
+          analysisMarkdown: string;
+          confidence: ConfidenceSignal;
+          result: ObservabilityAssistantResult;
+        }): Promise<void> => {
+          /*
+           * The quiet inbox — deliberately the ONLY write: no feed items,
+           * no workspace notification, no owner/on-call ping, no metrics,
+           * and no instrumentation-task trigger. Insights never page and
+           * never enter the notification pipeline (Preventive-lane rule);
+           * the summary waits on the Insights page until a human looks.
+           */
+          await AIInsightService.updateOneById({
+            id: sentinelInsightId,
+            data: {
+              triageSummaryMarkdown: postData.analysisMarkdown,
+              triageCompletedAt: OneUptimeDate.getCurrentDate(),
+            },
+            props: { isRoot: true },
+          });
+
+          logger.debug(
+            `AI insights: triage summary posted for insight ${sentinelInsightId.toString()} (run ${aiRunId.toString()}, confident=${postData.confidence.confident} via ${postData.confidence.source}).`,
+          );
+        },
+      },
+    });
+  }
+
+  // Build the compact insight record that seeds the triage.
+  private static buildInsightSummary(insight: AIInsight): string {
+    const lines: Array<string> = [];
+
+    lines.push(PREVENTIVE_TRIAGE_FRAMING);
+    lines.push("");
+    lines.push("# Insight finding");
+    lines.push(`Finding type: ${insight.insightType || "N/A"}`);
+    lines.push(`Title: ${insight.title || "N/A"}`);
+    lines.push(`Severity: ${insight.severity || "N/A"}`);
+
+    if (insight.serviceName) {
+      lines.push(`Attributed service: ${insight.serviceName}`);
+    }
+    if (insight.metricName) {
+      lines.push(`Metric: ${insight.metricName}`);
+    }
+    if (insight.traceId) {
+      lines.push(`Representative trace id: ${insight.traceId}`);
+    }
+    if (insight.firstSeenAt) {
+      lines.push(
+        `First seen: ${OneUptimeDate.getDateAsFormattedString(insight.firstSeenAt)}`,
+      );
+    }
+    if (insight.lastSeenAt) {
+      lines.push(
+        `Last seen: ${OneUptimeDate.getDateAsFormattedString(insight.lastSeenAt)}`,
+      );
+    }
+    if (insight.occurrenceCount) {
+      lines.push(`Times detected: ${insight.occurrenceCount}`);
+    }
+
+    if (insight.detailMarkdown) {
+      lines.push("");
+      lines.push(
+        "## Detector's evidence (deterministic, computed at detect time)",
+      );
+      lines.push(insight.detailMarkdown);
+    }
+
+    const renderedEvidence: string = this.renderEvidence(insight.evidence);
+    if (renderedEvidence) {
+      lines.push("");
+      lines.push("## Raw evidence values");
+      lines.push(renderedEvidence);
+    }
+
+    return lines.join("\n");
+  }
+
+  /*
+   * Render the stored evidence JSON compactly: one line per populated
+   * section, values verbatim (the numbers ARE the evidence), capped so a
+   * large span-tree finding cannot flood the prompt.
+   */
+  private static renderEvidence(
+    evidence: AIInsightEvidence | undefined,
+  ): string {
+    if (!evidence) {
+      return "";
+    }
+
+    const lines: Array<string> = [];
+
+    const sections: Array<keyof AIInsightEvidence> = [
+      "exception",
+      "logSpike",
+      "latency",
+      "metricDrift",
+    ];
+
+    for (const section of sections) {
+      const value: AIInsightEvidence[keyof AIInsightEvidence] =
+        evidence[section];
+
+      if (!value) {
+        continue;
+      }
+
+      let rendered: string;
+      try {
+        rendered = JSON.stringify(value);
+      } catch {
+        continue;
+      }
+
+      if (rendered.length > MAX_RENDERED_EVIDENCE_CHARS) {
+        rendered = `${rendered.substring(0, MAX_RENDERED_EVIDENCE_CHARS)}… (truncated)`;
+      }
+
+      lines.push(`- ${section}: ${rendered}`);
+    }
+
+    return lines.join("\n");
+  }
+}

package/Server/Utils/AI/SRE/Insights/Triage.ts

@@ -0,0 +1,162 @@
+import ObjectID from "../../../../../Types/ObjectID";
+import AIRunType from "../../../../../Types/AI/AIRunType";
+import AIRunStatus from "../../../../../Types/AI/AIRunStatus";
+import AIInsight from "../../../../../Models/DatabaseModels/AIInsight";
+import Project from "../../../../../Models/DatabaseModels/Project";
+import LlmProvider from "../../../../../Models/DatabaseModels/LlmProvider";
+import ProjectService from "../../../../Services/ProjectService";
+import LlmProviderService from "../../../../Services/LlmProviderService";
+import AIRunService from "../../../../Services/AIRunService";
+import AIInsightService from "../../../../Services/AIInsightService";
+import AIInvestigationQueue from "../InvestigationQueue";
+import QueryHelper from "../../../../Types/Database/QueryHelper";
+import logger from "../../../Logger";
+import CaptureSpan from "../../../Telemetry/CaptureSpan";
+
+/*
+ * Per-insight LLM triage enqueue: a budgeted, read-only Investigation AIRun
+ * (triggeredByAiInsightId set) that posts a cited root-cause/blast-
+ * radius/suggested-action summary back onto the insight. Quiet-skips when
+ * no LLM provider is configured or the budget has no headroom, and dedupes
+ * to one non-terminal triage run per insight.
+ *
+ * The durable queue does the heavy lifting (claim CAS, concurrency cap,
+ * daily token budget, retries, TTL expiry, stale sweeping) — this module
+ * only owns the insight-specific gates, mirroring the posture of
+ * AIInvestigationEngine.isEnabledForProject: enableAi not disabled,
+ * the subject's own strict opt-in (Project.enableAiInsights, default
+ * FALSE), and a configured LLM provider.
+ */
+
+export interface InsightTriageResult {
+  // Set when a triage run was enqueued for the insight.
+  triageAiRunId?: ObjectID | undefined;
+}
+
+export default class InsightTriage {
+  /*
+   * NEVER throws — this runs inside the scanner's per-insight routing and a
+   * failed triage enqueue must not fail the scan itself. Every failure is
+   * logged and swallowed; an empty result means "no triage enqueued".
+   */
+  @CaptureSpan()
+  public static async enqueueInsightTriage(data: {
+    insight: AIInsight;
+  }): Promise<InsightTriageResult> {
+    const { insight } = data;
+
+    try {
+      if (!insight.id || !insight.projectId) {
+        return {};
+      }
+
+      const projectId: ObjectID = insight.projectId;
+
+      const project: Project | null = await ProjectService.findOneById({
+        id: projectId,
+        select: {
+          enableAi: true,
+          enableAiInsights: true,
+        },
+        props: { isRoot: true },
+      });
+
+      if (!project) {
+        logger.debug(
+          `AI insights: not enqueueing triage for insight ${insight.id.toString()} — project not found.`,
+        );
+        return {};
+      }
+
+      if (project.enableAi === false) {
+        logger.debug(
+          `AI insights: not enqueueing triage for insight ${insight.id.toString()} — AI is disabled for the project.`,
+        );
+        return {};
+      }
+
+      /*
+       * Strict opt-in — the column defaults to false. A triage run only
+       * exists because insights exist, so it shares the insights flag; the
+       * fix-tasks flag is a separate, stricter opt-in.
+       */
+      if (project.enableAiInsights !== true) {
+        logger.debug(
+          `AI insights: not enqueueing triage for insight ${insight.id.toString()} — project has not opted in to AI insights.`,
+        );
+        return {};
+      }
+
+      const llmProvider: LlmProvider | null =
+        await LlmProviderService.getLLMProviderForProject(projectId);
+
+      if (!llmProvider) {
+        logger.debug(
+          `AI insights: not enqueueing triage for insight ${insight.id.toString()} — no LLM provider configured.`,
+        );
+        return {};
+      }
+
+      /*
+       * Dedupe: at most one non-terminal triage run per insight — the
+       * scanner refreshes recurring insights every tick, and a refresh must
+       * not fan out into duplicate triage runs.
+       */
+      const nonTerminalTriageRunCount: number = (
+        await AIRunService.countBy({
+          query: {
+            runType: AIRunType.Investigation,
+            triggeredByAiInsightId: insight.id,
+            status: QueryHelper.notIn([
+              AIRunStatus.Completed,
+              AIRunStatus.Error,
+              AIRunStatus.Cancelled,
+              AIRunStatus.Stale,
+            ]),
+          },
+          props: { isRoot: true },
+        })
+      ).toNumber();
+
+      if (nonTerminalTriageRunCount > 0) {
+        logger.debug(
+          `AI insights: not enqueueing triage for insight ${insight.id.toString()} — a non-terminal triage run already exists.`,
+        );
+        return {};
+      }
+
+      /*
+       * Record the durable intent. The queue's own budget quiet-skip
+       * applies here too — a null result means no run was created (budget
+       * exhausted or the create failed) and the insight simply gets no
+       * triage this tick.
+       */
+      const triageAiRunId: ObjectID | null = await AIInvestigationQueue.enqueue(
+        {
+          projectId,
+          subjectAIInsightId: insight.id,
+        },
+      );
+
+      if (!triageAiRunId) {
+        return {};
+      }
+
+      // Link the insight to its triage run for the dashboard's live panel.
+      await AIInsightService.updateOneById({
+        id: insight.id,
+        data: {
+          triageAiRunId,
+        },
+        props: { isRoot: true },
+      });
+
+      return { triageAiRunId };
+    } catch (error) {
+      logger.error(
+        `AI insights: failed to enqueue triage for insight ${insight.id?.toString()}: ${error}`,
+      );
+      return {};
+    }
+  }
+}