@vellumai/assistant 0.7.1 → 0.7.3

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

@@ -1,14 +1,52 @@
 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);
+const mockListHeartbeatRuns = mock(() => []);
+const mockCountCompletedHeartbeatRuns = mock(() => 10);
+mock.module("../heartbeat/heartbeat-run-store.js", () => ({
+  insertPendingHeartbeatRun: mockInsertPendingHeartbeatRun,
+  startHeartbeatRun: mockStartHeartbeatRun,
+  completeHeartbeatRun: mockCompleteHeartbeatRun,
+  skipHeartbeatRun: mockSkipHeartbeatRun,
+  supersedePendingRun: mockSupersedePendingRun,
+  markStaleRunsAsMissed: mockMarkStaleRunsAsMissed,
+  markStaleRunningAsError: mockMarkStaleRunningAsError,
+  listHeartbeatRuns: mockListHeartbeatRuns,
+  countCompletedHeartbeatRuns: mockCountCompletedHeartbeatRuns,
+}));
+
+// ── 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 +60,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
@@ -59,6 +123,14 @@ mock.module("../prompts/persona-resolver.js", () => ({
 const createdConversations: Array<{ title: string; conversationType: string }> =
   [];
 let conversationIdCounter = 0;
+const mockStoredMessages: Array<{
+  id: string;
+  conversationId: string;
+  role: string;
+  content: string;
+  createdAt: number;
+  metadata: string | null;
+}> = [];
 
 mock.module("../memory/conversation-crud.js", () => ({
   setConversationOriginChannelIfUnset: () => {},
@@ -67,7 +139,7 @@ mock.module("../memory/conversation-crud.js", () => ({
   updateConversationTitle: () => {},
   updateConversationUsage: () => {},
   addMessage: () => ({ id: "mock-msg-id" }),
-  getMessages: () => [],
+  getMessages: () => mockStoredMessages,
   getConversation: () => ({
     id: "conv-1",
     contextSummary: null,
@@ -139,21 +211,36 @@ mock.module("../credential-health/credential-health-service.js", () => ({
 // `notifyUnhealthyCredentials` dynamically imports `emitNotificationSignal`.
 // Track calls so tests can assert which credentials were notified about.
 const emittedNotificationSignals: Array<{
+  sourceEventName?: string;
+  sourceChannel?: string;
   sourceContextId: string;
   dedupeKey: string;
+  attentionHints?: Record<string, unknown>;
   contextPayload: Record<string, unknown>;
+  conversationAffinityHint?: Record<string, string>;
+  conversationMetadata?: Record<string, unknown>;
 }> = [];
 
 mock.module("../notifications/emit-signal.js", () => ({
   emitNotificationSignal: async (opts: {
+    sourceEventName?: string;
+    sourceChannel?: string;
     sourceContextId: string;
     dedupeKey: string;
+    attentionHints?: Record<string, unknown>;
     contextPayload: Record<string, unknown>;
+    conversationAffinityHint?: Record<string, string>;
+    conversationMetadata?: Record<string, unknown>;
   }) => {
     emittedNotificationSignals.push({
+      sourceEventName: opts.sourceEventName,
+      sourceChannel: opts.sourceChannel,
       sourceContextId: opts.sourceContextId,
       dedupeKey: opts.dedupeKey,
+      attentionHints: opts.attentionHints,
       contextPayload: opts.contextPayload,
+      conversationAffinityHint: opts.conversationAffinityHint,
+      conversationMetadata: opts.conversationMetadata,
     });
   },
 }));
@@ -258,11 +345,15 @@ describe("HeartbeatService", () => {
     alerterCalls = [];
     createdConversations.length = 0;
     conversationIdCounter = 0;
+    mockStoredMessages.length = 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[]) => {
@@ -274,10 +365,33 @@ 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);
+    mockListHeartbeatRuns.mockClear();
+    mockListHeartbeatRuns.mockImplementation(() => []);
+    mockCountCompletedHeartbeatRuns.mockClear();
+    mockCountCompletedHeartbeatRuns.mockImplementation(() => 10);
+    mockEmitFeedEvent.mockClear();
+    mockEmitFeedEvent.mockImplementation(() => Promise.resolve());
+
     mockConfig = {
       heartbeat: {
         enabled: true,
         intervalMs: 60_000,
+        cronExpression: null,
+        timezone: null,
         activeHoursStart: undefined,
         activeHoursEnd: undefined,
       },
@@ -287,6 +401,10 @@ describe("HeartbeatService", () => {
   function createService(overrides?: {
     processMessage?: (...args: unknown[]) => Promise<{ messageId: string }>;
     getCurrentHour?: () => number;
+    onConversationCreated?: (info: {
+      conversationId: string;
+      title: string;
+    }) => void;
   }) {
     if (overrides?.processMessage) {
       setTestProcessMessage(overrides.processMessage);
@@ -295,6 +413,7 @@ describe("HeartbeatService", () => {
       alerter: (alert: { type: string; title: string; body: string }) => {
         alerterCalls.push(alert);
       },
+      onConversationCreated: overrides?.onConversationCreated,
       getCurrentHour: overrides?.getCurrentHour,
     });
   }
@@ -639,6 +758,149 @@ describe("HeartbeatService", () => {
     });
   });
 
+  test("HEARTBEAT_ALERT emits a notification signal and surfaces the conversation", async () => {
+    const conversationCreatedCalls: Array<{
+      conversationId: string;
+      title: string;
+    }> = [];
+    const service = createService({
+      onConversationCreated: (info) => conversationCreatedCalls.push(info),
+      processMessage: async (...args: unknown[]) => {
+        const conversationId = args[0] as string;
+        mockStoredMessages.push({
+          id: "assistant-alert-1",
+          conversationId,
+          role: "assistant",
+          content: JSON.stringify([
+            {
+              type: "text",
+              text: "The first heartbeat found a concrete follow-up for the guardian.\nHEARTBEAT_ALERT",
+            },
+          ]),
+          createdAt: Date.now(),
+          metadata: null,
+        });
+        return { messageId: "user-heartbeat-1" };
+      },
+    });
+
+    await service.runOnce();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(conversationCreatedCalls).toEqual([
+      { conversationId: "conv-1", title: "Heartbeat" },
+    ]);
+    expect(emittedNotificationSignals).toHaveLength(1);
+    expect(emittedNotificationSignals[0]).toMatchObject({
+      sourceEventName: "heartbeat.alert",
+      sourceChannel: "watcher",
+      sourceContextId: "mock-run-id",
+      dedupeKey: "heartbeat:alert:mock-run-id",
+      attentionHints: {
+        requiresAction: true,
+        urgency: "medium",
+        isAsyncBackground: true,
+        visibleInSourceNow: false,
+      },
+      conversationAffinityHint: { vellum: "conv-1" },
+      conversationMetadata: {
+        source: "heartbeat",
+        groupId: "system:background",
+      },
+    });
+    expect(emittedNotificationSignals[0].contextPayload.summary).toBe(
+      "The first heartbeat found a concrete follow-up for the guardian.",
+    );
+    expect(emittedNotificationSignals[0].contextPayload.messageId).toBe(
+      "assistant-alert-1",
+    );
+    expect(
+      emittedNotificationSignals[0].contextPayload.sourceInterface,
+    ).toBeUndefined();
+  });
+
+  test("HEARTBEAT_OK stays silent", async () => {
+    const conversationCreatedCalls: Array<{
+      conversationId: string;
+      title: string;
+    }> = [];
+    const service = createService({
+      onConversationCreated: (info) => conversationCreatedCalls.push(info),
+      processMessage: async (...args: unknown[]) => {
+        const conversationId = args[0] as string;
+        mockStoredMessages.push({
+          id: "assistant-ok-1",
+          conversationId,
+          role: "assistant",
+          content: JSON.stringify([
+            {
+              type: "text",
+              text: "Everything looks good.\nHEARTBEAT_OK",
+            },
+          ]),
+          createdAt: Date.now(),
+          metadata: null,
+        });
+        return { messageId: "user-heartbeat-1" };
+      },
+    });
+
+    await service.runOnce();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(conversationCreatedCalls).toHaveLength(0);
+    expect(emittedNotificationSignals).toHaveLength(0);
+    const successFeedCalls = mockEmitFeedEvent.mock.calls.filter(
+      (call: unknown[]) => {
+        const opts = call[0] as { dedupKey?: string };
+        return opts.dedupKey?.startsWith("heartbeat:ok:");
+      },
+    );
+    expect(successFeedCalls).toHaveLength(0);
+  });
+
+  test("HEARTBEAT_OK stays silent when earlier content mentions HEARTBEAT_ALERT", async () => {
+    const conversationCreatedCalls: Array<{
+      conversationId: string;
+      title: string;
+    }> = [];
+    const service = createService({
+      onConversationCreated: (info) => conversationCreatedCalls.push(info),
+      processMessage: async (...args: unknown[]) => {
+        const conversationId = args[0] as string;
+        mockStoredMessages.push({
+          id: "assistant-ok-2",
+          conversationId,
+          role: "assistant",
+          content: JSON.stringify([
+            {
+              type: "thinking",
+              thinking:
+                "I should decide between HEARTBEAT_ALERT and HEARTBEAT_OK.",
+            },
+            {
+              type: "tool_result",
+              content: "Tool output mentions HEARTBEAT_ALERT.",
+            },
+            {
+              type: "text",
+              text: "I considered HEARTBEAT_ALERT, but there is nothing useful to surface.\nHEARTBEAT_OK",
+            },
+          ]),
+          createdAt: Date.now(),
+          metadata: null,
+        });
+        return { messageId: "user-heartbeat-1" };
+      },
+    });
+
+    await service.runOnce();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(conversationCreatedCalls).toHaveLength(0);
+    expect(emittedNotificationSignals).toHaveLength(0);
+  });
+
   test("end-to-end: llm.callSites.heartbeatAgent.speed resolves to 'fast'", async () => {
     // Verifies the contract that PR 7 establishes: heartbeat passes
     // `callSite: 'heartbeatAgent'`, and the LLM resolver maps that to the
@@ -1053,4 +1315,708 @@ describe("HeartbeatService", () => {
       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 surfacing", async () => {
+      mockCompleteHeartbeatRun.mockImplementation(() => false);
+
+      const conversationCreatedCalls: Array<{
+        conversationId: string;
+        title: string;
+      }> = [];
+      const service = createService({
+        onConversationCreated: (info) => conversationCreatedCalls.push(info),
+        processMessage: async (...args: unknown[]) => {
+          const conversationId = args[0] as string;
+          mockStoredMessages.push({
+            id: "assistant-alert-1",
+            conversationId,
+            role: "assistant",
+            content: JSON.stringify([
+              {
+                type: "text",
+                text: "Something worth surfacing.\nHEARTBEAT_ALERT",
+              },
+            ]),
+            createdAt: Date.now(),
+            metadata: null,
+          });
+          return { messageId: "msg-1" };
+        },
+      });
+      await service.runOnce();
+      await new Promise((resolve) => setTimeout(resolve, 0));
+
+      expect(conversationCreatedCalls).toHaveLength(0);
+      expect(emittedNotificationSignals).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();
+    });
+  });
+
+  describe("early heartbeat nudge", () => {
+    test("includes <early-heartbeat> when completedRunCount is 0", () => {
+      const service = createService();
+      const { prompt } = service.buildPrompt("- Check things", [], 0);
+
+      expect(prompt).toContain("<early-heartbeat>");
+      expect(prompt).toContain("first heartbeats");
+    });
+
+    test("includes <early-heartbeat> when completedRunCount is 2", () => {
+      const service = createService();
+      const { prompt } = service.buildPrompt("- Check things", [], 2);
+
+      expect(prompt).toContain("<early-heartbeat>");
+    });
+
+    test("omits <early-heartbeat> when completedRunCount is 3", () => {
+      const service = createService();
+      const { prompt } = service.buildPrompt("- Check things", [], 3);
+
+      expect(prompt).not.toContain("<early-heartbeat>");
+    });
+
+    test("omits <early-heartbeat> when completedRunCount is 10", () => {
+      const service = createService();
+      const { prompt } = service.buildPrompt("- Check things", [], 10);
+
+      expect(prompt).not.toContain("<early-heartbeat>");
+    });
+
+    test("executeRun passes completed run count to buildPrompt", async () => {
+      mockCountCompletedHeartbeatRuns.mockImplementation(() => 0);
+
+      const service = createService();
+      await service.runOnce();
+
+      expect(processMessageCalls).toHaveLength(1);
+      expect(processMessageCalls[0].content).toContain("<early-heartbeat>");
+    });
+
+    test("executeRun omits nudge when enough runs have completed", async () => {
+      mockCountCompletedHeartbeatRuns.mockImplementation(() => 5);
+
+      const service = createService();
+      await service.runOnce();
+
+      expect(processMessageCalls).toHaveLength(1);
+      expect(processMessageCalls[0].content).not.toContain("<early-heartbeat>");
+    });
+  });
 });