@oneuptime/common 12.0.4 → 12.0.6

package/Tests/Server/Utils/AI/InvestigationSettlement.test.ts

@@ -6,6 +6,7 @@ import AIInvestigationEngine, {
 } from "../../../../Server/Utils/AI/SRE/AIInvestigationEngine";
 import RemediationHandoff from "../../../../Server/Utils/AI/SRE/RemediationHandoff";
 import AIConfidenceSignal from "../../../../Server/Utils/AI/SRE/ConfidenceSignal";
+import InvestigationTldr from "../../../../Server/Utils/AI/SRE/InvestigationTldr";
 import ObservabilityAssistant, {
   ObservabilityAssistantResult,
 } from "../../../../Server/Utils/AI/Chat/ObservabilityAssistant";
@@ -13,8 +14,10 @@ import AIRunService from "../../../../Server/Services/AIRunService";
 import AIRunEventService from "../../../../Server/Services/AIRunEventService";
 import AIRun from "../../../../Models/DatabaseModels/AIRun";
 import AIRunEvent from "../../../../Models/DatabaseModels/AIRunEvent";
+import AIRunEventType from "../../../../Types/AI/AIRunEventType";
 import AIRunType from "../../../../Types/AI/AIRunType";
 import AIRunStatus from "../../../../Types/AI/AIRunStatus";
+import AIRunCodeFixRecommendation from "../../../../Types/AI/AIRunCodeFixRecommendation";
 import ObjectID from "../../../../Types/ObjectID";
 import PositiveNumber from "../../../../Types/PositiveNumber";
 import { describe, expect, test, afterEach, beforeEach } from "@jest/globals";
@@ -74,7 +77,11 @@ describe("AIInvestigationQueue.failOrRequeue — the settlement outcome", () =>
     expect(update).toHaveBeenCalledTimes(1);
     expect(update).toHaveBeenCalledWith(
       expect.objectContaining({
-        set: expect.objectContaining({ status: AIRunStatus.Queued }),
+        expectedAttemptCount: 1,
+        set: expect.objectContaining({
+          status: AIRunStatus.Queued,
+          codeFixRecommendation: AIRunCodeFixRecommendation.NotRecommended,
+        }),
       }),
     );
   });
@@ -113,7 +120,11 @@ describe("AIInvestigationQueue.failOrRequeue — the settlement outcome", () =>
     expect(outcome).toBe("finalized");
     expect(update).toHaveBeenCalledWith(
       expect.objectContaining({
-        set: expect.objectContaining({ status: AIRunStatus.Error }),
+        expectedAttemptCount: 1,
+        set: expect.objectContaining({
+          status: AIRunStatus.Error,
+          codeFixRecommendation: AIRunCodeFixRecommendation.NotRecommended,
+        }),
       }),
     );
   });
@@ -158,7 +169,7 @@ describe("AIInvestigationQueue.requeueOrMarkStale — the terminal-stale hand-of
     const incidentId: ObjectID = ObjectID.generate();
     jest.spyOn(AIRunService, "attemptStatusTransition").mockResolvedValue(1);
 
-    const outcome: "requeued" | "stale" =
+    const outcome: "requeued" | "stale" | "noop" =
       await AIInvestigationQueue.requeueOrMarkStale({
         id: ObjectID.generate(),
         attemptCount: MAX_INVESTIGATION_ATTEMPTS,
@@ -168,6 +179,15 @@ describe("AIInvestigationQueue.requeueOrMarkStale — the terminal-stale hand-of
       });
 
     expect(outcome).toBe("stale");
+    expect(AIRunService.attemptStatusTransition).toHaveBeenCalledWith(
+      expect.objectContaining({
+        expectedAttemptCount: MAX_INVESTIGATION_ATTEMPTS,
+        set: expect.objectContaining({
+          status: AIRunStatus.Stale,
+          codeFixRecommendation: AIRunCodeFixRecommendation.NotRecommended,
+        }),
+      }),
+    );
     expect(handoff).toHaveBeenCalledTimes(1);
     expect(handoff).toHaveBeenCalledWith(
       expect.objectContaining({ projectId, incidentId }),
@@ -175,18 +195,34 @@ describe("AIInvestigationQueue.requeueOrMarkStale — the terminal-stale hand-of
   });
 
   test("a requeued stale run is NOT settled — the retry owns it", async () => {
-    jest.spyOn(AIRunService, "attemptStatusTransition").mockResolvedValue(1);
+    const transition: jest.SpyInstance = jest
+      .spyOn(AIRunService, "attemptStatusTransition")
+      .mockResolvedValue(1);
+    const staleHeartbeat: Date = new Date("2026-08-07T12:00:00.000Z");
+    const runId: ObjectID = ObjectID.generate();
 
-    const outcome: "requeued" | "stale" =
+    const outcome: "requeued" | "stale" | "noop" =
       await AIInvestigationQueue.requeueOrMarkStale({
-        id: ObjectID.generate(),
+        id: runId,
         attemptCount: 1,
+        lastHeartbeatAt: staleHeartbeat,
         runType: AIRunType.Investigation,
         projectId: ObjectID.generate(),
         triggeredByIncidentId: ObjectID.generate(),
       });
 
     expect(outcome).toBe("requeued");
+    expect(transition).toHaveBeenCalledWith(
+      expect.objectContaining({
+        aiRunId: runId,
+        expectedAttemptCount: 1,
+        expectedLastHeartbeatAt: staleHeartbeat,
+        set: expect.objectContaining({
+          status: AIRunStatus.Queued,
+          codeFixRecommendation: AIRunCodeFixRecommendation.NotRecommended,
+        }),
+      }),
+    );
     expect(handoff).not.toHaveBeenCalled();
   });
 
@@ -208,14 +244,16 @@ describe("AIInvestigationQueue.requeueOrMarkStale — the terminal-stale hand-of
   test("a lost Stale transition does not hand off — the winning actor settles", async () => {
     jest.spyOn(AIRunService, "attemptStatusTransition").mockResolvedValue(0);
 
-    await AIInvestigationQueue.requeueOrMarkStale({
-      id: ObjectID.generate(),
-      attemptCount: MAX_INVESTIGATION_ATTEMPTS,
-      runType: AIRunType.Investigation,
-      projectId: ObjectID.generate(),
-      triggeredByIncidentId: ObjectID.generate(),
-    });
+    const outcome: "requeued" | "stale" | "noop" =
+      await AIInvestigationQueue.requeueOrMarkStale({
+        id: ObjectID.generate(),
+        attemptCount: MAX_INVESTIGATION_ATTEMPTS,
+        runType: AIRunType.Investigation,
+        projectId: ObjectID.generate(),
+        triggeredByIncidentId: ObjectID.generate(),
+      });
 
+    expect(outcome).toBe("noop");
     expect(handoff).not.toHaveBeenCalled();
   });
 });
@@ -268,7 +306,10 @@ describe("AIInvestigationQueue.processQueuedRuns — TTL expiry settles too", ()
 
     expect(update).toHaveBeenCalledWith(
       expect.objectContaining({
-        set: expect.objectContaining({ status: AIRunStatus.Cancelled }),
+        set: expect.objectContaining({
+          status: AIRunStatus.Cancelled,
+          codeFixRecommendation: AIRunCodeFixRecommendation.NotRecommended,
+        }),
       }),
     );
     expect(handoff).not.toHaveBeenCalled();
@@ -296,6 +337,7 @@ describe("AIInvestigationEngine.executeRun — the onSettled contract", () => {
   // Records call order so "after postAnalysis" is provable, not assumed.
   let callOrder: Array<string>;
   let postAnalysis: jest.Mock;
+  let onCodeFixRecommended: jest.Mock;
   let onSettled: jest.Mock;
 
   function makeResult(
@@ -311,22 +353,37 @@ describe("AIInvestigationEngine.executeRun — the onSettled contract", () => {
     };
   }
 
-  function makeRequest(): InvestigationRequest {
+  function makeRequest(
+    overrides: Partial<InvestigationRequest> = {},
+  ): InvestigationRequest {
     return {
       feature: "Test Investigation",
       contextSummary: "# Subject",
+      persistCodeFixRecommendation: true,
       postAnalysis:
         postAnalysis as unknown as InvestigationRequest["postAnalysis"],
+      onCodeFixRecommended:
+        onCodeFixRecommended as unknown as InvestigationRequest["onCodeFixRecommended"],
       onSettled: onSettled as unknown as InvestigationRequest["onSettled"],
+      ...overrides,
     };
   }
 
-  function executeRun(): Promise<void> {
+  function executeRun(
+    request: InvestigationRequest = makeRequest(),
+  ): Promise<void> {
     return AIInvestigationEngine.executeRun({
       aiRunId,
       projectId,
       attemptCount: 1,
-      request: makeRequest(),
+      request,
+    });
+  }
+
+  function emittedEventTypes(): Array<AIRunEventType> {
+    const create: jest.Mock = AIRunEventService.create as unknown as jest.Mock;
+    return create.mock.calls.map((call: Array<unknown>): AIRunEventType => {
+      return (call[0] as { data: AIRunEvent }).data.eventType!;
     });
   }
 
@@ -335,6 +392,9 @@ describe("AIInvestigationEngine.executeRun — the onSettled contract", () => {
     postAnalysis = jest.fn(async (): Promise<void> => {
       callOrder.push("postAnalysis");
     });
+    onCodeFixRecommended = jest.fn(async (): Promise<void> => {
+      callOrder.push("autoEnqueue");
+    });
     onSettled = jest.fn(async (): Promise<void> => {
       callOrder.push("onSettled");
     });
@@ -348,7 +408,14 @@ describe("AIInvestigationEngine.executeRun — the onSettled contract", () => {
       .mockResolvedValue({} as unknown as AIRunEvent);
     jest
       .spyOn(AIConfidenceSignal, "computeConfidenceSignal")
-      .mockResolvedValue({ confident: true, source: "classification" });
+      .mockResolvedValue({
+        confident: true,
+        codeFixRecommended: true,
+        source: "classification",
+      });
+    jest
+      .spyOn(AIRunService, "finalizeInvestigationCodeFixRecommendation")
+      .mockResolvedValue(1);
   });
 
   afterEach(() => {
@@ -356,17 +423,211 @@ describe("AIInvestigationEngine.executeRun — the onSettled contract", () => {
     handoff.mockClear();
   });
 
-  test("a successful run settles AFTER the analysis was posted", async () => {
+  test("a successful run posts, atomically persists the snapshot, then auto-enqueues and settles", async () => {
+    jest
+      .spyOn(ObservabilityAssistant, "answerQuestion")
+      .mockResolvedValue(makeResult());
+    const complete: jest.SpyInstance = jest
+      .spyOn(AIRunService, "attemptStatusTransition")
+      .mockResolvedValue(1);
+    postAnalysis.mockImplementation(async (): Promise<void> => {
+      expect(emittedEventTypes()).not.toContain(AIRunEventType.RunCompleted);
+      callOrder.push("postAnalysis");
+    });
+    (
+      AIRunService.finalizeInvestigationCodeFixRecommendation as unknown as jest.Mock
+    ).mockImplementation(async (): Promise<number> => {
+      callOrder.push("persistRecommendation");
+      return 1;
+    });
+    (AIRunEventService.create as unknown as jest.Mock).mockImplementation(
+      async (data: { data: AIRunEvent }): Promise<AIRunEvent> => {
+        if (data.data.eventType === AIRunEventType.RunCompleted) {
+          callOrder.push("runCompleted");
+        }
+        return {} as AIRunEvent;
+      },
+    );
+
+    await executeRun();
+
+    expect(postAnalysis).toHaveBeenCalledTimes(1);
+    expect(onSettled).toHaveBeenCalledTimes(1);
+    expect(callOrder).toEqual([
+      "postAnalysis",
+      "persistRecommendation",
+      "autoEnqueue",
+      "runCompleted",
+      "onSettled",
+    ]);
+    expect(emittedEventTypes()).toContain(AIRunEventType.RunCompleted);
+    expect(complete).toHaveBeenCalledWith(
+      expect.objectContaining({
+        fromStatus: AIRunStatus.Running,
+        expectedAttemptCount: 1,
+        set: expect.objectContaining({
+          status: AIRunStatus.Completed,
+          codeFixRecommendation: AIRunCodeFixRecommendation.Pending,
+        }),
+      }),
+    );
+
+    const postedAnalysisMarkdown: string = postAnalysis.mock.calls[0]![0]
+      .analysisMarkdown as string;
+    expect(
+      AIRunService.finalizeInvestigationCodeFixRecommendation,
+    ).toHaveBeenCalledWith({
+      aiRunId,
+      recommendation: AIRunCodeFixRecommendation.Recommended,
+      taskContext: {
+        sourceInvestigationRunId: aiRunId.toString(),
+        sourceInvestigationAnalysisMarkdown: postedAnalysisMarkdown,
+      },
+    });
+    expect(onCodeFixRecommended).toHaveBeenCalledWith({
+      analysisMarkdown: postedAnalysisMarkdown,
+    });
+    expect(postedAnalysisMarkdown).toContain(
+      "## 🧠 AI — Automated Root Cause Analysis",
+    );
+  });
+
+  test("a confident non-code analysis settles NotRecommended", async () => {
     jest
       .spyOn(ObservabilityAssistant, "answerQuestion")
       .mockResolvedValue(makeResult());
     jest.spyOn(AIRunService, "attemptStatusTransition").mockResolvedValue(1);
+    jest
+      .spyOn(AIConfidenceSignal, "computeConfidenceSignal")
+      .mockResolvedValue({
+        confident: true,
+        codeFixRecommended: false,
+        source: "classification",
+      });
 
     await executeRun();
 
     expect(postAnalysis).toHaveBeenCalledTimes(1);
+    expect(
+      AIRunService.finalizeInvestigationCodeFixRecommendation,
+    ).toHaveBeenCalledWith({
+      aiRunId,
+      recommendation: AIRunCodeFixRecommendation.NotRecommended,
+    });
+    expect(onCodeFixRecommended).not.toHaveBeenCalled();
+  });
+
+  test("an inconsistent positive field fails closed through the shared code-fix helper", async () => {
+    jest
+      .spyOn(ObservabilityAssistant, "answerQuestion")
+      .mockResolvedValue(makeResult());
+    jest.spyOn(AIRunService, "attemptStatusTransition").mockResolvedValue(1);
+    jest
+      .spyOn(AIConfidenceSignal, "computeConfidenceSignal")
+      .mockResolvedValue({
+        confident: false,
+        codeFixRecommended: true,
+        source: "classification",
+      });
+
+    await executeRun();
+
+    expect(
+      AIRunService.finalizeInvestigationCodeFixRecommendation,
+    ).toHaveBeenCalledWith({
+      aiRunId,
+      recommendation: AIRunCodeFixRecommendation.NotRecommended,
+    });
+    expect(onCodeFixRecommended).not.toHaveBeenCalled();
+  });
+
+  test("a transient recommendation write is retried up to a successful third attempt", async () => {
+    jest
+      .spyOn(ObservabilityAssistant, "answerQuestion")
+      .mockResolvedValue(makeResult());
+    jest.spyOn(AIRunService, "attemptStatusTransition").mockResolvedValue(1);
+    (
+      AIRunService.finalizeInvestigationCodeFixRecommendation as unknown as jest.Mock
+    )
+      .mockRejectedValueOnce(new Error("database unavailable"))
+      .mockRejectedValueOnce(new Error("connection reset"))
+      .mockResolvedValueOnce(1);
+
+    await executeRun();
+
+    expect(
+      AIRunService.finalizeInvestigationCodeFixRecommendation,
+    ).toHaveBeenCalledTimes(3);
+    expect(onCodeFixRecommended).toHaveBeenCalledTimes(1);
     expect(onSettled).toHaveBeenCalledTimes(1);
-    expect(callOrder).toEqual(["postAnalysis", "onSettled"]);
+  });
+
+  test("a zero-row recommendation write is safe and is not retried", async () => {
+    jest
+      .spyOn(ObservabilityAssistant, "answerQuestion")
+      .mockResolvedValue(makeResult());
+    jest.spyOn(AIRunService, "attemptStatusTransition").mockResolvedValue(1);
+    (
+      AIRunService.finalizeInvestigationCodeFixRecommendation as unknown as jest.Mock
+    ).mockResolvedValue(0);
+
+    await executeRun();
+
+    expect(
+      AIRunService.finalizeInvestigationCodeFixRecommendation,
+    ).toHaveBeenCalledTimes(1);
+    expect(onCodeFixRecommended).not.toHaveBeenCalled();
+    expect(onSettled).toHaveBeenCalledTimes(1);
+  });
+
+  test("a non-incident engine consumer neither enters Pending nor persists a recommendation", async () => {
+    jest
+      .spyOn(ObservabilityAssistant, "answerQuestion")
+      .mockResolvedValue(makeResult());
+    const complete: jest.SpyInstance = jest
+      .spyOn(AIRunService, "attemptStatusTransition")
+      .mockResolvedValue(1);
+
+    await executeRun(makeRequest({ persistCodeFixRecommendation: undefined }));
+
+    const completedSet: Record<string, unknown> = complete.mock.calls[0]![0]
+      .set as Record<string, unknown>;
+    expect(completedSet["codeFixRecommendation"]).toBeUndefined();
+    expect(
+      AIRunService.finalizeInvestigationCodeFixRecommendation,
+    ).not.toHaveBeenCalled();
+    expect(postAnalysis).toHaveBeenCalledTimes(1);
+  });
+
+  test("carries the subject lane through the assistant and confidence calls", async () => {
+    const incidentId: ObjectID = ObjectID.generate();
+    const answer: jest.SpyInstance = jest
+      .spyOn(ObservabilityAssistant, "answerQuestion")
+      .mockResolvedValue(makeResult());
+    const confidence: jest.SpyInstance = jest.spyOn(
+      AIConfidenceSignal,
+      "computeConfidenceSignal",
+    );
+    jest.spyOn(AIRunService, "attemptStatusTransition").mockResolvedValue(1);
+
+    await executeRun(makeRequest({ incidentId }));
+
+    expect(answer).toHaveBeenCalledWith(
+      expect.objectContaining({
+        projectId,
+        aiRunId,
+        incidentId,
+        alertId: undefined,
+      }),
+    );
+    expect(confidence).toHaveBeenCalledWith(
+      expect.objectContaining({
+        projectId,
+        aiRunId,
+        incidentId,
+        alertId: undefined,
+      }),
+    );
   });
 
   test("an empty analysis still settles — but posts nothing", async () => {
@@ -384,6 +645,13 @@ describe("AIInvestigationEngine.executeRun — the onSettled contract", () => {
     expect(postAnalysis).not.toHaveBeenCalled();
     expect(confidence).not.toHaveBeenCalled();
     expect(onSettled).toHaveBeenCalledTimes(1);
+    expect(emittedEventTypes()).toContain(AIRunEventType.RunCompleted);
+    expect(
+      AIRunService.finalizeInvestigationCodeFixRecommendation,
+    ).toHaveBeenCalledWith({
+      aiRunId,
+      recommendation: AIRunCodeFixRecommendation.NotRecommended,
+    });
   });
 
   test("a lost Completed CAS neither posts nor settles — the winning attempt owns both", async () => {
@@ -396,6 +664,9 @@ describe("AIInvestigationEngine.executeRun — the onSettled contract", () => {
 
     expect(postAnalysis).not.toHaveBeenCalled();
     expect(onSettled).not.toHaveBeenCalled();
+    expect(
+      AIRunService.finalizeInvestigationCodeFixRecommendation,
+    ).not.toHaveBeenCalled();
   });
 
   test("an agent failure that failOrRequeue FINALIZED settles", async () => {
@@ -410,6 +681,7 @@ describe("AIInvestigationEngine.executeRun — the onSettled contract", () => {
 
     expect(postAnalysis).not.toHaveBeenCalled();
     expect(onSettled).toHaveBeenCalledTimes(1);
+    expect(emittedEventTypes()).toContain(AIRunEventType.RunFailed);
   });
 
   test("an agent failure that was REQUEUED does not settle — the retry will", async () => {
@@ -423,6 +695,19 @@ describe("AIInvestigationEngine.executeRun — the onSettled contract", () => {
     await executeRun();
 
     expect(onSettled).not.toHaveBeenCalled();
+    expect(emittedEventTypes()).not.toContain(AIRunEventType.RunFailed);
+  });
+
+  test("a stale failing attempt that lost ownership emits no terminal event", async () => {
+    jest
+      .spyOn(ObservabilityAssistant, "answerQuestion")
+      .mockRejectedValue(new Error("stale attempt finished late"));
+    jest.spyOn(AIInvestigationQueue, "failOrRequeue").mockResolvedValue("noop");
+
+    await executeRun();
+
+    expect(onSettled).not.toHaveBeenCalled();
+    expect(emittedEventTypes()).not.toContain(AIRunEventType.RunFailed);
   });
 
   test("a postAnalysis failure after the WON Completed transition still settles", async () => {
@@ -439,6 +724,15 @@ describe("AIInvestigationEngine.executeRun — the onSettled contract", () => {
     await executeRun();
 
     expect(onSettled).toHaveBeenCalledTimes(1);
+    expect(emittedEventTypes()).not.toContain(AIRunEventType.RunCompleted);
+    expect(emittedEventTypes()).toContain(AIRunEventType.RunFailed);
+    expect(
+      AIRunService.finalizeInvestigationCodeFixRecommendation,
+    ).toHaveBeenCalledWith({
+      aiRunId,
+      recommendation: AIRunCodeFixRecommendation.NotRecommended,
+    });
+    expect(onCodeFixRecommended).not.toHaveBeenCalled();
   });
 
   test("an onSettled failure never rejects executeRun", async () => {
@@ -461,3 +755,294 @@ describe("AIInvestigationEngine.executeRun — the onSettled contract", () => {
     expect(failOrRequeue).not.toHaveBeenCalled();
   });
 });
+
+/*
+ * The investigation TL;DR (see InvestigationTldr) is display-only: opted-in
+ * subject runs get one, it is stored before the report is posted so the panel
+ * never renders a report without its summary, and NO failure of it — a
+ * degraded null, a failed write — may delay or fail the run.
+ */
+describe("AIInvestigationEngine.executeRun — the investigation TL;DR", () => {
+  const aiRunId: ObjectID = ObjectID.generate();
+  const projectId: ObjectID = ObjectID.generate();
+  const TLDR: string = "Checkout is failing on an exhausted connection pool.";
+
+  let callOrder: Array<string>;
+  let postAnalysis: jest.Mock;
+
+  function makeRequest(
+    overrides: Partial<InvestigationRequest> = {},
+  ): InvestigationRequest {
+    return {
+      feature: "Test Investigation",
+      contextSummary: "# Subject",
+      persistCodeFixRecommendation: true,
+      persistAnalysisTldr: true,
+      postAnalysis:
+        postAnalysis as unknown as InvestigationRequest["postAnalysis"],
+      ...overrides,
+    };
+  }
+
+  function executeRun(
+    request: InvestigationRequest = makeRequest(),
+  ): Promise<void> {
+    return AIInvestigationEngine.executeRun({
+      aiRunId,
+      projectId,
+      attemptCount: 1,
+      request,
+    });
+  }
+
+  beforeEach(() => {
+    callOrder = [];
+    postAnalysis = jest.fn(async (): Promise<void> => {
+      callOrder.push("postAnalysis");
+    });
+
+    jest
+      .spyOn(AIRunEventService, "countBy")
+      .mockResolvedValue(new PositiveNumber(0));
+    jest
+      .spyOn(AIRunEventService, "create")
+      .mockResolvedValue({} as unknown as AIRunEvent);
+    jest.spyOn(AIRunService, "attemptStatusTransition").mockResolvedValue(1);
+    jest
+      .spyOn(AIRunService, "finalizeInvestigationCodeFixRecommendation")
+      .mockResolvedValue(1);
+    jest
+      .spyOn(AIConfidenceSignal, "computeConfidenceSignal")
+      .mockResolvedValue({
+        confident: true,
+        codeFixRecommended: false,
+        source: "classification",
+      });
+    jest.spyOn(ObservabilityAssistant, "answerQuestion").mockResolvedValue({
+      contentInMarkdown: "**Summary** — the connection pool ran dry.",
+      citations: [],
+      totalTokens: 100,
+      llmCallCount: 2,
+      toolCallCount: 3,
+    } as ObservabilityAssistantResult);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    handoff.mockClear();
+  });
+
+  test("an opted-in run stores the summary BEFORE the report is posted", async () => {
+    jest.spyOn(InvestigationTldr, "generateTldr").mockResolvedValue(TLDR);
+    const store: jest.SpyInstance = jest
+      .spyOn(AIRunService, "setInvestigationAnalysisTldr")
+      .mockImplementation(async (): Promise<number> => {
+        callOrder.push("storeTldr");
+        return 1;
+      });
+
+    await executeRun();
+
+    expect(store).toHaveBeenCalledWith({ aiRunId, analysisTldr: TLDR });
+    expect(callOrder).toEqual(["storeTldr", "postAnalysis"]);
+  });
+
+  test("summarizes the model's own analysis, not the branded wrapper", async () => {
+    const generate: jest.SpyInstance = jest
+      .spyOn(InvestigationTldr, "generateTldr")
+      .mockResolvedValue(TLDR);
+    jest
+      .spyOn(AIRunService, "setInvestigationAnalysisTldr")
+      .mockResolvedValue(1);
+
+    await executeRun(makeRequest({ incidentId: ObjectID.generate() }));
+
+    const summarized: string = (
+      generate.mock.calls[0]![0] as { analysisMarkdown: string }
+    ).analysisMarkdown;
+
+    expect(summarized).toBe("**Summary** — the connection pool ran dry.");
+    expect(summarized).not.toContain("Automated Root Cause Analysis");
+    expect(summarized).not.toContain("Evidence checked");
+  });
+
+  test("runs concurrently with the confidence classification, not after it", async () => {
+    /*
+     * The classification only resolves once the TL;DR call has started. If
+     * the engine awaited them in sequence this test would never settle, so
+     * passing IS the proof that both are in flight together.
+     */
+    let releaseClassification: () => void = (): void => {};
+    const classificationStarted: Promise<void> = new Promise<void>(
+      (resolve: () => void) => {
+        releaseClassification = resolve;
+      },
+    );
+
+    jest
+      .spyOn(InvestigationTldr, "generateTldr")
+      .mockImplementation(async (): Promise<string | null> => {
+        releaseClassification();
+        return TLDR;
+      });
+    (
+      AIConfidenceSignal.computeConfidenceSignal as unknown as jest.Mock
+    ).mockImplementation(async () => {
+      await classificationStarted;
+      return {
+        confident: true,
+        codeFixRecommended: false,
+        source: "classification",
+      };
+    });
+    jest
+      .spyOn(AIRunService, "setInvestigationAnalysisTldr")
+      .mockResolvedValue(1);
+
+    await executeRun();
+
+    expect(postAnalysis).toHaveBeenCalledTimes(1);
+    expect(InvestigationTldr.generateTldr).toHaveBeenCalledTimes(1);
+  });
+
+  test("a degraded (null) summary writes nothing and still publishes the report", async () => {
+    jest.spyOn(InvestigationTldr, "generateTldr").mockResolvedValue(null);
+    const store: jest.SpyInstance = jest.spyOn(
+      AIRunService,
+      "setInvestigationAnalysisTldr",
+    );
+
+    await executeRun();
+
+    expect(store).not.toHaveBeenCalled();
+    expect(postAnalysis).toHaveBeenCalledTimes(1);
+    expect(emittedTypes()).toContain(AIRunEventType.RunCompleted);
+  });
+
+  test("a failed TL;DR write never fails the run", async () => {
+    jest.spyOn(InvestigationTldr, "generateTldr").mockResolvedValue(TLDR);
+    jest
+      .spyOn(AIRunService, "setInvestigationAnalysisTldr")
+      .mockRejectedValue(new Error("database unavailable"));
+
+    await expect(executeRun()).resolves.toBeUndefined();
+
+    expect(postAnalysis).toHaveBeenCalledTimes(1);
+    expect(emittedTypes()).toContain(AIRunEventType.RunCompleted);
+    expect(emittedTypes()).not.toContain(AIRunEventType.RunFailed);
+  });
+
+  test("a run whose row is no longer Completed is logged, not retried or failed", async () => {
+    jest.spyOn(InvestigationTldr, "generateTldr").mockResolvedValue(TLDR);
+    const store: jest.SpyInstance = jest
+      .spyOn(AIRunService, "setInvestigationAnalysisTldr")
+      .mockResolvedValue(0);
+
+    await expect(executeRun()).resolves.toBeUndefined();
+
+    expect(store).toHaveBeenCalledTimes(1);
+    expect(postAnalysis).toHaveBeenCalledTimes(1);
+  });
+
+  /*
+   * The blast radius here is wildly asymmetric. generateTldr sits in a
+   * Promise.all inside the main try, AFTER the Completed transition is won:
+   * a rejection would fall to the catch, finalize the run NotRecommended and
+   * emit RunFailed, so the RCA would never be posted at all — a cosmetic line
+   * of text destroying the entire investigation output.
+   */
+  test("a throwing TL;DR call still publishes the report and settles the run", async () => {
+    jest
+      .spyOn(InvestigationTldr, "generateTldr")
+      .mockRejectedValue(new Error("summarizer exploded"));
+    const store: jest.SpyInstance = jest.spyOn(
+      AIRunService,
+      "setInvestigationAnalysisTldr",
+    );
+    const onSettled: jest.Mock = jest.fn(async (): Promise<void> => {});
+
+    await expect(
+      executeRun(
+        makeRequest({
+          onSettled: onSettled as unknown as InvestigationRequest["onSettled"],
+        }),
+      ),
+    ).resolves.toBeUndefined();
+
+    expect(postAnalysis).toHaveBeenCalledTimes(1);
+    expect(store).not.toHaveBeenCalled();
+    expect(onSettled).toHaveBeenCalledTimes(1);
+    expect(emittedTypes()).toContain(AIRunEventType.RunCompleted);
+    expect(emittedTypes()).not.toContain(AIRunEventType.RunFailed);
+  });
+
+  /*
+   * A stale attempt — one the sweeper falsely requeued — loses the Completed
+   * CAS and must not spend a TL;DR call or label a run whose report belongs
+   * to the winning attempt.
+   */
+  test("an attempt that lost the Completed race neither spends nor writes a TL;DR", async () => {
+    (
+      AIRunService.attemptStatusTransition as unknown as jest.Mock
+    ).mockResolvedValue(0);
+    const generate: jest.SpyInstance = jest.spyOn(
+      InvestigationTldr,
+      "generateTldr",
+    );
+    const store: jest.SpyInstance = jest.spyOn(
+      AIRunService,
+      "setInvestigationAnalysisTldr",
+    );
+
+    await expect(executeRun()).resolves.toBeUndefined();
+
+    expect(generate).not.toHaveBeenCalled();
+    expect(store).not.toHaveBeenCalled();
+    expect(postAnalysis).not.toHaveBeenCalled();
+  });
+
+  test("an engine user without the opt-in never spends the call", async () => {
+    const generate: jest.SpyInstance = jest.spyOn(
+      InvestigationTldr,
+      "generateTldr",
+    );
+    const store: jest.SpyInstance = jest.spyOn(
+      AIRunService,
+      "setInvestigationAnalysisTldr",
+    );
+
+    await executeRun(makeRequest({ persistAnalysisTldr: undefined }));
+
+    expect(generate).not.toHaveBeenCalled();
+    expect(store).not.toHaveBeenCalled();
+    expect(postAnalysis).toHaveBeenCalledTimes(1);
+  });
+
+  test("a run that produced no analysis never spends the call", async () => {
+    (
+      ObservabilityAssistant.answerQuestion as unknown as jest.Mock
+    ).mockResolvedValue({
+      contentInMarkdown: "   ",
+      citations: [],
+      totalTokens: 0,
+      llmCallCount: 1,
+      toolCallCount: 0,
+    });
+    const generate: jest.SpyInstance = jest.spyOn(
+      InvestigationTldr,
+      "generateTldr",
+    );
+
+    await executeRun();
+
+    expect(generate).not.toHaveBeenCalled();
+    expect(postAnalysis).not.toHaveBeenCalled();
+  });
+
+  function emittedTypes(): Array<AIRunEventType> {
+    const create: jest.Mock = AIRunEventService.create as unknown as jest.Mock;
+    return create.mock.calls.map((call: Array<unknown>): AIRunEventType => {
+      return (call[0] as { data: AIRunEvent }).data.eventType!;
+    });
+  }
+});