@vellumai/assistant 0.7.0 → 0.7.2

package/src/__tests__/heartbeat-service.test.ts

@@ -1,14 +1,48 @@
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  jest,
+  mock,
+  test,
+} from "bun:test";
 
 const testWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR!;
 
+// ── Heartbeat run store mock ───────────────────────────────────────
+const mockInsertPendingHeartbeatRun = mock(() => "mock-run-id");
+const mockStartHeartbeatRun = mock(() => true);
+const mockCompleteHeartbeatRun = mock(() => true);
+const mockSkipHeartbeatRun = mock(() => true);
+const mockSupersedePendingRun = mock(() => true);
+const mockMarkStaleRunsAsMissed = mock(() => 0);
+const mockMarkStaleRunningAsError = mock(() => 0);
+mock.module("../heartbeat/heartbeat-run-store.js", () => ({
+  insertPendingHeartbeatRun: mockInsertPendingHeartbeatRun,
+  startHeartbeatRun: mockStartHeartbeatRun,
+  completeHeartbeatRun: mockCompleteHeartbeatRun,
+  skipHeartbeatRun: mockSkipHeartbeatRun,
+  supersedePendingRun: mockSupersedePendingRun,
+  markStaleRunsAsMissed: mockMarkStaleRunsAsMissed,
+  markStaleRunningAsError: mockMarkStaleRunningAsError,
+}));
+
+// ── Feed event mock ───────────────────────────────────────────────
+const mockEmitFeedEvent = mock(() => Promise.resolve());
+mock.module("../home/emit-feed-event.js", () => ({
+  emitFeedEvent: mockEmitFeedEvent,
+}));
+
 // Mock config loader
 let mockConfig = {
   heartbeat: {
     enabled: true,
     intervalMs: 60_000,
+    cronExpression: null as string | null,
+    timezone: null as string | null,
     activeHoursStart: undefined as number | undefined,
     activeHoursEnd: undefined as number | undefined,
   },
@@ -22,6 +56,32 @@ mock.module("../config/loader.js", () => ({
   invalidateConfigCache: () => {},
 }));
 
+// ── Recurrence engine mock ──────────────────────────────────────────
+//
+// HeartbeatService imports computeNextRunAt for cron scheduling.
+// Tests mutate `mockComputeNextRunAt` to control the next cron occurrence.
+let mockComputeNextRunAtResult: number | null = null;
+let mockComputeNextRunAtError: Error | null = null;
+let computeNextRunAtCallCount = 0;
+
+mock.module("../schedule/recurrence-engine.js", () => ({
+  computeNextRunAt: (_spec: {
+    syntax: string;
+    expression: string;
+    timezone?: string | null;
+  }) => {
+    computeNextRunAtCallCount++;
+    if (mockComputeNextRunAtError) {
+      throw mockComputeNextRunAtError;
+    }
+    if (mockComputeNextRunAtResult != null) {
+      return mockComputeNextRunAtResult;
+    }
+    // Default: 1 hour from now
+    return Date.now() + 3_600_000;
+  },
+}));
+
 // ── Guardian persona mock ─────────────────────────────────────────
 //
 // `heartbeat-service.isShallowProfile` reads the guardian persona via
@@ -90,16 +150,74 @@ mock.module("../memory/conversation-crud.js", () => ({
   },
 }));
 
-// Mock logger
+// Mock logger — capture warn calls for unreachable-credential assertions
+const loggerWarnCalls: Array<Record<string, unknown>> = [];
 mock.module("../util/logger.js", () => ({
   getLogger: () => ({
     info: () => {},
     debug: () => {},
-    warn: () => {},
+    warn: (...args: unknown[]) => {
+      if (args.length > 0 && typeof args[0] === "object" && args[0] !== null) {
+        loggerWarnCalls.push(args[0] as Record<string, unknown>);
+      }
+    },
     error: () => {},
   }),
 }));
 
+// ── Credential health mock ──────────────────────────────────────────
+//
+// HeartbeatService dynamically imports `checkAllCredentials` inside
+// `runCredentialHealthCheck`, so `mock.module` intercepts it. Tests
+// mutate `mockCredentialHealthReport` to drive different scenarios.
+import type {
+  CredentialHealthReport,
+  CredentialHealthResult,
+  CredentialHealthStatus,
+} from "../credential-health/credential-health-service.js";
+
+let mockCredentialHealthReport: CredentialHealthReport | null = null;
+let mockCheckAllCredentialsFail = false;
+
+mock.module("../credential-health/credential-health-service.js", () => ({
+  checkAllCredentials: async () => {
+    if (mockCheckAllCredentialsFail) {
+      throw new Error("CES unreachable");
+    }
+    return (
+      mockCredentialHealthReport ?? {
+        checkedAt: Date.now(),
+        results: [],
+        unhealthy: [],
+      }
+    );
+  },
+}));
+
+// ── Notification signal mock ────────────────────────────────────────
+//
+// `notifyUnhealthyCredentials` dynamically imports `emitNotificationSignal`.
+// Track calls so tests can assert which credentials were notified about.
+const emittedNotificationSignals: Array<{
+  sourceContextId: string;
+  dedupeKey: string;
+  contextPayload: Record<string, unknown>;
+}> = [];
+
+mock.module("../notifications/emit-signal.js", () => ({
+  emitNotificationSignal: async (opts: {
+    sourceContextId: string;
+    dedupeKey: string;
+    contextPayload: Record<string, unknown>;
+  }) => {
+    emittedNotificationSignals.push({
+      sourceContextId: opts.sourceContextId,
+      dedupeKey: opts.dedupeKey,
+      contextPayload: opts.contextPayload,
+    });
+  },
+}));
+
 // Mock conversation title service
 mock.module("../memory/conversation-title-service.js", () => ({
   GENERATING_TITLE: "Generating title...",
@@ -108,16 +226,18 @@ mock.module("../memory/conversation-title-service.js", () => ({
 
 // Mock processMessage — HeartbeatService now imports it directly.
 // Tests override _testProcessMessage to capture / customize calls.
-let _testProcessMessage: ((...args: unknown[]) => Promise<{ messageId: string }>) | undefined;
+let _testProcessMessage:
+  | ((...args: unknown[]) => Promise<{ messageId: string }>)
+  | undefined;
 
 mock.module("../daemon/process-message.js", () => ({
   processMessage: async (...args: unknown[]) => {
     if (_testProcessMessage) return _testProcessMessage(...args);
     return { messageId: `mock-msg-${Date.now()}` };
   },
+  processMessageInBackground: async () => ({ messageId: "mock-bg" }),
   resolveTurnChannel: () => "vellum",
   resolveTurnInterface: () => "vellum",
-  makePendingInteractionRegistrar: () => () => {},
   prepareConversationForMessage: async () => ({}),
 }));
 
@@ -199,6 +319,13 @@ describe("HeartbeatService", () => {
     createdConversations.length = 0;
     conversationIdCounter = 0;
     mockGuardianPersona = null;
+    mockCredentialHealthReport = null;
+    mockCheckAllCredentialsFail = false;
+    emittedNotificationSignals.length = 0;
+    loggerWarnCalls.length = 0;
+    mockComputeNextRunAtResult = null;
+    mockComputeNextRunAtError = null;
+    computeNextRunAtCallCount = 0;
 
     // Default processMessage mock: capture calls for assertions.
     setTestProcessMessage(async (...args: unknown[]) => {
@@ -210,10 +337,29 @@ describe("HeartbeatService", () => {
       return { messageId: "msg-1" };
     });
 
+    mockInsertPendingHeartbeatRun.mockClear();
+    mockInsertPendingHeartbeatRun.mockImplementation(() => "mock-run-id");
+    mockStartHeartbeatRun.mockClear();
+    mockStartHeartbeatRun.mockImplementation(() => true);
+    mockCompleteHeartbeatRun.mockClear();
+    mockCompleteHeartbeatRun.mockImplementation(() => true);
+    mockSkipHeartbeatRun.mockClear();
+    mockSkipHeartbeatRun.mockImplementation(() => true);
+    mockSupersedePendingRun.mockClear();
+    mockSupersedePendingRun.mockImplementation(() => true);
+    mockMarkStaleRunsAsMissed.mockClear();
+    mockMarkStaleRunsAsMissed.mockImplementation(() => 0);
+    mockMarkStaleRunningAsError.mockClear();
+    mockMarkStaleRunningAsError.mockImplementation(() => 0);
+    mockEmitFeedEvent.mockClear();
+    mockEmitFeedEvent.mockImplementation(() => Promise.resolve());
+
     mockConfig = {
       heartbeat: {
         enabled: true,
         intervalMs: 60_000,
+        cronExpression: null,
+        timezone: null,
         activeHoursStart: undefined,
         activeHoursEnd: undefined,
       },
@@ -221,9 +367,7 @@ describe("HeartbeatService", () => {
   });
 
   function createService(overrides?: {
-    processMessage?: (
-      ...args: unknown[]
-    ) => Promise<{ messageId: string }>;
+    processMessage?: (...args: unknown[]) => Promise<{ messageId: string }>;
     getCurrentHour?: () => number;
   }) {
     if (overrides?.processMessage) {
@@ -771,4 +915,859 @@ describe("HeartbeatService", () => {
       expect(prompt).toContain("google, slack");
     });
   });
+
+  describe("transient credential health suppression", () => {
+    function makeUnhealthyResult(
+      overrides: Partial<CredentialHealthResult> = {},
+    ): CredentialHealthResult {
+      return {
+        connectionId: overrides.connectionId ?? "conn-1",
+        provider: overrides.provider ?? "google",
+        accountInfo: overrides.accountInfo ?? "user@example.com",
+        status: overrides.status ?? ("missing_token" as CredentialHealthStatus),
+        details: overrides.details ?? "Token not found",
+        missingScopes: overrides.missingScopes ?? [],
+        canAutoRecover: overrides.canAutoRecover ?? false,
+      };
+    }
+
+    test("unreachable credentials do not trigger notifications", async () => {
+      mockCredentialHealthReport = {
+        checkedAt: Date.now(),
+        results: [
+          makeUnhealthyResult({
+            connectionId: "conn-google",
+            provider: "google",
+            status: "unreachable",
+            details: "CES backend unavailable",
+          }),
+        ],
+        unhealthy: [
+          makeUnhealthyResult({
+            connectionId: "conn-google",
+            provider: "google",
+            status: "unreachable",
+            details: "CES backend unavailable",
+          }),
+        ],
+      };
+
+      const service = createService();
+      await service.runOnce();
+
+      // No notification signals should have been emitted for unreachable
+      expect(emittedNotificationSignals).toHaveLength(0);
+    });
+
+    test("unreachable credentials do not block provider tools in heartbeat prompt", async () => {
+      mockCredentialHealthReport = {
+        checkedAt: Date.now(),
+        results: [
+          makeUnhealthyResult({
+            connectionId: "conn-google",
+            provider: "google",
+            status: "unreachable",
+            details: "CES backend unavailable",
+          }),
+        ],
+        unhealthy: [
+          makeUnhealthyResult({
+            connectionId: "conn-google",
+            provider: "google",
+            status: "unreachable",
+            details: "CES backend unavailable",
+          }),
+        ],
+      };
+
+      const service = createService();
+      await service.runOnce();
+
+      // The prompt should NOT contain <credential-status> since unreachable
+      // is not a hard failure and should not tell the LLM to skip providers
+      expect(processMessageCalls).toHaveLength(1);
+      expect(processMessageCalls[0].content).not.toContain(
+        "<credential-status>",
+      );
+    });
+
+    test("unreachable credentials log a warning", async () => {
+      mockCredentialHealthReport = {
+        checkedAt: Date.now(),
+        results: [
+          makeUnhealthyResult({
+            connectionId: "conn-google",
+            provider: "google",
+            status: "unreachable",
+            details: "CES backend unavailable",
+          }),
+        ],
+        unhealthy: [
+          makeUnhealthyResult({
+            connectionId: "conn-google",
+            provider: "google",
+            status: "unreachable",
+            details: "CES backend unavailable",
+          }),
+        ],
+      };
+
+      const service = createService();
+      await service.runOnce();
+
+      // Logger warn should have been called with unreachableCount
+      const unreachableWarns = loggerWarnCalls.filter(
+        (call) => "unreachableCount" in call,
+      );
+      expect(unreachableWarns).toHaveLength(1);
+      expect(unreachableWarns[0].unreachableCount).toBe(1);
+    });
+
+    test("missing_token still notifies and blocks provider tools", async () => {
+      mockCredentialHealthReport = {
+        checkedAt: Date.now(),
+        results: [
+          makeUnhealthyResult({
+            connectionId: "conn-google",
+            provider: "google",
+            status: "missing_token",
+            details: "Token not found in keychain",
+          }),
+        ],
+        unhealthy: [
+          makeUnhealthyResult({
+            connectionId: "conn-google",
+            provider: "google",
+            status: "missing_token",
+            details: "Token not found in keychain",
+          }),
+        ],
+      };
+
+      const service = createService();
+      await service.runOnce();
+
+      // Should have emitted a notification for missing_token
+      expect(emittedNotificationSignals).toHaveLength(1);
+      expect(emittedNotificationSignals[0].contextPayload.status).toBe(
+        "missing_token",
+      );
+      expect(emittedNotificationSignals[0].contextPayload.provider).toBe(
+        "google",
+      );
+
+      // Prompt should include <credential-status> blocking google
+      expect(processMessageCalls).toHaveLength(1);
+      expect(processMessageCalls[0].content).toContain("<credential-status>");
+      expect(processMessageCalls[0].content).toContain("google");
+    });
+
+    test("mixed report notifies only actionable failures, not unreachable", async () => {
+      mockCredentialHealthReport = {
+        checkedAt: Date.now(),
+        results: [
+          makeUnhealthyResult({
+            connectionId: "conn-google",
+            provider: "google",
+            status: "unreachable",
+            details: "CES backend unavailable",
+          }),
+          makeUnhealthyResult({
+            connectionId: "conn-slack",
+            provider: "slack",
+            status: "revoked",
+            details: "Token was revoked by user",
+          }),
+          makeUnhealthyResult({
+            connectionId: "conn-github",
+            provider: "github",
+            status: "unreachable",
+            details: "CES backend unavailable",
+          }),
+        ],
+        unhealthy: [
+          makeUnhealthyResult({
+            connectionId: "conn-google",
+            provider: "google",
+            status: "unreachable",
+            details: "CES backend unavailable",
+          }),
+          makeUnhealthyResult({
+            connectionId: "conn-slack",
+            provider: "slack",
+            status: "revoked",
+            details: "Token was revoked by user",
+          }),
+          makeUnhealthyResult({
+            connectionId: "conn-github",
+            provider: "github",
+            status: "unreachable",
+            details: "CES backend unavailable",
+          }),
+        ],
+      };
+
+      const service = createService();
+      await service.runOnce();
+
+      // Only the revoked credential should trigger a notification
+      expect(emittedNotificationSignals).toHaveLength(1);
+      expect(emittedNotificationSignals[0].contextPayload.provider).toBe(
+        "slack",
+      );
+      expect(emittedNotificationSignals[0].contextPayload.status).toBe(
+        "revoked",
+      );
+
+      // Only slack (revoked = hard failure) should appear in credential-status
+      expect(processMessageCalls).toHaveLength(1);
+      expect(processMessageCalls[0].content).toContain("<credential-status>");
+      expect(processMessageCalls[0].content).toContain("slack");
+      // google and github are unreachable — should NOT be in credential-status
+      expect(processMessageCalls[0].content).not.toContain("google");
+      expect(processMessageCalls[0].content).not.toContain("github");
+
+      // Should have logged a warning about the 2 unreachable credentials
+      const unreachableWarns = loggerWarnCalls.filter(
+        (call) => "unreachableCount" in call,
+      );
+      expect(unreachableWarns).toHaveLength(1);
+      expect(unreachableWarns[0].unreachableCount).toBe(2);
+    });
+  });
+
+  describe("cron scheduling mode", () => {
+    test("start() with cronExpression sets nextRunAt to cron occurrence, not now+intervalMs", () => {
+      const cronNextRunAt = Date.now() + 7_200_000; // 2 hours from now
+      mockComputeNextRunAtResult = cronNextRunAt;
+      mockConfig.heartbeat.cronExpression = "0 9,12,15,18 * * *";
+      mockConfig.heartbeat.timezone = "America/New_York";
+
+      const service = createService();
+      service.start();
+
+      expect(service.nextRunAt).toBe(cronNextRunAt);
+      // Should NOT be now + intervalMs
+      expect(service.nextRunAt).not.toBeCloseTo(
+        Date.now() + mockConfig.heartbeat.intervalMs,
+        -3,
+      );
+      service.stop();
+    });
+
+    test("runOnce() does not call scheduleNextRun(intervalMs) in cron mode — nextRunAt is not clobbered", async () => {
+      const cronNextRunAt = Date.now() + 7_200_000;
+      mockComputeNextRunAtResult = cronNextRunAt;
+      mockConfig.heartbeat.cronExpression = "0 9,12,15,18 * * *";
+
+      const service = createService();
+      service.start();
+
+      // nextRunAt should be the cron time before runOnce
+      expect(service.nextRunAt).toBe(cronNextRunAt);
+
+      await service.runOnce();
+
+      // After runOnce(), nextRunAt should still reflect a cron time, not now + intervalMs.
+      // The finally chain in scheduleNextCronRun recalculates it, but the runOnce()
+      // finally block should NOT have called scheduleNextRun(intervalMs).
+      // Since our mock always returns cronNextRunAt, nextRunAt should remain that value.
+      expect(service.nextRunAt).toBe(cronNextRunAt);
+      service.stop();
+    });
+
+    test("after runOnce() rejects in cron mode, the next cron run is still scheduled via finally", async () => {
+      const cronNextRunAt = Date.now() + 7_200_000;
+      mockComputeNextRunAtResult = cronNextRunAt;
+      mockConfig.heartbeat.cronExpression = "0 9,12,15,18 * * *";
+
+      const service = createService({
+        processMessage: async () => {
+          throw new Error("LLM down");
+        },
+      });
+      service.start();
+
+      await service.runOnce();
+
+      // Even though executeRun failed, the service should still have a nextRunAt
+      // set to the cron occurrence (the finally chain reschedules)
+      expect(service.nextRunAt).toBe(cronNextRunAt);
+      service.stop();
+    });
+
+    test("resetTimer() in cron mode recomputes from the current time", () => {
+      const firstCronTime = Date.now() + 3_600_000;
+      mockComputeNextRunAtResult = firstCronTime;
+      mockConfig.heartbeat.cronExpression = "0 9,12,15,18 * * *";
+
+      const service = createService();
+      service.start();
+      expect(service.nextRunAt).toBe(firstCronTime);
+
+      // Simulate time passing and a new cron occurrence
+      const secondCronTime = Date.now() + 5_400_000;
+      mockComputeNextRunAtResult = secondCronTime;
+
+      service.resetTimer();
+      expect(service.nextRunAt).toBe(secondCronTime);
+      service.stop();
+    });
+
+    test("reconfigure() switches from interval to cron mode", () => {
+      const service = createService();
+      // Start in interval mode
+      service.start();
+      const intervalNextRunAt = service.nextRunAt;
+      expect(intervalNextRunAt).not.toBeNull();
+
+      // Reconfigure to cron mode
+      const cronNextRunAt = Date.now() + 7_200_000;
+      mockComputeNextRunAtResult = cronNextRunAt;
+      mockConfig.heartbeat.cronExpression = "0 9,12,15,18 * * *";
+      service.reconfigure();
+
+      expect(service.nextRunAt).toBe(cronNextRunAt);
+      service.stop();
+    });
+
+    test("reconfigure() switches from cron to interval mode", () => {
+      const cronNextRunAt = Date.now() + 7_200_000;
+      mockComputeNextRunAtResult = cronNextRunAt;
+      mockConfig.heartbeat.cronExpression = "0 9,12,15,18 * * *";
+
+      const service = createService();
+      service.start();
+      expect(service.nextRunAt).toBe(cronNextRunAt);
+
+      // Reconfigure to interval mode
+      mockConfig.heartbeat.cronExpression = null;
+      const before = Date.now();
+      service.reconfigure();
+
+      expect(service.nextRunAt).not.toBeNull();
+      expect(service.nextRunAt!).toBeGreaterThanOrEqual(
+        before + mockConfig.heartbeat.intervalMs,
+      );
+      service.stop();
+    });
+
+    test("active hours guard uses cron timezone when configured", async () => {
+      mockConfig.heartbeat.cronExpression = "0 9,12,15,18 * * *";
+      mockConfig.heartbeat.timezone = "UTC";
+      mockConfig.heartbeat.activeHoursStart = 9;
+      mockConfig.heartbeat.activeHoursEnd = 17;
+      mockComputeNextRunAtResult = Date.now() + 3_600_000;
+
+      const service = createService();
+      service.start();
+
+      // In cron mode with timezone, the hour is computed via Intl.DateTimeFormat
+      // rather than getCurrentHour(). The test verifies the code path runs without
+      // error — the actual hour depends on the system clock and UTC conversion.
+      // We just verify it doesn't throw and returns a boolean result.
+      const result = await service.runOnce();
+      // Result depends on current UTC hour vs active window — either outcome is valid
+      expect(typeof result).toBe("boolean");
+      service.stop();
+    });
+
+    test("active hours guard falls back to getCurrentHour when cron mode has no timezone", async () => {
+      mockConfig.heartbeat.cronExpression = "0 9,12,15,18 * * *";
+      mockConfig.heartbeat.timezone = null;
+      mockConfig.heartbeat.activeHoursStart = 9;
+      mockConfig.heartbeat.activeHoursEnd = 17;
+      mockComputeNextRunAtResult = Date.now() + 3_600_000;
+
+      // getCurrentHour returns 3 (outside 9-17 window), so runOnce should skip
+      const service = createService({ getCurrentHour: () => 3 });
+      service.start();
+      const result = await service.runOnce();
+      expect(result).toBe(false);
+      expect(processMessageCalls).toHaveLength(0);
+      service.stop();
+    });
+
+    test("runtime fallback: computeNextRunAt throws, service falls back to interval mode", () => {
+      mockComputeNextRunAtError = new Error("No upcoming runs");
+      mockConfig.heartbeat.cronExpression = "0 9,12,15,18 * * *";
+
+      const service = createService();
+      service.start();
+
+      // Should have fallen back to interval mode — nextRunAt should be ~now + intervalMs
+      expect(service.nextRunAt).not.toBeNull();
+      const expectedMin = Date.now() + mockConfig.heartbeat.intervalMs - 100;
+      expect(service.nextRunAt!).toBeGreaterThanOrEqual(expectedMin);
+
+      // Should have logged a warning about the fallback
+      const fallbackWarns = loggerWarnCalls.filter((call) => "err" in call);
+      expect(fallbackWarns.length).toBeGreaterThanOrEqual(1);
+      service.stop();
+    });
+
+    test("null cronExpression behaves identically to current fixed-interval mode", () => {
+      mockConfig.heartbeat.cronExpression = null;
+
+      const service = createService();
+      const before = Date.now();
+      service.start();
+
+      expect(service.nextRunAt).not.toBeNull();
+      expect(service.nextRunAt!).toBeGreaterThanOrEqual(
+        before + mockConfig.heartbeat.intervalMs,
+      );
+      // computeNextRunAt should not have been called
+      expect(computeNextRunAtCallCount).toBe(0);
+      service.stop();
+    });
+  });
+
+  describe("heartbeat run store instrumentation", () => {
+    test("successful run: pending → running → ok with conversationId", async () => {
+      const service = createService();
+      await service.runOnce();
+
+      expect(mockStartHeartbeatRun).toHaveBeenCalledTimes(1);
+      expect(mockCompleteHeartbeatRun).toHaveBeenCalledTimes(1);
+      expect(mockCompleteHeartbeatRun).toHaveBeenCalledWith("mock-run-id", {
+        status: "ok",
+        conversationId: "conv-1",
+      });
+    });
+
+    test("failed run: pending → running → error preserving conversationId", async () => {
+      const service = createService({
+        processMessage: async () => {
+          throw new Error("LLM timeout");
+        },
+      });
+
+      await service.runOnce();
+
+      expect(mockStartHeartbeatRun).toHaveBeenCalledTimes(1);
+      expect(mockCompleteHeartbeatRun).toHaveBeenCalledTimes(1);
+      expect(mockCompleteHeartbeatRun).toHaveBeenCalledWith("mock-run-id", {
+        status: "error",
+        conversationId: "conv-1",
+        error: "LLM timeout",
+      });
+    });
+
+    test("CAS false suppresses success feed event", async () => {
+      mockCompleteHeartbeatRun.mockImplementation(() => false);
+
+      const service = createService();
+      await service.runOnce();
+
+      // completeHeartbeatRun returned false, so no feed event should be emitted for success
+      const successCalls = mockEmitFeedEvent.mock.calls.filter(
+        (call: unknown[]) => {
+          const opts = call[0] as { dedupKey?: string };
+          return opts.dedupKey?.startsWith("heartbeat:ok:");
+        },
+      );
+      expect(successCalls).toHaveLength(0);
+    });
+
+    test("CAS false suppresses failure alerter and feed event", async () => {
+      mockCompleteHeartbeatRun.mockImplementation(() => false);
+
+      const service = createService({
+        processMessage: async () => {
+          throw new Error("LLM timeout");
+        },
+      });
+
+      await service.runOnce();
+
+      // completeHeartbeatRun returned false, so alerter should NOT be called
+      expect(alerterCalls).toHaveLength(0);
+
+      // No failure feed event either
+      const failCalls = mockEmitFeedEvent.mock.calls.filter(
+        (call: unknown[]) => {
+          const opts = call[0] as { dedupKey?: string };
+          return opts.dedupKey?.startsWith("heartbeat:fail:");
+        },
+      );
+      expect(failCalls).toHaveLength(0);
+    });
+
+    test("active-hours skip calls skipHeartbeatRun", async () => {
+      mockConfig.heartbeat.activeHoursStart = 9;
+      mockConfig.heartbeat.activeHoursEnd = 17;
+
+      const service = createService({ getCurrentHour: () => 3 });
+      service.start();
+      await service.runOnce();
+
+      expect(mockSkipHeartbeatRun).toHaveBeenCalledWith(
+        "mock-run-id",
+        "outside_active_hours",
+      );
+      service.stop();
+    });
+
+    test("overlap skip calls skipHeartbeatRun", async () => {
+      let resolveFirst: () => void;
+      const firstPromise = new Promise<void>((r) => {
+        resolveFirst = r;
+      });
+
+      const service = createService({
+        processMessage: async () => {
+          await firstPromise;
+          return { messageId: "msg-1" };
+        },
+      });
+
+      // Start first run (will block)
+      const run1 = service.runOnce();
+      await new Promise((r) => setTimeout(r, 10));
+
+      // Start service so the second runOnce has a pending row
+      service.start();
+      mockSkipHeartbeatRun.mockClear();
+
+      // Second run should be skipped due to overlap
+      await service.runOnce();
+
+      expect(mockSkipHeartbeatRun).toHaveBeenCalledWith(
+        "mock-run-id",
+        "overlap",
+      );
+
+      resolveFirst!();
+      await run1;
+      service.stop();
+    });
+
+    test("start() calls markStaleRunsAsMissed and markStaleRunningAsError", () => {
+      const service = createService();
+      service.start();
+
+      expect(mockMarkStaleRunsAsMissed).toHaveBeenCalledTimes(1);
+      expect(mockMarkStaleRunningAsError).toHaveBeenCalledTimes(1);
+      service.stop();
+    });
+
+    test("scheduleNextRun supersedes old pending row before creating new one", () => {
+      const service = createService();
+      service.start();
+
+      // start() called scheduleNextRun which set _pendingRunId.
+      // Calling resetTimer triggers another scheduleNextRun which
+      // should supersede the existing pending row before inserting
+      // a new one.
+      const callOrder: string[] = [];
+      mockSupersedePendingRun.mockImplementation(() => {
+        callOrder.push("supersede");
+        return true;
+      });
+      mockInsertPendingHeartbeatRun.mockImplementation(() => {
+        callOrder.push("insert");
+        return "mock-run-id";
+      });
+
+      service.resetTimer();
+
+      // resetTimer's scheduleNextRun should supersede then insert
+      expect(callOrder.filter((c) => c === "supersede").length).toBeGreaterThan(
+        0,
+      );
+      const firstSupersede = callOrder.indexOf("supersede");
+      const firstInsert = callOrder.indexOf("insert");
+      expect(firstSupersede).toBeLessThan(firstInsert);
+
+      service.stop();
+    });
+
+    test("resetTimer() supersedes pending row", () => {
+      const service = createService();
+      service.start();
+
+      mockSupersedePendingRun.mockClear();
+      service.resetTimer();
+
+      // resetTimer calls scheduleNextRun which supersedes existing pending
+      expect(mockSupersedePendingRun).toHaveBeenCalled();
+      service.stop();
+    });
+
+    test("force run creates its own pending row, does not consume scheduled one", async () => {
+      const service = createService();
+      service.start();
+
+      // Clear to track only the force run's calls
+      mockInsertPendingHeartbeatRun.mockClear();
+
+      await service.runOnce({ force: true });
+
+      // Force run should have called insertPendingHeartbeatRun for itself
+      // (at least once for its own row, plus the scheduleNextRun in finally)
+      expect(mockInsertPendingHeartbeatRun).toHaveBeenCalled();
+
+      // The scheduled pending row (from start()) should NOT have been consumed
+      // by the force run — force creates its own
+      service.stop();
+    });
+
+    test("disabled config with stale pending row skips it as disabled", async () => {
+      const service = createService();
+      service.start();
+
+      // Now disable config and call runOnce — should skip the pending row
+      mockConfig.heartbeat.enabled = false;
+      mockSkipHeartbeatRun.mockClear();
+
+      await service.runOnce();
+
+      expect(mockSkipHeartbeatRun).toHaveBeenCalledWith(
+        "mock-run-id",
+        "disabled",
+      );
+      service.stop();
+    });
+
+    test("stop() supersedes outstanding pending row", async () => {
+      const service = createService();
+      service.start();
+
+      mockSupersedePendingRun.mockClear();
+      await service.stop();
+
+      expect(mockSupersedePendingRun).toHaveBeenCalledWith("mock-run-id");
+    });
+
+    test("timeout calls completeHeartbeatRun with status timeout", async () => {
+      jest.useFakeTimers();
+      try {
+        let resolveRun: () => void;
+        const runPromise = new Promise<void>((r) => {
+          resolveRun = r;
+        });
+
+        const service = createService({
+          processMessage: async () => {
+            await runPromise;
+            return { messageId: "msg-1" };
+          },
+        });
+
+        const runOncePromise = service.runOnce();
+        // Advance past the 30-minute timeout
+        jest.advanceTimersByTime(30 * 60 * 1000 + 1000);
+        await runOncePromise;
+
+        expect(mockCompleteHeartbeatRun).toHaveBeenCalledWith("mock-run-id", {
+          status: "timeout",
+          error: "Heartbeat execution exceeded the 30-minute timeout",
+        });
+
+        // Clean up — resolve the hanging promise so it doesn't leak
+        resolveRun!();
+      } finally {
+        jest.useRealTimers();
+      }
+    });
+
+    test("failure feed event has urgency high and includes error message", async () => {
+      const service = createService({
+        processMessage: async () => {
+          throw new Error("web_search outage");
+        },
+      });
+
+      await service.runOnce();
+
+      const failCalls = mockEmitFeedEvent.mock.calls.filter(
+        (call: unknown[]) => {
+          const opts = call[0] as { title?: string };
+          return opts.title === "Heartbeat Failed";
+        },
+      );
+      expect(failCalls).toHaveLength(1);
+      const opts = (failCalls as any[][])[0][0] as {
+        urgency?: string;
+        summary?: string;
+      };
+      expect(opts.urgency).toBe("high");
+      expect(opts.summary).toContain("web_search outage");
+    });
+
+    test("CAS false on complete suppresses failure feed event", async () => {
+      mockCompleteHeartbeatRun.mockImplementation(() => false);
+
+      const service = createService({
+        processMessage: async () => {
+          throw new Error("some error");
+        },
+      });
+
+      await service.runOnce();
+
+      const failCalls = mockEmitFeedEvent.mock.calls.filter(
+        (call: unknown[]) => {
+          const opts = call[0] as { title?: string };
+          return opts.title === "Heartbeat Failed";
+        },
+      );
+      expect(failCalls).toHaveLength(0);
+    });
+
+    test("timeout emits feed event with urgency high", async () => {
+      jest.useFakeTimers();
+      try {
+        let resolveRun: () => void;
+        const runPromise = new Promise<void>((r) => {
+          resolveRun = r;
+        });
+
+        const service = createService({
+          processMessage: async () => {
+            await runPromise;
+            return { messageId: "msg-1" };
+          },
+        });
+
+        const runOncePromise = service.runOnce();
+        jest.advanceTimersByTime(30 * 60 * 1000 + 1000);
+        await runOncePromise;
+
+        const timeoutCalls = mockEmitFeedEvent.mock.calls.filter(
+          (call: unknown[]) => {
+            const opts = call[0] as { title?: string };
+            return opts.title === "Heartbeat Timed Out";
+          },
+        );
+        expect(timeoutCalls).toHaveLength(1);
+        const opts = (timeoutCalls as any[][])[0][0] as {
+          urgency?: string;
+        };
+        expect(opts.urgency).toBe("high");
+
+        resolveRun!();
+      } finally {
+        jest.useRealTimers();
+      }
+    });
+
+    test("CAS false on timeout suppresses timeout feed event", async () => {
+      jest.useFakeTimers();
+      try {
+        mockCompleteHeartbeatRun.mockImplementation(() => false);
+
+        let resolveRun: () => void;
+        const runPromise = new Promise<void>((r) => {
+          resolveRun = r;
+        });
+
+        const service = createService({
+          processMessage: async () => {
+            await runPromise;
+            return { messageId: "msg-1" };
+          },
+        });
+
+        const runOncePromise = service.runOnce();
+        jest.advanceTimersByTime(30 * 60 * 1000 + 1000);
+        await runOncePromise;
+
+        // completeHeartbeatRun returned false, so no timeout feed event
+        const timeoutCalls = mockEmitFeedEvent.mock.calls.filter(
+          (call: unknown[]) => {
+            const opts = call[0] as { title?: string };
+            return opts.title === "Heartbeat Timed Out";
+          },
+        );
+        expect(timeoutCalls).toHaveLength(0);
+
+        resolveRun!();
+      } finally {
+        jest.useRealTimers();
+      }
+    });
+
+    test("late run emits late feed event", async () => {
+      const service = createService();
+      service.start();
+
+      // Set the pending run to be 10 minutes in the past
+      (service as any)._nextRunAt = Date.now() - 10 * 60 * 1000;
+      (service as any)._pendingRunId = "late-run-id";
+
+      await service.runOnce();
+
+      const lateCalls = mockEmitFeedEvent.mock.calls.filter(
+        (call: unknown[]) => {
+          const opts = call[0] as { title?: string };
+          return opts.title === "Heartbeat Ran Late";
+        },
+      );
+      expect(lateCalls).toHaveLength(1);
+      const opts = (lateCalls as any[][])[0][0] as {
+        urgency?: string;
+        summary?: string;
+      };
+      expect(opts.urgency).toBe("medium");
+      expect(opts.summary).toContain("10 minutes late");
+
+      await service.stop();
+    });
+
+    test("on-time run does not emit late feed event", async () => {
+      const service = createService();
+      await service.runOnce();
+
+      const lateCalls = mockEmitFeedEvent.mock.calls.filter(
+        (call: unknown[]) => {
+          const opts = call[0] as { title?: string };
+          return opts.title === "Heartbeat Ran Late";
+        },
+      );
+      expect(lateCalls).toHaveLength(0);
+    });
+
+    test("start() emits missed-run feed event when stale rows exist", () => {
+      mockMarkStaleRunsAsMissed.mockImplementation(() => 2);
+      mockMarkStaleRunningAsError.mockImplementation(() => 1);
+
+      const service = createService();
+      service.start();
+
+      const missedCalls = mockEmitFeedEvent.mock.calls.filter(
+        (call: unknown[]) => {
+          const opts = call[0] as { title?: string };
+          return opts.title === "Heartbeat Runs Missed";
+        },
+      );
+      expect(missedCalls).toHaveLength(1);
+      const opts = (missedCalls as any[][])[0][0] as {
+        urgency?: string;
+        summary?: string;
+      };
+      expect(opts.urgency).toBe("high");
+      expect(opts.summary).toContain("3");
+
+      service.stop();
+    });
+
+    test("start() does not emit missed-run feed event when counts are 0", () => {
+      mockMarkStaleRunsAsMissed.mockImplementation(() => 0);
+      mockMarkStaleRunningAsError.mockImplementation(() => 0);
+
+      const service = createService();
+      service.start();
+
+      const missedCalls = mockEmitFeedEvent.mock.calls.filter(
+        (call: unknown[]) => {
+          const opts = call[0] as { title?: string };
+          return opts.title === "Heartbeat Runs Missed";
+        },
+      );
+      expect(missedCalls).toHaveLength(0);
+      service.stop();
+    });
+  });
 });